Skip to content

Update content about upgrade (#5813) #5841

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ti-chi-bot merged 4 commits into from
Jun 24, 2021
Merged

Update content about upgrade (#5813) #5841

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ec5cc4b
Update content about upgrade
TomShawn Jun 22, 2021
1a55be1
Apply suggestions from code review
TomShawn Jun 24, 2021
918c1a8
Update upgrade-tidb-using-tiup.md
TomShawn Jun 24, 2021
002b6f4
Update upgrade-tidb-using-tiup.md
TomShawn Jun 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 22 additions & 16 deletions upgrade-tidb-using-tiup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
- Upgrade from TiDB 5.0 versions to TiDB 5.1 versions.

> **Note:**
>
> 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

- 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.
- To update versions earlier than 3.0 to 5.0:
- 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.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.0 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 to the "Compatibility Changes" section of the corresponding release notes.

> **Note:**
>
Expand All @@ -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" >}}

Expand All @@ -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" >}}

Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -148,12 +154,12 @@ If your application has a maintenance window for the database to be stopped for
tiup cluster upgrade <cluster-name> <version>
```

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 <cluster-name> v5.0.0
tiup cluster upgrade <cluster-name> v5.1.0
```

> **Note:**
Expand Down Expand Up @@ -203,7 +209,7 @@ tiup cluster display <cluster-name>
```
Cluster type: tidb
Cluster name: <cluster-name>
Cluster version: v5.0.0
Cluster version: v5.1.0
```

> **Note:**
Expand Down Expand Up @@ -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.