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>