remove direct placement

placement-rules-in-sql.md

@@ -19,23 +19,52 @@ The detailed user scenarios are as follows:
 - Schedule the leaders of hotspot data to high-performance TiKV instances
 - Separate cold data to lower-cost storage mediums to improve cost efficiency
 
-## Specify placement options
+## Specify placement rules
 
-To use Placement Rules in SQL, you need to specify one or more placement options in a SQL statement. To specify the Placement options, you can either use _direct placement_ or use a _placement policy_.
+To specify placement rules, first create a placement policy:
 
-In the following example, both tables `t1` and `t2` have the same rules. `t1` is specified rules using a direct placement while `t2` is specified rules using a placement policy.
+```sql
+CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1";
+```
+
+Then attach the policy to a table or partition using either `CREATE TABLE` or `ALTER TABLE`:
 
 ```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;
+CREATE TABLE t1 (a INT) PLACEMENT POLICY myplacementpolicy;
+CREATE TABLE t2 (a INT);
+ALTER TABLE t2 PLACEMENT POLICY myplacementpolicy;
 ```
 
-It is recommended to use placement policies for simpler rule management. When you change a placement policy (via [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md)), the change automatically propagates to all database objects.
+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.
 
-If you use direct placement options, you have to alter rules for each object (for example, tables and partitions).
+## 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`:
+
+```sql
+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)
+```
+
+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
+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` 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.
+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
 
@@ -173,7 +202,7 @@ The following known limitations exist in the experimental release of Placement R
 
 * 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 (either via direct placement or placement policies).
+* 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.
 * Placement rules only ensure that data at rest resides on the correct TiKV store. The rules do not guarantee that data in transit (via either user queries or internal operations) only occurs in a specific region.

sql-statements/sql-statement-alter-placement-policy.md

@@ -13,6 +13,13 @@ summary: The usage of ALTER PLACEMENT POLICY in TiDB.
 
 `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` _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
@@ -23,11 +30,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

sql-statements/sql-statement-create-placement-policy.md

@@ -23,11 +23,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

sql-statements/sql-statement-show-placement-for.md

@@ -11,7 +11,13 @@ summary: The usage of SHOW PLACEMENT FOR in TiDB.
 >
 > If you understand the risks, you can enable this experiment feature by executing `SET GLOBAL tidb_enable_alter_placement = 1;`.
 
-`SHOW PLACEMENT FOR` summarizes all placement options from direct placement and placement policies, and presents them in the canonical form for a specific table, database schema, or partition.
+`SHOW PLACEMENT FOR` summarizes all placement options, and presents them in the canonical form for a specific table, database schema, or partition.
+
+The statement returns a result set in which the `Scheduling_State` field indicates the current progress that the Placement Driver (PD) has made in scheduling the placement:
+
+* `PENDING`: The PD has not yet started scheduling the placement. This might indicate that that the placement rules are semantically correct, but can not currently be satisfied by the cluster. For example, if `FOLLOWERS=4` but there are only 3 TiKV stores which are candidates for followers.
+* `INPROGRESS`: The PD is currently scheduling the placement.
+* `SCHEDULED`: The PD has successfully scheduled the placement.
 
 ## Synopsis
 
@@ -34,14 +40,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;
 ```
 
 ```
@@ -74,28 +77,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 compatibility

sql-statements/sql-statement-show-placement.md

@@ -11,7 +11,13 @@ summary: The usage of SHOW PLACEMENT in TiDB.
 >
 > If you understand the risks, you can enable this experiment feature by executing `SET GLOBAL tidb_enable_alter_placement = 1;`.
 
-`SHOW PLACEMENT` summarizes all placement options from direct placement and placement policies, and presents them in canonical form.
+`SHOW PLACEMENT` summarizes all placement options from placement policies, and presents them in canonical form.
+
+The statement returns a result set in which the `Scheduling_State` field indicates the current progress that the Placement Driver (PD) has made in scheduling the placement:
+
+* `PENDING`: The PD has not yet started scheduling the placement. This might indicate that that the placement rules are semantically correct, but can not currently be satisfied by the cluster. For example, if `FOLLOWERS=4` but there are only 3 TiKV stores which are candidates for followers.
+* `INPROGRESS`: The PD is currently scheduling the placement.
+* `SCHEDULED`: The PD has successfully scheduled the placement.
 
 ## Synopsis
 
@@ -27,7 +33,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;
 ```
 
@@ -36,15 +41,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)
 ```