Pular para o conteúdo principal

​
Visão geral

Os protocolos componíveis permitem configurar com mais flexibilidade o acesso TCP ao servidor ClickHouse. Essa configuração pode coexistir com a configuração convencional ou substituí-la.

​
Configurando protocolos componíveis

Os protocolos componíveis podem ser configurados em um arquivo de configuração XML. A seção de protocolos é definida pelas tags protocols no arquivo de configuração XML: 
<protocols>

</protocols>

​
Configurando camadas de protocolo

Você pode definir camadas de protocolo usando módulos base. Por exemplo, para definir uma camada HTTP, adicione um novo módulo base à seção protocols: 
<protocols>

  <!-- módulo plain_http -->
  <plain_http>
    <type>http</type>
  </plain_http>

</protocols>
Os módulos podem ser configurados da seguinte forma:
  • plain_http - nome ao qual outra camada pode fazer referência
  • type - indica o handler de protocolo que será instanciado para processar dados. Ele tem o seguinte conjunto de handlers de protocolo predefinidos:
    • tcp - handler do protocolo nativo do ClickHouse
    • http - handler do protocolo HTTP do ClickHouse
    • tls - camada de criptografia TLS
    • proxy1 - camada PROXYv1
    • mysql - handler do protocolo de compatibilidade com MySQL
    • postgres - handler do protocolo de compatibilidade com PostgreSQL
    • prometheus - handler do protocolo Prometheus
    • interserver - handler de interservidor do ClickHouse
O handler de protocolo gRPC não está implementado para Composable protocols

​
Configurando endpoints

Os endpoints (portas de escuta) são representados pelas tags <port> e <host> opcionais. Por exemplo, para configurar um endpoint na camada HTTP adicionada anteriormente, poderíamos modificar nossa configuração da seguinte forma: 
<protocols>

  <plain_http>

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

  </plain_http>

</protocols>
Se a tag <host> for omitida, será usada a <listen_host> da configuração raiz.

​
Configurando sequências de camadas

As sequências de camadas são definidas com a tag <impl>, fazendo referência a outro módulo. Por exemplo, para configurar uma camada TLS sobre o nosso módulo plain_http, podemos ajustar ainda mais a configuração da seguinte forma: 
<protocols>

  <!-- módulo http -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- módulo https configurado como uma camada TLS sobre o módulo plain_http -->
  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

​
Associando endpoints às camadas

Endpoints podem ser associados a qualquer camada. Por exemplo, podemos definir endpoints para HTTP (porta 8123) e HTTPS (porta 8443): 
<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>

​
Definição de endpoints adicionais

É possível definir endpoints adicionais referenciando qualquer módulo e omitindo a tag <type>. Por exemplo, podemos definir o endpoint another_http para o módulo plain_http da seguinte forma: 
<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>

​
Handlers HTTP personalizados por endpoint

Por padrão, todas as entradas do protocolo type=http compartilham a mesma configuração <http_handlers>. Você pode sobrescrever isso adicionando uma tag <handlers> que aponta para outra seção de configuração. Isso permite que cada porta HTTP use um conjunto diferente de regras de roteamento HTTP. Por exemplo, para executar uma API HTTP alternativa na porta 8124 com seus próprios handlers: 
<protocols>

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

  <alt_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8124</port>
    <handlers>http_handlers_alt</handlers>
  </alt_http>

</protocols>

<!-- Handlers padrão usados por plain_http (porta 8123) -->
<http_handlers>
    <defaults/>
</http_handlers>

<!-- Handlers alternativos usados por alt_http (porta 8124) -->
<http_handlers_alt>
    <rule>
        <url>/custom</url>
        <handler>
            <type>predefined_query_handler</type>
            <query>SELECT 'custom_endpoint'</query>
        </handler>
    </rule>
    <defaults/>
</http_handlers_alt>
Neste exemplo, as requisições para a porta 8123 usam as regras padrão de <http_handlers>, enquanto as requisições para a porta 8124 usam as regras de <http_handlers_alt>. Se <handlers> for omitido, o endpoint volta para o <http_handlers> padrão. A seção de handlers personalizados segue o mesmo formato de <http_handlers>. As alterações na seção de handlers personalizados são detectadas durante a recarga da configuração, e o endpoint correspondente é reiniciado automaticamente.

​
Especificando parâmetros adicionais da camada

Alguns módulos podem conter parâmetros adicionais de camada. Por exemplo, a camada TLS permite especificar uma chave privada (privateKeyFile) e arquivos de certificado (certificateFile) da seguinte forma: 
<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>
Última modificação em 10 de junho de 2026