diff --git a/information-schema/information-schema-placement-rules.md b/information-schema/information-schema-placement-rules.md index cace3bee4401..e23b0460100b 100644 --- a/information-schema/information-schema-placement-rules.md +++ b/information-schema/information-schema-placement-rules.md @@ -5,7 +5,7 @@ summary: 了解 information_schema 表 `PLACEMENT_RULES`。 # PLACEMENT_RULES -`PLACEMENT_RULES` 表展示所有已显式配置的 [Placement Rules in SQL](/placement-rules-in-sql.md) 信息，包括通过放置策略 (placement policy) 和通过直接放置 (directly placement) 进行配置的信息。 +`PLACEMENT_RULES` 表展示所有已显式配置的 [Placement Rules in SQL](/placement-rules-in-sql.md) 信息，即所有放置策略 (placement policy) 的信息。 {{< copyable "sql" >}} @@ -39,17 +39,16 @@ DESC placement_rules; ## 示例 -`PLACEMENT_RULES` 表只展示显式配置的规则。如要查看 Placement Rules 放置规则的规范版本（包括附加到表格的放置策略），请改用 `SHOW PLACEMENT` 语句： +`PLACEMENT_RULES` 表只展示已显式配置的规则。如要查看 Placement Rules 放置规则的规范版本（包括绑定了对象的放置策略），请改用 `SHOW PLACEMENT` 语句： {{< copyable "sql" >}} ```sql CREATE TABLE t1 (a INT); -CREATE TABLE t2 (a INT) primary_region="us-east-1" regions="us-east-1"; CREATE PLACEMENT POLICY p1 primary_region="us-east-1" regions="us-east-1"; -CREATE TABLE t3 (a INT) PLACEMENT POLICY=p1; -SHOW PLACEMENT; -- 包含 t3。 -SELECT * FROM information_schema.placement_rules; -- 不包含 t3。 +CREATE TABLE t2 (a INT) PLACEMENT POLICY=p1; +SHOW PLACEMENT; -- 包含 t2。 +SELECT * FROM information_schema.placement_rules; -- 不包含 t2。 ``` ```sql @@ -66,15 +65,13 @@ Query OK, 0 rows affected (0.11 sec) +---------------+------------------------------------------------+ | POLICY p1 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | | TABLE test.t2 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | -| TABLE test.t3 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | +---------------+------------------------------------------------+ -3 rows in set (0.00 sec) +2 rows in set (0.00 sec) +-----------+--------------+-------------+-------------+------------+----------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+ | POLICY_ID | CATALOG_NAME | POLICY_NAME | SCHEMA_NAME | TABLE_NAME | PARTITION_NAME | PRIMARY_REGION | REGIONS | CONSTRAINTS | LEADER_CONSTRAINTS | FOLLOWER_CONSTRAINTS | LEARNER_CONSTRAINTS | SCHEDULE | FOLLOWERS | LEARNERS | +-----------+--------------+-------------+-------------+------------+----------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+ | 3 | def | p1 | NULL | NULL | NULL | us-east-1 | us-east-1 | | | | | | 0 | 0 | -| NULL | def | NULL | test | t2 | NULL | us-east-1 | us-east-1 | | | | | | 0 | 0 | +-----------+--------------+-------------+-------------+------------+----------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+ 2 rows in set (0.00 sec) ``` diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 62a8d56c1905..d7f4f90f134f 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -11,6 +11,10 @@ summary: 了解如何通过 SQL 接口调度表和分区的放置位置。 Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，用户可以将表和分区指定部署至不同的地域、机房、机柜、主机。适用场景包括低成本优化数据高可用策略、保证本地的数据副本可用于本地 Stale Read 读取、遵守数据本地要求等。 +> **注意：** +> +> Placement Rules in SQL 底层的实现依赖 PD 提供的放置规则 (placement rules) 功能，参考 [Placement Rules 使用文档](/configure-placement-rules.md)。在 Placement Rules in SQL 语境下，放置规则既可以代指绑定对象的放置策略 (placement policy)，也可以代指 TiDB 发给 PD 的放置规则。 + 该功能可以实现以下业务场景： - 合并多个不同业务的数据库，大幅减少数据库常规运维管理的成本 @@ -19,23 +23,51 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 - 把热点数据的 leader 放到高性能的 TiKV 实例上 - 将冷数据分离到不同的存储中以提高可用性 -## 指定放置选项 +## 指定放置规则 + +指定放置规则，首先需要创建放置策略 (placement policy)。 + +```sql +CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; +``` + +然后可以使用 `CREATE TABLE` 或者 `ALTER TABLE` 将规则绑定至表或分区表，这样就在表或分区上指定了放置规则： + +```sql +CREATE TABLE t1 (a INT) PLACEMENT POLICY myplacementpolicy; +CREATE TABLE t2 (a INT); +ALTER TABLE t2 PLACEMENT POLICY myplacementpolicy; +``` + +`PLACEMENT POLICY` 为全局作用域，不与任何数据库表结构相关联。因此，通过 `CREATE TABLE` 指定放置规则时，无需任何额外的权限。 -要使用 Placement Rules in SQL 特性，你需要在 SQL 语句中指定一个或多个放置选项 (placement option)。可通过*直接放置 (direct placement)* 或*放置策略 (placement policy)* 来指定放置选项。 +## 查看放置规则 -以下示例中，表 `t1` 和 `t2` 的放置规则相同。`t1` 是通过直接放置指定的规则，而 `t2` 是通过放置策略来指定的规则。 +如果一张表绑定了放置规则，你可以用 `SHOW CREATE TABLE` 来查看。还可以用 `SHOW CREATE PLACEMENT POLICY` 来查看已经创建的规则。 ```sql -CREATE TABLE t1 (a INT) PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; -CREATE PLACEMENT POLICY eastandwest PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; -CREATE TABLE t2 (a INT) PLACEMENT POLICY=eastandwest; +tidb> 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) +tidb> 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) ``` -为了能够更轻松地管理放置规则，推荐使用放置策略来指定规则。当你通过 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 更改放置策略后，此更改会自动传播至所有数据库对象。 +`information_schema.tables` 表和 `information_schema.partitions` 表也有一列 `tidb_placement_policy_name`，用于展示所有绑定了放置规则的对象： -如果你使用直接放置选项，你需要为每个对象（例如表和分区）都单独更改放置规则。 +```sql +SELECT * FROM information_schema.tables WHERE tidb_placement_policy_name IS NOT NULL; +SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS NOT NULL; +``` -`PLACEMENT POLICY` 为全局作用域，不与任何数据库表结构相关联。因此，通过 `CREATE TABLE` 指定放置策略时，无需任何额外的权限。 +所有绑定规则的对象都是异步调度的。可以用 [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) 来查看放置规则的调度进度。 ## 放置选项参考 @@ -62,7 +94,7 @@ CREATE TABLE t2 (a INT) PLACEMENT POLICY=eastandwest; | `SCHEDULE` | 用于调度 follower 放置位置的策略。可选值为 `EVEN`（默认值）或 `MAJORITY_IN_PRIMARY`。 | | `FOLLOWERS` | Follower 的数量。例如 `FOLLOWERS=2` 表示数据有 3 个副本（2 个 follower 和 1 个 leader）。 | -除以上配置选项外，你还可以使用高级配置，详细介绍见[高级放置](#高级放置)。 +除以上配置选项外，你还可以使用高级配置，详细介绍见[高级放置选项](#高级放置选项)。 | 选项名 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| @@ -99,7 +131,7 @@ CREATE TABLE t1 (a INT) PLACEMENT POLICY=eastandwest; > > 以下示例使用的 List 分区目前为 TiDB 实验特性。在表的分区功能中，要求主键里包含所有分区函数中使用的列。 -除了将放置选项分配给表之外，你还可以将选项分配给表分区。示例如下： +除了给表绑定放置策略之外，你还可以给表分区绑定放置策略。示例如下： ```sql CREATE PLACEMENT POLICY europe PRIMARY_REGION="eu-central-1" REGIONS="eu-central-1,eu-west-1"; @@ -117,25 +149,33 @@ CREATE TABLE t1 ( ### 为数据库配置默认的放置规则 -你可以为某个数据库指定默认的放置选项，类似于为数据库设置默认字符集或排序规则。如果没有指定其他选项，就会使用数据库上指定的配置。示例如下： +你可以为某个数据库指定默认的放置策略，类似于为数据库设置默认字符集或排序规则。如果没有指定其他选项，就会使用数据库上指定的配置。示例如下： ```sql -CREATE TABLE t1 (a INT); -- 创建表 t1，且未指定放置选项。 +CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2"; -- 创建放置策略 + +CREATE PLACEMENT POLICY p2 FOLLOWERS=4; + +CREATE PLACEMENT POLICY p3 FOLLOWERS=2; + +CREATE TABLE t1 (a INT); -- 创建表 t1，且未指定放置规则。 + +ALTER DATABASE test POLICY=p2; -- 更改默认的放置规则，但更改不影响已有的表 t1。 -ALTER DATABASE test FOLLOWERS=4; -- 更改默认的放置选项，但更改不影响已有的表 t1。 +CREATE TABLE t2 (a INT); -- 创建表 t2，默认的放置策略 p2 在 t2 上生效。 -CREATE TABLE t2 (a INT); -- 创建表 t2，默认的放置规则 FOLLOWERS=4 在 t2 上生效。 +CREATE TABLE t3 (a INT) POLICY=p1; -- 创建表 t3。因为语句中已经指定了其他放置规则，默认的 p2 策略在 t3 上不生效。 -CREATE TABLE t3 (a INT) PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2"; -- 创建表 t3。因为语句中已经指定了其他放置规则，默认的 FOLLOWERS=4 规则在 t3 上不生效。 +ALTER DATABASE test POLICY=p3; -- 再次更改默认的放置规则，此更改不影响已有的表。 -ALTER DATABASE test FOLLOWERS=2; -- 再次更改默认的放置选项，此更改不影响已有的表。 +CREATE TABLE t4 (a INT); -- 创建表 t4，默认的放置策略 p3 生效。 -CREATE TABLE t4 (a INT); -- 创建表 t4，默认的放置规则 FOLLOWERS=2 生效。 +ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- 绑定策略 p3 的表，也就是 t4，会采用 FOLLOWERS=3。 ``` -由于只有在创建表时才会从数据库继承放置选项，因此推荐使用 `PLACEMENT POLICY` 放置策略来设置默认的放置选项。使用后，用户可以通过改动放置策略，改变继承自数据库的放置选项。 +用户可以通过使用 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 改变放置策略，从而改变已从数据库继承放置规则的表。 -### 高级放置 +### 高级放置选项 放置选项 `PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 可满足数据放置的基本需求，但会缺乏一些灵活性。在较复杂的场景下，若需要更灵活地放置数据，可以使用高级放置选项 `CONSTRAINTS` 和 `FOLLOWER_CONSTRAINTS`。`PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 选项不可与 `CONSTRAINTS` 选项同时指定，否则会报错。 @@ -173,7 +213,7 @@ PARTITION BY RANGE( YEAR(purchased) ) ( * Dumpling 不支持导出放置策略，见 [issue #29371](https://github.com/pingcap/tidb/issues/29371)。 * TiDB 生态工具，包括 Backup & Restore (BR)、TiCDC、TiDB Lightning 和 TiDB Data Migration (DM)，不支持放置规则。 -* 临时表不支持放置选项，直接放置和放置策略均不支持。 +* 临时表不支持放置规则。 * 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 * 不能通过放置规则语法配置 TiFlash 副本。 * 放置规则仅保证静态数据被放置在正确的 TiKV 节点上。该规则不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 diff --git a/sql-statements/sql-statement-alter-placement-policy.md b/sql-statements/sql-statement-alter-placement-policy.md index 21c9b8a1992e..5c680543fdb3 100644 --- a/sql-statements/sql-statement-alter-placement-policy.md +++ b/sql-statements/sql-statement-alter-placement-policy.md @@ -9,7 +9,14 @@ summary: TiDB 数据库中 ALTER PLACEMENT POLICY 的使用概况。 > > Placement Rules in SQL 是 TiDB 在 v5.3.0 中引入的实验特性，其语法在 GA 前可能会发生变化，还可能存在 bug。如果你知晓潜在的风险，可通过执行 `SET GLOBAL tidb_enable_alter_placement = 1;` 来开启该实验特性。 -`ALTER PLACEMENT POLICY` 用于修改已创建的放置策略。此修改会自动更新至所有使用这些放置策略的表和分区。 +`ALTER PLACEMENT POLICY` 用于修改已创建的放置策略。此修改会自动更新至所有绑定这些放置策略的表和分区。 + +`ALTER PLACEMENT POLICY` 会完全替换之前定义的规则，而不会和之前的规则合并，比如在下面的例子中，`FOLLOWERS=4` 就被 `ALTER PLACEMENT POLICY` 语句覆盖了： + +```sql +CREATE PLACEMENT POLICY p1 FOLLOWERS=4; +ALTER PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; +``` ## 语法图 @@ -21,11 +28,11 @@ PolicyName ::= Identifier PlacementOptionList ::= - DirectPlacementOption -| PlacementOptionList DirectPlacementOption -| PlacementOptionList ',' DirectPlacementOption + PlacementOption +| PlacementOptionList PlacementOption +| PlacementOptionList ',' PlacementOption -DirectPlacementOption ::= +PlacementOption ::= "PRIMARY_REGION" EqOpt stringLit | "REGIONS" EqOpt stringLit | "FOLLOWERS" EqOpt LengthNum diff --git a/sql-statements/sql-statement-create-placement-policy.md b/sql-statements/sql-statement-create-placement-policy.md index 692a1fac441c..4b91f2db4895 100644 --- a/sql-statements/sql-statement-create-placement-policy.md +++ b/sql-statements/sql-statement-create-placement-policy.md @@ -9,7 +9,7 @@ summary: TiDB 数据库中 CREATE PLACEMENT POLICY 的使用概况。 > > Placement Rules in SQL 是 TiDB 在 v5.3.0 中引入的实验特性，其语法在 GA 前可能会发生变化，还可能存在 bug。如果你知晓潜在的风险，可通过执行 `SET GLOBAL tidb_enable_alter_placement = 1;` 来开启该实验特性。 -`CREATE PLACEMENT POLICY` 用于创建命名的放置策略，随后可以将该策略分配给表、分区或数据库。 +`CREATE PLACEMENT POLICY` 用于创建命名的放置策略，随后可以将该策略绑定到表、分区或数据库上。 ## 语法图 @@ -21,11 +21,11 @@ PolicyName ::= Identifier PlacementOptionList ::= - DirectPlacementOption -| PlacementOptionList DirectPlacementOption -| PlacementOptionList ',' DirectPlacementOption + PlacementOption +| PlacementOptionList PlacementOption +| PlacementOptionList ',' PlacementOption -DirectPlacementOption ::= +PlacementOption ::= "PRIMARY_REGION" EqOpt stringLit | "REGIONS" EqOpt stringLit | "FOLLOWERS" EqOpt LengthNum diff --git a/sql-statements/sql-statement-drop-placement-policy.md b/sql-statements/sql-statement-drop-placement-policy.md index 6568c3e9b158..8e2f28ae5ed4 100644 --- a/sql-statements/sql-statement-drop-placement-policy.md +++ b/sql-statements/sql-statement-drop-placement-policy.md @@ -23,20 +23,20 @@ PolicyName ::= ## 示例 -删除放置策略时，确保该策略未被任何表或分区引用，否则会删除失败。 +删除放置规则时，确保该策略未被任何表或分区引用，否则会删除失败。 {{< copyable "sql" >}} ```sql CREATE PLACEMENT POLICY p1 FOLLOWERS=4; CREATE TABLE t1 (a INT PRIMARY KEY) PLACEMENT POLICY=p1; -DROP PLACEMENT POLICY p1; -- 该语句执行失败，因为放置策略 p1 被引用。 +DROP PLACEMENT POLICY p1; -- 该语句执行失败，因为放置规则 p1 被引用。 --- 查看引用放置策略的表和分区。 +-- 查看引用放置规则的表和分区。 SELECT table_schema, table_name FROM information_schema.tables WHERE tidb_placement_policy_name='p1'; SELECT table_schema, table_name FROM information_schema.partitions WHERE tidb_placement_policy_name='p1'; -ALTER TABLE t1 PLACEMENT POLICY=default; -- 移除表 t1 上的默认放置策略。 +ALTER TABLE t1 PLACEMENT POLICY=default; -- 移除表 t1 上的默认放置规则。 DROP PLACEMENT POLICY p1; -- 执行成功。 ``` diff --git a/sql-statements/sql-statement-show-create-placement-policy.md b/sql-statements/sql-statement-show-create-placement-policy.md index cf46b823fb08..facb9df5f1dd 100644 --- a/sql-statements/sql-statement-show-create-placement-policy.md +++ b/sql-statements/sql-statement-show-create-placement-policy.md @@ -9,7 +9,7 @@ summary: TiDB 数据库中 SHOW CREATE PLACEMENT POLICY 的使用概况。 > > Placement Rules in SQL 是 TiDB 在 v5.3.0 中引入的实验特性，其语法在 GA 前可能会发生变化，还可能存在 bug。如果你知晓潜在的风险，可通过执行 `SET GLOBAL tidb_enable_alter_placement = 1;` 来开启该实验特性。 -`SHOW CREATE PLACEMENT POLICY` 语句可用于查看放置策略当前的定义，并在另一个 TiDB 集群中重新创建该策略。 +`SHOW CREATE PLACEMENT POLICY` 语句可用于查看放置规则当前的定义，并在另一个 TiDB 集群中重新创建该策略。 ## 语法图 diff --git a/sql-statements/sql-statement-show-placement-for.md b/sql-statements/sql-statement-show-placement-for.md index 3a6e6e12aa39..6feeba781ba9 100644 --- a/sql-statements/sql-statement-show-placement-for.md +++ b/sql-statements/sql-statement-show-placement-for.md @@ -9,7 +9,13 @@ summary: TiDB 数据库中 SHOW PLACEMENT FOR 的使用概况。 > > Placement Rules in SQL 是 TiDB 在 v5.3.0 中引入的实验特性，其语法在 GA 前可能会发生变化，还可能存在 bug。如果你知晓潜在的风险，可通过执行 `SET GLOBAL tidb_enable_alter_placement = 1;` 来开启该实验特性。 -`SHOW PLACEMENT FOR` 用于汇总直接放置 (direct placement) 和放置策略 (placement policy) 中所有的放置选项，并为特定表、数据库或分区以规范形式呈现这些选项信息。 +`SHOW PLACEMENT FOR` 用于汇总所有放置策略 (placement policy) ，并用统一的形式呈现特定表、数据库或分区的信息。 + +本语句返回结果中的 `Scheduling_State` 列标识了 Placement Driver (PD) 在当前对象上的调度进度，有以下可能的结果： + +* `PENDING`: PD 没有进行调度。可能的原因之一是放置规则虽然语法上正确，但集群拓扑并不满足。比如指定 `FOLLOWERS=4` 但只有 3 个可用作 follower 的 TiKV 实例。 +* `INPROGRESS`: PD 正在进行调度。 +* `SCHEDULED`: PD 调度完成。 ## 语法图 @@ -32,14 +38,11 @@ CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west use test; ALTER DATABASE test PLACEMENT POLICY=p1; CREATE TABLE t1 (a INT); -CREATE TABLE t2 (a INT) PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4; SHOW PLACEMENT FOR DATABASE test; SHOW PLACEMENT FOR TABLE t1; SHOW CREATE TABLE t1\G -SHOW PLACEMENT FOR TABLE t2; -CREATE TABLE t3 (a INT) PARTITION BY RANGE (a) (PARTITION p1 VALUES LESS THAN (10), PARTITION p2 VALUES LESS THAN (20) FOLLOWERS=4); +CREATE TABLE t3 (a INT) PARTITION BY RANGE (a) (PARTITION p1 VALUES LESS THAN (10), PARTITION p2 VALUES LESS THAN (20)); SHOW PLACEMENT FOR TABLE t3 PARTITION p1; -SHOW PLACEMENT FOR TABLE t3 PARTITION p2; ``` ```sql @@ -72,28 +75,12 @@ Create Table: CREATE TABLE `t1` ( ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin /*T![placement] PLACEMENT POLICY=`p1` */ 1 row in set (0.00 sec) -+---------------+----------------------------------------------------------------------+------------------+ -| Target | Placement | Scheduling_State | -+---------------+----------------------------------------------------------------------+------------------+ -| TABLE test.t2 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4 | INPROGRESS | -+---------------+----------------------------------------------------------------------+------------------+ -1 row in set (0.00 sec) - -Query OK, 0 rows affected (0.14 sec) - +----------------------------+-----------------------------------------------------------------------+------------------+ | Target | Placement | Scheduling_State | +----------------------------+-----------------------------------------------------------------------+------------------+ | TABLE test.t3 PARTITION p1 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1,,us-west-1" FOLLOWERS=4 | INPROGRESS | +----------------------------+-----------------------------------------------------------------------+------------------+ 1 row in set (0.00 sec) - -+----------------------------+-------------+------------------+ -| Target | Placement | Scheduling_State | -+----------------------------+-------------+------------------+ -| TABLE test.t3 PARTITION p2 | FOLLOWERS=4 | INPROGRESS | -+----------------------------+-------------+------------------+ -1 row in set (0.00 sec) ``` ## MySQL 兼容性 diff --git a/sql-statements/sql-statement-show-placement.md b/sql-statements/sql-statement-show-placement.md index 85bdac083c76..0c9797aa1be8 100644 --- a/sql-statements/sql-statement-show-placement.md +++ b/sql-statements/sql-statement-show-placement.md @@ -9,7 +9,13 @@ summary: TiDB 数据库中 SHOW PLACEMENT 的使用概况。 > > Placement Rules in SQL 是 TiDB 在 v5.3.0 中引入的实验特性，其语法在 GA 前可能会发生变化，还可能存在 bug。如果你知晓潜在的风险，可通过执行 `SET GLOBAL tidb_enable_alter_placement = 1;` 来开启该实验特性。 -`SHOW PLACEMENT` 汇总了直接放置 (direct placement) 和放置策略 (placement policy) 中的所有放置选项，并以规范的形式呈现这些选项信息。 +`SHOW PLACEMENT` 汇总了所有放置策略 (placement policy) ，并用统一的形式呈现相关信息。 + +本语句返回结果中的 `Scheduling_State` 列标识了 Placement Driver (PD) 在当前对象上的调度进度，有以下可能结果： + +* `PENDING`: PD 没有进行调度。可能的原因之一是放置规则虽然语法上正确，但集群拓扑并不满足。比如指定 `FOLLOWERS=4` 但只有 3 个可用作 follower 的 TiKV 实例。 +* `INPROGRESS`: PD 正在进行调度。 +* `SCHEDULED`: PD 调度完成。 ## 语法图 @@ -25,7 +31,6 @@ ShowStmt ::= ```sql CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4; CREATE TABLE t1 (a INT) PLACEMENT POLICY=p1; -CREATE TABLE t2 (a INT) PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4; SHOW PLACEMENT; ``` @@ -34,15 +39,12 @@ Query OK, 0 rows affected (0.01 sec) Query OK, 0 rows affected (0.00 sec) -Query OK, 0 rows affected (0.00 sec) - +---------------+----------------------------------------------------------------------+------------------+ | Target | Placement | Scheduling_State | +---------------+----------------------------------------------------------------------+------------------+ | POLICY p1 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4 | NULL | | DATABASE test | PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4 | INPROGRESS | | TABLE test.t1 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4 | INPROGRESS | -| TABLE test.t2 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4 | INPROGRESS | +---------------+----------------------------------------------------------------------+------------------+ 4 rows in set (0.00 sec) ```