TiDB Lightning使ったデータインポートを試した

はじめに

きっかけは、TiDBユーザグループ ミートアップ #5に参加し、そこでTiDB Lightningの紹介があり、どんなものかと試してみたことです。「数百万行、数億行のデータをTiDBに投入したいけど、INSERT文をループで実行すると時間がかかりすぎる…」という課題を解決するこのツールに興味を持ちました。

TiDB Lightningは、CSVやParquetなどのデータソースを直接TiKV（TiDBのストレージ層）に書き込むことで、従来のLOAD DATAやINSERT文とは比較にならない速度でデータをインポートします。

この記事では、ローカルのTiDBクラスタに対して、TiDB Lightningを使ってCSVファイルをインポートする手順を、設定ファイルの書き方から、実際に筆者が遭遇した多くのエラーとその最終的な解決策までを含めて解説します。

TiDB Lightningの仕組み（なぜ速いのか？）

通常のINSERT文は、SQLレイヤー（TiDB）を経由して、一行ずつデータをストレージ層（TiKV）に書き込みます。これは丁寧ですが、データ量が多いとボトルネックになります。

TiDB Lightningは、このSQLレイヤーをバイパスします。データを読み込んでTiKVが理解できる形式（キーと値のペア）に変換し、それを直接TiKVノードに流し込みます。例えるなら、「レジで商品を一つずつスキャンする」のではなく、「閉店後に業者が倉庫から直接商品を棚に並べる」ようなものです。

2つの動作モード
TiDB Lightningには2つの主要な動作モードがあります。

① ローカルバックエンド (backend = "local"): 最も高速なモード。インポート中はTiKVクラスタを「インポート専用モード」にして、超高速でデータを書き込みます。初期データ投入に最適で、今回の記事ではこちらを使用します。

② TiDBバックエンド (backend = "tidb"): 稼働中のクラスタを停止させずにインポートするモード。速度は劣りますが、オンラインのサービスにデータを追加する場合に使います。

チュートリアル：CSVデータをインポートする

前回使用したDockerコンテナが構築済みが前提となります。

準備

1. 前回で作ったTiDBのコンテナにアクセスします。
2. TiDB Lightningのインストール: tiupをインストールした環境で以下のコマンドを実行します。

   tiup install tidb-lightning
   

3. ソースデータ: インポートしたいCSVファイル。

ステップ1: インポート用データ（CSV）の準備

まず、インポートするデータを用意します。ここでは、シンプルなユーザー情報を想定したusers.csvを作成します。

./src/infra/db/tidb/data/test_db/test_db.users.csv

id,name
1,"Alice"
2,"Bob"
3,"Charlie"
4,"David"

この際に注意とすればヘッダーは、カラム名にします。
ヘッダーが無いとどこに何のデータをインポートするのか判断できないとエラーが出ます。

ステップ2: ターゲットDBの作成

インポート用のDBを作成します。
ルールとすればDB名_schema.sqlとします。

./src/infra/db/tidb/data/test_db/test_db-schema.sql

CREATE DATABASE IF NOT EXISTS test_db;
USE test_db;

ステップ3: ターゲットテーブルの作成

次に、インポート先のTiDBにテーブルを作成しておきます。TiDB Lightningは、このテーブル定義を見て、CSVの各列をどのカラムに対応させるかを判断します。
ルールとすればDB名_テーブル名-schema.sqlとします。

./src/infra/db/tidb/data/test_db/test_db-schema.sql

CREATE DATABASE IF NOT EXISTS my_db;

CREATE TABLE my_db.users (
    id BIGINT NOT NULL,
    name VARCHAR(255) NOT NULL,
);

ステップ4: 設定ファイル (lightning.toml) の作成

ここがTiDB Lightningの最も重要な部分です。インポートの挙動を制御するための設定ファイルをTOML形式で作成します。

./src/infra/db/tidb/lightning.toml

[lightning]
status-addr = ":8289"
level = "info"

[tikv-importer]
backend = "local"
sorted-kv-dir = "/tmp/sorted-kv"

[mydumper]
data-source-dir = "./data"

[tidb]
host = "127.0.0.1"
port = 4000
user = "root"
password = ""
status-port = 10080
pd-addr = "127.0.0.1:2379"

ステップ5: ディレクトリ構造の準備

設定ファイルに合わせて、以下のようなディレクトリとファイルを配置します。
TiDB Lightningは、ファイル名からインポート先のテーブルを自動で推測します。

.
├── lightning.toml
└── data/
    └── test_db-schema.sql
    └── test_db.users-schema.sql
    └── test_db.users.csv

ステップ6: インポートの実行

全ての準備が整ったら、tidb-lightningコマンドを実行します。
この際に、以下コマンドを実行したらパッケージのインストールも行なってくれます。

tiup tidb-lightning -c lightning.toml

注意

• 本番用のクラスターを構築しようとすると、SSHの設定が必要になります。
• DB用スキーマのDDLとテーブル用のDDLを分けないとインポートできませんでした

まとめ

TiDB Lightningを使えば、SQLレイヤーをバイパスすることで、大容量のデータをTiDBへ極めて高速にインポートできます。特に、バージョン不整合による不可解な設定エラーはハマりやすいポイントですが、バージョンを固定してフルパスで実行することで確実に回避できます。

TiDBユーザグループで知ったこのツール、皆さんもぜひお手元の環境でこの圧倒的なインポート速度を体感してみてください。