From a66368376f3423bc4578bacfd450552d32714707 Mon Sep 17 00:00:00 2001 From: xixirangrang <35301108+hfxsd@users.noreply.github.com> Date: Fri, 24 Nov 2023 11:47:59 +0800 Subject: [PATCH 1/5] Update smooth-upgrade-tidb.md --- smooth-upgrade-tidb.md | 48 +++++++++++++++++++++++++++++++++++------- 1 file changed, 40 insertions(+), 8 deletions(-) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index f73a2a62b1bf1..0a11be88f71c4 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -11,7 +11,20 @@ summary: This document introduces the smooth upgrade feature of TiDB, which supp This document introduces the smooth upgrade feature of TiDB, which supports upgrading TiDB clusters without manually canceling DDL operations. -Starting from v7.1.0, when you upgrade TiDB to a later version, TiDB supports smooth upgrade. This feature removes the limitations during the upgrade process and provides a more user-friendly upgrade experience. This feature is enabled by default and cannot be disabled. +Starting from v7.1.0, when you upgrade TiDB to a later version, TiDB supports smooth upgrade. This feature removes the limitations during the upgrade process and provides a more user-friendly upgrade experience. Note that you need to ensure that there are no user-initiated DDL operations during the upgrade process. + +## Supported versions + +Depending on whether the feature needs to be controlled by a switch, there are two ways to use smooth upgrade: + +- The feature is enabled by default and does not need to be controlled by a switch. Currently, the versions that support this method are v7.1.0, v7.1.1, v7.2.0, and v7.3.0. The specific supported versions are as follows: + - Upgrade from v7.1.0 to v7.1.1, v7.2.0, or v7.3.0 + - Upgrade from v7.1.1 to v7.2.0 or v7.3.0 + - Upgrade from v7.2.0 to v7.3.0 + +- The feature is disabled by default, and can be enabled by sending the `/upgrade/start` request. For details, see [TiDB HTTP API](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md). The supported versions are as follows: + - Upgrade from v7.1.2 and later v7.1 versions (that is, v7.1.x, where x >= 2) to v7.4.0 and later versions + - Upgrade from v7.4.0 to later versions ## Feature introduction @@ -20,16 +33,31 @@ Before the smooth upgrade feature is introduced, there are the following limitat - Running DDL operations during the upgrade process might cause undefined behavior in TiDB. - Upgrading TiDB during the DDL operations might cause undefined behavior in TiDB. -After the smooth upgrade feature is introduced, the upgrade process is no longer subject to the preceding limitations. +These limitations can be summarized as that you need to ensure that there are no user-initiated DDL operations during the upgrade process. After the smooth upgrade feature is introduced, TiDB is no longer subject to this limitation during the upgrade process. + +### Upgrade steps + +#### Use TiUP to upgrade + +Starting from v1.14.0, TiUP automatically supports this feature. That is, you can directly use the `tiup cluster upgrade` command to upgrade TiDB clusters. Note that the `tiup cluster patch` command is not supported currently. -During the upgrade process, TiDB automatically performs the following operations without user intervention: +#### Use TiDB Operator to upgrade -1. Pause user DDL operations. -2. Perform system DDL operations for the upgrade. -3. Resume the paused user DDL operations. -4. Complete the upgrade. +Currently, this feature is not supported. It will be supported as soon as possible. -The resumed DDL jobs are still executed in the order before the upgrade. +#### Other upgrade methods + +You can use the following steps to upgrade TiDB manually or by using a script: + +1. Send the HTTP upgrade start request to any TiDB node in the cluster: `curl -X POST http://{TiDBIP}:10080/upgrade/start`. + * The TiDB cluster enters the **Upgrading** state. + * The DDL operations to be performed are paused. + +2. Replace the TiDB binary and perform a rolling upgrade. This process is the same as the original upgrade process. + * Perform system DDL operations during the upgrade process. + +3. After all TiDB nodes in the cluster are upgraded successfully, send the HTTP upgrade finish request to any TiDB node: `curl -X POST http://{TiDBIP}:10080/upgrade/finish`. + * The paused DDL operations of users are resumed. ## Limitations @@ -54,3 +82,7 @@ When using the smooth upgrade feature, note the following limitations. * BR: BR might replicate the paused DDL jobs to TiDB. The paused DDL jobs cannot be automatically resumed, which might cause the DDL jobs to be stuck later. * DM and TiCDC: If you use DM or TiCDC to import SQL statements to TiDB during the upgrade process, and if one of the SQL statements contains DDL operations, the import operation is blocked and undefined errors might occur. + +### Limitation on plugins + +The plugins installed in TiDB might contain DDL operations. However, during the upgrade, if the DDL operations in the plugins are not performed on system tables, the upgrade might fail. From 793b7370d1a57b08fadae7669d5b42ac67b41f49 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Fri, 24 Nov 2023 21:42:52 +0800 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Ran --- smooth-upgrade-tidb.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index 0a11be88f71c4..0f16923170c7b 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -47,14 +47,14 @@ Currently, this feature is not supported. It will be supported as soon as possib #### Other upgrade methods -You can use the following steps to upgrade TiDB manually or by using a script: +You can take the following steps to upgrade TiDB manually or by using a script: 1. Send the HTTP upgrade start request to any TiDB node in the cluster: `curl -X POST http://{TiDBIP}:10080/upgrade/start`. * The TiDB cluster enters the **Upgrading** state. * The DDL operations to be performed are paused. 2. Replace the TiDB binary and perform a rolling upgrade. This process is the same as the original upgrade process. - * Perform system DDL operations during the upgrade process. + * The system DDL operations are performed during the upgrade process. 3. After all TiDB nodes in the cluster are upgraded successfully, send the HTTP upgrade finish request to any TiDB node: `curl -X POST http://{TiDBIP}:10080/upgrade/finish`. * The paused DDL operations of users are resumed. From 2196c0f934429b3db1e2b5e69e24d8012abc51c2 Mon Sep 17 00:00:00 2001 From: xixirangrang <35301108+hfxsd@users.noreply.github.com> Date: Wed, 29 Nov 2023 15:23:48 +0800 Subject: [PATCH 3/5] add the upgrade version table --- smooth-upgrade-tidb.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index 0f16923170c7b..4cbaaf081c289 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -26,15 +26,29 @@ Depending on whether the feature needs to be controlled by a switch, there are t - Upgrade from v7.1.2 and later v7.1 versions (that is, v7.1.x, where x >= 2) to v7.4.0 and later versions - Upgrade from v7.4.0 to later versions +Refer to the following table for the upgrade methods supported by specific versions: + +| Original version | Upgraded version | Upgrade methods | Note | +|------|--------|-------------|-------------| +| < v7.1.0 | Any version | Does not support smooth upgrade. | | +| v7.1.0 | v7.1.1、v7.2.0, or v7.3.0 | Smooth upgrade is automatically supported. No additional operations are required. | Experimental feature. It might encounter the issue [#44760](https://github.com/pingcap/tidb/pull/44760). | +| v7.1.1 | v7.2.0 or v7.3.0 | Smooth upgrade is automatically supported. No additional operations are required. | Experimental feature. | +| v7.2.0 | v7.3.0 | Smooth upgrade is automatically supported. No additional operations are required. | Experimental feature. | +| [v7.1.2, v7.2.0) | [v7.1.2, v7.2.0) | Enable smooth upgrade by sending the `/upgrade/start` HTTP request. There are two methods: [Use TiUP](#use-tiup-to-upgrade) and [Other upgrade methods](#other-upgrade-methods) | When smooth upgrade is not enabled, ensure that no DDL operations are performed during the upgrade. | +| [v7.1.2, v7.2.0) or >= v7.4.0 | >= v7.4.0 | Enable smooth upgrade by sending the `/upgrade/start` HTTP request. There are two methods: [Use TiUP](#use-tiup-to-upgrade) and [Other upgrade methods](#other-upgrade-methods) | When smooth upgrade is not enabled, ensure that no DDL operations are performed during the upgrade. | +| v7.1.0, v7.1.1, v7.2.0, and v7.3.0 | >= v7.4.0 | Does not support smooth upgrade. | | + ## Feature introduction -Before the smooth upgrade feature is introduced, there are the following limitations on DDL operations during the upgrade process (see the *Warning* content in [Upgrade TiDB Using TiUP](/upgrade-tidb-using-tiup.md#upgrade-tidb-using-tiup)): +Before the smooth upgrade feature is introduced, there are the following limitations on DDL operations during the upgrade process: - Running DDL operations during the upgrade process might cause undefined behavior in TiDB. - Upgrading TiDB during the DDL operations might cause undefined behavior in TiDB. These limitations can be summarized as that you need to ensure that there are no user-initiated DDL operations during the upgrade process. After the smooth upgrade feature is introduced, TiDB is no longer subject to this limitation during the upgrade process. +For more information, see the **Warning** content in [Upgrade TiDB Using TiUP](/upgrade-tidb-using-tiup.md#upgrade-tidb-using-tiup). + ### Upgrade steps #### Use TiUP to upgrade From e6ec814fa4e4231ce19ca96fa5fb0bd17b165f83 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Wed, 29 Nov 2023 17:08:34 +0800 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Lynn --- smooth-upgrade-tidb.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index 4cbaaf081c289..e1bc685f55606 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -65,7 +65,7 @@ You can take the following steps to upgrade TiDB manually or by using a script: 1. Send the HTTP upgrade start request to any TiDB node in the cluster: `curl -X POST http://{TiDBIP}:10080/upgrade/start`. * The TiDB cluster enters the **Upgrading** state. - * The DDL operations to be performed are paused. + * The user-initiated DDL operations to be performed are paused. 2. Replace the TiDB binary and perform a rolling upgrade. This process is the same as the original upgrade process. * The system DDL operations are performed during the upgrade process. @@ -99,4 +99,4 @@ When using the smooth upgrade feature, note the following limitations. ### Limitation on plugins -The plugins installed in TiDB might contain DDL operations. However, during the upgrade, if the DDL operations in the plugins are not performed on system tables, the upgrade might fail. +The plugins installed in TiDB might contain DDL operations. However, during the upgrade, if the DDL operations in the plugins are performed on non-system tables, the upgrade might fail. From 2ca2c9db1ece3af1eb92a0a5c5446b4d3976cde9 Mon Sep 17 00:00:00 2001 From: xixirangrang <35301108+hfxsd@users.noreply.github.com> Date: Wed, 29 Nov 2023 17:12:41 +0800 Subject: [PATCH 5/5] delete warning --- smooth-upgrade-tidb.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index e1bc685f55606..3901bc018e8dd 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -5,10 +5,6 @@ summary: This document introduces the smooth upgrade feature of TiDB, which supp # TiDB Smooth Upgrade -> **Warning:** -> -> Smooth upgrade is still an experimental feature. - This document introduces the smooth upgrade feature of TiDB, which supports upgrading TiDB clusters without manually canceling DDL operations. Starting from v7.1.0, when you upgrade TiDB to a later version, TiDB supports smooth upgrade. This feature removes the limitations during the upgrade process and provides a more user-friendly upgrade experience. Note that you need to ensure that there are no user-initiated DDL operations during the upgrade process. @@ -65,7 +61,7 @@ You can take the following steps to upgrade TiDB manually or by using a script: 1. Send the HTTP upgrade start request to any TiDB node in the cluster: `curl -X POST http://{TiDBIP}:10080/upgrade/start`. * The TiDB cluster enters the **Upgrading** state. - * The user-initiated DDL operations to be performed are paused. + * The DDL operations to be performed are paused. 2. Replace the TiDB binary and perform a rolling upgrade. This process is the same as the original upgrade process. * The system DDL operations are performed during the upgrade process.