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

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

TiUP使用してtiup install dumplingを実行するとDumpling を取得できます。その後、 tiup dumpling ...を使用してDumplingを実行できます。

Dumplingインストール パッケージはTiDB Toolkitに含まれています。TiDB 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 を使用する場合は、実行中のクラスターでエクスポート コマンドを実行する必要があります。

TiDB には、必要に応じて選択して使用できるその他のツールも用意されています。

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

注記：

PingCAP は以前、TiDB 固有の機能強化を加えたmydumper プロジェクトのフォークを維持していました。v7.5.0 以降、 マイダンパー非推奨となり、その機能のほとんどがDumplingに置き換えられました。mydumper ではなくDumpling を使用することを強くお勧めします。

Dumplingには次のような利点があります。

• SQL や CSV を含む複数の形式でのデータのエクスポートをサポートします。
• データのフィルタリングを容易にするテーブルフィルター機能をサポートします。
• Amazon S3 クラウドstorageへのデータのエクスポートをサポートします。
• TiDB に対してさらなる最適化が行われました:
  • 単一のTiDB SQLステートメントのメモリ制限の構成をサポートします。
  • Dumpling がTiDB クラスターの PD アドレスとINFORMATION_SCHEMA.CLUSTER_INFOテーブルにアクセスできる場合、 Dumpling はTiDB v4.0.0 以降のバージョンでGCセーフ ポイント時間をブロック 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からデータをエクスポートする

必要な権限

• プロセス: クラスター情報を照会して PD アドレスを取得し、PD 経由で GC を制御するために必要です。
• SELECT: テーブルをエクスポートするときに必要です。
• RELOAD: consistency flush使用する場合に必須です。この権限をサポートするのは TiDB のみであることに注意してください。アップストリームが RDS データベースまたはマネージド サービスである場合、この権限は無視できます。
• LOCK TABLES: consistency lock使用する場合に必要です。この権限は、エクスポートするすべてのデータベースとテーブルに付与する必要があります。
• レプリケーション クライアント: データのスナップショットを記録するためにメタデータをエクスポートするときに必要です。この権限はオプションであり、メタデータをエクスポートする必要がない場合は無視できます。

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

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

Dumpling はデフォルトでデータ--filetype sql SQL ファイルにエクスポートします。1 フラグを追加してデータを 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 ) オプションは、storageのエクスポート ディレクトリを指定します。これは、絶対ローカル ファイル パスまたは外部storageURIをサポートします。
• -tオプションは、エクスポートのスレッド数を指定します。スレッド数を増やすと、 Dumplingの同時実行性とエクスポート速度が向上しますが、データベースのメモリ消費も増加します。したがって、数値を大きくしすぎることはお勧めしません。通常は 64 未満です。
• -rオプションは、テーブル内同時実行を有効にしてエクスポートを高速化します。デフォルト値は0で、無効を意味します。0 より大きい値は有効であることを意味し、値はINTタイプです。ソース データベースが TiDB の場合、0 より大きい値-r 、TiDB 領域情報が分割に使用され、メモリ使用量が削減されることを示します。特定の-r値は分割アルゴリズムに影響しません。ソース データベースが MySQL で、主キーがINTタイプの場合、 -rを指定してもテーブル内同時実行を有効にできます。
• -Fオプションは、単一ファイルの最大サイズを指定するために使用されます (ここでの単位はMiBですが、 5GiBや8KBなどの入力も許容されます)。TiDB TiDB Lightningを使用してこのファイルを TiDB インスタンスにロードする予定の場合は、値を 256 MiB 以下に維持することをお勧めします。

注記：

エクスポートされた単一のテーブルのサイズが 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になるように指定します。

• --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によってエクスポートされた圧縮ファイルをデータ ソースとして使用できます。

注記：

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-post.sqlその他の*-schema-trigger.sqlファイル

Amazon S3クラウドstorageにデータをエクスポートする

バージョン 4.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オプションを指定して特定のスナップショットのデータをエクスポートできます。

--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) 以下に減らします。5 --tidb-mem-quota-query TiDB 内の単一のクエリ ステートメントのメモリ使用量を制御します。
• --params "tidb_distsql_scan_concurrency=5"パラメータを調整します。3 tidb_distsql_scan_concurrency 、TiDB でのスキャン操作の同時実行を制御するセッション変数です。

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

TiDB からデータをエクスポートする場合 (1 TB 未満)、TiDB のバージョンが v4.0.0 以降で、 Dumpling がTiDB クラスターの PD アドレスとINFORMATION_SCHEMA.CLUSTER_INFOテーブルにアクセスできる場合、 Dumpling はGC セーフ ポイントを自動的に調整し、元のクラスターに影響を与えずに 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のオプションリスト