作者：王贤净、李启航
一、背景 / 目的
本文档适用于对 TiDB 有一定运维经验，希望通过 TiUP 将 4.0 集群升级 5.0 集群的用户。
二、操作前的 Check 项
- 确保当前集群状态与 edit-config 中的拓扑一致
- 确保当前集群的各个组件运行正常
三、升级前的注意事项
3.1 查看 TiDB 的 Release Notes
以 v5.0.0 Release Notes 为例，通过Release Notes了解做了哪些优化或者修复了哪些 BUG。
3.2 升级前注意
- 注意通知业务，升级期间可能会有偶尔的性能抖动，PD Leader 升级可能会有 3s 以上业务不可用的影响；
- 注意预估升级时间 = tikv 个数 * 5 min（默认是 transfer leader 时间） + 10 min，滚动升级 TiKV 时间较长；
- 通知业务注意升级过程中在线事务失败处理；
- 最好做一次完整的数据冷备份，通过 Dumpling 导出业务库；
- 整个升级过程不支持版本回退；
- 升级操作通过中控机的 TiUP 组件完成，默认是 “tidb” 用户。
3.3 升级兼容性说明
- 不支持在升级后回退至 4.0 或更旧版本
- 3.0 之前的版本需要先通过 TiDB Ansible 升级到 3.0 版本，3.0 线上集群升级 4.0 ，先升级到 4.0 ，再升级到 5.0 版本
- 支持 TiDB Binlog，TiCDC，TiFlash 等组件版本的升级。
3.4 目前 TiUP 不支持的功能
- 不支持修改监控告警规则，需要到具体程序目录修改
- 不支持单独对 node_exporter 和 blackbox_exporter 进行安装
- 不支持设置单独机器的 node_exporter 和 blackbox_exporter 端口，需要统一设置端口
3.5 TiDB 4.0 与 TiDB 5.0 参数变量差异
本文仅提及升级前后需要关注的参数变化，完整的参数变更将在后面文档中展示。
3.5.1 配置文件参数 & 系统变量差异 - tidb
| v5.0.0 | v4 | 说明 |
|---|---|---|
| index-limit = 64 | - | 需要注意的&风险点：为了兼容 MySQL，新增 TiDB 单表索引数量的限制（之前无限制） 使用场景：用户需要为单表创建超过 64 索引时会报错，需要调大该值（注意调大之后，与 MySQL 不兼容） 含义：index-limit 用于处理兼容性问题。它只能在 [64,64 *8] |
| deprecate-integer-display-length = false | - | 需要注意的&风险点： 使用场景： 含义：deprecate-integer-display-length 用于兼容 MySQL 8.0，其中使用显示长度声明的整数将返回一个警告，如“integer 显示宽度已弃用，将在未来版本中删除” |
| - | tikv-client.copr-cache.enable = false | 需要注意的&风险点：5.0 中使用 tikv-client.copr-cache.capcity-mb是否为 0 判断是否开启 copr-cache，默认开启 使用场景：NA 含义：是否开启下推计算结果缓存 |
| oom-action = “cancel” | oom-action = “log” | 需要注意的&风险点： 使用场景： 含义：v5.0 使用 cancel 作为默认值，会对写入过程中的内存进行统计，v4.x 则不会。 注: 升级到 5.0 的集群，该配置项保持升级前的值；新部署 5.0 的集群，默认值为 cancel |
| enable-enum-length-limit = true | - | 需要注意的&风险点：是否限制 Enum 的长度，TiDB 旧版本无限制，但 MySQL 规定 Enum 长度 <255(https://github.com/pingcap/tidb/issues/19018) 使用场景：需要与旧 TiDB 兼容 含义：是否开启长度限制 |
| feedback-probability=0.0 | feedback-probability=0.05 | 需要注意的&风险点：该参数是 float 格式 使用场景： 含义： |
3.5.2 - 环境变量差异
| 系统变量 | 4.0-latest | 5.0 | 说明 |
|---|---|---|---|
| Change | |||
| tidb_enable_noop_functions | OFF | OFF | 5.0 之后，tidb_noop_function 将控制 ‘CREATE TEMPORARY TABLE’ 是否允许执行 |
| New | |||
| tidb_allow_fallback_to_tikv | NA | ‘’ | 指示其不可用性触发回退到TiKV的引擎类型,现在我们仅支持TiFlash。 |
| 如果开启 TiFlash，升级完成建议开启该变量。 | |||
| tidb_skip_ascii_check | NA | OFF | 是否对 ascii 字符集的合法范围进行检查（5.0 以前版本默认不检查） |
| tidb_enable_clustered_index | NA | INT_ONLY | 控制在建表语句未指定 clustered/nonclustered 关键字时建立的表是否是聚簇索引表 |
| tidb_enable_strict_double_type_check | NA | ON | 用于决定 create table t(id int, c double(10)); 这样的写法是否允许执行，这种写法在旧版 TiDB 中是允许；MySQL 不允许。考虑到兼容性，添加此方法。 |
| tidb_enable_async_commit | NA | 升级上来的集群为 false。新部署的 5.0 集群为 ture。 含义: 是否开启 async-commit，v5 中建议开启 |
|
| tidb_enable_1pc | NA | 升级上来的集群为 false。新部署的 5.0 集群为 ture。 含义: 是否开启 1pc。建议在 v5 中与 tidb_enable_async_commit - true 一起使用 |
|
| tidb_allow_mpp | NA | ON | 是否开启 MPP |
3.5.3 配置文件参数差异 - tikv
| v5.0.0 | v4 | 说明 |
|---|---|---|
| rocksdb.rate-limiter-auto-tuned = true | rocksdb.auto-tuned = false | 需要注意的&风险点：该配置项在5.0中改名并且默认打开，并且该开关的实现也经过优化。4.0或以前显式使用该功能的用户需要留意。 使用场景： 含义：限制压缩和刷新的磁盘 IO。压缩和刷新会在超过特定阈值时导致严重的峰值。考虑将其设置为磁盘吞吐量的 50％〜80％，以获得更稳定的结果。但是，在繁重的写入工作量中，限制压缩和刷新速度也会导致写入停止。rate-limiter-auto_tuned 根据最近对后台 I / O 的需求，可以在[10MB / s，rate_bytes_per_sec] 范围内动态调整速率限制。 |
| gc.enable-compaction-filter = true | - | 需要注意的&风险点：该功能显著改变了GC的实现，主要风险是数据的正确性。 使用场景： 含义：是否通过压缩过滤器启用GC |
| - | raftstore.sync-log=true | 需要注意的&风险点：5.0中不提供 sync-log 参数，写入数据强制落盘。之前显式关闭 sync-log 的用户需要留意。 使用场景： |
| 含义：数据、log 落盘是否 sync | ||
| pessimistic-txn.pipelined = true | pessimistic-txn.pipelined = false | 需要注意的&风险点： 使用场景：通用悲观事务场景，写多的话大概能提升20%性能 |
3.5.3 配置文件参数差异 - pd
无
上表主要是列出 4.0 和 5.0 存在差异或者被取消的参数，新增的 feature 引入的参数可以参考官方文档。
四、操作步骤
4.1 在中控机上安装 TiUP
- 在中控机上执行如下命令安装 TiUP
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh sh
- 重新声明全局环境变量
source .bash_profile
- 确认 TiUP工具是否安装
which tiup
- 安装 TiUP 的 cluster 工具
tiup cluster
4.2 滚动升级 TiDB 集群
- 通过 tiup cluster upgrade 命令升级集群
tiup cluster upgrade <cluster-name> <version>
以升级到 v5.0.0 版本为例
tiup cluster upgrade <cluster-name> v5.0.0
滚动升级会逐个升级所有的组件。升级 TiKV 期间，会逐个将 TiKV 上的所有 leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟，超过后会直接停止实例。
如果不希望驱逐 leader，而希望立刻升级，可以在上述命令中指定 --force，该方式会造成性能抖动，不会造成数据损失。
如果希望保持性能稳定，则需要保证 TiKV 上的所有 leader 驱逐完成后再停止该 TiKV 实例，可以指定 --transfer-timeout 为一个超大值，如 --transfer-timeout 100000000，单位为 s。
- 通过
tiup cluster display命令查看集群状态
tiup cluster display <cluster-name>
# 会有下面的输出
Starting component `cluster`: /home/tidb/.tiup/components/cluster/v1.4.1/tiup-cluster display <cluster-name>
Cluster type: tidb
Cluster name: <cluster-name>
Cluster version: v5.0.0
SSH type: builtin
Dashboard URL: http://127.0.0.1:2379/dashboard
...
检查 TiDB Version 显示为目标升级版本以及各个实例的 Status 显示为 Up 或 Healthy 表示集群状态正常
五、操作后 Check 监控项
登录 Grafana 页面 http://{grafana-ip}:{grafana-port}
- 查看
overview页面，Overview页面的 `Services Port Status 状态是否均为绿色的 up 状态；
- 查看 TiDB 页面， Query Summary 监控栏的 Duration、QPS、QPS By Instance、Failed Query OPM 监控项是否正常，在每个监控项左上↖️都会有一个“i” 光标放在那里会描述监控项的解释和预期情况；
- 新的 TiKV 相关监控数据主要会展示在 TiKV-Details、TiKV-Summary、TiKV-Trouble-Shooting 中。可以查看 TiKV-Details 页面，通过 Cluster、Error、Server 确认 TiKV 实例的状态的负载以及错误情况。
- 查看 PD 页面，查看 Cluster 监控栏中的 Storage capacity、Current storage size、Current stroage used、Normal stores、Number of Regions 确认当前集群存储数据和 Region 的情况。
六、离线环境升级
TiUP 目前也支持离线环境管理 TiDB 集群，需要搭建离线镜像环境，然后就可以按照在线环境方式使用 tiup。
离线升级方式兼容 【SOP 系列 11】3.0 线上集群升级 4.0
New：新版本的 TiUP，增强 TiUP mirror 命令的功能，支持将多个镜像合并成一个，支持在本地镜像发布组件，支持添加组件所有者到本地镜像，github doc 和 官方的一些说明。
七、周边工具升级
7.1 TiDB Binlog 升级
目前 TiUP 已经支持 Binlog 的管理，所以通过 TiUP 导入的 TiDB Ansible 集群，在升级 TiDB 集群时会同时升级 TiDB Binlog。
7.2.TiFlash 升级
目前 TiUP 已经支持 TiFlash 的管理，在升级 TiDB 集群时会同时升级 TiFlash。
在升级完成后，可以通过查询系统表，或者是按照官网提供的方式查看当前版本信息：
mysql> select type,version from information_schema.cluster_info where type='tiflash';
*************************** 1. row ***************************
type: tiflash
version: v5.0.0
1 row in set (0.00 sec)
7.3.TiCDC 升级
目前 TiUP 已经支持 TiCDC 的管理，在升级 TiDB 集群时会同时升级 TiCDC。
注意：4.0.x 和 5.0.x 之间存在一些兼容性问题，升级完成后，需要使用对应的 cdc-cli / tiup ctl cdc 版本，确保 cdc-cli 和 cdc-server 版本保持一致。#1306
7.4.BR 升级
TiDB 集群升级后，需要确保 BR 的版本和 TiDB 版本相同。BR 升级需要单独操作。下载对应版本的 BR，解压替换老版本的 BR binary 即可完成 BR升级。
wget https://download.pingcap.org/tidb-toolkit-{version}-linux-amd64.tar.gz
八、升级常见问题
8.1 升级之后系统性能下降
通过慢日志确认升级前后是否有执行计划变动，如果有执行计划变动的情况，可以手动收集一下统计信息