From 0800babfdc346af60056ecb5d4a8c3326a2cbd61 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 13:43:24 +0800 Subject: [PATCH 01/18] Create roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 117 +++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 roll-back-tidb-using-tiup.md diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md new file mode 100644 index 000000000000..7ffc2b06140f --- /dev/null +++ b/roll-back-tidb-using-tiup.md @@ -0,0 +1,117 @@ +--- +title: 使用 TiUP 回退 TiDB 的版本 +summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回退到某个版本。 +--- + +# 使用 TiUP 回退 TiDB 的版本 + +本文档介绍如何使用 TiUP 将 TiDB 回退到之前的某个版本。 + +## 支持回退的版本 + +本文档适用于以下回退路径： + +- 使用 TiDB 从 v7.5.Y 版本回退至 v7.5.X，其中 Y 和 X 是大于 0 的整数，且 Y>X。 + +其他补丁版本的回退未经验证，如直接回退，可能会产生非预期的问题。 + +## 注意事项 + + +回退版本时，请注意以下事项： + +- 对于无法进行连接重试的客户端，版本回退会导致连接到被关闭的 TiDB 节点的数据库的连接失效，造成部分业务请求失败。对于这类业务，推荐在客户端添加重试功能，或者在低峰期进行 TiDB 的滚动更新操作。 +- 在回退 TiDB 集群的过程中，请勿执行 DDL 语句，否则可能会出现行为未定义的问题。 +- 回退的集群内的各组件应该使用相同版本。 +- Changefeed 默认配置值在回退过程中不会被更改，已经修改的值，在回退过程中也不会被修改。 +- 配置参数 [`server-version`](/tidb-configuration-file.md#server-version) 的值会被 TiDB 节点用于验证当前 TiDB 的版本。因此在进行 TiDB 集群回退前，请将 `server-version` 的值设置为空或者当前 TiDB 真实的版本值，避免出现非预期行为。 +- 配置项 [`performance.force-init-stats`](/tidb-configuration-file.md#force-init-stats-从-v657-和-v710-版本开始引入) 设置为 `true` 会延长 TiDB 的启动时间，这可能会造成启动超时，回退失败。为避免这种情况，建议为 TiUP 设置更长的等待超时。可能受影响的场景： + - 原集群版本低于 v6.5.7、v7.1.0（尚未支持 `performance.force-init-stats`），目标版本为 v7.2.0 或更高。 + - 原集群版本高于或等于 v6.5.7、v7.1.0，且配置项 `performance.force-init-stats` 被设置为 `true`。 + + 设置 TiUP 的等待超时的步骤如下： + + 1. 查看配置项 `performance.force-init-stats` 的值。通常情况下，`20` 分钟超时等待能满足绝大部分场景的需求。如果需要更准确的预估，可以在 TiDB 日志中搜索 `init stats info time` 关键字，获取上次启动的统计信息加载时间作为参考。 + + 2. 通过增加命令行选项 [`--wait-timeout`](/tiup/tiup-component-dm.md#--wait-timeoutuint默认-120) 设置 TiUP 超时等待时间。如下命令可将超时等待设置为 `1200` 秒（即 `20` 分钟）: + + ```shell + `tiup update cluster --wait-timeout 1200 [other options]` + ``` + +## 回退兼容性说明 + +- TiDB 目前仅支持有限的补丁版本回退。请参见[支持回退的版本](#支持回退的版本)。 +- 仅支持 PD、TiDB、TiKV、TiFlash、TiCDC、BR、PITR 这些组件的补丁版本回退。 +- 具体不同版本的兼容性说明，请查看各个版本的 Release Note。请根据各个版本的 Release Note 的兼容性更改调整集群的配置。 + +## 回退前的准备工作 + +开始回退前需要更新 TiUP 和 TiUP 集群组件版本等。 + +### 查阅兼容性变更 + +查看对应版本的 [Release Notes](/releases/release-notes.md) 中的兼容性变更。如果有任何变更影响到回退，请采取相应的措施。 + +### 检查当前集群的 DDL + +集群中有 DDL 语句正在被执行时，请勿进行版本回退操作。被执行的 DDL 语句通常为 [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) 和列类型变更等耗时较久的 DDL 语句。 + +在回退前，为避免回退过程中出现未定义行为或其他故障，建议执行下列操作： + +1. 使用 [`ADMIN SHOW DDL`](/sql-statements/sql-statement-admin-show-ddl.md) 命令查看集群中是否有正在进行的 DDL Job。 + +2. 如需回退，请等待 DDL 执行完成，或使用 [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) 命令取消该 DDL Job。 + +### 检查当前集群的健康状况 + +为避免回退过程中出现未定义行为或其他故障，建议在回退前对使用 `check` 子命令检查集群的 Region 健康状态。 + +```shell +tiup cluster check --cluster +``` + +执行结束后，会输出 `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 会对各节点逐个迁移 leader 后再回退和重启。对于大规模集群需要较长时间才能完成整个回退操作，因此请提前预估预留足够的时间。 + +以 v7.5.1 回退到 v7.5.0 版本为例，执行下列命令： + +```shell +tiup ctl:v7.5.0 pd config set cluster-version "v7.5.0" -u \"pd-1-peer:2379\" +tiup cluster patch {cluster_name} {/tmp/cdc-v7.5.0-linux-amd64.tar.gz} -R cdc -y +tiup cluster patch {cluster_name} {/tmp/tidb-v7.5.0-linux-amd64.tar.gz} -R tidb -y +tiup cluster patch {cluster_name} {/tmp/tikv-v7.5.0-linux-amd64.tar.gz} -R tikv -y +tiup cluster patch {cluster_name} {/tmp/pd-v7.5.0-linux-amd64.tar.gz} -R pd -y +tiup cluster patch {cluster_name} {/tmp/tiflash-v7.5.0-linux-amd64.tar.gz} -R tiflash -y +``` + +注意以下事项： + +- 一定要按上面的顺序执行回退操作。 +- 滚动回退会逐个回退所有的组件。回退 TiKV 期间，会逐个将 TiKV 上的所有 leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟（300 秒），超时后会直接停止该实例。 +- 使用 [`--force`](/tiup//tiup-component-cluster-upgrade.md#--force) 参数可以在不驱逐 leader 的前提下快速回退集群至指定版本，但是该方式会忽略所有回退中的错误，在回退失败后得不到有效提示，请谨慎使用。 +- 如果希望保持性能稳定，则需要保证 TiKV 上的所有 leader 驱逐完成后再停止该 TiKV 实例，可以指定 [`--transfer-timeout`](/tiup/tiup-component-cluster-reload.md#--transfer-timeoutuint默认-600) 为一个更大的值，如 `--transfer-timeout 3600`，单位为秒。 + +## 验证回退结果 + +执行 `display` 命令来查看最新的集群版本 TiDB 版本： + +```shell +tiup cluster display +``` + +输出结果如下，版本成功回退到 v7.5.0： + +```shell +Cluster type: tidb +Cluster name: +Cluster version: v7.5.0 +``` From 5822f42310832b5ee1c16de6474edbca2747f0d8 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 13:46:02 +0800 Subject: [PATCH 02/18] Update TOC.md --- TOC.md | 1 + 1 file changed, 1 insertion(+) diff --git a/TOC.md b/TOC.md index 63387eaa0a22..6d3b53d928fb 100644 --- a/TOC.md +++ b/TOC.md @@ -158,6 +158,7 @@ - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/upgrade-a-tidb-cluster) - [平滑升级 TiDB](/smooth-upgrade-tidb.md) - [TiFlash 升级帮助](/tiflash-upgrade-guide.md) + - [回退 TiDB 版本](/roll-back-tidb-using-tiup.md) - 扩缩容 - [使用 TiUP（推荐）](/scale-tidb-using-tiup.md) - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/scale-a-tidb-cluster) From 1ceba4b63764c4abda082a234693c7ac2e1e0273 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 13:48:00 +0800 Subject: [PATCH 03/18] Update TOC.md --- TOC.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/TOC.md b/TOC.md index 6d3b53d928fb..45da0d4bc473 100644 --- a/TOC.md +++ b/TOC.md @@ -158,7 +158,9 @@ - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/upgrade-a-tidb-cluster) - [平滑升级 TiDB](/smooth-upgrade-tidb.md) - [TiFlash 升级帮助](/tiflash-upgrade-guide.md) - - [回退 TiDB 版本](/roll-back-tidb-using-tiup.md) + - 回退 TiDB 版本 + - [使用 TiUP](/roll-back-tidb-using-tiup.md) + - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/upgraderoll-back-a-tidb-cluster) - 扩缩容 - [使用 TiUP（推荐）](/scale-tidb-using-tiup.md) - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/scale-a-tidb-cluster) From 98f8daa52cfa64398b72d6b50c925937864eb3a5 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 13:49:23 +0800 Subject: [PATCH 04/18] Update TOC.md --- TOC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TOC.md b/TOC.md index 45da0d4bc473..63754c7280dc 100644 --- a/TOC.md +++ b/TOC.md @@ -160,7 +160,7 @@ - [TiFlash 升级帮助](/tiflash-upgrade-guide.md) - 回退 TiDB 版本 - [使用 TiUP](/roll-back-tidb-using-tiup.md) - - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/upgraderoll-back-a-tidb-cluster) + - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/roll-back-a-tidb-cluster) - 扩缩容 - [使用 TiUP（推荐）](/scale-tidb-using-tiup.md) - [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/stable/scale-a-tidb-cluster) From e5e6059e69aee2d450ab1c66366866b02a55d5e1 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 13:50:14 +0800 Subject: [PATCH 05/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index 7ffc2b06140f..0808fab8621d 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -29,11 +29,11 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 - 原集群版本低于 v6.5.7、v7.1.0（尚未支持 `performance.force-init-stats`），目标版本为 v7.2.0 或更高。 - 原集群版本高于或等于 v6.5.7、v7.1.0，且配置项 `performance.force-init-stats` 被设置为 `true`。 - 设置 TiUP 的等待超时的步骤如下： +设置 TiUP 的等待超时的步骤如下： - 1. 查看配置项 `performance.force-init-stats` 的值。通常情况下，`20` 分钟超时等待能满足绝大部分场景的需求。如果需要更准确的预估，可以在 TiDB 日志中搜索 `init stats info time` 关键字，获取上次启动的统计信息加载时间作为参考。 +1. 查看配置项 `performance.force-init-stats` 的值。通常情况下，`20` 分钟超时等待能满足绝大部分场景的需求。如果需要更准确的预估，可以在 TiDB 日志中搜索 `init stats info time` 关键字，获取上次启动的统计信息加载时间作为参考。 - 2. 通过增加命令行选项 [`--wait-timeout`](/tiup/tiup-component-dm.md#--wait-timeoutuint默认-120) 设置 TiUP 超时等待时间。如下命令可将超时等待设置为 `1200` 秒（即 `20` 分钟）: +2. 通过增加命令行选项 [`--wait-timeout`](/tiup/tiup-component-dm.md#--wait-timeoutuint默认-120) 设置 TiUP 超时等待时间。如下命令可将超时等待设置为 `1200` 秒（即 `20` 分钟）: ```shell `tiup update cluster --wait-timeout 1200 [other options]` From 4e22c91a5dfb325a4ed1421af5da5ec3281584eb Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 14:32:15 +0800 Subject: [PATCH 06/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index 0808fab8621d..ac67f250e3fb 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -39,19 +39,18 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 `tiup update cluster --wait-timeout 1200 [other options]` ``` -## 回退兼容性说明 - -- TiDB 目前仅支持有限的补丁版本回退。请参见[支持回退的版本](#支持回退的版本)。 -- 仅支持 PD、TiDB、TiKV、TiFlash、TiCDC、BR、PITR 这些组件的补丁版本回退。 -- 具体不同版本的兼容性说明，请查看各个版本的 Release Note。请根据各个版本的 Release Note 的兼容性更改调整集群的配置。 - ## 回退前的准备工作 开始回退前需要更新 TiUP 和 TiUP 集群组件版本等。 -### 查阅兼容性变更 +### 兼容性变更 + +- TiDB 目前仅支持有限的补丁版本回退。请参见[支持回退的版本](#支持回退的版本)。 +- 仅支持 PD、TiDB、TiKV、TiFlash、TiCDC、BR、PITR 这些组件的补丁版本回退。 +- 查看对应版本的 [Release Notes](/releases/release-notes.md) 中的兼容性变更。如果有任何变更影响到回退，请采取相应的措施。例如，从 TiDB v7.5.2 回退至 v7.5.1 时，需查阅以下各版本的兼容性变更： -查看对应版本的 [Release Notes](/releases/release-notes.md) 中的兼容性变更。如果有任何变更影响到回退，请采取相应的措施。 + - [TiDB v7.5.1 Release Notes](/releases/release-7.5.1#兼容性变更) 中的兼容性变更 + - [TiDB v7.5.2 Release Notes](/releases/release-7.5.2#兼容性变更) 中的兼容性变更 ### 检查当前集群的 DDL From 60adbc071849d73659ef98a509fb45edf783d0f7 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 14:51:52 +0800 Subject: [PATCH 07/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index ac67f250e3fb..102bdd936dbe 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -17,7 +17,6 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 ## 注意事项 - 回退版本时，请注意以下事项： - 对于无法进行连接重试的客户端，版本回退会导致连接到被关闭的 TiDB 节点的数据库的连接失效，造成部分业务请求失败。对于这类业务，推荐在客户端添加重试功能，或者在低峰期进行 TiDB 的滚动更新操作。 @@ -49,8 +48,8 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 - 仅支持 PD、TiDB、TiKV、TiFlash、TiCDC、BR、PITR 这些组件的补丁版本回退。 - 查看对应版本的 [Release Notes](/releases/release-notes.md) 中的兼容性变更。如果有任何变更影响到回退，请采取相应的措施。例如，从 TiDB v7.5.2 回退至 v7.5.1 时，需查阅以下各版本的兼容性变更： - - [TiDB v7.5.1 Release Notes](/releases/release-7.5.1#兼容性变更) 中的兼容性变更 - - [TiDB v7.5.2 Release Notes](/releases/release-7.5.2#兼容性变更) 中的兼容性变更 + - [TiDB v7.5.1 Release Notes](/releases/release-7.5.1.md#兼容性变更) 中的兼容性变更 + - [TiDB v7.5.2 Release Notes](/releases/release-7.5.2.md#兼容性变更) 中的兼容性变更 ### 检查当前集群的 DDL From 49d8cb258b7b404a8f29216689d60f0c391c0d01 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 15:03:51 +0800 Subject: [PATCH 08/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index 102bdd936dbe..ba9eb1456728 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -40,7 +40,7 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 ## 回退前的准备工作 -开始回退前需要更新 TiUP 和 TiUP 集群组件版本等。 +开始回退前需要[更新 TiUP 和 TiUP 集群组件版本](/tiup/tiup-component-management.md#升级组件)。 ### 兼容性变更 From 6badb6d57e6c985cc992298f10b5cd326b3944ca Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 15:05:38 +0800 Subject: [PATCH 09/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index ba9eb1456728..331464976e51 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -35,7 +35,7 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 2. 通过增加命令行选项 [`--wait-timeout`](/tiup/tiup-component-dm.md#--wait-timeoutuint默认-120) 设置 TiUP 超时等待时间。如下命令可将超时等待设置为 `1200` 秒（即 `20` 分钟）: ```shell - `tiup update cluster --wait-timeout 1200 [other options]` + tiup update cluster --wait-timeout 1200 [other options] ``` ## 回退前的准备工作 From e7f7e941ce26fd06036fe483377189ec7893da71 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 15:27:48 +0800 Subject: [PATCH 10/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 52 +++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 21 deletions(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index 331464976e51..4989128d4a58 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -11,9 +11,9 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 本文档适用于以下回退路径： -- 使用 TiDB 从 v7.5.Y 版本回退至 v7.5.X，其中 Y 和 X 是大于 0 的整数，且 Y>X。 +- 从 v7.5.Y 版本回退至 v7.5.X，其中 Y 和 X 是大于 0 的整数，且 Y>X。 -其他补丁版本的回退未经验证，如直接回退，可能会产生非预期的问题。 +注意，其他补丁版本的回退未经验证，如直接回退，可能会产生非预期的问题。 ## 注意事项 @@ -23,20 +23,6 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 - 在回退 TiDB 集群的过程中，请勿执行 DDL 语句，否则可能会出现行为未定义的问题。 - 回退的集群内的各组件应该使用相同版本。 - Changefeed 默认配置值在回退过程中不会被更改，已经修改的值，在回退过程中也不会被修改。 -- 配置参数 [`server-version`](/tidb-configuration-file.md#server-version) 的值会被 TiDB 节点用于验证当前 TiDB 的版本。因此在进行 TiDB 集群回退前，请将 `server-version` 的值设置为空或者当前 TiDB 真实的版本值，避免出现非预期行为。 -- 配置项 [`performance.force-init-stats`](/tidb-configuration-file.md#force-init-stats-从-v657-和-v710-版本开始引入) 设置为 `true` 会延长 TiDB 的启动时间，这可能会造成启动超时，回退失败。为避免这种情况，建议为 TiUP 设置更长的等待超时。可能受影响的场景： - - 原集群版本低于 v6.5.7、v7.1.0（尚未支持 `performance.force-init-stats`），目标版本为 v7.2.0 或更高。 - - 原集群版本高于或等于 v6.5.7、v7.1.0，且配置项 `performance.force-init-stats` 被设置为 `true`。 - -设置 TiUP 的等待超时的步骤如下： - -1. 查看配置项 `performance.force-init-stats` 的值。通常情况下，`20` 分钟超时等待能满足绝大部分场景的需求。如果需要更准确的预估，可以在 TiDB 日志中搜索 `init stats info time` 关键字，获取上次启动的统计信息加载时间作为参考。 - -2. 通过增加命令行选项 [`--wait-timeout`](/tiup/tiup-component-dm.md#--wait-timeoutuint默认-120) 设置 TiUP 超时等待时间。如下命令可将超时等待设置为 `1200` 秒（即 `20` 分钟）: - - ```shell - tiup update cluster --wait-timeout 1200 [other options] - ``` ## 回退前的准备工作 @@ -74,6 +60,29 @@ tiup cluster check --cluster - 如果结果为 `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` 后再继续回退。 +### 修改配置项 `server-version` + +- 配置项 [`server-version`](/tidb-configuration-file.md#server-version) 的值会被 TiDB 节点用于验证当前 TiDB 的版本。因此在进行 TiDB 集群回退前，请将 `server-version` 的值设置为空或者当前 TiDB 真实的版本值，避免出现非预期行为。 + +### 修改配置项 `performance.force-init-stats` + +配置项 [`performance.force-init-stats`](/tidb-configuration-file.md#force-init-stats-从-v657-和-v710-版本开始引入) 设置为 `true` 会延长 TiDB 的启动时间，这可能会造成启动超时，回退失败。为避免这种情况，建议为 TiUP 设置更长的等待超时。 + +可能受影响的场景： + +- 原集群版本低于 v6.5.7、v7.1.0（尚未支持 `performance.force-init-stats`），目标版本为 v7.2.0 或更高。 +- 原集群版本高于或等于 v6.5.7、v7.1.0，且配置项 `performance.force-init-stats` 被设置为 `true`。 + +设置 TiUP 的等待超时的步骤如下： + +1. 查看配置项 `performance.force-init-stats` 的值。通常情况下，`20` 分钟超时等待能满足绝大部分场景的需求。如果需要更准确的预估，可以在 TiDB 日志中搜索 `init stats info time` 关键字，获取上次启动的统计信息加载时间作为参考。 + +2. 通过增加命令行选项 [`--wait-timeout`](/tiup/tiup-component-dm.md#--wait-timeoutuint默认-120) 设置 TiUP 超时等待时间。如下命令可将超时等待设置为 `1200` 秒（即 `20` 分钟）: + + ```shell + tiup update cluster --wait-timeout 1200 [other options] + ``` + ## 执行回退操作 回退补丁版本仅支持不停机回退，回退过程中集群仍然可以对外提供服务。 @@ -91,12 +100,13 @@ tiup cluster patch {cluster_name} {/tmp/pd-v7.5.0-linux-amd64.tar.gz} -R pd -y tiup cluster patch {cluster_name} {/tmp/tiflash-v7.5.0-linux-amd64.tar.gz} -R tiflash -y ``` -注意以下事项： +> **注意：** +> +> - 一定要按上面的顺序执行回退操作。 +> - 滚动回退会逐个回退所有的组件。回退 TiKV 期间，会逐个将 TiKV 上的所有 leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟（300 秒），超时后会直接停止该实例。 +> - 使用 [`--force`](/tiup//tiup-component-cluster-upgrade.md#--force) 参数可以在不驱逐 leader 的前提下快速回退集群至指定版本，但是该方式会忽略所有回退中的错误，在回退失败后得不到有效提示，请谨慎使用。 -- 一定要按上面的顺序执行回退操作。 -- 滚动回退会逐个回退所有的组件。回退 TiKV 期间，会逐个将 TiKV 上的所有 leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟（300 秒），超时后会直接停止该实例。 -- 使用 [`--force`](/tiup//tiup-component-cluster-upgrade.md#--force) 参数可以在不驱逐 leader 的前提下快速回退集群至指定版本，但是该方式会忽略所有回退中的错误，在回退失败后得不到有效提示，请谨慎使用。 -- 如果希望保持性能稳定，则需要保证 TiKV 上的所有 leader 驱逐完成后再停止该 TiKV 实例，可以指定 [`--transfer-timeout`](/tiup/tiup-component-cluster-reload.md#--transfer-timeoutuint默认-600) 为一个更大的值，如 `--transfer-timeout 3600`，单位为秒。 +如果希望保持性能稳定，则需要保证 TiKV 上的所有 leader 驱逐完成后再停止该 TiKV 实例，可以指定 [`--transfer-timeout`](/tiup/tiup-component-cluster-reload.md#--transfer-timeoutuint默认-600) 为一个更大的值，如 `--transfer-timeout 3600`，单位为秒。 ## 验证回退结果 From 85cb0a3088e38aff21f0bf71eda31470f53e5769 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Tue, 23 Jul 2024 15:32:09 +0800 Subject: [PATCH 11/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index 4989128d4a58..3be74cd2feb6 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -13,7 +13,9 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 - 从 v7.5.Y 版本回退至 v7.5.X，其中 Y 和 X 是大于 0 的整数，且 Y>X。 -注意，其他补丁版本的回退未经验证，如直接回退，可能会产生非预期的问题。 +> **警告：** +> +> 其他补丁版本的回退未经验证，如直接回退，可能会产生非预期的问题。 ## 注意事项 From fa0b90919cd387aa5d31cc05311eca223cabf5ee Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Tue, 23 Jul 2024 16:41:54 +0800 Subject: [PATCH 12/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index 3be74cd2feb6..ce8ddaec09ae 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -11,7 +11,7 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 本文档适用于以下回退路径： -- 从 v7.5.Y 版本回退至 v7.5.X，其中 Y 和 X 是大于 0 的整数，且 Y>X。 +- 从 v7.5.Y 版本回退至 v7.5.X，其中 Y > 0, X ≥ 0, 且 Y > X。 > **警告：** > From 53cc90875ad95111a11b2da50ac7fb90c48c2ef2 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Tue, 23 Jul 2024 16:54:23 +0800 Subject: [PATCH 13/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index ce8ddaec09ae..fe1cbf649151 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -104,7 +104,7 @@ tiup cluster patch {cluster_name} {/tmp/tiflash-v7.5.0-linux-amd64.tar.gz} -R ti > **注意：** > -> - 一定要按上面的顺序执行回退操作。 +> - 必须按上面命令行的顺序执行回退操作。 > - 滚动回退会逐个回退所有的组件。回退 TiKV 期间，会逐个将 TiKV 上的所有 leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟（300 秒），超时后会直接停止该实例。 > - 使用 [`--force`](/tiup//tiup-component-cluster-upgrade.md#--force) 参数可以在不驱逐 leader 的前提下快速回退集群至指定版本，但是该方式会忽略所有回退中的错误，在回退失败后得不到有效提示，请谨慎使用。 From c314141312d93c3140dbca08ddd82c9c70abf6f6 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Tue, 23 Jul 2024 16:55:43 +0800 Subject: [PATCH 14/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index fe1cbf649151..91d3fdeec689 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -33,7 +33,7 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 ### 兼容性变更 - TiDB 目前仅支持有限的补丁版本回退。请参见[支持回退的版本](#支持回退的版本)。 -- 仅支持 PD、TiDB、TiKV、TiFlash、TiCDC、BR、PITR 这些组件的补丁版本回退。 +- 仅支持 PD、TiDB、TiKV、TiFlash、TiCDC、BR、PITR 组件的补丁版本回退。 - 查看对应版本的 [Release Notes](/releases/release-notes.md) 中的兼容性变更。如果有任何变更影响到回退，请采取相应的措施。例如，从 TiDB v7.5.2 回退至 v7.5.1 时，需查阅以下各版本的兼容性变更： - [TiDB v7.5.1 Release Notes](/releases/release-7.5.1.md#兼容性变更) 中的兼容性变更 From 2d6c587e852848ecb2450b3547f6ab2d551e43bb Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Wed, 24 Jul 2024 09:52:19 +0800 Subject: [PATCH 15/18] Update roll-back-tidb-using-tiup.md Co-authored-by: Frank945946 <108602632+Frank945946@users.noreply.github.com> --- roll-back-tidb-using-tiup.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index 91d3fdeec689..3942b9dfb3a2 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -70,10 +70,6 @@ tiup cluster check --cluster 配置项 [`performance.force-init-stats`](/tidb-configuration-file.md#force-init-stats-从-v657-和-v710-版本开始引入) 设置为 `true` 会延长 TiDB 的启动时间，这可能会造成启动超时，回退失败。为避免这种情况，建议为 TiUP 设置更长的等待超时。 -可能受影响的场景： - -- 原集群版本低于 v6.5.7、v7.1.0（尚未支持 `performance.force-init-stats`），目标版本为 v7.2.0 或更高。 -- 原集群版本高于或等于 v6.5.7、v7.1.0，且配置项 `performance.force-init-stats` 被设置为 `true`。 设置 TiUP 的等待超时的步骤如下： From b1942e218e75515dfae0d198c138afe711cfe01a Mon Sep 17 00:00:00 2001 From: houfaxin Date: Wed, 24 Jul 2024 11:08:56 +0800 Subject: [PATCH 16/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index 3942b9dfb3a2..55e66026fde1 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -26,9 +26,9 @@ summary: TiUP 可用于回退 TiDB 版本。本文档介绍如何使用 TiUP 回 - 回退的集群内的各组件应该使用相同版本。 - Changefeed 默认配置值在回退过程中不会被更改，已经修改的值，在回退过程中也不会被修改。 -## 回退前的准备工作 +## 准备工作 -开始回退前需要[更新 TiUP 和 TiUP 集群组件版本](/tiup/tiup-component-management.md#升级组件)。 +开始回退前需要[更新 TiUP 和 TiUP 集群组件版本](/tiup/tiup-component-management.md#升级组件)。同时还需要完成下面的准备工作。 ### 兼容性变更 @@ -59,33 +59,38 @@ tiup cluster check --cluster 执行结束后，会输出 `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` 后再继续回退。 +- 如果结果为 `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` 后再继续回退。 ### 修改配置项 `server-version` -- 配置项 [`server-version`](/tidb-configuration-file.md#server-version) 的值会被 TiDB 节点用于验证当前 TiDB 的版本。因此在进行 TiDB 集群回退前，请将 `server-version` 的值设置为空或者当前 TiDB 真实的版本值，避免出现非预期行为。 +配置项 [`server-version`](/tidb-configuration-file.md#server-version) 的值会被 TiDB 节点用于验证当前 TiDB 的版本。因此在回退 TiDB 版本前，需要将 `server-version` 的值设置为空或当前 TiDB 真实的版本值，避免出现非预期行为。 ### 修改配置项 `performance.force-init-stats` -配置项 [`performance.force-init-stats`](/tidb-configuration-file.md#force-init-stats-从-v657-和-v710-版本开始引入) 设置为 `true` 会延长 TiDB 的启动时间，这可能会造成启动超时，回退失败。为避免这种情况，建议为 TiUP 设置更长的等待超时。 +配置项 [`performance.force-init-stats`](/tidb-configuration-file.md#force-init-stats-从-v657-和-v710-版本开始引入) 设置为 `true` 会延长 TiDB 的启动时间，这可能会造成启动超时，回退失败。 +为避免这种情况，建议为 TiUP 设置更长的等待超时。 设置 TiUP 的等待超时的步骤如下： 1. 查看配置项 `performance.force-init-stats` 的值。通常情况下，`20` 分钟超时等待能满足绝大部分场景的需求。如果需要更准确的预估，可以在 TiDB 日志中搜索 `init stats info time` 关键字，获取上次启动的统计信息加载时间作为参考。 -2. 通过增加命令行选项 [`--wait-timeout`](/tiup/tiup-component-dm.md#--wait-timeoutuint默认-120) 设置 TiUP 超时等待时间。如下命令可将超时等待设置为 `1200` 秒（即 `20` 分钟）: +2. 使用命令行选项 [`--wait-timeout`](/tiup/tiup-component-dm.md#--wait-timeoutuint默认-120) 设置 TiUP 超时等待时间。如下命令可将超时等待设置为 `1200` 秒（即 20 分钟）: ```shell tiup update cluster --wait-timeout 1200 [other options] ``` +### 使用选项 `--transfer-timeout` 修改最长等待时间 + +如果希望回退过程保持性能稳定，则需要保证 TiKV 上的所有 Leader 驱逐完成后再停止该 TiKV 实例，可以指定 [`--transfer-timeout`](/tiup/tiup-component-cluster-reload.md#--transfer-timeoutuint默认-600) 为一个更大的值，如 `--transfer-timeout 3600`，单位为秒。 + ## 执行回退操作 回退补丁版本仅支持不停机回退，回退过程中集群仍然可以对外提供服务。 -回退时，TiDB 会对各节点逐个迁移 leader 后再回退和重启。对于大规模集群需要较长时间才能完成整个回退操作，因此请提前预估预留足够的时间。 +回退时，TiDB 会对各节点逐个迁移 leader 后再回退和重启。对于大规模集群需要较长时间才能完成整个回退操作，因此请提前预留足够的时间。 以 v7.5.1 回退到 v7.5.0 版本为例，执行下列命令： @@ -101,10 +106,8 @@ tiup cluster patch {cluster_name} {/tmp/tiflash-v7.5.0-linux-amd64.tar.gz} -R ti > **注意：** > > - 必须按上面命令行的顺序执行回退操作。 -> - 滚动回退会逐个回退所有的组件。回退 TiKV 期间，会逐个将 TiKV 上的所有 leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟（300 秒），超时后会直接停止该实例。 -> - 使用 [`--force`](/tiup//tiup-component-cluster-upgrade.md#--force) 参数可以在不驱逐 leader 的前提下快速回退集群至指定版本，但是该方式会忽略所有回退中的错误，在回退失败后得不到有效提示，请谨慎使用。 - -如果希望保持性能稳定，则需要保证 TiKV 上的所有 leader 驱逐完成后再停止该 TiKV 实例，可以指定 [`--transfer-timeout`](/tiup/tiup-component-cluster-reload.md#--transfer-timeoutuint默认-600) 为一个更大的值，如 `--transfer-timeout 3600`，单位为秒。 +> - 滚动回退会逐个回退所有的组件。回退 TiKV 期间，会逐个将 TiKV 上的所有 Leader 切走再停止该 TiKV 实例。默认超时时间为 5 分钟（300 秒），超时后会直接停止该实例。 +> - 使用 [`--force`](/tiup//tiup-component-cluster-upgrade.md#--force) 参数可以在不驱逐 Leader 的前提下快速回退集群至指定版本，但是该方式会忽略所有回退中的错误，在回退失败后得不到有效提示，请谨慎使用。 ## 验证回退结果 From 0d3e6d9eea4f1f32d3fa8ad7cf533692b3e7e26e Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Wed, 24 Jul 2024 14:19:26 +0800 Subject: [PATCH 17/18] Update roll-back-tidb-using-tiup.md --- roll-back-tidb-using-tiup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index 55e66026fde1..e8a8b1c74bf5 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -84,7 +84,7 @@ tiup cluster check --cluster ### 使用选项 `--transfer-timeout` 修改最长等待时间 -如果希望回退过程保持性能稳定，则需要保证 TiKV 上的所有 Leader 驱逐完成后再停止该 TiKV 实例，可以指定 [`--transfer-timeout`](/tiup/tiup-component-cluster-reload.md#--transfer-timeoutuint默认-600) 为一个更大的值，如 `--transfer-timeout 3600`，单位为秒。 +如果希望回退过程保持性能稳定，则需要保证 TiKV 上的所有 Leader 驱逐完成后再停止该 TiKV 实例，可以使用选项 [`--transfer-timeout`](/tiup/tiup-component-cluster-reload.md#--transfer-timeoutuint默认-600) 将最长等待时间设置为更大的值，如 `--transfer-timeout 3600`，单位为秒。 ## 执行回退操作 From be975a454f1209f26e69cfc0752d48f9890a62b4 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 6 Jan 2025 14:42:14 +0800 Subject: [PATCH 18/18] Apply suggestions from code review Co-authored-by: Frank945946 <108602632+Frank945946@users.noreply.github.com> --- roll-back-tidb-using-tiup.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/roll-back-tidb-using-tiup.md b/roll-back-tidb-using-tiup.md index e8a8b1c74bf5..2bbb323d2872 100644 --- a/roll-back-tidb-using-tiup.md +++ b/roll-back-tidb-using-tiup.md @@ -111,16 +111,18 @@ tiup cluster patch {cluster_name} {/tmp/tiflash-v7.5.0-linux-amd64.tar.gz} -R ti ## 验证回退结果 -执行 `display` 命令来查看最新的集群版本 TiDB 版本： +登录 TiDB，查看最新的集群版本 TiDB 版本： ```shell -tiup cluster display -``` +SELECT VERSION(); 输出结果如下，版本成功回退到 v7.5.0： ```shell -Cluster type: tidb -Cluster name: -Cluster version: v7.5.0 ++--------------------+ +| version() | ++--------------------+ +| 5.7.25-TiDB-v7.5.0 | ++--------------------+ +1 row in set (0.00 sec) ```