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 に固有の拡張機能を備えたマイダンパープロジェクトのフォークを維持していました。 Mydumper の詳細については、 v4.0 Mydumper ドキュメントを参照してください。 v7.5.0 以降、 マイダンパーは非推奨となり、その機能のほとんどがDumplingに置き換えられました。 Mydumper の代わりにDumpling を使用することを強くお勧めします。
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 からデータをエクスポートする
必要な権限
- PROCESS: クラスター情報をクエリして PD アドレスを取得し、PD 経由で GC を制御するために必要です。
- SELECT: テーブルをエクスポートする場合に必要です。
- RELOAD:
consistency flushを使用する場合は必須です。 TiDB のみがこの権限をサポートしていることに注意してください。アップストリームが RDS データベースまたはマネージド サービスである場合、この権限は無視できます。 - LOCK TABLES:
consistency lockを使用する場合は必須です。この権限は、エクスポートするすべてのデータベースとテーブルに付与する必要があります。 - レプリケーション クライアント: メタデータをエクスポートしてデータ スナップショットを記録する場合に必要です。この権限はオプションであり、メタデータをエクスポートする必要がない場合は無視できます。
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) オプションは、絶対ローカル ファイル パスまたは外部storageURIをサポートするstorageのエクスポート ディレクトリを指定します。-tオプションは、エクスポートのスレッド数を指定します。スレッドの数を増やすと、 Dumplingの同時実行性とエクスポート速度が向上し、データベースのメモリ消費量も増加します。したがって、あまり大きな数値を設定することはお勧めできません。通常は 64 未満です。-rオプションを使用すると、テーブル内の同時実行が有効になり、エクスポートが高速化されます。デフォルト値は0で、これは無効を意味します。 0 より大きい値は有効であることを意味し、値はINTタイプです。ソース データベースが TiDB の場合、0 より大きい-r値は、TiDB リージョン情報が分割に使用され、メモリ使用量が削減されることを示します。特定の-r値は分割アルゴリズムには影響しません。ソース データベースが MySQL で、主キーがINTタイプの場合、-r指定するとテーブル内の同時実行性も有効になります。-Fオプションは、単一ファイルの最大サイズを指定するために使用されます (ここでの単位はMiBです5GiBや8KBなどの入力も受け入れられます)。 TiDB Lightningを使用してこのファイルを TiDB インスタンスにロードする予定がある場合は、その値を 256 MiB 以下に保つことをお勧めします。
注記:
エクスポートされる 1 つのテーブルのサイズが 10 GB を超える場合は、
-rおよび-Fオプションを使用することを強くお勧めします。
storageサービスの URI 形式
このセクションでは、Amazon S3、GCS、Azure Blob Storage などのstorageサービスの URI 形式について説明します。 URI の形式は次のとおりです。
[scheme]://[host]/[path]?[parameters]
詳細については、 外部ストレージ サービスの URI 形式を参照してください。
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に変換されます。
エクスポートしたデータファイルを圧縮する
--compress <format>オプションを使用すると、 Dumplingによってエクスポートされた CSV、SQL データ、およびテーブル構造ファイルを圧縮できます。このパラメーターは、圧縮アルゴリズムgzip 、 snappy 、およびzstdをサポートします。圧縮はデフォルトでは無効になっています。
- このオプションは、個々のデータとテーブル構造ファイルのみを圧縮します。フォルダー全体を圧縮して単一の圧縮パッケージを生成することはできません。
- このオプションを使用するとディスク領域を節約できますが、エクスポート速度が遅くなり、CPU 消費量も増加します。エクスポート速度が重要なシナリオでは、このオプションを慎重に使用してください。
- TiDB Lightning v6.5.0 以降のバージョンでは、追加の構成を行わずに、 Dumplingによってエクスポートされた圧縮ファイルをデータ ソースとして使用できます。
注記:
Snappy 圧縮ファイルは公式の Snappy フォーマットに存在する必要があります。 Snappy 圧縮の他のバリアントはサポートされていません。
エクスポートされるファイルの形式
metadata: エクスポートされたファイルの開始時刻とマスター バイナリ ログの位置。cat metadataStarted 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.sqlCREATE DATABASE `test` /*!40100 DEFAULT CHARACTER SET utf8mb4 */;{schema}.{table}-schema.sql: テーブルの作成に使用される SQL ファイルcat test.t1-schema.sqlCREATE 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からの読み取りもサポートしています。 URI パラメータの説明の詳細については、 外部ストレージ サービスの URI 形式を参照してください。
./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 employeesemployeesデータベースをエクスポートします。-T employees.WorkOrderemployees.WorkOrderテーブルをエクスポートします。
同時実行によるエクスポート効率の向上
エクスポートされたファイルは、デフォルトでは./export-<current local time>ディレクトリに保存されます。一般的に使用されるオプションは次のとおりです。
-tオプションは、エクスポートのスレッド数を指定します。スレッドの数を増やすと、 Dumplingの同時実行性とエクスポート速度が向上し、データベースのメモリ消費量も増加します。したがって、あまり大きな数値を設定することはお勧めできません。-rオプションを使用すると、テーブル内の同時実行が有効になり、エクスポートが高速化されます。デフォルト値は0で、これは無効を意味します。 0 より大きい値は有効であることを意味し、値はINTタイプです。ソース データベースが TiDB の場合、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: レプリカ データベースの 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 より大きい-r値は、TiDB 領域情報が分割に使用され、特定の-r値が分割アルゴリズムに影響を与えないことを示します。 --tidb-mem-quota-queryの値を8589934592(8 GB) 以下に減らしてください。--tidb-mem-quota-queryTiDB 内の単一のクエリ ステートメントのメモリ使用量を制御します。--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 時間を自動的に調整できません。
- データサイズが非常に大きい(1TB以上)。
- たとえば、TiDB クラスターがTiDB Cloud上にある場合、またはDumplingから分離された Kubernetes 上にある場合、 Dumpling はPD に直接接続できません。
このようなシナリオでは、エクスポート プロセス中の GC によるエクスポートの失敗を避けるために、事前に GC 時間を手動で延長する必要があります。
GC 時間を手動で調整するには、次の SQL ステートメントを使用します。
SET GLOBAL tidb_gc_life_time = '720h';
Dumplingが終了した後は、エクスポートが成功したかどうかに関係なく、GC 時間を元の値 (デフォルト値は10m ) に設定し直す必要があります。
SET GLOBAL tidb_gc_life_time = '10m';