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の詳細な使用方法については、 --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のエクスポートディレクトリを指定します。

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

--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 \
  -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のオプション一覧

オプション	使用法	デフォルト値
`-V`または`--version`	Dumplingバージョンを出力し、直接終了します
`-B`または`--database`	指定したデータベースをエクスポートする
`-T`または`--tables-list`	指定したテーブルをエクスポートする
`-f`または`--filter`	フィルターパターンに一致するテーブルをエクスポートします。フィルター構文については、テーブルフィルターを参照してください。	`[\.\,!/^(mysql\|sys\|INFORMATION_SCHEMA\|PERFORMANCE_SCHEMA\|METRICS_SCHEMA\|INSPECTION_SCHEMA)$/.\*]` (システムスキーマを除くすべてのデータベースまたはテーブルをエクスポートします)
`--case-sensitive`	table-filter で大文字と小文字を区別するかどうか	false (大文字と小文字を区別しない)
`-h`または`--host`	接続されたデータベースホストの IP アドレス	「127.0.0.1」
`-t`または`--threads`	同時バックアップスレッドの数	4
`-r`または`--rows`	指定された行数でテーブルを行に分割します (通常、大きなテーブルを複数のファイルに分割する同時操作に適用されます。アップストリームデータベースが TiDB v3.0 以降のバージョンである場合、0 より大きい`-r`値は、TiDB リージョンが情報は分割に使用され、特定の`-r`値は分割アルゴリズムに影響しません。
`-L`または`--logfile`	ログ出力アドレス。空の場合、コンソールにログが出力されます	""
`--loglevel`	ログレベル {debug,info,warn,error,dpanic, panic,fatal}	"情報"
`--logfmt`	ログ出力形式 {text,json}	"文章"
`-d`または`--no-data`	データをエクスポートしない (スキーマのみがエクスポートされるシナリオに適しています)
`--no-header`	ヘッダーを生成せずにテーブルの CSV ファイルをエクスポートする
`-W`または`--no-views`	ビューをエクスポートしない	真実
`-m`または`--no-schemas`	データのみがエクスポートされたスキーマをエクスポートしないでください
`-s`または`--statement-size`	`INSERT`ステートメントのサイズを制御します。単位はバイトです
`-F`または`--filesize`	分割されたテーブルのファイルサイズ。単位は`128B` 、 `64KiB` 、 `32MiB` 、および`1.5GiB`のように指定する必要があります。
`--filetype`	エクスポートされるファイルの種類 (csv/sql)	"SQL"
`-o`または`--output`	エクスポートされたローカルファイルのパスまたは外部storageURL	"./export-${time}"
`-S`または`--sql`	指定された SQL ステートメントに従ってデータをエクスポートします。このコマンドは、同時エクスポートをサポートしていません。
`--consistency`	フラッシュ: ダンプの前に FTWRL を使用しますスナップショット: TSO の特定のスナップショットの TiDB データをダンプします lock: ダンプするすべてのテーブルで`lock tables read`を実行します none: 一貫性を保証できないロックを追加せずにダンプします。 auto: MySQL には --consistency フラッシュを使用します。 --consistency スナップショットを TiDB に使用する	「オート」
`--snapshot`	スナップショット TSO。 `consistency=snapshot`のときのみ有効
`--where`	`where`条件でテーブルバックアップの範囲を指定します
`-p`または`--password`	接続されたデータベースホストのパスワード
`-P`または`--port`	接続されたデータベースホストのポート	4000
`-u`または`--user`	接続されたデータベースホストのユーザー名	"根"
`--dump-empty-database`	空のデータベースの`CREATE DATABASE`ステートメントをエクスポートします	真実
`--ca`	TLS接続用の認証局ファイルのアドレス
`--cert`	TLS接続用のクライアント証明書ファイルのアドレス
`--key`	TLS接続用のクライアント秘密鍵ファイルのアドレス
`--csv-delimiter`	CSVファイルの文字型変数の区切り文字	'"'
`--csv-separator`	CSV ファイルの各値の区切り記号。デフォルトの「,」を使用することはお勧めしません。「	+	」を使用することをお勧めしますまたは他の珍しい文字の組み合わせ
`--csv-null-value`	CSV ファイルでの null 値の表現	「\N」
`--escape-backslash`	バックスラッシュ ( `\` ) を使用して、エクスポートファイル内の特殊文字をエスケープします	真実
`--output-filename-template`	golang テンプレートの形式で表されるファイル名テンプレート `{{.DB}}` 、 `{{.Table}}` 、および`{{.Index}}`引数をサポート 3 つの引数は、データファイルのデータベース名、テーブル名、およびチャンク ID を表します。	'{{.DB}}.{{.Table}}.{{.Index}}'
`--status-addr`	Dumpling のサービスアドレス (Prometheus がメトリクスをプルし、デバッグを pprof するためのアドレスを含む)	":8281"
`--tidb-mem-quota-query`	Dumplingコマンドの 1 行で SQL ステートメントをエクスポートする際のメモリ制限で、単位はバイトです。 v4.0.10 以降のバージョンでは、このパラメータを設定しない場合、TiDB はデフォルトで`mem-quota-query`構成項目の値をメモリ制限値として使用します。 v4.0.10 より前のバージョンでは、パラメーター値のデフォルトは 32 GB です。	34359738368
`--params`	エクスポートするデータベースの接続のセッション変数を指定します。必要な形式は`"character_set_client=latin1,character_set_connection=latin1"`です
`-c`または`--compress`	Dumplingによってエクスポートされた CSV および SQL データとテーブル構造ファイルを圧縮します。次の圧縮アルゴリズムがサポートされています: `gzip` 、 `snappy` 、および`zstd` 。	""