Dumplingの概要

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

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

ノート：

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

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

Mydumper と比較したDumplingの改善点

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

Dumpling紹介

Dumplingは Go で書かれています。 Github プロジェクトはピンキャップ/餃子です。

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 ツールをダウンロードを参照してください。

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をサポートするストレージのエクスポート ディレクトリを指定します。

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

ノート：

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

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

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

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

./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であることを指定します。

• --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-trigger.sql 、 *-schema-post.sql : その他のエクスポートされたファイル

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

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を使用してデータをバックアップする場合は、S3 ストレージのリージョンを意味する--s3.regionパラメータを明示的に指定します (たとえば、 ap-northeast-1 )。

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

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

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

Dumplingはデフォルトで、システム データベース ( mysql 、 sys 、 INFORMATION_SCHEMA 、 PERFORMANCE_SCHEMA 、 METRICS_SCHEMA 、およびINSPECTION_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オプションは、1 つのファイルの最大レコード数 (またはデータベース内の行数) を指定します。 Dumplingを有効にすると、テーブルの同時実行性が有効になり、大きなテーブルのエクスポート速度が向上します。アップストリーム データベースが TiDB v3.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 のデータ スキャンのメモリ オーバーヘッドが削減され、同時テーブル データ ダンプが可能になり、エクスポートの効率が向上します。アップストリーム データベースが TiDB v3.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 でのスキャン操作の同時実行性を制御するセッション変数です。

大容量データ（1TB以上）エクスポート時のTiDB GC設定

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 にインポートして戻すことができます。

Dumplingのオプション一覧