平滑升级 TiDB

本文档介绍 TiDB 的平滑升级集群功能，支持无需手动取消 DDL 的操作。

从 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 文档。具体版本情况：

    • 从 v7.1.2 以及它之后的 v7.1 版本（即 >= v7.1.2）升级到 v7.4.0 及更高版本
    • 从 v7.4.0 升级到更高的版本

具体版本支持的升级方式，请参考下表：

原版本升级后版本升级的升级方式备注
< v7.1.0任意版本不支持平滑升级方式
v7.1.0v7.1.1、v7.2.0 或 v7.3.0无需额外操作，自动支持平滑升级实验特性。可能遇到 #44760 问题
v7.1.1v7.2.0 或 v7.3.0无需额外操作，自动支持平滑升级实验特性
v7.2.0v7.3.0无需额外操作，自动支持平滑升级实验特性
[v7.1.2, v7.2.0)[v7.1.2, v7.2.0)通过发送 /upgrade/start HTTP 请求开启平滑升级，具体方式有两种：TiUP 方式；其它方式不开启平滑升级时，需确保升级时无 DDL 操作。
[v7.1.2, v7.2.0) 或 >= v7.4.0>= v7.4.0通过发送 /upgrade/start HTTP 请求开启平滑升级，具体方式有两种：TiUP 方式；其它方式不开启平滑升级时，需确保升级时无 DDL 操作。
v7.1.0、v7.1.1、v7.2.0、v7.3.0>= v7.4.0不支持平滑升级方式

功能简介

TiDB 引入平滑升级功能前，对于升级过程中的 DDL 操作有如下限制：

  • 在升级过程中执行 DDL 操作，TiDB 可能会出现未定义的行为。
  • 在 DDL 操作执行过程中升级 TiDB，TiDB 可能会出现未定义的行为。

上述限制可概括为，你需要保证在升级过程中无用户发起的 DDL 操作。引入平滑升级后，TiDB 升级过程不再受此限制。

更多详情，请参考使用 TiUP 升级 TiDB 中的警告部分。

升级方式及步骤

TiUP 方式

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 仍会按升级前的顺序执行。

使用限制

使用平滑升级功能时，需要注意以下限制。

用户操作限制

  • 在升级前有如下两种限制：

    • 如果集群中存在正在处理的 canceling DDL job，即有正在被处理的 DDL job 被用户取消了，由于处于 canceling 状态的 job 无法被 pause，TiDB 会尝试重试。如果重试失败，会报错并退出升级。

    • 如果当前集群版本 < v8.1.0, 且 TiDB 分布式执行框架已启用，请关闭 TiDB 分布式执行框架（即将 tidb_enable_dist_task 设置为 OFF），并确保所有分布式 ADD INDEX 和 IMPORT INTO 任务已完成，或者取消这些任务并等待升级完成后重新开始。否则，升级期间的 ADD INDEX 操作可能导致数据索引不一致。

  • 在使用 TiUP 进行升级的场景下，由于 TiUP 升级存在超时时间，如果在升级之前集群中有大量 DDL（超过 300 条）正在处理队列中等待执行，则此次升级可能会失败。

  • 在升级过程中，不允许以下操作：

    • 对系统表（mysql.*、information_schema.*、performance_schema.*、metrics_schema.*）进行 DDL 操作。

    • 执行手动取消 DDL job 操作：ADMIN CANCEL DDL JOBS job_id [, job_id] ...;。

    • 导入数据。

工具使用限制

在升级过程中，不支持使用以下工具：

  • BR：BR 可能会将处于 paused 状态的 DDL 拷贝到 TiDB 中，而此状态的 DDL 不能自动 resume，可能导致后续 DDL 卡住的情况。

  • DM 和 TiCDC：如果在升级过程中使用 DM 和 TiCDC 向 TiDB 导入 SQL，并且其中包含 DDL 操作，则该导入操作会被阻塞，并可能出现未定义错误。

插件使用限制

TiDB 安装的插件可能自带 DDL 操作。然而，在升级过程中，如果这些插件自带的 DDL 操作针对非系统表进行，可能导致升级过程出现问题。