SQL の配置ルール

SQL の配置ルールは、SQL ステートメントを使用して TiKV クラスター内のデータの保存場所を指定できる機能です。この機能を使用すると、クラスター、データベース、テーブル、またはパーティションのデータを特定のリージョン、データセンター、ラック、またはホストにスケジュールできます。

この機能は、次のユースケースを満たすことができます。

• 複数のデータセンターにデータをデプロイ、高可用性戦略を最適化するためのルールを構成します。
• 異なるアプリケーションからの複数のデータベースをマージし、異なるユーザーのデータを物理的に分離することで、インスタンス内の異なるユーザーの分離要件を満たします。
• 重要なデータのレプリカの数を増やして、アプリケーションの可用性とデータの信頼性を向上させます。

注記：

この機能はTiDB Cloudサーバーレスクラスターでは使用できません。

概要

SQL の配置ルール機能を使用すると、次のように、粗い粒度から細かい粒度までのさまざまなレベルのデータに対して、 配置ポリシーを作成するな配置ポリシーを構成できます。

ヒント：

SQL での配置ルールの実装は、PD の配置ルール機能に依存します。詳細については、 配置ルールを構成するを参照してください。SQL での配置ルールのコンテキストでは、配置ルールは、他のオブジェクトに添付された配置ポリシー、または TiDB から PD に送信されるルールを指す場合があります。

制限事項

• メンテナンスを簡素化するために、クラスター内の配置ポリシーの数を 10 以下に制限することをお勧めします。
• 配置ポリシーがアタッチされるテーブルとパーティションの合計数は 10,000 以下に制限することをお勧めします。ポリシーをアタッチするテーブルとパーティションが多すぎると、PD の計算ワークロードが増加し、サービス パフォーマンスに影響する可能性があります。
• 他の複雑な配置ポリシーを使用するのではなく、このドキュメントに示されている例に従って SQL 機能の配置ルールを使用することをお勧めします。

前提条件

配置ポリシーは、TiKV ノードのラベルの構成に依存します。たとえば、配置オプションPRIMARY_REGIONは、TiKV のラベルregionに依存します。

配置ポリシーを作成すると、TiDB はポリシーで指定されたラベルが存在するかどうかをチェックしません。代わりに、ポリシーをアタッチするときに TiDB がチェックを実行します。したがって、配置ポリシーをアタッチする前に、各 TiKV ノードが正しいラベルで構成されていることを確認してください。TiDB セルフマネージド クラスターの構成方法は次のとおりです。

tikv-server --labels region=<region>,zone=<zone>,host=<host>

詳細な設定方法については、次の例を参照してください。

注記：

TiDB Cloud Dedicated クラスターの場合、 TiDB Cloud Dedicated クラスター内の TiKV ノードのラベルは自動的に構成されるため、これらのラベル構成手順をスキップできます。

現在の TiKV クラスターで使用可能なすべてのラベルを表示するには、次のSHOW PLACEMENT LABELSステートメントを使用します。

SHOW PLACEMENT LABELS;
+--------+----------------+
| Key    | Values         |
+--------+----------------+
| disk   | ["ssd"]        |
| region | ["us-east-1"]  |
| zone   | ["us-east-1a"] |
+--------+----------------+
3 rows in set (0.00 sec)

使用法

このセクションでは、SQL ステートメントを使用して配置ポリシーを作成、アタッチ、表示、変更、および削除する方法について説明します。

配置ポリシーを作成して添付する

1. 配置ポリシーを作成するには、 CREATE PLACEMENT POLICYステートメントを使用します。

   CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1";
   

   この声明では、

   • PRIMARY_REGION="us-east-1"オプションは、 regionラベルのノードにRaft Leaders をus-east-1として配置することを意味します。
   • REGIONS="us-east-1,us-west-1"オプションは、 regionラベルのノードにus-east-1として、 regionラベルのノードにus-west-1としてRaft Followers を配置することを意味します。

   構成可能な配置オプションとその意味の詳細については、 配置オプションを参照してください。

2. テーブルまたはパーティションテーブルに配置ポリシーをアタッチするには、 CREATE TABLEまたはALTER TABLEステートメントを使用して、そのテーブルまたはパーティションテーブルの配置ポリシーを指定します。

   CREATE TABLE t1 (a INT) PLACEMENT POLICY=myplacementpolicy;
   CREATE TABLE t2 (a INT);
   ALTER TABLE t2 PLACEMENT POLICY=myplacementpolicy;
   

   PLACEMENT POLICYどのデータベース スキーマにも関連付けられておらず、グローバル スコープでアタッチできます。したがって、 CREATE TABLE使用して配置ポリシーを指定する場合、追加の権限は必要ありません。

配置ポリシーをビュー

• 既存の配置ポリシーを表示するには、次のSHOW CREATE PLACEMENT POLICYステートメントを使用します。

  SHOW CREATE PLACEMENT POLICY myplacementpolicy\G
  *************************** 1. row ***************************
         Policy: myplacementpolicy
  Create Policy: CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"
  1 row in set (0.00 sec)
  

• 特定のテーブルにアタッチされている配置ポリシーを表示するには、次のSHOW CREATE TABLEステートメントを使用します。

  SHOW CREATE TABLE t1\G
  *************************** 1. row ***************************
         Table: t1
  Create Table: CREATE TABLE `t1` (
    `a` int(11) DEFAULT NULL
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin /*T![placement] PLACEMENT POLICY=`myplacementpolicy` */
  1 row in set (0.00 sec)
  

• クラスター内の配置ポリシーの定義を表示するには、 INFORMATION_SCHEMA.PLACEMENT_POLICIESシステム テーブルをクエリします。

  SELECT * FROM information_schema.placement_policies\G
  ***************************[ 1. row ]***************************
  POLICY_ID            | 1
  CATALOG_NAME         | def
  POLICY_NAME          | p1
  PRIMARY_REGION       | us-east-1
  REGIONS              | us-east-1,us-west-1
  CONSTRAINTS          |
  LEADER_CONSTRAINTS   |
  FOLLOWER_CONSTRAINTS |
  LEARNER_CONSTRAINTS  |
  SCHEDULE             |
  FOLLOWERS            | 4
  LEARNERS             | 0
  1 row in set
  

• クラスター内の配置ポリシーに関連付けられているすべてのテーブルを表示するには、 information_schema.tablesのシステム テーブルのtidb_placement_policy_name列目をクエリします。

  SELECT * FROM information_schema.tables WHERE tidb_placement_policy_name IS NOT NULL;
  

• クラスター内の配置ポリシーに関連付けられているすべてのパーティションを表示するには、 information_schema.partitionsシステム テーブルのtidb_placement_policy_name列目をクエリします。

  SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS NOT NULL;
  

• すべてのオブジェクトに添付された配置ポリシーは非同期的に適用されます。配置ポリシーのスケジュールの進行状況を確認するには、 SHOW PLACEMENTステートメントを使用できます。

  SHOW PLACEMENT;
  

配置ポリシーを変更する

配置ポリシーを変更するには、 ALTER PLACEMENT POLICYステートメントを使用できます。変更は、対応するポリシーに関連付けられているすべてのオブジェクトに適用されます。

ALTER PLACEMENT POLICY myplacementpolicy FOLLOWERS=4;

このステートメントでは、 FOLLOWERS=4オプションは、 4 つのフォロワーと 1 つのLeaderを含む、データの 5 つのレプリカを構成することを意味します。 構成可能な配置オプションとその意味の詳細については、 配置オプションリファレンス参照してください。

ドロップ配置ポリシー

どのテーブルまたはパーティションにもアタッチされていないポリシーを削除するには、次のDROP PLACEMENT POLICYステートメントを使用します。

DROP PLACEMENT POLICY myplacementpolicy;

配置オプションリファレンス

配置ポリシーを作成または変更するときに、必要に応じて配置オプションを構成できます。

注記：

PRIMARY_REGION 、 REGIONS 、 SCHEDULEオプションはCONSTRAINTSオプションと同時に指定できません。指定するとエラーが発生します。

通常の配置オプション

通常の配置オプションは、データ配置の基本要件を満たすことができます。

高度な配置オプション

高度な構成オプションを使用すると、複雑なシナリオの要件を満たすためのデータ配置の柔軟性が高まります。ただし、高度なオプションの構成は通常のオプションよりも複雑であり、クラスター トポロジと TiDB データ シャーディングについて深く理解している必要があります。

制約フォーマット

次のいずれかの形式を使用して、 CONSTRAINTS 、 FOLLOWER_CONSTRAINTS 、およびLEARNER_CONSTRAINTS配置オプションを設定できます。

注記：

• LEADER_CONSTRAINTS配置オプションはリスト形式のみをサポートします。
• リスト形式と辞書形式はどちらも YAML パーサーに基づいていますが、場合によっては YAML 構文が誤って解析されることがあります。たとえば、 "{+region=east:1,+region=west:2}" ( :後にスペースがない) は'{"+region=east:1": null, "+region=west:2": null}'と誤って解析される可能性があり、これは予期しません。ただし、 "{+region=east: 1,+region=west: 2}" ( :の後にスペースがある) は'{"+region=east": 1, "+region=west": 2}'と正しく解析されます。したがって、 :の後にスペースを追加することをお勧めします。

基本的な例

クラスタ全体のレプリカ数を指定する

クラスターが初期化された後、デフォルトのレプリカ数は3です。クラスターにさらに多くのレプリカが必要な場合は、配置ポリシーを構成してこの数を増やし、 ALTER RANGE使用してクラスター レベルでポリシーを適用できます。例:

CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4;
ALTER RANGE global PLACEMENT POLICY five_replicas;

TiDB ではリーダーの数がデフォルトで1に設定されているので、 five replicasフォロワーが4 、Leaderが1であることを意味することに注意してください。

データベースのデフォルトの配置ポリシーを指定する

データベースのデフォルトの配置ポリシーを指定できます。これは、データベースのデフォルトの文字セットまたは照合順序を設定するのと同様に機能します。データベース内のテーブルまたはパーティションに他の配置ポリシーが指定されていない場合は、データベースの配置ポリシーがテーブルとパーティションに適用されます。例:

CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2";  -- Creates a placement policy

CREATE PLACEMENT POLICY p2 FOLLOWERS=4;

CREATE PLACEMENT POLICY p3 FOLLOWERS=2;

CREATE TABLE t1 (a INT);  -- Creates a table t1 without specifying any placement policy.

ALTER DATABASE test PLACEMENT POLICY=p2;  -- Changes the default placement policy of the database to p2, which does not apply to the existing table t1.

CREATE TABLE t2 (a INT);  -- Creates a table t2. The default placement policy p2 applies to t2.

CREATE TABLE t3 (a INT) PLACEMENT POLICY=p1;  -- Creates a table t3. Because this statement has specified another placement rule, the default placement policy p2 does not apply to table t3.

ALTER DATABASE test PLACEMENT POLICY=p3;  -- Changes the default policy of the database again, which does not apply to existing tables.

CREATE TABLE t4 (a INT);  -- Creates a table t4. The default placement policy p3 applies to t4.

ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- `FOLLOWERS=3` applies to the table attached with policy p3 (that is, table t4).

テーブルからそのパーティションへのポリシー継承は、前述の例のポリシー継承とは異なることに注意してください。テーブルのデフォルト ポリシーを変更すると、新しいポリシーはそのテーブル内のパーティションにも適用されます。ただし、テーブルがデータベースからポリシーを継承するのは、ポリシーを指定せずに作成された場合のみです。テーブルがデータベースからポリシーを継承すると、データベースのデフォルト ポリシーを変更してもそのテーブルには適用されません。

テーブルの配置ポリシーを指定する

テーブルのデフォルトの配置ポリシーを指定できます。例:

CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4;

CREATE TABLE t (a INT) PLACEMENT POLICY=five_replicas;  -- Creates a table t and attaches the 'five_replicas' placement policy to it.

ALTER TABLE t PLACEMENT POLICY=default; -- Removes the placement policy 'five_replicas' from the table t and resets the placement policy to the default one.

パーティションテーブルの配置ポリシーを指定する

パーティションテーブルまたはパーティションの配置ポリシーを指定することもできます。例:

CREATE PLACEMENT POLICY storageforhisotrydata CONSTRAINTS="[+node=history]";
CREATE PLACEMENT POLICY storagefornewdata CONSTRAINTS="[+node=new]";
CREATE PLACEMENT POLICY companystandardpolicy CONSTRAINTS="";

CREATE TABLE t1 (id INT, name VARCHAR(50), purchased DATE)
PLACEMENT POLICY=companystandardpolicy
PARTITION BY RANGE( YEAR(purchased) ) (
  PARTITION p0 VALUES LESS THAN (2000) PLACEMENT POLICY=storageforhisotrydata,
  PARTITION p1 VALUES LESS THAN (2005),
  PARTITION p2 VALUES LESS THAN (2010),
  PARTITION p3 VALUES LESS THAN (2015),
  PARTITION p4 VALUES LESS THAN MAXVALUE PLACEMENT POLICY=storagefornewdata
);

テーブル内のパーティションに配置ポリシーが指定されていない場合、パーティションはテーブルからポリシー (存在する場合) を継承しようとします。上記の例では、次のようになります。

• p0パーティションにはstorageforhisotrydataポリシーが適用されます。
• p4パーティションにはstoragefornewdataポリシーが適用されます。
• p1 、およびp3パーティションにはp2表t1から継承されたcompanystandardpolicy配置ポリシーが適用されます。
• テーブルt1に配置ポリシーが指定されていない場合、 p1 、 p2 、およびp3パーティションはデータベースのデフォルト ポリシーまたはグローバル デフォルト ポリシーを継承します。

これらのパーティションに配置ポリシーをアタッチした後、次の例のように特定のパーティションの配置ポリシーを変更できます。

ALTER TABLE t1 PARTITION p1 PLACEMENT POLICY=storageforhisotrydata;

高可用性の例

次のトポロジを持つクラスターがあり、TiKV ノードが 3 つのリージョンに分散され、各リージョンに 3 つの利用可能なゾーンが含まれているとします。

SELECT store_id,address,label from INFORMATION_SCHEMA.TIKV_STORE_STATUS;
+----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+
| store_id | address         | label                                                                                                                    |
+----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+
|        1 | 127.0.0.1:20163 | [{"key": "region", "value": "us-east-1"}, {"key": "zone", "value": "us-east-1a"}, {"key": "host", "value": "host1"}]     |
|        2 | 127.0.0.1:20162 | [{"key": "region", "value": "us-east-1"}, {"key": "zone", "value": "us-east-1b"}, {"key": "host", "value": "host2"}]     |
|        3 | 127.0.0.1:20164 | [{"key": "region", "value": "us-east-1"}, {"key": "zone", "value": "us-east-1c"}, {"key": "host", "value": "host3"}]     |
|        4 | 127.0.0.1:20160 | [{"key": "region", "value": "us-east-2"}, {"key": "zone", "value": "us-east-2a"}, {"key": "host", "value": "host4"}]     |
|        5 | 127.0.0.1:20161 | [{"key": "region", "value": "us-east-2"}, {"key": "zone", "value": "us-east-2b"}, {"key": "host", "value": "host5"}]     |
|        6 | 127.0.0.1:20165 | [{"key": "region", "value": "us-east-2"}, {"key": "zone", "value": "us-east-2c"}, {"key": "host", "value": "host6"}]     |
|        7 | 127.0.0.1:20166 | [{"key": "region", "value": "us-west-1"}, {"key": "zone", "value": "us-west-1a"}, {"key": "host", "value": "host7"}]     |
|        8 | 127.0.0.1:20167 | [{"key": "region", "value": "us-west-1"}, {"key": "zone", "value": "us-west-1b"}, {"key": "host", "value": "host8"}]     |
|        9 | 127.0.0.1:20168 | [{"key": "region", "value": "us-west-1"}, {"key": "zone", "value": "us-west-1c"}, {"key": "host", "value": "host9"}]     |
+----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+

生存の好みを指定する

正確なデータ分散については特に気にせず、災害復旧要件を満たすことを優先する場合は、 SURVIVAL_PREFERENCESオプションを使用してデータ存続の設定を指定できます。

前の例と同様に、TiDB クラスターは 3 つのリージョンに分散されており、各リージョンには 3 つのゾーンが含まれています。このクラスターの配置ポリシーを作成するときは、 SURVIVAL_PREFERENCESを次のように構成すると仮定します。

CREATE PLACEMENT POLICY multiaz SURVIVAL_PREFERENCES="[region, zone, host]";
CREATE PLACEMENT POLICY singleaz CONSTRAINTS="[+region=us-east-1]" SURVIVAL_PREFERENCES="[zone]";

配置ポリシーを作成したら、必要に応じて対応するテーブルに添付できます。

• multiazの配置ポリシーが関連付けられているテーブルの場合、データは異なるリージョンの 3 つのレプリカに配置され、データ分離のクロスリージョン存続目標、次にクロスゾーン存続目標、最後にクロスホスト存続目標を満たすことが優先されます。
• singleazの配置ポリシーがアタッチされたテーブルの場合、データは最初にus-east-1リージョンの 3 つのレプリカに配置され、その後、データ分離のゾーン間存続目標が満たされます。

注記：

SURVIVAL_PREFERENCESはPDではlocation-labelsに相当します。詳細についてはトポロジラベルによるレプリカのスケジュール参照してください。

複数のデータセンターに2:2:1で分散された5つのレプリカを持つクラスターを指定します。

2:2:1 の比率で 5 つのレプリカを分散するなど、特定のデータ分散が必要な場合は、次の辞書の形式のCONSTRAINTS構成することで、さまざまな制約に対して異なる数のレプリカを指定できます。

CREATE PLACEMENT POLICY `deploy221` CONSTRAINTS='{"+region=us-east-1":2, "+region=us-east-2": 2, "+region=us-west-1": 1}';

ALTER RANGE global PLACEMENT POLICY = "deploy221";

SHOW PLACEMENT;
+-------------------+---------------------------------------------------------------------------------------------+------------------+
| Target            | Placement                                                                                   | Scheduling_State |
+-------------------+---------------------------------------------------------------------------------------------+------------------+
| POLICY deploy221  | CONSTRAINTS="{\"+region=us-east-1\":2, \"+region=us-east-2\": 2, \"+region=us-west-1\": 1}" | NULL             |
| RANGE TiDB_GLOBAL | CONSTRAINTS="{\"+region=us-east-1\":2, \"+region=us-east-2\": 2, \"+region=us-west-1\": 1}" | SCHEDULED        |
+-------------------+---------------------------------------------------------------------------------------------+------------------+

クラスターにグローバルdeploy221配置ポリシーが設定されると、TiDB はこのポリシーに従ってデータを分散します。つまり、 us-east-1リージョンに 2 つのレプリカ、 us-east-2リージョンに 2 つのレプリカ、 us-west-1リージョンに 1 つのレプリカを配置します。

リーダーとフォロワーの分布を指定する

制約またはPRIMARY_REGION使用して、リーダーとフォロワーの特定の分布を指定できます。

制約を使用する

ノード間でのRaftリーダーの分散に関して特定の要件がある場合は、次のステートメントを使用して配置ポリシーを指定できます。

CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1: 1}';

この配置ポリシーが作成され、目的のデータにアタッチされると、データのRaftLeaderレプリカはLEADER_CONSTRAINTSオプションで指定されたus-east-1リージョンに配置され、データの他のレプリカはFOLLOWER_CONSTRAINTSオプションで指定されたリージョンに配置されます。 us-east-1リージョンでのノード停止など、クラスターに障害が発生した場合、これらのリージョンがFOLLOWER_CONSTRAINTSで指定されている場合でも、新しいLeaderは他のリージョンから選出されることに注意してください。つまり、サービスの可用性の確保が最優先されます。

us-east-1リージョンで障害が発生した場合、 us-west-1に新しいリーダーを配置したくない場合は、そのリージョンで新しく選出されたリーダーを排除するための特別なevict-leader属性を構成できます。

CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1,#evict-leader": 1}';

PRIMARY_REGION使用する

クラスター トポロジでregionラベルが設定されている場合は、 PRIMARY_REGIONおよびREGIONSオプションを使用してフォロワーの配置ポリシーを指定することもできます。

CREATE PLACEMENT POLICY eastandwest PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2,us-west-1" SCHEDULE="MAJORITY_IN_PRIMARY" FOLLOWERS=4;
CREATE TABLE t1 (a INT) PLACEMENT POLICY=eastandwest;

• PRIMARY_REGIONリーダーの配布地域を指定します。このオプションでは 1 つの地域のみ指定できます。
• SCHEDULEオプションは、TiDB がフォロワーの分散をどのようにバランスさせるかを指定します。
  • デフォルトのEVENスケジュール ルールにより、すべてのリージョンにわたってフォロワーが均等に分散されます。
  • 十分な数のFollowerレプリカがPRIMARY_REGION (つまりus-east-1 ) に配置されるようにするには、 MAJORITY_IN_PRIMARYスケジュール ルールを使用できます。このスケジュール ルールでは、可用性を犠牲にして、トランザクションのレイテンシーが低くなります。プライマリ リージョンに障害が発生した場合、 MAJORITY_IN_PRIMARY自動フェイルオーバーは提供されません。

データ分離の例

次の例のように、配置ポリシーを作成するときに、各ポリシーに制約を構成して、指定されたappラベルを持つ TiKV ノードにデータを配置するように要求できます。

CREATE PLACEMENT POLICY app_order CONSTRAINTS="[+app=order]";
CREATE PLACEMENT POLICY app_list CONSTRAINTS="[+app=list_collection]";
CREATE TABLE order (id INT, name VARCHAR(50), purchased DATE)
PLACEMENT POLICY=app_order
CREATE TABLE list (id INT, name VARCHAR(50), purchased DATE)
PLACEMENT POLICY=app_list

この例では、制約は[+app=order]などのリスト形式を使用して指定されています。 {+app=order: 3}などの辞書形式を使用して指定することもできます。

例のステートメントを実行すると、TiDB はapp_orderデータをappラベルを持つ TiKV ノードにorderとして配置し、 app_listデータをappラベルを持つ TiKV ノードにlist_collectionとして配置して、storage内での物理的なデータ分離を実現します。

互換性

他の機能との互換性

• 一時テーブルは配置ポリシーをサポートしていません。
• 配置ポリシーは、保存中のデータが正しい TiKV ノードに存在することを保証するだけで、転送中のデータ (ユーザー クエリまたは内部操作経由) が特定のリージョンでのみ発生することを保証するものではありません。
• データのTiFlashレプリカを構成するには、配置ポリシーを使用するのではなく、 TiFlashレプリカを作成する実行する必要があります。
• 構文糖衣規則は設定PRIMARY_REGIONとREGIONSに許可されています。将来的にはPRIMARY_RACK 、 PRIMARY_ZONE 、 PRIMARY_HOSTにも多様性を追加する予定です。 問題 #18030参照してください。

ツールとの互換性