diff --git a/TOC.md b/TOC.md index 76ceb55911da3..19b052c5e6103 100644 --- a/TOC.md +++ b/TOC.md @@ -275,6 +275,7 @@ + [`ALTER DATABASE`](/sql-statements/sql-statement-alter-database.md) + [`ALTER INDEX`](/sql-statements/sql-statement-alter-index.md) + [`ALTER INSTANCE`](/sql-statements/sql-statement-alter-instance.md) + + [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) + [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) + [`ALTER USER`](/sql-statements/sql-statement-alter-user.md) + [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md) @@ -287,6 +288,7 @@ + [`CREATE [GLOBAL|SESSION] BINDING`](/sql-statements/sql-statement-create-binding.md) + [`CREATE DATABASE`](/sql-statements/sql-statement-create-database.md) + [`CREATE INDEX`](/sql-statements/sql-statement-create-index.md) + + [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md) + [`CREATE ROLE`](/sql-statements/sql-statement-create-role.md) + [`CREATE SEQUENCE`](/sql-statements/sql-statement-create-sequence.md) + [`CREATE TABLE LIKE`](/sql-statements/sql-statement-create-table-like.md) @@ -346,6 +348,7 @@ + [`SHOW COLLATION`](/sql-statements/sql-statement-show-collation.md) + [`SHOW [FULL] COLUMNS FROM`](/sql-statements/sql-statement-show-columns-from.md) + [`SHOW CONFIG`](/sql-statements/sql-statement-show-config.md) + + [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) + [`SHOW CREATE SEQUENCE`](/sql-statements/sql-statement-show-create-sequence.md) + [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) + [`SHOW CREATE USER`](/sql-statements/sql-statement-show-create-user.md) @@ -359,6 +362,8 @@ + [`SHOW INDEXES [FROM|IN]`](/sql-statements/sql-statement-show-indexes.md) + [`SHOW KEYS [FROM|IN]`](/sql-statements/sql-statement-show-keys.md) + [`SHOW MASTER STATUS`](/sql-statements/sql-statement-show-master-status.md) + + [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) + + [`SHOW PLACEMENT FOR`](/sql-statements/sql-statement-show-placement-for.md) + [`SHOW PLUGINS`](/sql-statements/sql-statement-show-plugins.md) + [`SHOW PRIVILEGES`](/sql-statements/sql-statement-show-privileges.md) + [`SHOW [FULL] PROCESSSLIST`](/sql-statements/sql-statement-show-processlist.md) @@ -426,6 +431,7 @@ + [Views](/views.md) + [Partitioning](/partitioned-table.md) + [Character Set and Collation](/character-set-and-collation.md) + + [Placement Rules in SQL](/placement-rules-in-sql.md) + System Tables + [`mysql`](/mysql-schema.md) + INFORMATION_SCHEMA diff --git a/configure-placement-rules.md b/configure-placement-rules.md index b28a4526cf270..79b9134e6ba51 100644 --- a/configure-placement-rules.md +++ b/configure-placement-rules.md @@ -10,6 +10,10 @@ aliases: ['/docs/dev/configure-placement-rules/','/docs/dev/how-to/configure/pla > > In the scenario of using TiFlash, the Placement Rules feature has been extensively tested and can be used in the production environment. Except for the scenario where TiFlash is used, using Placement Rules alone has not been extensively tested, so it is not recommended to enable this feature separately in the production environment. +> **Note:** +> +> TiDB v5.3.0 introduces an experimental support for [Placement Rules in SQL](/placement-rules-in-sql.md). This offers a more convenient way to configure the placement of tables and partitions. Placement Rules in SQL might replace placement configuration with PD in future releases. + Placement Rules is an experimental feature of the Placement Driver (PD) introduced in v4.0. It is a replica rule system that guides PD to generate corresponding schedules for different types of data. By combining different scheduling rules, you can finely control the attributes of any continuous data range, such as the number of replicas, the storage location, the host type, whether to participate in Raft election, and whether to act as the Raft leader. ## Rule system diff --git a/information-schema/information-schema-placement-rules.md b/information-schema/information-schema-placement-rules.md new file mode 100644 index 0000000000000..34a51747de883 --- /dev/null +++ b/information-schema/information-schema-placement-rules.md @@ -0,0 +1,80 @@ +--- +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). The information includes both placement policies and directly attached rules. + +{{< 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 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; -- Includes t3. +SELECT * FROM information_schema.placement_rules; -- Does not include 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) + +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" | +| TABLE test.t3 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | ++---------------+------------------------------------------------+ +3 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/information-schema/information-schema.md b/information-schema/information-schema.md index c06b656376e69..5ac50eca3b3a8 100644 --- a/information-schema/information-schema.md +++ b/information-schema/information-schema.md @@ -76,6 +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. | | [`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 new file mode 100644 index 0000000000000..3cbee7d70ecc6 --- /dev/null +++ b/placement-rules-in-sql.md @@ -0,0 +1,169 @@ +--- +title: Placement Rules in SQL +summary: Learn how to schedule placement of tables and partitions. +--- + +# Placement Rules in SQL + +> **Warning:** +> +> Placement Rules in SQL is an experimental feature. 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;`. + +Placement Rules allow you to configure where data will be stored in a TiKV cluster. This is useful for scenarios including optimizing a high availability strategy, ensuring that local copies of data will be available for local stale reads, and adhering to compliance requirements. + +## Specify placement options + +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_. + +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 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; +``` + +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. + +If you use direct placement options, you have to alter rules for each object (for example, tables and partitions). + +`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. + +## Option reference + +> **Note:** +> +> Placement options depend on labels correctly specified in the configuration of each TiKV node. For example, the `PRIMARY_REGION` option depends on the `region` label in TiKV. To see a summary of all labels available in your TiKV cluster, use the statement [`SHOW PLACEMENT LABELS`](/sql-statements/sql-statement-show-placement-labels.md): +> +> ```sql +> mysql> show placement labels; +> +--------+----------------+ +> | Key | Values | +> +--------+----------------+ +> | disk | ["ssd"] | +> | region | ["us-east-1"] | +> | zone | ["us-east-1a"] | +> +--------+----------------+ +> 3 rows in set (0.00 sec) +> ``` + +| Option Name | Description | +|----------------------------|------------------------------------------------------------------------------------------------| +| `PRIMARY_REGION` | Raft leaders are placed in stores that have the `region` label that matches the value of this option. | +| `REGIONS` | Raft followers are placed in stores that have the `region` label that matches the value of this option. | +| `SCHEDULE` | The strategy used to schedule the placement of followers. The value options are `EVEN` (default) or `MAJORITY_IN_PRIMARY`. | +| `FOLLOWERS` | The number of followers. For example, `FOLLOWERS=2` means that there will be 3 replicas of the data (2 followers and 1 leader). | + +In addition to the placement options above, you can also use the advance configurations. For details, see [Advance placement](#advanced-placement). + +| 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. | + +## Examples + +### Increase the number of replicas + +The default configuration of [`max-replicas`](/pd-configuration-file.md#max-replicas) is `3`. To increase this for a specific set of tables, you can use a placement policy as follows: + +```sql +CREATE PLACEMENT POLICY fivereplicas FOLLOWERS=4; +CREATE TABLE t1 (a INT) PLACEMENT POLICY=fivereplicas; +``` + +Note that the PD configuration includes the leader and follower count, thus 4 followers + 1 leader equals 5 replicas in total. + +To expand on this example, you can also use `PRIMARY_REGION` and `REGIONS` placement options to describe the placement for the followers: + +```sql +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; +``` + +The `SCHEDULE` option instructs TiDB on how to balance the followers. + +The default schedule of `EVEN` ensures a balance of followers in all regions. You can use the `MAJORITY_IN_PRIMARY` schedule to ensure that enough followers are placed in the primary region (`us-east-1`) so that quorum can be achieved. If the primary region completely fails, you can the `MAJORITY_IN_PRIMARY` schedule for lower latency transactions at the expense of availability. + +### Assign placement to a partitioned table + +> **Note:** +> +> The following example uses list partitioning, which is currently an experimental feature of TiDB. Partitioned tables also require the `PRIMARY KEY` to be included in all columns in the table's partitioning function. + +In addition to assigning placement options to tables, you can also assign the options to table partitions. For example: + +```sql +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"; + +SET tidb_enable_list_partition = 1; +CREATE TABLE t1 ( + country VARCHAR(10) NOT NULL, + userdata VARCHAR(100) NOT NULL +) 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 +); +``` + +### Set the default placement for a schema + +You can directly attach the default placement options 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: + +```sql +CREATE TABLE t1 (a INT); -- Creates a table t1 with no placement options. + +ALTER DATABASE test FOLLOWERS=4; -- Changes the default placement option, and does not apply to the existing table t1. + +CREATE TABLE t2 (a INT); -- Creates a table t2 with the default placement of FOLLOWERS=4. + +CREATE TABLE t3 (a INT) PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2"; -- Creates a table t3 without the default FOLLOWERS=4 placement, because this statement has specified another placement. + +ALTER DATABASE test FOLLOWERS=2; -- Changes the default placement, and does not apply to existing tables. + +CREATE TABLE t4 (a INT); -- Creates a table t4 with the default FOLLOWERS=2 option. +``` + +Because placement options are only inherited from the database schema when a table is created, it is recommended to set the default placement option using a `PLACEMENT POLICY`. This ensures that future changes to the policy propagate to existing tables. + +### Advanced placement + +The placement options `PRIMARY_REGION`, `REGIONS`, and `SCHEDULE` meet the basic needs of data placement at the loss of some flexibility. For more complex scenarios with the need for higher flexibility, you can also use the advanced placement options of `CONSTRAINTS` and `FOLLOWER_CONSTRAINTS`. These two options are mutually exclusive. If you specify both at the same time, an error will be returned. + +For example, to set constraints that data must reside on a TiKV store where the label `disk` must match a value: + +```sql +CREATE PLACEMENT POLICY storeonfastssd CONSTRAINTS="[+disk=ssd]"; +CREATE PLACEMENT POLICY storeonhdd CONSTRAINTS="[+disk=hdd]"; +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=storeonhdd, + 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=storeonfastssd +); +``` + +You can either specify constraints in list format (`[+disk=ssd]`) or in dictionary format (`{+disk=ssd:1,+disk=hdd:2}`). + +In list format, constraints are specified as a list of key-value pairs. The key starts with either a `+` or a `-` with `+disk=ssd` indicating that the label `disk` must be set to `ssd`, and `-disk=hdd`, indicating that the label `disk` must not be `hdd`. + +In dictionary format, constraints also indicate a number of instances that apply to that rule. For example `FOLLOWER_CONSTRAINTS="{+region=us-east-1:1,+region=us-east-2:1,+region=us-west-1:1,+any:1}";` indicates that 1 follower is in us-east-1, 1 follower is in us-east-2, 1 follower is in us-west-1, and 1 follower can be in any region. + +## 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 (either via direct placement or placement policies). +* Syntactic sugar rules exist for setting `PRIMARY_REGION` and `REGIONS`, but in 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. diff --git a/schedule-replicas-by-topology-labels.md b/schedule-replicas-by-topology-labels.md index 3f613b7a4644e..fd5f1197c2326 100644 --- a/schedule-replicas-by-topology-labels.md +++ b/schedule-replicas-by-topology-labels.md @@ -6,6 +6,10 @@ aliases: ['/docs/dev/location-awareness/','/docs/dev/how-to/deploy/geographic-re # Schedule Replicas by Topology Labels +> **Note:** +> +> TiDB v5.3.0 introduces an experimental support for [Placement Rules in SQL](/placement-rules-in-sql.md). This offers a more convenient way to configure the placement of tables and partitions. Placement Rules in SQL might replace placement configuration with PD in future releases. + To improve the high availability and disaster recovery capability of TiDB clusters, it is recommended that TiKV nodes are physically scattered as much as possible. For example, TiKV nodes can be distributed on different racks or even in different data centers. According to the topology information of TiKV, the PD scheduler automatically performs scheduling at the background to isolate each replica of a Region as much as possible, which maximizes the capability of disaster recovery. To make this mechanism effective, you need to properly configure TiKV and PD so that the topology information of the cluster, especially the TiKV location information, is reported to PD during deployment. Before you begin, see [Deploy TiDB Using TiUP](/production-deployment-using-tiup.md) first. diff --git a/sql-statements/sql-statement-alter-placement-policy.md b/sql-statements/sql-statement-alter-placement-policy.md new file mode 100644 index 0000000000000..b15be14f8c7d0 --- /dev/null +++ b/sql-statements/sql-statement-alter-placement-policy.md @@ -0,0 +1,80 @@ +--- +title: ALTER PLACEMENT POLICY +summary: The usage of ALTER PLACEMENT POLICY in TiDB. +--- + +# ALTER PLACEMENT POLICY + +> **Warning:** +> +> Placement Rules in SQL is an experimental feature. 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;`. + +`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. + +## Synopsis + +```ebnf+diagram +AlterPolicyStmt ::= + "ALTER" "PLACEMENT" "POLICY" IfExists PolicyName PlacementOptionList + +PolicyName ::= + Identifier + +PlacementOptionList ::= + DirectPlacementOption +| PlacementOptionList DirectPlacementOption +| PlacementOptionList ',' DirectPlacementOption + +DirectPlacementOption ::= + "PRIMARY_REGION" EqOpt stringLit +| "REGIONS" EqOpt stringLit +| "FOLLOWERS" EqOpt LengthNum +| "VOTERS" EqOpt LengthNum +| "LEARNERS" EqOpt LengthNum +| "SCHEDULE" EqOpt stringLit +| "CONSTRAINTS" EqOpt stringLit +| "LEADER_CONSTRAINTS" EqOpt stringLit +| "FOLLOWER_CONSTRAINTS" EqOpt stringLit +| "VOTER_CONSTRAINTS" EqOpt stringLit +| "LEARNER_CONSTRAINTS" EqOpt stringLit +``` + +## Examples + +> **Note:** +> +> To know which regions are available in your cluster, see [`SHOW PLACEMENT LABELS`](/sql-statements/sql-statement-show-placement-labels.md). +> +> If you do not see any available regions, your TiKV installation might not have labels set correctly. + +{{< copyable "sql" >}} + +```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 +``` + +``` +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 in set (0.00 sec) +``` + +## MySQL compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See also + +* [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 diff --git a/sql-statements/sql-statement-create-placement-policy.md b/sql-statements/sql-statement-create-placement-policy.md new file mode 100644 index 0000000000000..d0f2bd006c723 --- /dev/null +++ b/sql-statements/sql-statement-create-placement-policy.md @@ -0,0 +1,82 @@ +--- +title: CREATE PLACEMENT POLICY +summary: The usage of CREATE PLACEMENT POLICY in TiDB. +--- + +# CREATE PLACEMENT POLICY + +> **Warning:** +> +> Placement Rules in SQL is an experimental feature. 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;`. + +`CREATE PLACEMENT POLICY` is used to create a named placement policy that can later be assigned to tables, partitions, or database schemas. + +## Synopsis + +```ebnf+diagram +CreatePolicyStmt ::= + "CREATE" "PLACEMENT" "POLICY" IfNotExists PolicyName PlacementOptionList + +PolicyName ::= + Identifier + +PlacementOptionList ::= + DirectPlacementOption +| PlacementOptionList DirectPlacementOption +| PlacementOptionList ',' DirectPlacementOption + +DirectPlacementOption ::= + "PRIMARY_REGION" EqOpt stringLit +| "REGIONS" EqOpt stringLit +| "FOLLOWERS" EqOpt LengthNum +| "VOTERS" EqOpt LengthNum +| "LEARNERS" EqOpt LengthNum +| "SCHEDULE" EqOpt stringLit +| "CONSTRAINTS" EqOpt stringLit +| "LEADER_CONSTRAINTS" EqOpt stringLit +| "FOLLOWER_CONSTRAINTS" EqOpt stringLit +| "VOTER_CONSTRAINTS" EqOpt stringLit +| "LEARNER_CONSTRAINTS" EqOpt stringLit +``` + +## Examples + +> **Note:** +> +> To know which regions are available in your cluster, see [`SHOW PLACEMENT LABELS`](/sql-statements/sql-statement-show-placement-labels.md). +> +> If you do not see any available regions, your TiKV installation might not have labels set correctly. + +{{< copyable "sql" >}} + +```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; +``` + +``` +Query OK, 0 rows affected (0.08 sec) + +Query OK, 0 rows affected (0.10 sec) + ++--------+---------------------------------------------------------------------------------------------------+ +| Policy | Create Policy | ++--------+---------------------------------------------------------------------------------------------------+ +| p1 | 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) +``` + +## MySQL compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See also + +* [Placement Rules in SQL](/placement-rules-in-sql.md) +* [SHOW PLACEMENT](/sql-statements/sql-statement-show-placement.md) +* [ALTER PLACEMENT POLICY](/sql-statements/sql-statement-alter-placement-policy.md) +* [DROP PLACEMENT POLICY](/sql-statements/sql-statement-drop-placement-policy.md) diff --git a/sql-statements/sql-statement-drop-placement-policy.md b/sql-statements/sql-statement-drop-placement-policy.md new file mode 100644 index 0000000000000..12b5296b8b4c8 --- /dev/null +++ b/sql-statements/sql-statement-drop-placement-policy.md @@ -0,0 +1,75 @@ +--- +title: DROP PLACEMENT POLICY +summary: The usage of ALTER PLACEMENT POLICY in TiDB. +--- + +# DROP PLACEMENT POLICY + +> **Warning:** +> +> Placement Rules in SQL is an experimental feature. 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;`. + +`DROP PLACEMENT POLICY` is used to drop a previously created placement policy. + +## Synopsis + +```ebnf+diagram +DropPolicyStmt ::= + "DROP" "PLACEMENT" "POLICY" IfExists PolicyName + +PolicyName ::= + Identifier +``` + +## Examples + +Placement policies can only be dropped when they are not referenced by any tables or partitions. + +{{< copyable "sql" >}} + +```sql +CREATE PLACEMENT POLICY p1 FOLLOWERS=4; +CREATE TABLE t1 (a INT PRIMARY KEY) PLACEMENT POLICY=p1; +DROP PLACEMENT POLICY p1; -- This statement fails because the placement policy p1 is referenced. + +-- Finds which tables and partitions reference the placement policy. +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; -- Removes the placement policy from t1. +DROP PLACEMENT POLICY p1; -- Succeeds. +``` + +```sql +Query OK, 0 rows affected (0.10 sec) + +Query OK, 0 rows affected (0.11 sec) + +ERROR 8241 (HY000): Placement policy 'p1' is still in use + ++--------------+------------+ +| table_schema | table_name | ++--------------+------------+ +| test | t1 | ++--------------+------------+ +1 row in set (0.00 sec) + +Empty set (0.01 sec) + +Query OK, 0 rows affected (0.08 sec) + +Query OK, 0 rows affected (0.21 sec) +``` + +## MySQL compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See also + +* [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) +* [ALTER PLACEMENT POLICY](/sql-statements/sql-statement-alter-placement-policy.md) diff --git a/sql-statements/sql-statement-show-create-placement-policy.md b/sql-statements/sql-statement-show-create-placement-policy.md new file mode 100644 index 0000000000000..647f80d0f310b --- /dev/null +++ b/sql-statements/sql-statement-show-create-placement-policy.md @@ -0,0 +1,56 @@ +--- +title: SHOW CREATE PLACEMENT POLICY +summary: The usage of SHOW CREATE PLACEMENT POLICY in TiDB. +--- + +# SHOW CREATE PLACEMENT POLICY + +> **Warning:** +> +> Placement Rules in SQL is an experimental feature. 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;`. + +`SHOW CREATE PLACEMENT POLICY` is used to show the definition of a placement policy. This can be used to see the current definition of a placement policy and recreate it in another TiDB cluster. + +## Synopsis + +```ebnf+diagram +"SHOW" "CREATE" "PLACEMENT" "POLICY" PolicyName + +PolicyName ::= + Identifier +``` + +## Examples + +{{< copyable "sql" >}} + +```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 +``` + +``` +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 in set (0.00 sec) +``` + +## MySQL compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See also + +* [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) +* [ALTER PLACEMENT POLICY](/sql-statements/sql-statement-alter-placement-policy.md) +* [DROP PLACEMENT POLICY](/sql-statements/sql-statement-drop-placement-policy.md) diff --git a/sql-statements/sql-statement-show-placement-for.md b/sql-statements/sql-statement-show-placement-for.md new file mode 100644 index 0000000000000..021bbc01b5b9d --- /dev/null +++ b/sql-statements/sql-statement-show-placement-for.md @@ -0,0 +1,109 @@ +--- +title: SHOW PLACEMENT FOR +summary: The usage of SHOW PLACEMENT FOR in TiDB. +--- + +# SHOW PLACEMENT FOR + +> **Warning:** +> +> Placement Rules in SQL is an experimental feature. 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;`. + +`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. + +## Synopsis + +```ebnf+diagram +ShowStmt ::= + "PLACEMENT" "FOR" ShowPlacementTarget + +ShowPlacementTarget ::= + DatabaseSym DBName +| "TABLE" TableName +| "TABLE" TableName "PARTITION" Identifier +``` + +## Examples + +{{< copyable "sql" >}} + +```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); +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); +SHOW PLACEMENT FOR TABLE t3 PARTITION p1; +SHOW PLACEMENT FOR TABLE t3 PARTITION p2; +``` + +``` +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) + ++---------------+----------------------------------------------------------------------+------------------+ +| Target | Placement | Scheduling_State | ++---------------+----------------------------------------------------------------------+------------------+ +| DATABASE test | 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.t1 | FOLLOWERS=4 | INPROGRESS | ++---------------+-------------+------------------+ +1 row in set (0.00 sec) + +*************************** 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.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 + +This statement is a TiDB extension to MySQL syntax. + +## See also + +* [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) diff --git a/sql-statements/sql-statement-show-placement-labels.md b/sql-statements/sql-statement-show-placement-labels.md new file mode 100644 index 0000000000000..0335fb54e9f51 --- /dev/null +++ b/sql-statements/sql-statement-show-placement-labels.md @@ -0,0 +1,49 @@ +--- +title: SHOW PLACEMENT LABELS +summary: The usage of SHOW PLACEMENT LABELS in TiDB. +--- + +# SHOW PLACEMENT LABELS + +> **Warning:** +> +> Placement Rules in SQL is an experimental feature. 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;`. + +`SHOW PLACEMENT LABELS` is used to summarize the labels and values that are available for Placement Rules. + +## Synopsis + +```ebnf+diagram +ShowStmt ::= + "PLACEMENT" "LABELS" +``` + +## Examples + +{{< copyable "sql" >}} + +```sql +SHOW PLACEMENT LABELS; +``` + +``` ++--------+----------------+ +| Key | Values | ++--------+----------------+ +| region | ["us-east-1"] | +| zone | ["us-east-1a"] | ++--------+----------------+ +2 rows in set (0.00 sec) +``` + +## MySQL compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See also + +* [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) \ No newline at end of file diff --git a/sql-statements/sql-statement-show-placement.md b/sql-statements/sql-statement-show-placement.md new file mode 100644 index 0000000000000..e14fd7a35035f --- /dev/null +++ b/sql-statements/sql-statement-show-placement.md @@ -0,0 +1,60 @@ +--- +title: SHOW PLACEMENT +summary: The usage of SHOW PLACEMENT in TiDB. +--- + +# SHOW PLACEMENT + +> **Warning:** +> +> Placement Rules in SQL is an experimental feature. 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;`. + +`SHOW PLACEMENT` summarizes all placement options from direct placement and placement policies, and presents them in canonical form. + +## Synopsis + +```ebnf+diagram +ShowStmt ::= + "PLACEMENT" +``` + +## Examples + +{{< copyable "sql" >}} + +```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; +``` + +``` +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) +``` + +## MySQL compatibility + +This statement is a TiDB extension to MySQL syntax. + +## See also + +* [Placement Rules in SQL](/placement-rules-in-sql.md) +* [SHOW PLACEMENT FOR](/sql-statements/sql-statement-show-placement-for.md) +* [CREATE PLACEMENT POLICY](/sql-statements/sql-statement-create-placement-policy.md) diff --git a/system-variables.md b/system-variables.md index fd88f3fc1b065..e4ebb4144e398 100644 --- a/system-variables.md +++ b/system-variables.md @@ -282,6 +282,13 @@ This variable is an alias for `last_insert_id`. > > Unlike in MySQL, the `max_execution_time` system variable currently works on all kinds of statements in TiDB, not only restricted to the `SELECT` statement. The precision of the timeout value is roughly 100ms. This means the statement might not be terminated in accurate milliseconds as you specify. +### placement_checks + +- Scope: SESSION | GLOBAL +- Default value: ON +- This variable controls whether DDL statements validate [Placement Rules in SQL](/placement-rules-in-sql.md). +- It is intended to be used by logical dump/restore tools to ensure that tables can always be created even if placement rules are violated. This is similar to how mysqldump writes `SET FOREIGN_KEY_CHECKS=0;` to the start of every dump file. + ### plugin_dir - Scope: INSTANCE