From 8ab378cdbb511b33f464f128d4e266f7070f2c65 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Tue, 22 Jun 2021 11:48:09 +0800 Subject: [PATCH 1/4] Update content about upgrade --- upgrade-tidb-using-tiup.md | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md index 6a4b19e70878a..4ac264ea46617 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -6,20 +6,26 @@ aliases: ['/docs/dev/upgrade-tidb-using-tiup/','/docs/dev/how-to/upgrade/using-t # Upgrade TiDB Using TiUP -This document is targeted for users who want to upgrade from TiDB 4.0 versions to TiDB 5.0 versions, or from TiDB 5.0 to a later version. +This document is targeted for the following upgrade paths: -If your cluster to upgrade is v3.1 or an earlier version (v3.0 or v2.1), you need to upgrade your cluster first to v4.0 and then to v5.0. You cannot upgrade your cluster across a major version or versions. +- Upgrade from TiDB 4.0 versions to TiDB 5.1 versions, or from TiDB 5.1 to a later v5.1 patch version. +- Upgrade from TiDB 5.0 versions to TiDB 5.1 versions, or from TiDB 5.1 to a later v5.1 patch version. + +> **Note:** +> +> If your cluster to upgrade is v3.1 or an earlier version (v3.0 or v2.1), direct upgrade to v5.1 or its patch versions is not supported. You need to upgrade your cluster first to v4.0 and then to v5.1. ## Upgrade caveat -- After the upgrade, rolling back to 4.0 or earlier versions is not supported. -- For the v4.0 cluster managed using TiDB Ansible, you need to import the cluster to TiUP (`tiup cluster`) for new management according to [Upgrade TiDB Using TiUP (v4.0)](https://docs.pingcap.com/tidb/v4.0/upgrade-tidb-using-tiup#import-tidb-ansible-and-the-inventoryini-configuration-to-tiup). Then you can upgrade the cluster to v5.0 according to this document. +- TiDB currently does not support version downgrade or rolling back to an earlier version after the upgrade. +- For the v4.0 cluster managed using TiDB Ansible, you need to import the cluster to TiUP (`tiup cluster`) for new management according to [Upgrade TiDB Using TiUP (v4.0)](https://docs.pingcap.com/tidb/v4.0/upgrade-tidb-using-tiup#import-tidb-ansible-and-the-inventoryini-configuration-to-tiup). Then you can upgrade the cluster to v5.1 or its patch versions according to this document. - To update versions earlier than 3.0 to 5.0: 1. Update this version to 3.0 using [TiDB Ansible](https://docs.pingcap.com/tidb/v3.0/upgrade-tidb-using-ansible). 2. Use TiUP (`tiup cluster`) to import the TiDB Ansible configuration. 3. Update the 3.0 version to 4.0 according to [Upgrade TiDB Using TiUP (v4.0)](https://docs.pingcap.com/tidb/v4.0/upgrade-tidb-using-tiup#import-tidb-ansible-and-the-inventoryini-configuration-to-tiup). - 4. Then you can upgrade the cluster to v5.0 according to this document. + 4. Then you can upgrade the cluster to v5.1 according to this document. - Support upgrading the versions of TiDB Binlog, TiCDC, TiFlash, and other components. +- For detailed compatibility changes of different versions, see the [Release Notes](/releases/release-notes.md) of each version. Modify your cluster configuration according the "Compatibility Changes" section of the corresponding release notes. > **Note:** > @@ -39,7 +45,7 @@ Before upgrading your TiDB cluster, you first need to upgrade TiUP or TiUP mirro > > If the control machine of the cluster to upgrade cannot access `https://tiup-mirrors.pingcap.com`, skip this section and see [Upgrade TiUP offline mirror](#upgrade-tiup-offline-mirror). -1. Upgrade the TiUP version. It is recommended that the TiUP version is `1.4.0` or later. +1. Upgrade the TiUP version. It is recommended that the TiUP version is `1.5.0` or later. {{< copyable "shell-regular" >}} @@ -48,7 +54,7 @@ Before upgrading your TiDB cluster, you first need to upgrade TiUP or TiUP mirro tiup --version ``` -2. Upgrade the TiUP Cluster version. It is recommended that the TiUP Cluster version is `1.4.0` or later. +2. Upgrade the TiUP Cluster version. It is recommended that the TiUP Cluster version is `1.5.0` or later. {{< copyable "shell-regular" >}} @@ -90,7 +96,7 @@ Now, the offline mirror has been upgraded successfully. If an error occurs durin > Skip this step if one of the following situations applies: > > + You have not modified the configuration parameters of the original cluster. Or you have modified the configuration parameters using `tiup cluster` but no more modification is needed. -> + After the upgrade, you want to use v5.0's default parameter values for the unmodified configuration items. +> + After the upgrade, you want to use v5.1's default parameter values for the unmodified configuration items. 1. Enter the `vi` editing mode to edit the topology file: @@ -106,9 +112,9 @@ Now, the offline mirror has been upgraded successfully. If an error occurs durin > **Note:** > -> Before you upgrade the cluster to v5.0, make sure that the parameters you have modified in v4.0 are compatible in v5.0. For details, see [TiKV Configuration File](/tikv-configuration-file.md). +> Before you upgrade the cluster to v5.1, make sure that the parameters you have modified in v4.0 are compatible in v5.1. For details, see [TiKV Configuration File](/tikv-configuration-file.md). > -> The following three TiKV parameters are obsolete in TiDB v5.0. If the following parameters have been configured in your original cluster, you need to delete these parameters through `edit-config`: +> The following three TiKV parameters are obsolete in TiDB v5.1. If the following parameters have been configured in your original cluster, you need to delete these parameters through `edit-config`: > > - pessimistic-txn.enabled > - server.request-batch-enable-cross-command @@ -149,12 +155,12 @@ If your application has a maintenance window for the database to be stopped for tiup cluster upgrade ``` -For example, if you want to upgrade the cluster to v5.0.0: +For example, if you want to upgrade the cluster to v5.1.0: {{< copyable "shell-regular" >}} ```shell -tiup cluster upgrade v5.0.0 +tiup cluster upgrade v5.1.0 ``` > **Note:** @@ -204,7 +210,7 @@ tiup cluster display ``` Cluster type: tidb Cluster name: -Cluster version: v5.0.0 +Cluster version: v5.1.0 ``` > **Note:** @@ -254,10 +260,10 @@ You can upgrade the tool version by using TiUP to install the `ctl` component of {{< copyable "shell-regular" >}} ```shell -tiup install ctl:v5.0.0 +tiup install ctl:v5.1.0 ``` ## TiDB 5.1 compatibility changes -- See TiDB 5.1 GA Release Notes for the compatibility changes. +- See TiDB 5.1 Release Notes for the compatibility changes. - Try to avoid creating a new clustered index table when you apply rolling updates to the clusters using TiDB-Binlog. From e7cbd65a4e460f56424f49f78c7e24289fe4371a Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 24 Jun 2021 11:11:22 +0800 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Grace Cai --- upgrade-tidb-using-tiup.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md index 4ac264ea46617..c4d728cb9904c 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -8,22 +8,22 @@ aliases: ['/docs/dev/upgrade-tidb-using-tiup/','/docs/dev/how-to/upgrade/using-t This document is targeted for the following upgrade paths: -- Upgrade from TiDB 4.0 versions to TiDB 5.1 versions, or from TiDB 5.1 to a later v5.1 patch version. -- Upgrade from TiDB 5.0 versions to TiDB 5.1 versions, or from TiDB 5.1 to a later v5.1 patch version. +- Upgrade from TiDB 4.0 versions to TiDB 5.1 versions. +- Upgrade from TiDB 5.0 versions to TiDB 5.1 versions, > **Note:** > -> If your cluster to upgrade is v3.1 or an earlier version (v3.0 or v2.1), direct upgrade to v5.1 or its patch versions is not supported. You need to upgrade your cluster first to v4.0 and then to v5.1. +> If your cluster to be upgraded is v3.1 or an earlier version (v3.0 or v2.1), the direct upgrade to v5.1 or its patch versions is not supported. You need to upgrade your cluster first to v4.0 and then to v5.1. ## Upgrade caveat - TiDB currently does not support version downgrade or rolling back to an earlier version after the upgrade. - For the v4.0 cluster managed using TiDB Ansible, you need to import the cluster to TiUP (`tiup cluster`) for new management according to [Upgrade TiDB Using TiUP (v4.0)](https://docs.pingcap.com/tidb/v4.0/upgrade-tidb-using-tiup#import-tidb-ansible-and-the-inventoryini-configuration-to-tiup). Then you can upgrade the cluster to v5.1 or its patch versions according to this document. -- To update versions earlier than 3.0 to 5.0: +- To update versions earlier than 3.0 to 5.1: 1. Update this version to 3.0 using [TiDB Ansible](https://docs.pingcap.com/tidb/v3.0/upgrade-tidb-using-ansible). 2. Use TiUP (`tiup cluster`) to import the TiDB Ansible configuration. 3. Update the 3.0 version to 4.0 according to [Upgrade TiDB Using TiUP (v4.0)](https://docs.pingcap.com/tidb/v4.0/upgrade-tidb-using-tiup#import-tidb-ansible-and-the-inventoryini-configuration-to-tiup). - 4. Then you can upgrade the cluster to v5.1 according to this document. + 4. Upgrade the cluster to v5.1 according to this document. - Support upgrading the versions of TiDB Binlog, TiCDC, TiFlash, and other components. - For detailed compatibility changes of different versions, see the [Release Notes](/releases/release-notes.md) of each version. Modify your cluster configuration according the "Compatibility Changes" section of the corresponding release notes. From 81c088a0f2fb754eda5712b5064bfe81a51c2141 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 24 Jun 2021 13:19:01 +0800 Subject: [PATCH 3/4] Update upgrade-tidb-using-tiup.md --- upgrade-tidb-using-tiup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md index c4d728cb9904c..4698a84306295 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -25,7 +25,7 @@ This document is targeted for the following upgrade paths: 3. Update the 3.0 version to 4.0 according to [Upgrade TiDB Using TiUP (v4.0)](https://docs.pingcap.com/tidb/v4.0/upgrade-tidb-using-tiup#import-tidb-ansible-and-the-inventoryini-configuration-to-tiup). 4. Upgrade the cluster to v5.1 according to this document. - Support upgrading the versions of TiDB Binlog, TiCDC, TiFlash, and other components. -- For detailed compatibility changes of different versions, see the [Release Notes](/releases/release-notes.md) of each version. Modify your cluster configuration according the "Compatibility Changes" section of the corresponding release notes. +- For detailed compatibility changes of different versions, see the [Release Notes](/releases/release-notes.md) of each version. Modify your cluster configuration according to the "Compatibility Changes" section of the corresponding release notes. > **Note:** > From b91c9758d15075e29fa948d1cb01eacb87c4ced6 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 24 Jun 2021 13:22:49 +0800 Subject: [PATCH 4/4] Update upgrade-tidb-using-tiup.md Co-authored-by: Grace Cai --- upgrade-tidb-using-tiup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md index 4698a84306295..0c49c9d5b49c2 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -9,7 +9,7 @@ aliases: ['/docs/dev/upgrade-tidb-using-tiup/','/docs/dev/how-to/upgrade/using-t This document is targeted for the following upgrade paths: - Upgrade from TiDB 4.0 versions to TiDB 5.1 versions. -- Upgrade from TiDB 5.0 versions to TiDB 5.1 versions, +- Upgrade from TiDB 5.0 versions to TiDB 5.1 versions. > **Note:** >