diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index 98f3cff758b9..ff78e05ae33d 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -5,29 +5,69 @@ summary: 本文介绍支持无需手动取消 DDL 的平滑升级集群功能。 # 平滑升级 TiDB -> **警告:** -> -> 平滑升级目前为实验特性。 - 本文档介绍 TiDB 的平滑升级集群功能,支持无需手动取消 DDL 的操作。 -从 v7.1.0 起,当将 TiDB 升级至更高的版本时,TiDB 支持平滑升级功能,取消了升级过程中的限制,提供更平滑的升级体验。此功能默认开启,且无开关控制。 +从 v7.1.0 起,当将 TiDB 升级至更高的版本时,TiDB 支持平滑升级功能,取消了升级过程中的限制(你需要保证升级过程中无用户发起的 DDL 操作),提供更平滑的升级体验。 + +## 版本支持情况 + +依据是否需要开关控制,可分为两种支持方式: + +* 无需开关控制,默认开启此功能的方式。目前支持此方式的版本分别是 v7.1.0,v7.1.1,v7.2.0,和 v7.3.0。具体支持升级版本的情况: + * 从 v7.1.0 升级到 v7.1.1、v7.2.0 或 v7.3.0 版本 + * 从 v7.1.1 升级到 v7.2.0 或 v7.3.0 版本 + * 从 v7.2.0 升级到 v7.3.0 版本 + +* 通过是否发送 `/upgrade/start` HTTP 请求控制此功能开关。即此功能默认关闭,可通过发送 `/upgrade/start` 请求,开启此功能。具体方式可以参考:[TiDB HTTP API 文档](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md)。具体版本情况: + * 从 v7.1.2 以及它之后的 v7.1 版本(即 >= v7.1.2)升级到 v7.4.0 及更高版本 + * 从 v7.4.0 升级到更高的版本 + +具体版本支持的升级方式,请参考下表: + +| 原版本 | 升级后版本 | 升级的升级方式 | 备注 | +|------|--------|-------------|-------------| +| < v7.1.0 | 任意版本 | 不支持平滑升级方式 | | +| v7.1.0 | v7.1.1、v7.2.0 或 v7.3.0 | 无需额外操作,自动支持平滑升级 | 实验特性。可能遇到 [#44760](https://github.com/pingcap/tidb/pull/44760) 问题 | +| v7.1.1 | v7.2.0 或 v7.3.0 | 无需额外操作,自动支持平滑升级 | 实验特性 | +| v7.2.0 | v7.3.0 | 无需额外操作,自动支持平滑升级 | 实验特性 | +| [v7.1.2, v7.2.0) | [v7.1.2, v7.2.0) | 通过发送 `/upgrade/start` HTTP 请求开启平滑升级,具体方式有两种:[TiUP 方式](#tiup-方式);[其它方式](#其它方式) | 不开启平滑升级时,需确保升级时无 DDL 操作。 | +| [v7.1.2, v7.2.0) 或 >= v7.4.0 | >= v7.4.0 | 通过发送 `/upgrade/start` HTTP 请求开启平滑升级,具体方式有两种:[TiUP 方式](#tiup-方式);[其它方式](#其它方式) | 不开启平滑升级时,需确保升级时无 DDL 操作。 | +| v7.1.0、v7.1.1、v7.2.0、v7.3.0 | >= v7.4.0 | 不支持平滑升级方式 | | ## 功能简介 -TiDB 引入平滑升级功能前,对于升级过程中的 DDL 操作有如下限制(可以参考[使用 TiUP 升级 TiDB](/upgrade-tidb-using-tiup.md#使用-tiup-升级-tidb)中警告部分): +TiDB 引入平滑升级功能前,对于升级过程中的 DDL 操作有如下限制: - 在升级过程中执行 DDL 操作,TiDB 可能会出现未定义的行为。 - 在 DDL 操作执行过程中升级 TiDB,TiDB 可能会出现未定义的行为。 -引入平滑升级后,TiDB 升级过程不再受上述限制。 +上述限制可概括为,你需要保证在升级过程中无用户发起的 DDL 操作。引入平滑升级后,TiDB 升级过程不再受此限制。 + +更多详情,请参考[使用 TiUP 升级 TiDB](/upgrade-tidb-using-tiup.md#使用-tiup-升级-tidb) 中的警告部分。 + +### 升级方式及步骤 -升级过程中,TiDB 会自动进行以下操作,无需用户干预: +#### TiUP 方式 -1. 暂停用户的 DDL 操作。 -2. 执行升级过程中的系统 DDL 操作。 -3. 恢复被暂停的用户的 DDL 操作。 -4. 完成升级。 +TiUP 会在 v1.14.0 版本自适应支持此功能,即无需特殊操作,直接使用 `tiup cluster upgrade` 操作流程即可。注意目前不支持 `tiup cluster patch` 方式。 + +#### TiDB Operator 方式 + +目前不支持此功能,会尽早自适应支持此功能。 + +#### 其它方式 + +手动升级或者使用脚本升级的操作如下: + +1. 给集群中的任意一台 TiDB 发送 HTTP 升级开始请求:`curl -X POST http://{TiDBIP}:10080/upgrade/start`。 + * TiDB 集群会进入 **Upgrading** 状态。 + * 接下来将要执行的 DDL 操作都会被暂停。 + +2. 替换 TiDB binary,并进行滚动升级。此过程和原升级过程一致。 + * 执行升级过程中的系统 DDL 操作。 + +3. 等集群中所有 TiDB 升级成功后,给任意一台 TiDB 发送 HTTP 升级结束请求:`curl -X POST http://{TiDBIP}:10080/upgrade/finish`。 + * 恢复被暂停的用户的 DDL 操作。 其中,恢复的 DDL job 仍会按升级前的顺序执行。 @@ -56,3 +96,7 @@ TiDB 引入平滑升级功能前,对于升级过程中的 DDL 操作有如下 * BR:BR 可能会将处于 paused 状态的 DDL 拷贝到 TiDB 中,而此状态的 DDL 不能自动 resume,可能导致后续 DDL 卡住的情况。 * DM 和 TiCDC:如果在升级过程中使用 DM 和 TiCDC 向 TiDB 导入 SQL,并且其中包含 DDL 操作,则该导入操作会被阻塞,并可能出现未定义错误。 + +### 插件使用限制 + +TiDB 安装的插件可能自带 DDL 操作。然而,在升级过程中,如果这些插件自带的 DDL 操作针对非系统表进行,可能导致升级过程出现问题。 \ No newline at end of file