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

このドキュメントは、v6.1.x、v6.5.x、v7.1.x、v7.5.x、v8.1.x、v8.2.0、v8.3.0、および v8.4.0 から TiDB v8.5.x へのアップグレードに適用されます。

警告

TiDBをアップグレードする前に、ご使用のオペレーティングシステムのバージョンがOSおよびプラットフォームの要件満たしていることを確認してください。CentOS Linux 7で稼働しているクラスタをv8.5にアップグレードする場合は、クラスタが利用できなくなるリスクを回避するため、TiDB v8.5.1以降のバージョンを使用してください。詳細については、 TiDB v8.5.1 リリースノート参照してください。
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 以降の場合は、前述の警告 3 と 4 は無視できます。詳細については、 TiDBスムーズアップグレードの使用に関する制限参照してください。
TiUPを使用して TiDB クラスターをアップグレードする前に、必ずユーザー操作の制限お読みください。

注記：
アップグレード対象のクラスターがバージョン6.2より前のバージョンの場合、一部のシナリオでは、クラスターをバージョン6.2以降にアップグレードすると、アップグレードが停止する可能性があります問題を解決する方法を参照してください。
TiDBノードは、構成項目server-versionの値を使用して現在のTiDBバージョンを確認します。そのため、予期しない動作を回避するには、TiDBクラスタをアップグレードする前に、値server-versionを空または現在のTiDBクラスタの実際のバージョンに設定する必要があります。
設定項目performance.force-init-stats ONに設定すると、TiDB の起動時間が長くなり、起動タイムアウトやアップグレード失敗が発生する可能性があります。この問題を回避するには、 TiUPの待機タイムアウトを長めに設定することをお勧めします。
影響を受ける可能性のあるシナリオ:
元のクラスターバージョンは v6.5.7 および v7.1.0 ( performance.force-init-statsはまだサポートされていません) より前であり、ターゲットバージョンは v7.2.0 以降です。
元のクラスターのバージョンは v6.5.7 および v7.1.0 以上であり、 performance.force-init-stats構成項目はONに設定されています。
performance.force-init-stats構成項目の値を確認します。
SHOW CONFIG WHERE type = 'tidb' AND name = 'performance.force-init-stats';
コマンドラインオプション--wait-timeoutを追加することで、 TiUP の待機タイムアウトを長くすることができます。例えば、以下のコマンドを実行すると、待機タイムアウトが 1200 秒（20 分）に設定されます。
tiup update cluster --wait-timeout 1200 [other options]
一般的に、ほとんどのシナリオでは20分の待機タイムアウトで十分です。より正確な推定値を得るには、TiDBログでinit stats info time検索し、前回の起動時の統計読み込み時間を参考にしてください。例えば、
[domain.go:2271] ["init stats info time"] [lite=true] ["take time"=2.151333ms]
元のクラスターがv7.1.0以前の場合、v7.2.0以降にアップグレードすると、 performance.lite-init-statsの導入により統計情報の読み込み時間が大幅に短縮されます。この場合、アップグレード前のinit stats info timeアップグレード後の読み込み時間よりも長くなります。
TiDBのローリングアップグレード期間を短縮したい場合、かつアップグレード中に初期統計情報が失われることによるパフォーマンスへの影響がクラスターにとって許容範囲内であれば、アップグレード前にperformance.force-init-statsをOFF設定し、 TiUPを使用してターゲットインスタンスの構成を変更するを加算することができます。アップグレードが完了したら、必要に応じてこの設定を再評価し、元に戻すことができます。

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

現在、TiDB は、アップグレード後のバージョンのダウングレードまたは以前のバージョンへのロールバックをサポートしていません。
TiCDC、 TiFlash、およびその他のコンポーネントのバージョンのアップグレードをサポートします。
TiFlashをv6.3.0より前のバージョンからv6.3.0以降のバージョンにアップグレードする場合、CPUがLinux AMD64アーキテクチャではAVX2命令セット、Linux ARM64アーキテクチャではARMv8命令セットアーキテクチャをサポートしている必要があることに注意してください。詳細については、 v6.3.0 リリースノートの説明を参照してください。
各バージョン間の互換性に関する変更の詳細については、各バージョンのリリースノートご覧ください。対応するリリースノートの「互換性の変更」セクションに従って、クラスター構成を変更してください。
クラスターをv5.3より前のバージョンからv5.3以降のバージョンにアップデートする場合、デフォルトでデプロイされているPrometheusによって生成されるアラートの時刻形式が変更されていることにご注意ください。この形式の変更は、Prometheus v2.27.1から導入されています。詳細については、プロメテウスコミットご覧ください。

準備

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

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

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

以下は、v8.4.0から最新バージョン（v8.5.3）にアップグレードする際に知っておくべきリリースノートです。v8.3.0以前のバージョンから最新バージョンにアップグレードする場合は、中間バージョンリリースノート確認する必要があるかもしれません。

ステップ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クラスタのバージョンをアップグレードしてください。TiUPTiUPのバージョンは1.11.3以降が推奨されます。
```
tiup update cluster
tiup cluster --version
```

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

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

TiUPを使用して TiDBクラスタをデプロイ- TiUPをオフラインでデプロイを参照して、新しいバージョンのTiUPミラーをダウンロードし、制御マシンにアップロードしてください。3 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使用して構成パラメータを変更しましたが、それ以上の変更は必要ありません。
アップグレード後、変更されていない構成項目に対して、v8.5.3 のデフォルトのパラメータ値を使用します。

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

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

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

クラスタDDL:
- スムーズなアップグレード使用して TiDB を v8.1.0 以降にアップグレードし、分散実行フレームワーク (DXF)有効になっている場合は、アップグレード前に DXF を無効にすることをお勧めします。そうしないと、アップグレードプロセス中に追加されたインデックスがデータと不整合になり、アップグレードが失敗する可能性があります。
- スムーズなアップグレード使用しない場合は、 ADMIN SHOW DDLステートメントを使用して、実行中の DDL ジョブが存在するかどうかを確認することをお勧めします。実行中の DDL ジョブが存在する場合は、アップグレードを実行する前に、その実行が完了するまで待つか、 ADMIN CANCEL DDLステートメントを使用してキャンセルしてください。
クラスタのバックアップ：クラスター内で実行中のバックアップまたは復元タスクがあるかどうかを確認するために、 SHOW [BACKUPS|RESTORES]ステートメントを実行することをお勧めします。実行中の場合は、アップグレードを実行する前に完了をお待ちください。

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

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

tiup cluster check <cluster-name> --cluster

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

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

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

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

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

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

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

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

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

tiup cluster upgrade <cluster-name> <version>

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

tiup cluster upgrade <cluster-name> v8.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をアップグレードする参照してください。

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

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

注記：
TiDB、TiKV、PD、TiCDC など、バージョン番号を共有するコンポーネントについては、混在バージョンのデプロイメントシナリオで正常に動作することを保証するための完全なテストは用意されていません。このセクションはテスト環境でのみ使用するか、テクニカルサポートの支援を受けて使用してください。

tiup cluster upgrade -h | grep "version"
      --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>にはアップグレードするバージョン（例： v8.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:    v8.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>アップグレードするバージョン（例： v8.5.3 ）です。

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

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

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

tiup install ctl:v8.5.3