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を使用する場合は、実行中のクラスターでエクスポートコマンドを実行する必要があります。

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

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

ノート：
PingCAP は以前、TiDB に固有の拡張機能を備えたマイダンパープロジェクトのフォークを維持していました。その後、このフォークは Go で書き直された Dumplingに置き換えられ、TiDB に固有のさらなる最適化をサポートしています。 mydumper の代わりにDumpling を使用することを強くお勧めします。
Mydumper の詳細については、 v4.0 Mydumper ドキュメントを参照してください。

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

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

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

必要な権限

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

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オプションは、ローカルファイルパスまたは外部storageのURLをサポートするstorageのエクスポートディレクトリを指定します。
-tオプションは、エクスポートのスレッド数を指定します。スレッドの数を増やすと、 Dumplingの同時実行性とエクスポート速度が向上し、データベースのメモリ消費量も増加します。したがって、あまり大きな数値を設定することはお勧めできません。通常は 64 未満です。
-rオプションは、単一ファイル内の最大行数を指定します。このオプションを指定すると、 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 ステートメントでレコードをフィルターできます。たとえば、次のコマンドを使用して、 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であることを指定します。
--csv-separatorや--csv-delimiterのようなオプションを使用して、CSV ファイル形式を構成できます。詳細は Dumplingオプション一覧を参照してください。

ノート：
Dumplingでは文字列とキーワードは区別されません。インポートされたデータが Boolean 型の場合、値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 クラウド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を使用してデータをバックアップする場合は、S3storageの領域 (たとえば、 ap-northeast-1 ) を意味する--s3.regionパラメータを明示的に指定します。

./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オプションを使用すると、ダンプを圧縮できます。これは、storageがボトルネックになっている場合、またはstorage容量が懸念される場合に、データのダンプを高速化するのに役立ちます。この欠点は、CPU 使用率が増加することです。各ファイルは個別に圧縮されます。

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

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

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

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

flush : レプリカデータベースの DML および DDL 操作を一時的に中断し、バックアップ接続のグローバルな一貫性を確保し、binlog位置 (POS) 情報を記録するには、 FLUSH TABLES WITH READ LOCKを使用します。すべてのバックアップ接続がトランザクションを開始すると、ロックが解放されます。完全バックアップはオフピーク時間帯に実行するか、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オプションは、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 でのスキャン操作の同時実行性を制御するセッション変数です。

大量のデータ (1 TB を超える) をエクスポートする場合は 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';

Dumplingのオプション一覧

オプション	使用法	デフォルト値
`-V`または`--version`	Dumplingバージョンを出力して直接終了します
`-B`または`--database`	指定したデータベースをエクスポートする
`-T`または`--tables-list`	指定したテーブルをエクスポートする
`-f`または`--filter`	フィルターパターンに一致するテーブルをエクスポートします。フィルターの構文については、テーブルフィルターを参照してください。	`[\.\,!/^(mysql\|sys\|INFORMATION_SCHEMA\|PERFORMANCE_SCHEMA\|METRICS_SCHEMA\|INSPECTION_SCHEMA)$/.\*]` (システムスキーマを除くすべてのデータベースまたはテーブルをエクスポート)
`--case-sensitive`	テーブルフィルターで大文字と小文字が区別されるかどうか	false (大文字と小文字を区別しない)
`-h`または`--host`	接続されているデータベースホストのIPアドレス	「127.0.0.1」
`-t`または`--threads`	同時バックアップスレッドの数	4
`-r`または`--rows`	テーブルを指定した行数の行に分割します (通常、大きなテーブルを複数のファイルに分割する同時操作に適用されます。アップストリームデータベースが TiDB v3.0 以降のバージョンの場合、このパラメータの値が 0 より大きい場合、 TiDB リージョン情報は分割に使用されるため、ここで指定した値は有効になりません。
`-L`または`--logfile`	ログ出力アドレス。空の場合、ログがコンソールに出力されます。	「」
`--loglevel`	ログレベル {デバッグ、情報、警告、エラー、パニック、panic、致命的}	"情報"
`--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`	エクスポートされたローカルファイルのパス、または外部storageのURL	「./export-${time}」
`-S`または`--sql`	指定されたSQL文に従ってデータをエクスポートします。このコマンドは同時エクスポートをサポートしていません。
`--consistency`	フラッシュ: ダンプの前に FTWRL を使用します。スナップショット: TSO の特定のスナップショットの TiDB データをダンプします。 lock: ダンプされるすべてのテーブルに対して`lock tables read`を実行します。 none: ロックを追加せずにダンプします。一貫性は保証できません。 auto: MySQL の場合は --consistency flash を使用します。 TiDB の --consistency スナップショットを使用する	「自動」
`--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"`です