Skip to main content
Skip to main content
Edit this page

Composable Protocols

Overview​

Composable protocols allow more flexible configuration of TCP access to the ClickHouse server. This configuration can co-exist alongside, or replace, conventional configuration.

Configuring composable protocols​

Composable protocols can be configured in an XML configuration file. The protocols section is denoted with protocols tags in the XML config file:

Configuring protocol layers​

You can define protocol layers using basic modules. For example, to define an HTTP layer, you can add a new basic module to the protocols section:

Modules can be configured according to:

  • plain_http - name which can be referred to by another layer
  • type - denotes the protocol handler which will be instantiated to process data. It has the following set of predefined protocol handlers:
    • tcp - native clickhouse protocol handler
    • http - HTTP clickhouse protocol handler
    • tls - TLS encryption layer
    • proxy1 - PROXYv1 layer
    • mysql - MySQL compatibility protocol handler
    • postgres - PostgreSQL compatibility protocol handler
    • prometheus - Prometheus protocol handler
    • interserver - clickhouse interserver handler
note

gRPC protocol handler is not implemented for Composable protocols

Configuring endpoints​

Endpoints (listening ports) are denoted by <port> and optional <host> tags. For example, to configure an endpoint on the previously added HTTP layer we could modify our configuration as follows:

If the <host> tag is omitted, then the <listen_host> from the root config is used.

Configuring layer sequences​

Layers sequences are defined using the <impl> tag, and referencing another module. For example, to configure a TLS layer on top of our plain_http module we could further modify our configuration as follows:

Attaching endpoints to layers​

Endpoints can be attached to any layer. For example, we can define endpoints for HTTP (port 8123) and HTTPS (port 8443):

Defining additional endpoints​

Additional endpoints can be defined by referencing any module and omitting the <type> tag. For example, we can define another_http endpoint for the plain_http module as follows:

Specifying additional layer parameters​

Some modules can contain additional layer parameters. For example, the TLS layer allows a private key (privateKeyFile) and certificate files (certificateFile) to be specified as follows: