diff --git a/TOC.md b/TOC.md index ca9808ef3b6f9..1002877443ad1 100644 --- a/TOC.md +++ b/TOC.md @@ -726,6 +726,7 @@ - [`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) diff --git a/character-set-and-collation.md b/character-set-and-collation.md index d8077292291d1..fdd8b411b1e7a 100644 --- a/character-set-and-collation.md +++ b/character-set-and-collation.md @@ -112,6 +112,8 @@ SHOW COLLATION; > **警告：** > > TiDB 会错误地将 `latin1` 视为 `utf8` 的子集。当用户存储不同于 `latin1` 和 `utf8` 编码的字符时，可能会导致意外情况出现。因此强烈建议使用 `utf8mb4` 字符集。详情参阅 [TiDB #18955](https://github.com/pingcap/tidb/issues/18955)。 +> +> 如果查询条件中包含对字符串前缀的 `LIKE` 过滤， 比如 `LIKE 'prefix%'`，并且该列被设置为非二进制排序规则（即排序规则的后缀不是以 `_bin` 结尾），那么 TiDB 优化器暂时无法把这个过滤条件转化为范围扫描 (Range Scan)，而是用全量扫描代替。因此这类 SQL 有可能造成超出预期的资源消耗。 > **注意：** > diff --git a/character-set-gbk.md b/character-set-gbk.md index 6c99cc3bbcece..57017167bafa0 100644 --- a/character-set-gbk.md +++ b/character-set-gbk.md @@ -88,6 +88,8 @@ SHOW COLLATION WHERE CHARSET = 'gbk'; * 对于 `ENUM` 和 `SET` 类型中的二进制字符，TiDB 目前都会将其作为 `utf8mb4` 字符集处理。 +* 如果查询条件中包含对字符串前缀的 `LIKE` 过滤，比如 `LIKE 'prefix%'`，并且该列被设置为 GBK 的排序规则（`gbk_bin` 或 `gbk_chinese_ci`），那么 TiDB 优化器暂时无法把这个过滤条件转化为范围扫描 (Range Scan)，而是用全量扫描代替。因此这类 SQL 有可能造成超出预期的资源消耗。 + ## 组件兼容性 * TiFlash 目前不支持 GBK 字符集。 diff --git a/develop/dev-guide-sample-application-golang-gorm.md b/develop/dev-guide-sample-application-golang-gorm.md index 495bae3671395..7ac7ea942bd1a 100644 --- a/develop/dev-guide-sample-application-golang-gorm.md +++ b/develop/dev-guide-sample-application-golang-gorm.md @@ -225,7 +225,7 @@ db.Delete(&Player{ID: "id"}) - 关于 GORM 的更多使用方法，可以参考 [GORM 官方文档](https://gorm.io/zh_CN/docs/index.html) 及 GORM 官方文档中的 [TiDB 章节](https://gorm.io/zh_CN/docs/connecting_to_the_database.html#TiDB)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-golang-sql-driver.md b/develop/dev-guide-sample-application-golang-sql-driver.md index ae1fc25c24e07..ab25e9022ae5d 100644 --- a/develop/dev-guide-sample-application-golang-sql-driver.md +++ b/develop/dev-guide-sample-application-golang-sql-driver.md @@ -275,7 +275,7 @@ Golang 驱动程序提供对数据库的底层访问，但要求开发者： - 关于 Go-MySQL-Driver 的更多使用方法，可以参考 [Go-MySQL-Driver 官方文档](https://github.com/go-sql-driver/mysql/blob/master/README.md)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-java-hibernate.md b/develop/dev-guide-sample-application-java-hibernate.md index 40439695b421d..5ff28ee211082 100644 --- a/develop/dev-guide-sample-application-java-hibernate.md +++ b/develop/dev-guide-sample-application-java-hibernate.md @@ -246,7 +246,7 @@ try (Session session = sessionFactory.openSession()) { - 关于 Hibernate 的更多使用方法，可以参考 [Hibernate 官方文档](https://hibernate.org/orm/documentation)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 - 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.com/learner/course/840002/?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.com/learner/course/780002/?utm_source=docs-cn-dev-guide)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-java-jdbc.md b/develop/dev-guide-sample-application-java-jdbc.md index aae478fa728e4..8dc25f5b0eac0 100644 --- a/develop/dev-guide-sample-application-java-jdbc.md +++ b/develop/dev-guide-sample-application-java-jdbc.md @@ -280,7 +280,7 @@ Java 驱动程序提供对数据库的底层访问，但要求开发者： - 关于 MySQL Connector/J 的更多使用方法，可以参考 [MySQL Connector/J 官方文档](https://dev.mysql.com/doc/connector-j/8.1/en/)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 - 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.com/learner/course/840002/?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.com/learner/course/780002/?utm_source=docs-cn-dev-guide)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-java-mybatis.md b/develop/dev-guide-sample-application-java-mybatis.md index a6671ed02c238..ce28fba352b54 100644 --- a/develop/dev-guide-sample-application-java-mybatis.md +++ b/develop/dev-guide-sample-application-java-mybatis.md @@ -296,7 +296,7 @@ public SqlSessionFactory getSessionFactory() { - 关于 MyBatis 的更多使用方法，可以参考 [MyBatis 官方文档](http://www.mybatis.org/mybatis-3/)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 - 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.com/learner/course/840002/?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.com/learner/course/780002/?utm_source=docs-cn-dev-guide)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-java-spring-boot.md b/develop/dev-guide-sample-application-java-spring-boot.md index eba7811eb4438..4213b46603cdc 100644 --- a/develop/dev-guide-sample-application-java-spring-boot.md +++ b/develop/dev-guide-sample-application-java-spring-boot.md @@ -249,7 +249,7 @@ playerRepository.deleteById(id); - [Spring Data JPA 官方文档](https://spring.io/projects/spring-data-jpa) - [Hibernate 官方文档](https://hibernate.org/orm/documentation) - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 - 我们还额外提供针对 Java 开发者的课程：[使用 Connector/J - TiDB v6](https://learn.pingcap.com/learner/course/840002/?utm_source=docs-cn-dev-guide) 及[在 TiDB 上开发应用的最佳实践 - TiDB v6](https://learn.pingcap.com/learner/course/780002/?utm_source=docs-cn-dev-guide)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-nodejs-mysql2.md b/develop/dev-guide-sample-application-nodejs-mysql2.md index 573b74b96ac9d..e49a7502b92f3 100644 --- a/develop/dev-guide-sample-application-nodejs-mysql2.md +++ b/develop/dev-guide-sample-application-nodejs-mysql2.md @@ -285,4 +285,4 @@ console.log(rsh.affectedRows); - 关于 node-mysql2 的更多使用方法，可以参考 [node-mysql2 的 GitHub 仓库](https://github.com/sidorares/node-mysql2)。 - 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)，[更新数据](/develop/dev-guide-update-data.md)，[删除数据](/develop/dev-guide-delete-data.md)，[单表读取](/develop/dev-guide-get-data-from-single-table.md)，[事务](/develop/dev-guide-transaction-overview.md)，[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 \ No newline at end of file +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 \ No newline at end of file diff --git a/develop/dev-guide-sample-application-nodejs-mysqljs.md b/develop/dev-guide-sample-application-nodejs-mysqljs.md index 3153d53b74ca6..b2693a49f2014 100644 --- a/develop/dev-guide-sample-application-nodejs-mysqljs.md +++ b/develop/dev-guide-sample-application-nodejs-mysqljs.md @@ -316,4 +316,4 @@ conn.query('DELETE FROM players WHERE id = ?;', [1], (err, ok) => { - 关于 mysql.js 驱动的更多使用方法，可以参考 [mysql.js 的 GitHub 仓库](https://github.com/mysqljs/mysql)。 - 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)，[更新数据](/develop/dev-guide-update-data.md)，[删除数据](/develop/dev-guide-delete-data.md)，[单表读取](/develop/dev-guide-get-data-from-single-table.md)，[事务](/develop/dev-guide-transaction-overview.md)，[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 \ No newline at end of file +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 \ No newline at end of file diff --git a/develop/dev-guide-sample-application-nodejs-prisma.md b/develop/dev-guide-sample-application-nodejs-prisma.md index e5bdf38e84187..18063cdcae947 100644 --- a/develop/dev-guide-sample-application-nodejs-prisma.md +++ b/develop/dev-guide-sample-application-nodejs-prisma.md @@ -358,4 +358,4 @@ await prisma.player.delete({ - 关于 Prisma 的更多使用方法，可以参考 [Prisma 的官方文档](https://www.prisma.io/docs)。 - 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)，[更新数据](/develop/dev-guide-update-data.md)，[删除数据](/develop/dev-guide-delete-data.md)，[单表读取](/develop/dev-guide-get-data-from-single-table.md)，[事务](/develop/dev-guide-transaction-overview.md)，[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 \ No newline at end of file +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 \ No newline at end of file diff --git a/develop/dev-guide-sample-application-nodejs-typeorm.md b/develop/dev-guide-sample-application-nodejs-typeorm.md index b1c76fc0dc4c0..e556601309080 100644 --- a/develop/dev-guide-sample-application-nodejs-typeorm.md +++ b/develop/dev-guide-sample-application-nodejs-typeorm.md @@ -360,7 +360,7 @@ export class ActionLog { - 关于 TypeORM 的更多使用方法，可以参考 [TypeORM 的官方文档](https://typeorm.io)。 - 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)，[更新数据](/develop/dev-guide-update-data.md)，[删除数据](/develop/dev-guide-delete-data.md)，[单表读取](/develop/dev-guide-get-data-from-single-table.md)，[事务](/develop/dev-guide-transaction-overview.md)，[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-python-django.md b/develop/dev-guide-sample-application-python-django.md index 5229eff5cdbbf..203177bd52483 100644 --- a/develop/dev-guide-sample-application-python-django.md +++ b/develop/dev-guide-sample-application-python-django.md @@ -310,7 +310,7 @@ Player.objects.filter(coins=100).delete() - 关于 Django 的更多使用方法，可以参考 [Django 官方文档](https://www.djangoproject.com/)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-python-mysql-connector.md b/develop/dev-guide-sample-application-python-mysql-connector.md index 6fb47ac4640cf..3831f37ad4474 100644 --- a/develop/dev-guide-sample-application-python-mysql-connector.md +++ b/develop/dev-guide-sample-application-python-mysql-connector.md @@ -263,7 +263,7 @@ Python 驱动程序提供对数据库的底层访问，但要求开发者： - 关于 mysql-connector-python 的更多使用方法，可以参考 [MySQL Connector/Python 官方文档](https://dev.mysql.com/doc/connector-python/en/)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-python-mysqlclient.md b/develop/dev-guide-sample-application-python-mysqlclient.md index 0e533098ca146..97ed22f96afa4 100644 --- a/develop/dev-guide-sample-application-python-mysqlclient.md +++ b/develop/dev-guide-sample-application-python-mysqlclient.md @@ -264,7 +264,7 @@ Python 驱动程序提供对数据库的底层访问，但要求开发者： - 关于 mysqlclient 的更多使用方法，可以参考 [mysqlclient 官方文档](https://mysqlclient.readthedocs.io/)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-python-peewee.md b/develop/dev-guide-sample-application-python-peewee.md index e1fcfae6e1e34..a6e1af0ac6697 100644 --- a/develop/dev-guide-sample-application-python-peewee.md +++ b/develop/dev-guide-sample-application-python-peewee.md @@ -287,7 +287,7 @@ Player.delete().where(Player.coins == 100).execute() - 关于 peewee 的更多使用方法，可以参考 [peewee 官方文档](https://docs.peewee-orm.com/)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-python-pymysql.md b/develop/dev-guide-sample-application-python-pymysql.md index 5b45bdb9a6ed6..13c10e7e5316b 100644 --- a/develop/dev-guide-sample-application-python-pymysql.md +++ b/develop/dev-guide-sample-application-python-pymysql.md @@ -267,7 +267,7 @@ Python 驱动程序提供对数据库的底层访问，但要求开发者： - 关于 PyMySQL 的更多使用方法，可以参考 [PyMySQL 官方文档](https://pymysql.readthedocs.io)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-python-sqlalchemy.md b/develop/dev-guide-sample-application-python-sqlalchemy.md index 2f581b281f79f..2f97c7dfa2265 100644 --- a/develop/dev-guide-sample-application-python-sqlalchemy.md +++ b/develop/dev-guide-sample-application-python-sqlalchemy.md @@ -276,7 +276,7 @@ with Session() as session: - 关于 SQLAlchemy 的更多使用方法，可以参考 [SQLAlchemy 官方文档](https://www.sqlalchemy.org/)。 - 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助? diff --git a/develop/dev-guide-sample-application-ruby-mysql2.md b/develop/dev-guide-sample-application-ruby-mysql2.md index e711c3a32974c..2950a49836a54 100644 --- a/develop/dev-guide-sample-application-ruby-mysql2.md +++ b/develop/dev-guide-sample-application-ruby-mysql2.md @@ -295,7 +295,7 @@ end - 从 [mysql2 的文档](https://github.com/brianmario/mysql2#readme)中了解更多关于 mysql2 驱动的使用情况。 - 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)，[更新数据](/develop/dev-guide-update-data.md)，[删除数据](/develop/dev-guide-delete-data.md)，[单表读取](/develop/dev-guide-get-data-from-single-table.md)，[事务](/develop/dev-guide-transaction-overview.md)，[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助？ diff --git a/develop/dev-guide-sample-application-ruby-rails.md b/develop/dev-guide-sample-application-ruby-rails.md index 5d74d507aab80..898fae33925e6 100644 --- a/develop/dev-guide-sample-application-ruby-rails.md +++ b/develop/dev-guide-sample-application-ruby-rails.md @@ -270,7 +270,7 @@ player.destroy - 从 [ActiveRecord 文档](https://guides.rubyonrails.org/active_record_basics.html)中了解更多关于 ActiveRecord ORM 的用法。 - 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)，[更新数据](/develop/dev-guide-update-data.md)，[删除数据](/develop/dev-guide-delete-data.md)，[单表读取](/develop/dev-guide-get-data-from-single-table.md)，[事务](/develop/dev-guide-transaction-overview.md)，[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 -- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 +- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 ## 需要帮助？ diff --git a/placement-rules-in-sql.md b/placement-rules-in-sql.md index 464a2d3e542c7..2c817ca133b96 100644 --- a/placement-rules-in-sql.md +++ b/placement-rules-in-sql.md @@ -5,118 +5,187 @@ summary: 了解如何通过 SQL 接口调度表和分区的放置位置。 # Placement Rules in SQL -Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，用户可以将表和分区指定部署至不同的地域、机房、机柜、主机。适用场景包括低成本优化数据高可用策略、保证本地的数据副本可用于本地 Stale Read 读取、遵守数据本地要求等。 +Placement Rules in SQL 特性用于通过 SQL 语句配置数据在 TiKV 集群中的放置位置。通过该功能，你可以将集群、数据库、表、或分区的数据部署到不同的地域、机房、机柜、主机。 -> **注意：** +该功能可以实现以下业务场景： + +- 多数据中心部署，配置规则优化数据高可用策略 +- 合并多个不同业务的数据库，物理隔离不同用户的数据，满足实例内部不同用户的隔离需求 +- 增加重要数据的副本数，提高业务可用性和数据可靠性 + +## 功能概述 + +通过 Placement Rules in SQL 功能, 你可以[创建放置策略 (placement policy)](#创建并绑定放置策略)，并为不同的数据级别配置所需的放置策略，粒度从粗到细为： + +| 级别 | 描述 | +|----------------------------|------------------------------------------------------------------------------------------------| +| 集群 | TiDB 默认为集群配置 3 副本的策略。你可以为集群配置全局放置策略，参考[集群配置](#为集群指定全局的副本数)。 | +| 数据库 | 你可以为指定的 Database 配置放置策略，参考[为数据库指定默认的放置策略](#为数据库指定默认的放置策略)。 | +| 表 | 你可以为指定的 Table 配置放置策略，参考[为表指定放置策略](#为表指定放置策略)。 | +| 分区 | 你可以为表中不同的 Row 创建分区，并单独对分区配置放置策略，参考[为分区表指定放置策略](#为分区表指定放置策略)。 | + +> **建议：** > > 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 policy 数量限制在 10 个以内。 +- 建议将绑定了 placement policy 的表和分区数的总数限制在 10000 以内。为过多的表和分区绑定 policy，会增加 PD 上规则计算的负担，从而影响服务性能。 +- 建议按照本文中提到的示例场景使用 Placement Rules in SQL 功能，不建议使用复杂的放置策略。 -## 指定放置规则 +## 前提条件 -指定放置规则，首先需要通过 [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md) 语句创建**放置策略 (placement policy)**。 +放置策略依赖于 TiKV 节点标签 (label) 的配置。例如，放置选项 `PRIMARY_REGION` 依赖 TiKV 中的 `region` 标签。 -```sql -CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"; +创建放置策略时，TiDB 不会检查标签是否存在，而是在绑定放置策略的时候进行检查。因此，在绑定放置策略前，请确保各个 TiKV 节点已配置正确的标签。配置方法为： + +``` +tikv-server --labels region=,zone=,host= ``` -然后可以使用 `CREATE TABLE` 或者 `ALTER TABLE` 将规则绑定至表或分区表，这样就在表或分区上指定了放置规则： +详细配置方法可参考以下示例: + +| 方式 | 示例 | +| --- | --- | +| 手动部署 | [通过拓扑 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 集群中所有可用的标签，可以使用 [`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 TABLE`](/sql-statements/sql-statement-show-create-table.md) 来查看。还可以用 [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.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` 和 `region` 标签为 `us-west-1` 的节点上。 -```sql -tidb> SHOW CREATE TABLE t1\G -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin /*T![placement] PLACEMENT POLICY=`myplacementpolicy` */ -1 row in set (0.00 sec) -tidb> SHOW CREATE PLACEMENT POLICY myplacementpolicy\G -*************************** 1. row *************************** - Policy: myplacementpolicy -Create Policy: CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1" -1 row in set (0.00 sec) -``` + 更多可配置的放置选项和对应的含义，请参考[放置选项](#放置选项参考)。 + +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) 系统表： -你也可以用 [`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.tables` 系统表的 `tidb_placement_policy_name` 列： + + ```sql + SELECT * FROM information_schema.tables WHERE tidb_placement_policy_name IS NOT NULL; + ``` + +- 要查看集群中所有绑定了放置策略的分区，可以查询 `information_schema.partitions` 系统表的 `tidb_placement_policy_name` 列： + + ```sql + SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS NOT NULL; + ``` + +- 所有绑定放置策略的对象都是异步调度的。要查看放置策略的调度进度，可以使用 [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) 语句。 + + ```sql + SHOW PLACEMENT; + ``` + +### 修改放置策略 + +要修改放置策略，可以使用 [`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=4; ``` -`information_schema.tables` 表和 `information_schema.partitions` 表也有一列 `tidb_placement_policy_name`，用于展示所有绑定了放置规则的对象： +在该语句中，`FOLLOWERS=4` 选项代表数据有 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` 选项同时指定，否则会报错。 + +### 常规放置选项 + +常规放置选项可以满足数据放置的基本需求。 | 选项名 | 描述 | |----------------------------|------------------------------------------------------------------------------------------------| @@ -125,72 +194,50 @@ 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]"`。 | +| `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`、`FOLLOWER_CONSTRAINTS`、`LEARNER_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; -``` +| 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。| -`SCHEDULE` 选项指示 TiDB 如何平衡 follower。该选项默认的 `EVEN` 调度规则确保 follower 在所有区域内分布平衡。 +> **注意：** +> +> - `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}'`。因此建议 `:` 后加上空格。 +> -如要保证在主区域内 (`us-east-1`) 放置足够多的 follower 副本，你可以使用 `MAJORITY_IN_PRIMARY` 调度规则来使该区域的 follower 达到指定数量。该调度牺牲一些可用性来换取更低的事务延迟。如果主区域宕机，`MAJORITY_IN_PRIMARY` 无法提供自动故障转移。 +## 基础示例 -### 为分区表指定放置规则 +### 为集群指定全局的副本数 -除了给表绑定放置策略之外，你还可以给表分区绑定放置策略。示例如下： +集群初始化后，副本数默认值为 `3`。集群如需更多的副本数，可使用配置策略调大该值，应用到集群级别，可以使用 [`ALTER RANGE`](/sql-statements/sql-statement-alter-range.md)。示例如下： ```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` 就不会应用任何策略。 +注意，TiDB 默认 leader 个数是 1。因此，5 个副本为 4 个 follower 和 1 个 leader。 -给分区绑定放置策略后，你可以更改指定分区的放置策略。示例如下： - -```sql -ALTER TABLE t1 PARTITION pEurope PLACEMENT POLICY=p1; -``` - -### 为数据库配置默认的放置规则 +### 为数据库指定默认的放置策略 -你可以为某个数据库指定默认的放置策略，类似于为数据库设置默认字符集或排序规则。如果没有指定其他选项，就会使用数据库上指定的配置。示例如下： +你可以为某个数据库指定默认的放置策略，类似于为数据库设置默认字符集或排序规则。如果数据库中的表或分区没有单独指定其他放置策略，就会使用数据库上指定的放置策略。示例如下： ```sql CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2"; -- 创建放置策略 @@ -199,88 +246,195 @@ 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; -- 更改数据库默认的放置策略为 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 生效。 +CREATE TABLE t4 (a INT); -- 创建表 t4，默认的放置策略 p3 在 t4 生效。 ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- 绑定策略 p3 的表，也就是 t4，会采用 FOLLOWERS=3。 ``` -注意分区与表之间的继承和这里的继承不同。改变表的放置策略，也会让分区应用新的策略。但是只有建表时没有指定放置策略的时候，表才会从数据库继承放置策略，且之后再改变数据库也不影响已经继承的表。 +注意分区与表之间的继承和这里的继承不同。改变表的默认放置策略，也会让分区应用新的策略。但是只有建表时没有指定放置策略，表才会从数据库继承放置策略，且之后再改变数据库的默认放置策略也不影响已经继承的表。 -### 高级放置选项 +### 为表指定放置策略 + +你可以为某个表指定默认的放置策略。示例如下： -放置选项 `PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 可满足数据放置的基本需求，但会缺乏一些灵活性。在较复杂的场景下，若需要更灵活地放置数据，可以使用高级放置选项 `CONSTRAINTS` 和 `FOLLOWER_CONSTRAINTS`。`PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 选项不可与 `CONSTRAINTS` 选项同时指定，否则会报错。 +```sql +CREATE PLACEMENT POLICY five_replicas FOLLOWERS=4; -以下示例设置了一个约束，要求数据必须位于某个 TiKV 节点，且该节点的 `disk` 标签必须匹配特定的值： +CREATE TABLE t (a INT) PLACEMENT POLICY=five_replicas; -- 创建表 t。绑定放置策略为 five_replicas。 + +ALTER TABLE t PLACEMENT POLICY=default; -- 删除表 t 已绑定的放置策略 five_replicas，重置为默认的放置策略。 +``` + +### 为分区表指定放置策略 + +你还可以给表分区指定放置策略。示例如下： ```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 ); ``` -该约束可通过列表格式 (`[+disk=ssd]`) 或字典格式 (`{+disk=ssd: 1,+disk=nvme: 2}`) 指定。 +如果没有为表中的某个分区指定任何放置策略，该分区将尝试继承表上可能存在的策略。在上面示例中： -在列表格式中，约束以键值对列表格式。键以 `+` 或 `-` 开头。`+disk=nvme` 表示 `disk` 标签必须设为 `nvme`，`-disk=nvme` 表示 `disk` 标签值不能为 `nvme`。 +- `p0` 分区将会应用 `storageforhisotrydata` 策略 +- `p4` 分区将会应用 `storagefornewdata` 策略 +- `p1`、`p2`、`p3` 分区将会应用表 `t1` 的放置策略 `companystandardpolicy` +- 如果 `t1` 没有绑定任何策略，`p1`、`p2`、`p3` 会继承数据库或全局的默认策略 -在字典格式中，约束还指定了适用于该规则的多个实例。例如，`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}'`。 +```sql +ALTER TABLE t1 PARTITION p1 PLACEMENT POLICY=storageforhisotrydata; +``` -### 生存偏好 +## 高可用场景示例 -在创建或修改放置策略时，你可以使用 `SURVIVAL_PREFERENCES` 选项设置数据的生存能力偏好。 +假设集群的拓扑结构如下，集群的 TiKV 节点分布在 3 个 `region`（区域），每个 `region` 有 3 个可用的 `zone` （可用区）： -例如，假设你的 TiDB 集群分布在 3 个 `zone`（即可用区），且每个可用区的 `host`（即节点）上混合部署了多个 TiKV 实例。在为该集群创建放置策略时，假设 `SURVIVAL_PREFERENCES` 的设置如下： +```sql +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"}] | ++----------+-----------------+--------------------------------------------------------------------------------------------------------------------------+ + +``` + +### 指定生存偏好 + +如果你不特别在意数据的具体分布，只希望能满足容灾生存要求，可以使用 `SURVIVAL_PREFERENCES` 选项设置数据的生存能力偏好。 + +在上面的例子中，TiDB 集群分布在 3 个 `region`，且每个区域有 3 个 `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` 里，优先满足跨 `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 分布 -| 工具名称 | 最低兼容版本 | 说明 | -| --- | --- | --- | -| 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 | 忽略放置规则，不同步规则到下游集群 | +如需特定的数据分布（如 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}'; + +ALTER RANGE global PLACEMENT POLICY = "deploy221"; + +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 分布 -目前已知 Placement Rules in SQL 特性存在以下限制： +你可以通过 Constraints 或 PRIMARY_REGION 指定特殊的 Leader/Follower 的分布。 -* 临时表不支持放置规则。 -* 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。 -* 放置规则仅保证静态数据被放置在正确的 TiKV 节点上。该规则不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。 +#### 使用 Constraints 指定 + +如果你对 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 副本将会放置在 `LEADER_CONSTRAINTS` 选项指定的 `us-east-1` 区域中，其他副本将会放置在`FOLLOWER_CONSTRAINTS` 选项指定的区域。需要注意的是，如果集群发生故障，比如 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 指定 + +如果你的集群拓扑配置了 `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 分布的区域，只能指定一个。 +- `SCHEDULE` 选项指定 TiDB 如何平衡 follower 的分布。 + - 该选项默认的 `EVEN` 调度规则确保 follower 在所有区域内分布平衡。 + - 如需保证在 `PRIMARY_REGION`（即 `us-east-1`）内放置足够多的 follower 副本，你可以使用 `MAJORITY_IN_PRIMARY` 调度规则来使该区域的 follower 达到指定数量。该调度牺牲一些可用性来换取更低的事务延迟。如果主区域宕机，`MAJORITY_IN_PRIMARY` 无法提供自动故障转移。 + +## 数据隔离场景示例 + +以下示例在创建放置策略时，设置了一个约束，要求数据必须放置在配置了指定的 `app` 标签的 TiKV 节点： + +```sql +CREATE PLACEMENT POLICY app_order CONSTRAINTS="[+app=order]"; +CREATE PLACEMENT POLICY app_list CONSTRAINTS="[+app=list_collection]"; +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}`)。 + +执行示例中的语句后，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)。 + +### 工具兼容性 + +| 工具名称 | 最低兼容版本 | 说明 | +| --- | --- | --- | +| 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 | 忽略放置策略，不同步策略到下游集群 | diff --git a/releases/release-6.3.0.md b/releases/release-6.3.0.md index 2ffbbc704e1a4..423efc2f70d5d 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 兼容性 diff --git a/releases/release-6.6.0.md b/releases/release-6.6.0.md index c319c77d2225f..050edd6499f7a 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) @[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) @[gozssky](https://github.com/gozssky) + - 导入时关闭对表外键的检查 [#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) @[gozssky](https://github.com/gozssky) + - 修复冲突处理逻辑 (`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) diff --git a/sql-statements/sql-statement-alter-placement-policy.md b/sql-statements/sql-statement-alter-placement-policy.md index 869b58d22583b..be793aa05dd55 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 ``` ## 示例 diff --git a/sql-statements/sql-statement-alter-range.md b/sql-statements/sql-statement-alter-range.md new file mode 100644 index 0000000000000..740895b75f04c --- /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 内部存储的元信息的数据范围 + +## 示例 + +```sql +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 = "deploy111"; +ALTER RANGE meta PLACEMENT POLICY = "five_replicas"; +``` + +上述示例创建了一个名为 `deploy111` 和 `five_replicas` 的放置策略，为不同的区域指定了约束条件。然后将 `deploy111` 放置策略应用到了整个集群范围内的数据，将 `five_replicas` 放置策略应用到元数据范围内。 \ No newline at end of file diff --git a/sql-statements/sql-statement-create-placement-policy.md b/sql-statements/sql-statement-create-placement-policy.md index 966a5f4737758..83d6971959e74 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 ``` ## 示例 diff --git a/sql-statements/sql-statement-import-into.md b/sql-statements/sql-statement-import-into.md index 65751f28b6fbe..7d76a2af7e725 100644 --- a/sql-statements/sql-statement-import-into.md +++ b/sql-statements/sql-statement-import-into.md @@ -7,10 +7,6 @@ summary: TiDB 数据库中 IMPORT INTO 的使用概况。 `IMPORT INTO` 语句使用 TiDB Lightning 的[物理导入模式](/tidb-lightning/tidb-lightning-physical-import-mode.md)，用于将 `CSV`、`SQL`、`PARQUET` 等格式的数据导入到 TiDB 的一张空表中。 -> **警告：** -> -> 目前该语句为实验特性，不建议在生产环境中使用。 - `IMPORT INTO` 支持导入存储在 Amazon S3、GCS、Azure Blob Storage 和 TiDB 本地的数据文件。 - 对于存储在 S3、GCS 或 Azure Blob Storage 的数据文件，`IMPORT INTO` 支持通过[后端任务分布式框架](/tidb-distributed-execution-framework.md)运行。 @@ -22,7 +18,7 @@ summary: TiDB 数据库中 IMPORT INTO 的使用概况。 ## 使用限制 -- 目前该语句支持导入 1 TiB 以内的数据。 +- 目前该语句支持导入 10 TiB 以内的数据。 - 只支持导入数据到数据库中已有的空表。 - 不支持事务，也无法回滚。在显式事务 (`BEGIN`/`END`) 中执行会报错。 - 在导入完成前会阻塞当前连接，如果需要异步执行，可以添加 `DETACHED` 选项。 @@ -33,6 +29,9 @@ summary: TiDB 数据库中 IMPORT INTO 的使用概况。 - TiDB [临时目录](/tidb-configuration-file.md#temp-dir-从-v630-版本开始引入)至少需要有 90 GiB 的可用空间。建议预留大于等于所需导入数据的存储空间，以保证最佳导入性能。 - 一个导入任务只支持导入数据到一张目标表中。如需导入数据到多张目标表，需要在一张目标表导入完成后，再新建一个任务导入下一张目标表。 - TiDB 集群升级期间不支持使用该语句。 +- 当使用[全局排序](/tidb-global-sort.md)导入数据时，单行数据的总长度不能超过 32 MiB。 +- 当使用全局排序导入数据时，如果 TiDB 集群在导入任务尚未完成时被删除了，Amazon S3 上可能会残留用于全局排序的临时数据。该场景需要手动删除这些数据，以免增加 S3 存储成本。 +- 所需导入的数据不能存在主键或非空唯一索引冲突的记录，否则会导致任务失败。 ## 导入前准备 @@ -131,7 +130,7 @@ SET 表达式左侧只能引用 `ColumnNameOrUserVarList` 中没有的列名。 | `MAX_WRITE_SPEED=''` | 所有格式 | 控制写入到单个 TiKV 的速度，默认无速度限制。例如设置为 `1MiB`，则限制写入速度为 1 MiB/s。| | `CHECKSUM_TABLE=''` | 所有格式 | 配置是否在导入完成后对目标表是否执行 CHECKSUM 检查来验证导入的完整性。可选的配置项为 `"required"`（默认）、`"optional"` 和 `"off"`。`"required"` 表示在导入完成后执行 CHECKSUM 检查，如果 CHECKSUM 检查失败，则会报错退出。`"optional"` 表示在导入完成后执行 CHECKSUM 检查，如果报错，会输出一条警告日志并忽略报错。`"off"` 表示导入结束后不执行 CHECKSUM 检查。 | | `DETACHED` | 所有格式 | 该参数用于控制 `IMPORT INTO` 是否异步执行。开启该参数后，执行 `IMPORT INTO` 会立即返回该导入任务的 `Job_ID` 等信息，且该任务会在后台异步执行。 | -| `CLOUD_STORAGE_URI` | 所有格式 | 指定编码后的 KV 数据[全局排序](#全局排序)的目标存储地址。未指定该参数时，`IMPORT INTO` 会根据系统变量 [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-从-v740-版本开始引入) 的值来确定是否使用全局排序，如果该系统变量指定了目标存储地址，就使用指定的地址进行全局排序。当指定该参数时，如果参数值不为空，`IMPORT INTO` 会使用该参数值作为目标存储地址；如果参数值为空，则表示强制使用本地排序。目前目标存储地址仅支持 Amazon S3，具体 Amazon S3 URI 格式配置，请参见 [Amazon S3 URI 格式](/external-storage-uri.md#amazon-s3-uri-格式)。注意当使用该功能时，所有 TiDB 节点都需要有目标 Amazon S3 bucket 的读写权限。 | +| `CLOUD_STORAGE_URI` | 所有格式 | 指定编码后的 KV 数据[全局排序](/tidb-global-sort.md)的目标存储地址。未指定该参数时，`IMPORT INTO` 会根据系统变量 [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-从-v740-版本开始引入) 的值来确定是否使用全局排序，如果该系统变量指定了目标存储地址，就使用指定的地址进行全局排序。当指定该参数时，如果参数值不为空，`IMPORT INTO` 会使用该参数值作为目标存储地址；如果参数值为空，则表示强制使用本地排序。目前目标存储地址仅支持 Amazon S3，具体 Amazon S3 URI 格式配置，请参见 [Amazon S3 URI 格式](/external-storage-uri.md#amazon-s3-uri-格式)。注意当使用该功能时，所有 TiDB 节点都需要有目标 Amazon S3 bucket 的读写权限。 | ## 压缩文件 @@ -149,6 +148,10 @@ SET 表达式左侧只能引用 `ColumnNameOrUserVarList` 中没有的列名。 ## 全局排序 +> **警告：** +> +> 全局排序为实验特性，不建议在生产环境中使用。 + `IMPORT INTO` 会将源数据文件的导入拆分到多个子任务中，各个子任务独立进行编码排序并导入。如果各个子任务编码后的 KV (TiDB 将数据编码为 KV 的方式，参考 [TiDB 数据库的计算](/tidb-computing.md)) range 重叠过多，导入时 TiKV 需要不断地进行 compaction，会降低导入的性能和稳定性。 在以下情况中，可能存在较多的 KV range 重叠： @@ -157,7 +160,14 @@ SET 表达式左侧只能引用 `ColumnNameOrUserVarList` 中没有的列名。 - 说明：`IMPORT INTO` 会按数据文件遍历顺序来划分子任务，一般遍历文件按文件名字典序来排列。 - 如果目标表索引较多，或索引列值在数据文件中较分散，那么各个子任务编码后产生的索引 KV 也会存在重叠。 -当开启[后端任务分布式框架](/tidb-distributed-execution-framework.md) 时，可通过 `IMPORT INTO` 的 `CLOUD_STORAGE_URI` 参数，或者使用系统变量 [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-从-v740-版本开始引入) 指定编码后的 KV 数据的目标存储地址来开启全局排序。注意目前仅支持使用 S3 作为全局排序存储地址。开启全局排序后，`IMPORT INTO` 会将编码后的 KV 数据写入云存储，并在云存储进行全局排序，之后再将全局排序后的索引数据和表数据并行导入到 TiKV，从而避免因 KV 重叠导致的问题，以提升导入的稳定性。 +当开启[后端任务分布式框架](/tidb-distributed-execution-framework.md) 时，可通过 `IMPORT INTO` 的 `CLOUD_STORAGE_URI` 参数，或者使用系统变量 [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-从-v740-版本开始引入) 指定编码后的 KV 数据的目标存储地址来开启[全局排序](/tidb-global-sort.md)。注意目前仅支持使用 S3 作为全局排序存储地址。开启全局排序后，`IMPORT INTO` 会将编码后的 KV 数据写入云存储，并在云存储进行全局排序，之后再将全局排序后的索引数据和表数据并行导入到 TiKV，从而避免因 KV 重叠导致的问题，以提升导入的稳定性。 + +全局排序对内存资源的使用较高，在数据导入开始前，建议先设置 [`tidb_server_memory_limit_gc_trigger`](/system-variables.md#tidb_server_memory_limit_gc_trigger-从-v640-版本开始引入) 和 [`tidb_server_memory_limit`](/system-variables.md#tidb_server_memory_limit-从-v640-版本开始引入) 两个变量，避免频繁触发 golang GC 从而影响导入效率： + +```sql +SET GLOBAL tidb_server_memory_limit_gc_trigger=0.99; +SET GLOBAL tidb_server_memory_limit='88%'; +``` > **注意：** > diff --git a/system-variables.md b/system-variables.md index b993f6717229d..1880080bf1684 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1396,10 +1396,6 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; ### `tidb_enable_dist_task` 从 v7.1.0 版本开始引入 -> **警告：** -> -> 该功能目前为实验特性，不建议在生产环境中使用。 - - 作用域：GLOBAL - 是否持久化到集群：是 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 diff --git a/tidb-distributed-execution-framework.md b/tidb-distributed-execution-framework.md index 53193c1313d6e..242f6c2b9bc05 100644 --- a/tidb-distributed-execution-framework.md +++ b/tidb-distributed-execution-framework.md @@ -5,10 +5,6 @@ summary: 了解 TiDB 后端任务分布式框架的使用场景与限制、使 # TiDB 后端任务分布式框架 -> **警告：** -> -> 当前该功能为实验特性，不建议在生产环境中使用。 - TiDB 采用计算存储分离架构，具有出色的扩展性和弹性的扩缩容能力。从 v7.1.0 开始，TiDB 引入了一个后端任务分布式执行框架，以进一步发挥分布式架构的资源优势。该框架的目标是实现对所有后端任务的统一调度与分布式执行，并为接入的后端任务提供统一的资源管理能力，从整体和单个后端任务两个维度提供资源管理的能力，更好地满足用户对于资源使用的预期。 本文档介绍了 TiDB 后端任务分布式框架的使用场景与限制、使用方法和实现原理。 diff --git a/tidb-global-sort.md b/tidb-global-sort.md index e25f4850d0880..f40744bc0d07a 100644 --- a/tidb-global-sort.md +++ b/tidb-global-sort.md @@ -41,6 +41,10 @@ TiDB 全局排序功能增强了数据导入和 DDL（数据定义语言）操 SET GLOBAL tidb_cloud_storage_uri = 's3://my-bucket/test-data?role-arn=arn:aws:iam::888888888888:role/my-role' ``` +> **注意：** +> +> [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) 也可使用 [`CLOUD_STORAGE_URI`](/sql-statements/sql-statement-import-into.md#withoptions) 参数来控制云存储路径。如果 [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-从-v740-版本开始引入) 和 `CLOUD_STORAGE_URI` 都设置了有效的云存储路径，[`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) 将以 `CLOUD_STORAGE_URI` 参数的配置为准。 + ## 实现原理 全局排序功能的算法如下图所示： diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md index 67bbe6cf1ff69..306a1c072d617 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -23,6 +23,7 @@ aliases: ['/docs-cn/dev/upgrade-tidb-using-tiup/','/docs-cn/dev/how-to/upgrade/u > **注意：** > > - 如果原集群是 3.0 或 3.1 或更早的版本，不支持直接升级到 v7.4.0 及后续修订版本。你需要先从早期版本升级到 4.0 后，再从 4.0 升级到 v7.4.0 及后续修订版本。 +> - 如果原集群是 6.2 之前的版本，升级到 6.2 及以上版本时，部分场景会遇到升级卡住的情况，你可以参考[如何解决升级卡住的问题](#42-升级到-v620-及以上版本时如何解决升级卡住的问题)。 > - 配置参数 [`server-version`](/tidb-configuration-file.md#server-version) 的值会被 TiDB 节点用于验证当前 TiDB 的版本。因此在进行 TiDB 集群升级前，请将 `server-version` 的值设置为空或者当前 TiDB 真实的版本值，避免出现非预期行为。 ## 1. 升级兼容性说明 @@ -262,7 +263,31 @@ Cluster version: v7.4.0 tiup cluster replay ``` -### 4.2 升级过程中 evict leader 等待时间过长，如何跳过该步骤快速升级 +### 4.2 升级到 v6.2.0 及以上版本时，如何解决升级卡住的问题 + +从 v6.2.0 开始，TiDB 默认开启[并发 DDL 框架](/ddl-introduction.md#tidb-在线-ddl-异步变更的原理)执行并发 DDL。该框架改变了 DDL 作业存储方式，由 KV 队列变为表队列。这一变化可能会导致部分升级场景卡住。下面是一些会触发该问题的场景及解决方案： + +- 加载插件导致的卡住 + + 升级过程中加载部分插件时需要执行 DDL 语句，此时会卡住升级。 + + **解决方案**：升级过程中避免加载插件。待升级完成后再执行插件加载。 + +- 使用 `kill -9` 命令停机升级导致的卡住 + + - 预防措施：避免使用 `kill -9` 命令停机升级。如需使用，应在 2 分钟后再启动新版本 TiDB 节点。 + - 如果升级已经被卡住：重启受影响的 TiDB 节点。如果问题刚发生，建议等待 2 分钟后再重启。 + +- DDL Owner 变更导致的卡住 + + 在多 TiDB 实例场景升级时，网络或机器故障可能引起 DDL Owner 变更。如果此时存在未完成的升级阶段 DDL 语句，升级可能会卡住。 + + **解决方案**： + + 1. 先 Kill 卡住的 TiDB 节点（避免使用 `kill -9`）。 + 2. 重新启动新版本 TiDB 节点。 + +### 4.3 升级过程中 evict leader 等待时间过长，如何跳过该步骤快速升级 可以指定 `--force`，升级时会跳过 `PD transfer leader` 和 `TiKV evict leader` 过程，直接重启并升级版本，对线上运行的集群性能影响较大。命令如下，其中 `` 为升级的目标版本，例如 `v7.4.0`： @@ -272,7 +297,7 @@ Cluster version: v7.4.0 tiup cluster upgrade --force ``` -### 4.3 升级完成后，如何更新 pd-ctl 等周边工具版本 +### 4.4 升级完成后，如何更新 pd-ctl 等周边工具版本 可通过 TiUP 安装对应版本的 `ctl` 组件来更新相关工具版本：