Skip to main content
レプリカ対応ルーティング (sticky sessions、スティッキールーティング、session affinity とも呼ばれます) は、関連するリクエストを同じ ClickHouse レプリカに振り分けます。一時テーブルや名前付きセッション状態をクエリ間で利用可能な状態に保つ必要がある場合、関連するクエリで同じレプリカのローカル cache を再利用する場合、または書き込みとその後の読み取りで書き込み後の読み取り整合性が必要な場合に使用します。 これはベストエフォートであり、分離は保証されません。プロキシ は各ルーティング値を 1 つのレプリカにマッピングします。レプリカ数が変わらない限り、このマッピングは安定していますが、サービス をスケーリングすると、その値が別のレプリカにマッピングされる可能性があります。 レプリカ対応ルーティングは、次の両方のインターフェイスで利用できます。 どちらも個別に有効化され、プロキシ の背後で同じ 一貫性ハッシュ を使用します。

​
前提条件

  • ご利用のサービスには 2 つ以上のレプリカ が必要です。単一レプリカのサービスでは、固定先となるレプリカがありません。
  • Enterprise tier のサービスであること。
  • 標準の ClickHouse Cloud サービスおよび BYOC でサポートされています

​
レプリカ対応ルーティングの設定

Enterprise のお客様は、ClickHouse Cloud コンソールのサービス設定ページからレプリカ対応ルーティングを有効化できます。対象のサービスを開き、Settings に移動して、利用したいインターフェイスのトグルをオンにしてください。
  • 一方のトグルは、X-ClickHouse-Replica-Tag ヘッダーを用いた HTTP ベースのルーティングを有効にします。
  • もう一方のトグルは、SNI オーバーライド を用いたネイティブプロトコルのルーティングを有効にします。
いずれか一方でも、両方でも有効にできます。再起動は不要で、反映までにかかる時間は 1 分未満です。 これらのトグルは Enterprise tier のプランへ順次展開されています。お使いのサービスでまだ利用できない場合は、サービス ID を添えて サポート チケットを起票いただければ、早期に機能を有効化できます。

​
HTTP ベースのルーティング

ワークロードを特定のレプリカに固定するには、HTTPS インターフェイス経由のリクエストに X-ClickHouse-Replica-Tag ヘッダーを付加します。プロキシはヘッダー値に対して一貫性ハッシュを使用するため、レプリカ数が変わらない限り、同じ値を持つリクエストは同じレプリカに送られます。異なる値はそれぞれ独立してハッシュ化され、同じレプリカまたは別のレプリカに送られる可能性がありますが、値をどのレプリカにマッピングするかを指定することはできません。 既存のサービスホスト名を使用してください。特別な sticky ホスト名や DNS の変更は必要ありません。ヘッダー値には、アプリケーション名、ユーザー ID、ワークロードラベルなど、任意の文字列を指定できます。ヘッダーのないリクエストには、通常の負荷分散が適用されます。 各リクエストに X-ClickHouse-Replica-Tag ヘッダーを設定します。
clickhouse-go (v2) では、Protocol: clickhouse.HTTP を設定し、HttpHeaders 接続オプションを使用してヘッダーを渡します。
X-ClickHouse-Replica-Tag を使用すると、ClickHouse HTTP セッションを作成せずにレプリカアフィニティを実現できます。同時実行リクエストでも、SESSION_IS_LOCKED を発生させることなく同じタグを再利用できます。

​
ネイティブプロトコルでのルーティング

ネイティブプロトコルを使用する場合は、ルーティング値を <routing-value>.sticky.<host> という形式の TLS サーバー名として渡します。接続先には、通常どおりサービスホスト名を指定します。ClickHouse Client では、--tls-sni-override でルーティング値を指定します:
--host には通常のサービスホスト名を指定し、--secure で TLS を有効化し、--tls-sni-override でルーティング値を渡します。TLS は必須です。追加の証明書や DNS エントリは不要です。

​
書き込み後の読み取り整合性

マルチレプリカの service では、あるレプリカへの書き込みが、レプリケーションが追いつくまで他のレプリカから見えないことがあります。書き込み時に routing value を指定し、後続の読み取りでも同じ値を再利用してください。proxy が両方を同じレプリカにルーティングするため、他のレプリカがまだ追いついていない状態でも、自身の書き込みを読み取れます。このパターンは、書き込んだ直後に同じデータを読み返すワークロード、たとえばインタラクティブなアプリケーションや、次の処理に進む前に insert を検証する ETL ジョブに適しています。 また、スキーマ変更がまだレプリケーションされていない場合にも有効です。routing value を再利用すれば、新しいスキーマをすでに持つレプリカに insert し続けられるためです。 HTTP 経由では、ヘッダー値を再利用します:
ネイティブプロトコル経由の場合は、同じ SNI オーバーライドを再利用します。
すべてのレプリカにわたるより広範な保証が必要な場合は、ClickHouse Cloud で select_sequential_consistency を 1 に設定することもできます。

​
接続先のレプリカを確認する

同じ routing value を使用して、SELECT hostName() の例のいずれかを再度実行します。レプリカ数が変わらない限り、同じホスト名が返されるはずです。異なる routing value は、別のレプリカにマッピングされる場合があります。

​
レプリカ対応ルーティングの制約事項

​
レプリカ数の変更によりスティッキー性が変化します

スケールアウト/スケールインにより、ルーティングのハッシュリングが変化します。その結果、同じ routing value を共有するリクエストが別のレプリカに振り分けられる場合があります。一時テーブルやセッションレベルの設定に依存している場合は、再マップ後にそれらを再作成できるようにしておいてください。SELECT hostName() を実行すれば、現在どのレプリカに接続しているかを常に確認できます。

​
レプリカ対応ルーティングはワークロードの分離ではありません

スティッキールーティングで制御できるのは、どのレプリカがリクエストを処理するかだけです。そのレプリカは、引き続きほかのトラフィックも処理する可能性があります。専用のコンピュートが必要な場合は、コンピュート-コンピュート分離を使用してください。

​
プライベートネットワーキング

HTTP ベースのルーティングとネイティブプロトコルのルーティングはいずれも、通常のサービスホスト名でプライベートネットワーキングを使用する場合は動作します。追加の DNS エントリは必要ありません。

​
ネイティブプロトコルのルーティングには TLS が必要

ネイティブプロトコルのルーティングには TLS が必要なため、--secure を指定してください。暗号化されていないネイティブ接続の場合は、通常の負荷分散が使用されます。

​
トラブルシューティング

同じルーティング値を使用しているにもかかわらず、クエリが異なるレプリカに送信される
  • 使用しているインターフェイスのトグルが、サービス設定ページで有効になっていることを確認してください。HTTP とネイティブの各メソッドは個別に有効化します。
  • HTTP 経由の場合、すべてのリクエストに X-ClickHouse-Replica-Tag ヘッダーが含まれ、すべてのリクエストで完全に同じ値が使用されていることを確認してください。
  • ネイティブプロトコル経由の場合、--secure が設定されており、--tls-sni-override が <routing-value>.sticky.<host> の形式になっていることを確認してください。
  • 有効化後、しばらく待ってください。反映までに 1 分未満かかることがあります。
  • 最近レプリカ数が変更されたかどうかを確認してください。スケーリング後の再マッピングは想定される動作です。新しいマッピングを確認するには、SELECT hostName() を使用してください。
ネイティブプロトコル経由での証明書エラー
  • --host が通常のサービスホスト名であること、およびルーティング値が --host ではなく --tls-sni-override を介して渡されていることを確認してください。
最終更新日 2026年9月26日