Skip to main content

Composable Protocols

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

Composable protocols section is denoted as protocols in configuration xml

Example:

<protocols>

</protocols>

Basic modules define protocol layers

Example:

<protocols>

<!-- plain_http module -->
<plain_http>
<type>http</type>
</plain_http>

</protocols>

where:

  • plain_http - name which can be referred by another layer
  • type - denotes protocol handler which will be instantiated to process data, set of protocol handlers is predefined:
    • 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

Endpoint (i.e. listening port) is denoted by <port> and (optional) <host> tags

Example:

<protocols>

<plain_http>

<type>http</type>
<!-- endpoint -->
<host>127.0.0.1</host>
<port>8123</port>

</plain_http>

</protocols>

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

Layers sequence is defined by <impl> tag, referencing another module

Example: definition for HTTPS protocol

<protocols>

<!-- http module -->
<plain_http>
<type>http</type>
</plain_http>

<!-- https module configured as a tls layer on top of plain_http module -->
<https>
<type>tls</type>
<impl>plain_http</impl>
<host>127.0.0.1</host>
<port>8443</port>
</https>

</protocols>

Endpoint can be attached to any layer

Example: definition for HTTP (port 8123) and HTTPS (port 8443) endpoints

<protocols>

<plain_http>
<type>http</type>
<host>127.0.0.1</host>
<port>8123</port>
</plain_http>

<https>
<type>tls</type>
<impl>plain_http</impl>
<host>127.0.0.1</host>
<port>8443</port>
</https>

</protocols>

Additional endpoints can be defined by referencing any module and omitting <type> tag

Example: another_http endpoint is defined for plain_http module

<protocols>

<plain_http>
<type>http</type>
<host>127.0.0.1</host>
<port>8123</port>
</plain_http>

<https>
<type>tls</type>
<impl>plain_http</impl>
<host>127.0.0.1</host>
<port>8443</port>
</https>

<another_http>
<impl>plain_http</impl>
<host>127.0.0.1</host>
<port>8223</port>
</another_http>

</protocols>

Some modules can contain specific for its layer parameters

Example: for TLS layer private key (privateKeyFile) and certificate files (certificateFile) can be specified

<protocols>

<plain_http>
<type>http</type>
<host>127.0.0.1</host>
<port>8123</port>
</plain_http>

<https>
<type>tls</type>
<impl>plain_http</impl>
<host>127.0.0.1</host>
<port>8443</port>
<privateKeyFile>another_server.key</privateKeyFile>
<certificateFile>another_server.crt</certificateFile>
</https>

</protocols>