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 1 commit
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
48 changes: 40 additions & 8 deletions smooth-upgrade-tidb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,20 @@ summary: This document introduces the smooth upgrade feature of TiDB, which supp

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

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

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.
* Perform system DDL operations during the upgrade process.
hfxsd marked this conversation as resolved.
Show resolved Hide resolved

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