diff --git a/TOC.md b/TOC.md index a238905c9ec09..c8b23709cf798 100644 --- a/TOC.md +++ b/TOC.md @@ -585,7 +585,7 @@ - [`METRICS_SUMMARY`](/information-schema/information-schema-metrics-summary.md) - [`METRICS_TABLES`](/information-schema/information-schema-metrics-tables.md) - [`PARTITIONS`](/information-schema/information-schema-partitions.md) - - [`PLACEMENT_RULES`](/information-schema/information-schema-placement-rules.md) + - [`PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md) - [`PROCESSLIST`](/information-schema/information-schema-processlist.md) - [`REFERENTIAL_CONSTRAINTS`](/information-schema/information-schema-referential-constraints.md) - [`SCHEMATA`](/information-schema/information-schema-schemata.md) diff --git a/br/backup-and-restore-tool.md b/br/backup-and-restore-tool.md index 4bf4480bcff23..4ec4e973f1d67 100644 --- a/br/backup-and-restore-tool.md +++ b/br/backup-and-restore-tool.md @@ -132,6 +132,8 @@ The compatibility issues of BR and the TiDB cluster are divided into the followi + BR versions earlier than v5.4.0 do not support recovering `charset=GBK` tables. No version of BR supports recovering `charset=GBK` tables to TiDB clusters earlier than v5.4.0. + + BR does not support [placement rules](/placement-rules-in-sql.md) before v6.0.0. Since v6.0.0, BR supports placement rules and introduces a command-line option `--with-tidb-placement-mode=strict/ignore` to control the backup and restore mode of placement rules. With the default value `strict`, BR imports and validates placement rules, but ignores all placement rules when the value is `ignore`. + + The KV format might change when some features are enabled or disabled. If these features are not consistently enabled or disabled during backup and restore, compatibility issues might occur. These features are as follows: diff --git a/information-schema/information-schema-placement-policies.md b/information-schema/information-schema-placement-policies.md new file mode 100644 index 0000000000000..19aae3f6b0c90 --- /dev/null +++ b/information-schema/information-schema-placement-policies.md @@ -0,0 +1,73 @@ +--- +title: PLACEMENT_POLICIES +summary: Learn the `PLACEMENT_POLICIES` information_schema table. +aliases: ['/tidb/dev/information-schema-placement-rules'] +--- + +# PLACEMENT_POLICIES + +The `PLACEMENT_POLICIES` table provides information on all placement policies. For details, refer to [Placement Rules in SQL](/placement-rules-in-sql.md). + +{{< copyable "sql" >}} + +```sql +USE information_schema; +DESC placement_policies; +``` + +```sql ++----------------------+---------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++----------------------+---------------+------+-----+---------+-------+ +| POLICY_ID | bigint(64) | NO | | | | +| CATALOG_NAME | varchar(512) | NO | | | | +| POLICY_NAME | varchar(64) | NO | | | | +| PRIMARY_REGION | varchar(1024) | YES | | | | +| REGIONS | varchar(1024) | YES | | | | +| CONSTRAINTS | varchar(1024) | YES | | | | +| LEADER_CONSTRAINTS | varchar(1024) | YES | | | | +| FOLLOWER_CONSTRAINTS | varchar(1024) | YES | | | | +| LEARNER_CONSTRAINTS | varchar(1024) | YES | | | | +| SCHEDULE | varchar(20) | YES | | | | +| FOLLOWERS | bigint(64) | YES | | | | +| LEARNERS | bigint(64) | YES | | | | ++----------------------+---------------+------+-----+---------+-------+ +12 rows in set (0.00 sec) +``` + +## Examples + +The `PLACEMENT_POLICIES` table only shows all placement policies. To view the canonical version of placement rules (including all placement policies and objects assigned placement policies), use the statement `SHOW PLACEMENT` instead: + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (a INT); +CREATE PLACEMENT POLICY p1 primary_region="us-east-1" regions="us-east-1"; +CREATE TABLE t3 (a INT) PLACEMENT POLICY=p1; +SHOW PLACEMENT; -- Shows all information, including table t3. +SELECT * FROM information_schema.placement_policies; -- Only shows placement policies, excluding t3. +``` + +```sql +Query OK, 0 rows affected (0.09 sec) + +Query OK, 0 rows affected (0.11 sec) + +Query OK, 0 rows affected (0.08 sec) + ++---------------+------------------------------------------------+------------------+ +| Target | Placement | Scheduling_State | ++---------------+------------------------------------------------+------------------+ +| POLICY p1 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | NULL | +| TABLE test.t3 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | PENDING | ++---------------+------------------------------------------------+------------------+ +2 rows in set (0.00 sec) + ++-----------+--------------+-------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+ +| POLICY_ID | CATALOG_NAME | POLICY_NAME | PRIMARY_REGION | REGIONS | CONSTRAINTS | LEADER_CONSTRAINTS | FOLLOWER_CONSTRAINTS | LEARNER_CONSTRAINTS | SCHEDULE | FOLLOWERS | LEARNERS | ++-----------+--------------+-------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+ +| 1 | def | p1 | us-east-1 | us-east-1 | | | | | | 2 | 0 | ++-----------+--------------+-------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+ +1 rows in set (0.00 sec) +``` diff --git a/information-schema/information-schema-placement-rules.md b/information-schema/information-schema-placement-rules.md deleted file mode 100644 index 83d0c43f12299..0000000000000 --- a/information-schema/information-schema-placement-rules.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: PLACEMENT_RULES -summary: Learn the `PLACEMENT_RULES` information_schema table. ---- - -# PLACEMENT_RULES - -The `PLACEMENT_RULES` table provides information on all explicitly configured [Placement Rules in SQL](/placement-rules-in-sql.md), which means all placement policies. - -{{< copyable "sql" >}} - -```sql -USE information_schema; -DESC placement_rules; -``` - -```sql -+----------------------+--------------+------+------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+----------------------+--------------+------+------+---------+-------+ -| POLICY_ID | bigint(64) | NO | | NULL | | -| CATALOG_NAME | varchar(512) | NO | | NULL | | -| POLICY_NAME | varchar(5) | YES | | NULL | | -| SCHEMA_NAME | varchar(5) | YES | | NULL | | -| TABLE_NAME | varchar(5) | YES | | NULL | | -| PARTITION_NAME | varchar(5) | YES | | NULL | | -| PRIMARY_REGION | varchar(5) | NO | | NULL | | -| REGIONS | varchar(5) | NO | | NULL | | -| CONSTRAINTS | varchar(5) | NO | | NULL | | -| LEADER_CONSTRAINTS | varchar(5) | NO | | NULL | | -| FOLLOWER_CONSTRAINTS | varchar(5) | NO | | NULL | | -| LEARNER_CONSTRAINTS | varchar(5) | NO | | NULL | | -| SCHEDULE | varchar(20) | NO | | NULL | | -| FOLLOWERS | bigint(64) | NO | | NULL | | -| LEARNERS | bigint(64) | NO | | NULL | | -+----------------------+--------------+------+------+---------+-------+ -15 rows in set (0.00 sec) -``` - -## Examples - -The `PLACEMENT_RULES` table only shows explicitly configured rules. To see the canonical version of placement rules (including placement policies attached to tables), use the statement `SHOW PLACEMENT` instead: - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT); -CREATE PLACEMENT POLICY p1 primary_region="us-east-1" regions="us-east-1"; -CREATE TABLE t2 (a INT) PLACEMENT POLICY=p1; -SHOW PLACEMENT; -- Includes t2. -SELECT * FROM information_schema.placement_rules; -- Does not include t2. -``` - -```sql -Query OK, 0 rows affected (0.09 sec) - -Query OK, 0 rows affected (0.11 sec) - -Query OK, 0 rows affected (0.08 sec) - -Query OK, 0 rows affected (0.11 sec) - -+---------------+------------------------------------------------+ -| Target | Placement | -+---------------+------------------------------------------------+ -| POLICY p1 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | -| TABLE test.t2 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | -+---------------+------------------------------------------------+ -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 | -+-----------+--------------+-------------+-------------+------------+----------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+ -2 rows in set (0.00 sec) -``` diff --git a/information-schema/information-schema.md b/information-schema/information-schema.md index a886bb829c54a..f36baae720f6c 100644 --- a/information-schema/information-schema.md +++ b/information-schema/information-schema.md @@ -76,7 +76,7 @@ Many `INFORMATION_SCHEMA` tables have a corresponding `SHOW` command. The benefi | [`METRICS_SUMMARY`](/information-schema/information-schema-metrics-summary.md) | A summary of metrics extracted from Prometheus. | | `METRICS_SUMMARY_BY_LABEL` | See `METRICS_SUMMARY` table. | | [`METRICS_TABLES`](/information-schema/information-schema-metrics-tables.md) | Provides the PromQL definitions for tables in `METRICS_SCHEMA`. | -| [`PLACEMENT_RULES`](/information-schema/information-schema-placement-rules.md) | Provides information on all objects that have explicit placement rules assigned. | +| [`PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md) | Provides information on all placement policies. | | [`SEQUENCES`](/information-schema/information-schema-sequences.md) | The TiDB implementation of sequences is based on MariaDB. | | [`SLOW_QUERY`](/information-schema/information-schema-slow-query.md) | Provides information on slow queries on the current TiDB server. | | [`STATEMENTS_SUMMARY`](/statement-summary-tables.md) | Similar to performance_schema statement summary in MySQL. | diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 6a966702ec4c6..f891b0c8f6067 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -9,7 +9,7 @@ summary: Learn how to schedule placement of tables and partitions using SQL stat > > Placement Rules in SQL is an experimental feature introduced in v5.3.0. The syntax might change before its GA, and there might also be bugs. If you understand the risks, you can enable this experiment feature by executing `SET GLOBAL tidb_enable_alter_placement = 1;`. -> **Noteļ¼š** +> **Note:** > > The implementation of *Placement Rules in SQL* relies on the *placement rules feature* of PD. For details, refer to [Configure Placement Rules](/configure-placement-rules.md). In the context of Placement Rules in SQL, *placement rules* might refer to *placement policies* attached to other objects, or to rules that are sent from TiDB to PD. @@ -25,7 +25,7 @@ The detailed user scenarios are as follows: ## Specify placement rules -To specify placement rules, first create a placement policy: +To specify placement rules, first create a placement policy using [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md): ```sql CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; @@ -34,16 +34,28 @@ CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us Then attach the policy to a table or partition using either `CREATE TABLE` or `ALTER TABLE`. Then, the placement rules are specified on the table or the partition: ```sql -CREATE TABLE t1 (a INT) PLACEMENT POLICY myplacementpolicy; +CREATE TABLE t1 (a INT) PLACEMENT POLICY=myplacementpolicy; CREATE TABLE t2 (a INT); -ALTER TABLE t2 PLACEMENT POLICY myplacementpolicy; +ALTER TABLE t2 PLACEMENT POLICY=myplacementpolicy; ``` A placement policy is not associated with any database schema and has the global scope. Therefore, assigning a placement policy does not require any additional privileges over the `CREATE TABLE` privilege. +To modify a placement policy, you can use [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md), and the changes will propagate to all objects assigned with the corresponding policy. + +```sql +ALTER PLACEMENT POLICY myplacementpolicy FOLLOWERS=5; +``` + +To drop policies that are not attached to any table or partition, you can use [`DROP PLACEMENT POLICY`](/sql-statements/sql-statement-drop-placement-policy.md): + +```sql +DROP PLACEMENT POLICY myplacementpolicy; +``` + ## View current placement rules -If a table has placement rules attached, you can view the placement rules in the output of `SHOW CREATE TABLE`. To view the definition of the policy available, execute `SHOW CREATE PLACEMENT POLICY`: +If a table has placement rules attached, you can view the placement rules in the output of [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md). To view the definition of the policy available, execute [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md): ```sql tidb> SHOW CREATE TABLE t1\G @@ -61,6 +73,26 @@ Create Policy: CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east 1 row in set (0.00 sec) ``` +You can also view definitions of placement policies using the [`INFORMATION_SCHEMA.PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md) table. + +```sql +tidb> 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 +``` + The `information_schema.tables` and `information_schema.partitions` tables also include a column for `tidb_placement_policy_name`, which shows all objects with placement rules attached: ```sql @@ -68,7 +100,7 @@ SELECT * FROM information_schema.tables WHERE tidb_placement_policy_name IS NOT SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS NOT NULL; ``` -Rules that are attached to objects are applied _asynchronously_. To view the current scheduling progress of placement, use [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md). +Rules that are attached to objects are applied *asynchronously*. To view the current scheduling progress of placement, use [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md). ## Option reference @@ -99,8 +131,11 @@ In addition to the placement options above, you can also use the advance configu | Option Name | Description | | --------------| ------------ | -| `CONSTRAINTS` | A list of constraints that apply to all roles. For example, `CONSTRAINTS="[+disk=ssd]`. | -| `FOLLOWER_CONSTRAINTS` | A list of constraints that only apply to followers. | +| `CONSTRAINTS` | A list of constraints that apply to all roles. For example, `CONSTRAINTS="[+disk=ssd]`. | +| `LEADER_CONSTRAINTS` | A list of constraints that only apply to leader. | +| `FOLLOWER_CONSTRAINTS` | A list of constraints that only apply to followers. | +| `LEARNER_CONSTRAINTS` | A list of constraints that only apply to learners. | +| `LEARNERS` | The number of learners. | ## Examples @@ -135,6 +170,7 @@ To ensure that enough followers are placed in the primary region (`us-east-1`) s In addition to assigning placement options to tables, you can also assign the options to table partitions. For example: ```sql +CREATE PLACEMENT POLICY p1 FOLLOWERS=5; CREATE PLACEMENT POLICY europe PRIMARY_REGION="eu-central-1" REGIONS="eu-central-1,eu-west-1"; CREATE PLACEMENT POLICY northamerica PRIMARY_REGION="us-east-1" REGIONS="us-east-1"; @@ -142,12 +178,15 @@ SET tidb_enable_list_partition = 1; CREATE TABLE t1 ( country VARCHAR(10) NOT NULL, userdata VARCHAR(100) NOT NULL -) PARTITION BY LIST COLUMNS (country) ( +) PLACEMENT POLICY=p1 PARTITION BY LIST COLUMNS (country) ( PARTITION pEurope VALUES IN ('DE', 'FR', 'GB') PLACEMENT POLICY=europe, PARTITION pNorthAmerica VALUES IN ('US', 'CA', 'MX') PLACEMENT POLICY=northamerica + PARTITION pAsia VALUES IN ('CN', 'KR', 'JP') ); ``` +If a partition has no attached policies, it tries to apply possibly existing policies on the table. For example, the `pEurope` partition will apply the `europe` policy, but the `pAsia` partition will apply the `p1` policy from table `t1`. If `t1` has no assigned policies, `pAsia` will not apply any policy, too. + ### Set the default placement for a schema You can directly attach the default placement rules to a database schema. This works similar to setting the default character set or collation for a schema. Your specified placement options apply when no other options are specified. For example: @@ -174,7 +213,7 @@ CREATE TABLE t4 (a INT); -- Creates a table t4 with the default policy p3. ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- The table with policy p3 (t4) will have FOLLOWERS=3. ``` -You can use [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) to change a policy, and the changes will propagate to all objects with the corresponding policy. +Note that this is different from the inheritance between partitions and tables, where changing the policy of tables will affect their partitions. Tables inherit the policy of schema only when they are created without policies attached, and modifying the policies of schemas does not affect created tables. ### Advanced placement options @@ -208,12 +247,19 @@ In dictionary format, constraints also indicate a number of instances that apply > > Dictionary and list formats are based on the YAML parser, but the YAML syntax might be incorrectly parsed. For example, `"{+disk=ssd:1,+disk=hdd:2}"` is incorrectly parsed as `'{"+disk=ssd:1": null, "+disk=hdd:1": null}'`. But `"{+disk=ssd: 1,+disk=hdd: 1}"` is correctly parsed as `'{"+disk=ssd": 1, "+disk=hdd": 1}'`. +## Compatibility with tools + +| Tool Name | Minimum supported version | Description | +| --- | --- | --- | +| Backup & Restore (BR) | 6.0 | Supports importing and exporting placement rules. Refer to [BR Compatibility](/br/backup-and-restore-tool.md#compatibility] for details. | +| TiDB Lightning | Not compatible yet | | +| TiCDC | 6.0 | Ignores placement rules, and does not replicate the rules to the downstream | +| TiDB Binlog | 6.0 | Ignores placement rules, and does not replicate the rules to the downstream | + ## Known limitations The following known limitations exist in the experimental release of Placement Rules in SQL: -* Dumpling does not support dumping placement policies. See [issue #29371](https://github.com/pingcap/tidb/issues/29371). -* TiDB tools, including Backup & Restore (BR), TiCDC, TiDB Lightning, and TiDB Data Migration (DM), do not yet support placement rules. * Temporary tables do not support placement options. * Syntactic sugar rules are permitted for setting `PRIMARY_REGION` and `REGIONS`. In the future, we plan to add varieties for `PRIMARY_RACK`, `PRIMARY_ZONE`, and `PRIMARY_HOST`. See [issue #18030](https://github.com/pingcap/tidb/issues/18030). * TiFlash learners are not configurable through Placement Rules syntax. diff --git a/sql-statements/sql-statement-alter-placement-policy.md b/sql-statements/sql-statement-alter-placement-policy.md index d6983ba3ea7c4..e27bc872a6f20 100644 --- a/sql-statements/sql-statement-alter-placement-policy.md +++ b/sql-statements/sql-statement-alter-placement-policy.md @@ -11,15 +11,10 @@ summary: The usage of ALTER PLACEMENT POLICY in TiDB. > > If you understand the risks, you can enable this experiment feature by executing `SET GLOBAL tidb_enable_alter_placement = 1;`. -`ALTER PLACEMENT POLICY` is used to modify existing placement policies that have previously been created. All the tables and partitions which use the placement policy will automatically be updated. +`ALTER PLACEMENT POLICY` is used to modify existing placement policies that have previously been created. All the tables and partitions attached with this placement policy will automatically be updated. `ALTER PLACEMENT POLICY` _replaces_ the previous policy with the new definition. It does not _merge_ the old policy with the new one. In the following example, `FOLLOWERS=4` is lost when the `ALTER PLACEMENT POLICY` is executed: -```sql -CREATE PLACEMENT POLICY p1 FOLLOWERS=4; -ALTER PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; -``` - ## Synopsis ```ebnf+diagram @@ -35,16 +30,23 @@ PlacementOptionList ::= | PlacementOptionList ',' PlacementOption PlacementOption ::= + CommonPlacementOption +| SugarPlacementOption +| AdvancedPlacementOption + +CommonPlacementOption ::= + "FOLLOWERS" EqOpt LengthNum + +SugarPlacementOption ::= "PRIMARY_REGION" EqOpt stringLit | "REGIONS" EqOpt stringLit -| "FOLLOWERS" EqOpt LengthNum -| "VOTERS" EqOpt LengthNum -| "LEARNERS" EqOpt LengthNum | "SCHEDULE" EqOpt stringLit + +AdvancedPlacementOption ::= + "LEARNERS" EqOpt LengthNum | "CONSTRAINTS" EqOpt stringLit | "LEADER_CONSTRAINTS" EqOpt stringLit | "FOLLOWER_CONSTRAINTS" EqOpt stringLit -| "VOTER_CONSTRAINTS" EqOpt stringLit | "LEARNER_CONSTRAINTS" EqOpt stringLit ``` @@ -60,8 +62,9 @@ PlacementOption ::= ```sql CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; -ALTER PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1,us-west-2" FOLLOWERS=4; -SHOW CREATE PLACEMENT POLICY p1\G +CREATE TABLE t1 (i INT) PLACEMENT POLICY=p1; -- Assign policy p1 to table t1 +ALTER PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1,us-west-2" FOLLOWERS=4; -- The rules of t1 will be updated automatically. +SHOW CREATE PLACEMENT POLICY p1\G; ``` ``` @@ -69,9 +72,9 @@ Query OK, 0 rows affected (0.08 sec) Query OK, 0 rows affected (0.10 sec) -*************************** 1. row *************************** - Policy: p1 -Create Policy: CREATE PLACEMENT POLICY `p1` PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1,us-west-2" FOLLOWERS=4 +***************************[ 1. row ]*************************** +Policy | p1 +Create Policy | CREATE PLACEMENT POLICY `p1` PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1,us-west-2" FOLLOWERS=4 1 row in set (0.00 sec) ``` @@ -84,4 +87,4 @@ This statement is a TiDB extension to MySQL syntax. * [Placement Rules in SQL](/placement-rules-in-sql.md) * [SHOW PLACEMENT](/sql-statements/sql-statement-show-placement.md) * [CREATE PLACEMENT POLICY](/sql-statements/sql-statement-create-placement-policy.md) -* [DROP PLACEMENT POLICY](/sql-statements/sql-statement-drop-placement-policy.md) \ No newline at end of file +* [DROP PLACEMENT POLICY](/sql-statements/sql-statement-drop-placement-policy.md) diff --git a/sql-statements/sql-statement-create-placement-policy.md b/sql-statements/sql-statement-create-placement-policy.md index bd0344ab784e7..4a44c1189f426 100644 --- a/sql-statements/sql-statement-create-placement-policy.md +++ b/sql-statements/sql-statement-create-placement-policy.md @@ -28,16 +28,23 @@ PlacementOptionList ::= | PlacementOptionList ',' PlacementOption PlacementOption ::= + CommonPlacementOption +| SugarPlacementOption +| AdvancedPlacementOption + +CommonPlacementOption ::= + "FOLLOWERS" EqOpt LengthNum + +SugarPlacementOption ::= "PRIMARY_REGION" EqOpt stringLit | "REGIONS" EqOpt stringLit -| "FOLLOWERS" EqOpt LengthNum -| "VOTERS" EqOpt LengthNum -| "LEARNERS" EqOpt LengthNum | "SCHEDULE" EqOpt stringLit + +AdvancedPlacementOption ::= + "LEARNERS" EqOpt LengthNum | "CONSTRAINTS" EqOpt stringLit | "LEADER_CONSTRAINTS" EqOpt stringLit | "FOLLOWER_CONSTRAINTS" EqOpt stringLit -| "VOTER_CONSTRAINTS" EqOpt stringLit | "LEARNER_CONSTRAINTS" EqOpt stringLit ``` diff --git a/sql-statements/sql-statement-show-create-placement-policy.md b/sql-statements/sql-statement-show-create-placement-policy.md index 96c90202b66dc..2ab8151b8d22f 100644 --- a/sql-statements/sql-statement-show-create-placement-policy.md +++ b/sql-statements/sql-statement-show-create-placement-policy.md @@ -30,7 +30,7 @@ PolicyName ::= ```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; -SHOW CREATE PLACEMENT POLICY p1\G +SHOW CREATE PLACEMENT POLICY p1\G; ``` ``` @@ -38,9 +38,9 @@ Query OK, 0 rows affected (0.08 sec) Query OK, 0 rows affected (0.10 sec) -*************************** 1. row *************************** - Policy: p1 -Create Policy: CREATE PLACEMENT POLICY `p1` PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4 +***************************[ 1. row ]*************************** +Policy | p1 +Create Policy | CREATE PLACEMENT POLICY `p1` PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4 1 row in set (0.00 sec) ``` diff --git a/sql-statements/sql-statement-show-placement-for.md b/sql-statements/sql-statement-show-placement-for.md index 31b36461df439..758eabff86345 100644 --- a/sql-statements/sql-statement-show-placement-for.md +++ b/sql-statements/sql-statement-show-placement-for.md @@ -37,14 +37,13 @@ ShowPlacementTarget ::= ```sql CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4; -use test; ALTER DATABASE test PLACEMENT POLICY=p1; CREATE TABLE t1 (a INT); SHOW PLACEMENT FOR DATABASE test; SHOW PLACEMENT FOR TABLE t1; -SHOW CREATE TABLE t1\G +SHOW CREATE TABLE t1\G; 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 p1\G; ``` ``` @@ -52,8 +51,6 @@ Query OK, 0 rows affected (0.02 sec) Query OK, 0 rows affected (0.00 sec) -Query OK, 0 rows affected (0.00 sec) - Query OK, 0 rows affected (0.01 sec) +---------------+----------------------------------------------------------------------+------------------+ @@ -70,18 +67,17 @@ Query OK, 0 rows affected (0.01 sec) +---------------+-------------+------------------+ 1 row in set (0.00 sec) -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( +***************************[ 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=`p1` */ 1 row in set (0.00 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 ]*************************** +Target | TABLE test.t3 PARTITION p1 +Placement | PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" FOLLOWERS=4 +Scheduling_State | PENDING 1 row in set (0.00 sec) ``` diff --git a/system-variables.md b/system-variables.md index 3c80b670ee7c7..d0d4ae2d38344 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1410,6 +1410,14 @@ explain select * from t where age=5; - Default value: `ON` - This variable controls whether to enable the [ANALYZE configuration persistence](/statistics.md#persist-analyze-configurations) feature. +### tidb_placement_mode (New in v6.0.0) + +- Scope: SESSION | GLOBAL +- Default value: `STRICT` +- Possible values: `STRICT`, `IGNORE` +- This variable controls whether DDL statements ignore the [placement rules specified in SQL](/placement-rules-in-sql.md). When the variable value is `IGNORE`, all placement rule options are ignored. +- It is intended to be used by logical dump/restore tools to ensure that tables can always be created even if invalid placement rules are assigned. This is similar to how mysqldump writes `SET FOREIGN_KEY_CHECKS=0;` to the start of every dump file. + ### tidb_pprof_sql_cpu New in v4.0 - Scope: INSTANCE