使用 TiUP 升级 TiDB

使用 TiUP 从 TiDB 4.0 版本升级至 TiDB 5.4 及后续修订版本。
使用 TiUP 从 TiDB 5.0 版本升级至 TiDB 5.4 及后续修订版本。
使用 TiUP 从 TiDB 5.1 版本升级至 TiDB 5.4 及后续修订版本。
使用 TiUP 从 TiDB 5.2 版本升级至 TiDB 5.4 及后续修订版本。
使用 TiUP 从 TiDB 5.3 版本升级至 TiDB 5.4 及后续修订版本。

TiDB 目前暂不支持版本降级或升级后回退。
使用 TiDB Ansible 管理的 4.0 版本集群，需要先按照将集群导入到 TiUP (tiup cluster) 管理后，再按本文档说明升级到 5.4 版本及后续修订版本。
若要将 3.0 之前的版本升级至 5.4 版本：
1. 首先通过 TiDB Ansible 升级到 3.0 版本。
2. 然后按照，使用 TiUP (tiup cluster) 将 TiDB Ansible 配置导入。
3. 将集群升级至 4.0 版本。
4. 按本文档说明将集群升级到 5.4 版本。
支持 TiDB Binlog，TiCDC，TiFlash 等组件版本的升级。
具体不同版本的兼容性说明，请查看各个版本的 Release Note。请根据各个版本的 Release Note 的兼容性更改调整集群的配置。
升级 v5.3 之前版本的集群到 v5.3 及后续版本时，默认部署的 Prometheus 会从 v2.8.1 升级到 v2.27.1，v2.27.1 提供更多的功能并解决了安全风险。Prometheus v2.27.1 相对于 v2.8.1 存在 Alert 时间格式变化，详情见。

本部分介绍实际开始升级前需要进行的更新 TiUP 和 TiUP Cluster 组件版本等准备工作。

升级 TiUP 和 TiUP Cluster

注意：

如果原集群中控机不能访问 https://tiup-mirrors.pingcap.com 地址，可跳过本步骤，然后。

先升级 TiUP 版本（建议 tiup 版本不低于 1.9.0）：
再升级 TiUP Cluster 版本（建议 tiup cluster 版本不低于 1.9.0）：
```
 tiup update cluster
 tiup cluster --version
```

更新 TiUP 离线镜像

可以参考的步骤下载部署新版本的 TiUP 离线镜像，上传到中控机。在执行 local_install.sh 后，TiUP 会完成覆盖升级。

tar xzvf tidb-community-server-${version}-linux-amd64.tar.gz
sh tidb-community-server-${version}-linux-amd64/local_install.sh
source /home/tidb/.bash_profile

覆盖升级完成后，执行下列命令升级 Cluster 组件：

tiup update cluster

2.2 编辑 TiUP Cluster 拓扑配置文件

注意：

以下情况可跳过此步骤：

原集群没有修改过配置参数，或通过 tiup cluster 修改过参数但不需要调整。
升级后对未修改过的配置项希望使用 5.4 默认参数。

进入拓扑文件的编辑模式：

 tiup cluster edit-config <cluster-name>

修改完成后 :wq 保存并退出编辑模式，输入 Y 确认变更。

为避免升级过程中出现未定义行为或其他故障，建议在升级前对集群当前的 region 健康状态进行检查，此操作可通过 check 子命令完成。

执行结束后，最后会输出 region status 检查结果。如果结果为 “All regions are healthy”，则说明当前集群中所有 region 均为健康状态，可以继续执行升级；如果结果为 “Regions are not fully healthy: m miss-peer, n pending-peer” 并提示 “Please fix unhealthy regions before other operations.”，则说明当前集群中有 region 处在异常状态，应先排除相应异常状态，并再次检查结果为 “All regions are healthy” 后再继续升级。

本部分介绍如何滚动升级 TiDB 集群以及如何进行升级后的验证。

3.1 将集群升级到指定版本

升级的方式有两种：不停机升级和停机升级。TiUP Cluster 默认的升级 TiDB 集群的方式是不停机升级，即升级过程中集群仍然可以对外提供服务。升级时会对各节点逐个迁移 leader 后再升级和重启，因此对于大规模集群需要较长时间才能完成整个升级操作。如果业务有维护窗口可供数据库停机维护，则可以使用停机升级的方式快速进行升级操作。

不停机升级

tiup cluster upgrade <cluster-name> <version>

tiup cluster upgrade <cluster-name> v5.4.3

注意：

滚动升级会逐个升级所有的组件。升级 TiKV 期间，会逐个将 TiKV 上的所有 leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟（300 秒），超时后会直接停止该实例。
使用 --force 参数可以在不驱逐 leader 的前提下快速升级集群至新版本，但是该方式会忽略所有升级中的错误，在升级失败后得不到有效提示，请谨慎使用。
如果希望保持性能稳定，则需要保证 TiKV 上的所有 leader 驱逐完成后再停止该 TiKV 实例，可以指定 --transfer-timeout 为一个更大的值，如 --transfer-timeout 3600，单位为秒。
若想将 TiFlash 从 5.3 之前的版本升级到 5.3 及之后的版本，必须进行 TiFlash 的停机升级。参考如下步骤，可以在确保其他组件正常运行的情况下升级 TiFlash：

关闭 TiFlash 实例：tiup cluster stop <cluster-name> -R tiflash
使用 --offline 参数在不重启（只更新文件）的情况下升级集群：tiup cluster upgrade <cluster-name> <version> --offline
reload 整个集群：tiup cluster reload <cluster-name>。此时，TiFlash 也会正常启动，无需额外操作。

停机升级

在停机升级前，首先需要将整个集群关停。

tiup cluster stop <cluster-name>

之后通过 upgrade 命令添加 --offline 参数来进行停机升级。

升级完成后集群不会自动启动，需要使用 start 命令来启动集群。

执行 display 命令来查看最新的集群版本 TiDB Version：

tiup cluster display <cluster-name>

Cluster type:       tidb
Cluster name:       <cluster-name>
Cluster version:    v5.4.3

本部分介绍使用 TiUP 升级 TiDB 集群遇到的常见问题。

4.1 升级时报错中断，处理完报错后，如何继续升级

重新执行 tiup cluster upgrade 命令进行升级，升级操作会重启之前已经升级完成的节点。如果不希望重启已经升级过的节点，可以使用 replay 子命令来重试操作，具体方法如下：

使用 tiup cluster audit 命令查看操作记录：
```
 tiup cluster audit
```
在其中找到失败的升级操作记录，并记下该操作记录的 ID，下一步中将使用 <audit-id> 表示操作记录 ID 的值。
使用 tiup cluster replay <audit-id> 命令重试对应操作：
```
 tiup cluster replay <audit-id>
```

4.3 升级完成后，如何更新 pd-ctl 等周边工具版本

可通过 TiUP 安装对应版本的 ctl 组件来更新相关工具版本：

请避免在对使用 TiDB Binlog 的集群进行滚动升级过程中新创建聚簇索引表。

使用 TiUP 升级（推荐）