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

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

TiUP使ってtiup install dumpling実行するとDumpling が手に入ります。その後、 tiup dumpling ...使ってDumpling を実行できます。

DumplingインストールパッケージはTiDB Toolkitに含まれています。TiDBTiDB Toolkitをダウンロードするには、 TiDBツールをダウンロード参照してください。

Dumplingの詳細な使用方法については、 --helpオプションを使用するか、 Dumplingのオプションリストを参照してください。

Dumpling を使用する場合は、実行中のクラスターでエクスポート コマンドを実行する必要があります。

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

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

注記：

PingCAPは以前、TiDBに特化した機能強化を加えたバージョンmydumperプロジェクトのフォークを保守していました。バージョン7.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場合に必須です。アップストリームが RDS データベースまたはマネージドサービスの場合は、この権限は無視できます。
• LOCK TABLES: レベルconsistencyがlock場合に必要です。この権限は、エクスポートするすべてのデータベースとテーブルに付与する必要があります。
• レプリケーションクライアント: データのスナップショットを記録するためにメタデータをエクスポートする場合に必要です。この権限はオプションであり、メタデータをエクスポートする必要がない場合は無視できます。
• SHOW VIEW: エクスポート用のビュー メタデータを収集するために必要です。

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

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

DumplingはデフォルトでSQLファイルにデータをエクスポートします。1 --filetype sqlを追加することで、SQLファイルにデータをエクスポートすることもできます。

tiup 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より大きい値で有効にした場合、動作はソースデータベースによって異なります。

  • TiDBの場合、 Dumplingは分割にリージョン情報を使用するため、メモリ使用量も削減されます。指定された値-rは分割アルゴリズムに影響を与えません。
  • MySQL の場合、このオプションは、主キー (または複合主キーの最初の列) がINTまたはSTRINGタイプの場合にサポートされます。

• -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に一致するすべてのレコードをエクスポートできます。

tiup 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 はエクスポートされたテーブルとスキーマ情報を取得できません。3 オプションを使用して CSV ファイルのファイル名形式を指定できます。これにより、後で--output-filename-templateオプションを使用してデータファイルをインポートしやすくなります。例えば、 --output-filename-template='test.sbtest1.{{.Index}}'指定すると、エクスポートされた CSV ファイルはTiDB Lightningまたはtest.sbtest1.000000001 test.sbtest1.000000000名前になります。

• --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 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形式参照してください。

tiup dumpling -u root -P 4000 -h 127.0.0.1 -r 200000 -o "s3://${Bucket}/${Folder}"

エクスポートしたデータをフィルタリングする

--whereオプションを使用してデータをフィルタリングします

デフォルトMETRICS_SCHEMA PERFORMANCE_SCHEMA 、 DumplingはINSPECTION_SCHEMAデータベース（ mysqlを含む） INFORMATION_SCHEMA除くすべてのデータベースをエクスポートします--where <SQL where expression>使用して、エクスポートするレコードsys選択できます。

tiup dumpling -u root -P 4000 -h 127.0.0.1 -o /tmp/test --where "id < 100"

上記のコマンドは、各テーブルからid < 100に一致するデータ--sql --whereを同時に使用できないことに注意してください。

--filterオプションを使用してデータをフィルタリングします

Dumplingは、 --filterオプションでテーブルフィルタを指定することで、特定のデータベースまたはテーブルをフィルタリングできます。テーブルフィルタの構文は.gitignoreと同様です。詳細はテーブルフィルター参照してください。

tiup 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 zstd圧縮アルゴリズムをサポートしています。storageがsnappyネックになっている場合やstorage容量が懸念される場合、このオプションを使用するとデータのダンプを高速化できます。ただし、CPU使用率が増加するという欠点があります。各ファイルは個別に圧縮されます。

上記のオプションを指定すると、 Dumpling はデータのエクスポート速度を速めることができます。

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

注記：

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

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

• flush : レプリカデータベースのDMLおよびDDL操作を一時的に中断し、バックアップ接続のグローバルな一貫性を確保し、binlogの位置（POS）情報を記録するために、 FLUSH TABLES WITH READ LOCK使用します。ロックは、すべてのバックアップ接続がトランザクションを開始した後に解除されます。フルバックアップは、オフピーク時間帯またはMySQLレプリカデータベースで実行することをお勧めします。TiDBはこの値をサポートしていないことに注意してください。
• 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の形式) に設定できます。次に例を示します。

tiup dumpling --snapshot 417773951312461825
tiup 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 以降の場合、 -rが 0 より大きい場合、分割には 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 時間を自動的に調整できません。

• データサイズが非常に大きい（1 TB 以上）。
• たとえば、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のオプションリスト

出力ファイル名テンプレート

--output-filename-template引数は、ファイル拡張子を除く出力ファイルの命名規則を定義しますGo text/template構文の文字列を受け入れます。

テンプレートでは次のフィールドを使用できます。

• .DB : データベース名
• .Table : テーブル名またはオブジェクト名
• .Index : テーブルが複数のファイルに分割されている場合、ファイルの0から始まるシーケンス番号。ダンプされる部分を示します。例えば、 {{printf "%09d" .Index}} .Index先頭に0が付いた9桁の数字としてフォーマットすることを意味します。

データベース名やテーブル名には、ファイルシステムでは許可されていない特殊文字（ /など）が含まれている場合があります。この問題に対処するため、 Dumplingはこれらの特殊文字をパーセントエンコードするfn関数を提供しています。

• U+0000からU+001F（制御文字）
• / > < : ? \ * "
• . (データベース名またはテーブル名の区切り文字)
• - 、 -schemaの一部として使用される場合

たとえば、 --output-filename-template '{{fn .Table}}.{{printf "%09d" .Index}}'使用すると、 Dumpling はテーブルdb.tbl:normal tbl%3Anormal.000000000.sql 、 tbl%3Anormal.000000001.sqlなどの名前のファイルに書き込みます。

出力データファイルに加えて、スキーマファイルのファイル名を置き換えるために--output-filename-template定義することができます。次の表はデフォルトの設定を示しています。

たとえば、 --output-filename-template '{{define "table"}}{{fn .Table}}.$schema{{end}}{{define "data"}}{{fn .Table}}.{{printf "%09d" .Index}}{{end}}'使用すると、 Dumpling はテーブルdb.tbl:normalのスキーマをtbl%3Anormal.$schema.sqlという名前のファイルに書き込み、データをtbl%3Anormal.000000000.sql 、 tbl%3Anormal.000000001.sqlなどのファイルに書き込みます。