From ec5cc4b3d47bf79c9745a308dac129ef90211027 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 e8206e415f13d..4625dd90974fd 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -5,20 +5,26 @@ summary: Learn how to upgrade TiDB using TiUP. # 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:** > @@ -38,7 +44,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" >}} @@ -47,7 +53,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" >}} @@ -89,7 +95,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: @@ -105,9 +111,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 @@ -148,12 +154,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:** @@ -203,7 +209,7 @@ tiup cluster display ``` Cluster type: tidb Cluster name: -Cluster version: v5.0.0 +Cluster version: v5.1.0 ``` > **Note:** @@ -253,10 +259,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 1a55be11d0284953108e62711e362c1d1ce61bb3 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 4625dd90974fd..4d6b659a33681 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -7,22 +7,22 @@ summary: Learn how to upgrade TiDB using TiUP. 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 918c1a8011b9fbfc434d47b49f6bb78d2fe2edbc 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 4d6b659a33681..211562b8aa308 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -24,7 +24,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 002b6f406c6bee1a86bdab77a970dc5f71547857 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 211562b8aa308..b0a8cf860249c 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -8,7 +8,7 @@ summary: Learn how to upgrade TiDB using TiUP. 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:** >