使用 TiUP 升级 TiDB

    • 使用 TiUP 从 TiDB 4.0 版本升级至 TiDB 6.5。
    • 使用 TiUP 从 TiDB 5.0-5.4 版本升级至 TiDB 6.5。
    • 使用 TiUP 从 TiDB 6.0 版本升级至 TiDB 6.5。
    • 使用 TiUP 从 TiDB 6.1 版本升级至 TiDB 6.5。
    • 使用 TiUP 从 TiDB 6.2 版本升级至 TiDB 6.5。
    • 使用 TiUP 从 TiDB 6.3 版本升级至 TiDB 6.5。
    • 使用 TiUP 从 TiDB 6.4 版本升级至 TiDB 6.5。

    警告

    • 不支持将 TiFlash 组件从 5.3 之前的老版本在线升级至 5.3 及之后的版本，只能采用停机升级。如果集群中其他组件（如 tidb，tikv）不能停机升级，参考不停机升级中的注意事项。
    • 在升级 TiDB 集群的过程中，请勿执行 DDL 语句，否则可能会出现行为未定义的问题。

    使用 TiUP 升级 - 图2

    注意

    如果原集群是 3.0 或 3.1 或更早的版本，不支持直接升级到 6.5.0 及后续修订版本。你需要先从早期版本升级到 4.0 后，再从 4.0 升级到 6.5.0 及后续修订版本。

    • TiDB 目前暂不支持版本降级或升级后回退。
    • 使用 TiDB Ansible 管理的 4.0 版本集群，需要先按照 4.0 版本文档的说明将集群导入到 TiUP (tiup cluster) 管理后，再按本文档说明升级到 6.5.1 版本。
    • 若要将 3.0 之前的版本升级至 6.5.1 版本：
      1. 首先。
      2. 然后按照 4.0 版本文档的说明，使用 TiUP (tiup cluster) 将 TiDB Ansible 配置导入。
      3. 将集群升级至 4.0 版本。
      4. 按本文档说明将集群升级到 6.5.1 版本。
    • 支持 TiDB Binlog，TiCDC，TiFlash 等组件版本的升级。
    • 将 v6.3.0 之前的 TiFlash 升级至 v6.3.0 及之后的版本时，需要特别注意：在 Linux AMD64 架构的硬件平台部署 TiFlash 时，CPU 必须支持 AVX2 指令集。而在 Linux ARM64 架构的硬件平台部署 TiFlash 时，CPU 必须支持 ARMv8 架构。具体请参考 中的描述。
    • 具体不同版本的兼容性说明，请查看各个版本的 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 组件版本等准备工作。

    查阅 TiDB release notes 中的兼容性变更。如果有任何变更影响到了你的升级，请采取相应的措施。

    以下为从 v6.4.0 升级至当前版本 (v6.5.2) 所需兼容性变更信息。如果从 v6.3.0 或之前版本升级到当前版本，可能也需要考虑和查看中间版本 release notes 中提到的兼容性变更信息。

    2.2 升级 TiUP 或更新 TiUP 离线镜像

    升级 TiUP 和 TiUP Cluster

    注意

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

    1. 先升级 TiUP 版本（建议 tiup 版本不低于 1.11.0）：

    2. 再升级 TiUP Cluster 版本（建议 tiup cluster 版本不低于 1.11.0）：

      1. tiup update cluster
      2. tiup cluster --version

    更新 TiUP 离线镜像

    使用 TiUP 升级 - 图4

    注意

    如果原集群不是通过离线部署方式部署的，可忽略此步骤。

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

    小贴士

    关于 TiDB-community-server 软件包和 TiDB-community-toolkit 软件包的内容物，请查阅 。

    覆盖升级完成后，需将 server 和 toolkit 两个离线镜像合并，执行以下命令合并离线组件到 server 目录下。

    1. tar xf tidb-community-toolkit-${version}-linux-amd64.tar.gz
    2. ls -ld tidb-community-server-${version}-linux-amd64 tidb-community-toolkit-${version}-linux-amd64
    3. cd tidb-community-server-${version}-linux-amd64/
    4. cp -rp keys ~/.tiup/
    5. tiup mirror merge ../tidb-community-toolkit-${version}-linux-amd64

    离线镜像合并后，执行下列命令升级 Cluster 组件：

    1. tiup update cluster

    此时离线镜像已经更新成功。如果覆盖后发现 TiUP 运行报错，可能是 manifest 未更新导致，可尝试 rm -rf ~/.tiup/manifests/* 后再使用。

    2.3 编辑 TiUP Cluster 拓扑配置文件

    使用 TiUP 升级 - 图6

    注意

    以下情况可跳过此步骤：

    • 升级后对未修改过的配置项希望使用 默认参数。

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

      1. tiup cluster edit-config <cluster-name>

    2. 参考 配置模板的格式，将希望修改的参数填到拓扑文件的 server_configs 下面。

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

    注意

    升级到 6.5.1 版本前，请确认已在 4.0 修改的参数在 6.5.1 版本中是兼容的，可参考 TiKV 配置文件描述。

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

    2.5 检查当前集群的 DDL 和 Backup 情况

    为避免升级过程中出现未定义行为或其他故障，建议检查以下指标后再进行升级操作。

    • 集群 DDL 情况：建议使用 命令查看集群中是否有正在进行的 DDL Job。如需升级，请等待 DDL 执行完成或使用 ADMIN CANCEL DDL 命令取消该 DDL Job 后再进行升级。
    • 集群 Backup 情况：建议使用 命令查看集群中是否有正在进行的 Backup 或者 Restore 任务。如需升级，请等待 Backup 执行完成后，得到一个有效的备份后再执行升级。

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

    3.1 将集群升级到指定版本

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

    不停机升级

    1. tiup cluster upgrade <cluster-name> <version>

    以升级到 6.5.1 版本为例：

    1. tiup cluster upgrade <cluster-name> v6.5.2

    使用 TiUP 升级 - 图8

    注意

    • 滚动升级会逐个升级所有的组件。升级 TiKV 期间，会逐个将 TiKV 上的所有 leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟（300 秒），超时后会直接停止该实例。
    • 使用 --force 参数可以在不驱逐 leader 的前提下快速升级集群至新版本，但是该方式会忽略所有升级中的错误，在升级失败后得不到有效提示，请谨慎使用。
    • 如果希望保持性能稳定，则需要保证 TiKV 上的所有 leader 驱逐完成后再停止该 TiKV 实例，可以指定 --transfer-timeout 为一个更大的值，如 --transfer-timeout 3600，单位为秒。
    • 若想将 TiFlash 从 5.3 之前的版本升级到 5.3 及之后的版本，必须进行 TiFlash 的停机升级。参考如下步骤，可以在确保其他组件正常运行的情况下升级 TiFlash：
      1. 关闭 TiFlash 实例：tiup cluster stop <cluster-name> -R tiflash
      2. 使用 --offline 参数在不重启（只更新文件）的情况下升级集群：tiup cluster upgrade <cluster-name> <version> --offline，例如 tiup cluster upgrade <cluster-name> v6.3.0 --offline
      3. reload 整个集群：tiup cluster reload <cluster-name>。此时，TiFlash 也会正常启动，无需额外操作。
    • 在对使用 TiDB Binlog 的集群进行滚动升级过程中，请避免新创建聚簇索引表。

    停机升级

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

    1. tiup cluster stop <cluster-name>

    之后通过 upgrade 命令添加 --offline 参数来进行停机升级，其中 <cluster-name> 为集群名，<version> 为升级的目标版本，例如 v6.5.2。

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

    1. tiup cluster start <cluster-name>

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

    1. Cluster type:       tidb
    2. Cluster name:       <cluster-name>
    3. Cluster version:    v6.5.2

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

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

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

    1. 使用 tiup cluster audit 命令查看操作记录：

      1. tiup cluster audit

      在其中找到失败的升级操作记录，并记下该操作记录的 ID，下一步中将使用 <audit-id> 表示操作记录 ID 的值。

    2. 使用 tiup cluster replay <audit-id> 命令重试对应操作：

      1. tiup cluster replay <audit-id>

    4.2 升级过程中 evict leader 等待时间过长，如何跳过该步骤快速升级

    可以指定 --force，升级时会跳过 PD transfer leader 和 TiKV evict leader 过程，直接重启并升级版本，对线上运行的集群性能影响较大。命令如下，其中 <version> 为升级的目标版本，例如 v6.5.2：

    1. tiup cluster upgrade <cluster-name> <version> --force