- 文档中心
- 关于 TiDB
- 快速上手
- 部署标准集群
- 数据迁移
- 运维操作
- 监控与告警
- 故障诊断
- 性能调优
- 系统调优
- 软件调优
- SQL 性能调优
- SQL 性能调优概览
- 理解 TiDB 执行计划
- SQL 优化流程
- 控制执行计划
- 教程
- TiDB 工具
- 功能概览
- 适用场景
- 工具下载
- TiUP
- TiDB Operator
- Dumpling
- TiDB Lightning
- TiDB Data Migration
- Backup & Restore (BR)
- TiDB Binlog
- TiCDC
- TiUniManager
- sync-diff-inspector
- TiSpark
- 参考指南
- 架构
- 监控指标
- 安全加固
- 权限
- SQL
- SQL 语言结构和语法
- SQL 语句
ADD COLUMN
ADD INDEX
ADMIN
ADMIN CANCEL DDL
ADMIN CHECKSUM TABLE
ADMIN CHECK [TABLE|INDEX]
ADMIN SHOW DDL [JOBS|QUERIES]
ALTER DATABASE
ALTER INDEX
ALTER INSTANCE
ALTER TABLE
ALTER USER
ANALYZE TABLE
BACKUP
BEGIN
CHANGE COLUMN
CHANGE DRAINER
CHANGE PUMP
COMMIT
CREATE [GLOBAL|SESSION] BINDING
CREATE DATABASE
CREATE INDEX
CREATE ROLE
CREATE SEQUENCE
CREATE TABLE LIKE
CREATE TABLE
CREATE USER
CREATE VIEW
DEALLOCATE
DELETE
DESC
DESCRIBE
DO
DROP [GLOBAL|SESSION] BINDING
DROP COLUMN
DROP DATABASE
DROP INDEX
DROP ROLE
DROP SEQUENCE
DROP STATS
DROP TABLE
DROP USER
DROP VIEW
EXECUTE
EXPLAIN ANALYZE
EXPLAIN
FLASHBACK TABLE
FLUSH PRIVILEGES
FLUSH STATUS
FLUSH TABLES
GRANT <privileges>
GRANT <role>
INSERT
KILL [TIDB]
LOAD DATA
LOAD STATS
MODIFY COLUMN
PREPARE
RECOVER TABLE
RENAME INDEX
RENAME TABLE
RENAME USER
REPLACE
RESTORE
REVOKE <privileges>
REVOKE <role>
ROLLBACK
SELECT
SET DEFAULT ROLE
SET [NAMES|CHARACTER SET]
SET PASSWORD
SET ROLE
SET TRANSACTION
SET [GLOBAL|SESSION] <variable>
SHOW [BACKUPS|RESTORES]
SHOW ANALYZE STATUS
SHOW [GLOBAL|SESSION] BINDINGS
SHOW BUILTINS
SHOW CHARACTER SET
SHOW COLLATION
SHOW [FULL] COLUMNS FROM
SHOW CONFIG
SHOW CREATE SEQUENCE
SHOW CREATE TABLE
SHOW CREATE USER
SHOW DATABASES
SHOW DRAINER STATUS
SHOW ENGINES
SHOW ERRORS
SHOW [FULL] FIELDS FROM
SHOW GRANTS
SHOW INDEX [FROM|IN]
SHOW INDEXES [FROM|IN]
SHOW KEYS [FROM|IN]
SHOW MASTER STATUS
SHOW PLUGINS
SHOW PRIVILEGES
SHOW [FULL] PROCESSSLIST
SHOW PROFILES
SHOW PUMP STATUS
SHOW SCHEMAS
SHOW STATS_HEALTHY
SHOW STATS_HISTOGRAMS
SHOW STATS_META
SHOW STATUS
SHOW TABLE NEXT_ROW_ID
SHOW TABLE REGIONS
SHOW TABLE STATUS
SHOW [FULL] TABLES
SHOW [GLOBAL|SESSION] VARIABLES
SHOW WARNINGS
SHUTDOWN
SPLIT REGION
START TRANSACTION
TABLE
TRACE
TRUNCATE
UPDATE
USE
WITH
- 数据类型
- 函数与操作符
- 聚簇索引
- 约束
- 生成列
- SQL 模式
- 事务
- 垃圾回收 (GC)
- 视图
- 分区表
- 字符集和排序规则
- 系统表
mysql
- INFORMATION_SCHEMA
- Overview
ANALYZE_STATUS
CLIENT_ERRORS_SUMMARY_BY_HOST
CLIENT_ERRORS_SUMMARY_BY_USER
CLIENT_ERRORS_SUMMARY_GLOBAL
CHARACTER_SETS
CLUSTER_CONFIG
CLUSTER_HARDWARE
CLUSTER_INFO
CLUSTER_LOAD
CLUSTER_LOG
CLUSTER_SYSTEMINFO
COLLATIONS
COLLATION_CHARACTER_SET_APPLICABILITY
COLUMNS
DATA_LOCK_WAITS
DDL_JOBS
DEADLOCKS
ENGINES
INSPECTION_RESULT
INSPECTION_RULES
INSPECTION_SUMMARY
KEY_COLUMN_USAGE
METRICS_SUMMARY
METRICS_TABLES
PARTITIONS
PROCESSLIST
SCHEMATA
SEQUENCES
SESSION_VARIABLES
SLOW_QUERY
STATISTICS
TABLES
TABLE_CONSTRAINTS
TABLE_STORAGE_STATS
TIDB_HOT_REGIONS
TIDB_INDEXES
TIDB_SERVERS_INFO
TIDB_TRX
TIFLASH_REPLICA
TIKV_REGION_PEERS
TIKV_REGION_STATUS
TIKV_STORE_STATUS
USER_PRIVILEGES
VIEWS
METRICS_SCHEMA
- UI
- CLI
- 命令行参数
- 配置文件参数
- 系统变量
- 存储引擎
- 遥测
- 错误码
- 通过拓扑 label 进行副本调度
- 常见问题解答 (FAQ)
- 版本发布历史
- 发布版本汇总
- v5.1
- v5.0
- v4.0
- v3.1
- v3.0
- v2.1
- v2.0
- v1.0
- 术语表
TiDB Lightning 常见问题
本文列出了一些使用 TiDB Lightning 时可能会遇到的问题与解决办法。
TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少?
TiDB Lightning 的版本应与集群相同。如果使用 Local-backend 模式,最低版本要求为 4.0.0。如果使用 Importer-backend 或 TiDB-backend 模式 最低版本要求是 2.0.9,但建议使用最新的稳定版本 3.0。
TiDB Lightning 支持导入多个库吗?
支持。
TiDB Lightning 对下游数据库的账号权限要求是怎样的?
TiDB Lightning 需要以下权限:
- SELECT
- UPDATE
- ALTER
- CREATE
- DROP
如果选择 TiDB-backend 模式,或目标数据库用于存储断点,则 TiDB Lightning 额外需要以下权限:
- INSERT
- DELETE
Local-backend 和 Importer-backend 无需以上两个权限,因为数据直接被 Ingest 到 TiKV 中,所以绕过了 TiDB 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问,就可以保证安全。
如果 TiDB Lightning 配置项 checksum = true
,则 TiDB Lightning 需要有下游 TiDB admin 用户权限。
TiDB Lightning 在导数据过程中某个表报错了,会影响其他表吗?进程会马上退出吗?
如果只是个别表报错,不会影响整体。报错的那个表会停止处理,继续处理其他的表。
如何正确重启 TiDB Lightning?
如果使用 Importer-backend,根据 tikv-importer
的状态,重启 TiDB Lightning 的基本顺序如下:
如果 tikv-importer
仍在运行:
- 结束
tidb-lightning
进程。 - 执行修改操作(如修复数据源、更改设置、更换硬件等)。
- 如果上面的修改操作更改了任何表,你还需要清除对应的断点。
- 重启
tidb-lightning
。
如果 tikv-importer
需要重启:
- 结束
tidb-lightning
进程。 - 结束
tikv-importer
进程。 - 执行修改操作(如修复数据源、更改设置、更换硬件等)。
- 重启
tikv-importer
。 - 重启
tidb-lightning
并等待,直到程序因校验和错误(如果有的话)而失败。- 重启
tikv-importer
将清除所有仍在写入的引擎文件,但是tidb-lightning
并不会感知到该操作。从 v3.0 开始,最简单的方法是让tidb-lightning
继续,然后再重试。
- 重启
- 清除失败的表及断点。
- 再次重启
tidb-lightning
。
如果使用 Local-backend 和 TiDB-backend,操作和 Importer-backend 的 tikv-importer
仍在运行时相同。
如何校验导入的数据的正确性?
TiDB Lightning 默认会对导入数据计算校验和 (checksum),如果校验和不一致就会停止导入该表。可以在日志看到相关的信息。
TiDB 也支持从 MySQL 命令行运行 ADMIN CHECKSUM TABLE
指令来计算校验和。
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)
TiDB Lightning 支持哪些格式的数据源?
目前,TiDB Lightning 支持:
- 导入 Dumpling、CSV 或 Amazon Aurora Parquet 输出格式的数据源。
- 从本地盘或 Amazon S3 云盘读取数据。
我已经在下游创建好库和表了,TiDB Lightning 可以忽略建库建表操作吗?
可以。在配置文档中的 [mydumper]
部分将 no-schema
设置为 true
即可。no-schema=true
会默认下游已经创建好所需的数据库和表,如果没有创建,会报错。
有些不合法的数据,能否通过关掉严格 SQL 模式 (Strict SQL Mode) 来导入?
可以。TiDB Lightning 默认的 sql_mode
为 "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"
。
这个设置不允许一些非法的数值,例如 1970-00-00
这样的日期。可以修改配置文件 [tidb]
下的 sql-mode
值。
...
[tidb]
sql-mode = ""
...
可以启用一个 tikv-importer
,同时有多个 tidb-lightning
进程导入数据吗?
只要每个 TiDB Lightning 操作的表互不相同就可以。
如何正确结束 tikv-importer
进程?
手动部署:如果 tikv-importer
正在前台运行,可直接按 Ctrl+C 退出。否则,可通过 ps aux | grep tikv-importer
获取进程 ID,然后通过 kill «pid»
结束进程。
如何正确结束 tidb-lightning
进程?
根据部署方式,选择相应操作结束进程
手动部署:如果 tidb-lightning
正在前台运行,可直接按 Ctrl+C 退出。否则,可通过 ps aux | grep tidb-lightning
获取进程 ID,然后通过 kill -2 «pid»
结束进程。
tidb-lightning
在服务器上运行,进程莫名其妙地退出了,是怎么回事呢?
这种情况可能是启动方式不正确,导致收到 SIGHUP 信号而退出。此时 tidb-lightning.log
通常有如下日志:
[2018/08/10 07:29:08.310 +08:00] [INFO] [main.go:41] ["got signal to exit"] [signal=hangup]
不推荐在命令行中直接使用 nohup
启动进程,推荐使用脚本启动 tidb-lightning
。
另外,如果从 TiDB Lightning 的 log 的最后一条日志显示遇到的错误是 "Context canceled",需要在日志中搜索第一条 "ERROR" 级别的日志。在这条日志之前,通常也会紧跟有一条 "got signal to exit",表示 Lighting 是收到中断信号然后退出的。
为什么用过 TiDB Lightning 之后,TiDB 集群变得又慢又耗 CPU?
如果 tidb-lightning
异常退出,集群可能仍处于“导入模式” (import mode),该模式不适用于生产环境。此时可执行以下命令查看当前使用的模式:
tidb-lightning-ctl --fetch-mode
可执行以下命令强制切换回“普通模式” (normal mode):
tidb-lightning-ctl --switch-mode=normal
TiDB Lightning 可以使用千兆网卡吗?
使用 TiDB Lightning 建议配置万兆网卡。不推荐使用千兆网卡,尤其是在部署 tikv-importer
的机器上。
千兆网卡的总带宽只有 120 MB/s,而且需要与整个 TiKV 集群共享。在使用 TiDB Lightning 导入时,极易用尽所有带宽,继而因 PD 无法联络集群使集群断连。为了避免这种情况,你可以在 tikv-importer
的配置文件中限制上传速度。
[import]
# Importer 上传至 TiKV 的最大速度(字节/秒)。
# 建议将该速度设为 100 MB/s 或更小。
upload-speed-limit = "100MB"
为什么 TiDB Lightning 需要在 TiKV 集群预留这么多空间?
当使用默认的 3 副本设置时,TiDB Lightning 需要 TiKV 集群预留数据源大小 6 倍的空间。多出来的 2 倍是算上下列没储存在数据源的因素的保守估计:
- 索引会占据额外的空间
- RocksDB 的空间放大效应
TiDB Lightning 使用过程中是否可以重启 TiKV Importer?
不能,TiKV Importer 会在内存中存储一些引擎文件,重启后,tidb-lightning
会因连接失败而停止。此时,你需要清除失败的断点,因为这些 TiKV Importer 特有的信息丢失了。你可以在之后重启 TiDB Lightning。
如何清除所有与 TiDB Lightning 相关的中间数据?
删除断点文件。
tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-remove=all
如果出于某些原因而无法运行该命令,你可以尝试手动删除
/tmp/tidb_lightning_checkpoint.pb
文件。如果使用 Local-backend,删除配置中
sorted-kv-dir
对应的目录;如果使用 Importer-backend,删除tikv-importer
所在机器上的整个import
文件目录。如果需要的话,删除 TiDB 集群上创建的所有表和库。
TiDB Lightning 报错 could not find first pair, this shouldn't happen
报错原因是遍历本地排序的文件时出现异常,可能在 TiDB Lightning 打开的文件数量超过系统的上限时发生报错。在 Linux 系统中,可以使用 ulimit -n
命令确认此值是否过小。建议在导入期间将此设置调整为 1000000
(即 ulimit -n 1000000
)。
TiDB Lightning 导入速度太慢
TiDB Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数据文件,如果速度远慢于这个数值就是有问题。导入的速度可以检查日志提及 restore chunk … takes
的记录,或者观察 Grafana 的监控信息。
导入速度太慢一般有几个原因:
原因 1:region-concurrency
设定太高,线程间争用资源反而减低了效率。
- 从日志的开头搜寻
region-concurrency
能知道 TiDB Lightning 读到的参数是多少。 - 如果 TiDB Lightning 与其他服务(如 TiKV Importer)共用一台服务器,必需手动将
region-concurrency
设为该服务器 CPU 数量的 75%。 - 如果 CPU 设有限额(例如从 Kubernetes 指定的上限),TiDB Lightning 可能无法自动判断出来,此时亦需要手动调整
region-concurrency
。
原因 2:表结构太复杂。
每条索引都会额外增加键值对。如果有 N 条索引,实际导入的大小就差不多是 Dumpling 文件的 N+1 倍。如果索引不太重要,可以考虑先从 schema 去掉,待导入完成后再使用 CREATE INDEX
加回去。
原因 3: 单个文件过大。
把源数据分割为单个大小约为 256 MB 的多个文件时,TiDB Lightning 会并行处理数据,达到最佳效果。如果导入的单个文件过大,TiDB Lightning 可能无响应。
如果源数据是 CSV 格式文件,并且所有的 CSV 文件内都不存在包含字符换行符的字段 (U+000A 及 U+000D),则可以启用 strict-format
,TiDB Lightning 会自动分割大文件。
[mydumper]
strict-format = true
原因 4:TiDB Lightning 版本太旧。
试试最新的版本吧!可能会有改善。
checksum failed: checksum mismatched remote vs local
原因:本地数据源跟目标数据库某个表的校验和不一致。这通常有更深层的原因,可以通过检查日志中包含 checksum mismatched
的行进一步定位。
包含 checksum mismatched
的行中有 total_kvs: x vs y
的信息,x
表示导入集群在完成导入后计算出的键值对(KV pairs)数目,y
表示本地数据源产生的键值对数目。
x
大,即导入集群键值对更多:- 可能这张表在导入前已有数据,因此影响了数据校验。这也包括 TiDB Lightning 之前失败停机过,但没有正确重启。
y
大,即本地数据源键值对更多:- 如果目标数据库的校验和全是 0,表示没有发生任何导入,有可能是集群太忙无法接收任何数据。
- 可能导出数据中包含重复数据,例如唯一键和主键 (UNIQUE and PRIMARY KEYs) 有重复的值、下游表结构为大小写不敏感而数据为大小写敏感。
- 其他情况
- 如果数据源是由机器生成而不是从 Dumpling 备份的,需确保数据符合表的限制,例如自增 (AUTO_INCREMENT) 的列需要为正数,不能为 0。
解决办法:
使用
tidb-lightning-ctl
把出错的表删除,检查表结构与数据,重启 TiDB Lightning 重新导入此前出错的表。tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all
把断点存放在外部数据库(修改
[checkpoint] dsn
),减轻目标集群压力。参考如何正确重启 TiDB Lightning中的解决办法。
Checkpoint for … has invalid status:
(错误码)
原因:断点续传已启用。TiDB Lightning 或 TiKV Importer 之前发生了异常退出。为了防止数据意外损坏,TiDB Lightning 在错误解决以前不会启动。
错误码是小于 25 的整数,可能的取值是 0、3、6、9、12、14、15、17、18、20、21。整数越大,表示异常退出所发生的步骤在导入流程中越晚。
解决办法:
如果错误原因是非法数据源,使用 tidb-lightning-ctl
删除已导入数据,并重启 TiDB Lightning。
tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all
其他解决方法请参考断点续传的控制。
ResourceTemporarilyUnavailable("Too many open engines …: …")
原因:并行打开的引擎文件 (engine files) 超出 tikv-importer
里的限制。这可能由配置错误引起。即使配置没问题,如果 tidb-lightning
曾经异常退出,也有可能令引擎文件残留在打开的状态,占据可用的数量。
解决办法:
提高
tikv-importer.toml
内max-open-engines
的值。这个设置主要由内存决定,计算公式为:最大内存使用量 ≈
max-open-engines
×write-buffer-size
×max-write-buffer-number
降低
table-concurrency
+index-concurrency
,使之低于max-open-engines
。重启
tikv-importer
来强制移除所有引擎文件 (默认值为./data.import/
)。这样也会丢弃导入了一半的表,所以启动 TiDB Lightning 前必须清除过期的断点记录:tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all
cannot guess encoding for input file, please convert to UTF-8 manually
原因:TiDB Lightning 只支持 UTF-8 和 GB-18030 编码的表架构。此错误代表数据源不是这里任一个编码。也有可能是文件中混合了不同的编码,例如,因为在不同的环境运行过 ALTER TABLE
,使表架构同时出现 UTF-8 和 GB-18030 的字符。
解决办法:
- 编辑数据源,保存为纯 UTF-8 或 GB-18030 的文件。
- 手动在目标数量库创建所有的表,然后设置
[mydumper] no-schema = true
跳过创建表的步骤。 - 设置
[mydumper] character-set = "binary"
跳过这个检查。但是这样可能使数据库出现乱码。
[sql2kv] sql encode error = [types:1292]invalid time format: '{1970 1 1 …}'
原因: 一个 timestamp
类型的时间戳记录了不存在的时间值。时间值不存在是由于夏时制切换或超出支持的范围(1970 年 1 月 1 日至 2038 年 1 月 19 日)。
解决办法:
确保 TiDB Lightning 与数据源时区一致。
手动部署的话,通过设定
$TZ
环境变量强制时区设定。强制使用 Asia/Shanghai 时区:
TZ='Asia/Shanghai' bin/tidb-lightning -config tidb-lightning.toml
导出数据时,必须加上
--skip-tz-utc
选项。确保整个集群使用的是同一最新版本的
tzdata
(2018i 或更高版本)。如果你使用的是 CentOS 机器,你可以运行
yum info tzdata
命令查看tzdata
的版本及是否有更新。然后运行yum upgrade tzdata
命令升级tzdata
。
[Error 8025: entry too large, the max entry size is 6291456]
原因:TiDB Lightning 生成的单行 KV 超过了 TiDB 的限制。
解决办法:
目前无法绕过 TiDB 的限制,只能忽略这张表,确保其它表顺利导入。
switch-mode 时遇到 rpc error: code = Unimplemented ...
原因:集群中有不支持 switch-mode 的节点。目前已知的组件中,4.0.0-rc.2 之前的 TiFlash 不支持 switch-mode 操作。
解决办法:
- 如果集群中有 TiFlash 节点,可以将集群更新到 4.0.0-rc.2 或更新版本。
- 如果不方便升级,可以临时禁用 TiFlash。
tidb lightning encountered error: TiDB version too old, expected '>=4.0.0', found '3.0.18'
TiDB Lightning Local-backend 只支持导入到 v4.0.0 及以上版本的 TiDB 集群。如果尝试使用 Local-backend 导入到 v2.x 或 v3.x 的集群,就会报以上错误。此时可以修改配置使用 Importer-backend 或 TiDB-backend 进行导入。
部分 nightly
版本的 TiDB 集群的版本可能类似 4.0.0-beta.2。这种版本的 TiDB Lightning 实际支持 Local-backend,如果使用 nightly
版本遇到该报错,可以通过设置配置 check-requirements = false
跳过版本检查。在设置此参数之前,请确保 TiDB Lightning 的配置支持对应的版本,否则无法保证导入成功。
restore table test.district failed: unknown columns in header [...]
出现该错误通常是因为 CSV 格式的数据文件不包含 header(第一行也是数据),因此需要在 TiDB Lightning 的配置文件中增加如下配置项:
[mydumper.csv]
header = false
- TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少?
- TiDB Lightning 支持导入多个库吗?
- TiDB Lightning 对下游数据库的账号权限要求是怎样的?
- TiDB Lightning 在导数据过程中某个表报错了,会影响其他表吗?进程会马上退出吗?
- 如何正确重启 TiDB Lightning?
- 如何校验导入的数据的正确性?
- TiDB Lightning 支持哪些格式的数据源?
- 我已经在下游创建好库和表了,TiDB Lightning 可以忽略建库建表操作吗?
- 有些不合法的数据,能否通过关掉严格 SQL 模式 (Strict SQL Mode) 来导入?
- 可以启用一个 tikv-importer,同时有多个 tidb-lightning 进程导入数据吗?
- 如何正确结束 tikv-importer 进程?
- 如何正确结束 tidb-lightning 进程?
- tidb-lightning 在服务器上运行,进程莫名其妙地退出了,是怎么回事呢?
- 为什么用过 TiDB Lightning 之后,TiDB 集群变得又慢又耗 CPU?
- TiDB Lightning 可以使用千兆网卡吗?
- 为什么 TiDB Lightning 需要在 TiKV 集群预留这么多空间?
- TiDB Lightning 使用过程中是否可以重启 TiKV Importer?
- 如何清除所有与 TiDB Lightning 相关的中间数据?
- TiDB Lightning 报错 could not find first pair, this shouldn't happen
- TiDB Lightning 导入速度太慢
- checksum failed: checksum mismatched remote vs local
- Checkpoint for … has invalid status:(错误码)
- ResourceTemporarilyUnavailable("Too many open engines …: …")
- cannot guess encoding for input file, please convert to UTF-8 manually
- sql2kv sql encode error = types:1292invalid time format: '{1970 1 1 …}'
- [Error 8025: entry too large, the max entry size is 6291456]
- switch-mode 时遇到 rpc error: code = Unimplemented ...
- tidb lightning encountered error: TiDB version too old, expected '>=4.0.0', found '3.0.18'
- restore table test.district failed: unknown columns in header [...]