From 83c5af41ec2c54b4feb4d8d817b44a02ec436598 Mon Sep 17 00:00:00 2001 From: nolouch Date: Fri, 13 Oct 2023 01:09:21 +0800 Subject: [PATCH 01/65] *: refine placement rule in sql Signed-off-by: nolouch --- placement-rules-in-sql.md | 276 +++++++++++++++++++++++++++----------- 1 file changed, 199 insertions(+), 77 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 464a2d3e542c..141707585d58 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -5,24 +5,40 @@ summary: 了解如何通过 SQL 接口调度表和分区的放置位置。 # Placement Rules in SQL -Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，用户可以将表和分区指定部署至不同的地域、机房、机柜、主机。适用场景包括低成本优化数据高可用策略、保证本地的数据副本可用于本地 Stale Read 读取、遵守数据本地要求等。 +Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，用户可以将表和分区或指定数据范围部署至不同的地域、机房、机柜、主机。适用场景包括低成本优化数据高可用策略、数据隔离要求等。 -> **注意：** +该功能可以实现以下业务场景： + +- 优化数据高可用策略，多数据中心部署 +- 合并多个不同业务的数据库，物理隔离不同用户的数据，满足实例内部不同用户的隔离需求 +- 增加重要数据的副本数，提高业务可用性和数据可靠性 + +限制和注意事项： + +- 不建议创建过多的 placement policy 增加运维复杂度，一个集群 policy 个数建议在 10 个以内 +- 不建议使用复杂的放置策略，使用推荐的[常见场景](#常用场景示例)应用 +- 限制绑定 policy 的表和分区数总数在 10000 以内。为过多的表，分区绑定 policy，会增加 PD 上规则计算的负担，从而影响服务。 + +> **提示：** > > Placement Rules in SQL 底层的实现依赖 PD 提供的放置规则 (placement rules) 功能，参考 [Placement Rules 使用文档](/configure-placement-rules.md)。在 Placement Rules in SQL 语境下，放置规则既可以代指绑定对象的放置策略 (placement policy)，也可以代指 TiDB 发给 PD 的放置规则。 -该功能可以实现以下业务场景： +## 概览 -- 合并多个不同业务的数据库，大幅减少数据库常规运维管理的成本 -- 增加重要数据的副本数，提高业务可用性和数据可靠性 -- 将最新数据存入 NVMe，历史数据存入 SSD，降低归档数据存储成本 -- 把热点数据的 leader 放到高性能的 TiKV 实例上 -- 将冷数据分离到不同的存储中以提高可用性 -- 支持物理隔离不同用户之间的计算资源，满足实例内部不同用户的隔离需求，以及不同混合负载 CPU、I/O、内存等资源隔离的需求 +通过 `Placement Rules in SQL`, 可以为不同的数据级别配置放置策略，从粗到细为： + +| 级别 | 描述 | +|----------------------------|------------------------------------------------------------------------------------------------| +| `Cluster` | TiDB 默认会配置为集群设置 3 副本的策略，你可以另外为全局放置策略进行置配置，参考[集群配置](#为集群指定全局的副本数) | +| `Database` | 你可以另外对 Databases 配置放置策略，参考[为数据库配置默认的放置规则](#为数据库配置默认的放置规则) | +| `Table` | 你可以另外对 Tables 配置放置策略，参考[为表指定放置规则](#为表指定放置规则) | +| `Row` | 你可以另外对特定的 Row 通过定义 Partition 来配置放置策略，参考[为分区表指定放置规则](#为分区表指定放置规则) | + +这些对象绑定 PLACEMENT POLICY， 都可以使用 `ALTER .... PLACEMENT POLICY policy_name` 语法，具体可参考示例。 `PLACEMENT POLICY` 具体的放置规则需要提前创建好。创建 POLICY 方式下面会介绍。 -## 指定放置规则 +## 创建放置规则 -指定放置规则，首先需要通过 [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md) 语句创建**放置策略 (placement policy)**。 +创建放置规则，首先需要通过 [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md) 语句创建**放置策略 (placement policy)**。 ```sql CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; @@ -52,9 +68,16 @@ DROP PLACEMENT POLICY myplacementpolicy; ## 查看放置规则 -如果一张表绑定了放置规则，你可以用 [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) 来查看。还可以用 [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) 来查看已经创建的放置策略。 +可以用 [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) 来查看已经创建的放置策略。如果一张表绑定了放置规则，你可以用 [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) 来查看。还 ```sql +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) + + tidb> SHOW CREATE TABLE t1\G *************************** 1. row *************************** Table: t1 @@ -62,11 +85,6 @@ 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) ``` 你也可以用 [`INFORMATION_SCHEMA.PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md) 系统表查看所有放置策略的定义。 @@ -125,68 +143,48 @@ SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS | `SCHEDULE` | 用于调度 follower 放置位置的策略。可选值为 `EVEN`（默认值）或 `MAJORITY_IN_PRIMARY`。 | | `FOLLOWERS` | Follower 的数量。例如 `FOLLOWERS=2` 表示数据有 3 个副本（2 个 follower 和 1 个 leader）。 | -除以上配置选项外，你还可以使用高级配置，详细介绍见[高级放置选项](#高级放置选项)。 +### 高级配置选项 + +除以上配置选项外，你还可以使用更高级的配置选项，使用起来相对更复杂一些，需要对集群拓扑和 TiDB 数据分片有更近一步了解才能使用得当。 | 选项名 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| | `CONSTRAINTS` | 适用于所有角色 (role) 的约束列表。例如，`CONSTRAINTS="[+disk=ssd]"`。 | | `LEADER_CONSTRAINTS` | 仅适用于 leader 的约束列表。 | | `FOLLOWER_CONSTRAINTS` | 仅适用于 follower 的约束列表。 | -| `LEARNER_CONSTRAINTS` | 仅适用于 learner 的约束列表。 | +| `LEARNER_CONSTRAINTS` | 仅适用于 learner 的约束列表。 | | `LEARNERS` | 指定 learner 的数量。 | | `SURVIVAL_PREFERENCE` | 指定按 label 容灾等级的优先级放置副本。例如 `SURVIVAL_PREFERENCE="[region, zone, host]"`。 | -## 示例 - -### 增加副本数 - -[`max-replicas`](/pd-configuration-file.md#max-replicas) 配置项的默认值为 `3`。如要为特定的表调大该值，可使用配置策略，示例如下： - -```sql -CREATE PLACEMENT POLICY fivereplicas FOLLOWERS=4; -CREATE TABLE t1 (a INT) PLACEMENT POLICY=fivereplicas; -``` - -注意，PD 配置中包含了 leader 数和 follower 数。因此，5 个副本为 4 个 follower + 1 个 leader。 +### CONSTRAINTS 格式 -对于以上示例，你还可使用 `PRIMARY_REGION` 和 `REGIONS` 选项来描述 follower 的放置规则： +`CONSTRAINTS` 支持两种类型的格式: -```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; -``` +| Constraint Type | 描述 | +|----------------------------|-----------------------------------------------------------------------------------------------------------| +| 列表格式 (All Replicas) | 约束以键值对列表格式。键以 `+` 或 `-` 开头。`+disk=nvme` 表示 `disk` 标签必须设为 `nvme`，`-disk=nvme` 表示 `disk` 标签值不能为 `nvme`。 | +| 字典格式 (Per Replica) | 在字典格式中，约束还指定了适用于该规则的多个实例。例如，`FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。再例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+disk=nvme": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有 `nvme` 硬盘的机器上，1 个 follower 位于 `us-west-1`。| -`SCHEDULE` 选项指示 TiDB 如何平衡 follower。该选项默认的 `EVEN` 调度规则确保 follower 在所有区域内分布平衡。 +> **注意：** +> +> LEADER_CONSTRAINTS 只支持列表格式。 +> +> 字典和列表格式都基于 YAML 解析，但 YAML 语法有些时候不能被正常解析。例如 YAML 会把 `"{+disk=ssd:1,+disk=nvme:2}"`（`:` 后无空格）错误地解析成 `'{"+disk=ssd:1": null, "+disk=nvme:2": null}'`，不符合预期。但 `"{+disk=ssd: 1,+disk=nvme: 2}"`（`:` 后有空格）能被正确解析成 `'{"+disk=ssd": 1, "+disk=nvme": 2}'`。 +> +> 字典格式支持以 `+` 或 `-` 开头的键，还支持另外一个特殊的属性 `#reject-leader`, 如 `FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2}' FOLLOWER_CONSTRAINTS='{"+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。 -如要保证在主区域内 (`us-east-1`) 放置足够多的 follower 副本，你可以使用 `MAJORITY_IN_PRIMARY` 调度规则来使该区域的 follower 达到指定数量。该调度牺牲一些可用性来换取更低的事务延迟。如果主区域宕机，`MAJORITY_IN_PRIMARY` 无法提供自动故障转移。 +## 基础示例 -### 为分区表指定放置规则 +### 为集群指定全局的副本数 -除了给表绑定放置策略之外，你还可以给表分区绑定放置策略。示例如下： +集群初始化后，副本数默认值为 `3`。如要为特定的表调大该值，可使用配置策略，示例如下： ```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"; - -SET tidb_enable_list_partition = 1; -CREATE TABLE t1 ( - country VARCHAR(10) NOT NULL, - userdata VARCHAR(100) NOT NULL -) 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') -); +CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; +ALTER RANGE global PLACEMENT POLICY five_replicas; ``` -如果分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，`pEurope` 分区将会应用 `europe` 策略，而 `pAsia` 分区将会应用表 `t1` 的放置策略 `p1`。如果 `t1` 没有绑定任何策略，`pAsia` 就不会应用任何策略。 - -给分区绑定放置策略后，你可以更改指定分区的放置策略。示例如下： - -```sql -ALTER TABLE t1 PARTITION pEurope PLACEMENT POLICY=p1; -``` +注意，配置中默认会认定 leader 数是 1。因此，5 个副本为 4 个 follower + 1 个 leader。 ### 为数据库配置默认的放置规则 @@ -216,11 +214,22 @@ ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- 绑定策略 p3 的表，也就是 t4 注意分区与表之间的继承和这里的继承不同。改变表的放置策略，也会让分区应用新的策略。但是只有建表时没有指定放置策略的时候，表才会从数据库继承放置策略，且之后再改变数据库也不影响已经继承的表。 -### 高级放置选项 +### 为表指定放置规则 -放置选项 `PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 可满足数据放置的基本需求，但会缺乏一些灵活性。在较复杂的场景下，若需要更灵活地放置数据，可以使用高级放置选项 `CONSTRAINTS` 和 `FOLLOWER_CONSTRAINTS`。`PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 选项不可与 `CONSTRAINTS` 选项同时指定，否则会报错。 +你可以为某个表制定默认的放置策略。 -以下示例设置了一个约束，要求数据必须位于某个 TiKV 节点，且该节点的 `disk` 标签必须匹配特定的值： +```sql +CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; + +CREATE TABLE t (a INT) PLACEMENT POLICY=five_replicas; -- 创建表 t。绑定放置策略为 five_replicas。 + +ALTER TABLE t PLACEMENT POLICY=default; -- 删除已绑定的放置策略 + +``` + +### 为分区表指定放置规则 + +除了给表绑定放置策略之外，你还可以给表分区绑定放置策略。示例如下： ```sql CREATE PLACEMENT POLICY storageonnvme CONSTRAINTS="[+disk=nvme]"; @@ -238,36 +247,148 @@ PARTITION BY RANGE( YEAR(purchased) ) ( ); ``` -该约束可通过列表格式 (`[+disk=ssd]`) 或字典格式 (`{+disk=ssd: 1,+disk=nvme: 2}`) 指定。 +如果分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，`p0` 分区将会应用 `storageonssd` 策略，`p4` 分区将会应用 `storageonnvme` 策略，而 `p1`,`p2`,`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy`。如果 `t1` 没有绑定任何策略，`p1`,`p2`,`p3` 就不会应用任何策略，即继承表或数据库或全局的默认策略。 + +给分区绑定放置策略后，你可以更改指定分区的放置策略。示例如下： + +```sql +ALTER TABLE t1 PARTITION p1 PLACEMENT POLICY=storageonssd; +``` + +## 常用场景示例 -在列表格式中，约束以键值对列表格式。键以 `+` 或 `-` 开头。`+disk=nvme` 表示 `disk` 标签必须设为 `nvme`，`-disk=nvme` 表示 `disk` 标签值不能为 `nvme`。 +放置选项 `PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 可满足数据放置的基本需求，但会缺乏一些灵活性。在较复杂的场景下，若需要更灵活地放置数据，可以使用高级放置选项 `CONSTRAINTS` 和 `FOLLOWER_CONSTRAINTS`。其中 `PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 选项不可与 `CONSTRAINTS` 选项同时指定，否则会报错。具体可参考[放置选项参考](#放置选项参考)。 -在字典格式中，约束还指定了适用于该规则的多个实例。例如，`FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。再例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+disk=nvme": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有 `nvme` 硬盘的机器上，1 个 follower 位于 `us-west-1`。 +**如何给节点打上标签** -> **注意：** -> -> 字典和列表格式都基于 YAML 解析，但 YAML 语法有些时候不能被正常解析。例如 YAML 会把 `"{+disk=ssd:1,+disk=nvme:2}"`（`:` 后无空格）错误地解析成 `'{"+disk=ssd:1": null, "+disk=nvme:2": null}'`，不符合预期。但 `"{+disk=ssd: 1,+disk=nvme: 2}"`（`:` 后有空格）能被正确解析成 `'{"+disk=ssd": 1, "+disk=nvme": 2}'`。 +放置规则依赖给存储节点标记上相应的属性，才能正常使用。 标记方式为： + +{{< copyable "" >}} -### 生存偏好 +``` +tikv-server --labels region=,zone=,host= +``` + +详细可参考相关示例: + +| 方式 | 示例 | +| --- | --- | +| 手动部署 | [通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md) | +| TiUP 部署 | [跨机房部署拓扑结构](/geo-distributed-deployment-topology.md) | +| Operator 部署| [在 Kubernetes 中配置 TiDB 集群](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/configure-a-tidb-cluster#高数据的高可用) | -在创建或修改放置策略时，你可以使用 `SURVIVAL_PREFERENCES` 选项设置数据的生存能力偏好。 +### 高可用场景 -例如，假设你的 TiDB 集群分布在 3 个 `zone`（即可用区），且每个可用区的 `host`（即节点）上混合部署了多个 TiKV 实例。在为该集群创建放置策略时，假设 `SURVIVAL_PREFERENCES` 的设置如下： +假设集群的拓扑扑结构如下： + +```sql +mysql> SELECT store_id,address,label from INFORMATION_SCHEMA.TIKV_STORE_STATUS; ++----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+ +| store_id | address | label | ++----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+ +| 1 | 127.0.0.1:20163 | [{"key": "region", "value": "us-east-1"}, {"key": "zone", "value": "us-east-1a"}, {"key": "host", "value": "host1"}] | +| 2 | 127.0.0.1:20162 | [{"key": "region", "value": "us-east-1"}, {"key": "zone", "value": "us-east-1b"}, {"key": "host", "value": "host2"}] | +| 3 | 127.0.0.1:20164 | [{"key": "region", "value": "us-east-1"}, {"key": "zone", "value": "us-east-1c"}, {"key": "host", "value": "host3"}] | +| 4 | 127.0.0.1:20160 | [{"key": "region", "value": "us-east-2"}, {"key": "zone", "value": "us-east-2a"}, {"key": "host", "value": "host4"}] | +| 5 | 127.0.0.1:20161 | [{"key": "region", "value": "us-east-2"}, {"key": "zone", "value": "us-east-2b"}, {"key": "host", "value": "host5"}] | +| 6 | 127.0.0.1:20165 | [{"key": "region", "value": "us-east-2"}, {"key": "zone", "value": "us-east-2c"}, {"key": "host", "value": "host6"}] | +| 7 | 127.0.0.1:20166 | [{"key": "region", "value": "us-west-1"}, {"key": "zone", "value": "us-west-1a"}, {"key": "host", "value": "host7"}] | +| 8 | 127.0.0.1:20167 | [{"key": "region", "value": "us-west-1"}, {"key": "zone", "value": "us-west-1b"}, {"key": "host", "value": "host8"}] | +| 9 | 127.0.0.1:20168 | [{"key": "region", "value": "us-west-1"}, {"key": "zone", "value": "us-west-1c"}, {"key": "host", "value": "host9"}] | ++----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+ + +``` + +集群的 TiKV 数据节点分布在 3 个 `region` 区域，每个中心有两个可用的 `zone`。 + +#### 指定生存偏好 + +如果你不特别在意数据的分布，只希望能满足容灾生存要求，你可以使用 `SURVIVAL_PREFERENCES` 选项设置数据的生存能力偏好。 + +例如，在例子中 TiDB 集群分布在 3 个 `region`（区域），且每个区域有多个 `zone`（即可用区）。在为该集群创建放置策略时，假设 `SURVIVAL_PREFERENCES` 的设置如下： ``` sql -CREATE PLACEMENT POLICY multiaz SURVIVAL_PREFERENCES="[zone, host]"; -CREATE PLACEMENT POLICY singleaz CONSTRAINTS="[+zone=zone1]" SURVIVAL_PREFERENCES="[host]"; +CREATE PLACEMENT POLICY multiaz SURVIVAL_PREFERENCES="[region, zone, host]"; +CREATE PLACEMENT POLICY singleaz CONSTRAINTS="[+region=us-east-1]" SURVIVAL_PREFERENCES="[zone]"; ``` 创建好放置策略后，你可以按需将放置策略绑定到对应的表上： -- 对于绑定了 `multiaz` 放置策略的表，数据将以 3 副本的形式放置在不同的可用区里，优先满足跨 `zone` 级别数据隔离的生存目标，再满足跨 `host` 级别的数据隔离的生存目标。 -- 对于绑定了 `singleaz` 放置策略的表，数据会优先以 3 副本的形式全部放置在 `zone1` 这个可用区里，再满足跨 `host` 级别的数据隔离的生存目标。 +- 对于绑定了 `multiaz` 放置策略的表，数据将以 3 副本的形式放置在不同的可用区里，优先满足跨 `region` 级别的生存目标，再满足跨 `zone` 级别的生存目标, 再满足跨 `host` 级别的生存目标。 +- 对于绑定了 `singleaz` 放置策略的表，数据会优先以 3 副本的形式全部放置在 `us-east-1` 这个可用区里，再满足跨 `zone` 级别的数据隔离的生存目标。 > **注意：** > > `SURVIVAL_PREFERENCES` 和 PD 中的 `location-labels` 是等价的，更多信息可以参考[通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md)。 +#### 指定集群多数据中心 5 副本 2:2:1 分布 + +如果要特定的数据分布，可以使用 `CONSTRAINTS` 配置 `Per-Replica` [字典格式](#constraints-格式)的策略: + +```sql +tidb> CREATE PLACEMENT POLICY `deploy221` CONSTRAINTS='{"+region=us-east-1":2, "+region=us-east-2": 2, "+region=us-west-1": 1}'; + +tidb> ALTER RANGE global PLACEMENT POLICY = "deploy221"; + +mysql> show placement; ++-------------------+---------------------------------------------------------------------------------------------+------------------+ +| Target | Placement | Scheduling_State | ++-------------------+---------------------------------------------------------------------------------------------+------------------+ +| POLICY deploy221 | CONSTRAINTS="{\"+region=us-east-1\":2, \"+region=us-east-2\": 2, \"+region=us-west-1\": 1}" | NULL | +| RANGE TiDB_GLOBAL | CONSTRAINTS="{\"+region=us-east-1\":2, \"+region=us-east-2\": 2, \"+region=us-west-1\": 1}" | SCHEDULED | ++-------------------+---------------------------------------------------------------------------------------------+------------------+ +``` + +通过为系统全局设置 `deploy221` 的放置规则后，TiDB 调度器会将数据根据该规则来分布数据： `us-east-1` 区域放置两个副本，`us-east-2` 区域放置两个副本，`us-west-1` 区域放置一个副本。 + +#### 指定 Leader/Follower 分布 + +以下两种方式都可以制定特殊的 Leader/Follower 的分布 + +##### 使用 Constraints 指定 + +如果你对 Leader 的分布要要求，可以使用如下语句指定。 + +```sql +CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1: 1}'; +``` + +该语句创建好后，绑定改策略的数据会将副本组的 Raft Leader 放置在 `us-east-1` 中，其他副本在其他区域。值得注意的是，如果集群发生故障，比如 leader 所在区域 `us-east-1` 的节点都挂了，这时候即时其他区域设置的都是 FOLLOWER_CONSTRAINTS, 也会选举出一个新的 leader，也就是说保证服务可用的优先级是最高的。如果希望在 `us-east-1` 区域故障发生时，leader 不要在 `us-west-1`，可以配置特殊的属性，驱逐上面新的 leader: + +```sql +CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1,#reject-leader: 1}'; +``` + +##### 使用 PRIMARY_REGION 指定 + +如果你的集群拓扑是使用 `region` label 标记的，上面例子你还可使用 `PRIMARY_REGION` 和 `REGIONS` 选项来描述 follower 的放置规则： + +```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; +``` + +`PRIMARY_REGION` 为 LEADER 分布的 REGION，只能指定一个。 + +`SCHEDULE` 选项指示 TiDB 如何平衡 follower。该选项默认的 `EVEN` 调度规则确保 follower 在所有区域内分布平衡。 + +如要保证在主区域内 (`us-east-1`) 放置足够多的 follower 副本，你可以使用 `MAJORITY_IN_PRIMARY` 调度规则来使该区域的 follower 达到指定数量。该调度牺牲一些可用性来换取更低的事务延迟。如果主区域宕机，`MAJORITY_IN_PRIMARY` 无法提供自动故障转移。 + +### 数据隔离场景 + +以下示例设置了一个约束，要求数据必须位于某个 TiKV 节点，且该节点的 `disk` 标签必须匹配特定的值： + +```sql +CREATE PLACEMENT POLICY storageonnvme CONSTRAINTS="[+disk=nvme]"; +CREATE PLACEMENT POLICY storageonssd CONSTRAINTS="[+disk=ssd]"; +CREATE TABLE tpapp (id INT, name VARCHAR(50), purchased DATE) +PLACEMENT POLICY=storageonnvme； +CREATE TABLE apapp (id INT, name VARCHAR(50), purchased DATE) +PLACEMENT POLICY=storageonssd +``` + +该约束可通过列表格式 (`[+disk=ssd]`) 或字典格式 (`{+disk=ssd: 1,+disk=nvme: 2}`) 指定。将应用 `tpapp` 数据放置在 `disk` 为 `nvme` 的 tikv 节点上，应用 `apapp` 的数据放置在 `disk` 为 `ssd` 的 tikv 节点上，从而在存储上达到了物理隔离的效果。 + ## 工具兼容性 | 工具名称 | 最低兼容版本 | 说明 | @@ -282,5 +403,6 @@ CREATE PLACEMENT POLICY singleaz CONSTRAINTS="[+zone=zone1]" SURVIVAL_PREFERENCE 目前已知 Placement Rules in SQL 特性存在以下限制： * 临时表不支持放置规则。 -* 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 * 放置规则仅保证静态数据被放置在正确的 TiKV 节点上。该规则不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 +* 设置 `TiFlash` 的副本要通过[构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md)的方式创建，不能使用该特性。 +* 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 From 58ff756489a65bf5a364658ae3014a6b03bb145d Mon Sep 17 00:00:00 2001 From: nolouch Date: Tue, 17 Oct 2023 11:42:24 +0800 Subject: [PATCH 02/65] fix Signed-off-by: nolouch --- releases/release-6.6.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/releases/release-6.6.0.md b/releases/release-6.6.0.md index 99df74ae6add..2fcfcd46d4bc 100644 --- a/releases/release-6.6.0.md +++ b/releases/release-6.6.0.md @@ -162,7 +162,7 @@ TiDB 版本：6.6.0-[DMR](/releases/versioning.md#开发里程碑版本) - 对于跨云区域部署的 TiDB 集群，当某个云区域产生故障时，指定数据库或表能在另一个云区域继续提供服务。 - 对于单个云区域内部署的 TiDB 集群，当某个可用区产生故障时，指定数据库或表能在另一个可用区继续提供服务。 - 更多信息，请参考[用户文档](/placement-rules-in-sql.md#生存偏好)。 + 更多信息，请参考[用户文档](/placement-rules-in-sql.md#指定生存偏好)。 * 支持通过 `FLASHBACK CLUSTER TO TIMESTAMP` 命令闪回 DDL 操作 [#14088](https://github.com/tikv/tikv/issues/14045) @[Defined2014](https://github.com/Defined2014) @[JmPotato](https://github.com/JmPotato) @@ -218,7 +218,7 @@ TiDB 版本：6.6.0-[DMR](/releases/versioning.md#开发里程碑版本) 更多信息，请参考[用户文档](/tidb-lightning/tidb-lightning-configuration.md#tidb-lightning-任务配置)。 -- TiDB Lightning 向 TiKV 传输键值对时支持启用压缩传输 [#41163](https://github.com/pingcap/tidb/issues/41163) @[gozssky](https://github.com/gozssky) +- TiDB Lightning 向 TiKV 传输键值对时支持启用压缩传输 [#41163](https://github.com/pingcap/tidb/issues/41163) @[sleepymole1](https://github.com/sleepymole1) 自 v6.6.0 起，TiDB Lightning 支持将本地编码排序后的键值对在网络传输时进行压缩再发送到 TiKV，从而减少网络传输的数据量，降低网络带宽开销。之前版本不支持该功能，在数据量较大的情况下，TiDB Lightning 对网络带宽要求相对较高，且会产生较高的流量费。 @@ -484,7 +484,7 @@ TiDB 版本：6.6.0-[DMR](/releases/versioning.md#开发里程碑版本) - 支持通过 `lightning.max-error` 设置最大冲突个数 [#40743](https://github.com/pingcap/tidb/issues/40743) @[dsdashun](https://github.com/dsdashun) - 支持导入带有 BOM header 的 CSV 数据文件 [#40744](https://github.com/pingcap/tidb/issues/40744) @[dsdashun](https://github.com/dsdashun) - 优化遇到 TiKV 限流错误时的处理逻辑，改为尝试其他空闲的 Region [#40205](https://github.com/pingcap/tidb/issues/40205) @[lance6716](https://github.com/lance6716) - - 导入时关闭对表外键的检查 [#40027](https://github.com/pingcap/tidb/issues/40027) @[gozssky](https://github.com/gozssky) + - 导入时关闭对表外键的检查 [#40027](https://github.com/pingcap/tidb/issues/40027) @[sleepymole1](https://github.com/sleepymole1) + Dumpling @@ -597,7 +597,7 @@ TiDB 版本：6.6.0-[DMR](/releases/versioning.md#开发里程碑版本) - 修复在并行导入时，当除最后一个 TiDB Lightning 实例外的其他实例都遇到本地重复记录时，TiDB Lightning 可能会错误地跳过冲突处理的问题 [#40923](https://github.com/pingcap/tidb/issues/40923) @[lichunzhu](https://github.com/lichunzhu) - 修复 precheck 无法准确检测目标集群是否存在运行中的 TiCDC 的问题 [#41040](https://github.com/pingcap/tidb/issues/41040) @[lance6716](https://github.com/lance6716) - 修复 TiDB Lightning 在 split-region 阶段发生 panic 的问题 [#40934](https://github.com/pingcap/tidb/issues/40934) @[lance6716](https://github.com/lance6716) - - 修复冲突处理逻辑 (`duplicate-resolution`) 可能导致 checksum 不一致的问题 [#40657](https://github.com/pingcap/tidb/issues/40657) @[gozssky](https://github.com/gozssky) + - 修复冲突处理逻辑 (`duplicate-resolution`) 可能导致 checksum 不一致的问题 [#40657](https://github.com/pingcap/tidb/issues/40657) @[sleepymole1](https://github.com/sleepymole1) - 修复当数据文件中存在未闭合的 delimiter 时可能 OOM 的问题 [#40400](https://github.com/pingcap/tidb/issues/40400) @[buchuitoudegou](https://github.com/buchuitoudegou) - 修复报错中的文件 offset 超过文件大小的问题 [#40034](https://github.com/pingcap/tidb/issues/40034) @[buchuitoudegou](https://github.com/buchuitoudegou) - 修复新版 PD client 可能导致并行导入失败的问题 [#40493](https://github.com/pingcap/tidb/issues/40493) @[AmoebaProtozoa](https://github.com/AmoebaProtozoa) From e025712587135095a6d025d60c9ad55aac2845d9 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 17 Oct 2023 15:09:28 +0800 Subject: [PATCH 03/65] Update placement-rules-in-sql.md Co-authored-by: Yongbo Jiang --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 141707585d58..becb2f9ed52a 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -68,7 +68,7 @@ DROP PLACEMENT POLICY myplacementpolicy; ## 查看放置规则 -可以用 [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) 来查看已经创建的放置策略。如果一张表绑定了放置规则，你可以用 [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) 来查看。还 +可以用 [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) 来查看已经创建的指定放置策略。如果一张表绑定了放置规则，你可以用 [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) 来查看。 ```sql tidb> SHOW CREATE PLACEMENT POLICY myplacementpolicy\G From b14461f4efc25bf8d883d2e091d2a056d195c4d5 Mon Sep 17 00:00:00 2001 From: nolouch Date: Tue, 17 Oct 2023 15:16:21 +0800 Subject: [PATCH 04/65] fix Signed-off-by: nolouch --- placement-rules-in-sql.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index becb2f9ed52a..8b418a81fe86 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -376,18 +376,18 @@ CREATE TABLE t1 (a INT) PLACEMENT POLICY=eastandwest; ### 数据隔离场景 -以下示例设置了一个约束，要求数据必须位于某个 TiKV 节点，且该节点的 `disk` 标签必须匹配特定的值： +以下示例设置了一个约束，要求数据必须位于某些 TiKV 节点，且节点的 `app` 标签必须匹配特定的值： ```sql -CREATE PLACEMENT POLICY storageonnvme CONSTRAINTS="[+disk=nvme]"; -CREATE PLACEMENT POLICY storageonssd CONSTRAINTS="[+disk=ssd]"; +CREATE PLACEMENT POLICY app_order CONSTRAINTS="[+app=order]"; +CREATE PLACEMENT POLICY app_list CONSTRAINTS="[+app=list_collection]"; CREATE TABLE tpapp (id INT, name VARCHAR(50), purchased DATE) -PLACEMENT POLICY=storageonnvme； +PLACEMENT POLICY=apptp1 CREATE TABLE apapp (id INT, name VARCHAR(50), purchased DATE) -PLACEMENT POLICY=storageonssd +PLACEMENT POLICY=apptp1 ``` -该约束可通过列表格式 (`[+disk=ssd]`) 或字典格式 (`{+disk=ssd: 1,+disk=nvme: 2}`) 指定。将应用 `tpapp` 数据放置在 `disk` 为 `nvme` 的 tikv 节点上，应用 `apapp` 的数据放置在 `disk` 为 `ssd` 的 tikv 节点上，从而在存储上达到了物理隔离的效果。 +该约束可通过列表格式 (`[+app=order]`) 或字典格式 (`{+app=order: 3}`) 指定。将应用 `app_order` 数据放置在标记了标签 `app` 为 `order` 的 tikv 节点上，应用 `app_list` 的数据放置在标记了标签 `app` 为 `list_collection` 的 tikv 节点上，从而在存储上达到了物理隔离的效果。 ## 工具兼容性 From 13bfbfedc29e76aa57bb27485a738b6cd97ed924 Mon Sep 17 00:00:00 2001 From: nolouch Date: Tue, 17 Oct 2023 15:21:41 +0800 Subject: [PATCH 05/65] fix Signed-off-by: nolouch --- placement-rules-in-sql.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 8b418a81fe86..713fad395cf7 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -381,10 +381,10 @@ CREATE TABLE t1 (a INT) PLACEMENT POLICY=eastandwest; ```sql CREATE PLACEMENT POLICY app_order CONSTRAINTS="[+app=order]"; CREATE PLACEMENT POLICY app_list CONSTRAINTS="[+app=list_collection]"; -CREATE TABLE tpapp (id INT, name VARCHAR(50), purchased DATE) -PLACEMENT POLICY=apptp1 -CREATE TABLE apapp (id INT, name VARCHAR(50), purchased DATE) -PLACEMENT POLICY=apptp1 +CREATE TABLE order (id INT, name VARCHAR(50), purchased DATE) +PLACEMENT POLICY=app_order +CREATE TABLE list (id INT, name VARCHAR(50), purchased DATE) +PLACEMENT POLICY=app_list ``` 该约束可通过列表格式 (`[+app=order]`) 或字典格式 (`{+app=order: 3}`) 指定。将应用 `app_order` 数据放置在标记了标签 `app` 为 `order` 的 tikv 节点上，应用 `app_list` 的数据放置在标记了标签 `app` 为 `list_collection` 的 tikv 节点上，从而在存储上达到了物理隔离的效果。 From 6b6206d28584d12a3a79ffaf4d35a91b507d6db3 Mon Sep 17 00:00:00 2001 From: nolouch Date: Wed, 18 Oct 2023 17:12:12 +0800 Subject: [PATCH 06/65] replace rule to policy Signed-off-by: nolouch --- placement-rules-in-sql.md | 58 +++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 713fad395cf7..49c41c27566c 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -30,21 +30,21 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 | 级别 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| | `Cluster` | TiDB 默认会配置为集群设置 3 副本的策略，你可以另外为全局放置策略进行置配置，参考[集群配置](#为集群指定全局的副本数) | -| `Database` | 你可以另外对 Databases 配置放置策略，参考[为数据库配置默认的放置规则](#为数据库配置默认的放置规则) | -| `Table` | 你可以另外对 Tables 配置放置策略，参考[为表指定放置规则](#为表指定放置规则) | -| `Row` | 你可以另外对特定的 Row 通过定义 Partition 来配置放置策略，参考[为分区表指定放置规则](#为分区表指定放置规则) | +| `Database` | 你可以另外对 Databases 配置放置策略，参考[为数据库配置默认的放置策略](#为数据库配置默认的放置策略) | +| `Table` | 你可以另外对 Tables 配置放置策略，参考[为表指定放置策略](#为表指定放置策略) | +| `Row` | 你可以另外对特定的 Row 通过定义 Partition 来配置放置策略，参考[为分区表指定放置策略](#为分区表指定放置策略) | -这些对象绑定 PLACEMENT POLICY， 都可以使用 `ALTER .... PLACEMENT POLICY policy_name` 语法，具体可参考示例。 `PLACEMENT POLICY` 具体的放置规则需要提前创建好。创建 POLICY 方式下面会介绍。 +这些对象绑定 PLACEMENT POLICY， 都可以使用 `ALTER .... PLACEMENT POLICY policy_name` 语法，具体可参考示例。 `PLACEMENT POLICY` 具体的放置策略需要提前创建好。创建 POLICY 方式下面会介绍。 -## 创建放置规则 +## 创建放置策略 -创建放置规则，首先需要通过 [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md) 语句创建**放置策略 (placement policy)**。 +创建放置策略，首先需要通过 [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md) 语句创建**放置策略 (placement policy)**。 ```sql CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; ``` -然后可以使用 `CREATE TABLE` 或者 `ALTER TABLE` 将规则绑定至表或分区表，这样就在表或分区上指定了放置规则： +然后可以使用 `CREATE TABLE` 或者 `ALTER TABLE` 将策略绑定至表或分区表，这样就在表或分区上指定了放置策略： ```sql CREATE TABLE t1 (a INT) PLACEMENT POLICY=myplacementpolicy; @@ -52,7 +52,7 @@ CREATE TABLE t2 (a INT); ALTER TABLE t2 PLACEMENT POLICY=myplacementpolicy; ``` -`PLACEMENT POLICY` 为全局作用域，不与任何数据库表结构相关联。因此，通过 `CREATE TABLE` 指定放置规则时，无需任何额外的权限。 +`PLACEMENT POLICY` 为全局作用域，不与任何数据库表结构相关联。因此，通过 `CREATE TABLE` 指定放置策略时，无需任何额外的权限。 要修改放置策略，你可以使用 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 语句。修改将传播到所有绑定此放置策略的对象。 @@ -66,9 +66,9 @@ ALTER PLACEMENT POLICY myplacementpolicy FOLLOWERS=5; DROP PLACEMENT POLICY myplacementpolicy; ``` -## 查看放置规则 +## 查看放置策略 -可以用 [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) 来查看已经创建的指定放置策略。如果一张表绑定了放置规则，你可以用 [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) 来查看。 +可以用 [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) 来查看已经创建的指定放置策略。如果一张表绑定了放置策略，你可以用 [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) 来查看。 ```sql tidb> SHOW CREATE PLACEMENT POLICY myplacementpolicy\G @@ -107,14 +107,14 @@ LEARNERS | 0 1 row in set ``` -`information_schema.tables` 表和 `information_schema.partitions` 表也有一列 `tidb_placement_policy_name`，用于展示所有绑定了放置规则的对象： +`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; ``` -所有绑定规则的对象都是异步调度的。可以用 [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) 来查看放置规则的调度进度。 +所有绑定策略的对象都是异步调度的。可以用 [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) 来查看放置策略的调度进度。 ## 放置选项参考 @@ -134,7 +134,7 @@ SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS > 3 rows in set (0.00 sec) > ``` > -> - 使用 `CREATE PLACEMENT POLICY` 创建放置规则时，TiDB 不会检查标签是否存在，而是在绑定表的时候进行检查。 +> - 使用 `CREATE PLACEMENT POLICY` 创建放置策略时，TiDB 不会检查标签是否存在，而是在绑定表的时候进行检查。 | 选项名 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| @@ -163,7 +163,7 @@ SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS | Constraint Type | 描述 | |----------------------------|-----------------------------------------------------------------------------------------------------------| | 列表格式 (All Replicas) | 约束以键值对列表格式。键以 `+` 或 `-` 开头。`+disk=nvme` 表示 `disk` 标签必须设为 `nvme`，`-disk=nvme` 表示 `disk` 标签值不能为 `nvme`。 | -| 字典格式 (Per Replica) | 在字典格式中，约束还指定了适用于该规则的多个实例。例如，`FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。再例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+disk=nvme": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有 `nvme` 硬盘的机器上，1 个 follower 位于 `us-west-1`。| +| 字典格式 (Per Replica) | 在字典格式中，约束还指定了适用于该策略的多个实例。例如，`FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。再例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+disk=nvme": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有 `nvme` 硬盘的机器上，1 个 follower 位于 `us-west-1`。| > **注意：** > @@ -186,7 +186,7 @@ ALTER RANGE global PLACEMENT POLICY five_replicas; 注意，配置中默认会认定 leader 数是 1。因此，5 个副本为 4 个 follower + 1 个 leader。 -### 为数据库配置默认的放置规则 +### 为数据库配置默认的放置策略 你可以为某个数据库指定默认的放置策略，类似于为数据库设置默认字符集或排序规则。如果没有指定其他选项，就会使用数据库上指定的配置。示例如下： @@ -197,15 +197,15 @@ CREATE PLACEMENT POLICY p2 FOLLOWERS=4; CREATE PLACEMENT POLICY p3 FOLLOWERS=2; -CREATE TABLE t1 (a INT); -- 创建表 t1，且未指定放置规则。 +CREATE TABLE t1 (a INT); -- 创建表 t1，且未指定放置策略。 -ALTER DATABASE test PLACEMENT POLICY=p2; -- 更改默认的放置规则，但更改不影响已有的表 t1。 +ALTER DATABASE test PLACEMENT POLICY=p2; -- 更改默认的放置策略，但更改不影响已有的表 t1。 CREATE TABLE t2 (a INT); -- 创建表 t2，默认的放置策略 p2 在 t2 上生效。 -CREATE TABLE t3 (a INT) PLACEMENT POLICY=p1; -- 创建表 t3。因为语句中已经指定了其他放置规则，默认的 p2 策略在 t3 上不生效。 +CREATE TABLE t3 (a INT) PLACEMENT POLICY=p1; -- 创建表 t3。因为语句中已经指定了其他放置策略，默认的 p2 策略在 t3 上不生效。 -ALTER DATABASE test PLACEMENT POLICY=p3; -- 再次更改默认的放置规则，此更改不影响已有的表。 +ALTER DATABASE test PLACEMENT POLICY=p3; -- 再次更改默认的放置策略，此更改不影响已有的表。 CREATE TABLE t4 (a INT); -- 创建表 t4，默认的放置策略 p3 生效。 @@ -214,7 +214,7 @@ ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- 绑定策略 p3 的表，也就是 t4 注意分区与表之间的继承和这里的继承不同。改变表的放置策略，也会让分区应用新的策略。但是只有建表时没有指定放置策略的时候，表才会从数据库继承放置策略，且之后再改变数据库也不影响已经继承的表。 -### 为表指定放置规则 +### 为表指定放置策略 你可以为某个表制定默认的放置策略。 @@ -227,7 +227,7 @@ ALTER TABLE t PLACEMENT POLICY=default; -- 删除已绑定的放置策略 ``` -### 为分区表指定放置规则 +### 为分区表指定放置策略 除了给表绑定放置策略之外，你还可以给表分区绑定放置策略。示例如下： @@ -261,7 +261,7 @@ ALTER TABLE t1 PARTITION p1 PLACEMENT POLICY=storageonssd; **如何给节点打上标签** -放置规则依赖给存储节点标记上相应的属性，才能正常使用。 标记方式为： +放置策略依赖给存储节点标记上相应的属性，才能正常使用。 标记方式为： {{< copyable "" >}} @@ -339,7 +339,7 @@ mysql> show placement; +-------------------+---------------------------------------------------------------------------------------------+------------------+ ``` -通过为系统全局设置 `deploy221` 的放置规则后，TiDB 调度器会将数据根据该规则来分布数据： `us-east-1` 区域放置两个副本，`us-east-2` 区域放置两个副本，`us-west-1` 区域放置一个副本。 +通过为系统全局设置 `deploy221` 的放置策略后，TiDB 调度器会将数据根据该策略来分布数据： `us-east-1` 区域放置两个副本，`us-east-2` 区域放置两个副本，`us-west-1` 区域放置一个副本。 #### 指定 Leader/Follower 分布 @@ -361,7 +361,7 @@ CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us- ##### 使用 PRIMARY_REGION 指定 -如果你的集群拓扑是使用 `region` label 标记的，上面例子你还可使用 `PRIMARY_REGION` 和 `REGIONS` 选项来描述 follower 的放置规则： +如果你的集群拓扑是使用 `region` label 标记的，上面例子你还可使用 `PRIMARY_REGION` 和 `REGIONS` 选项来描述 follower 的放置策略： ```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; @@ -393,16 +393,16 @@ PLACEMENT POLICY=app_list | 工具名称 | 最低兼容版本 | 说明 | | --- | --- | --- | -| Backup & Restore (BR) | 6.0 | BR 在 v6.0 之前不支持放置规则的备份与恢复，见[恢复 Placement Rule 到集群时为什么会报错？](/faq/backup-and-restore-faq.md#恢复-placement-rule-到集群时为什么会报错) | +| Backup & Restore (BR) | 6.0 | BR 在 v6.0 之前不支持放置策略的备份与恢复，见[恢复 Placement Rule 到集群时为什么会报错？](/faq/backup-and-restore-faq.md#恢复-placement-rule-到集群时为什么会报错) | | TiDB Lightning | 暂时不兼容 | 导入包含放置策略的数据时会报错 | -| TiCDC | 6.0 | 忽略放置规则，不同步规则到下游集群 | -| TiDB Binlog | 6.0 | 忽略放置规则，不同步规则到下游集群 | +| TiCDC | 6.0 | 忽略放置策略，不同步策略到下游集群 | +| TiDB Binlog | 6.0 | 忽略放置策略，不同步策略到下游集群 | ## 使用限制 目前已知 Placement Rules in SQL 特性存在以下限制： -* 临时表不支持放置规则。 -* 放置规则仅保证静态数据被放置在正确的 TiKV 节点上。该规则不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 +* 临时表不支持放置策略。 +* 放置策略仅保证静态数据被放置在正确的 TiKV 节点上。该策略不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 * 设置 `TiFlash` 的副本要通过[构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md)的方式创建，不能使用该特性。 * 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 From 233fde72cdfdec9b13c21736dbaf0d41d8b8a9ca Mon Sep 17 00:00:00 2001 From: nolouch Date: Wed, 18 Oct 2023 17:30:28 +0800 Subject: [PATCH 07/65] address Signed-off-by: nolouch --- placement-rules-in-sql.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 49c41c27566c..5dfd10a77967 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -30,11 +30,11 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 | 级别 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| | `Cluster` | TiDB 默认会配置为集群设置 3 副本的策略，你可以另外为全局放置策略进行置配置，参考[集群配置](#为集群指定全局的副本数) | -| `Database` | 你可以另外对 Databases 配置放置策略，参考[为数据库配置默认的放置策略](#为数据库配置默认的放置策略) | +| `Database` | 你可以另外对 Databases 配置放置策略，参考[为数据库配置默认的放置策略](#为数据库配置默认的放置策略) | | `Table` | 你可以另外对 Tables 配置放置策略，参考[为表指定放置策略](#为表指定放置策略) | | `Row` | 你可以另外对特定的 Row 通过定义 Partition 来配置放置策略，参考[为分区表指定放置策略](#为分区表指定放置策略) | -这些对象绑定 PLACEMENT POLICY， 都可以使用 `ALTER .... PLACEMENT POLICY policy_name` 语法，具体可参考示例。 `PLACEMENT POLICY` 具体的放置策略需要提前创建好。创建 POLICY 方式下面会介绍。 +这些对象绑定 PLACEMENT POLICY， 都可以使用 `ALTER .... PLACEMENT POLICY policy_name` 语法，具体可参考示例。 `PLACEMENT POLICY` 具体的放置策略需要提前创建好。创建 POLICY 方式下面会介绍。 ## 创建放置策略 @@ -162,14 +162,14 @@ SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS | Constraint Type | 描述 | |----------------------------|-----------------------------------------------------------------------------------------------------------| -| 列表格式 (All Replicas) | 约束以键值对列表格式。键以 `+` 或 `-` 开头。`+disk=nvme` 表示 `disk` 标签必须设为 `nvme`，`-disk=nvme` 表示 `disk` 标签值不能为 `nvme`。 | -| 字典格式 (Per Replica) | 在字典格式中，约束还指定了适用于该策略的多个实例。例如，`FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。再例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+disk=nvme": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有 `nvme` 硬盘的机器上，1 个 follower 位于 `us-west-1`。| +| 列表格式 (All Replicas) | 约束以键值对列表格式。键以 `+` 或 `-` 开头。`[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。`[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签值 `us-east-1` 且 `type` 标签值不为 `fault` 的节点上。 | +| 字典格式 (Per Replica) | 在字典格式中，还将约束映射到了副本数。例如，`FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。再例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。| > **注意：** > > LEADER_CONSTRAINTS 只支持列表格式。 > -> 字典和列表格式都基于 YAML 解析，但 YAML 语法有些时候不能被正常解析。例如 YAML 会把 `"{+disk=ssd:1,+disk=nvme:2}"`（`:` 后无空格）错误地解析成 `'{"+disk=ssd:1": null, "+disk=nvme:2": null}'`，不符合预期。但 `"{+disk=ssd: 1,+disk=nvme: 2}"`（`:` 后有空格）能被正确解析成 `'{"+disk=ssd": 1, "+disk=nvme": 2}'`。 +> 字典和列表格式都基于 YAML 解析，但 YAML 语法有些时候不能被正常解析。例如 YAML 会把 `"{+region=east:1,+region=west:2}"`（`:` 后无空格）错误地解析成 `'{"+region=east:1": null, "+region=west:2": null}'`，不符合预期。但 `"{+region=east: 1,+region=west: 2}"`（`:` 后有空格）能被正确解析成 `'{"+region=east": 1, "+region=west": 2}'`。 > > 字典格式支持以 `+` 或 `-` 开头的键，还支持另外一个特殊的属性 `#reject-leader`, 如 `FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2}' FOLLOWER_CONSTRAINTS='{"+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。 @@ -223,7 +223,7 @@ CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; CREATE TABLE t (a INT) PLACEMENT POLICY=five_replicas; -- 创建表 t。绑定放置策略为 five_replicas。 -ALTER TABLE t PLACEMENT POLICY=default; -- 删除已绑定的放置策略 +ALTER TABLE t PLACEMENT POLICY=default; -- 删除表 t 已绑定的放置策略 five_replicas, 重置为默认的。 ``` From 731db43cfe3ac9acccb12ca210a6019e906ecfe4 Mon Sep 17 00:00:00 2001 From: nolouch Date: Wed, 25 Oct 2023 16:12:43 +0800 Subject: [PATCH 08/65] address Signed-off-by: nolouch --- placement-rules-in-sql.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 5dfd10a77967..e679d2c28c8f 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -9,23 +9,23 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 该功能可以实现以下业务场景： -- 优化数据高可用策略，多数据中心部署 +- 多数据中心部署，配置规则优化数据高可用策略 - 合并多个不同业务的数据库，物理隔离不同用户的数据，满足实例内部不同用户的隔离需求 - 增加重要数据的副本数，提高业务可用性和数据可靠性 -限制和注意事项： +## 使用限制 -- 不建议创建过多的 placement policy 增加运维复杂度，一个集群 policy 个数建议在 10 个以内 -- 不建议使用复杂的放置策略，使用推荐的[常见场景](#常用场景示例)应用 -- 限制绑定 policy 的表和分区数总数在 10000 以内。为过多的表，分区绑定 policy，会增加 PD 上规则计算的负担，从而影响服务。 +- 为了降低运维难度，建议将一个集群的 placement policy 数量限制在 10 个以内。 +- 建议使用推荐的[常见场景](#常用场景示例)应用，不建议使用复杂的放置策略。 +- 建议将绑定了 placement policy 的表和分区数的总数限制在 10000 以内。为过多的表和分区绑定 policy，会增加 PD 上规则计算的负担，从而影响服务性能。 -> **提示：** +> **建议：** > > Placement Rules in SQL 底层的实现依赖 PD 提供的放置规则 (placement rules) 功能，参考 [Placement Rules 使用文档](/configure-placement-rules.md)。在 Placement Rules in SQL 语境下，放置规则既可以代指绑定对象的放置策略 (placement policy)，也可以代指 TiDB 发给 PD 的放置规则。 ## 概览 -通过 `Placement Rules in SQL`, 可以为不同的数据级别配置放置策略，从粗到细为： +通过 Placement Rules in SQL 功能, 你可以为不同的数据级别配置放置策略，粒度从粗到细为： | 级别 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| From e9156ba4caeb4989d37f0ad8e5ee857fdac8b075 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Wed, 25 Oct 2023 16:13:35 +0800 Subject: [PATCH 09/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index e679d2c28c8f..55a636ab6379 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -5,7 +5,7 @@ summary: 了解如何通过 SQL 接口调度表和分区的放置位置。 # Placement Rules in SQL -Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，用户可以将表和分区或指定数据范围部署至不同的地域、机房、机柜、主机。适用场景包括低成本优化数据高可用策略、数据隔离要求等。 +Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，你可以将表、分区、或指定的数据范围部署到不同的地域、机房、机柜、主机。 该功能可以实现以下业务场景： From 1b50d024b5d3f519c31a8cb182898ca592ae7bf2 Mon Sep 17 00:00:00 2001 From: nolouch Date: Wed, 25 Oct 2023 16:12:43 +0800 Subject: [PATCH 10/65] address Signed-off-by: nolouch --- placement-rules-in-sql.md | 14 +++++++------- releases/release-6.6.0.md | 6 +++--- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 5dfd10a77967..e679d2c28c8f 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -9,23 +9,23 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 该功能可以实现以下业务场景： -- 优化数据高可用策略，多数据中心部署 +- 多数据中心部署，配置规则优化数据高可用策略 - 合并多个不同业务的数据库，物理隔离不同用户的数据，满足实例内部不同用户的隔离需求 - 增加重要数据的副本数，提高业务可用性和数据可靠性 -限制和注意事项： +## 使用限制 -- 不建议创建过多的 placement policy 增加运维复杂度，一个集群 policy 个数建议在 10 个以内 -- 不建议使用复杂的放置策略，使用推荐的[常见场景](#常用场景示例)应用 -- 限制绑定 policy 的表和分区数总数在 10000 以内。为过多的表，分区绑定 policy，会增加 PD 上规则计算的负担，从而影响服务。 +- 为了降低运维难度，建议将一个集群的 placement policy 数量限制在 10 个以内。 +- 建议使用推荐的[常见场景](#常用场景示例)应用，不建议使用复杂的放置策略。 +- 建议将绑定了 placement policy 的表和分区数的总数限制在 10000 以内。为过多的表和分区绑定 policy，会增加 PD 上规则计算的负担，从而影响服务性能。 -> **提示：** +> **建议：** > > Placement Rules in SQL 底层的实现依赖 PD 提供的放置规则 (placement rules) 功能，参考 [Placement Rules 使用文档](/configure-placement-rules.md)。在 Placement Rules in SQL 语境下，放置规则既可以代指绑定对象的放置策略 (placement policy)，也可以代指 TiDB 发给 PD 的放置规则。 ## 概览 -通过 `Placement Rules in SQL`, 可以为不同的数据级别配置放置策略，从粗到细为： +通过 Placement Rules in SQL 功能, 你可以为不同的数据级别配置放置策略，粒度从粗到细为： | 级别 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| diff --git a/releases/release-6.6.0.md b/releases/release-6.6.0.md index 2fcfcd46d4bc..44474a462f5d 100644 --- a/releases/release-6.6.0.md +++ b/releases/release-6.6.0.md @@ -218,7 +218,7 @@ TiDB 版本：6.6.0-[DMR](/releases/versioning.md#开发里程碑版本) 更多信息，请参考[用户文档](/tidb-lightning/tidb-lightning-configuration.md#tidb-lightning-任务配置)。 -- TiDB Lightning 向 TiKV 传输键值对时支持启用压缩传输 [#41163](https://github.com/pingcap/tidb/issues/41163) @[sleepymole1](https://github.com/sleepymole1) +- TiDB Lightning 向 TiKV 传输键值对时支持启用压缩传输 [#41163](https://github.com/pingcap/tidb/issues/41163) @[sleepymole](https://github.com/sleepymole) 自 v6.6.0 起，TiDB Lightning 支持将本地编码排序后的键值对在网络传输时进行压缩再发送到 TiKV，从而减少网络传输的数据量，降低网络带宽开销。之前版本不支持该功能，在数据量较大的情况下，TiDB Lightning 对网络带宽要求相对较高，且会产生较高的流量费。 @@ -484,7 +484,7 @@ TiDB 版本：6.6.0-[DMR](/releases/versioning.md#开发里程碑版本) - 支持通过 `lightning.max-error` 设置最大冲突个数 [#40743](https://github.com/pingcap/tidb/issues/40743) @[dsdashun](https://github.com/dsdashun) - 支持导入带有 BOM header 的 CSV 数据文件 [#40744](https://github.com/pingcap/tidb/issues/40744) @[dsdashun](https://github.com/dsdashun) - 优化遇到 TiKV 限流错误时的处理逻辑，改为尝试其他空闲的 Region [#40205](https://github.com/pingcap/tidb/issues/40205) @[lance6716](https://github.com/lance6716) - - 导入时关闭对表外键的检查 [#40027](https://github.com/pingcap/tidb/issues/40027) @[sleepymole1](https://github.com/sleepymole1) + - 导入时关闭对表外键的检查 [#40027](https://github.com/pingcap/tidb/issues/40027) @[sleepymole](https://github.com/sleepymole) + Dumpling @@ -597,7 +597,7 @@ TiDB 版本：6.6.0-[DMR](/releases/versioning.md#开发里程碑版本) - 修复在并行导入时，当除最后一个 TiDB Lightning 实例外的其他实例都遇到本地重复记录时，TiDB Lightning 可能会错误地跳过冲突处理的问题 [#40923](https://github.com/pingcap/tidb/issues/40923) @[lichunzhu](https://github.com/lichunzhu) - 修复 precheck 无法准确检测目标集群是否存在运行中的 TiCDC 的问题 [#41040](https://github.com/pingcap/tidb/issues/41040) @[lance6716](https://github.com/lance6716) - 修复 TiDB Lightning 在 split-region 阶段发生 panic 的问题 [#40934](https://github.com/pingcap/tidb/issues/40934) @[lance6716](https://github.com/lance6716) - - 修复冲突处理逻辑 (`duplicate-resolution`) 可能导致 checksum 不一致的问题 [#40657](https://github.com/pingcap/tidb/issues/40657) @[sleepymole1](https://github.com/sleepymole1) + - 修复冲突处理逻辑 (`duplicate-resolution`) 可能导致 checksum 不一致的问题 [#40657](https://github.com/pingcap/tidb/issues/40657) @[sleepymole](https://github.com/sleepymole) - 修复当数据文件中存在未闭合的 delimiter 时可能 OOM 的问题 [#40400](https://github.com/pingcap/tidb/issues/40400) @[buchuitoudegou](https://github.com/buchuitoudegou) - 修复报错中的文件 offset 超过文件大小的问题 [#40034](https://github.com/pingcap/tidb/issues/40034) @[buchuitoudegou](https://github.com/buchuitoudegou) - 修复新版 PD client 可能导致并行导入失败的问题 [#40493](https://github.com/pingcap/tidb/issues/40493) @[AmoebaProtozoa](https://github.com/AmoebaProtozoa) From 555013f63a307ae3f962749fc7958a45e8b96d0c Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 26 Oct 2023 17:56:06 +0800 Subject: [PATCH 11/65] refine the structure and descriptions --- placement-rules-in-sql.md | 349 ++++++++++++++++++++------------------ 1 file changed, 187 insertions(+), 162 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 55a636ab6379..ce53e6ed5fc3 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -5,7 +5,7 @@ summary: 了解如何通过 SQL 接口调度表和分区的放置位置。 # Placement Rules in SQL -Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，你可以将表、分区、或指定的数据范围部署到不同的地域、机房、机柜、主机。 +Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，你可以将集群、数据库、表、或分区的数据部署到不同的地域、机房、机柜、主机。 该功能可以实现以下业务场景： @@ -13,128 +13,184 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 - 合并多个不同业务的数据库，物理隔离不同用户的数据，满足实例内部不同用户的隔离需求 - 增加重要数据的副本数，提高业务可用性和数据可靠性 -## 使用限制 +## 功能概述 + +通过 Placement Rules in SQL 功能, 你可以[创建放置策略 (placement policy)](#创建并绑定放置策略)，并为不同的数据级别配置所需的放置策略，粒度从粗到细为： + +| 级别 | 描述 | +|----------------------------|------------------------------------------------------------------------------------------------| +| 集群 | TiDB 默认为集群配置 3 副本的策略。你可以为集群配置全局放置策略，参考[集群配置](#为集群指定全局的副本数)。 | +| 数据库 | 你可以为指定的 Database 配置放置策略，参考[为数据库配置默认的放置策略](#为数据库配置默认的放置策略)。 | +| 表 | 你可以为指定的 Table 配置放置策略，参考[为表指定放置策略](#为表指定放置策略)。 | +| 分区 | 你可以为表中不同的 Row 创建分区，并单独对分区配置放置策略，参考[为分区表指定放置策略](#为分区表指定放置策略)。 | -- 为了降低运维难度，建议将一个集群的 placement policy 数量限制在 10 个以内。 -- 建议使用推荐的[常见场景](#常用场景示例)应用，不建议使用复杂的放置策略。 -- 建议将绑定了 placement policy 的表和分区数的总数限制在 10000 以内。为过多的表和分区绑定 policy，会增加 PD 上规则计算的负担，从而影响服务性能。 > **建议：** > > Placement Rules in SQL 底层的实现依赖 PD 提供的放置规则 (placement rules) 功能，参考 [Placement Rules 使用文档](/configure-placement-rules.md)。在 Placement Rules in SQL 语境下，放置规则既可以代指绑定对象的放置策略 (placement policy)，也可以代指 TiDB 发给 PD 的放置规则。 -## 概览 +## 使用限制 -通过 Placement Rules in SQL 功能, 你可以为不同的数据级别配置放置策略，粒度从粗到细为： +Placement Rules in SQL 特性目前存在以下限制： -| 级别 | 描述 | -|----------------------------|------------------------------------------------------------------------------------------------| -| `Cluster` | TiDB 默认会配置为集群设置 3 副本的策略，你可以另外为全局放置策略进行置配置，参考[集群配置](#为集群指定全局的副本数) | -| `Database` | 你可以另外对 Databases 配置放置策略，参考[为数据库配置默认的放置策略](#为数据库配置默认的放置策略) | -| `Table` | 你可以另外对 Tables 配置放置策略，参考[为表指定放置策略](#为表指定放置策略) | -| `Row` | 你可以另外对特定的 Row 通过定义 Partition 来配置放置策略，参考[为分区表指定放置策略](#为分区表指定放置策略) | +- 临时表不支持放置策略。 +- 放置策略仅保证静态数据被放置在正确的 TiKV 节点上。该策略不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 +- 设置 `TiFlash` 的副本要通过[构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md)的方式创建，不能使用该特性。 +- 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 +- 为了降低运维难度，建议将一个集群的 placement policy 数量限制在 10 个以内。 +- 建议使用推荐的[常见场景](#常用场景示例)应用，不建议使用复杂的放置策略。 +- 建议将绑定了 placement policy 的表和分区数的总数限制在 10000 以内。为过多的表和分区绑定 policy，会增加 PD 上规则计算的负担，从而影响服务性能。 -这些对象绑定 PLACEMENT POLICY， 都可以使用 `ALTER .... PLACEMENT POLICY policy_name` 语法，具体可参考示例。 `PLACEMENT POLICY` 具体的放置策略需要提前创建好。创建 POLICY 方式下面会介绍。 +## 前提条件 -## 创建放置策略 +放置策略依赖于 TiKV 节点标签 (label) 的配置。例如，`PRIMARY_REGION` 选项依赖 TiKV 中的 `region` 标签。 -创建放置策略，首先需要通过 [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md) 语句创建**放置策略 (placement policy)**。 +创建放置策略时，TiDB 不会检查标签是否存在，而是在绑定表的时候进行检查。因此，在绑定放置策略前，请确保各个 TiKV 节点已配置正确的 labels。配置方法为： -```sql -CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; ``` +tikv-server --labels region=,zone=,host= +``` + +详细配置方法可参考以下示例: + +| 方式 | 示例 | +| --- | --- | +| 手动部署 | [通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md) | +| TiUP 部署 | [跨机房部署拓扑结构](/geo-distributed-deployment-topology.md) | +| Operator 部署| [在 Kubernetes 中配置 TiDB 集群](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/configure-a-tidb-cluster#高数据的高可用) | -然后可以使用 `CREATE TABLE` 或者 `ALTER TABLE` 将策略绑定至表或分区表，这样就在表或分区上指定了放置策略： +如需查看当前 TiKV 集群中所有可用的标签，可以使用 [`SHOW PLACEMENT LABELS`](/sql-statements/sql-statement-show-placement-labels.md) 语句： ```sql -CREATE TABLE t1 (a INT) PLACEMENT POLICY=myplacementpolicy; -CREATE TABLE t2 (a INT); -ALTER TABLE t2 PLACEMENT POLICY=myplacementpolicy; +SHOW PLACEMENT LABELS; ++--------+----------------+ +| Key | Values | ++--------+----------------+ +| disk | ["ssd"] | +| region | ["us-east-1"] | +| zone | ["us-east-1a"] | ++--------+----------------+ +3 rows in set (0.00 sec) ``` -`PLACEMENT POLICY` 为全局作用域，不与任何数据库表结构相关联。因此，通过 `CREATE TABLE` 指定放置策略时，无需任何额外的权限。 +## 使用方法 -要修改放置策略，你可以使用 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 语句。修改将传播到所有绑定此放置策略的对象。 +本节介绍如何通过 SQL 语句创建、绑定、查看、修改、删除放置策略。 -```sql -ALTER PLACEMENT POLICY myplacementpolicy FOLLOWERS=5; -``` +### 创建并绑定放置策略 -要删除没有绑定任何分区或表的放置策略，你可以使用 [`DROP PLACEMENT POLICY`](/sql-statements/sql-statement-drop-placement-policy.md)： +1. 使用 [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md) 语句创建放置策略： -```sql -DROP PLACEMENT POLICY myplacementpolicy; -``` + ```sql + CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; + ``` -## 查看放置策略 + 在该语句中： -可以用 [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) 来查看已经创建的指定放置策略。如果一张表绑定了放置策略，你可以用 [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) 来查看。 + - `PRIMARY_REGION="us-east-1"` 选项代表 Raft leader 被放置在 `region` 标签为 `us-east-1` 的节点上。 + - `REGIONS="us-east-1,us-west-1"` 选项代表 Raft followers 被放置在`region` 标签为 `us-east-1` 和 `us-west-1` 的节点上。 -```sql -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) - - -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) -``` + 更多可配置的放置选项和对应的含义，请参考[放置选项](#放置选项参考)。 + +2. 使用 `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` 指定放置策略时，无需任何额外的权限。 + +### 查看放置策略 + +- 要查看某条已创建的放置策略，可以使用 [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md) 语句： + + ```sql + 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) + ``` + +- 要查看某张表绑定的放置策略，可以使用 [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) 语句： + + ```sql + 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) + ``` + +- 要查看集群中所有放置策略的定义，可以查询 [`INFORMATION_SCHEMA.PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md) 系统表： + + ```sql + 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 + ``` -你也可以用 [`INFORMATION_SCHEMA.PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md) 系统表查看所有放置策略的定义。 +- 要查看集群中所有绑定了放置策略的表，可以查询 `information_schema.tables` 系统表的 `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; + ``` + +- 要查看集群中所有绑定了放置策略的分区，可以查询 `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; + ``` + +- 所有绑定放置策略的对象都是异步调度的。要查看放置策略的调度进度，可以使用 [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) 语句。 + +### 修改放置策略 + +要修改放置策略，可以使用 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 语句。该修改将应用于所有绑定了此放置策略的对象。 ```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 +ALTER PLACEMENT POLICY myplacementpolicy FOLLOWERS=5; ``` -`information_schema.tables` 表和 `information_schema.partitions` 表也有一列 `tidb_placement_policy_name`，用于展示所有绑定了放置策略的对象： +在该语句中，`FOLLOWERS=5` 选项代表数据有 5 个副本，包括 4 个 follower 和 1 个 leader。更多可配置的放置选项和对应的含义，请参考[放置选项](#放置选项参考)。 + +### 删除放置策略 + +要删除没有绑定任何表或分区的放置策略，可以使用 [`DROP PLACEMENT POLICY`](/sql-statements/sql-statement-drop-placement-policy.md) 语句： ```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; +DROP PLACEMENT POLICY myplacementpolicy; ``` -所有绑定策略的对象都是异步调度的。可以用 [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) 来查看放置策略的调度进度。 - ## 放置选项参考 +在创建和修改放置策略时，你可以按需配置放置选项。 + > **注意：** > -> - 放置选项依赖于正确地指定在每个 TiKV 节点配置中的标签 (label)。例如，`PRIMARY_REGION` 选项依赖 TiKV 中的 `region` 标签。若要查看当前 TiKV 集群中所有可用的标签，可执行 [`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) -> ``` -> -> - 使用 `CREATE PLACEMENT POLICY` 创建放置策略时，TiDB 不会检查标签是否存在，而是在绑定表的时候进行检查。 +> `PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 选项不可与 `CONSTRAINTS` 选项同时指定，否则会报错。 + +### 常规放置选项 + +常规放置选项可以满足数据放置的基本需求。 | 选项名 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| @@ -143,13 +199,13 @@ SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS | `SCHEDULE` | 用于调度 follower 放置位置的策略。可选值为 `EVEN`（默认值）或 `MAJORITY_IN_PRIMARY`。 | | `FOLLOWERS` | Follower 的数量。例如 `FOLLOWERS=2` 表示数据有 3 个副本（2 个 follower 和 1 个 leader）。 | -### 高级配置选项 +### 高级放置选项 -除以上配置选项外，你还可以使用更高级的配置选项，使用起来相对更复杂一些，需要对集群拓扑和 TiDB 数据分片有更近一步了解才能使用得当。 +高级配置选项可以更灵活地放置数据，满足复杂的场景需求，但其配置方法相对常规配置选项更复杂一些，需要你对集群拓扑和 TiDB 数据分片有深入的了解。 | 选项名 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| -| `CONSTRAINTS` | 适用于所有角色 (role) 的约束列表。例如，`CONSTRAINTS="[+disk=ssd]"`。 | +| `CONSTRAINTS` | 适用于所有角色 (role) 的约束列表。例如，`CONSTRAINTS="[+disk=ssd]"`。| | `LEADER_CONSTRAINTS` | 仅适用于 leader 的约束列表。 | | `FOLLOWER_CONSTRAINTS` | 仅适用于 follower 的约束列表。 | | `LEARNER_CONSTRAINTS` | 仅适用于 learner 的约束列表。 | @@ -158,20 +214,19 @@ SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS ### CONSTRAINTS 格式 -`CONSTRAINTS` 支持两种类型的格式: +`CONSTRAINTS`、`FOLLOWER_CONSTRAINTS`、`LEARNER_CONSTRAINTS` 放置选项支持以下两种配置格式: -| Constraint Type | 描述 | +| CONSTRAINTS 格式 | 描述 | |----------------------------|-----------------------------------------------------------------------------------------------------------| -| 列表格式 (All Replicas) | 约束以键值对列表格式。键以 `+` 或 `-` 开头。`[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。`[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签值 `us-east-1` 且 `type` 标签值不为 `fault` 的节点上。 | -| 字典格式 (Per Replica) | 在字典格式中，还将约束映射到了副本数。例如，`FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。再例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。| +| 列表格式 (All Replicas) | 约束使用键值对列表格式。键以 `+` 或 `-` 开头。例如：
  • `[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。
  • `[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签值 `us-east-1` 且 `type` 标签值不为 `fault` 的节点上。

| +| 字典格式 (Per Replica) | 在字典格式中，约束可以指定对应的副本数。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，还支持一个特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2}' FOLLOWER_CONSTRAINTS='{"+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| > **注意：** > -> LEADER_CONSTRAINTS 只支持列表格式。 +> - `LEADER_CONSTRAINTS` 放置选项只支持列表格式。 > -> 字典和列表格式都基于 YAML 解析，但 YAML 语法有些时候不能被正常解析。例如 YAML 会把 `"{+region=east:1,+region=west:2}"`（`:` 后无空格）错误地解析成 `'{"+region=east:1": null, "+region=west:2": null}'`，不符合预期。但 `"{+region=east: 1,+region=west: 2}"`（`:` 后有空格）能被正确解析成 `'{"+region=east": 1, "+region=west": 2}'`。 +> - 字典和列表格式都基于 YAML 解析，但 YAML 语法有时不能被正常解析。例如 YAML 会把 `"{+region=east:1,+region=west:2}"`（`:` 后无空格）错误地解析成 `'{"+region=east:1": null, "+region=west:2": null}'`，不符合预期。但 `"{+region=east: 1,+region=west: 2}"`（`:` 后有空格）能被正确解析成 `'{"+region=east": 1, "+region=west": 2}'`。 > -> 字典格式支持以 `+` 或 `-` 开头的键，还支持另外一个特殊的属性 `#reject-leader`, 如 `FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2}' FOLLOWER_CONSTRAINTS='{"+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。 ## 基础示例 @@ -184,9 +239,9 @@ CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; ALTER RANGE global PLACEMENT POLICY five_replicas; ``` -注意，配置中默认会认定 leader 数是 1。因此，5 个副本为 4 个 follower + 1 个 leader。 +注意，TiDB 默认 leader 个数是 1。因此，5 个副本为 4 个 follower 和 1 个 leader。 -### 为数据库配置默认的放置策略 +### 为数据库指定默认的放置策略 你可以为某个数据库指定默认的放置策略，类似于为数据库设置默认字符集或排序规则。如果没有指定其他选项，就会使用数据库上指定的配置。示例如下： @@ -216,7 +271,7 @@ ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- 绑定策略 p3 的表，也就是 t4 ### 为表指定放置策略 -你可以为某个表制定默认的放置策略。 +你可以为某个表指定默认的放置策略。示例如下： ```sql CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; @@ -229,7 +284,7 @@ ALTER TABLE t PLACEMENT POLICY=default; -- 删除表 t 已绑定的放置策略 ### 为分区表指定放置策略 -除了给表绑定放置策略之外，你还可以给表分区绑定放置策略。示例如下： +你还可以给表分区指定放置策略。示例如下： ```sql CREATE PLACEMENT POLICY storageonnvme CONSTRAINTS="[+disk=nvme]"; @@ -247,7 +302,7 @@ PARTITION BY RANGE( YEAR(purchased) ) ( ); ``` -如果分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，`p0` 分区将会应用 `storageonssd` 策略，`p4` 分区将会应用 `storageonnvme` 策略，而 `p1`,`p2`,`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy`。如果 `t1` 没有绑定任何策略，`p1`,`p2`,`p3` 就不会应用任何策略，即继承表或数据库或全局的默认策略。 +如果某个分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，`p0` 分区将会应用 `storageonssd` 策略，`p4` 分区将会应用 `storageonnvme` 策略，而 `p1`,`p2`,`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy`。如果 `t1` 没有绑定任何策略，`p1`,`p2`,`p3` 就会继承数据库或全局的默认策略。 给分区绑定放置策略后，你可以更改指定分区的放置策略。示例如下： @@ -255,34 +310,12 @@ PARTITION BY RANGE( YEAR(purchased) ) ( ALTER TABLE t1 PARTITION p1 PLACEMENT POLICY=storageonssd; ``` -## 常用场景示例 +## 高可用场景示例 -放置选项 `PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 可满足数据放置的基本需求，但会缺乏一些灵活性。在较复杂的场景下，若需要更灵活地放置数据，可以使用高级放置选项 `CONSTRAINTS` 和 `FOLLOWER_CONSTRAINTS`。其中 `PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 选项不可与 `CONSTRAINTS` 选项同时指定，否则会报错。具体可参考[放置选项参考](#放置选项参考)。 - -**如何给节点打上标签** - -放置策略依赖给存储节点标记上相应的属性，才能正常使用。 标记方式为： - -{{< copyable "" >}} - -``` -tikv-server --labels region=,zone=,host= -``` - -详细可参考相关示例: - -| 方式 | 示例 | -| --- | --- | -| 手动部署 | [通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md) | -| TiUP 部署 | [跨机房部署拓扑结构](/geo-distributed-deployment-topology.md) | -| Operator 部署| [在 Kubernetes 中配置 TiDB 集群](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/configure-a-tidb-cluster#高数据的高可用) | - -### 高可用场景 - -假设集群的拓扑扑结构如下： +假设集群的拓扑扑结构如下，集群的 TiKV 数据节点分布在 3 个 `region`（区域），每个 `region` 有两个可用的 `zone` （可用区）： ```sql -mysql> SELECT store_id,address,label from INFORMATION_SCHEMA.TIKV_STORE_STATUS; +SELECT store_id,address,label from INFORMATION_SCHEMA.TIKV_STORE_STATUS; +----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+ | store_id | address | label | +----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+ @@ -299,13 +332,11 @@ mysql> SELECT store_id,address,label from INFORMATION_SCHEMA.TIKV_STORE_STATUS; ``` -集群的 TiKV 数据节点分布在 3 个 `region` 区域，每个中心有两个可用的 `zone`。 - -#### 指定生存偏好 +### 指定生存偏好 -如果你不特别在意数据的分布，只希望能满足容灾生存要求，你可以使用 `SURVIVAL_PREFERENCES` 选项设置数据的生存能力偏好。 +如果你不特别在意数据的具体分布，只希望能满足容灾生存要求，可以使用 `SURVIVAL_PREFERENCES` 选项设置数据的生存能力偏好。 -例如，在例子中 TiDB 集群分布在 3 个 `region`（区域），且每个区域有多个 `zone`（即可用区）。在为该集群创建放置策略时，假设 `SURVIVAL_PREFERENCES` 的设置如下： +在上面的例子中， TiDB 集群分布在 3 个 `region`，且每个区域有两个 `zone`。在为该集群创建放置策略时，假设 `SURVIVAL_PREFERENCES` 的设置如下： ``` sql CREATE PLACEMENT POLICY multiaz SURVIVAL_PREFERENCES="[region, zone, host]"; @@ -314,23 +345,23 @@ CREATE PLACEMENT POLICY singleaz CONSTRAINTS="[+region=us-east-1]" SURVIVAL_PREF 创建好放置策略后，你可以按需将放置策略绑定到对应的表上： -- 对于绑定了 `multiaz` 放置策略的表，数据将以 3 副本的形式放置在不同的可用区里，优先满足跨 `region` 级别的生存目标，再满足跨 `zone` 级别的生存目标, 再满足跨 `host` 级别的生存目标。 -- 对于绑定了 `singleaz` 放置策略的表，数据会优先以 3 副本的形式全部放置在 `us-east-1` 这个可用区里，再满足跨 `zone` 级别的数据隔离的生存目标。 +- 对于绑定了 `multiaz` 放置策略的表，数据将以 3 副本的形式放置在不同的 `region` 里，优先满足跨 `region` 级别的生存目标，再满足跨 `zone` 级别的生存目标，最后再满足跨 `host` 级别的生存目标。 +- 对于绑定了 `singleaz` 放置策略的表，数据会优先以 3 副本的形式全部放置在 `us-east-1` 这个 `region` 里，再满足跨 `zone` 级别的数据隔离的生存目标。 > **注意：** > > `SURVIVAL_PREFERENCES` 和 PD 中的 `location-labels` 是等价的，更多信息可以参考[通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md)。 -#### 指定集群多数据中心 5 副本 2:2:1 分布 +### 指定集群多数据中心 5 副本 2:2:1 分布 -如果要特定的数据分布，可以使用 `CONSTRAINTS` 配置 `Per-Replica` [字典格式](#constraints-格式)的策略: +如需特定的数据分布（如 5 副本 2:2:1 分布），可以使用 `CONSTRAINTS` 配置 `Per-Replica` [字典格式](#constraints-格式)的策略: ```sql -tidb> CREATE PLACEMENT POLICY `deploy221` CONSTRAINTS='{"+region=us-east-1":2, "+region=us-east-2": 2, "+region=us-west-1": 1}'; +CREATE PLACEMENT POLICY `deploy221` CONSTRAINTS='{"+region=us-east-1":2, "+region=us-east-2": 2, "+region=us-west-1": 1}'; -tidb> ALTER RANGE global PLACEMENT POLICY = "deploy221"; +ALTER RANGE global PLACEMENT POLICY = "deploy221"; -mysql> show placement; +SHOW PLACEMENT; +-------------------+---------------------------------------------------------------------------------------------+------------------+ | Target | Placement | Scheduling_State | +-------------------+---------------------------------------------------------------------------------------------+------------------+ @@ -339,44 +370,45 @@ mysql> show placement; +-------------------+---------------------------------------------------------------------------------------------+------------------+ ``` -通过为系统全局设置 `deploy221` 的放置策略后，TiDB 调度器会将数据根据该策略来分布数据： `us-east-1` 区域放置两个副本，`us-east-2` 区域放置两个副本，`us-west-1` 区域放置一个副本。 +通过为集群全局设置 `deploy221` 放置策略后，TiDB 会根据该策略来分布数据： `us-east-1` 区域放置两个副本，`us-east-2` 区域放置两个副本，`us-west-1` 区域放置一个副本。 -#### 指定 Leader/Follower 分布 +### 指定 Leader/Follower 分布 -以下两种方式都可以制定特殊的 Leader/Follower 的分布 +你可以通过 Constraints 或 PRIMARY_REGION 指定特殊的 Leader/Follower 的分布。 -##### 使用 Constraints 指定 +#### 使用 Constraints 指定 -如果你对 Leader 的分布要要求，可以使用如下语句指定。 +如果你对 Raft Leader 的分布节点有要求，可以使用如下语句指定： ```sql CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1: 1}'; ``` -该语句创建好后，绑定改策略的数据会将副本组的 Raft Leader 放置在 `us-east-1` 中，其他副本在其他区域。值得注意的是，如果集群发生故障，比如 leader 所在区域 `us-east-1` 的节点都挂了，这时候即时其他区域设置的都是 FOLLOWER_CONSTRAINTS, 也会选举出一个新的 leader，也就是说保证服务可用的优先级是最高的。如果希望在 `us-east-1` 区域故障发生时，leader 不要在 `us-west-1`，可以配置特殊的属性，驱逐上面新的 leader: +该语句创建好放置策略后，绑定该策略的数据会将副本中的 Raft Leader 放置在 `us-east-1` 中，其他副本在其他区域。需要注意的是，如果集群发生故障，比如 leader 所在区域 `us-east-1` 的节点宕机，这时候即使其他区域设置的都是 `FOLLOWER_CONSTRAINTS`, 也会从中选举出一个新的 Leader，也就是说保证服务可用的优先级是最高的。 + +在 `us-east-1` 区域故障发生时，如果希望新的 Leader 不要放置在 `us-west-1`，可以配置特殊的 `reject-leader` 属性，驱逐上面新的 Leader: ```sql CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1,#reject-leader: 1}'; ``` -##### 使用 PRIMARY_REGION 指定 +#### 使用 PRIMARY_REGION 指定 -如果你的集群拓扑是使用 `region` label 标记的，上面例子你还可使用 `PRIMARY_REGION` 和 `REGIONS` 选项来描述 follower 的放置策略： +如果你的集群拓扑配置了 `region` label，你还可以使用 `PRIMARY_REGION` 和 `REGIONS` 选项来指定 follower 的放置策略： ```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; ``` -`PRIMARY_REGION` 为 LEADER 分布的 REGION，只能指定一个。 - -`SCHEDULE` 选项指示 TiDB 如何平衡 follower。该选项默认的 `EVEN` 调度规则确保 follower 在所有区域内分布平衡。 - -如要保证在主区域内 (`us-east-1`) 放置足够多的 follower 副本，你可以使用 `MAJORITY_IN_PRIMARY` 调度规则来使该区域的 follower 达到指定数量。该调度牺牲一些可用性来换取更低的事务延迟。如果主区域宕机，`MAJORITY_IN_PRIMARY` 无法提供自动故障转移。 +- `PRIMARY_REGION` 为 Leader 分布的区域，只能指定一个。 +- `SCHEDULE` 选项指定 TiDB 如何平衡 follower 的分布。 + - 该选项默认的 `EVEN` 调度规则确保 follower 在所有区域内分布平衡。 + - 如需保证在 `PRIMARY_REGION`（即 `us-east-1`）内 放置足够多的 follower 副本，你可以使用 `MAJORITY_IN_PRIMARY` 调度规则来使该区域的 follower 达到指定数量。该调度牺牲一些可用性来换取更低的事务延迟。如果主区域宕机`MAJORITY_IN_PRIMARY` 无法提供自动故障转移。 -### 数据隔离场景 +## 数据隔离场景示例 -以下示例设置了一个约束，要求数据必须位于某些 TiKV 节点，且节点的 `app` 标签必须匹配特定的值： +以下示例在创建放置策略时，设置了一个约束，要求数据必须放置在配置了指定的 `app` 标签的 TiKV 节点： ```sql CREATE PLACEMENT POLICY app_order CONSTRAINTS="[+app=order]"; @@ -387,7 +419,9 @@ CREATE TABLE list (id INT, name VARCHAR(50), purchased DATE) PLACEMENT POLICY=app_list ``` -该约束可通过列表格式 (`[+app=order]`) 或字典格式 (`{+app=order: 3}`) 指定。将应用 `app_order` 数据放置在标记了标签 `app` 为 `order` 的 tikv 节点上，应用 `app_list` 的数据放置在标记了标签 `app` 为 `list_collection` 的 tikv 节点上，从而在存储上达到了物理隔离的效果。 +在该示例中，约束是通过列表格式 (`[+app=order]`) 指定的。你也可以使用字典格式指定，例如 (`{+app=order: 3}`)。 + +执行示例中的语句后，TiDB 会将 `app_order` 的数据放置在配置了 `app` 标签为 `order` 的 TiKV 节点上，将 `app_list` 的数据放置在配置了 `app` 标签为 `list_collection` 的 TiKV 节点上，从而在存储上达到了物理隔离的效果。 ## 工具兼容性 @@ -397,12 +431,3 @@ PLACEMENT POLICY=app_list | TiDB Lightning | 暂时不兼容 | 导入包含放置策略的数据时会报错 | | TiCDC | 6.0 | 忽略放置策略，不同步策略到下游集群 | | TiDB Binlog | 6.0 | 忽略放置策略，不同步策略到下游集群 | - -## 使用限制 - -目前已知 Placement Rules in SQL 特性存在以下限制： - -* 临时表不支持放置策略。 -* 放置策略仅保证静态数据被放置在正确的 TiKV 节点上。该策略不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 -* 设置 `TiFlash` 的副本要通过[构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md)的方式创建，不能使用该特性。 -* 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 From 716e7eebc2a9650922e599dbfbc55e3e663d946e Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 27 Oct 2023 17:16:54 +0800 Subject: [PATCH 12/65] Update placement-rules-in-sql.md --- placement-rules-in-sql.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index ce53e6ed5fc3..7470ae4999d4 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -24,22 +24,15 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 | 表 | 你可以为指定的 Table 配置放置策略，参考[为表指定放置策略](#为表指定放置策略)。 | | 分区 | 你可以为表中不同的 Row 创建分区，并单独对分区配置放置策略，参考[为分区表指定放置策略](#为分区表指定放置策略)。 | - > **建议：** > > Placement Rules in SQL 底层的实现依赖 PD 提供的放置规则 (placement rules) 功能，参考 [Placement Rules 使用文档](/configure-placement-rules.md)。在 Placement Rules in SQL 语境下，放置规则既可以代指绑定对象的放置策略 (placement policy)，也可以代指 TiDB 发给 PD 的放置规则。 ## 使用限制 -Placement Rules in SQL 特性目前存在以下限制： - -- 临时表不支持放置策略。 -- 放置策略仅保证静态数据被放置在正确的 TiKV 节点上。该策略不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 -- 设置 `TiFlash` 的副本要通过[构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md)的方式创建，不能使用该特性。 -- 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 - 为了降低运维难度，建议将一个集群的 placement policy 数量限制在 10 个以内。 -- 建议使用推荐的[常见场景](#常用场景示例)应用，不建议使用复杂的放置策略。 - 建议将绑定了 placement policy 的表和分区数的总数限制在 10000 以内。为过多的表和分区绑定 policy，会增加 PD 上规则计算的负担，从而影响服务性能。 +- 建议按照本文中提到的示例场景使用 Placement Rules in SQL 功能，不建议使用复杂的放置策略。 ## 前提条件 @@ -423,7 +416,16 @@ PLACEMENT POLICY=app_list 执行示例中的语句后，TiDB 会将 `app_order` 的数据放置在配置了 `app` 标签为 `order` 的 TiKV 节点上，将 `app_list` 的数据放置在配置了 `app` 标签为 `list_collection` 的 TiKV 节点上，从而在存储上达到了物理隔离的效果。 -## 工具兼容性 +## 兼容性说明 + +### 功能兼容性 + +- 临时表不支持放置策略。 +- 放置策略仅保证静态数据被放置在正确的 TiKV 节点上。该策略不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 +- 设置 `TiFlash` 的副本要通过[构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md)的方式创建，不能使用该特性。 +- 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 + +### 工具兼容性 | 工具名称 | 最低兼容版本 | 说明 | | --- | --- | --- | From 203c6afad3292c14ce9edbe8e2d896520c868ae9 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:19:27 +0800 Subject: [PATCH 13/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 7470ae4999d4..a85270331e37 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -36,7 +36,7 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 ## 前提条件 -放置策略依赖于 TiKV 节点标签 (label) 的配置。例如，`PRIMARY_REGION` 选项依赖 TiKV 中的 `region` 标签。 +放置策略依赖于 TiKV 节点标签 (label) 的配置。例如，放置选项 `PRIMARY_REGION` 依赖 TiKV 中的 `region` 标签。 创建放置策略时，TiDB 不会检查标签是否存在，而是在绑定表的时候进行检查。因此，在绑定放置策略前，请确保各个 TiKV 节点已配置正确的 labels。配置方法为： From 73a5e055b6836b5bc3b67b26d5f89e9aa6213c99 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:20:06 +0800 Subject: [PATCH 14/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 1 - 1 file changed, 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index a85270331e37..7101c5510b6a 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -143,7 +143,6 @@ SHOW PLACEMENT LABELS; ```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; ``` - 要查看集群中所有绑定了放置策略的分区，可以查询 `information_schema.partitions` 系统表的 `tidb_placement_policy_name` 列： From 35a73635e9a83fd6999f14d50e829a7b061f94bf Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:20:16 +0800 Subject: [PATCH 15/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 1 - 1 file changed, 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 7101c5510b6a..e10f63034154 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -148,7 +148,6 @@ SHOW PLACEMENT LABELS; - 要查看集群中所有绑定了放置策略的分区，可以查询 `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; ``` From c40f08ac75c2b9988f75d4f83f386f05e9dd579f Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:20:45 +0800 Subject: [PATCH 16/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index e10f63034154..af6fbfa26f3a 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -209,7 +209,7 @@ DROP PLACEMENT POLICY myplacementpolicy; | CONSTRAINTS 格式 | 描述 | |----------------------------|-----------------------------------------------------------------------------------------------------------| -| 列表格式 (All Replicas) | 约束使用键值对列表格式。键以 `+` 或 `-` 开头。例如：
  • `[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。
  • `[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签值 `us-east-1` 且 `type` 标签值不为 `fault` 的节点上。

| +| 列表格式 | 如果指定的约束适用于所有副本，可以使用键值对列表格式。键以 `+` 或 `-` 开头。例如：
  • `[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。
  • `[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签为 `us-east-1` 且 `type` 标签不为 `fault` 的节点上。

| | 字典格式 (Per Replica) | 在字典格式中，约束可以指定对应的副本数。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，还支持一个特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2}' FOLLOWER_CONSTRAINTS='{"+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| > **注意：** From 75f8c8b73ab00b6b239fdcee229ac9eb66619019 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:20:56 +0800 Subject: [PATCH 17/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index af6fbfa26f3a..bc5e83117db5 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -210,7 +210,7 @@ DROP PLACEMENT POLICY myplacementpolicy; | CONSTRAINTS 格式 | 描述 | |----------------------------|-----------------------------------------------------------------------------------------------------------| | 列表格式 | 如果指定的约束适用于所有副本，可以使用键值对列表格式。键以 `+` 或 `-` 开头。例如：
  • `[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。
  • `[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签为 `us-east-1` 且 `type` 标签不为 `fault` 的节点上。

| -| 字典格式 (Per Replica) | 在字典格式中，约束可以指定对应的副本数。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，还支持一个特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2}' FOLLOWER_CONSTRAINTS='{"+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| +| 字典格式 | 如果需要为不同的约束指定不同数量的副本，可以使用字典格式。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，并支持配置特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2}' FOLLOWER_CONSTRAINTS='{"+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| > **注意：** > From 2906f135202a209fc4d95a778342c2c62f17270e Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:21:06 +0800 Subject: [PATCH 18/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index bc5e83117db5..a5a830d60fc5 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -223,7 +223,7 @@ DROP PLACEMENT POLICY myplacementpolicy; ### 为集群指定全局的副本数 -集群初始化后，副本数默认值为 `3`。如要为特定的表调大该值，可使用配置策略，示例如下： +集群初始化后，副本数默认值为 `3`。集群如需更多的副本数，可使用配置策略调大该值，示例如下： ```sql CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; From f2e63b88e1168b03ed0d5a15601eb668a923352c Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:21:16 +0800 Subject: [PATCH 19/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 1 - 1 file changed, 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index a5a830d60fc5..ea34e966d80c 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -215,7 +215,6 @@ DROP PLACEMENT POLICY myplacementpolicy; > **注意：** > > - `LEADER_CONSTRAINTS` 放置选项只支持列表格式。 -> > - 字典和列表格式都基于 YAML 解析，但 YAML 语法有时不能被正常解析。例如 YAML 会把 `"{+region=east:1,+region=west:2}"`（`:` 后无空格）错误地解析成 `'{"+region=east:1": null, "+region=west:2": null}'`，不符合预期。但 `"{+region=east: 1,+region=west: 2}"`（`:` 后有空格）能被正确解析成 `'{"+region=east": 1, "+region=west": 2}'`。 > From 7163311547a1bdef7171dca45ece1f29518f72d3 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:21:33 +0800 Subject: [PATCH 20/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index ea34e966d80c..f53ede46dc85 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -344,7 +344,7 @@ CREATE PLACEMENT POLICY singleaz CONSTRAINTS="[+region=us-east-1]" SURVIVAL_PREF ### 指定集群多数据中心 5 副本 2:2:1 分布 -如需特定的数据分布（如 5 副本 2:2:1 分布），可以使用 `CONSTRAINTS` 配置 `Per-Replica` [字典格式](#constraints-格式)的策略: +如需特定的数据分布（如 5 副本 2:2:1 分布），可以配置[字典格式](#constraints-格式)的 `CONSTRAINTS` 为不同的约束指定不同数量的副本： ```sql CREATE PLACEMENT POLICY `deploy221` CONSTRAINTS='{"+region=us-east-1":2, "+region=us-east-2": 2, "+region=us-west-1": 1}'; From a173123d75c213482d5da9fdd0ead5a841a6c8f8 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:21:40 +0800 Subject: [PATCH 21/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index f53ede46dc85..07b5a0e5103d 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -394,7 +394,7 @@ CREATE TABLE t1 (a INT) PLACEMENT POLICY=eastandwest; - `PRIMARY_REGION` 为 Leader 分布的区域，只能指定一个。 - `SCHEDULE` 选项指定 TiDB 如何平衡 follower 的分布。 - 该选项默认的 `EVEN` 调度规则确保 follower 在所有区域内分布平衡。 - - 如需保证在 `PRIMARY_REGION`（即 `us-east-1`）内 放置足够多的 follower 副本，你可以使用 `MAJORITY_IN_PRIMARY` 调度规则来使该区域的 follower 达到指定数量。该调度牺牲一些可用性来换取更低的事务延迟。如果主区域宕机`MAJORITY_IN_PRIMARY` 无法提供自动故障转移。 + - 如需保证在 `PRIMARY_REGION`（即 `us-east-1`）内放置足够多的 follower 副本，你可以使用 `MAJORITY_IN_PRIMARY` 调度规则来使该区域的 follower 达到指定数量。该调度牺牲一些可用性来换取更低的事务延迟。如果主区域宕机，`MAJORITY_IN_PRIMARY` 无法提供自动故障转移。 ## 数据隔离场景示例 From 8cc741899a33747e3ac65a98e343e465ea10a2c7 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:21:45 +0800 Subject: [PATCH 22/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 07b5a0e5103d..ee968c894786 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -374,7 +374,7 @@ SHOW PLACEMENT; CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1: 1}'; ``` -该语句创建好放置策略后，绑定该策略的数据会将副本中的 Raft Leader 放置在 `us-east-1` 中，其他副本在其他区域。需要注意的是，如果集群发生故障，比如 leader 所在区域 `us-east-1` 的节点宕机，这时候即使其他区域设置的都是 `FOLLOWER_CONSTRAINTS`, 也会从中选举出一个新的 Leader，也就是说保证服务可用的优先级是最高的。 +该语句创建好放置策略后，绑定该策略的数据会将副本中的 Raft Leader 放置在 `us-east-1` 中，其他副本在其他区域。需要注意的是，如果集群发生故障，比如 Leader 所在区域 `us-east-1` 的节点宕机，这时候即使其他区域设置的都是 `FOLLOWER_CONSTRAINTS`, 也会从中选举出一个新的 Leader，也就是说保证服务可用的优先级是最高的。 在 `us-east-1` 区域故障发生时，如果希望新的 Leader 不要放置在 `us-west-1`，可以配置特殊的 `reject-leader` 属性，驱逐上面新的 Leader: From ace7e729d4dbea2d7fef1f1e3ebd009268009e73 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 27 Oct 2023 17:31:11 +0800 Subject: [PATCH 23/65] fix a broken link --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index ee968c894786..36a926857f2b 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -20,7 +20,7 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 | 级别 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| | 集群 | TiDB 默认为集群配置 3 副本的策略。你可以为集群配置全局放置策略，参考[集群配置](#为集群指定全局的副本数)。 | -| 数据库 | 你可以为指定的 Database 配置放置策略，参考[为数据库配置默认的放置策略](#为数据库配置默认的放置策略)。 | +| 数据库 | 你可以为指定的 Database 配置放置策略，参考[为数据库配置默认的放置策略](#为数据库指定默认的放置策略)。 | | 表 | 你可以为指定的 Table 配置放置策略，参考[为表指定放置策略](#为表指定放置策略)。 | | 分区 | 你可以为表中不同的 Row 创建分区，并单独对分区配置放置策略，参考[为分区表指定放置策略](#为分区表指定放置策略)。 | From a220ee7986e0ccfbe24628ca288eb2d4c16631f5 Mon Sep 17 00:00:00 2001 From: nolouch Date: Fri, 27 Oct 2023 17:33:25 +0800 Subject: [PATCH 24/65] update Signed-off-by: nolouch --- placement-rules-in-sql.md | 14 +++++++------- .../sql-statement-create-placement-policy.md | 1 + 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index ee968c894786..86abe5f41de4 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -20,7 +20,7 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 | 级别 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| | 集群 | TiDB 默认为集群配置 3 副本的策略。你可以为集群配置全局放置策略，参考[集群配置](#为集群指定全局的副本数)。 | -| 数据库 | 你可以为指定的 Database 配置放置策略，参考[为数据库配置默认的放置策略](#为数据库配置默认的放置策略)。 | +| 数据库 | 你可以为指定的 Database 配置放置策略，参考[为数据库指定默认的放置策略](#为数据库指定默认的放置策略)。 | | 表 | 你可以为指定的 Table 配置放置策略，参考[为表指定放置策略](#为表指定放置策略)。 | | 分区 | 你可以为表中不同的 Row 创建分区，并单独对分区配置放置策略，参考[为分区表指定放置策略](#为分区表指定放置策略)。 | @@ -210,7 +210,7 @@ DROP PLACEMENT POLICY myplacementpolicy; | CONSTRAINTS 格式 | 描述 | |----------------------------|-----------------------------------------------------------------------------------------------------------| | 列表格式 | 如果指定的约束适用于所有副本，可以使用键值对列表格式。键以 `+` 或 `-` 开头。例如：
  • `[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。
  • `[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签为 `us-east-1` 且 `type` 标签不为 `fault` 的节点上。

| -| 字典格式 | 如果需要为不同的约束指定不同数量的副本，可以使用字典格式。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，并支持配置特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2}' FOLLOWER_CONSTRAINTS='{"+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| +| 字典格式 | 如果需要为不同的约束指定不同数量的副本，可以使用字典格式。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，并支持配置特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2, +region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| > **注意：** > @@ -277,22 +277,22 @@ ALTER TABLE t PLACEMENT POLICY=default; -- 删除表 t 已绑定的放置策略 你还可以给表分区指定放置策略。示例如下： ```sql -CREATE PLACEMENT POLICY storageonnvme CONSTRAINTS="[+disk=nvme]"; -CREATE PLACEMENT POLICY storageonssd CONSTRAINTS="[+disk=ssd]"; +CREATE PLACEMENT POLICY storageforhisotrydata CONSTRAINTS="[+node=history]"; +CREATE PLACEMENT POLICY storagefornewdata CONSTRAINTS="[+node=new]"; 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=storageonssd, + PARTITION p0 VALUES LESS THAN (2000) PLACEMENT POLICY=storageforhisotrydata, 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=storageonnvme + PARTITION p4 VALUES LESS THAN MAXVALUE PLACEMENT POLICY=storagefornewdata ); ``` -如果某个分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，`p0` 分区将会应用 `storageonssd` 策略，`p4` 分区将会应用 `storageonnvme` 策略，而 `p1`,`p2`,`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy`。如果 `t1` 没有绑定任何策略，`p1`,`p2`,`p3` 就会继承数据库或全局的默认策略。 +如果某个分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，`p0` 分区将会应用 `storageforhisotrydata` 策略，`p4` 分区将会应用 `storagefornewdata` 策略，而 `p1`,`p2`,`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy`。如果 `t1` 没有绑定任何策略，`p1`,`p2`,`p3` 就会继承数据库或全局的默认策略。 给分区绑定放置策略后，你可以更改指定分区的放置策略。示例如下： diff --git a/sql-statements/sql-statement-create-placement-policy.md b/sql-statements/sql-statement-create-placement-policy.md index 966a5f473775..83d6971959e7 100644 --- a/sql-statements/sql-statement-create-placement-policy.md +++ b/sql-statements/sql-statement-create-placement-policy.md @@ -40,6 +40,7 @@ AdvancedPlacementOption ::= | "LEADER_CONSTRAINTS" EqOpt stringLit | "FOLLOWER_CONSTRAINTS" EqOpt stringLit | "LEARNER_CONSTRAINTS" EqOpt stringLit +| "SURVIVAL_PREFERENCES" EqOpt stringLit ``` ## 示例 From 167e67c77fa6aaf8947c2cf11293a331ea69b9ad Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:45:19 +0800 Subject: [PATCH 25/65] Update placement-rules-in-sql.md --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 86abe5f41de4..1d412e5f6293 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -210,7 +210,7 @@ DROP PLACEMENT POLICY myplacementpolicy; | CONSTRAINTS 格式 | 描述 | |----------------------------|-----------------------------------------------------------------------------------------------------------| | 列表格式 | 如果指定的约束适用于所有副本，可以使用键值对列表格式。键以 `+` 或 `-` 开头。例如：
  • `[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。
  • `[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签为 `us-east-1` 且 `type` 标签不为 `fault` 的节点上。

| -| 字典格式 | 如果需要为不同的约束指定不同数量的副本，可以使用字典格式。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，并支持配置特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2, +region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| +| 字典格式 | 如果需要为不同的约束指定不同数量的副本，可以使用字典格式。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，并支持配置特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2, "+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| > **注意：** > From 1b5997f5de7aacfed77ab0d1853a41b0496e4cd4 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:47:09 +0800 Subject: [PATCH 26/65] Update placement-rules-in-sql.md --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 1d412e5f6293..e45f72e71d3b 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -379,7 +379,7 @@ CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us- 在 `us-east-1` 区域故障发生时，如果希望新的 Leader 不要放置在 `us-west-1`，可以配置特殊的 `reject-leader` 属性，驱逐上面新的 Leader: ```sql -CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1,#reject-leader: 1}'; +CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1,#reject-leader": 1}'; ``` #### 使用 PRIMARY_REGION 指定 From 512cfe60301abda828700b2ebe682c7263206466 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 17:48:31 +0800 Subject: [PATCH 27/65] Update placement-rules-in-sql.md --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index e45f72e71d3b..96e9ec61e659 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -297,7 +297,7 @@ PARTITION BY RANGE( YEAR(purchased) ) ( 给分区绑定放置策略后，你可以更改指定分区的放置策略。示例如下： ```sql -ALTER TABLE t1 PARTITION p1 PLACEMENT POLICY=storageonssd; +ALTER TABLE t1 PARTITION p1 PLACEMENT POLICY=storageforhisotrydata; ``` ## 高可用场景示例 From 00b3e5e115dd00b853208588d148e02ecaad04a1 Mon Sep 17 00:00:00 2001 From: nolouch Date: Fri, 27 Oct 2023 17:52:33 +0800 Subject: [PATCH 28/65] update Signed-off-by: nolouch --- sql-statements/sql-statement-alter-placement-policy.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sql-statements/sql-statement-alter-placement-policy.md b/sql-statements/sql-statement-alter-placement-policy.md index 869b58d22583..be793aa05dd5 100644 --- a/sql-statements/sql-statement-alter-placement-policy.md +++ b/sql-statements/sql-statement-alter-placement-policy.md @@ -47,6 +47,7 @@ AdvancedPlacementOption ::= | "LEADER_CONSTRAINTS" EqOpt stringLit | "FOLLOWER_CONSTRAINTS" EqOpt stringLit | "LEARNER_CONSTRAINTS" EqOpt stringLit +| "SURVIVAL_PREFERENCES" EqOpt stringLit ``` ## 示例 From bf4e48eaec65baedde771041c9c57e5a15d9ff9d Mon Sep 17 00:00:00 2001 From: nolouch Date: Fri, 27 Oct 2023 18:05:09 +0800 Subject: [PATCH 29/65] update Signed-off-by: nolouch --- placement-rules-in-sql.md | 2 +- sql-statements/sql-statement-alter-range.md | 32 +++++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 sql-statements/sql-statement-alter-range.md diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 96e9ec61e659..7848ae0c5e24 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -222,7 +222,7 @@ DROP PLACEMENT POLICY myplacementpolicy; ### 为集群指定全局的副本数 -集群初始化后，副本数默认值为 `3`。集群如需更多的副本数，可使用配置策略调大该值，示例如下： +集群初始化后，副本数默认值为 `3`。集群如需更多的副本数，可使用配置策略调大该值，应用到集群级别，可以使用 [`ALTER RANGE`](/sql-statements/sql-statement-alter-range.md)。示例如下： ```sql CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md new file mode 100644 index 000000000000..94b5ad14c7ad --- /dev/null +++ b/sql-statements/sql-statement-alter-range.md @@ -0,0 +1,32 @@ +--- +title: ALTER RANGE +summary: TiDB 数据库中 ALTER RANGE 的使用概况。 +--- + +# ALTER RANGE + +`ALTER RANGE` 语句目前仅用于修改 TiDB 数据库中指定范围的放置策略。 + +## 语法图 + +```ebnf+diagram +AlterRangeStmt ::= + 'ALTER' 'RANGE' Identifier PlacementPolicyOption +``` + +目前 ALTER RANGE 能作用的只有 `global` 和 `meta` 两个： + +- global: 表示集群内全域数据范围 +- meta: 表示 TiDB 内部存储的元信息的数据范围 + +## 示例 + +{{< copyable "sql" >}} + +```sql +CREATE PLACEMENT POLICY `deploy221` CONSTRAINTS='{"+region=us-east-1":2, "+region=us-east-2": 2, "+region=us-west-1": 1}'; + +ALTER RANGE global PLACEMENT POLICY = "deploy221"; +``` + +上述示例创建了一个名为 "deploy221" 的放置策略，并为不同的区域指定了约束条件。然后，为整个集群内的数据使用了 "deploy221" 放置策略。 \ No newline at end of file From 8b90b0164feceb026296b31217bd406048233eab Mon Sep 17 00:00:00 2001 From: ShuNing Date: Fri, 27 Oct 2023 18:07:14 +0800 Subject: [PATCH 30/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 7848ae0c5e24..8767e6be9cfd 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -210,7 +210,7 @@ DROP PLACEMENT POLICY myplacementpolicy; | CONSTRAINTS 格式 | 描述 | |----------------------------|-----------------------------------------------------------------------------------------------------------| | 列表格式 | 如果指定的约束适用于所有副本，可以使用键值对列表格式。键以 `+` 或 `-` 开头。例如：
  • `[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。
  • `[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签为 `us-east-1` 且 `type` 标签不为 `fault` 的节点上。

| -| 字典格式 | 如果需要为不同的约束指定不同数量的副本，可以使用字典格式。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，并支持配置特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{ "+region=us-east-1":1, "+region=us-east-2": 2, "+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| +| 字典格式 | 如果需要为不同的约束指定不同数量的副本，可以使用字典格式。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，并支持配置特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1":1, "+region=us-east-2": 2, "+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| > **注意：** > From b052fc0cc449f1ec20a10c9b885e6037d24c5084 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 14:32:16 +0800 Subject: [PATCH 31/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 8767e6be9cfd..683446e770a9 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -292,7 +292,7 @@ PARTITION BY RANGE( YEAR(purchased) ) ( ); ``` -如果某个分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，`p0` 分区将会应用 `storageforhisotrydata` 策略，`p4` 分区将会应用 `storagefornewdata` 策略，而 `p1`,`p2`,`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy`。如果 `t1` 没有绑定任何策略，`p1`,`p2`,`p3` 就会继承数据库或全局的默认策略。 +如果某个分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，`p0` 分区将会应用 `storageforhisotrydata` 策略，`p4` 分区将会应用 `storagefornewdata` 策略，而 `p1`,`p2`,`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy`。如果 `t1` 没有绑定任何策略，`p1`,`p2`,`p3` 就会继承数据库或全局的默认策略。 给分区绑定放置策略后，你可以更改指定分区的放置策略。示例如下： From e946a2f8f330b0b6b548b869a6d0a7ccc13c7efd Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 14:32:21 +0800 Subject: [PATCH 32/65] Update sql-statements/sql-statement-alter-range.md Co-authored-by: xixirangrang --- sql-statements/sql-statement-alter-range.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md index 94b5ad14c7ad..2a457fc11280 100644 --- a/sql-statements/sql-statement-alter-range.md +++ b/sql-statements/sql-statement-alter-range.md @@ -14,7 +14,7 @@ AlterRangeStmt ::= 'ALTER' 'RANGE' Identifier PlacementPolicyOption ``` -目前 ALTER RANGE 能作用的只有 `global` 和 `meta` 两个： +目前 `ALTER RANGE` 能起作用的有 `global` 和 `meta` 两个参数： - global: 表示集群内全域数据范围 - meta: 表示 TiDB 内部存储的元信息的数据范围 From 840ebce2d2e0b9d226999562c9a84b5c0cee9126 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 14:32:28 +0800 Subject: [PATCH 33/65] Update placement-rules-in-sql.md Co-authored-by: xixirangrang --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 683446e770a9..9183ad819b15 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -426,7 +426,7 @@ PLACEMENT POLICY=app_list | 工具名称 | 最低兼容版本 | 说明 | | --- | --- | --- | -| Backup & Restore (BR) | 6.0 | BR 在 v6.0 之前不支持放置策略的备份与恢复，见[恢复 Placement Rule 到集群时为什么会报错？](/faq/backup-and-restore-faq.md#恢复-placement-rule-到集群时为什么会报错) | +| Backup & Restore (BR) | 6.0 | BR 在 v6.0 之前不支持放置策略的备份与恢复，请参见[恢复 Placement Rule 到集群时为什么会报错？](/faq/backup-and-restore-faq.md#恢复-placement-rule-到集群时为什么会报错) | | TiDB Lightning | 暂时不兼容 | 导入包含放置策略的数据时会报错 | | TiCDC | 6.0 | 忽略放置策略，不同步策略到下游集群 | | TiDB Binlog | 6.0 | 忽略放置策略，不同步策略到下游集群 | From d380d85be2e221c7d04854f5c270a32fa1d3023c Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 14:32:43 +0800 Subject: [PATCH 34/65] Update sql-statements/sql-statement-alter-range.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-alter-range.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md index 2a457fc11280..4976bdc4ce94 100644 --- a/sql-statements/sql-statement-alter-range.md +++ b/sql-statements/sql-statement-alter-range.md @@ -16,8 +16,8 @@ AlterRangeStmt ::= 目前 `ALTER RANGE` 能起作用的有 `global` 和 `meta` 两个参数： -- global: 表示集群内全域数据范围 -- meta: 表示 TiDB 内部存储的元信息的数据范围 +- `global`: 表示集群内全域数据的范围 +- `meta`: 表示 TiDB 内部存储的元信息的数据范围 ## 示例 From a0fcdb4f1e9e6ded1b9b1234ecca0755d2c8c9e7 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 14:32:48 +0800 Subject: [PATCH 35/65] Update sql-statements/sql-statement-alter-range.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-alter-range.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md index 4976bdc4ce94..00db9220042a 100644 --- a/sql-statements/sql-statement-alter-range.md +++ b/sql-statements/sql-statement-alter-range.md @@ -29,4 +29,4 @@ CREATE PLACEMENT POLICY `deploy221` CONSTRAINTS='{"+region=us-east-1":2, "+regio ALTER RANGE global PLACEMENT POLICY = "deploy221"; ``` -上述示例创建了一个名为 "deploy221" 的放置策略，并为不同的区域指定了约束条件。然后，为整个集群内的数据使用了 "deploy221" 放置策略。 \ No newline at end of file +上述示例创建了一个名为 `deploy221` 的放置策略，为不同的区域指定了约束条件。然后，将该放置策略应用到了整个集群范围内的数据。 \ No newline at end of file From 9a113da5aab3d54e9112db172d8867865dfe4d6b Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 14:32:53 +0800 Subject: [PATCH 36/65] Update sql-statements/sql-statement-alter-range.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-alter-range.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md index 00db9220042a..813ec874ff36 100644 --- a/sql-statements/sql-statement-alter-range.md +++ b/sql-statements/sql-statement-alter-range.md @@ -21,8 +21,6 @@ AlterRangeStmt ::= ## 示例 -{{< copyable "sql" >}} - ```sql CREATE PLACEMENT POLICY `deploy221` CONSTRAINTS='{"+region=us-east-1":2, "+region=us-east-2": 2, "+region=us-west-1": 1}'; From 593b606ed570c0be73b8e5fc2e672c6203d10d98 Mon Sep 17 00:00:00 2001 From: nolouch Date: Mon, 30 Oct 2023 14:37:59 +0800 Subject: [PATCH 37/65] address Signed-off-by: nolouch --- TOC.md | 1 + sql-statements/sql-statement-alter-range.md | 6 ++++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/TOC.md b/TOC.md index 5910c2fb887d..093e4fff7641 100644 --- a/TOC.md +++ b/TOC.md @@ -728,6 +728,7 @@ - [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) - [`ALTER TABLE COMPACT`](/sql-statements/sql-statement-alter-table-compact.md) - [`ALTER USER`](/sql-statements/sql-statement-alter-user.md) + - [`ALTER RANGE`](/sql-statements/sql-statement-alter-range.md) - [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md) - [`BACKUP`](/sql-statements/sql-statement-backup.md) - [`BATCH`](/sql-statements/sql-statement-batch.md) diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md index 813ec874ff36..277352f3c733 100644 --- a/sql-statements/sql-statement-alter-range.md +++ b/sql-statements/sql-statement-alter-range.md @@ -22,9 +22,11 @@ AlterRangeStmt ::= ## 示例 ```sql -CREATE PLACEMENT POLICY `deploy221` CONSTRAINTS='{"+region=us-east-1":2, "+region=us-east-2": 2, "+region=us-west-1": 1}'; +CREATE PLACEMENT POLICY `deploy111` CONSTRAINTS='{"+region=us-east-1":1, "+region=us-east-2": 1, "+region=us-west-1": 1}'; +CREATE PLACEMENT POLICY `five_replicas` FOLLOWERS=4; ALTER RANGE global PLACEMENT POLICY = "deploy221"; +ALTER RANGE global PLACEMENT POLICY = "five_replicas"; ``` -上述示例创建了一个名为 `deploy221` 的放置策略，为不同的区域指定了约束条件。然后，将该放置策略应用到了整个集群范围内的数据。 \ No newline at end of file +上述示例创建了一个名为 `deploy221` 和 `five_replicas` 的放置策略，为不同的区域指定了约束条件。然后将 `deploy111` 放置策略应用到了整个集群范围内的数据，将 `five_replicas` 放置策略应用到元数据范围内。 \ No newline at end of file From f732d26d41d88ad68261ef04e5300a61f0e059f3 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 15:53:07 +0800 Subject: [PATCH 38/65] Update placement-rules-in-sql.md Co-authored-by: xixirangrang --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 9183ad819b15..a60bdd4cd082 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -268,7 +268,7 @@ CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; CREATE TABLE t (a INT) PLACEMENT POLICY=five_replicas; -- 创建表 t。绑定放置策略为 five_replicas。 -ALTER TABLE t PLACEMENT POLICY=default; -- 删除表 t 已绑定的放置策略 five_replicas, 重置为默认的。 +ALTER TABLE t PLACEMENT POLICY=default; -- 删除表 t 已绑定的放置策略 five_replicas, 重置为默认的放置策略。 ``` From 7192c5e39ea6ca2848bab80989e3a8d23380b6c3 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 15:53:30 +0800 Subject: [PATCH 39/65] Update placement-rules-in-sql.md Co-authored-by: xixirangrang --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index a60bdd4cd082..eca8addb462c 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -360,7 +360,7 @@ SHOW PLACEMENT; +-------------------+---------------------------------------------------------------------------------------------+------------------+ ``` -通过为集群全局设置 `deploy221` 放置策略后，TiDB 会根据该策略来分布数据： `us-east-1` 区域放置两个副本，`us-east-2` 区域放置两个副本，`us-west-1` 区域放置一个副本。 +通过为集群全局设置 `deploy221` 放置策略后，TiDB 会根据该策略来分布数据：`us-east-1` 区域放置两个副本，`us-east-2` 区域放置两个副本，`us-west-1` 区域放置一个副本。 ### 指定 Leader/Follower 分布 From 594394dc045bafc664ce26484806f0d1d77535b7 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 15:53:48 +0800 Subject: [PATCH 40/65] Update placement-rules-in-sql.md Co-authored-by: xixirangrang --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index eca8addb462c..7c4fa6b09abe 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -38,7 +38,7 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 放置策略依赖于 TiKV 节点标签 (label) 的配置。例如，放置选项 `PRIMARY_REGION` 依赖 TiKV 中的 `region` 标签。 -创建放置策略时，TiDB 不会检查标签是否存在，而是在绑定表的时候进行检查。因此，在绑定放置策略前，请确保各个 TiKV 节点已配置正确的 labels。配置方法为： +创建放置策略时，TiDB 不会检查标签是否存在，而是在绑定表的时候进行检查。因此，在绑定放置策略前，请确保各个 TiKV 节点已配置正确的标签。配置方法为： ``` tikv-server --labels region=,zone=,host= From 8034385764e3fd442e4c2e3d73d43c04416eeb7b Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 15:55:16 +0800 Subject: [PATCH 41/65] Update placement-rules-in-sql.md Co-authored-by: xixirangrang --- placement-rules-in-sql.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 7c4fa6b09abe..c00ad720d4cf 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -292,7 +292,12 @@ PARTITION BY RANGE( YEAR(purchased) ) ( ); ``` -如果某个分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，`p0` 分区将会应用 `storageforhisotrydata` 策略，`p4` 分区将会应用 `storagefornewdata` 策略，而 `p1`,`p2`,`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy`。如果 `t1` 没有绑定任何策略，`p1`,`p2`,`p3` 就会继承数据库或全局的默认策略。 +如果某个分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，上面示例中： + +- `p0` 分区将会应用 `storageforhisotrydata` 策略 +- `p4` 分区将会应用 `storagefornewdata` 策略 +- `p1`、`p2`、`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy` +- 如果 `t1` 没有绑定任何策略，`p1`、`p2`、`p3` 会继承数据库或全局的默认策略 给分区绑定放置策略后，你可以更改指定分区的放置策略。示例如下： From cb395936173b5df867e14a1c6f46268f1f0caca4 Mon Sep 17 00:00:00 2001 From: nolouch Date: Mon, 30 Oct 2023 15:57:51 +0800 Subject: [PATCH 42/65] address Signed-off-by: nolouch --- placement-rules-in-sql.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 9183ad819b15..fe612f718434 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -153,6 +153,10 @@ SHOW PLACEMENT LABELS; - 所有绑定放置策略的对象都是异步调度的。要查看放置策略的调度进度，可以使用 [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) 语句。 + ```sql + SHOW PLACEMENT; + ``` + ### 修改放置策略 要修改放置策略，可以使用 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 语句。该修改将应用于所有绑定了此放置策略的对象。 @@ -302,7 +306,7 @@ ALTER TABLE t1 PARTITION p1 PLACEMENT POLICY=storageforhisotrydata; ## 高可用场景示例 -假设集群的拓扑扑结构如下，集群的 TiKV 数据节点分布在 3 个 `region`（区域），每个 `region` 有两个可用的 `zone` （可用区）： +假设集群的拓扑扑结构如下，集群的 TiKV 数据节点分布在 3 个 `region`（区域），每个 `region` 有 3 个可用的 `zone` （可用区）： ```sql SELECT store_id,address,label from INFORMATION_SCHEMA.TIKV_STORE_STATUS; @@ -326,7 +330,7 @@ SELECT store_id,address,label from INFORMATION_SCHEMA.TIKV_STORE_STATUS; 如果你不特别在意数据的具体分布，只希望能满足容灾生存要求，可以使用 `SURVIVAL_PREFERENCES` 选项设置数据的生存能力偏好。 -在上面的例子中， TiDB 集群分布在 3 个 `region`，且每个区域有两个 `zone`。在为该集群创建放置策略时，假设 `SURVIVAL_PREFERENCES` 的设置如下： +在上面的例子中， TiDB 集群分布在 3 个 `region`，且每个区域有 3 个 `zone`。在为该集群创建放置策略时，假设 `SURVIVAL_PREFERENCES` 的设置如下： ``` sql CREATE PLACEMENT POLICY multiaz SURVIVAL_PREFERENCES="[region, zone, host]"; From e9285bb4f037af948437f58f25b3bee89b20141e Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 30 Oct 2023 17:20:01 +0800 Subject: [PATCH 43/65] Update placement-rules-in-sql.md Co-authored-by: xixirangrang --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 9eef3e90f440..d87b44be18f6 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -219,7 +219,7 @@ DROP PLACEMENT POLICY myplacementpolicy; > **注意：** > > - `LEADER_CONSTRAINTS` 放置选项只支持列表格式。 -> - 字典和列表格式都基于 YAML 解析，但 YAML 语法有时不能被正常解析。例如 YAML 会把 `"{+region=east:1,+region=west:2}"`（`:` 后无空格）错误地解析成 `'{"+region=east:1": null, "+region=west:2": null}'`，不符合预期。但 `"{+region=east: 1,+region=west: 2}"`（`:` 后有空格）能被正确解析成 `'{"+region=east": 1, "+region=west": 2}'`。 +> - 字典和列表格式都基于 YAML 解析，但 YAML 语法有时不能被正常解析。例如 YAML 会把 `"{+region=east:1,+region=west:2}"`（`:` 后无空格）错误地解析成 `'{"+region=east:1": null, "+region=west:2": null}'`，不符合预期。但 `"{+region=east: 1,+region=west: 2}"`（`:` 后有空格）能被正确解析成 `'{"+region=east": 1, "+region=west": 2}'`。因此建议 `:` 后加上空格。 > ## 基础示例 From 5331b15a5b9413885cacf03ae506f4f947aa2912 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:51:01 +0800 Subject: [PATCH 44/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index d87b44be18f6..598861504271 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -38,7 +38,7 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群 放置策略依赖于 TiKV 节点标签 (label) 的配置。例如，放置选项 `PRIMARY_REGION` 依赖 TiKV 中的 `region` 标签。 -创建放置策略时，TiDB 不会检查标签是否存在，而是在绑定表的时候进行检查。因此，在绑定放置策略前，请确保各个 TiKV 节点已配置正确的标签。配置方法为： +创建放置策略时，TiDB 不会检查标签是否存在，而是在绑定放置策略的时候进行检查。因此，在绑定放置策略前，请确保各个 TiKV 节点已配置正确的标签。配置方法为： ``` tikv-server --labels region=,zone=,host= From e6ae990bc318875fdacfc6918e5511a413d9ff0e Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:51:12 +0800 Subject: [PATCH 45/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 598861504271..4242363d1e80 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -214,7 +214,7 @@ DROP PLACEMENT POLICY myplacementpolicy; | CONSTRAINTS 格式 | 描述 | |----------------------------|-----------------------------------------------------------------------------------------------------------| | 列表格式 | 如果指定的约束适用于所有副本，可以使用键值对列表格式。键以 `+` 或 `-` 开头。例如：
  • `[+region=us-east-1]` 表示放置数据在 `region` 标签为 `us-east-1` 的节点上。
  • `[+region=us-east-1,-type=fault]` 表示放置数据在 `region` 标签为 `us-east-1` 且 `type` 标签不为 `fault` 的节点上。

| -| 字典格式 | 如果需要为不同的约束指定不同数量的副本，可以使用字典格式。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的机器上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，并支持配置特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1":1, "+region=us-east-2": 2, "+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| +| 字典格式 | 如果需要为不同的约束指定不同数量的副本，可以使用字典格式。例如：
  • `FOLLOWER_CONSTRAINTS="{+region=us-east-1: 1,+region=us-east-2: 1,+region=us-west-1: 1}";` 表示 1 个 follower 位于 `us-east-1`，1 个 follower 位于 `us-east-2`，1 个 follower 位于 `us-west-1`。
  • `FOLLOWER_CONSTRAINTS='{"+region=us-east-1,+type=scale-node": 1,"+region=us-west-1": 1}';` 表示 1 个 follower 位于 `us-east-1` 区域中有标签 `type` 为 `scale-node` 的节点上，1 个 follower 位于 `us-west-1`。
字典格式支持以 `+` 或 `-` 开头的键，并支持配置特殊的 `#reject-leader` 属性。例如，`FOLLOWER_CONSTRAINTS='{"+region=us-east-1":1, "+region=us-east-2": 2, "+region=us-west-1,#reject-leader": 1}'` 表示当进行容灾时，`us-west-1` 上尽可能驱逐当选的 leader。| > **注意：** > From c9dcdb25034dd17fb9f8c255cd29eaa93e143ac7 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:51:23 +0800 Subject: [PATCH 46/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 4242363d1e80..50315c02fb4f 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -254,7 +254,7 @@ CREATE TABLE t2 (a INT); -- 创建表 t2，默认的放置策略 p2 在 t2 上 CREATE TABLE t3 (a INT) PLACEMENT POLICY=p1; -- 创建表 t3。因为语句中已经指定了其他放置策略，默认的 p2 策略在 t3 上不生效。 -ALTER DATABASE test PLACEMENT POLICY=p3; -- 再次更改默认的放置策略，此更改不影响已有的表。 +ALTER DATABASE test PLACEMENT POLICY=p3; -- 再次更改数据库默认的放置策略，此更改不影响已有的表。 CREATE TABLE t4 (a INT); -- 创建表 t4，默认的放置策略 p3 生效。 From 4a9d4ab203e4cb8cb3a0317f4cf7718779c8955c Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:51:57 +0800 Subject: [PATCH 47/65] Update sql-statements/sql-statement-alter-range.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-alter-range.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md index 277352f3c733..4008061aa43a 100644 --- a/sql-statements/sql-statement-alter-range.md +++ b/sql-statements/sql-statement-alter-range.md @@ -26,7 +26,7 @@ CREATE PLACEMENT POLICY `deploy111` CONSTRAINTS='{"+region=us-east-1":1, "+regio CREATE PLACEMENT POLICY `five_replicas` FOLLOWERS=4; ALTER RANGE global PLACEMENT POLICY = "deploy221"; -ALTER RANGE global PLACEMENT POLICY = "five_replicas"; +ALTER RANGE meta PLACEMENT POLICY = "five_replicas"; ``` 上述示例创建了一个名为 `deploy221` 和 `five_replicas` 的放置策略，为不同的区域指定了约束条件。然后将 `deploy111` 放置策略应用到了整个集群范围内的数据，将 `five_replicas` 放置策略应用到元数据范围内。 \ No newline at end of file From c7526b73e5b740c807b30e38419cc3d2dde3cbbc Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:52:16 +0800 Subject: [PATCH 48/65] Update sql-statements/sql-statement-alter-range.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-alter-range.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md index 4008061aa43a..e3247ad545a2 100644 --- a/sql-statements/sql-statement-alter-range.md +++ b/sql-statements/sql-statement-alter-range.md @@ -16,8 +16,8 @@ AlterRangeStmt ::= 目前 `ALTER RANGE` 能起作用的有 `global` 和 `meta` 两个参数： -- `global`: 表示集群内全域数据的范围 -- `meta`: 表示 TiDB 内部存储的元信息的数据范围 +- `global`：表示集群内全域数据的范围 +- `meta`：表示 TiDB 内部存储的元信息的数据范围 ## 示例 From f492461f90a2c343f2b34f8ada1df0c6eb59c094 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:52:39 +0800 Subject: [PATCH 49/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 50315c02fb4f..69cef6d11dac 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -248,7 +248,7 @@ CREATE PLACEMENT POLICY p3 FOLLOWERS=2; CREATE TABLE t1 (a INT); -- 创建表 t1，且未指定放置策略。 -ALTER DATABASE test PLACEMENT POLICY=p2; -- 更改默认的放置策略，但更改不影响已有的表 t1。 +ALTER DATABASE test PLACEMENT POLICY=p2; -- 更改数据库默认的放置策略为 p2，但更改不影响已有的表 t1。 CREATE TABLE t2 (a INT); -- 创建表 t2，默认的放置策略 p2 在 t2 上生效。 From 0b86405e9b1309a23253d0cda3cd700c38b2bf8c Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:53:05 +0800 Subject: [PATCH 50/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 69cef6d11dac..7049509cc124 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -5,7 +5,7 @@ summary: 了解如何通过 SQL 接口调度表和分区的放置位置。 # Placement Rules in SQL -Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，你可以将集群、数据库、表、或分区的数据部署到不同的地域、机房、机柜、主机。 +Placement Rules in SQL 特性用于通过 SQL 语句配置数据在 TiKV 集群中的放置位置。通过该功能，你可以将集群、数据库、表、或分区的数据部署到不同的地域、机房、机柜、主机。 该功能可以实现以下业务场景： From 8c44732e546ed785997a1bf7be790e1c0440bde1 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:53:28 +0800 Subject: [PATCH 51/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 7049509cc124..b0a640170d75 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -237,7 +237,7 @@ ALTER RANGE global PLACEMENT POLICY five_replicas; ### 为数据库指定默认的放置策略 -你可以为某个数据库指定默认的放置策略，类似于为数据库设置默认字符集或排序规则。如果没有指定其他选项，就会使用数据库上指定的配置。示例如下： +你可以为某个数据库指定默认的放置策略，类似于为数据库设置默认字符集或排序规则。如果数据库中的表或分区没有单独指定其他放置策略，就会使用数据库上指定的放置策略。示例如下： ```sql CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2"; -- 创建放置策略 From 8bd7285acf7b0d3804d646acf6ce217e921fe884 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:53:37 +0800 Subject: [PATCH 52/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index b0a640170d75..b9e72e6fa02e 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -272,8 +272,7 @@ CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; CREATE TABLE t (a INT) PLACEMENT POLICY=five_replicas; -- 创建表 t。绑定放置策略为 five_replicas。 -ALTER TABLE t PLACEMENT POLICY=default; -- 删除表 t 已绑定的放置策略 five_replicas, 重置为默认的放置策略。 - +ALTER TABLE t PLACEMENT POLICY=default; -- 删除表 t 已绑定的放置策略 five_replicas，重置为默认的放置策略。 ``` ### 为分区表指定放置策略 From 273aa7897ba35776c536e4f09eb641d05f639df6 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:53:51 +0800 Subject: [PATCH 53/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index b9e72e6fa02e..6fb314029e82 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -256,7 +256,7 @@ CREATE TABLE t3 (a INT) PLACEMENT POLICY=p1; -- 创建表 t3。因为语句中 ALTER DATABASE test PLACEMENT POLICY=p3; -- 再次更改数据库默认的放置策略，此更改不影响已有的表。 -CREATE TABLE t4 (a INT); -- 创建表 t4，默认的放置策略 p3 生效。 +CREATE TABLE t4 (a INT); -- 创建表 t4，默认的放置策略 p3 在 t4 生效。 ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- 绑定策略 p3 的表，也就是 t4，会采用 FOLLOWERS=3。 ``` From e810196e634ad9c432438ec955bdcdd03faaaf14 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:54:06 +0800 Subject: [PATCH 54/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 6fb314029e82..4b21f7321231 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -261,7 +261,7 @@ CREATE TABLE t4 (a INT); -- 创建表 t4，默认的放置策略 p3 在 t4 生 ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- 绑定策略 p3 的表，也就是 t4，会采用 FOLLOWERS=3。 ``` -注意分区与表之间的继承和这里的继承不同。改变表的放置策略，也会让分区应用新的策略。但是只有建表时没有指定放置策略的时候，表才会从数据库继承放置策略，且之后再改变数据库也不影响已经继承的表。 +注意分区与表之间的继承和这里的继承不同。改变表的默认放置策略，也会让分区应用新的策略。但是只有建表时没有指定放置策略，表才会从数据库继承放置策略，且之后再改变数据库的默认放置策略也不影响已经继承的表。 ### 为表指定放置策略 From e8b00ac0f7448aaca7215f9f0bf567811ab0ff22 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:55:04 +0800 Subject: [PATCH 55/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 4b21f7321231..70ac52da9b28 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -295,7 +295,7 @@ PARTITION BY RANGE( YEAR(purchased) ) ( ); ``` -如果某个分区没有绑定任何放置策略，分区将尝试继承表上可能存在的策略。比如，上面示例中： +如果没有为表中的某个分区指定任何放置策略，该分区将尝试继承表上可能存在的策略。在上面示例中： - `p0` 分区将会应用 `storageforhisotrydata` 策略 - `p4` 分区将会应用 `storagefornewdata` 策略 From 35b7047428c71578c96b13a7a5db15ad8a8db03e Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:55:30 +0800 Subject: [PATCH 56/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 70ac52da9b28..f03daa0bada1 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -310,7 +310,7 @@ ALTER TABLE t1 PARTITION p1 PLACEMENT POLICY=storageforhisotrydata; ## 高可用场景示例 -假设集群的拓扑扑结构如下，集群的 TiKV 数据节点分布在 3 个 `region`（区域），每个 `region` 有 3 个可用的 `zone` （可用区）： +假设集群的拓扑结构如下，集群的 TiKV 节点分布在 3 个 `region`（区域），每个 `region` 有 3 个可用的 `zone` （可用区）： ```sql SELECT store_id,address,label from INFORMATION_SCHEMA.TIKV_STORE_STATUS; From 2c7bc626213f0951b93184acdfc2e98130beebef Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:55:56 +0800 Subject: [PATCH 57/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index f03daa0bada1..5e7bace66a0e 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -382,7 +382,7 @@ SHOW PLACEMENT; CREATE PLACEMENT POLICY deploy221_primary_east1 LEADER_CONSTRAINTS="[+region=us-east-1]" FOLLOWER_CONSTRAINTS='{"+region=us-east-1": 1, "+region=us-east-2": 2, "+region=us-west-1: 1}'; ``` -该语句创建好放置策略后，绑定该策略的数据会将副本中的 Raft Leader 放置在 `us-east-1` 中，其他副本在其他区域。需要注意的是，如果集群发生故障，比如 Leader 所在区域 `us-east-1` 的节点宕机，这时候即使其他区域设置的都是 `FOLLOWER_CONSTRAINTS`, 也会从中选举出一个新的 Leader，也就是说保证服务可用的优先级是最高的。 +该放置策略创建好并绑定到所需的数据后，这些数据的 Raft Leader 副本将会放置在 `LEADER_CONSTRAINTS` 选项指定的 `us-east-1` 区域中，其他副本将会放置在`FOLLOWER_CONSTRAINTS` 选项指定的区域。需要注意的是，如果集群发生故障，比如 Leader 所在区域 `us-east-1` 的节点宕机，这时候即使其他区域设置的都是 `FOLLOWER_CONSTRAINTS`, 也会从中选举出一个新的 Leader，也就是说保证服务可用的优先级是最高的。 在 `us-east-1` 区域故障发生时，如果希望新的 Leader 不要放置在 `us-west-1`，可以配置特殊的 `reject-leader` 属性，驱逐上面新的 Leader: From b1baeafcf8cb16bdb006a1488ff5b80ca88f0a41 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:56:11 +0800 Subject: [PATCH 58/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 5e7bace66a0e..beae8f1ab4f5 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -427,7 +427,7 @@ PLACEMENT POLICY=app_list - 临时表不支持放置策略。 - 放置策略仅保证静态数据被放置在正确的 TiKV 节点上。该策略不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 -- 设置 `TiFlash` 的副本要通过[构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md)的方式创建，不能使用该特性。 +- 设置数据的 TiFlash 副本需要通过[构建 TiFlash 副本](/tiflash/create-tiflash-replicas.md)的方式创建，不能使用该特性。 - 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 ### 工具兼容性 From 19be3758820121db4d7602bcec6074649f5da826 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Tue, 7 Nov 2023 14:56:25 +0800 Subject: [PATCH 59/65] Update placement-rules-in-sql.md Co-authored-by: Grace Cai --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index beae8f1ab4f5..b4a6fa11fa96 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -334,7 +334,7 @@ SELECT store_id,address,label from INFORMATION_SCHEMA.TIKV_STORE_STATUS; 如果你不特别在意数据的具体分布，只希望能满足容灾生存要求，可以使用 `SURVIVAL_PREFERENCES` 选项设置数据的生存能力偏好。 -在上面的例子中， TiDB 集群分布在 3 个 `region`，且每个区域有 3 个 `zone`。在为该集群创建放置策略时，假设 `SURVIVAL_PREFERENCES` 的设置如下： +在上面的例子中，TiDB 集群分布在 3 个 `region`，且每个区域有 3 个 `zone`。在为该集群创建放置策略时，假设 `SURVIVAL_PREFERENCES` 的设置如下： ``` sql CREATE PLACEMENT POLICY multiaz SURVIVAL_PREFERENCES="[region, zone, host]"; From 56251bfc609ba68e7e5af04ea22596dca91e9835 Mon Sep 17 00:00:00 2001 From: nolouch Date: Tue, 7 Nov 2023 14:58:41 +0800 Subject: [PATCH 60/65] address Signed-off-by: nolouch --- TOC.md | 2 +- placement-rules-in-sql.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/TOC.md b/TOC.md index 093e4fff7641..128136131f59 100644 --- a/TOC.md +++ b/TOC.md @@ -724,11 +724,11 @@ - [`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 RANGE`](/sql-statements/sql-statement-alter-range.md) - [`ALTER RESOURCE GROUP`](/sql-statements/sql-statement-alter-resource-group.md) - [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) - [`ALTER TABLE COMPACT`](/sql-statements/sql-statement-alter-table-compact.md) - [`ALTER USER`](/sql-statements/sql-statement-alter-user.md) - - [`ALTER RANGE`](/sql-statements/sql-statement-alter-range.md) - [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md) - [`BACKUP`](/sql-statements/sql-statement-backup.md) - [`BATCH`](/sql-statements/sql-statement-batch.md) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index b4a6fa11fa96..dbd08789add6 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -162,10 +162,10 @@ SHOW PLACEMENT LABELS; 要修改放置策略，可以使用 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 语句。该修改将应用于所有绑定了此放置策略的对象。 ```sql -ALTER PLACEMENT POLICY myplacementpolicy FOLLOWERS=5; +ALTER PLACEMENT POLICY myplacementpolicy FOLLOWERS=4; ``` -在该语句中，`FOLLOWERS=5` 选项代表数据有 5 个副本，包括 4 个 follower 和 1 个 leader。更多可配置的放置选项和对应的含义，请参考[放置选项](#放置选项参考)。 +在该语句中，`FOLLOWERS=4` 选项代表数据有 5 个副本，包括 4 个 follower 和 1 个 leader。更多可配置的放置选项和对应的含义，请参考[放置选项](#放置选项参考)。 ### 删除放置策略 From 5a7eaa2f56db5901fac9cfa471e62db38ec70b85 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 7 Nov 2023 15:42:56 +0800 Subject: [PATCH 61/65] fix format issues --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index dbd08789add6..4dcbb23535cd 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -89,7 +89,7 @@ SHOW PLACEMENT LABELS; ```sql CREATE TABLE t1 (a INT) PLACEMENT POLICY=myplacementpolicy; - CREATE TABLE t2 (a INT);· + CREATE TABLE t2 (a INT); ALTER TABLE t2 PLACEMENT POLICY=myplacementpolicy; ``` From 32865e653b2ac9f91f67691039993bab78c5a97d Mon Sep 17 00:00:00 2001 From: ShuNing Date: Wed, 8 Nov 2023 14:09:15 +0800 Subject: [PATCH 62/65] Update sql-statements/sql-statement-alter-range.md Co-authored-by: xixirangrang --- sql-statements/sql-statement-alter-range.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md index e3247ad545a2..0ad010525fbf 100644 --- a/sql-statements/sql-statement-alter-range.md +++ b/sql-statements/sql-statement-alter-range.md @@ -25,7 +25,7 @@ AlterRangeStmt ::= CREATE PLACEMENT POLICY `deploy111` CONSTRAINTS='{"+region=us-east-1":1, "+region=us-east-2": 1, "+region=us-west-1": 1}'; CREATE PLACEMENT POLICY `five_replicas` FOLLOWERS=4; -ALTER RANGE global PLACEMENT POLICY = "deploy221"; +ALTER RANGE global PLACEMENT POLICY = "deploy111"; ALTER RANGE meta PLACEMENT POLICY = "five_replicas"; ``` From 26c3bb81c2dd2fda9216a683eb1a16887747e224 Mon Sep 17 00:00:00 2001 From: ShuNing Date: Wed, 8 Nov 2023 14:09:23 +0800 Subject: [PATCH 63/65] Update sql-statements/sql-statement-alter-range.md Co-authored-by: xixirangrang --- sql-statements/sql-statement-alter-range.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md index 0ad010525fbf..740895b75f04 100644 --- a/sql-statements/sql-statement-alter-range.md +++ b/sql-statements/sql-statement-alter-range.md @@ -29,4 +29,4 @@ ALTER RANGE global PLACEMENT POLICY = "deploy111"; ALTER RANGE meta PLACEMENT POLICY = "five_replicas"; ``` -上述示例创建了一个名为 `deploy221` 和 `five_replicas` 的放置策略，为不同的区域指定了约束条件。然后将 `deploy111` 放置策略应用到了整个集群范围内的数据，将 `five_replicas` 放置策略应用到元数据范围内。 \ No newline at end of file +上述示例创建了一个名为 `deploy111` 和 `five_replicas` 的放置策略，为不同的区域指定了约束条件。然后将 `deploy111` 放置策略应用到了整个集群范围内的数据，将 `five_replicas` 放置策略应用到元数据范围内。 \ No newline at end of file From a9b9d5af88aa47616644404012c5720671a296c8 Mon Sep 17 00:00:00 2001 From: qiancai Date: Wed, 8 Nov 2023 14:35:28 +0800 Subject: [PATCH 64/65] Update release-6.3.0.md --- releases/release-6.3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/releases/release-6.3.0.md b/releases/release-6.3.0.md index 2ffbbc704e1a..423efc2f70d5 100644 --- a/releases/release-6.3.0.md +++ b/releases/release-6.3.0.md @@ -152,7 +152,7 @@ TiDB 版本：6.3.0-DMR * 解决基于 SQL 的数据放置规则功能和构建 TiFlash 副本功能的冲突 [#37171](https://github.com/pingcap/tidb/issues/37171) @[lcwangchao](https://github.com/lcwangchao) - TiDB 在 v6.0.0 版本提供基于 SQL 的数据放置规则功能，但是由于实现机制问题，该功能和构建 TiFlash 副本功能有冲突。v6.3.0 版本进行改进优化，[解决了这两个功能的冲突](/placement-rules-in-sql.md#使用限制)，使这两个功能更加方便易用。 + TiDB 在 v6.0.0 版本提供[基于 SQL 的数据放置规则](/placement-rules-in-sql.md)功能，但是由于实现机制问题，该功能和构建 TiFlash 副本功能有冲突。v6.3.0 版本进行改进优化，解决了这两个功能的冲突，使这两个功能更加方便易用。 ### MySQL 兼容性 From 6d7252437d255ca8c9579c08055298d973ab385c Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 8 Nov 2023 14:37:22 +0800 Subject: [PATCH 65/65] Update placement-rules-in-sql.md --- placement-rules-in-sql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 4dcbb23535cd..2c817ca133b9 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -81,7 +81,7 @@ SHOW PLACEMENT LABELS; 在该语句中： - `PRIMARY_REGION="us-east-1"` 选项代表 Raft leader 被放置在 `region` 标签为 `us-east-1` 的节点上。 - - `REGIONS="us-east-1,us-west-1"` 选项代表 Raft followers 被放置在`region` 标签为 `us-east-1` 和 `us-west-1` 的节点上。 + - `REGIONS="us-east-1,us-west-1"` 选项代表 Raft followers 被放置在 `region` 标签为 `us-east-1` 和 `region` 标签为 `us-west-1` 的节点上。 更多可配置的放置选项和对应的含义，请参考[放置选项](#放置选项参考)。