Dumpling を使用してデータをエクスポートする

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

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プロファイル ファイルのパスに変更する必要があります。

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

Dumplingを使用する場合は、実行中のクラスターで export コマンドを実行する必要があります。

TiDB は、必要に応じて選択して使用できる他のツールも提供します。

• レイテンシーの影響を受けない SST ファイル (キーと値のペア) のバックアップまたは増分データのバックアップについては、 BRを参照してください。
• 増分データのリアルタイム バックアップについては、 TiCDCを参照してください。
• エクスポートされたすべてのデータは、 TiDB Lightning使用して TiDB にインポートして戻すことができます。

ノート：

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

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

Mydumper と比較して、 Dumpling には次の改善点があります。

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

ノート：

Dumpling は、次のシナリオでは PD に接続できません。

• TiDB クラスターは Kubernetes 上で実行されています ( Dumpling自体が Kubernetes 環境内で実行されている場合を除く)。
• TiDB クラスターはTiDB Cloudで実行されています。

このような場合、エクスポートの失敗を避けるために手動でTiDB GC 時間を調整するする必要があります。

TiDB または MySQL からデータをエクスポートする

必要な権限

• SELECT: テーブルをエクスポートするときに必要です。
• RELOAD: consistency flushを使用する場合に必要です。この権限をサポートしているのは TiDB のみであることに注意してください。アップストリームが RDS データベースまたはマネージド サービスの場合、この権限は無視できます。
• LOCK TABLES: consistency lockを使用する場合に必要です。この権限は、エクスポートするすべてのデータベースとテーブルに対して付与する必要があります。
• REPLICATION CLIENT: メタデータをエクスポートしてデータのスナップショットを記録する場合に必要です。この権限はオプションであり、メタデータをエクスポートする必要がない場合は無視できます。

SQL ファイルへのエクスポート

このドキュメントでは、127.0.0.1:4000 ホストに TiDB インスタンスがあり、この TiDB インスタンスにはパスワードのない root ユーザーがいると想定しています。

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 (または--output ) オプションは、ローカル ファイル パスまたは外部storageURLをサポートするstorageのエクスポート ディレクトリを指定します。

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

• -tオプションは、エクスポートのスレッド数を指定します。スレッドの数を増やすと、Dumplingの同時実行性とエクスポート速度が向上しますが、データベースのメモリ消費も増加します。そのため、あまり大きな数値を設定することはお勧めしません。通常は 64 未満です。
• -rオプションは、1 つのファイル内の最大行数を指定します。このオプションを指定すると、 Dumpling はテーブル内の同時実行性を有効にして、エクスポートを高速化し、メモリ使用量を削減します。アップストリーム データベースが TiDB v3.0 以降のバージョンの場合、0 より大きい-r値は、TiDB リージョン情報が分割に使用され、特定の-r値が分割アルゴリズムに影響しないことを示します。アップストリーム データベースが MySQL で主キーがint型の場合、 -r指定するとテーブル内同時実行も有効になります。
• -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であることを指定します。

• --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に変換されます。

エクスポートされたデータ ファイルを圧縮する

--compress <format>オプションを使用して、 Dumplingによってエクスポートされた CSV および SQL データとテーブル構造ファイルを圧縮できます。このパラメーターは、次の圧縮アルゴリズムをサポートしています: gzip 、 snappy 、およびzstd 。圧縮はデフォルトで無効になっています。

• このオプションは、個々のデータおよびテーブル構造ファイルのみを圧縮します。フォルダー全体を圧縮して、単一の圧縮パッケージを生成することはできません。
• このオプションはディスク容量を節約できますが、エクスポート速度が遅くなり、CPU 消費が増加します。エクスポート速度が重要なシナリオでは、このオプションを慎重に使用してください。
• TiDB Lightning v6.5.0 以降のバージョンでは、追加の構成なしでDumplingによってエクスポートされた圧縮ファイルをデータ ソースとして使用できます。

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

• 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 クラウドstorageにエクスポートする

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

指定されたリージョンに Amazon S3 バケットを作成する必要があります ( Amazon ドキュメント - S3 バケットを作成する方法を参照)。バケットにフォルダーも作成する必要がある場合は、 Amazon ドキュメント - フォルダーの作成を参照してください。

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

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

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

Dumpling は、 ~/.aws/credentialsからの資格情報ファイルの読み取りもサポートしています。 Dumplingを使用して Amazon S3 にデータをエクスポートするためのパラメーターは、 BRで使用されるパラメーターと同じです。パラメーターの詳細については、 外部storageURLを参照してください。

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

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

--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 より大きい-r値は、TiDB リージョン情報が分割に使用され、特定の-r値が分割アルゴリズムに影響しないことを示します。アップストリーム データベースが MySQL で主キーがint型の場合、 -r指定するとテーブル内同時実行も有効になります。
• --compress <format>オプションは、ダンプの圧縮形式を指定します。次の圧縮アルゴリズムをサポートしています: gzip 、 snappy 、およびzstd 。storageがボトルネックである場合、またはstorage容量が懸念される場合、このオプションはデータのダンプを高速化できます。欠点は、CPU 使用率の増加です。各ファイルは個別に圧縮されます。

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

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

ノート：

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

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 より大きい-r値は、TiDB リージョン情報が分割に使用され、特定の-r値が分割アルゴリズムに影響しないことを示します。
• --tidb-mem-quota-queryの値を8589934592 (8 GB) 以下に減らします。 --tidb-mem-quota-query TiDB での単一のクエリ ステートメントのメモリ使用量を制御します。
• --params "tidb_distsql_scan_concurrency=5"パラメータを調整します。 tidb_distsql_scan_concurrencyは、TiDB でのスキャン操作の同時実行性を制御するセッション変数です。

TiDB GC 時間を手動で設定する

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

ただし、次のいずれかのシナリオでは、 Dumpling はGC 時間を自動的に調整できません。

• データ サイズが非常に大きい (1 TB を超える)。
• Dumpling は、たとえば、TiDB クラスターがTiDB Cloud上にある場合、またはDumplingから分離された Kubernetes 上にある場合、PD に直接接続することはできません。

このようなシナリオでは、事前に GC 時間を手動で延長して、エクスポート プロセス中の GC によるエクスポートの失敗を回避する必要があります。

GC 時間を手動で調整するには、次の SQL ステートメントを使用します。

SET GLOBAL tidb_gc_life_time = '720h';

Dumplingの終了後、エクスポートが成功したかどうかに関係なく、GC 時間を元の値に戻す必要があります (デフォルト値は10mです)。

SET GLOBAL tidb_gc_life_time = '10m';

Dumplingのオプション一覧