データベースの作成
zoo_path— ZooKeeper のパスです。同じ ZooKeeper パスは同じデータベースに対応します。shard_name— 分片名です。データベースのレプリカはshard_nameによって分片ごとにグループ化されます。replica_name— レプリカ名です。同じ分片内のすべてのレプリカで、レプリカ名はそれぞれ異なっている必要があります。
zoo_path にマクロ {uuid} が含まれている場合は、このデータベースのすべてのレプリカで同じ UUID が使われるように、明示的に UUID を指定するか、CREATE ステートメントに ON CLUSTER を追加する必要があります。
ReplicatedMergeTree テーブルでは、引数が指定されていない場合、デフォルト引数 /clickhouse/tables/{uuid}/{shard} と {replica} が使用されます。これらは、サーバー設定 default_replica_path および default_replica_name で変更できます。マクロ {uuid} はテーブルの uuid に展開され、{shard} と {replica} はデータベースエンジンの引数ではなく、サーバー設定の値に展開されます。ただし将来的には、Replicated データベースの shard_name と replica_name を使用できるようになる予定です。
デフォルトの ZooKeeper クラスターの代わりに、Replicated データベースのメタデータ保存先として補助 ZooKeeper クラスターを使用することもサポートされています。次のように SQL を使用して、補助 ZooKeeper クラスターを使うReplicated データベースを作成できます。
特有の動作と推奨事項
Replicated データベースでの DDL クエリは、ON CLUSTER クエリとほぼ同様に動作しますが、いくつか細かな違いがあります。
まず、DDL リクエストはイニシエーター (ユーザーからのリクエストを最初に受け取ったホスト) で実行が試みられます。ここでリクエストを完了できなかった場合、ユーザーには即座にエラーが返され、他のホストで実行が試みられることはありません。イニシエーターで正常に完了した場合は、他のすべてのホストが完了するまで自動的に再試行します。イニシエーターは、他のホストでのクエリ完了を待機しようとし (待機時間は distributed_ddl_task_timeout まで) 、各ホストにおけるクエリ実行ステータスを示すテーブルを返します。
エラー時の動作は distributed_ddl_output_mode 設定で制御されますが、Replicated データベースではこれを null_status_on_timeout に設定することを推奨します。つまり、一部のホストが distributed_ddl_task_timeout 以内にリクエストを実行できなかった場合でも、例外をスローするのではなく、それらのホストについてはテーブル内に NULL ステータスを表示します。
system.clusters システムテーブルには、Replicated データベースと同名のクラスターが含まれており、そのクラスターはそのデータベースのすべてのレプリカで構成されます。このクラスターは、レプリカの作成や削除に応じて自動的に更新され、Distributed 分散テーブルで利用できます。
データベースの新しいレプリカを作成すると、そのレプリカは自動的にテーブルを作成します。レプリカが長期間利用不能で、レプリケーションログに対して大きく遅れている場合は、ローカルメタデータを ZooKeeper 上の現在のメタデータと照合し、余分なデータを含むテーブルを別の非レプリケートデータベースに移動し (不要なものを誤って削除しないようにするため) 、不足しているテーブルを作成し、テーブル名が変更されている場合はその名前を更新します。データは ReplicatedMergeTree レベルでレプリケートされます。つまり、テーブルがレプリケートされていない場合、データはレプリケートされません (データベースが担うのはメタデータのみです) 。
ALTER TABLE FREEZE|ATTACH|FETCH|DROP|DROP DETACHED|DETACH PARTITION|PART クエリは許可されていますが、レプリケートはされません。データベースエンジンは、現在のレプリカに対してのみパーティションまたはパートの追加、fetch、削除を行います。ただし、テーブル自体が Replicated テーブルエンジンを使用している場合は、ATTACH 実行後にデータがレプリケートされます。
テーブルのレプリケーションを維持せずにクラスターだけを構成したい場合は、Cluster Discovery 機能を参照してください。
使用例
{uuid} を zoo_path で使用している場合に、別のホストへレプリカを追加する:
設定
| 設定 | デフォルト | 説明 |
|---|---|---|
max_broken_tables_ratio | 1 | 古くなったテーブルの比率が全テーブルに対してこの値を超える場合、レプリカは自動復旧されません |
max_replication_lag_to_enqueue | 50 | レプリケーション遅延がこの値を超えているレプリカでクエリを実行しようとすると、例外がスローされます |
wait_entry_commited_timeout_sec | 3600 | タイムアウトを超過してもイニシエーターホストがまだそのクエリを実行していない場合、レプリカはクエリのキャンセルを試みます |
collection_name | クラスター認証に関するすべての情報が定義されている、サーバーの設定内のコレクション名 | |
check_consistency | true | ローカルメタデータと Keeper 内のメタデータの整合性を確認し、不整合がある場合はレプリカの復旧を行います |
max_retries_before_automatic_recovery | 10 | キューエントリの実行試行回数の上限です。これを超えると、レプリカは失われたものと見なされ、スナップショットから復旧されます (0 は無制限を意味します) |
allow_skipping_old_temporary_tables_ddls_of_refreshable_materialized_views | false | 有効な場合、Replicatedデータベースで DDL を処理する際に、可能であればリフレッシュ可能なマテリアライズドビューの一時テーブルに対する DDL の作成および入れ替えをスキップします |
logs_to_keep | 1000 | Replicatedデータベース用に ZooKeeper に保持するログのデフォルト数です。 |
default_replica_path | /clickhouse/databases/{uuid} | ZooKeeper 内のデータベースへのパスです。引数が省略された場合、データベース作成時に使用されます。 |
default_replica_shard_name | {shard} | データベース内のレプリカの分片名です。引数が省略された場合、データベース作成時に使用されます。 |
default_replica_name | {replica} | データベース内のレプリカ名です。引数が省略された場合、データベース作成時に使用されます。 |
internal_replication | false | この Replicatedデータベースのクラスターで作成された 分散テーブルが、データをいずれか 1 つのレプリカに送信するか (internal replication はクラスター内のレプリカ自身がレプリケーションを行うことを意味します) 、またはすべてのレプリカに送信するかを指定します (internal replication が無効な場合、分散テーブルは挿入されたデータをすべてのレプリカに送信します) |