はじめに
以前、データエクスポートツールとしてDumplingを紹介しました。
これと対になるツールが、TiDB lightningです。
・・・なのですが、以前紹介した IMPORT INTO 文に将来的に置き換わることが予定されています。ただ、現在のところ複数のファイルを一括インポートする機能には対応しておらず、lightningの方がdumpling後の利用には便利だったりします。
本記事ではtidb-lightningの利用方法について説明します。なお、tidb-lightningはOSS版（セルフマネージ）のクラスタに対して利用すると、TiKVに直接データを投入する物理モードを利用でき、オプションも様々なものがあります。しかしこのモードはTiDB Cloudでは利用できませんので、論理モード（INSERT文を生成して実行する）の説明のみにとどめます。
準備
まずはdumplingでデータを出力しないことには始まりません。前回のDumplingの際に使ったMySQLのEmployデータベースを使い、dumplingで出力します。（TiDBは、TiDB Playgroundを利用しています）
tiup dumpling -h 127.0.0.1 -P 3306 -u root -p <password> \
-B employees -o output/ --filetype sql
できるファイルはこんな感じです
> ls output
employees-schema-create.sql employees.dept_manager.000000000.sql employees.test.000000000.sql
employees.departments-schema.sql employees.employees-schema.sql employees.titles-schema.sql
employees.departments.000000000.sql employees.employees.000000000.sql employees.titles.000000000.sql
employees.dept_emp-schema.sql employees.salaries-schema.sql metadata
employees.dept_emp.000000000.sql employees.salaries.000000000.sql
employees.dept_manager-schema.sql employees.test-schema.sql
tidb-lightning.toml ファイルの準備
tidb lightningの実行には、設定を記述したtomlファイルが必要です。今回利用するファイルは次のようになります。
[lightning]
# Logging
level = "info"
file = "tidb-lightning.log"
[conflict]
strategy = "replace"
[tikv-importer]
# Configure the import mode
backend = "tidb"
[mydumper]
# Local source data directory
data-source-dir = "output"
[tidb]
# Information of the target cluster
host = "127.0.0.1"
port = 4000
user = "root"
password = ""
設定ファイルの詳細は下記のドキュメントを御覧ください。
ここで利用しているセクションのうち、よく変更するものについて説明します。
conflict
キーやユニーク制約違反が発生した場合の扱いを記載します。
- strategy: "replace", "ignore", "error" から選択します
replaceはINSERTする行で置き換えます。ignoreは元の行を戻し、errorはエラーにして処理を中断します。
tidb-lightningはすでにデータがあるテーブルに対してのimportもサポートしますが、その際に重複したレコードの扱いを決めるのがこのConflictセクションです。通常は、replaceかerrorと思います。
tikv-importer
- backend: "tidb"もしくは"local" です。今回利用する論理モードでは "tidb" を利用します
mydumper
- data-source-dir: dumplingがexportしたディレクトリを指定します
なお、今回のような簡単な例ならコマンドラインでも実行可能です。今回の例のほぼ同等なコマンドラインでの指定例は下記です。
tiup tidb-lightning -d output -tidb-host 127.0.0.1 -tidb-user root -tidb-port 4000 -backend tidb
実行
では実行していきます。tidb-lightningはtiupから利用できます。
> tiup tidb-lightning -config tidb-lightning.toml
Starting component tidb-lightning: /Users/bohnen/.tiup/components/tidb-lightning/v8.5.0/tidb-lightning -config tidb-lightning.toml
Verbose debug logs will be written to tidb-lightning.log
+---+----------------------------------------------+-------------+--------+
| # | CHECK ITEM | TYPE | PASSED |
+---+----------------------------------------------+-------------+--------+
| 1 | Source data files size is proper | performance | true |
+---+----------------------------------------------+-------------+--------+
| 2 | the checkpoints are valid | critical | true |
+---+----------------------------------------------+-------------+--------+
| 3 | Cluster version check passed | critical | true |
+---+----------------------------------------------+-------------+--------+
| 4 | Lightning has the correct storage permission | critical | true |
+---+----------------------------------------------+-------------+--------+
tidb lightning exit successfully
事前チェックをパスして無事インポートされました。
（Tips) tidb-lightning-ctl ツール
tidb lightiningは実行結果やチェックポイントをDBや /tmp などに作成して、失敗するとこれらの場所にレコードやログが残ります。そして再実行に失敗するケースがあります。
+---+------------------------------------------------------------------------------------------------------------------------------------+-------------+--------+
| # | CHECK ITEM | TYPE | PASSED |
+---+------------------------------------------------------------------------------------------------------------------------------------+-------------+--------+
| 1 | Source data files size is proper | performance | true |
+---+------------------------------------------------------------------------------------------------------------------------------------+-------------+--------+
| 2 | TiDB Lightning has failed last time. To prevent data loss, this run will stop now, `employees`.`dept_emp` failed in step(written), | critical | false |
| | please run command ./tidb-lightning-ctl --checkpoint-error-destroy='`employees`.`dept_emp`' --config=...,You may also run `./tidb | | |
| | -lightning-ctl --checkpoint-error-destroy=all --config=...` to start from scratch,For details of this failure, read the log file f | | |
| | rom the PREVIOUS run | | |
| | TiDB Lightning has failed last time. To prevent data loss, this run will stop now, `employees`.`employees` failed in step(written) | | |
| | , please run command ./tidb-lightning-ctl --checkpoint-error-destroy='`employees`.`employees`' --config=...,You may also run `./ti | | |
| | db-lightning-ctl --checkpoint-error-destroy=all --config=...` to start from scratch,For details of this failure, read the log file | | |
| | from the PREVIOUS run | | |
+---+------------------------------------------------------------------------------------------------------------------------------------+-------------+--------+
エラーメッセージには tidb-lightning-ctl を利用するように指示があるのですが、このツール、実はMacバージョンがありません。
Macバージョンは先日記事にしたTiDBのgithubリポジトリで、make build_-lightning-ctl すると作成できます。
または、中間結果を保存しているデータベース、/tmp/ 以下のファイルを削除しても構いません。
mysql> drop database lightning_task_info;
Query OK, 0 rows affected (0.07 sec)
rm /tmp/tidb_lightning_checkpoint.pb
覚えておくと良いと思います。
おわりに
tidb-lightiningは、dumplingの出力するsql, csvファイルに対応しているデータインポートツールです。また、ローカルファイルだけではなく S3上のファイルや、Aurora Snapshot形式のparquetなどにも対応しています。まだまだ現役ですので使い方を覚えておくとデータの出し入れに便利です。