設定ファイル

XML ベースの settings profiles と設定ファイルは、ClickHouse Cloud ではサポートされていません。そのため、ClickHouse Cloud には config.xml ファイルは存在しません。代わりに、SQL コマンドを使用して settings profiles 経由で設定を管理する必要があります。詳細は、“Configuring Settings” を参照してください。

ClickHouse サーバーは、XML または YAML 構文の設定ファイルで構成できます。ほとんどのインストール形態では、ClickHouse サーバーは /etc/clickhouse-server/config.xml をデフォルトの設定ファイルとして使用して動作しますが、サーバーの起動時にコマンドラインオプション --config-file または -C を使って、設定ファイルの場所を手動で指定することもできます。これらのオプションがいずれも指定されていない場合、サーバーはカレントディレクトリ内で config.xml、config.yaml、config.yml をこの順に探し、最初に見つかったものを使用します。いずれも存在しない場合、サーバーはバイナリに埋め込まれた設定で起動します。 --config-file で指定されたファイルはそのまま使用されます。ファイルが存在しない場合、サーバーは別の拡張子のファイルを探さず、エラーを報告します。 clickhouse-keeper も、keeper_config.xml、keeper_config.yaml、keeper_config.yml に対して同じ規則に従います。追加の設定ファイルは、メインの設定ファイルからの相対ディレクトリである config.d/ に配置できます。たとえば、/etc/clickhouse-server/config.d/ ディレクトリです。このディレクトリ内のファイルとメイン設定は、ClickHouse サーバーに設定が適用される前の前処理段階でマージされます。設定フラグメントは完全パスの辞書式順序でマージされます。標準の config.d/ ディレクトリ内のファイルでは、これはファイル名順と同等です。レガシーの conf.d/ ディレクトリもマージされます。conf.d は config.d より前にソートされるため、両方のディレクトリが存在する場合は、そのすべてのフラグメントが最初に処理されます。更新を容易にし、モジュール化を進めるため、デフォルトの config.xml ファイルは変更せず、追加のカスタマイズは config.d/ に配置するのがベストプラクティスです。 ClickHouse Keeper の設定は /etc/clickhouse-keeper/keeper_config.xml にあります。同様に、Keeper 用の追加設定ファイルは /etc/clickhouse-keeper/keeper_config.d/ に配置する必要があります。 XML と YAML の設定ファイルを混在させることも可能です。たとえば、メイン設定ファイルとして config.xml を使用し、追加の設定ファイルとして config.d/network.xml、config.d/timezone.yaml、config.d/keeper.yaml を使用できます。単一の設定ファイル内で XML と YAML を混在させることはサポートされていません。 XML 設定ファイルでは、トップレベルタグとして <clickhouse>...</clickhouse> を使用する必要があります。 YAML 設定ファイルでは、clickhouse: は省略可能で、省略された場合はパーサーが自動的に挿入します。

設定ファイルのマージ

2 つの設定ファイル (通常はメインの設定ファイルと、config.d/ 内の別の設定ファイル) は、次のルールでマージされます。

ノード (つまり、要素に至る path) が両方のファイルに存在し、replace 属性または remove 属性を持たない場合、そのノードはマージ後の設定ファイルに含まれ、両方のノードの子要素も含めて再帰的にマージされます。
2 つのノードのいずれか 1 つが replace 属性を持つ場合、そのノードはマージ後の設定ファイルに含まれますが、含まれる子要素は replace 属性を持つノードのものだけです。
2 つのノードのいずれか 1 つが remove 属性を持つ場合、そのノードはマージ後の設定ファイルに含まれません (すでに存在する場合は削除されます) 。

たとえば、次の 2 つの設定ファイルがあるとします。

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>

結果として生成されるマージ後の設定ファイルは次のようになります。

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

環境変数とZooKeeperノードによる置換

要素の値を環境変数の値に置き換えるよう指定するには、属性 from_env を使用できます。たとえば、環境変数 $MAX_QUERY_SIZE = 150000 が設定されている場合:

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

最終的な設定は次のようになります。

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

from_zk (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

その結果、次の設定になります。

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

値の解釈方法

from_env と from_zk では、置換される値の解釈方法が異なります。

from_env で置換される直接値は、リテラルテキストとして扱われます。&、<、> などの XML 特殊文字は自動的にエスケープされるため、環境変数に a&b<c>d のような XML で表現可能な任意の値を含めても、設定が壊れることはありません (XML で使用できない制御文字については、後述の注記を参照してください)。直接値は、XML フラグメントのように見える場合でも XML として解釈されることはありません。たとえば <a>1</a> は、リテラルテキスト <a>1</a> として置換されます。これは、直接属性を <profiles from_env="…"/> のような通常のコンテナー要素に指定した場合も同様です。既存の XML サブツリー置換は <profiles><include from_env="…"/></profiles> に移行する必要があります。ただし後方互換性のため、<include from_env="…"/> は例外的な動作となり、環境変数を XML フラグメントとしてパースし、その子要素を親要素に挿入します。
from_zk で置換される値の扱いは、値が < で始まるかどうかによって異なります。< で始まる値は常に XML フラグメントとしてパースされます。構造的な <include from_zk="…"/> でも、<profiles from_zk="…"/> のような通常のコンテナー要素でも、任意の要素にサブツリーを挿入するにはこの方法を使用します。以前のバージョンでは from_zk の値が常に XML として解釈されていたため、後方互換性のためにこの動作が維持されています。< で始まらない値は、明示的な形式 <include from_zk="…" yaml="true"/> を使用した場合にのみ YAML サブツリーとしてパースされ、YAML が不正な場合は設定全体が拒否されます。yaml="true" 属性は、leaf 要素の内部を含め、汎用の <include> 形式を使用するすべての場所で YAML パースを有効にするため、リテラルの設定値やシークレットには使用しないでください。yaml="true" を指定しない場合、< で始まらない値はリテラルテキストとして扱われます。これは汎用の leaf 置換形式 <password><include from_zk="/secret"/></password> を使用した場合も同様です。これにより、abc # rotated や [1 のように、たまたま YAML 構文を含む値や不正な YAML の値もそのまま保持されます。ただしこの形式では、<include> の前後に空白のテキストノードがなく、インラインで記述されている場合にのみ、正確なバイト列が保持されます。正確なバイト列が重要となるシークレットや leaf 設定には、直接形式の <password from_zk="…"/> を使用することを推奨します。それ以外の要素では、<some_setting from_zk="…"/> や <password from_zk="…"/> のような leaf 置換でも、<profiles from_zk="…"/> のような通常のコンテナー要素でも、< で始まらない値は元の正確なバイト列のままリテラルテキストとして保持されます (XML 特殊文字は from_env と同様に自動的にエスケープされます)。そのため、たとえば abc: def という値は <abc>def</abc> というサブ要素にはならず、リテラルテキスト abc: def のまま保持されます。(構造的な <include> ではなく) 通常の要素にサブツリーを挿入するには、XML フラグメント (< で始まる値) として指定してください。

リテラル値は有効な XML 1.0 テキストである必要がありますリテラル置換 (from_env、または < で始まらない leaf の from_zk 値) では、XML 1.0 がテキストとして表現できるすべての文字について、値の正確なバイト列が保持されます。XML 1.0 で使用できない制御文字 (0x00–0x08、0x0B、0x0C、0x0E–0x1F) は、XML 設定を介して渡すことが一切できません (XML 仕様では、 のような数値文字参照としても禁止されています)。これらの文字を含む値は、置換の処理時に拒否されます。タブ (\t)、改行 (\n)、復帰 (\r) は使用可能で、バイト単位で正確に往復変換されます。

エンティティエンコードされたleaf値のアップグレード時の動作以前のバージョンでは、直接指定された from_env の値をすべて XML として再パースしていたため、生の &、<、> は整形式でないとして拒否され、これらを埋め込むには XML エンティティエンコードするしかありませんでした。たとえば、環境変数に a&b を設定すると a&b に、<a>1</a> は <a>1</a> に、 はキャリッジリターンにデコードされていました。現在は、直接指定された from_env の値はリテラルテキストとして扱われるため、同じ環境変数の値はそれぞれリテラルの a&b、<a>1</a>、 として解決されます。つまり、以前と同じ意味を保つのはプレーンテキストの値だけです。旧来の XML パス向けにエンティティエンコードしていた環境変数の値は、生のまま設定し直す必要があります (たとえば a&b を設定します。これは旧来のパスでは拒否されていましたが、新しいパスではリテラルテキスト a&b として受け入れられます) 。以前のバージョンでは、leaf の from_zk の値をすべて XML として再パースしていたため、生の &、<、> は整形式でないとして拒否され、これらを埋め込むには XML エンティティエンコードするしかありませんでした。たとえば、a&b として保存された値は a&b に、<a>1</a> は <a>1</a> に、 はキャリッジリターンにデコードされていました。現在は、< で始まらない leaf 値は元のバイト列のまま保持されるため、同じノードはそれぞれリテラルの a&b、<a>1</a>、 として解決されます。つまり、以前と同じ意味を保つのはプレーンテキストのスカラー値だけです。旧来の XML パス向けにエンティティエンコードしていた leaf 値は、生のまま保存し直す必要があります (たとえば a&b を保存します。これは旧来のパスでは拒否されていましたが、新しいパスではリテラルテキスト a&b として受け入れられます) 。この変更は、leaf の設定やシークレットの下でインラインの <include from_zk="…"/> によって置換されるプレーンなスカラー値にも適用されます (例: <password><include from_zk="/secret"/></password>) 。この場合もスカラー値は元のバイト列のまま保持されるため、/secret = a&b (以前は a&b にデコードされていました) はリテラルの a&b として解決されるようになり、生のまま a&b として保存し直す必要があります。この形式では、前後に空白を入れないでください。空白もそのまま設定値の一部になります。正確なバイト列が重要な場合は、直接指定の <password from_zk="…"/> 形式を使用することを推奨します。 (< で始まる from_zk の値や、<include from_zk="…" yaml="true"/> で参照される YAML サブツリーは影響を受けません。リテラルとして保持されるのは、マークのない、< 以外で始まる値のみです。)

デフォルト値

from_env または from_zk 属性を持つ要素には、追加で replace="1" 属性を指定することもできます (後者は from_env/from_zk より前に記述する必要があります) 。この場合、その要素にデフォルト値を定義できます。環境変数または ZooKeeper ノードが設定されている場合、要素にはその値が使用され、設定されていない場合はデフォルト値が使用されます。以下では、MAX_QUERY_SIZE が設定されていないものとして、前の例を繰り返します。

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

結果として、次の設定になります：

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

ファイル内容による置換

設定の一部をファイルの内容で置き換えることもできます。これには次の 2 つの方法があります。

値の置換: 要素に incl 属性がある場合、その値は参照先ファイルの内容で置き換えられます。置換用ファイルのパスは、サーバー設定の include_from 要素で設定します。デフォルトのパスはないため、指定されている場合にのみ置換が読み取られます。このファイルでは、置換値を /clickhouse/substitution_name 要素に指定します。incl で指定した置換が存在しない場合は、その旨がログに記録されます。ClickHouse が不足している置換をログに記録しないようにするには、optional="true" 属性を指定します (たとえば、macros の設定) 。
要素の置換: 置換で要素全体を置き換えたい場合は、要素名として include を使用します。要素名 include は、from_zk = "/path/to/node" 属性と組み合わせて使用できます。この場合、要素の値は /path/to/node にある ZooKeeper ノードの内容で置き換えられます。これは、XML サブツリー全体を ZooKeeper ノードとして保存した場合にも機能し、その内容全体がソース要素に挿入されます。

バージョン 26.8 で変更: それ以前のバージョンでは、include_from が指定されていない場合でも、ファイル /etc/metrika.xml が存在すれば暗黙的に使用されていました。このファイルに依存している場合は、そのパスを include_from に明示的に指定してください。include_from は各設定ファイルから個別に読み取られることに注意してください。メインサーバー設定とは別に読み込まれるファイル、つまりユーザー’設定 (たとえば、メインファイルに含まれていない場合の users.xml) と XML Dictionary 設定には、それぞれ独自の include_from 要素が必要です。メインサーバー設定でのみ指定しても、それらには適用されません。

その例を以下に示します。

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

追加するのではなく、置換される内容を既存の設定にマージしたい場合は、属性 merge="true" を使用できます。例: <include from_zk="/some_path" merge="true">。この場合、既存の設定は置換内容とマージされ、既存の設定項目は置換内容の値で置き換えられます。

設定の暗号化と秘匿

対称暗号化を使用して、設定要素 (たとえば平文のパスワードや秘密鍵) を暗号化できます。そのためには、まず暗号化コーデックを設定し、次に暗号化する要素に、暗号化コーデック名を値に持つ属性 encrypted_by を追加します。 from_zk、from_env、incl 属性や include 要素とは異なり、前処理済みファイルでは置換 (つまり、暗号化された値の復号) は行われません。復号は、サーバープロセスの実行時にのみ行われます。例:

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

属性 from_env と from_zk は、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>

暗号化キーと暗号化された値は、どちらの設定ファイルにも定義できます。 config.xml の例を以下に示します。

<clickhouse>

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

</clickhouse>

users.xml の例は次のとおりです:

<clickhouse>

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

</clickhouse>

値を暗号化するには、 (例) プログラム encrypt_decrypt を使用できます:

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

961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85

暗号化された設定要素を使用していても、前処理済みの設定ファイルには暗号化された要素がそのまま表示されます。これが ClickHouse のデプロイメントで問題になる場合は、対処方法が 2 つあります。前処理済みファイルの権限を 600 に設定するか、属性 hide_in_preprocessed を使用してください。例:

<clickhouse>

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

</clickhouse>

ユーザー設定

config.xml ファイルでは、ユーザー設定、プロファイル、クォータ用の設定を別ファイルとして指定できます。この設定への相対パスは users_config 要素で設定します。デフォルトでは users.xml です。users_config を省略した場合、ユーザー設定、プロファイル、クォータは config.xml に直接指定されます。ユーザー設定は、config.xml および config.d/ と同様に、複数のファイルに分割できます。ディレクトリ名は、users_config 設定値から .xml 接尾辞を除き、.d を連結した名前になります。デフォルトでは users_config は users.xml のため、users.d ディレクトリが使用されます。ユーザー設定フラグメントは、完全パスの辞書式順序でマージされます。標準の users.d/ ディレクトリ内のファイルでは、これはファイル名順と同等です。レガシーの conf.d/ ディレクトリもマージされます。conf.d は users.d より先にソートされるため、両方のディレクトリが存在する場合は、そのすべてのフラグメントが先に処理されます。なお、設定ファイルはまず設定項目を考慮してマージされ、その後で include が処理されます。

XML の例

たとえば、各ユーザーごとにこのような個別の設定ファイルを用意できます。

$ 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>

YAML の例

ここでは、YAML で記述されたデフォルト設定を確認できます: config.yaml.example。 ClickHouse の設定では、YAML フォーマットと XML フォーマットにいくつか違いがあります。 YAML フォーマットで設定を記述する際のヒントを以下に示します。テキスト値を持つ XML タグは、YAML ではキー・バリューのペアで表されます

key: value

対応する XML:

<key>value</key>

ネストされた XML ノードは、YAML のマップとして表現されます。

map_key:
  key1: val1
  key2: val2
  key3: val3

対応する XML:

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

同じXMLタグを複数回作成するには、YAMLシーケンスを使用します。

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

対応する XML:

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

XML の属性を指定するには、@ プレフィックス付きの属性キーを使用できます。なお、@ は YAML 標準で予約されているため、二重引用符で囲む必要があります。

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

対応する XML:

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

YAML シーケンスでも属性を使用できます。

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

対応する XML:

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

前述の構文では、XML属性を持つXMLテキストノードをYAMLで表現できません。この特殊なケースは、 #text 属性キーを使うことで表現できます：

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

対応する XML:

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

実装の詳細

各設定ファイルについて、サーバーは起動時に file-preprocessed.xml ファイルも生成します。これらのファイルには、すべての置換と上書きが反映された内容が含まれており、参照用の情報として利用できます。設定ファイルで ZooKeeper の置換が使用されていても、サーバー起動時に ZooKeeper を利用できない場合、サーバーは前処理済みファイルから設定を読み込みます。サーバーは、設定ファイルの変更に加え、置換や上書きの実行時に使用されたファイルや ZooKeeper ノードの変更も追跡し、ユーザーとクラスターの設定を動的に再読み込みします。つまり、サーバーを再起動しなくても、クラスター、ユーザー、およびそれらの設定を変更できます。

基礎

ClickHouseの基本概念

ベストプラクティス

設定ファイルのマージ

環境変数とZooKeeperノードによる置換

値の解釈方法

デフォルト値

ファイル内容による置換

設定の暗号化と秘匿

ユーザー設定

XML の例

YAML の例

実装の詳細

​設定ファイルのマージ

​環境変数とZooKeeperノードによる置換

​値の解釈方法

​デフォルト値

​ファイル内容による置換

​設定の暗号化と秘匿

​ユーザー設定

​XML の例

​YAML の例

​実装の詳細

設定ファイルのマージ

環境変数とZooKeeperノードによる置換

値の解釈方法

デフォルト値

ファイル内容による置換

設定の暗号化と秘匿

ユーザー設定

XML の例

YAML の例

実装の詳細