重要

このページは英語版のページを機械翻訳しています。原文はこちらからご覧ください。

TiUPを使用して TiDB をアップグレードする

このドキュメントは、次のアップグレードパスを対象としています。

TiDB 4.0 バージョンから TiDB 7.5 にアップグレードします。
TiDB 5.0-5.4 バージョンから TiDB 7.5 にアップグレードします。
TiDB 6.0-6.6 から TiDB 7.5 にアップグレードします。
TiDB 7.0-7.4 から TiDB 7.5 にアップグレードします。

警告

TiFlash を5.3 より前のバージョンから 5.3 以降にオンラインでアップグレードすることはできません。代わりに、まず以前のバージョンのすべてのTiFlashインスタンスを停止してから、クラスターをオフラインでアップグレードする必要があります。他のコンポーネント (TiDB や TiKV など) がオンラインアップグレードをサポートしていない場合は、オンラインアップグレードの警告の手順に従ってください。
アップグレードプロセス中に DDL ステートメントを実行しないでください。そうしないと、未定義の動作の問題が発生する可能性があります。
クラスター内で DDL ステートメントが実行されているときは、TiDB クラスターをアップグレードしないでください(通常は、 ADD INDEXや列タイプの変更などの時間のかかる DDL ステートメントの場合)。アップグレードの前に、 ADMIN SHOW DDLコマンドを使用して、TiDB クラスターに実行中の DDL ジョブがあるかどうかを確認することをお勧めします。クラスターに DDL ジョブがある場合は、クラスターをアップグレードする前に、DDL の実行が完了するまで待つか、 ADMIN CANCEL DDLコマンドを使用して DDL ジョブをキャンセルしてください。
アップグレード前の TiDB バージョンが 7.1.0 以降の場合、前述の警告 2 と 3 は無視できます。詳細については、 TiDB スムーズアップグレードの使用に関する制限参照してください。
TiUPを使用して TiDB クラスターをアップグレードする前に、必ずユーザー操作の制限お読みください。

注記：
アップグレードするクラスターが v3.1 またはそれ以前のバージョン (v3.0 または v2.1) の場合、v7.5.0 またはそれ以降の v7.5.x バージョンへの直接アップグレードはサポートされていません。最初にクラスターを v4.0 にアップグレードしてから、ターゲットの TiDB バージョンにアップグレードする必要があります。
アップグレードするクラスターが v6.2 より前の場合、一部のシナリオでは、クラスターを v6.2 以降のバージョンにアップグレードすると、アップグレードが停止する可能性があります。問題を解決する方法を参照してください。
TiDB ノードは、構成項目server-versionの値を使用して現在の TiDB バージョンを確認します。したがって、予期しない動作を回避するには、TiDB クラスターをアップグレードする前に、値server-versionを空に設定するか、現在の TiDB クラスターの実際のバージョンに設定する必要があります。

アップグレードの注意事項

TiDB は現在、アップグレード後のバージョンのダウングレードや以前のバージョンへのロールバックをサポートしていません。
TiDB Ansibleを使用して管理されているv4.0クラスターの場合、 TiUP (v4.0) を使用して TiDB をアップグレードするに従って新しい管理のためにクラスターをTiUP （ tiup cluster ）にインポートする必要があります。その後、このドキュメントに従ってクラスターをv7.5.3にアップグレードできます。
v3.0 より前のバージョンを v7.5.3 に更新するには:
1. TiDB アンシブルを使用してこのバージョンを 3.0 に更新します。
2. TiUP （ tiup cluster ）を使用してTiDB Ansible構成をインポートします。
3. TiUP (v4.0) を使用して TiDB をアップグレードするに従って 3.0 バージョンを 4.0 に更新します。
4. このドキュメントに従ってクラスターを v7.5.3 にアップグレードします。
TiDB Binlog、TiCDC、 TiFlash、およびその他のコンポーネントのバージョンのアップグレードをサポートします。
TiFlash をv6.3.0 より前のバージョンから v6.3.0 以降のバージョンにアップグレードする場合、CPU が Linux AMD64アーキテクチャの AVX2 命令セットと Linux ARM64アーキテクチャの ARMv8 命令セットアーキテクチャをサポートしている必要があることに注意してください。詳細については、 v6.3.0 リリースノートの説明を参照してください。
異なるバージョンの詳細な互換性の変更については、各バージョンのリリースノート参照してください。対応するリリースノートの「互換性の変更」セクションに従って、クラスター構成を変更します。
v5.3 より前のバージョンから v5.3 以降のバージョンにアップグレードするクラスターの場合、デフォルトでデプロイされている Prometheus は v2.8.1 から v2.27.1 にアップグレードされます。Prometheus v2.27.1 では、より多くの機能が提供され、セキュリティ問題が修正されています。v2.8.1 と比較して、v2.27.1 ではアラート時間の表現が変更されています。詳細については、プロメテウスコミット参照してください。

準備

このセクションでは、 TiUPおよびTiUPクラスタコンポーネントのアップグレードなど、TiDB クラスターをアップグレードする前に必要な準備作業について説明します。

ステップ1: 互換性の変更を確認する

TiDB リリースノートで互換性の変更を確認してください。変更がアップグレードに影響する場合は、それに応じて対処してください。

以下は、v7.5.0 から現在のバージョン (v7.5.3) にアップグレードするときに知っておく必要がある互換性の変更点を示しています。v7.4.0 以前のバージョンから現在のバージョンにアップグレードする場合は、対応するリリースノート中間バージョンで導入された互換性の変更点も確認する必要がある可能性があります。

TiDB v7.5.0 互換性の変更
TiDB v7.5.1 互換性の変更
TiDB v7.5.2 互換性の変更
TiDB v7.5.3 互換性の変更

ステップ2: TiUPまたはTiUPオフラインミラーをアップグレードする

TiDB クラスターをアップグレードする前に、まずTiUPまたはTiUPミラーをアップグレードする必要があります。

TiUPとTiUPクラスタのアップグレード

注記：
アップグレードするクラスターの制御マシンがhttps://tiup-mirrors.pingcap.comアクセスできない場合は、このセクションをスキップしてTiUPオフラインミラーのアップグレードを参照してください。

TiUPバージョンをアップグレードします。TiUP バージョンは1.11.3以降が推奨されます。

tiup update --self
tiup --version

TiUPクラスタのバージョンをアップグレードします。TiUPクラスタのTiUPは1.11.3以降にすることをお勧めします。
```
tiup update cluster
tiup cluster --version
```

TiUPオフラインミラーのアップグレード

注記：
アップグレードするクラスターがオフライン方式を使用せずにデプロイされた場合は、この手順をスキップします。

TiUPを使用して TiDBクラスタをデプロイ- TiUPをオフラインでデプロイを参照して、新しいバージョンのTiUPミラーをダウンロードし、制御マシンにアップロードします。 local_install.shを実行すると、 TiUP は上書きアップグレードを完了します。

tar xzvf tidb-community-server-${version}-linux-amd64.tar.gz
sh tidb-community-server-${version}-linux-amd64/local_install.sh
source /home/tidb/.bash_profile

上書きアップグレード後、次のコマンドを実行して、サーバーおよびツールキットのオフラインミラーをサーバーディレクトリにマージします。

tar xf tidb-community-toolkit-${version}-linux-amd64.tar.gz
ls -ld tidb-community-server-${version}-linux-amd64 tidb-community-toolkit-${version}-linux-amd64
cd tidb-community-server-${version}-linux-amd64/
cp -rp keys ~/.tiup/
tiup mirror merge ../tidb-community-toolkit-${version}-linux-amd64

ミラーをマージした後、次のコマンドを実行してTiUPクラスタコンポーネントをアップグレードします。

tiup update cluster

これで、オフラインミラーのアップグレードは成功しました。上書き後のTiUP操作中にエラーが発生した場合は、 manifestが更新されていない可能性があります。TiUPを再度実行する前に、 rm -rf ~/.tiup/manifests/*試してください。

ステップ3: TiUPトポロジ構成ファイルを編集する

注記：
次のいずれかの状況に該当する場合は、この手順をスキップしてください。
元のクラスターの構成パラメータを変更していません。または、 tiup clusterを使用して構成パラメータを変更しましたが、それ以上の変更は必要ありません。
アップグレード後、変更されていない構成項目に対して v7.5.3 のデフォルトのパラメータ値を使用します。

トポロジファイルを編集するには、 vi編集モードに入ります。
```
tiup cluster edit-config <cluster-name>
```
トポロジーの構成テンプレートの形式を参照して、トポロジファイルのserver_configsセクションに変更するパラメータを入力します。
変更後、 : + w + qと入力して変更を保存し、編集モードを終了します。変更を確認するには、 Yと入力します。

注記：
クラスターを v6.6.0 にアップグレードする前に、v4.0 で変更したパラメータが v7.5.3 と互換性があることを確認してください。詳細については、 TiKVコンフィグレーションファイル参照してください。

ステップ4: クラスターのDDLとバックアップのステータスを確認する

アップグレード中に未定義の動作やその他の予期しない問題を回避するために、アップグレード前に次の項目を確認することをお勧めします。

クラスタDDL:
- スムーズなアップグレード使用する場合、TiDB クラスターの DDL 操作を確認する必要はありません。DDL ジョブの完了を待ったり、進行中の DDL ジョブをキャンセルしたりする必要はありません。
- スムーズなアップグレード使用しない場合は、 ADMIN SHOW DDLステートメントを使用して、実行中の DDL ジョブが存在するかどうかを確認することをお勧めします。実行中の DDL ジョブが存在する場合は、アップグレードを実行する前に、その実行が完了するまで待つか、 ADMIN CANCEL DDLステートメントを使用してキャンセルしてください。
クラスタバックアップ: クラスター内で実行中のバックアップまたは復元タスクがあるかどうかを確認するには、 SHOW [BACKUPS|RESTORES]ステートメントを実行することをお勧めします。実行中の場合は、アップグレードを実行する前に完了するまで待機します。

ステップ5: 現在のクラスターのヘルスステータスを確認する

アップグレード中に未定義の動作やその他の問題を回避するには、アップグレード前に現在のクラスターのリージョンのヘルスステータスを確認することをお勧めします。これを行うには、 checkサブコマンドを使用できます。

tiup cluster check <cluster-name> --cluster

コマンドを実行すると、「リージョンステータス」のチェック結果が出力されます。

結果が「すべてのリージョンが正常です」の場合、現在のクラスター内のすべてのリージョンが正常であり、アップグレードを続行できます。
結果が「リージョンが完全に正常ではありません: m ミスピア、n 保留中のピア」で、「他の操作の前に、異常なリージョンを修正してください。」というプロンプトが表示される場合、現在のクラスター内の一部のリージョンが異常です。チェック結果が「すべてのリージョンが正常です」になるまで、異常をトラブルシューティングする必要があります。その後、アップグレードを続行できます。

TiDBクラスタをアップグレードする

このセクションでは、TiDB クラスターをアップグレードし、アップグレード後のバージョンを確認する方法について説明します。

TiDBクラスタを指定のバージョンにアップグレードする

クラスターは、オンラインアップグレードとオフラインアップグレードの 2 つの方法のいずれかでアップグレードできます。

デフォルトでは、 TiUP クラスタはオンライン方式を使用して TiDB クラスターをアップグレードします。つまり、TiDB クラスターはアップグレードプロセス中でも引き続きサービスを提供できます。オンライン方式では、アップグレードと再起動の前に、各ノードでリーダーが 1 つずつ移行されます。そのため、大規模なクラスターの場合、アップグレード操作全体が完了するまでに長い時間がかかります。

アプリケーションに、メンテナンスのためにデータベースを停止するメンテナンスウィンドウがある場合は、オフラインアップグレードメソッドを使用して、アップグレード操作を迅速に実行できます。

オンラインアップグレード

tiup cluster upgrade <cluster-name> <version>

たとえば、クラスターを v7.5.3 にアップグレードする場合は、次のようにします。

tiup cluster upgrade <cluster-name> v7.5.3

注記：
オンラインアップグレードでは、すべてのコンポーネントが 1 つずつアップグレードされます。TiKV のアップグレード中、インスタンスを停止する前に、TiKV インスタンス内のすべてのリーダーが削除されます。デフォルトのタイムアウト時間は 5 分 (300 秒) です。このタイムアウト時間が経過すると、インスタンスは直接停止されます。
--forceパラメータを使用すると、リーダーを削除せずにクラスターをすぐにアップグレードできます。ただし、アップグレード中に発生したエラーは無視されるため、アップグレードの失敗は通知されません。したがって、 --forceパラメータは慎重に使用してください。
安定したパフォーマンスを維持するには、インスタンスを停止する前に、TiKV インスタンス内のすべてのリーダーが排除されていることを確認してください。1 --transfer-timeout --transfer-timeout 3600 (単位: 秒) などのより大きな値に設定できます。
TiFlashを v5.3.0 より前のバージョンから v5.3.0 以降にアップグレードするには、 TiFlashを停止してからアップグレードする必要があり、 TiUP のバージョンは v1.12.0 より前である必要があります。詳細については、 TiUPを使用してTiFlashをアップグレードする参照してください。
TiDB Binlogを使用してクラスターにローリング更新を適用するときは、新しいクラスター化インデックステーブルを作成しないようにしてください。

アップグレード中にコンポーネントのバージョンを指定する

tiup-cluster v1.14.0 以降では、クラスターのアップグレード中に特定のコンポーネントを特定のバージョンに指定できます。これらのコンポーネントは、別のバージョンを指定しない限り、後続のアップグレードでも固定バージョンのままになります。

注記：
TiDB、TiKV、PD、TiCDC など、バージョン番号を共有するコンポーネントについては、混合バージョンの展開シナリオで正しく動作することを確認するための完全なテストはありません。このセクションは、テスト環境でのみ使用するか、テクニカルサポートの助けを借りて使用してください。

tiup cluster upgrade -h | grep "version string"
      --alertmanager-version string        Fix the version of alertmanager and no longer follows the cluster version.
      --blackbox-exporter-version string   Fix the version of blackbox-exporter and no longer follows the cluster version.
      --cdc-version string                 Fix the version of cdc and no longer follows the cluster version.
      --ignore-version-check               Ignore checking if target version is bigger than current version.
      --node-exporter-version string       Fix the version of node-exporter and no longer follows the cluster version.
      --pd-version string                  Fix the version of pd and no longer follows the cluster version.
      --tidb-dashboard-version string      Fix the version of tidb-dashboard and no longer follows the cluster version.
      --tiflash-version string             Fix the version of tiflash and no longer follows the cluster version.
      --tikv-cdc-version string            Fix the version of tikv-cdc and no longer follows the cluster version.
      --tikv-version string                Fix the version of tikv and no longer follows the cluster version.
      --tiproxy-version string             Fix the version of tiproxy and no longer follows the cluster version.

オフラインアップグレード

オフラインアップグレードを実行する前に、まずクラスター全体を停止する必要があります。
```
tiup cluster stop <cluster-name>
```
オフラインアップグレードを実行するには、 upgradeコマンドを--offlineオプションとともに使用します。 <cluster-name>にはクラスターの名前を入力し、 <version>にはアップグレードするバージョン ( v7.5.3など) を入力します。
```
tiup cluster upgrade <cluster-name> <version> --offline
```
アップグレード後、クラスターは自動的に再起動されません。再起動するには、 startコマンドを使用する必要があります。
```
tiup cluster start <cluster-name>
```

クラスターのバージョンを確認する

最新のクラスターバージョンTiDB Versionを表示するには、コマンドdisplayを実行します。

tiup cluster display <cluster-name>

Cluster type:       tidb
Cluster name:       <cluster-name>
Cluster version:    v7.5.3

FAQ

このセクションでは、 TiUPを使用して TiDB クラスターを更新するときに発生する一般的な問題について説明します。

エラーが発生してアップグレードが中断された場合、このエラーを修正した後でアップグレードを再開するにはどうすればよいですか?

アップグレードを再開するには、 tiup cluster upgradeコマンドを再実行します。アップグレード操作により、以前にアップグレードされたノードが再起動されます。アップグレードされたノードを再起動したくない場合は、 replayサブコマンドを使用して操作を再試行します。

操作記録を表示するには、 tiup cluster audit実行します。
```
tiup cluster audit
```
失敗したアップグレード操作レコードを見つけて、この操作レコードの ID を保持します。ID は次の手順の<audit-id>値です。
対応する操作を再試行するには、 tiup cluster replay <audit-id>実行します。
```
tiup cluster replay <audit-id>
```

v6.2.0 以降のバージョンにアップグレードするときにアップグレードが停止する問題を修正するにはどうすればよいですか?

v6.2.0 以降、TiDB では、並行DDLフレームワークがデフォルトで同時 DDL を実行できるようになりました。このフレームワークでは、DDL ジョブstorageがKV キューからテーブルキューに変更されます。この変更により、一部のシナリオでアップグレードが停止する可能性があります。この問題を引き起こす可能性のあるシナリオと、それに対応する解決策を次に示します。

プラグインの読み込みによりアップグレードが停止する
アップグレード中に、DDL ステートメントの実行を必要とする特定のプラグインをロードすると、アップグレードが停止する可能性があります。
解決策: アップグレード中にプラグインをロードしないでください。代わりに、アップグレードが完了した後にのみプラグインをロードします。
オフラインアップグレードにkill -9コマンドを使用したため、アップグレードが停止しました
- 注意事項: オフラインアップグレードを実行するためにkill -9コマンドを使用しないでください。必要な場合は、2 分後に新しいバージョンの TiDB ノードを再起動してください。
- アップグレードがすでに停止している場合は、影響を受ける TiDB ノードを再起動します。問題が発生したばかりの場合は、2 分後にノードを再起動することをお勧めします。
DDL 所有者の変更によりアップグレードが停止する
複数インスタンスのシナリオでは、ネットワークまたはハードウェアの障害により DDL 所有者が変更される可能性があります。アップグレードフェーズで未完了の DDL ステートメントがある場合、アップグレードが停止する可能性があります。
解決：
1. スタックした TiDB ノードを終了します ( kill -9使用は避けてください)。
2. 新しいバージョンの TiDB ノードを再起動します。

アップグレード中にエビクトリーダーが長時間待機しました。この手順をスキップして迅速にアップグレードするにはどうすればよいでしょうか。

--forceを指定できます。その場合、アップグレード中に PD リーダーの転送と TiKV リーダーの削除のプロセスがスキップされます。クラスターは直接再起動されてバージョンが更新されるため、オンラインで実行されるクラスターに大きな影響を与えます。次のコマンドでは、 <version>アップグレードするバージョンです (例: v7.5.3 。

tiup cluster upgrade <cluster-name> <version> --force

TiDB クラスターをアップグレードした後、pd-ctl などのツールのバージョンを更新するにはどうすればよいですか?

TiUPを使用して対応するバージョンのctlコンポーネントをインストールすることで、ツールのバージョンをアップグレードできます。

tiup install ctl:v7.5.3