Arquivos de configuração

Perfis de configuração e arquivos de configuração baseados em XML não são compatíveis com ClickHouse Cloud. Portanto, no ClickHouse Cloud, você não encontrará um arquivo config.xml. Em vez disso, use comandos SQL para gerenciar as configurações por meio de perfis de configuração.Para mais detalhes, consulte “Configuração de settings”

O servidor ClickHouse pode ser configurado com arquivos de configuração em sintaxe XML ou YAML. Na maioria dos tipos de instalação, o servidor ClickHouse usa /etc/clickhouse-server/config.xml como arquivo de configuração padrão, mas também é possível especificar manualmente o local do arquivo de configuração na inicialização do servidor usando a opção de linha de comando --config-file ou -C. Quando nenhuma dessas opções é informada, o servidor procura config.xml, config.yaml e config.yml, nessa ordem, no diretório de trabalho atual, e usa o primeiro que encontrar. Se nenhum deles existir, o servidor é iniciado com a configuração embutida no binary. Um arquivo indicado com --config-file é usado exatamente como especificado: se ele não existir, o servidor reporta um erro em vez de procurar um arquivo com outra extensão. O clickhouse-keeper segue as mesmas regras com keeper_config.xml, keeper_config.yaml e keeper_config.yml. Arquivos de configuração adicionais podem ser colocados no diretório config.d/, relativo ao arquivo de configuração principal, por exemplo no diretório /etc/clickhouse-server/config.d/. Os arquivos desse diretório e a configuração principal são mesclados em uma etapa de pré-processamento antes de a configuração ser aplicada no servidor ClickHouse. Os fragmentos de configuração são mesclados em ordem lexicográfica por seus caminhos completos. Para arquivos no diretório padrão config.d/, isso equivale a ordená-los pelo nome do arquivo. O diretório legado conf.d/ também é mesclado; como conf.d é ordenado antes de config.d, todos os seus fragmentos são processados primeiro quando ambos os diretórios existem. Para simplificar atualizações e melhorar a modularização, é uma prática recomendada manter o arquivo padrão config.xml sem alterações e colocar personalizações adicionais em config.d/. A configuração do ClickHouse Keeper fica em /etc/clickhouse-keeper/keeper_config.xml. Da mesma forma, arquivos de configuração adicionais do Keeper precisam ser colocados em /etc/clickhouse-keeper/keeper_config.d/. É possível misturar arquivos de configuração XML e YAML; por exemplo, você pode ter um arquivo de configuração principal config.xml e arquivos de configuração adicionais config.d/network.xml, config.d/timezone.yaml e config.d/keeper.yaml. Não há suporte para misturar XML e YAML em um único arquivo de configuração. Arquivos de configuração XML devem usar <clickhouse>...</clickhouse> como tag de nível superior. Em arquivos de configuração YAML, clickhouse: é opcional; se estiver ausente, o parser o insere automaticamente.

Mesclagem de configuração

Dois arquivos de configuração (geralmente o arquivo de configuração principal e outro arquivo de configuração em config.d/) são mesclados da seguinte forma:

Se um nó (ou seja, um caminho que leva a um elemento) estiver presente em ambos os arquivos e não tiver os atributos replace ou remove, ele será incluído no arquivo de configuração mesclado, e os filhos de ambos os nós serão incluídos e mesclados recursivamente.
Se um dos dois nós contiver o atributo replace, ele será incluído no arquivo de configuração mesclado, mas apenas os filhos do nó com o atributo replace serão incluídos.
Se um dos dois nós contiver o atributo remove, o nó não será incluído no arquivo de configuração mesclado (se já existir, será removido).

Por exemplo, considerando dois arquivos de configuração:

config.xml

<clickhouse>
    <config_a>
        <setting_1>1</setting_1>
    </config_a>
    <config_b>
        <setting_2>2</setting_2>
    </config_b>
    <config_c>
        <setting_3>3</setting_3>
    </config_c>
</clickhouse>

config.d/other_config.xml

<clickhouse>
    <config_a>
        <setting_4>4</setting_4>
    </config_a>
    <config_b replace="replace">
        <setting_5>5</setting_5>
    </config_b>
    <config_c remove="remove">
        <setting_6>6</setting_6>
    </config_c>
</clickhouse>

O arquivo de configuração mesclado resultante será:

<clickhouse>
    <config_a>
        <setting_1>1</setting_1>
        <setting_4>4</setting_4>
    </config_a>
    <config_b>
        <setting_5>5</setting_5>
    </config_b>
</clickhouse>

Substituição por variáveis de ambiente e nós do ZooKeeper

Para especificar que o valor de um elemento deve ser substituído pelo valor de uma variável de ambiente, você pode usar o atributo from_env. Por exemplo, com a variável de ambiente $MAX_QUERY_SIZE = 150000:

<clickhouse>
    <profiles>
        <default>
            <max_query_size from_env="MAX_QUERY_SIZE"/>
        </default>
    </profiles>
</clickhouse>

A configuração resultante será:

<clickhouse>
    <profiles>
        <default>
            <max_query_size>150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

Também é possível usar from_zk (nó do ZooKeeper):

<clickhouse>
    <postgresql_port from_zk="/zk_configs/postgresql_port"/>
</clickhouse>

# clickhouse-keeper-client
/ :) touch /zk_configs
/ :) create /zk_configs/postgresql_port "9005"
/ :) get /zk_configs/postgresql_port
9005

Resultando na configuração a seguir:

<clickhouse>
    <postgresql_port>9005</postgresql_port>
</clickhouse>

Como os valores são interpretados

from_env e from_zk diferem na forma como o valor substituído é interpretado:

Um valor direto substituído via from_env é tratado como texto literal. Caracteres especiais de XML, como &, < e >, são escapados automaticamente, de modo que uma variável de ambiente pode conter qualquer valor representável em XML, por exemplo a&b<c>d, sem quebrar a configuração (consulte abaixo a nota sobre caracteres de controle inválidos em XML). Um valor direto nunca é interpretado como XML, mesmo que pareça um fragmento XML: <a>1</a> é substituído pelo texto literal <a>1</a>. Isso também se aplica quando o atributo direto é colocado em um contêiner comum, como <profiles from_env="…"/>: uma substituição de subárvore XML já existente deve ser migrada para <profiles><include from_env="…"/></profiles>. Por compatibilidade retroativa, <include from_env="…"/> se comporta de forma diferente: ele interpreta a variável de ambiente como um fragmento XML e insere os filhos desse fragmento no elemento pai.
A interpretação de um valor substituído via from_zk depende de ele começar ou não com <. Um valor que começa com < é sempre interpretado como um fragmento XML: é assim que uma subárvore é inserida em qualquer elemento, tanto em um <include from_zk="…"/> estrutural quanto em um contêiner comum, como <profiles from_zk="…"/>. Esse comportamento é mantido por compatibilidade retroativa, pois versões anteriores sempre interpretavam um valor de from_zk como XML. Um valor que não começa com < só é interpretado como uma subárvore YAML com a forma explícita <include from_zk="…" yaml="true"/>; nesse caso, um YAML malformado faz com que a configuração seja rejeitada. O atributo yaml="true" habilita o parsing de YAML em qualquer lugar onde a forma genérica <include> seja usada, inclusive dentro de um elemento folha; portanto, não o utilize para uma configuração literal ou um segredo. Sem yaml="true", um valor que não começa com < é tratado como texto literal, inclusive quando usado por meio da forma genérica de substituição de folha <password><include from_zk="/secret"/></password>. Isso preserva valores que por acaso contenham sintaxe YAML ou sejam YAML malformado, como abc # rotated ou [1. Nessa forma, os bytes exatos só são preservados quando o <include> está em linha, sem nós de texto com espaços em branco ao redor; para segredos e configurações folha em que os bytes exatos importam, prefira a forma direta <password from_zk="…"/>. Em qualquer outro elemento — seja uma substituição de folha, como <some_setting from_zk="…"/> ou <password from_zk="…"/>, seja um contêiner comum, como <profiles from_zk="…"/> —, um valor que não começa com < também é mantido como texto literal, com seus bytes originais exatos (caracteres especiais de XML são escapados automaticamente, assim como em from_env). Assim, um valor como abc: def permanece como o texto literal abc: def, em vez de se tornar um subelemento <abc>def</abc>. Para inserir uma subárvore em um elemento comum (e não em um <include> estrutural), forneça-a como um fragmento XML (um valor que começa com <).

Valores literais devem ser texto XML 1.0 válidoUma substituição literal (from_env, ou um valor from_zk de folha que não começa com <) preserva os bytes exatos do valor para todo caractere que o XML 1.0 consegue representar como texto. Caracteres de controle inválidos em XML 1.0 — 0x00–0x08, 0x0B, 0x0C e 0x0E–0x1F — não podem, de forma alguma, ser transportados em uma configuração XML (a especificação XML os proíbe até mesmo como referências numéricas de caracteres, como ), e um valor que contenha algum deles é rejeitado quando a substituição é processada. Tabulação (\t), quebra de linha (\n) e retorno de carro (\r) são válidos e são preservados byte a byte na ida e volta.

Comportamento no upgrade para valores folha codificados com entidadesVersões anteriores reinterpretavam todo valor from_env direto como XML, de modo que um &, < ou > bruto era rejeitado como XML malformado, e a única forma de incluí-lo era codificá-lo com entidades XML: uma variável de ambiente definida como a&b era decodificada como a&b, <a>1</a> como <a>1</a> e  como um retorno de carro. Agora, um valor from_env direto é tratado como texto literal, então esses mesmos valores de ambiente passam a ser resolvidos como os literais a&b, <a>1</a> e . Ou seja, apenas valores em texto simples mantêm o significado anterior: um valor de ambiente que era codificado com entidades para o antigo caminho de processamento XML agora deve ser definido em forma bruta (por exemplo, defina a&b, que o caminho antigo rejeitava, mas o novo aceita como o texto literal a&b).Versões anteriores reinterpretavam todo valor folha from_zk como XML, de modo que um &, < ou > bruto era rejeitado como XML malformado, e a única forma de incluí-lo era codificá-lo com entidades XML: um valor armazenado como a&b era decodificado como a&b, <a>1</a> como <a>1</a> e  como um retorno de carro. Agora, um valor folha que não começa com < é mantido com seus bytes originais exatos, então esses mesmos nós passam a ser resolvidos como os literais a&b, <a>1</a> e . Ou seja, apenas escalares em texto simples mantêm o significado anterior: um valor folha que era codificado com entidades para o antigo caminho de processamento XML agora deve ser armazenado em forma bruta (por exemplo, armazene a&b, que o caminho antigo rejeitava, mas o novo aceita como o texto literal a&b).A mesma mudança se aplica a um escalar simples substituído por meio de um <include from_zk="…"/> inline dentro de uma configuração folha ou de um segredo, por exemplo <password><include from_zk="/secret"/></password>: nesse caso, o escalar também passa a ser mantido com seus bytes originais exatos, então /secret = a&b (que antes era decodificado como a&b) agora é resolvido como o literal a&b e deve ser armazenado em forma bruta como a&b. Não use espaços em branco ao redor nessa forma, pois eles passam a fazer parte do valor resultante da configuração; prefira a forma direta <password from_zk="…"/> quando os bytes exatos forem importantes. (Um valor from_zk que começa com <, ou uma subárvore YAML referenciada com <include from_zk="…" yaml="true"/>, não é afetado — apenas valores sem marcação que não começam com < são mantidos como literais.)

Valores padrão

Um elemento com os atributos from_env ou from_zk também pode ter o atributo replace="1" (este último deve aparecer antes de from_env/from_zk). Nesse caso, o elemento pode definir um valor padrão. O elemento assume o valor da variável de ambiente ou do nó do ZooKeeper, se estiver definido; caso contrário, assume o valor padrão. O exemplo anterior é repetido, mas supondo que MAX_QUERY_SIZE não esteja definido:

<clickhouse>
    <profiles>
        <default>
            <max_query_size replace="1" from_env="MAX_QUERY_SIZE">150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

O resultado é a configuração:

<clickhouse>
    <profiles>
        <default>
            <max_query_size>150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

Substituição com conteúdo de arquivo

Também é possível substituir partes da configuração pelo conteúdo de arquivos. Isso pode ser feito de duas formas:

Substituição de valores: se um elemento tiver o atributo incl, seu valor será substituído pelo conteúdo do arquivo referenciado. O caminho para o arquivo com substituições é definido pelo elemento include_from da configuração do servidor; não há um caminho padrão, portanto as substituições são lidas somente quando ele é especificado. Os valores de substituição são especificados em elementos /clickhouse/substitution_name nesse arquivo. Se uma substituição especificada em incl não existir, isso será registrado no log. Para impedir que o ClickHouse registre substituições ausentes, especifique o atributo optional="true" (por exemplo, para configurações de macros).
Substituição de elementos: se você quiser substituir o elemento inteiro por uma substituição, use include como nome do elemento. O nome de elemento include pode ser combinado com o atributo from_zk = "/path/to/node". Nesse caso, o valor do elemento é substituído pelo conteúdo do nó do ZooKeeper em /path/to/node. Isso também funciona quando você armazena uma subárvore XML inteira como um nó do ZooKeeper; ela será inserida por completo no elemento de origem.

Alterado na versão 26.8: antes dessa versão, o arquivo /etc/metrika.xml era usado implicitamente sempre que existia, mesmo quando include_from não era especificado. Se você depende desse arquivo, especifique explicitamente seu caminho em include_from. Observe que include_from é lido individualmente em cada arquivo de configuração: arquivos carregados separadamente da configuração principal do servidor — a configuração dos usuários’ (por exemplo, users.xml quando não está incluído no arquivo principal) e as configurações de Dicionário XML — cada um precisa de seu próprio elemento include_from; especificá-lo apenas na configuração principal do servidor não se aplica a eles.

Um exemplo disso é mostrado abaixo:

<clickhouse>
    <!-- Appends XML subtree found at `/profiles-in-zookeeper` ZK path to `<profiles>` element. -->
    <profiles from_zk="/profiles-in-zookeeper" />

    <users>
        <!-- Replaces `include` element with the subtree found at `/users-in-zookeeper` ZK path. -->
        <include from_zk="/users-in-zookeeper" />
        <include from_zk="/other-users-in-zookeeper" />
    </users>
</clickhouse>

Se você quiser mesclar o conteúdo da substituição com a configuração existente, em vez de apenas anexá-lo, pode usar o atributo merge="true". Por exemplo: <include from_zk="/some_path" merge="true">. Nesse caso, a configuração existente será mesclada com o conteúdo da substituição, e as configurações existentes serão substituídas pelos valores da substituição.

Criptografando e ocultando a configuração

Você pode usar criptografia simétrica para criptografar um elemento de configuração, por exemplo, uma senha em texto simples ou uma chave privada. Para isso, primeiro configure o codec de criptografia e, em seguida, adicione o atributo encrypted_by, com o nome do codec de criptografia como valor, ao elemento que será criptografado. Diferentemente dos atributos from_zk, from_env e incl, ou do elemento include, nenhuma substituição (ou seja, a descriptografia do valor criptografado) é realizada no arquivo pré-processado. A descriptografia ocorre apenas em tempo de execução, no processo do servidor. Por exemplo:

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex>00112233445566778899aabbccddeeff</key_hex>
        </aes_128_gcm_siv>
    </encryption_codecs>

    <interserver_http_credentials>
        <user>admin</user>
        <password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
    </interserver_http_credentials>

</clickhouse>

Os atributos from_env e from_zk também podem ser aplicados a encryption_codecs:

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex from_env="CLICKHOUSE_KEY_HEX"/>
        </aes_128_gcm_siv>
    </encryption_codecs>

    <interserver_http_credentials>
        <user>admin</user>
        <password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
    </interserver_http_credentials>

</clickhouse>

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex from_zk="/clickhouse/aes128_key_hex"/>
        </aes_128_gcm_siv>
    </encryption_codecs>

    <interserver_http_credentials>
        <user>admin</user>
        <password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
    </interserver_http_credentials>

</clickhouse>

Chaves de criptografia e valores criptografados podem ser definidos em qualquer um dos arquivos de configuração. Um exemplo de config.xml é o seguinte:

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex from_zk="/clickhouse/aes128_key_hex"/>
        </aes_128_gcm_siv>
    </encryption_codecs>

</clickhouse>

Um exemplo de users.xml é o seguinte:

<clickhouse>

    <users>
        <test_user>
            <password encrypted_by="AES_128_GCM_SIV">96280000000D000000000030D4632962295D46C6FA4ABF007CCEC9C1D0E19DA5AF719C1D9A46C446</password>
            <profile>default</profile>
        </test_user>
    </users>

</clickhouse>

Para criptografar um valor, você pode usar o programa de exemplo encrypt_decrypt:

./encrypt_decrypt /etc/clickhouse-server/config.xml -e AES_128_GCM_SIV abcd

961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85

Mesmo com elementos de configuração criptografados, eles ainda aparecem no arquivo de configuração pré-processado. Se isso for um problema para a sua implantação do ClickHouse, há duas alternativas: definir as permissões do arquivo pré-processado como 600 ou usar o atributo hide_in_preprocessed. Por exemplo:

<clickhouse>

    <interserver_http_credentials hide_in_preprocessed="true">
        <user>admin</user>
        <password>secret</password>
    </interserver_http_credentials>

</clickhouse>

Configurações de usuário

O arquivo config.xml pode especificar uma configuração separada com configurações de usuário, perfis e cotas. O caminho relativo para essa configuração é definido no elemento users_config. Por padrão, ele é users.xml. Se users_config for omitido, as configurações de usuário, os perfis e as cotas serão especificados diretamente em config.xml. A configuração de usuário pode ser dividida em arquivos separados, assim como em config.xml e config.d/. O nome do diretório é definido pela configuração users_config, sem o sufixo .xml, concatenado com .d. O diretório users.d é usado por padrão, já que users_config tem como padrão users.xml. Os fragmentos de configuração de usuário são mesclados em ordem lexicográfica por seus caminhos completos. Para arquivos no diretório padrão users.d/, isso equivale a ordená-los pelo nome do arquivo. O diretório legado conf.d/ também é mesclado; como conf.d é ordenado antes de users.d, todos os seus fragmentos são processados primeiro quando ambos os diretórios existem. Observe que os arquivos de configuração primeiro são mesclados, levando em conta as configurações, e as inclusões são processadas depois disso.

Exemplo em XML

Por exemplo, você pode ter um arquivo de configuração separado para cada usuário, assim:

$ cat /etc/clickhouse-server/users.d/alice.xml

<clickhouse>
    <users>
      <alice>
          <profile>analytics</profile>
            <networks>
                  <ip>::/0</ip>
            </networks>
          <password_sha256_hex>...</password_sha256_hex>
          <quota>analytics</quota>
      </alice>
    </users>
</clickhouse>

Exemplos de YAML

Aqui você pode ver a configuração padrão escrita em YAML: config.yaml.example. Há algumas diferenças entre os formatos YAML e XML no que diz respeito às configurações do ClickHouse. As dicas para escrever configurações no formato YAML são apresentadas abaixo. Uma tag XML com um valor de texto é representada por um par chave-valor em YAML

key: value

XML correspondente:

<key>value</key>

Um nó XML aninhado é representado como um mapa YAML:

map_key:
  key1: val1
  key2: val2
  key3: val3

XML correspondente:

<map_key>
    <key1>val1</key1>
    <key2>val2</key2>
    <key3>val3</key3>
</map_key>

Para criar a mesma tag XML várias vezes, use uma sequência YAML:

seq_key:
  - val1
  - val2
  - key1: val3
  - map:
      key2: val4
      key3: val5

XML correspondente:

<seq_key>val1</seq_key>
<seq_key>val2</seq_key>
<seq_key>
    <key1>val3</key1>
</seq_key>
<seq_key>
    <map>
        <key2>val4</key2>
        <key3>val5</key3>
    </map>
</seq_key>

Para fornecer um atributo XML, você pode usar uma chave de atributo com o prefixo @. Observe que @ é reservado pelo padrão YAML e, por isso, deve ser colocado entre aspas duplas:

map:
  "@attr1": value1
  "@attr2": value2
  key: 123

XML correspondente:

<map attr1="value1" attr2="value2">
    <key>123</key>
</map>

Também é possível usar atributos em uma sequência YAML:

seq:
  - "@attr1": value1
  - "@attr2": value2
  - 123
  - abc

XML correspondente:

<seq attr1="value1" attr2="value2">123</seq>
<seq attr1="value1" attr2="value2">abc</seq>

A sintaxe mencionada anteriormente não permite representar, em YAML, nós de texto XML com atributos XML. Esse caso especial pode ser tratado usando uma chave de atributo #text:

map_key:
  "@attr1": value1
  "#text": value2

XML correspondente:

<map_key attr1="value1">value2</map_key>

Detalhes de implementação

Para cada arquivo de configuração, o servidor também gera arquivos file-preprocessed.xml ao iniciar. Esses arquivos contêm todas as substituições e sobrescritas já resolvidas e se destinam apenas à consulta. Se substituições do ZooKeeper tiverem sido usadas nos arquivos de configuração, mas o ZooKeeper não estiver disponível na inicialização do servidor, o servidor carregará a configuração a partir do arquivo pré-processado. O servidor monitora alterações nos arquivos de configuração, bem como nos arquivos e nós do ZooKeeper usados para realizar substituições e sobrescritas, e recarrega dinamicamente as configurações de usuários e clusters. Isso significa que você pode modificar o cluster, os usuários e suas configurações sem reiniciar o servidor.

Fundamentos

Conceitos do ClickHouse

Boas práticas

Mesclagem de configuração

Substituição por variáveis de ambiente e nós do ZooKeeper

Como os valores são interpretados

Valores padrão

Substituição com conteúdo de arquivo

Criptografando e ocultando a configuração

Configurações de usuário

Exemplo em XML

Exemplos de YAML

Detalhes de implementação

​Mesclagem de configuração

​Substituição por variáveis de ambiente e nós do ZooKeeper

​Como os valores são interpretados

​Valores padrão

​Substituição com conteúdo de arquivo

​Criptografando e ocultando a configuração

​Configurações de usuário

​Exemplo em XML

​Exemplos de YAML

​Detalhes de implementação

Mesclagem de configuração

Substituição por variáveis de ambiente e nós do ZooKeeper

Como os valores são interpretados

Valores padrão

Substituição com conteúdo de arquivo

Criptografando e ocultando a configuração

Configurações de usuário

Exemplo em XML

Exemplos de YAML

Detalhes de implementação