> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Protocolos componíveis permitem configurar de forma mais flexível o acesso TCP ao servidor ClickHouse.

# Protocolos componíveis

<div id="overview">
  ## Visão geral
</div>

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.

<div id="composable-protocols-section-is-denoted-as-protocols-in-configuration-xml">
  ## Configurando protocolos componíveis
</div>

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:

```xml theme={null}
<protocols>

</protocols>
```

<div id="basic-modules-define-protocol-layers">
  ### Configurando camadas de protocolo
</div>

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`:

```xml theme={null}
<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

<Note>
  O handler de protocolo `gRPC` não está implementado para `Composable protocols`
</Note>

<div id="endpoint-ie-listening-port-is-denoted-by-port-and-optional-host-tags">
  ### Configurando endpoints
</div>

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:

```xml theme={null}
<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.

<div id="layers-sequence-is-defined-by-impl-tag-referencing-another-module">
  ### Configurando sequências de camadas
</div>

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:

```xml theme={null}
<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>
```

<div id="endpoint-can-be-attached-to-any-layer">
  ### Associando endpoints às camadas
</div>

Endpoints podem ser associados a qualquer camada. Por exemplo, podemos definir endpoints para
HTTP (porta 8123) e HTTPS (porta 8443):

```xml theme={null}
<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>
```

<div id="additional-endpoints-can-be-defined-by-referencing-any-module-and-omitting-type-tag">
  ### Definição de endpoints adicionais
</div>

É 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:

```xml theme={null}
<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>
```

<div id="custom-http-handlers-per-endpoint">
  ### Handlers HTTP personalizados por endpoint
</div>

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:

```xml theme={null}
<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>

<!-- Default handlers used by plain_http (port 8123) -->
<http_handlers>
    <defaults/>
</http_handlers>

<!-- Alternative handlers used by alt_http (port 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>`](/pt-BR/reference/settings/server-settings/settings/http#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.

<div id="default-session-user-per-endpoint">
  ### Usuário de sessão padrão por endpoint
</div>

Quando um cliente se conecta sem especificar um nome de usuário (por exemplo, uma requisição HTTP
sem o parâmetro `user` ou um pacote `Hello` do protocolo nativo com um nome de usuário
vazio), o servidor o autentica como o usuário de sessão padrão —
a [configuração do servidor](/pt-BR/reference/settings/server-settings/settings) `default_session_user`, cujo valor padrão é `default`.

A tag `<default_session_user>` substitui essa configuração para um único endpoint. Isso
permite que diferentes portas de escuta atendam a diferentes usuários anônimos:

```xml theme={null}
<protocols>

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

  <readonly_http>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8124</port>
    <default_session_user>readonly_user</default_session_user>
  </readonly_http>

</protocols>
```

Neste exemplo, as solicitações sem credenciais na porta 8123 são autenticadas como o
usuário de sessão padrão configurado globalmente, enquanto as da porta 8124 são autenticadas
como `readonly_user`. Um cliente que informa explicitamente um nome de usuário não é afetado.

A tag é pesquisada a partir do módulo do endpoint em direção aos módulos (`impl`)
referenciados, e o valor mais próximo do endpoint prevalece. Ela se aplica aos handlers de protocolo
`tcp`, `http`, `mysql` e `postgres`, bem como aos handlers `prometheus` que
autenticam solicitações (`remote_write`, `remote_read`, `query` e `api_v1`); os
endpoints de exposição de métricas (incluindo endpoints do Keeper exclusivos para métricas) são disponibilizados
sem autenticação e ignoram a configuração. Handlers com um usuário fixo (a chave `user`
dentro de `handler` de uma regra `http_handlers`, ou a chave `user` dentro de `handler`
de uma regra `prometheus.handlers`) autenticam as solicitações como o usuário configurado e também ignoram a configuração — em
particular, um `default_session_user` vazio não os rejeita. Ela não pode ser usada com o
protocolo `interservidor`: as conexões interservidor são autenticadas pelo Secret do cluster
e pelo usuário inicial e nunca usam o usuário de sessão padrão.

<div id="some-modules-can-contain-specific-for-its-layer-parameters">
  ### Especificando parâmetros adicionais da camada
</div>

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:

```xml theme={null}
<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>
```