バックアップと復元にBRコマンドラインを使用する

このドキュメントでは、BRコマンドラインを使用してTiDBクラスタデータをバックアップおよび復元する方法について説明します。

BRツールの概要 、特に使用制限とベストプラクティスを読んだことを確認してください。

BRコマンドラインの説明

brコマンドは、サブコマンド、オプション、およびパラメーターで構成されます。

• サブコマンド： -または--のない文字。
• オプション： -または--で始まる文字。
• パラメーター：直後に続き、サブコマンドまたはオプションに渡される文字。

これは完全なbrのコマンドです。

br backup full --pd "${PDIP}:2379" -s "local:///tmp/backup"

上記のコマンドの説明は次のとおりです。

• backup ： brのサブコマンド。
• full ： backupのサブコマンド。
• -s （または--storage ）：バックアップファイルが保存されるパスを指定するオプション。
• "local:///tmp/backup" ： -sのパラメータ。 /tmp/backupは、各TiKVノードのバックアップファイルが保存されているローカルディスク内のパスです。
• --pd ：配置ドライバー（PD）サービスアドレスを指定するオプション。
• "${PDIP}:2379" ： --pdのパラメータ。

ノート：

• localのストレージを使用すると、バックアップデータは各ノードのローカルファイルシステムに分散されます。

• データの復元を完了するには、これらのデータを手動で集約する必要があるため、実稼働環境でローカルディスクにバックアップすることはお勧めしません。詳細については、 クラスターデータの復元を参照してください。

• これらのバックアップデータを集約すると、冗長性が生じ、運用や保守に支障をきたす可能性があります。さらに悪いことに、これらのデータを集約せずにデータを復元すると、かなり紛らわしいエラーメッセージSST file not foundを受け取る可能性があります。

• 各ノードにNFSディスクをマウントするか、 S3のオブジェクトストレージにバックアップすることをお勧めします。

サブコマンド

brのコマンドは、サブコマンドの複数のレイヤーで構成されます。現在、BRには次の3つのサブコマンドがあります。

• br backup ：TiDBクラスタのデータをバックアップするために使用されます。
• br restore ：TiDBクラスタのデータを復元するために使用されます。

上記の3つのサブコマンドのそれぞれに、操作の範囲を指定するための次の3つのサブコマンドが含まれている場合があります。

• full ：すべてのクラスタデータをバックアップまたは復元するために使用されます。
• db ：クラスタの指定されたデータベースをバックアップまたは復元するために使用されます。
• table ：クラスタの指定されたデータベース内の単一のテーブルをバックアップまたは復元するために使用されます。

一般的なオプション

• --pd ：接続に使用され、PDサーバーアドレスを指定します。たとえば、 "${PDIP}:2379" 。
• -h （または--help ）：すべてのサブコマンドのヘルプを取得するために使用されます。たとえば、 br backup --help 。
• -V （または--version ）：BRのバージョンを確認するために使用されます。
• --ca ：信頼できるCA証明書へのパスをPEM形式で指定します。
• --cert ：SSL証明書へのパスをPEM形式で指定します。
• --key ：SSL証明書キーへのパスをPEM形式で指定します。
• --status-addr ：BRがPrometheusに統計を提供するためのリスニングアドレスを指定します。

BRコマンドラインを使用してクラスタデータをバックアップする

クラスタデータをバックアップするには、 br backupコマンドを使用します。 fullまたはtableサブコマンドを追加して、バックアップ操作の範囲（クラスタ全体または単一のテーブル）を指定できます。

すべてのクラスタデータをバックアップします

すべてのクラスタデータをバックアップするには、 br backup fullコマンドを実行します。このコマンドのヘルプを表示するには、 br backup full -hまたはbr backup full --helpを実行します。

使用例：

すべてのクラスタデータを各TiKVノードの/tmp/backupのパスにバックアップし、このパスにbackupmetaのファイルを書き込みます。

ノート：

• バックアップディスクとサービスディスクが異なる場合、フルスピードバックアップの場合、オンラインバックアップによって読み取り専用オンラインサービスのQPSが約15％〜25％低下することがテストされています。 QPSへの影響を減らしたい場合は、 --ratelimitを使用してレートを制限します。

• バックアップディスクとサービスディスクが同じである場合、バックアップはI/Oリソースを求めてサービスと競合します。これにより、読み取り専用オンラインサービスのQPSが半分以上低下する可能性があります。したがって、オンラインサービスデータをTiKVデータディスクにバックアップすることは強くお勧めしません。

br backup full \
    --pd "${PDIP}:2379" \
    --storage "local:///tmp/backup" \
    --ratelimit 128 \
    --log-file backupfull.log

上記のコマンドのいくつかのオプションの説明は次のとおりです。

• --ratelimit ：各TiKVノードでバックアップ操作が実行される最大速度（MiB / s）を指定します。
• --log-file ：BRログをbackupfull.logファイルに書き込むことを指定します。

バックアップ中は、端末にプログレスバーが表示されます。プログレスバーが100％に進むと、バックアップが完了します。次に、BRはバックアップデータもチェックして、データの安全性を確保します。プログレスバーは次のように表示されます。

br backup full \
    --pd "${PDIP}:2379" \
    --storage "local:///tmp/backup" \
    --ratelimit 128 \
    --log-file backupfull.log
Full Backup <---------/................................................> 17.12%.

データベースをバックアップする

クラスタのデータベースをバックアップするには、 br backup dbコマンドを実行します。このコマンドのヘルプを表示するには、 br backup db -hまたはbr backup db --helpを実行します。

使用例：

testのデータベースのデータを各TiKVノードの/tmp/backupのパスにバックアップし、 backupmetaのファイルをこのパスに書き込みます。

br backup db \
    --pd "${PDIP}:2379" \
    --db test \
    --storage "local:///tmp/backup" \
    --ratelimit 128 \
    --log-file backupdb.log

上記のコマンドで、 --dbはバックアップするデータベースの名前を指定します。その他のオプションの説明については、 すべてのクラスタデータをバックアップしますを参照してください。

バックアップ中は、端末にプログレスバーが表示されます。プログレスバーが100％に進むと、バックアップが完了します。次に、BRはバックアップデータもチェックして、データの安全性を確保します。

テーブルをバックアップする

クラスタの単一のテーブルのデータをバックアップするには、 br backup tableコマンドを実行します。このコマンドのヘルプを表示するには、 br backup table -hまたはbr backup table --helpを実行します。

使用例：

test.usertableのテーブルのデータを各TiKVノードの/tmp/backupのパスにバックアップし、 backupmetaのファイルをこのパスに書き込みます。

br backup table \
    --pd "${PDIP}:2379" \
    --db test \
    --table usertable \
    --storage "local:///tmp/backup" \
    --ratelimit 128 \
    --log-file backuptable.log

tableサブコマンドには2つのオプションがあります。

• --db ：データベース名を指定します
• --table ：テーブル名を指定します。

その他のオプションの説明については、 すべてのクラスタデータをバックアップしますを参照してください。

バックアップ操作中は、端末にプログレスバーが表示されます。プログレスバーが100％に進むと、バックアップが完了します。次に、BRはバックアップデータもチェックして、データの安全性を確保します。

テーブルフィルターでバックアップする

より複雑な基準で複数のテーブルをバックアップするには、 br backup fullコマンドを実行し、 --filterまたは-fでテーブルフィルターを指定します。

使用例：

次のコマンドは、フォームdb*.tbl*のすべてのテーブルのデータを各TiKVノードの/tmp/backupパスにバックアップし、 backupmetaファイルをこのパスに書き込みます。

br backup full \
    --pd "${PDIP}:2379" \
    --filter 'db*.tbl*' \
    --storage "local:///tmp/backup" \
    --ratelimit 128 \
    --log-file backupfull.log

データをAmazonS3バックエンドにバックアップします

データをlocalのストレージではなくAmazonS3バックエンドにバックアップする場合は、 storageサブコマンドでS3ストレージパスを指定し、BRノードとTiKVノードがAmazonS3にアクセスできるようにする必要があります。

AWS公式ドキュメントを参照して、指定したBucketにS33を作成できRegion 。別のAWS公式ドキュメントを参照して、 BucketにFolderを作成することもできます。

ノート：

1つのバックアップを完了するには、TiKVとBRは通常、 s3:ListBucket 、およびs3:PutObjectの最小特権を必要としs3:AbortMultipartUpload 。

S3バックエンドにアクセスする権限を持つアカウントのSecretKeyとAccessKeyをBRノードに渡します。ここでは、 SecretKeyとAccessKeyが環境変数として渡されます。次に、BRを介して特権をTiKVノードに渡します。

export AWS_ACCESS_KEY_ID=${AccessKey}
export AWS_SECRET_ACCESS_KEY=${SecretKey}

BRを使用してバックアップする場合は、パラメーター--s3.regionと--send-credentials-to-tikvを明示的に指定してください。 --s3.regionはS3が配置されているリージョンを示し、 --send-credentials-to-tikvはS3にアクセスする特権をTiKVノードに渡すことを意味します。

br backup full \
    --pd "${PDIP}:2379" \
    --storage "s3://${Bucket}/${Folder}" \
    --s3.region "${region}" \
    --send-credentials-to-tikv=true \
    --ratelimit 128 \
    --log-file backupfull.log

インクリメンタルデータをバックアップする

増分バックアップする場合は、最後のバックアップタイムスタンプ--lastbackuptsを指定するだけで済みます。

増分バックアップには2つの制限があります。

• 増分バックアップは、前の完全バックアップとは異なるパスの下にある必要があります。
• GC（ガベージコレクション）セーフポイントは、 lastbackuptsの前にある必要があります。

(LAST_BACKUP_TS, current PD timestamp]の間の増分データをバックアップするには、次のコマンドを実行します。

br backup full\
    --pd ${PDIP}:2379 \
    --ratelimit 128 \
    -s local:///home/tidb/backupdata/incr \
    --lastbackupts ${LAST_BACKUP_TS}

最後のバックアップのタイムスタンプを取得するには、 validateコマンドを実行します。例えば：

LAST_BACKUP_TS=`br validate decode --field="end-version" -s local:///home/tidb/backupdata | tail -n1`

上記の例では、増分バックアップデータの場合、BRは(LAST_BACKUP_TS, current PD timestamp]の間のデータ変更とDDL操作を記録します。データを復元する場合、BRは最初にDDL操作を復元し、次にデータを復元します。

バックアップ中にデータを暗号化する（実験的機能）

TiDB v5.3.0以降、TiDBはバックアップ暗号化をサポートしています。バックアップ中にデータを暗号化するには、次のパラメーターを構成できます。

• --crypter.method ：暗号化アルゴリズム。 3つのアルゴリズムをサポートしますaes128-ctr/aes192-ctr/aes256-ctr 。デフォルト値はplaintextで、暗号化されていないことを示します。
• --crypter.key進文字列形式の暗号化キー。 aes128-ctrは128ビット（16バイト）のキー長を意味し、 aes192-ctrは24バイトを意味し、 aes256-ctrは32バイトを意味します。
• --crypter.key-file ：キーファイル。 「crypter.key」を渡さなくても、キーがパラメータとして保存されているファイルパスを直接渡すことができます。

バックアップ暗号化の設定例は次のとおりです。

br backup full\
    --pd ${PDIP}:2379 \
    -s local:///home/tidb/backupdata/incr \
    --crypter.method aes128-ctr \
    --crypter.key 0123456789abcdef0123456789abcdef

Raw KVのバックアップ（実験的機能）

一部のシナリオでは、TiKVはTiDBとは独立して実行される場合があります。そのため、BRはTiDBレイヤーのバイパスとTiKVでのデータのバックアップもサポートしています。

たとえば、次のコマンドを実行して、デフォルトCFの[0x31, 0x3130303030303030)から$BACKUP_DIRまでのすべてのキーをバックアップできます。

br backup raw --pd $PD_ADDR \
    -s "local://$BACKUP_DIR" \
    --start 31 \
    --ratelimit 128 \
    --end 3130303030303030 \
    --format hex \
    --cf default

ここで、 --startと--endのパラメータは、TiKVに送信される前に、 --formatで指定された方法を使用してデコードされます。現在、次の方法を使用できます。

• "raw"：入力文字列はバイナリ形式のキーとして直接エンコードされます。
• 「hex」：デフォルトのエンコード方法。入力文字列は16進数として扱われます。
• 「エスケープ」：最初に入力文字列をエスケープしてから、バイナリ形式にエンコードします。

BRコマンドラインを使用してクラスタデータを復元する

クラスタデータを復元するには、 br restoreコマンドを使用します。 full 、またはdbサブコマンドを追加して、復元の範囲（クラスタ全体、データベース、または単一のテーブル）を指定できtable 。

ノート：

ローカルストレージを使用する場合は、すべてのバックアップSSTファイルを--storageで指定されたパスのすべてのTiKVノードにコピーする必要があります。

各TiKVノードが最終的にすべてのSSTファイルの一部を読み取るだけでよい場合でも、次の理由により、すべてのTiKVノードが完全なアーカイブへのフルアクセスを必要とします。

• データは複数のピアに複製されます。 SSTを取り込む場合、これらのファイルはすべてのピアに存在する必要があります。これは、単一ノードからの読み取りで十分なバックアップとは異なります。
• 復元中に各ピアが分散する場所はランダムです。どのノードがどのファイルを読み取るかは事前にわかりません。

これらは、共有ストレージを使用して回避できます。たとえば、ローカルパスにNFSをマウントしたり、S3を使用したりできます。ネットワークストレージを使用すると、すべてのノードがすべてのSSTファイルを自動的に読み取ることができるため、これらの警告は適用されなくなります。

また、1つのクラスタに対して同時に実行できる復元操作は1つだけであることに注意してください。そうしないと、予期しない動作が発生する可能性があります。詳細については、 FAQを参照してください。

すべてのバックアップデータを復元する

すべてのバックアップデータをクラスタに復元するには、 br restore fullコマンドを実行します。このコマンドのヘルプを表示するには、 br restore full -hまたはbr restore full --helpを実行します。

使用例：

クラスタへの/tmp/backupのパスにあるすべてのバックアップデータを復元します。

br restore full \
    --pd "${PDIP}:2379" \
    --storage "local:///tmp/backup" \
    --ratelimit 128 \
    --log-file restorefull.log

上記のコマンドのいくつかのオプションの説明は次のとおりです。

• --ratelimit ：各TiKVノードで復元操作が実行される最大速度（MiB / s）を指定します。
• --log-file ：BRログをrestorefull.logファイルに書き込むことを指定します。

復元中は、ターミナルにプログレスバーが表示されます。プログレスバーが100％に進むと、復元が完了します。次に、BRはバックアップデータもチェックして、データの安全性を確保します。

br restore full \
    --pd "${PDIP}:2379" \
    --storage "local:///tmp/backup" \
    --ratelimit 128 \
    --log-file restorefull.log
Full Restore <---------/...............................................> 17.12%.

データベースを復元する

データベースをクラスタに復元するには、 br restore dbコマンドを実行します。このコマンドのヘルプを表示するには、 br restore db -hまたはbr restore db --helpを実行します。

使用例：

クラスタへの/tmp/backupのパスでバックアップされたデータベースを復元します。

br restore db \
    --pd "${PDIP}:2379" \
    --db "test" \
    --ratelimit 128 \
    --storage "local:///tmp/backup" \
    --log-file restoredb.log

上記のコマンドで、 --dbは復元するデータベースの名前を指定します。その他のオプションの説明については、 すべてのバックアップデータを復元する ）を参照してください。

ノート：

バックアップデータを復元する場合、 --dbで指定されたデータベースの名前は、backupコマンドで-- dbで指定された名前と同じである必要があります。それ以外の場合、復元は失敗します。これは、バックアップデータのメタファイル（ backupmetaファイル）にデータベース名が記録されているため、同じ名前のデータベースにしかデータを復元できないためです。推奨される方法は、バックアップデータを別のクラスタの同じ名前のデータベースに復元することです。

テーブルを復元する

単一のテーブルをクラスタに復元するには、 br restore tableコマンドを実行します。このコマンドのヘルプを表示するには、 br restore table -hまたはbr restore table --helpを実行します。

使用例：

クラスタへの/tmp/backupのパスでバックアップされたテーブルを復元します。

br restore table \
    --pd "${PDIP}:2379" \
    --db "test" \
    --table "usertable" \
    --ratelimit 128 \
    --storage "local:///tmp/backup" \
    --log-file restoretable.log

上記のコマンドで、 --tableは復元するテーブルの名前を指定します。その他のオプションの説明については、 すべてのバックアップデータを復元するおよびデータベースを復元するを参照してください。

テーブルフィルターで復元

より複雑な基準で複数のテーブルを復元するには、 br restore fullコマンドを実行し、 --filterまたは-fでテーブルフィルターを指定します。

使用例：

次のコマンドは、クラスタへの/tmp/backupのパスでバックアップされたテーブルのサブセットを復元します。

br restore full \
    --pd "${PDIP}:2379" \
    --filter 'db*.tbl*' \
    --storage "local:///tmp/backup" \
    --log-file restorefull.log

AmazonS3バックエンドからデータを復元する

localのストレージではなくAmazonS3バックエンドからデータを復元する場合は、 storageサブコマンドでS3ストレージパスを指定し、BRノードとTiKVノードがAmazonS3にアクセスできるようにする必要があります。

ノート：

1つの復元を完了するには、通常、TiKVとBRにs3:ListBucketとs3:GetObjectの最小特権が必要です。

S3バックエンドにアクセスする権限を持つアカウントのSecretKeyとAccessKeyをBRノードに渡します。ここでは、 SecretKeyとAccessKeyが環境変数として渡されます。次に、BRを介して特権をTiKVノードに渡します。

export AWS_ACCESS_KEY_ID=${AccessKey}
export AWS_SECRET_ACCESS_KEY=${SecretKey}

BRを使用してデータを復元する場合は、パラメータ--s3.regionと--send-credentials-to-tikvを明示的に指定してください。 --s3.regionはS3が配置されているリージョンを示し、 --send-credentials-to-tikvはS3にアクセスする特権をTiKVノードに渡すことを意味します。

--storageパラメーターのBucketとFolderは、S3バケットと、復元するデータが配置されているフォルダーを表します。

br restore full \
    --pd "${PDIP}:2379" \
    --storage "s3://${Bucket}/${Folder}" \
    --s3.region "${region}" \
    --ratelimit 128 \
    --send-credentials-to-tikv=true \
    --log-file restorefull.log

上記のコマンドで、 --tableは復元するテーブルの名前を指定します。その他のオプションの説明については、 データベースを復元するを参照してください。

増分データを復元する

インクリメンタルデータの復元はBRを使用して完全なデータを復元するに似ています。インクリメンタルデータを復元するときは、 last backup tsより前にバックアップされたすべてのデータがターゲットクラスタに復元されていることを確認してください。

mysqlスキーマで作成されたテーブルを復元する（実験的機能）

BRは、デフォルトでmysqlスキーマで作成されたテーブルをバックアップします。

BRを使用してデータを復元する場合、 mysqlスキーマで作成されたテーブルはデフォルトでは復元されません。これらのテーブルを復元する必要がある場合は、 テーブルフィルターを使用して明示的に含めることができます。次の例では、 mysqlスキーマで作成されたmysql.usertableを復元します。このコマンドは、他のデータとともにmysql.usertableを復元します。

br restore full -f '*.*' -f '!mysql.*' -f 'mysql.usertable' -s $external_storage_url --ratelimit 128

上記のコマンドでは、 -f '*.*'はデフォルトのルールをオーバーライドするために使用され、 -f '!mysql.*'は特に明記されていない限りmysqlのテーブルを復元しないようにBRに指示します。 -f 'mysql.usertable'は、復元にmysql.usertableが必要であることを示します。詳細な実装については、 テーブルフィルタードキュメントを参照してください。

mysql.usertableのみを復元する必要がある場合は、次のコマンドを使用します。

br restore full -f 'mysql.usertable' -s $external_storage_url --ratelimit 128

復元中にデータを復号化する（実験的機能）

バックアップデータを暗号化した後、対応する復号化パラメータを渡してデータを復元する必要があります。復号化パラメーターと暗号化パラメーターが一貫していることを確認する必要があります。復号化アルゴリズムまたはキーが正しくない場合、データを復元できません。

以下は、バックアップデータを復号化する例です。

br restore full\
    --pd ${PDIP}:2379 \
    -s local:///home/tidb/backupdata/incr \
    --crypter.method aes128-ctr \
    --crypter.key 0123456789abcdef0123456789abcdef

Raw KVの復元（実験的機能）

RawKVのバックアップと同様に、次のコマンドを実行してRawKVを復元できます。

br restore raw --pd $PD_ADDR \
    -s "local://$BACKUP_DIR" \
    --start 31 \
    --end 3130303030303030 \
    --ratelimit 128 \
    --format hex \
    --cf default

上記の例では、範囲[0x31, 0x3130303030303030)のすべてのバックアップされたキーがTiKVクラスタに復元されます。これらのキーのコーディング方法は、 バックアッププロセス中のキーのコーディング方法と同じです。

オンライン復元（実験的機能）

データの復元中に、書き込みが多すぎると、オンラインクラスタのパフォーマンスに影響します。この影響を可能な限り回避するために、BRはリソースを分離するために配置ルールをサポートします。この場合、SSTのダウンロードとインポートは、指定されたいくつかのノード（または略して「ノードの復元」）でのみ実行されます。オンライン復元を完了するには、次の手順を実行します。

1. PDを構成し、配置ルールを開始します。

   echo "config set enable-placement-rules true" | pd-ctl
   

2. TiKVの「復元ノード」の設定ファイルを編集し、 serverの設定項目に「復元」を指定します。

   [server]
   labels = { exclusive = "restore" }
   

3. 「復元ノード」のTiKVを起動し、BRを使用してバックアップファイルを復元します。オフライン復元と比較すると、 --onlineのフラグを追加するだけで済みます。

   br restore full \
       -s "local://$BACKUP_DIR" \
       --ratelimit 128 \
       --pd $PD_ADDR \
       --online