*: refine placement documents (#7885)

* *: refine placement documents Signed-off-by: xhe <[email protected]> * *: reword Signed-off-by: xhe <[email protected]> * *: improve words, update compatibility Signed-off-by: xhe <[email protected]> * address comments Signed-off-by: xhe <[email protected]> * fix lint Signed-off-by: xhe <[email protected]> * sync with cn doc Signed-off-by: xhe <[email protected]> * sync with cn Signed-off-by: xhe <[email protected]> * Update information-schema/information-schema-placement-policies.md Co-authored-by: Ran <[email protected]> * variable update Signed-off-by: xhe <[email protected]> * compatibility refine Signed-off-by: xhe <[email protected]> * fix CI Signed-off-by: xhe <[email protected]> * sync with cn Signed-off-by: xhe <[email protected]> * remove enable_alter Signed-off-by: xhe <[email protected]> * Update system-variables.md Co-authored-by: TomShawn <[email protected]> * Apply suggestions from code review Co-authored-by: TomShawn <[email protected]> * Update system-variables.md Co-authored-by: TomShawn <[email protected]> * Update sql-statements/sql-statement-alter-placement-policy.md Co-authored-by: TomShawn <[email protected]> * Update system-variables.md Co-authored-by: TomShawn <[email protected]> * reword Signed-off-by: xhe <[email protected]> Co-authored-by: Ran <[email protected]> Co-authored-by: TomShawn <[email protected]>
pingcap · Mar 23, 2022 · 91fe4b0 · 91fe4b0
1 parent 20150b6
commit 91fe4b0
Show file tree

Hide file tree

Showing 11 changed files with 186 additions and 128 deletions.
diff --git 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
@@ -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
@@ -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   |     | <null>  |       |
+| CATALOG_NAME         | varchar(512)  | NO   |     | <null>  |       |
+| POLICY_NAME          | varchar(64)   | NO   |     | <null>  |       |
+| PRIMARY_REGION       | varchar(1024) | YES  |     | <null>  |       |
+| REGIONS              | varchar(1024) | YES  |     | <null>  |       |
+| CONSTRAINTS          | varchar(1024) | YES  |     | <null>  |       |
+| LEADER_CONSTRAINTS   | varchar(1024) | YES  |     | <null>  |       |
+| FOLLOWER_CONSTRAINTS | varchar(1024) | YES  |     | <null>  |       |
+| LEARNER_CONSTRAINTS  | varchar(1024) | YES  |     | <null>  |       |
+| SCHEDULE             | varchar(20)   | YES  |     | <null>  |       |
+| FOLLOWERS            | bigint(64)    | YES  |     | <null>  |       |
+| LEARNERS             | bigint(64)    | YES  |     | <null>  |       |
++----------------------+---------------+------+-----+---------+-------+
+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
diff --git 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. |