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

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

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

注記：

• アップグレードするクラスターが v3.1 またはそれ以前のバージョン (v3.0 または v2.1) の場合、v8.1.0 への直接アップグレードはサポートされていません。最初にクラスターを v4.0 にアップグレードし、次に v8.1.0 にアップグレードする必要があります。

• アップグレードするクラスターが v6.2 より前の場合、一部のシナリオではクラスターを v6.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をTiUPを使用してターゲットインスタンスの構成を変更するに設定してOFF設定できます。アップグレードが完了したら、必要に応じてこの設定を再評価して元に戻すことができます。

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

• TiDB は現在、アップグレード後のバージョンのダウングレードや以前のバージョンへのロールバックをサポートしていません。
• TiDB Ansibleを使用して管理されているv4.0クラスターの場合、 TiUP (v4.0) を使用して TiDB をアップグレードするに従って新しい管理のためにクラスターをTiUP （ tiup cluster ）にインポートする必要があります。その後、このドキュメントに従ってクラスターをv8.1.0にアップグレードできます。
• v3.0 より前のバージョンを v8.1.0 に更新するには:
  1. TiDB アンシブルを使用してこのバージョンを 3.0 に更新します。
  2. TiUP （ tiup cluster ）を使用してTiDB Ansible設定をインポートします。
  3. TiUP (v4.0) を使用して TiDB をアップグレードするに従って 3.0 バージョンを 4.0 に更新します。
  4. このドキュメントに従ってクラスターを v8.1.0 にアップグレードします。
• 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 v8.1.0 リリース ノートの互換性の変更確認してください。アップグレードに影響する変更がある場合は、それに応じて対処してください。

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

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

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

注記：

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

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

   tiup update --self
   tiup --version
   

2. 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を使用して構成パラメータを変更しましたが、それ以上の変更は必要ありません。
• アップグレード後、変更されていない構成項目に対して v8.1.0 のデフォルトのパラメータ値を使用します。

1. トポロジファイルを編集するには、 vi編集モードに入ります。

   tiup cluster edit-config <cluster-name>
   

2. トポロジーの構成テンプレートの形式を参照して、トポロジ ファイルのserver_configsセクションに変更するパラメータを入力します。

3. 変更後、 : + w + qと入力して変更を保存し、編集モードを終了します。変更を確認するには、 Yと入力します。

注記：

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

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

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

• クラスタDDL: 実行中の DDL ジョブがあるかどうかを確認するには、 ADMIN SHOW 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>

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

tiup cluster upgrade <cluster-name> v8.1.0

注記：

• オンライン アップグレードでは、すべてのコンポーネントが 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"
      --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.

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

1. オフライン アップグレードを行う前に、まずクラスター全体を停止する必要があります。

   tiup cluster stop <cluster-name>
   

2. オフライン アップグレードを実行するには、 upgradeコマンドを--offlineオプションとともに使用します。 <cluster-name>にはクラスターの名前を入力し、 <version>にはアップグレードするバージョン ( v8.1.0など) を入力します。

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

3. アップグレード後、クラスターは自動的に再起動されません。再起動するには、 startコマンドを使用する必要があります。

   tiup cluster start <cluster-name>
   

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

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

tiup cluster display <cluster-name>

Cluster type:       tidb
Cluster name:       <cluster-name>
Cluster version:    v8.1.0

FAQ

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

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

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

1. 操作記録を表示するには、 tiup cluster audit実行します。

   tiup cluster audit
   

   失敗したアップグレード操作レコードを見つけて、この操作レコードの ID を保持します。ID は次の手順の<audit-id>値です。

2. 対応する操作を再試行するには、 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.1.0 。

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

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

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

tiup install ctl:v8.1.0