TiDB Lightning FAQ

What is the minimum TiDB/TiKV/PD cluster version supported by Lightning?

The version of TiDB Lightning should be the same as the cluster. The earliest available version is 2.0.9, but we recommend using the latest stable version (3.0).

Does TiDB Lightning support importing multiple schemas (databases)?

Yes.

What is the privilege requirements for the target database?

TiDB Lightning requires the following privileges:

• SELECT
• UPDATE
• ALTER
• CREATE
• DROP

If the TiDB-backend is chosen, or the target database is used to store checkpoints, it additionally requires these privileges:

• INSERT
• DELETE

The Importer-backend does not require these two privileges because data is ingested into TiKV directly, which bypasses the entire TiDB privilege system. This is secure as long as the ports of TiKV, TiKV Importer and TiDB Lightning are not reachable outside the cluster.

If the checksum configuration of TiDB Lightning is set to true, then the admin user privileges in the downstream TiDB need to be granted to TiDB Lightning.

TiDB Lightning encountered an error when importing one table. Will it affect other tables? Will the process be terminated?

If only one table has an error encountered, the rest will still be processed normally.

How to properly restart TiDB Lightning?

Depending on the status of tikv-importer, the basic sequence of restarting TiDB Lightning is like this:

If tikv-importer is still running:

1. Stop tidb-lightning.
2. Perform the intended modifications, such as fixing the source data, changing settings, replacing hardware etc.
3. If the modification previously has changed any table, remove the corresponding checkpoint too.
4. Start tidb-lightning.

If tikv-importer needs to be restarted:

1. Stop tidb-lightning.
2. Stop tikv-importer.
3. Perform the intended modifications, such as fixing the source data, changing settings, replacing hardware etc.
4. Start tikv-importer.
5. Start tidb-lightning and wait until the program fails with CHECKSUM error, if any.
   • Restarting tikv-importer would destroy all engine files still being written, but tidb-lightning did not know about it. As of v3.0 the simplest way is to let tidb-lightning go on and retry.
6. Destroy the failed tables and checkpoints
7. Start tidb-lightning again.

How to ensure the integrity of the imported data?

TiDB Lightning by default performs checksum on the local data source and the imported tables. If there is checksum mismatch, the process would be aborted. These checksum information can be read from the log.

You could also execute the ADMIN CHECKSUM TABLE SQL command on the target table to recompute the checksum of the imported data.

ADMIN CHECKSUM TABLE `schema`.`table`;

+---------+------------+---------------------+-----------+-------------+
| Db_name | Table_name | Checksum_crc64_xor  | Total_kvs | Total_bytes |
+---------+------------+---------------------+-----------+-------------+
| schema  | table      | 5505282386844578743 |         3 |          96 |
+---------+------------+---------------------+-----------+-------------+
1 row in set (0.01 sec)

What kind of data source format is supported by Lightning?

TiDB Lightning only supports the SQL dump generated by Mydumper or CSV files stored in the local file system.

Could TiDB Lightning skip creating schema and tables?

Yes. If you have already created the tables in the target database, you could set no-schema = true in the [mydumper] section in tidb-lightning.toml. This makes TiDB Lightning skip the CREATE TABLE invocations and fetch the metadata directly from the target database. TiDB Lightning will exit with error if a table is actually missing.

Can the Strict SQL Mode be disabled to allow importing invalid data?

Yes. By default, the sql_mode used by TiDB Lightning is "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION", which disallows invalid data such as the date 1970-00-00. The mode can be changed by modifying the sql-mode setting in the [tidb] section in tidb-lightning.toml.

...
[tidb]
sql-mode = ""
...

Can one tikv-importer serve multiple tidb-lightning instances?

Yes, as long as every tidb-lightning instance operates on different tables.

How to stop the tikv-importer process?

To stop the tikv-importer process, you can choose the corresponding operation according to your deployment method.

• For deployment using TiDB Ansible: run scripts/stop_importer.sh on the Importer server.

• For manual deployment: if tikv-importer is running in foreground, press Ctrl+C to exit. Otherwise, obtain the process ID using the ps aux | grep tikv-importer command and then terminate the process using the kill «pid» command.

How to stop the tidb-lightning process?

To stop the tidb-lightning process, you can choose the corresponding operation according to your deployment method.

• For deployment using TiDB Ansible: run scripts/stop_lightning.sh on the Lightning server.

• For manual deployment: if tidb-lightning is running in foreground, press Ctrl+C to exit. Otherwise, obtain the process ID using the ps aux | grep tidb-lighting command and then terminate the process using the kill -2 «pid» command.

Why the tidb-lightning process suddenly quits while running in background?

It is potentially caused by starting tidb-lightning incorrectly, which causes the system to send a SIGHUP signal to stop the tidb-lightning process. In this situation, tidb-lightning.log usually outputs the following log:

[2018/08/10 07:29:08.310 +08:00] [INFO] [main.go:41] ["got signal to exit"] [signal=hangup]

It is not recommended to directly use nohup in the command line to start tidb-lightning. You can start tidb-lightning by executing a script.

Why my TiDB cluster is using lots of CPU resources and running very slowly after using TiDB Lightning?

If tidb-lightning abnormally exited, the cluster might be stuck in the "import mode", which is not suitable for production. You can force the cluster back to "normal mode" using the following command:

tidb-lightning-ctl --switch-mode=normal

Can TiDB Lightning be used with 1-Gigabit network card?

The TiDB Lightning toolset is best used with a 10-Gigabit network card. 1-Gigabit network cards are not recommended, especially for tikv-importer.

1-Gigabit network cards can only provide a total bandwidth of 120 MB/s, which has to be shared among all target TiKV stores. TiDB Lightning can easily saturate all bandwidth of the 1-Gigabit network and bring down the cluster because PD is unable to be contacted anymore. To avoid this, set an upload speed limit in Importer's configuration:

[import]
# Restricts the total upload speed to TiKV to 100 MB/s or less
upload-speed-limit = "100MB"

Why TiDB Lightning requires so much free space in the target TiKV cluster?

With the default settings of 3 replicas, the space requirement of the target TiKV cluster is 6 times the size of data source. The extra multiple of “2” is a conservative estimation because the following factors are not reflected in the data source:

• The space occupied by indices
• Space amplification in RocksDB

Can TiKV Importer be restarted while TiDB Lightning is running?

No. Importer stores some information of engines in memory. If tikv-importer is restarted, tidb-lightning will be stopped due to lost connection. At this point, you need to destroy the failed checkpoints as those Importer-specific information is lost. You can restart Lightning afterwards.

See also How to properly restart TiDB Lightning? for the correct sequence.

How to completely destroy all intermediate data associated with TiDB Lightning?

1. Delete the checkpoint file.

   tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-remove=all
   

   If, for some reason, you cannot run this command, try manually deleting the file /tmp/tidb_lightning_checkpoint.pb.

2. Delete the entire "import" directory on the machine hosting tikv-importer.

3. Delete all tables and databases created on the TiDB cluster, if needed.