pingcap · ti-chi-bot · May 25, 2023 · May 17, 2023 · May 18, 2023 · May 19, 2023
diff --git a/TOC.md b/TOC.md
@@ -127,6 +127,7 @@
   - 升级 TiDB 版本
     - [使用 TiUP 升级](/upgrade-tidb-using-tiup.md)
     - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/upgrade-a-tidb-cluster)
+    - [平滑升级 TiDB](/smooth-upgrade-tidb.md)
     - [TiFlash v6.2 升级帮助](/tiflash-620-upgrade-guide.md)
   - 扩缩容
     - [使用 TiUP（推荐）](/scale-tidb-using-tiup.md)

diff --git a/faq/upgrade-faq.md b/faq/upgrade-faq.md
@@ -18,9 +18,15 @@ aliases: ['/docs-cn/dev/faq/upgrade-faq/','/docs-cn/dev/faq/upgrade/']
 
 ### 集群在执行 DDL 请求期间可以进行升级操作吗？
 
-集群中有 DDL 语句正在被执行时（通常为 `ADD INDEX` 和列类型变更等耗时较久的 DDL 语句），**请勿进行**升级操作。在升级前，建议使用 [`ADMIN SHOW DDL`](/sql-statements/sql-statement-admin-show-ddl.md) 命令查看集群中是否有正在进行的 DDL Job。如需升级，请等待 DDL 执行完成或使用 [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) 命令取消该 DDL Job 后再进行升级。
+* 从 TiDB 低版本升级至 v7.1 版本时：
 
-另外，在升级 TiDB 集群的过程中，**请勿执行**  DDL 语句，否则可能会出现行为未定义的问题。
+  * 集群中有 DDL 语句正在被执行时（通常为 `ADD INDEX` 和列类型变更等耗时较久的 DDL 语句），**请勿进行**升级操作。在升级前，建议使用 [`ADMIN SHOW DDL`](/sql-statements/sql-statement-admin-show-ddl.md) 命令查看集群中是否有正在进行的 DDL Job。如需升级，请等待 DDL 执行完成或使用 [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) 命令取消该 DDL Job 后再进行升级。
+
+  * 在升级 TiDB 集群的过程中，**请勿执行** DDL 语句，否则可能会出现行为未定义的问题。
+
+* 从 TiDB v7.1 版本升级至更高的版本时：
+
+  * 不用遵循限制低版本升级时的限制，即在升级时可以接收用户 DDL 任务。建议参考[平滑升级 TiDB](/smooth-upgrade-tidb.md)。
 
 ### Binary 如何升级？
 

diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md
@@ -0,0 +1,54 @@
+---
+title: 平滑升级 TiDB
+summary: 本文介绍支持无需手动取消 DDL 的平滑升级集群功能。
+---
+
+# 平滑升级 TiDB
+
+> **警告：**
+>
+> 平滑升级目前为实验特性。
+
+本文档介绍 TiDB 的平滑升级集群功能，支持无需手动取消 DDL 的操作。
+
+平滑升级功能支持从 TiDB v7.1.0 升级至更高的版本，取消了升级过程中的限制，提供更平滑的升级体验。
+
+## 功能简介
+
+TiDB 引入平滑升级功能前，对于升级过程中的 DDL 操作有如下限制(可以参考[使用 TiUP 升级 TiDB](/upgrade-tidb-using-tiup.md#使用-tiup-升级-tidb)中警告部分)：
+
+1. 在升级过程中，请勿执行 DDL 操作，否则可能会出现行为未定义的问题。
+2. 集群中有 DDL 语句正在被执行时（通常为 `ADD INDEX` 和列类型变更等耗时较久的 DDL 语句），请勿进行升级操作。
+
+开启平滑升级后，TiDB 升级过程不再受上述限制。
+
+升级过程中，TiDB 会自动进行以下操作，无需用户干预：
+
+1. 暂停用户的 DDL 操作。
+2. 执行升级过程中的系统 DDL 操作。 
+3. 恢复被暂停的用户的 DDL 操作。
+4. 完成升级。
+
+其中，恢复的 DDL job 仍会按升级前的顺序执行。
+
+## 使用限制
+
+使用平滑升级功能时，需要注意以下限制。
+
+### 用户操作限制
+
+* 在升级前，如果集群中存在正在处理的 canceling DDL job，即有正在被处理的 DDL job 被用户取消了，由于处于 canceling 状态的 job 无法被 `pause`，TiDB 会尝试重试。如果重试失败，会报错并退出升级。
+
+* 在升级过程中，不允许以下操作：
+
+  * 对系统表（`mysql.*`、`information_schema.*`、`performance_schema.*`、`metrics_schema.*`）进行 DDL 操作。
+
+  * 执行手动取消、暂停、恢复 DDL job 操作：`ADMIN CANCEL/PAUSE/RESUME DDL JOBS job_id [, job_id] ...;`。
+
+### 组件使用限制
+
+* 在升级过程中，不支持以下组件操作：
+
+  * BR、Import Data 和通过 ingest 方式导入数据等组件：由于这些操作可能会将处于 paused 状态的 DDL 拷贝到 TiDB 中，而此状态的 DDL 不能自动 resume，可能导致后续 DDL 卡住的情况。因此无法处理此类组件的操作。
+
+  * DM、Import Data 和 TiCDC 等组件。如果在升级过程中使用这些组件向 TiDB 导入 SQL，并且其中包含 DDL 操作，则会阻塞该导入操作，并可能出现未定义错误。
diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md
@@ -19,9 +19,11 @@ aliases: ['/docs-cn/dev/upgrade-tidb-using-tiup/','/docs-cn/dev/how-to/upgrade/u
 
 > **警告：**
 >
-> - 不支持将 TiFlash 组件从 5.3 之前的老版本在线升级至 5.3 及之后的版本，只能采用停机升级。如果集群中其他组件（如 tidb，tikv）不能停机升级，参考[不停机升级](#不停机升级)中的注意事项。
-> - 在升级 TiDB 集群的过程中，**请勿执行** DDL 语句，否则可能会出现行为未定义的问题。
-> - 集群中有 DDL 语句正在被执行时（通常为 `ADD INDEX` 和列类型变更等耗时较久的 DDL 语句），**请勿进行**升级操作。在升级前，建议使用 [`ADMIN SHOW DDL`](/sql-statements/sql-statement-admin-show-ddl.md) 命令查看集群中是否有正在进行的 DDL Job。如需升级，请等待 DDL 执行完成或使用 [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) 命令取消该 DDL Job 后再进行升级。
+> 1. 不支持将 TiFlash 组件从 5.3 之前的老版本在线升级至 5.3 及之后的版本，只能采用停机升级。如果集群中其他组件（如 tidb，tikv）不能停机升级，参考[不停机升级](#不停机升级)中的注意事项。
+> 2. 在升级 TiDB 集群的过程中，**请勿执行** DDL 语句，否则可能会出现行为未定义的问题。
+> 3. 集群中有 DDL 语句正在被执行时（通常为 `ADD INDEX` 和列类型变更等耗时较久的 DDL 语句），**请勿进行**升级操作。在升级前，建议使用 [`ADMIN SHOW DDL`](/sql-statements/sql-statement-admin-show-ddl.md) 命令查看集群中是否有正在进行的 DDL Job。如需升级，请等待 DDL 执行完成或使用 [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) 命令取消该 DDL Job 后再进行升级。
+>
+> 从 TiDB v7.1 版本升级至更高的版本时，可以不遵循上面的限制 2 和 3，建议参考[平滑升级 TiDB 的限制](/smooth-upgrade-tidb.md#使用限制)。
 
 > **注意：**
 >