- 文档中心
- 关于 TiDB
- 快速上手
- 部署标准集群
- 数据迁移
- 运维操作
- 监控与告警
- 故障诊断
- 性能调优
- 系统调优
- 软件调优
- SQL 性能调优
- SQL 性能调优概览
- 理解 TiDB 执行计划
- SQL 优化流程
- 控制执行计划
- 教程
- 同城多中心部署
- 两地三中心部署
- 同城两中心部署
- 读取历史数据
- 使用 Stale Read 功能读取历史数据(推荐)
- 使用系统变量
tidb_snapshot
读取历史数据
- 最佳实践
- Placement Rules 使用文档
- Load Base Split 使用文档
- Store Limit 使用文档
- TiDB 工具
- 功能概览
- 适用场景
- 工具下载
- TiUP
- 文档地图
- 概览
- 术语及核心概念
- TiUP 组件管理
- FAQ
- 故障排查
- TiUP 命令参考手册
- 命令概览
- TiUP 命令
- TiUP Cluster 命令
- TiUP Cluster 命令概览
- tiup cluster audit
- tiup cluster check
- tiup cluster clean
- tiup cluster deploy
- tiup cluster destroy
- tiup cluster disable
- tiup cluster display
- tiup cluster edit-config
- tiup cluster enable
- tiup cluster help
- tiup cluster import
- tiup cluster list
- tiup cluster patch
- tiup cluster prune
- tiup cluster reload
- tiup cluster rename
- tiup cluster replay
- tiup cluster restart
- tiup cluster scale-in
- tiup cluster scale-out
- tiup cluster start
- tiup cluster stop
- tiup cluster template
- tiup cluster upgrade
- TiUP DM 命令
- TiUP DM 命令概览
- tiup dm audit
- tiup dm deploy
- tiup dm destroy
- tiup dm disable
- tiup dm display
- tiup dm edit-config
- tiup dm enable
- tiup dm help
- tiup dm import
- tiup dm list
- tiup dm patch
- tiup dm prune
- tiup dm reload
- tiup dm replay
- tiup dm restart
- tiup dm scale-in
- tiup dm scale-out
- tiup dm start
- tiup dm stop
- tiup dm template
- tiup dm upgrade
- TiDB 集群拓扑文件配置
- DM 集群拓扑文件配置
- TiUP 镜像参考指南
- TiUP 组件文档
- TiDB Operator
- Dumpling
- TiDB Lightning
- TiDB Data Migration
- Backup & Restore (BR)
- TiDB Binlog
- TiCDC
- TiUniManager
- sync-diff-inspector
- TiSpark
- 参考指南
- 架构
- 监控指标
- 安全加固
- 权限
- SQL
- SQL 语言结构和语法
- SQL 语句
ADD COLUMN
ADD INDEX
ADMIN
ADMIN CANCEL DDL
ADMIN CHECKSUM TABLE
ADMIN CHECK [TABLE|INDEX]
ADMIN SHOW DDL [JOBS|QUERIES]
ADMIN SHOW TELEMETRY
ALTER DATABASE
ALTER INDEX
ALTER INSTANCE
ALTER PLACEMENT POLICY
ALTER TABLE
ALTER USER
ANALYZE TABLE
BACKUP
BEGIN
CHANGE COLUMN
CHANGE DRAINER
CHANGE PUMP
COMMIT
CREATE [GLOBAL|SESSION] BINDING
CREATE DATABASE
CREATE INDEX
CREATE PLACEMENT POLICY
CREATE ROLE
CREATE SEQUENCE
CREATE TABLE LIKE
CREATE TABLE
CREATE USER
CREATE VIEW
DEALLOCATE
DELETE
DESC
DESCRIBE
DO
DROP [GLOBAL|SESSION] BINDING
DROP COLUMN
DROP DATABASE
DROP INDEX
DROP PLACEMENT POLICY
DROP ROLE
DROP SEQUENCE
DROP STATS
DROP TABLE
DROP USER
DROP VIEW
EXECUTE
EXPLAIN ANALYZE
EXPLAIN
FLASHBACK TABLE
FLUSH PRIVILEGES
FLUSH STATUS
FLUSH TABLES
GRANT <privileges>
GRANT <role>
INSERT
KILL [TIDB]
LOAD DATA
LOAD STATS
MODIFY COLUMN
PREPARE
RECOVER TABLE
RENAME INDEX
RENAME TABLE
RENAME USER
REPLACE
RESTORE
REVOKE <privileges>
REVOKE <role>
ROLLBACK
SELECT
SET DEFAULT ROLE
SET [NAMES|CHARACTER SET]
SET PASSWORD
SET ROLE
SET TRANSACTION
SET [GLOBAL|SESSION] <variable>
SHOW [BACKUPS|RESTORES]
SHOW ANALYZE STATUS
SHOW [GLOBAL|SESSION] BINDINGS
SHOW BUILTINS
SHOW CHARACTER SET
SHOW COLLATION
SHOW [FULL] COLUMNS FROM
SHOW CONFIG
SHOW CREATE PLACEMENT POLICY
SHOW CREATE SEQUENCE
SHOW CREATE TABLE
SHOW CREATE USER
SHOW DATABASES
SHOW DRAINER STATUS
SHOW ENGINES
SHOW ERRORS
SHOW [FULL] FIELDS FROM
SHOW GRANTS
SHOW INDEX [FROM|IN]
SHOW INDEXES [FROM|IN]
SHOW KEYS [FROM|IN]
SHOW MASTER STATUS
SHOW PLACEMENT
SHOW PLACEMENT FOR
SHOW PLACEMENT LABELS
SHOW PLUGINS
SHOW PRIVILEGES
SHOW [FULL] PROCESSSLIST
SHOW PROFILES
SHOW PUMP STATUS
SHOW SCHEMAS
SHOW STATS_HEALTHY
SHOW STATS_HISTOGRAMS
SHOW STATS_META
SHOW STATUS
SHOW TABLE NEXT_ROW_ID
SHOW TABLE REGIONS
SHOW TABLE STATUS
SHOW [FULL] TABLES
SHOW [GLOBAL|SESSION] VARIABLES
SHOW WARNINGS
SHUTDOWN
SPLIT REGION
START TRANSACTION
TABLE
TRACE
TRUNCATE
UPDATE
USE
WITH
- 数据类型
- 函数与操作符
- 聚簇索引
- 约束
- 生成列
- SQL 模式
- 表属性
- 事务
- 垃圾回收 (GC)
- 视图
- 分区表
- 临时表
- 字符集和排序
- Placement Rules in SQL
- 系统表
mysql
- INFORMATION_SCHEMA
- Overview
ANALYZE_STATUS
CLIENT_ERRORS_SUMMARY_BY_HOST
CLIENT_ERRORS_SUMMARY_BY_USER
CLIENT_ERRORS_SUMMARY_GLOBAL
CHARACTER_SETS
CLUSTER_CONFIG
CLUSTER_HARDWARE
CLUSTER_INFO
CLUSTER_LOAD
CLUSTER_LOG
CLUSTER_SYSTEMINFO
COLLATIONS
COLLATION_CHARACTER_SET_APPLICABILITY
COLUMNS
DATA_LOCK_WAITS
DDL_JOBS
DEADLOCKS
ENGINES
INSPECTION_RESULT
INSPECTION_RULES
INSPECTION_SUMMARY
KEY_COLUMN_USAGE
METRICS_SUMMARY
METRICS_TABLES
PARTITIONS
PLACEMENT_RULES
PROCESSLIST
REFERENTIAL_CONSTRAINTS
SCHEMATA
SEQUENCES
SESSION_VARIABLES
SLOW_QUERY
STATISTICS
TABLES
TABLE_CONSTRAINTS
TABLE_STORAGE_STATS
TIDB_HOT_REGIONS
TIDB_HOT_REGIONS_HISTORY
TIDB_INDEXES
TIDB_SERVERS_INFO
TIDB_TRX
TIFLASH_REPLICA
TIKV_REGION_PEERS
TIKV_REGION_STATUS
TIKV_STORE_STATUS
USER_PRIVILEGES
VIEWS
METRICS_SCHEMA
- UI
- CLI
- 命令行参数
- 配置文件参数
- 系统变量
- 存储引擎
- 遥测
- 错误码
- 通过拓扑 label 进行副本调度
- 常见问题解答 (FAQ)
- 版本发布历史
- 术语表
你正在查看 TiDB 数据库的较旧版本 (TiDB v5.4) 的文档。
Placement Rules in SQL
Placement Rules in SQL 是 TiDB 在 v5.3.0 中引入的实验特性,其语法在 GA 前可能会发生变化,还可能存在 bug。如果你知晓潜在的风险,可通过执行 SET GLOBAL tidb_enable_alter_placement = 1;
来开启该实验特性。
Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能,用户可以将表和分区指定部署至不同的地域、机房、机柜、主机。适用场景包括低成本优化数据高可用策略、保证本地的数据副本可用于本地 Stale Read 读取、遵守数据本地要求等。
该功能可以实现以下业务场景:
- 合并多个不同业务的数据库,大幅减少数据库常规运维管理的成本
- 增加重要数据的副本数,提高业务可用性和数据可靠性
- 将最新数据存入 NVMe,历史数据存入 SSD,降低归档数据存储成本
- 把热点数据的 leader 放到高性能的 TiKV 实例上
- 将冷数据分离到不同的存储中以提高可用性
指定放置选项
要使用 Placement Rules in SQL 特性,你需要在 SQL 语句中指定一个或多个放置选项 (placement option)。可通过直接放置 (direct placement) 或放置策略 (placement policy) 来指定放置选项。
以下示例中,表 t1
和 t2
的放置规则相同。t1
是通过直接放置指定的规则,而 t2
是通过放置策略来指定的规则。
CREATE TABLE t1 (a INT) PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1";
CREATE PLACEMENT POLICY eastandwest PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1";
CREATE TABLE t2 (a INT) PLACEMENT POLICY=eastandwest;
为了能够更轻松地管理放置规则,推荐使用放置策略来指定规则。当你通过 ALTER PLACEMENT POLICY
更改放置策略后,此更改会自动传播至所有数据库对象。
如果你使用直接放置选项,你需要为每个对象(例如表和分区)都单独更改放置规则。
PLACEMENT POLICY
为全局作用域,不与任何数据库表结构相关联。因此,通过 CREATE TABLE
指定放置策略时,无需任何额外的权限。
放置选项参考
放置选项依赖于正确地指定在每个 TiKV 节点配置中的标签 (label)。例如,
PRIMARY_REGION
选项依赖 TiKV 中的region
标签。若要查看当前 TiKV 集群中所有可用的标签,可执行SHOW PLACEMENT LABELS
语句。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 | Raft leader 被放置在有 region 标签的节点上,且这些 region 标签匹配本选项的值。 |
REGIONS | Raft followers 被放置在有 region 标签的节点上,且这些 region 标签匹配本选项的值。 |
SCHEDULE | 用于调度 follower 放置位置的策略。可选值为 EVEN (默认值)或 MAJORITY_IN_PRIMARY 。 |
FOLLOWERS | Follower 的数量。例如 FOLLOWERS=2 表示数据有 3 个副本(2 个 follower 和 1 个 leader)。 |
除以上配置选项外,你还可以使用高级配置,详细介绍见高级放置。
选项名 | 描述 |
---|---|
CONSTRAINTS | 适用于所有角色 (role) 的约束列表。例如,CONSTRAINTS="[+disk=ssd] 。 |
FOLLOWER_CONSTRAINTS | 仅适用于 follower 的约束列表。 |
示例
增加副本数
max-replicas
配置项的默认值为 3
。如要为特定的表调大该值,可使用配置策略,示例如下:
CREATE PLACEMENT POLICY fivereplicas FOLLOWERS=4;
CREATE TABLE t1 (a INT) PLACEMENT POLICY=fivereplicas;
注意,PD 配置中包含了 leader 数和 follower 数。因此,5 个副本为 4 个 follower + 1 个 leader。
对于以上示例,你还可使用 PRIMARY_REGION
和 REGIONS
选项来描述 follower 的放置规则:
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;
SCHEDULE
选项指示 TiDB 如何平衡 follower。该选项默认的 EVEN
调度规则确保 follower 在所有区域内分布平衡。
如要保证在主区域内 (us-east-1
) 放置足够多的 follower 副本,你可以使用 MAJORITY_IN_PRIMARY
调度规则来使该区域的 follower 达到指定数量。该调度牺牲一些可用性来换取更低的事务延迟。如果主区域宕机,MAJORITY_IN_PRIMARY
无法提供自动故障转移。
为分区表指定放置规则
以下示例使用的 List 分区目前为 TiDB 实验特性。在表的分区功能中,要求主键里包含所有分区函数中使用的列。
除了将放置选项分配给表之外,你还可以将选项分配给表分区。示例如下:
CREATE PLACEMENT POLICY europe PRIMARY_REGION="eu-central-1" REGIONS="eu-central-1,eu-west-1";
CREATE PLACEMENT POLICY northamerica PRIMARY_REGION="us-east-1" REGIONS="us-east-1";
SET tidb_enable_list_partition = 1;
CREATE TABLE t1 (
country VARCHAR(10) NOT NULL,
userdata VARCHAR(100) NOT NULL
) PARTITION BY LIST COLUMNS (country) (
PARTITION pEurope VALUES IN ('DE', 'FR', 'GB') PLACEMENT POLICY=europe,
PARTITION pNorthAmerica VALUES IN ('US', 'CA', 'MX') PLACEMENT POLICY=northamerica
);
为数据库配置默认的放置规则
你可以为某个数据库指定默认的放置选项,类似于为数据库设置默认字符集或排序规则。如果没有指定其他选项,就会使用数据库上指定的配置。示例如下:
CREATE TABLE t1 (a INT); -- 创建表 t1,且未指定放置选项。
ALTER DATABASE test FOLLOWERS=4; -- 更改默认的放置选项,但更改不影响已有的表 t1。
CREATE TABLE t2 (a INT); -- 创建表 t2,默认的放置规则 FOLLOWERS=4 在 t2 上生效。
CREATE TABLE t3 (a INT) PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2"; -- 创建表 t3。因为语句中已经指定了其他放置规则,默认的 FOLLOWERS=4 规则在 t3 上不生效。
ALTER DATABASE test FOLLOWERS=2; -- 再次更改默认的放置选项,此更改不影响已有的表。
CREATE TABLE t4 (a INT); -- 创建表 t4,默认的放置规则 FOLLOWERS=2 生效。
由于只有在创建表时才会从数据库继承放置选项,因此推荐使用 PLACEMENT POLICY
放置策略来设置默认的放置选项。使用后,用户可以通过改动放置策略,改变继承自数据库的放置选项。
高级放置
放置选项 PRIMARY_REGION
、REGIONS
和 SCHEDULE
可满足数据放置的基本需求,但会缺乏一些灵活性。在较复杂的场景下,若需要更灵活地放置数据,可以使用高级放置选项 CONSTRAINTS
和 FOLLOWER_CONSTRAINTS
。PRIMARY_REGION
、REGIONS
和 SCHEDULE
选项不可与 CONSTRAINTS
选项同时指定,否则会报错。
以下示例设置了一个约束,要求数据必须位于某个 TiKV 节点,且该节点的 disk
标签必须匹配特定的值:
CREATE PLACEMENT POLICY storageonnvme CONSTRAINTS="[+disk=nvme]";
CREATE PLACEMENT POLICY storageonssd CONSTRAINTS="[+disk=ssd]";
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 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
);
该约束可通过列表格式 ([+disk=ssd]
) 或字典格式 ({+disk=ssd: 1,+disk=nvme: 2}
) 指定。
在列表格式中,约束以键值对列表格式。键以 +
或 -
开头。+disk=nvme
表示 disk
标签必须设为 nvme
,-disk=nvme
表示 disk
标签值不能为 nvme
。
在字典格式中,约束还指定了适用于该规则的多个实例。例如,FOLLOWER_CONSTRAINTS="{+region=us-east-1:1,+region=us-east-2:1,+region=us-west-1:1,+any:1}";
表示 1 个 follower 位于 us-east-1
,1 个 follower 位于 us-east-2
,1 个 follower 位于 us-west-1
,1 个 follower 可位于任意区域。再例如,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}'。
使用限制
目前已知 Placement Rules in SQL 存在以下限制:
- Dumpling 不支持导出放置策略,见 issue #29371。
- TiDB 生态工具,包括 Backup & Restore (BR)、TiCDC、TiDB Lightning 和 TiDB Data Migration (DM),不支持放置规则。
- 临时表不支持放置选项,直接放置和放置策略均不支持。
- 设置
PRIMARY_REGION
和REGIONS
时允许存在语法糖。但在未来版本中,我们计划为PRIMARY_RACK
、PRIMARY_ZONE
和PRIMARY_HOST
添加变体支持,见 issue #18030。 - 不能通过放置规则语法配置 TiFlash 副本。
- 放置规则仅保证静态数据被放置在正确的 TiKV 节点上。该规则不保证传输中的数据(通过用户查询或内部操作)只出现在特定区域内。