TiDB lightningの使い方

## はじめに

以前、データエクスポートツールとしてDumplingを紹介しました。

https://qiita.com/bohnen/items/c65f382d2b7f64ad3ef0

これと対になるツールが、TiDB lightningです。

https://docs.pingcap.com/ja/tidb/stable/tidb-lightning-overview

・・・なのですが、以前紹介した `IMPORT INTO` 文に将来的に置き換わることが予定されています。ただ、現在のところ複数のファイルを一括インポートする機能には対応しておらず、lightningの方がdumpling後の利用には便利だったりします。

本記事ではtidb-lightningの利用方法について説明します。なお、tidb-lightningはOSS版（セルフマネージ）のクラスタに対して利用すると、TiKVに直接データを投入する物理モードを利用でき、オプションも様々なものがあります。しかしこのモードはTiDB Cloudでは利用できませんので、論理モード（INSERT文を生成して実行する）の説明のみにとどめます。

## 準備

まずはdumplingでデータを出力しないことには始まりません。前回のDumplingの際に使ったMySQLのEmployデータベースを使い、dumplingで出力します。（TiDBは、TiDB Playgroundを利用しています）

```bash
tiup dumpling -h 127.0.0.1 -P 3306 -u root -p <password> \
-B employees -o output/ --filetype sql
```

できるファイルはこんな感じです

```bash
> 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ファイルが必要です。今回利用するファイルは次のようになります。

```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 = ""
```

設定ファイルの詳細は下記のドキュメントを御覧ください。

https://docs.pingcap.com/ja/tidb/stable/tidb-lightning-configuration#configuration-files

ここで利用しているセクションのうち、よく変更するものについて説明します。

### 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したディレクトリを指定します

:::note info
なお、今回のような簡単な例ならコマンドラインでも実行可能です。今回の例のほぼ同等なコマンドラインでの指定例は下記です。
```bash
tiup tidb-lightning -d output -tidb-host 127.0.0.1 -tidb-user root -tidb-port 4000 -backend tidb
```
:::

## 実行

では実行していきます。tidb-lightningはtiupから利用できます。

```bash
> 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` などに作成して、失敗するとこれらの場所にレコードやログが残ります。そして再実行に失敗するケースがあります。

```bash
+---+------------------------------------------------------------------------------------------------------------------------------------+-------------+--------+
| # | 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バージョンがありません。

https://docs.pingcap.com/tidb/stable/download-ecosystem-tools

Macバージョンは先日記事にしたTiDBのgithubリポジトリで、`make build_-lightning-ctl` すると作成できます。

https://qiita.com/bohnen/items/a890c9afd721e31647ea

または、中間結果を保存しているデータベース、`/tmp/` 以下のファイルを削除しても構いません。

```sql
mysql> drop database lightning_task_info;
Query OK, 0 rows affected (0.07 sec)
```

```bash
 rm /tmp/tidb_lightning_checkpoint.pb
```

覚えておくと良いと思います。

## おわりに

tidb-lightiningは、dumplingの出力するsql, csvファイルに対応しているデータインポートツールです。また、ローカルファイルだけではなく S3上のファイルや、Aurora Snapshot形式のparquetなどにも対応しています。まだまだ現役ですので使い方を覚えておくとデータの出し入れに便利です。