Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pingcap/tidb/llms.txt

Use this file to discover all available pages before exploring further.

TiDB is MySQL-compatible, which means most applications can migrate with minimal changes. The standard migration path uses Dumpling to export data and TiDB Lightning to import it at high speed.

​
Migration workflow

1

Assess compatibility

Review your schema and queries for any MySQL features TiDB handles differently — foreign key enforcement, auto-increment behavior, and certain system variables. Run your application test suite against TiDB first.
2

Export from MySQL with Dumpling

Dumpling exports data from MySQL (or MariaDB) as SQL or CSV files.
tiup dumpling \
  -u root -P 3306 -h 127.0.0.1 \
  --filetype sql \
  --threads 4 \
  --output ./export \
  --consistency flush
For large databases, export specific databases with --filter:
tiup dumpling -u root -P 3306 -h 127.0.0.1 \
  --filter "mydb.*" \
  --filetype csv \
  --output ./export
3

Import into TiDB with TiDB Lightning

TiDB Lightning imports the exported files into TiDB at high speed.
tiup tidb-lightning \
  --config tidb-lightning.toml
Minimal tidb-lightning.toml:
tidb-lightning.toml
[lightning]
level = "info"
file = "tidb-lightning.log"

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

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

[tidb]
host = "127.0.0.1"
port = 4000
user = "root"
password = ""
4

Verify the migration

Compare row counts and spot-check data between source and target.
-- Run on both MySQL and TiDB, compare results
SELECT table_name, table_rows
FROM information_schema.tables
WHERE table_schema = 'mydb'
ORDER BY table_name;
5

Switch application traffic

Update your application’s connection string to point to TiDB (port 4000). TiDB accepts the same MySQL protocol, so no driver changes are needed.

​
Continuous replication with DM

For zero-downtime migrations, use TiDB Data Migration (DM) to replicate changes from MySQL to TiDB in real time while you migrate.
Use Dumpling + TiDB Lightning for a one-time bulk import. Suitable when you can afford a maintenance window.
  • Fast: Lightning physical mode can import hundreds of GB per hour
  • Simple: no ongoing replication to manage
  • Best for: new projects, smaller datasets, scheduled migrations

​
TiDB Lightning import modes

Physical Import Mode

Directly ingest SST files into TiKV. Fastest option — suitable for initial bulk loads. Requires exclusive access to the target table.

Logical Import Mode

Uses SQL INSERT statements. Slower but works with a live cluster and concurrent writes. Use backend = "tidb" in config.
Physical import mode (backend = "local") is recommended for large datasets. For tables already in production use, switch to logical mode (backend = "tidb").

Build docs developers (and LLMs) love

Get started for freeTalk to us