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 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からの読み取りもサポートしています。 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 employees employeesデータベースをエクスポートします。
• -T employees.WorkOrder employees.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-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 時間を自動的に調整できません。

• データサイズが非常に大きい（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';

Dumplingのオプション一覧