大网数据广告活动
数据库部署与 SQL 参考

从 SQL 文件迁移数据到 TiDB

· 52CE 我爱测

本文介绍如何使用 TiDB Lightning 从 MySQL SQL 文件迁移数据到 TiDB。关于如何生成 MySQL SQL 文件,请参考 Dumpling 文档中的导出为 SQL 文件。

从 SQL 文件迁移数据到 TiDB

本文介绍如何使用 TiDB Lightning 从 MySQL SQL 文件迁移数据到 TiDB。关于如何生成 MySQL SQL 文件,请参考 Dumpling 文档中的导出为 SQL 文件。

前提条件

第 1 步:准备 SQL 文件

将所有 SQL 文件放到统一目录下,例如 /data/my_datasource/ 或 s3://my-bucket/sql-backup。默认情况下,TiDB Lightning 会递归搜索该目录及其子目录中符合 ${db_name}.${table_name}.sql 或 ${db_name}.${table_name}.001.sql 等命名模式的 SQL 数据文件。

如果你的 SQL 文件使用了不同的命名方式,请配置 [[mydumper.files]] 来匹配这些文件。自定义规则会禁用默认的文件匹配规则。若希望在使用自定义规则的同时继续匹配符合默认命名模式的文件,请在 [mydumper] 下设置 default-file-rules = true。否则,自定义规则需要能涵盖所有所需的数据文件和表结构文件。

第 2 步:定义目标表结构

要导入 TiDB,就必须为 SQL 文件提供表结构。

如果使用 Dumpling 工具导出数据,则会自动导出表结构文件。此外,其他方式导出的数据可以通过以下任一方法创建表结构:

  • 方法一:使用 TiDB Lightning 创建表结构。

    编写包含 DDL 语句的 SQL 文件:

    • 文件名格式为 ${db_name}-schema-create.sql,其内容需包含 CREATE DATABASE 语句。
    • 文件名格式为 ${db_name}.${table_name}-schema.sql,其内容需包含 CREATE TABLE 语句。
  • 方法二:手动在下游 TiDB 建库和表。

第 3 步:编写配置文件

新建文件 tidb-lightning.toml,包含以下内容:

[lightning]
# 日志
level = "info"
file = "tidb-lightning.log"

[tikv-importer]
# "local":默认使用该模式,适用于 TiB 级以上大数据量。导入期间,下游 TiDB 只能提供有限服务。如果 TiDB Lightning 版本为 v6.2.0 及以上且 TiDB 版本为 v6.1.0 及以上,TiDB Lightning 默认只会暂停目标表对应 Region 的调度。导入仍可能影响集群性能。
# 导入期间,请勿对目标表执行 DDL 或 DML 操作。
# 避免读取目标表,因为读取结果可能不一致。
backend = "local"
# # "tidb":TiB 级以下数据量也可以采用 `tidb` 后端模式,下游 TiDB 可正常提供服务。关于后端模式更多信息请参考 https://docs.pingcap.com/zh/tidb/stable/tidb-lightning-backends 。
# 设置排序的键值对的临时存放地址,目标路径必须是一个空目录,目录空间须大于待导入数据集的大小。建议设为与 `data-source-dir` 不同的磁盘目录并使用闪存介质,独占 I/O 会获得更好的导入性能。
sorted-kv-dir = "${sorted-kv-dir}"

[mydumper]
# 源数据目录
data-source-dir = "${data-path}" # 本地或 S3 路径,例如:'s3://my-bucket/sql-backup'

[tidb]
# 目标集群的信息
host = "${host}"            # 例如:172.16.32.1
port = ${port}              # 例如:4000
user = "${user_name}"     # 例如:"root"
password = "${password}"  # 例如:"rootroot"
status-port = ${status-port}  # 导入过程 Lightning 需要在从 TiDB 的“状态端口”获取表结构信息,例如:10080
pd-addr = "${ip}:${port}" # 集群 PD 的地址,Lightning 通过 PD 获取部分信息,例如 172.16.31.3:2379。当 backend = "local" 时 status-port 和 pd-addr 必须正确填写,否则导入将出现异常。

关于配置文件更多信息,可参阅 TiDB Lightning Configuration。

第 4 步:执行导入

运行 tidb-lightning。如果直接在命令行中启动程序,可能会因为 SIGHUP 信号而退出,建议配合 nohup 或 screen 等工具。

若从 Amazon S3 导入,则需将有权限访问该 S3 后端存储的账号的 SecretKey 和 AccessKey 作为环境变量传入 Lightning 节点。

建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。将 <version> 替换为目标 TiDB 集群的版本号。

nohup tiup tidb-lightning:<version> -config tidb-lightning.toml > nohup.out 2>&1 &

同时,TiDB Lightning 还支持从 ~/.aws/credentials 读取凭证文件。

导入开始后,可以采用以下任意方式查看进度:

  • 通过 grep 日志关键字 progress 查看进度,默认 5 分钟更新一次。
  • 通过监控面板查看进度,请参考 TiDB Lightning 监控。

导入完毕后,TiDB Lightning 会自动退出。查看 tidb-lightning.log 日志末尾是否有 the whole procedure completed 信息,如果有,表示导入成功。如果没有,则表示导入遇到了问题,可根据日志中的 error 提示解决遇到的问题。

注意:

无论导入成功与否,最后一行都会显示 tidb lightning exit。它只是表示 TiDB Lightning 正常退出,不代表任务完成。

如果导入过程中遇到问题,请参见 TiDB Lightning 常见问题。

本文来自 PingCAP / TiDB 文档贡献者,按 CC BY-SA 3.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
PingCAP / TiDB 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY-SA 3.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。