Skip to content
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

*: add more contents about supported versions and upgrade methods #15445

Merged
merged 5 commits into from
Nov 29, 2023
Merged

*: add more contents about supported versions and upgrade methods #15445

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a663683
Update smooth-upgrade-tidb.md
hfxsd Nov 24, 2023
793b737
Apply suggestions from code review
hfxsd Nov 24, 2023
2196c0f
add the upgrade version table
hfxsd Nov 29, 2023
e6ec814
Apply suggestions from code review
hfxsd Nov 29, 2023
2ca2c9d
delete warning
hfxsd Nov 29, 2023
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
68 changes: 55 additions & 13 deletions smooth-upgrade-tidb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,31 +5,69 @@ 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. 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

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.

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.

For more information, see the **Warning** content in [Upgrade TiDB Using TiUP](/upgrade-tidb-using-tiup.md#upgrade-tidb-using-tiup).

### Upgrade steps

During the upgrade process, TiDB automatically performs the following operations without user intervention:
#### Use TiUP 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.
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.

The resumed DDL jobs are still executed in the order before the upgrade.
#### Use TiDB Operator to upgrade

Currently, this feature is not supported. It will be supported as soon as possible.

#### Other upgrade methods

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.
hfxsd marked this conversation as resolved.
Show resolved Hide resolved

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.

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

Expand All @@ -54,3 +92,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 performed on non-system tables, the upgrade might fail.
Loading