Skip to content
40 changes: 23 additions & 17 deletions upgrade-tidb-using-tiup.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,26 @@ aliases: ['/docs-cn/dev/upgrade-tidb-using-tiup/','/docs-cn/dev/how-to/upgrade/u

# 使用 TiUP 升级 TiDB

本文档适用于使用 TiUP 从 TiDB 4.0 版本升级至 TiDB 5.0 版本,以及从 5.0 版本升级至后续修订版本。
本文档适用于以下升级路径:
Comment thread
TomShawn marked this conversation as resolved.

如果原集群是 3.0 或 3.1 或更老的版本,需要先升级到 4.0 后再升级到 5.0,不可跨主版本升级。
- 使用 TiUP 从 TiDB 4.0 版本升级至 TiDB 5.1 及后续修订版本。
- 使用 TiUP 从 TiDB 5.0 版本升级至 TiDB 5.1 及后续修订版本。

> **注意:**
>
> 如果原集群是 3.0 或 3.1 或更早的版本,不支持直接升级到 5.1 及后续修订版本。你需要先从早期版本升级到 4.0 后,再从 4.0 升级到 5.1 及后续修订版本。

## 1. 升级兼容性说明

- 不支持在升级后回退至 4.0 或更旧版本
- 使用 TiDB Ansible 管理的 4.0 版本集群,需要先按照 [4.0 版本文档的说明](https://docs.pingcap.com/zh/tidb/v4.0/upgrade-tidb-using-tiup)将集群导入到 TiUP (`tiup cluster`) 管理后,再按本文档说明升级到 5.0 版本
- 若要将 3.0 之前的版本升级至 5.0 版本:
- TiDB 目前暂不支持版本降级或升级后回退
- 使用 TiDB Ansible 管理的 4.0 版本集群,需要先按照 [4.0 版本文档的说明](https://docs.pingcap.com/zh/tidb/v4.0/upgrade-tidb-using-tiup)将集群导入到 TiUP (`tiup cluster`) 管理后,再按本文档说明升级到 5.1 版本及后续修订版本
- 若要将 3.0 之前的版本升级至 5.1 版本:
1. 首先[通过 TiDB Ansible 升级到 3.0 版本](https://docs.pingcap.com/zh/tidb/v3.0/upgrade-tidb-using-ansible)。
2. 然后按照 [4.0 版本文档的说明](https://docs.pingcap.com/zh/tidb/v4.0/upgrade-tidb-using-tiup),使用 TiUP (`tiup cluster`) 将 TiDB Ansible 配置导入。
3. 将集群升级至 4.0 版本。
4. 按本文档说明将集群升级到 5.0 版本。
4. 按本文档说明将集群升级到 5.1 版本。
- 支持 TiDB Binlog,TiCDC,TiFlash 等组件版本的升级。
- 具体不同版本的兼容性说明,请查看各个版本的 [Release Note](/releases/release-notes.md)。请根据各个版本的 Release Note 的兼容性更改调整集群的配置。

> **注意:**
>
Expand All @@ -36,7 +42,7 @@ aliases: ['/docs-cn/dev/upgrade-tidb-using-tiup/','/docs-cn/dev/how-to/upgrade/u
>
> 如果原集群中控机不能访问 `https://tiup-mirrors.pingcap.com` 地址,可跳到步骤 2.2 使用离线升级方式。

1. 先升级 TiUP 版本(建议 `tiup` 版本不低于 `1.4.0`):
1. 先升级 TiUP 版本(建议 `tiup` 版本不低于 `1.5.0`):

{{< copyable "shell-regular" >}}

Expand All @@ -45,7 +51,7 @@ aliases: ['/docs-cn/dev/upgrade-tidb-using-tiup/','/docs-cn/dev/how-to/upgrade/u
tiup --version
```

2. 再升级 TiUP Cluster 版本(建议 `tiup cluster` 版本不低于 `1.4.0`):
2. 再升级 TiUP Cluster 版本(建议 `tiup cluster` 版本不低于 `1.5.0`):

{{< copyable "shell-regular" >}}

Expand Down Expand Up @@ -87,7 +93,7 @@ tiup update cluster
> 以下情况可跳过此步骤:
>
> - 原集群没有修改过配置参数,或通过 tiup cluster 修改过参数但不需要调整。
> - 升级后对未修改过的配置项希望使用 `5.0` 默认参数。
> - 升级后对未修改过的配置项希望使用 `5.1` 默认参数。

1. 进入拓扑文件的 `vi` 编辑模式:

Expand All @@ -103,9 +109,9 @@ tiup update cluster

> **注意:**
>
> 升级到 5.0 版本前,请确认已在 4.0 修改的参数在 5.0 版本中是兼容的,可参考 [TiKV 配置文件描述](/tikv-configuration-file.md)。
> 升级到 5.1 版本前,请确认已在 4.0 修改的参数在 5.1 版本中是兼容的,可参考 [TiKV 配置文件描述](/tikv-configuration-file.md)。
>
> 以下 TiKV 参数在 TiDB v5.0 已废弃。如果在原集群配置过以下参数,需要通过 `edit-config` 编辑模式删除这些参数:
> 以下 TiKV 参数在 TiDB v5.1 已废弃。如果在原集群配置过以下参数,需要通过 `edit-config` 编辑模式删除这些参数:
>
> - pessimistic-txn.enabled
> - server.request-batch-enable-cross-command
Expand Down Expand Up @@ -139,12 +145,12 @@ tiup cluster check <cluster-name> --cluster
tiup cluster upgrade <cluster-name> <version>
```

以升级到 5.0.0 版本为例:
以升级到 5.1.0 版本为例:

{{< copyable "shell-regular" >}}

```
tiup cluster upgrade <cluster-name> v5.0.0
tiup cluster upgrade <cluster-name> v5.1.0
```

> **注意:**
Expand Down Expand Up @@ -192,7 +198,7 @@ tiup cluster display <cluster-name>
```
Cluster type: tidb
Cluster name: <cluster-name>
Cluster version: v5.0.0
Cluster version: v5.1.0
```

> **注意:**
Expand Down Expand Up @@ -242,10 +248,10 @@ tiup cluster upgrade <cluster-name> <version> --force
{{< copyable "" >}}

```
tiup install ctl:v5.0.0
tiup install ctl:v5.1.0
```

## 5. TiDB 5.1 兼容性变化

- 兼容性变化请参考 5.1 GA Release Notes。
- 请避免在对使用 TiDB-Binlog 的集群进行滚动升级过程中新创建聚簇索引表。
- 兼容性变化请参考 5.1 Release Notes。
- 请避免在对使用 TiDB-Binlog 的集群进行滚动升级过程中新创建聚簇索引表。