Dumplingの概要

このドキュメントでは、データエクスポートツールDumplingを紹介します。Dumplingは、TiDB / MySQLに保存されているデータをSQLまたはCSVデータファイルとしてエクスポートし、論理的な完全バックアップまたはエクスポートを行うために使用できます。

SSTファイル（キーと値のペア）のバックアップ、またはレイテンシーの影響を受けない増分データのバックアップについては、 BRを参照してください。インクリメンタルデータのリアルタイムバックアップについては、 TiCDCを参照してください。

ノート：

PingCAPは以前、TiDBに固有の拡張機能を備えたmydumperプロジェクトのフォークを維持していました。その後、このフォークはDumplingに置き換えられました。これは、Goで書き直され、TiDBに固有のより多くの最適化をサポートします。 mydumperの代わりにDumplingを使用することを強くお勧めします。

Mydumperの概要については、 v4.0Mydumperのドキュメントを参照してください。

Mydumperと比較したDumplingの改善

1. SQLやCSVを含む複数の形式でのデータのエクスポートをサポート
2. データのフィルタリングを容易にするテーブルフィルターつの機能をサポートします
3. AmazonS3クラウドストレージへのデータのエクスポートをサポートします。
4. TiDBに対してさらに最適化が行われます。
   • 単一のTiDB SQLステートメントのメモリ制限の構成をサポート
   • TiDBv4.0.0以降のTiDBGC時間の自動調整をサポート
   • TiDBの非表示列_tidb_rowidを使用して、単一のテーブルからの同時データエクスポートのパフォーマンスを最適化します
   • TiDBの場合、値tidb_snapshotを設定して、データバックアップの時点を指定できます。これにより、一貫性を確保するためにFLUSH TABLES WITH READ LOCKを使用する代わりに、バックアップの一貫性が保証されます。

Dumpling紹介

Dumplingは囲碁で書かれています。 Githubプロジェクトはpingcap/餃子です。

Dumplingの詳細な使用法については、 --helpオプションを使用するか、 Dumplingのオプションリストを参照してください。

Dumplingを使用する場合は、実行中のクラスタでexportコマンドを実行する必要があります。このドキュメントでは、 127.0.0.1:4000のホストにTiDBインスタンスがあり、このTiDBインスタンスにパスワードのないrootユーザーがいることを前提としています。

tiup install dumplingを実行すると、 TiUPを使用してDumplingを取得できます。その後、 tiup dumpling ...を使用してDumplingを実行できます。

DumplingインストールパッケージはTiDB Toolkitに含まれています。 TiDB Toolkitをダウンロードするには、 TiDBツールをダウンロードするを参照してください。

次のコマンドを使用して、 Dumplingをインストールできます。

curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
source ~/.bash_profile
tiup install dumpling

上記のコマンドでは、プロファイルファイルのパスに~/.bash_profileを変更する必要があります。

TiDB/MySQLからデータをエクスポートする

必要な特権

• 選択する
• リロード
• ロックテーブル
• レプリケーションクライアント
• 処理する

SQLファイルにエクスポート

Dumplingは、デフォルトでデータをSQLファイルにエクスポートします。 --filetype sqlフラグを追加して、データをSQLファイルにエクスポートすることもできます。

dumpling \
  -u root \
  -P 4000 \
  -h 127.0.0.1 \
  --filetype sql \
  -t 8 \
  -o /tmp/test \
  -r 200000 \
  -F 256MiB

上記のコマンドでは：

• -h 、および-pオプションは、それぞれアドレス、ポート、およびユーザーを意味し-u 。認証にパスワードが必要な場合は、 -p $YOUR_SECRET_PASSWORDを使用してパスワードをDumplingに渡すことができます。

• -oオプションは、ローカルファイルパスまたは外部ストレージのURLをサポートするストレージのエクスポートディレクトリを指定します。

• -oオプションは、ローカルファイルパスまたは外部ストレージのURLをサポートするストレージのエクスポートディレクトリを指定します。

• -tオプションは、エクスポートするスレッドの数を指定します。スレッドの数を増やすと、Dumplingの同時実行性とエクスポート速度が向上し、データベースのメモリ消費量も増加します。したがって、数値を大きく設定しすぎることはお勧めしません。通常、64未満です。
• -rオプションは、1つのファイルの最大行数を指定します。このオプションを指定すると、 Dumplingにより、テーブル内の同時実行がエクスポートを高速化し、メモリ使用量を削減できます。アップストリームデータベースがTiDBv3.0以降のバージョンの場合、このパラメーターの値が0より大きい場合は、TiDB領域情報が分割に使用され、ここで指定された値は無効になることを示します。
• -Fオプションは、単一ファイルの最大サイズを指定するために使用されます（ここでの単位はMiBです5GiBや8KBなどの入力も受け入れられます）。 TiDB Lightningを使用してこのファイルをTiDBインスタンスにロードする場合は、その値を256MiB以下に保つことをお勧めします。

ノート：

エクスポートされた単一のテーブルのサイズが10GBを超える場合は、 -rおよび-Fオプションを使用することを強くお勧めします。

CSVファイルにエクスポート

--filetype csv引数を追加すると、データをCSVファイルにエクスポートできます。

データをCSVファイルにエクスポートする場合、 --sql <SQL>を使用してSQLステートメントでレコードをフィルタリングできます。たとえば、次のコマンドを使用して、 test.sbtest1分のid < 100に一致するすべてのレコードをエクスポートできます。

./dumpling \
  -u root \
  -P 4000 \
  -h 127.0.0.1 \
  -o /tmp/test \
  --filetype csv \
  --sql 'select * from `test`.`sbtest1` where id < 100' \
  -F 100MiB \
  --output-filename-template 'test.sbtest1.{{.Index}}'

上記のコマンドでは：

• --sqlオプションは、CSVファイルへのエクスポートにのみ使用できます。上記のコマンドは、エクスポートされるすべてのテーブルでSELECT * FROM <table-name> WHERE id <100ステートメントを実行します。テーブルに指定されたフィールドがない場合、エクスポートは失敗します。

• --sqlオプションを使用すると、 Dumplingはエクスポートされたテーブルおよびスキーマ情報を取得できません。 --output-filename-templateオプションを使用してCSVファイルのファイル名形式を指定できます。これにより、後でTiDB Lightningを使用してデータファイルをインポートしやすくなります。たとえば、 --output-filename-template='test.sbtest1.{{.Index}}'は、エクスポートされたCSVファイルの名前がtest.sbtest1.000000000またはtest.sbtest1.000000001であることを指定します。

• --sqlオプションを使用すると、 Dumplingはエクスポートされたテーブルおよびスキーマ情報を取得できません。 --output-filename-templateオプションを使用して、CSVファイルのファイル名形式を指定できます。たとえば、 --output-filename-template='test.sbtest1.{{.Index}}'は、エクスポートされたCSVファイルの名前がtest.sbtest1.000000000またはtest.sbtest1.000000001であることを指定します。

• --csv-separatorや--csv-delimiterなどのオプションを使用して、CSVファイル形式を構成できます。詳しくはDumplingオプションリストをご覧ください。

ノート：

文字列とキーワードはDumplingによって区別されません。インポートされたデータがブール型の場合、 trueの値は1に変換され、 falseの値は0に変換されます。

エクスポートされたファイルの形式

• metadata ：エクスポートされたファイルの開始時刻とマスターバイナリログの位置。

  cat metadata
  

  Started dump at: 2020-11-10 10:40:19
  SHOW MASTER STATUS:
          Log: tidb-binlog
          Pos: 420747102018863124
  Finished dump at: 2020-11-10 10:40:20
  

• {schema}-schema-create.sql ：スキーマの作成に使用されるSQLファイル

  cat test-schema-create.sql
  

  CREATE DATABASE `test` /*!40100 DEFAULT CHARACTER SET utf8mb4 */;
  

• {schema}.{table}-schema.sql ：テーブルの作成に使用されるSQLファイル

  cat test.t1-schema.sql
  

  CREATE TABLE `t1` (
    `id` int(11) DEFAULT NULL
  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
  

• {schema}.{table}.{0001}.{sql|csv }：日付ソースファイル

  cat test.t1.0.sql
  

  /*!40101 SET NAMES binary*/;
  INSERT INTO `t1` VALUES
  (1);
  

• *-schema-view.sql ： *-schema-post.sqlの*-schema-trigger.sqlされたファイル

AmazonS3クラウドストレージにデータをエクスポートする

v4.0.8以降、 Dumplingはクラウドストレージへのデータのエクスポートをサポートしています。 AmazonのS3バックエンドストレージにデータをバックアップする必要がある場合は、 -oパラメーターでS3ストレージパスを指定する必要があります。

指定したリージョンにS3バケットを作成する必要があります（ Amazonドキュメント-S3バケットを作成するにはどうすればよいですかを参照）。バケット内にフォルダーも作成する必要がある場合は、 Amazonドキュメント-フォルダーの作成を参照してください。

S3バックエンドストレージにアクセスする権限を持つアカウントのSecretKeyとAccessKeyを、環境変数としてDumplingノードに渡します。

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

Dumplingは、 ~/.aws/credentialsからのクレデンシャルファイルの読み取りもサポートします。Dumplingの構成の詳細については、 外部ストレージの構成を参照してください。

Dumplingは、 ~/.aws/credentialsからのクレデンシャルファイルの読み取りもサポートします。Dumplingの構成の詳細については、 外部ストレージの構成を参照してください。

Dumplingを使用してデータをバックアップする場合は、 --s3.regionパラメーターを明示的に指定します。これは、S3ストレージの領域（たとえば、 ap-northeast-1 ）を意味します。

./dumpling \
  -u root \
  -P 4000 \
  -h 127.0.0.1 \
  -r 200000 \
  -o "s3://${Bucket}/${Folder}" \
  --s3.region "${region}"

エクスポートされたデータをフィルタリングする

--whereオプションを使用して、データをフィルタリングします

デフォルトでは、 DumplingはシステムPERFORMANCE_SCHEMA （ mysql 、 METRICS_SCHEMA sysをINSPECTION_SCHEMA ）を除くすべてのデータベースをエクスポートしINFORMATION_SCHEMA 。 --where <SQL where expression>を使用して、エクスポートするレコードを選択できます。

./dumpling \
  -u root \
  -P 4000 \
  -h 127.0.0.1 \
  -o /tmp/test \
  --where "id < 100"

上記のコマンドは、各テーブルからid < 100に一致するデータをエクスポートします。 --whereパラメータを--sqlと一緒に使用することはできないことに注意してください。

--filterオプションを使用して、データをフィルタリングします

Dumplingは、 --filterオプションでテーブルフィルターを指定することにより、特定のデータベースまたはテーブルをフィルター処理できます。テーブルフィルターの構文は.gitignoreの構文と似ています。詳細については、 テーブルフィルターを参照してください。

./dumpling \
  -u root \
  -P 4000 \
  -h 127.0.0.1 \
  -o /tmp/test \
  -r 200000 \
  --filter "employees.*" \
  --filter "*.WorkOrder"

上記のコマンドは、 employeesのデータベースのすべてのテーブルとすべてのデータベースのWorkOrderのテーブルをエクスポートします。

-Bまたは-Tオプションを使用して、データをフィルタリングします

Dumplingは、 -Bオプションの特定のデータベースまたは-Tオプションの特定のテーブルをエクスポートすることもできます。

ノート：

• --filterオプションと-Tオプションを同時に使用することはできません。
• -Tオプションは、 database-name.table-nameのような完全な形式の入力のみを受け入れることができ、テーブル名のみを含む入力は受け入れられません。例：Dumplingは-T WorkOrderを認識できません。

例:

• -B employeesはemployeesのデータベースをエクスポートします。
• -T employees.WorkOrderはemployees.WorkOrderテーブルをエクスポートします。

同時実行によるエクスポート効率の向上

エクスポートされたファイルは、デフォルトで./export-<current local time>ディレクトリに保存されます。一般的に使用されるオプションは次のとおりです。

• -tオプションは、エクスポートするスレッドの数を指定します。スレッドの数を増やすと、Dumplingの同時実行性とエクスポート速度が向上し、データベースのメモリ消費量も増加します。したがって、数値を大きく設定しすぎることはお勧めしません。
• -rオプションは、単一ファイルのレコードの最大数（またはデータベース内の行数）を指定します。有効にすると、Dumplingによってテーブルの同時実行が有効になり、大きなテーブルのエクスポート速度が向上します。アップストリームデータベースがTiDBv3.0以降のバージョンの場合、このパラメーターの値が0より大きい場合は、TiDB領域情報が分割に使用され、ここで指定された値は無効になることを示します。
• --compress gzipオプションは、ダンプを圧縮するために使用できます。これは、ストレージがボトルネックである場合、またはストレージ容量が懸念される場合に、データのダンプを高速化するのに役立ちます。これの欠点は、CPU使用率の増加です。各ファイルは個別に圧縮されます。

上記のオプションを指定すると、Dumplingのデータエクスポート速度を上げることができます。

Dumplingのデータ整合性オプションを調整する

ノート：

ほとんどのシナリオでは、 Dumplingのデフォルトのデータ整合性オプションを調整する必要はありません（デフォルト値はautoです）。

Dumplingは--consistency <consistency level>オプションを使用して、「整合性保証」のためにデータをエクスポートする方法を制御します。一貫性を保つためにスナップショットを使用する場合は、 --snapshotオプションを使用して、バックアップするタイムスタンプを指定できます。次のレベルの整合性を使用することもできます。

• flush ： FLUSH TABLES WITH READ LOCKを使用して、レプリカデータベースのDMLおよびDDL操作を一時的に中断し、バックアップ接続のグローバル整合性を確保し、binlog位置（POS）情報を記録します。すべてのバックアップ接続がトランザクションを開始すると、ロックが解除されます。オフピーク時またはMySQLレプリカデータベースで完全バックアップを実行することをお勧めします。
• snapshot ：指定されたタイムスタンプの一貫したスナップショットを取得してエクスポートします。
• lock ：エクスポートするすべてのテーブルに読み取りロックを追加します。
• none ：一貫性の保証はありません。
• auto ：MySQLにはflushを使用し、TiDBにはsnapshotを使用します。

すべてが完了すると、エクスポートされたファイルを/tmp/testで確認できます。

ls -lh /tmp/test | awk '{print $5 "\t" $9}'

140B  metadata
66B   test-schema-create.sql
300B  test.sbtest1-schema.sql
190K  test.sbtest1.0.sql
300B  test.sbtest2-schema.sql
190K  test.sbtest2.0.sql
300B  test.sbtest3-schema.sql
190K  test.sbtest3.0.sql

TiDBの履歴データスナップショットをエクスポートする

Dumplingは、 --snapshotオプションを指定して特定のtidb_snapshotのデータをエクスポートできます。

--snapshotオプションは、TSO（ SHOW MASTER STATUSコマンドによって出力されるPositionフィールド）またはdatetimeデータ型の有効時間（ YYYY-MM-DD hh:mm:ssの形式）に設定できます。次に例を示します。

./dumpling --snapshot 417773951312461825
./dumpling --snapshot "2020-07-02 17:12:45"

TSOが417773951312461825で時刻が2020-07-02 17:12:45の場合のTiDB履歴データスナップショットがエクスポートされます。

大きなテーブルをエクスポートする際のメモリ使用量を制御する

DumplingがTiDBから大きな単一のテーブルをエクスポートしている場合、エクスポートされたデータサイズが大きすぎるためにメモリ不足（OOM）が発生し、接続の中止とエクスポートの失敗が発生する可能性があります。次のパラメータを使用して、TiDBのメモリ使用量を減らすことができます。

• エクスポートするデータをチャンクに分割するには、 -rを設定します。これにより、TiDBのデータスキャンのメモリオーバーヘッドが削減され、同時テーブルデータダンプが可能になり、エクスポートの効率が向上します。アップストリームデータベースがTiDBv3.0以降のバージョンの場合、このパラメーターの値が0より大きい場合は、TiDB領域情報が分割に使用され、ここで指定された値は無効になることを示します。
• --tidb-mem-quota-queryから8589934592 （8 GB）以下の値を減らします。 --tidb-mem-quota-queryは、TiDB内の単一のクエリステートメントのメモリ使用量を制御します。
• --params "tidb_distsql_scan_concurrency=5"パラメータを調整します。 tidb_distsql_scan_concurrencyは、TiDBでのスキャン操作の同時実行性を制御するセッション変数です。

大量のデータ（1 TBを超える）をエクスポートする場合のTiDBGC設定

TiDB（1 TBを超える）からデータをエクスポートするときに、TiDBのバージョンがv4.0.0以降で、 DumplingがTiDBクラスタのPDアドレスにアクセスできる場合、 Dumplingは元のクラスタに影響を与えることなくGC時間を自動的に延長します。

他のシナリオでは、データサイズが非常に大きい場合、エクスポートプロセス中のGCによるエクスポートの失敗を回避するために、事前にGC時間を延長できます。

SET GLOBAL tidb_gc_life_time = '720h';

操作が完了したら、GC時間を元に戻します（デフォルト値は10mです）。

SET GLOBAL tidb_gc_life_time = '10m';

最後に、エクスポートされたすべてのデータは、 TiDB Lightningを使用してTiDBにインポートして戻すことができます。

最後に、エクスポートされたすべてのデータをTiDBにインポートして戻すことができます。

Dumplingのオプションリスト