TiDB Lightning 配置参数

你可以使用配置文件或命令行配置 TiDB Lightning。本文主要介绍 TiDB Lightning 的全局配置、任务配置和 TiKV Importer 的配置，以及如何使用命令行进行参数配置。

配置文件

TiDB Lightning 的配置文件分为“全局”和“任务”两种类别，二者在结构上兼容。只有当服务器模式开启时，全局配置和任务配置才会有区别；默认情况下，服务器模式为禁用状态，此时 TiDB Lightning 只会执行一个任务，且全局和任务配置使用同一配置文件。

TiDB Lightning 全局配置

1. ### tidb-lightning 全局配置

3. [lightning]
4. # 用于进度展示 web 界面、拉取 Prometheus 监控项、暴露调试数据和提交导入任务（服务器模式下）的 HTTP 端口。设置为 0 时为禁用状态。
5. status-addr = ':8289'

7. # 服务器模式，默认值为 false，命令启动后会开始导入任务。如果改为 true，命令启动后会等待用户在 web 界面上提交任务。
8. # 详情参见“TiDB Lightning web 界面”文档
9. server-mode = false

11. # 日志
12. level = "info"
13. file = "tidb-lightning.log"
14. max-size = 128 # MB
15. max-days = 28
16. max-backups = 14

TiDB Lightning 任务配置

1. ### tidb-lightning 任务配置

3. [lightning]
4. # 启动之前检查集群是否满足最低需求。
5. # check-requirements = true

7. # 引擎文件的最大并行数。
8. # 每张表被切分成一个用于存储索引的“索引引擎”和若干存储行数据的“数据引擎”。
9. # 这两项设置控制两种引擎文件的最大并发数。
10. # 这两项设置的值会影响 tikv-importer 的内存和磁盘用量。
11. # 两项数值之和不能超过 tikv-importer 的 max-open-engines 的设定。
12. index-concurrency = 2
13. table-concurrency = 6

15. # 数据的并发数。默认与逻辑 CPU 的数量相同。
16. # 混合部署的情况下可以将其大小配置为逻辑 CPU 数的 75%，以限制 CPU 的使用。
17. # region-concurrency =

19. # I/O 最大并发数。I/O 并发量太高时，会因硬盘内部缓存频繁被刷新
20. # 而增加 I/O 等待时间，导致缓存未命中和读取速度降低。
21. # 对于不同的存储介质，此参数可能需要调整以达到最佳效率。
22. io-concurrency = 5

24. # TiDB Lightning 停止迁移任务之前能容忍的最大非严重 (non-fatal errors) 错误数。
25. # 在忽略非严重错误所在的行数据之后，迁移任务可以继续执行。
26. # 将该值设置为 N，表示 TiDB Lightning 会在遇到第 (N+1) 个错误时停止迁移任务。
27. # 被忽略的行会被记录到位于目标集群的 "task info" 数据库中。最大错误数可以通过下面参数配置。
28. max-error = 0
29. # 参数 task-info-schema-name 指定用于存储 TiDB Lightning 执行结果的数据库。
30. # 要关闭该功能，需要将该值设置为空字符串。
31. # task-info-schema-name = 'lightning_task_info'

33. # 在并行导入模式下，在目标集群保存各个 TiDB Lightning 实例元信息的 schema 名字，默认为 "lightning_metadata"。
34. # 如果未开启并行导入模式，无须设置此配置项。
35. # **注意：**
36. # - 对于参与同一批并行导入的每个 TiDB Lightning 实例，该参数设置的值必须相同，否则将无法确保导入数据的正确性。
37. # - 如果开启并行导入模式，需要确保导入使用的用户（对于 tidb.user 配置项）有权限创建和访问此配置对应的库。
38. # - TiDB Lightning 在导入完成后会删除此 schema，因此不要使用已存在的库名配置该参数。
39. meta-schema-name = "lightning_metadata"

41. [security]
42. # 指定集群中用于 TLS 连接的证书和密钥。
43. # CA 的公钥证书。如果留空，则禁用 TLS。
44. # ca-path = "/path/to/ca.pem"
45. # 此服务的公钥证书。
46. # cert-path = "/path/to/lightning.pem"
47. # 该服务的密钥。
48. # key-path = "/path/to/lightning.key"

50. [checkpoint]
51. # 是否启用断点续传。
52. # 导入数据时，TiDB Lightning 会记录当前表导入的进度。
53. # 所以即使 TiDB Lightning 或其他组件异常退出，在重启时也可以避免重复再导入已完成的数据。
54. enable = true
55. # 存储断点的数据库名称。
56. schema = "tidb_lightning_checkpoint"
57. # 存储断点的方式。
58. #  - file：存放在本地文件系统。
59. #  - mysql：存放在兼容 MySQL 的数据库服务器。
60. driver = "file"

62. # dsn 是数据源名称 (data source name)，表示断点的存放位置。
63. # 若 driver = "file"，则 dsn 为断点信息存放的文件路径。
64. #若不设置该路径，则默认存储路径为“/tmp/CHECKPOINT_SCHEMA.pb”。
65. # 若 driver = "mysql"，则 dsn 为“用户:密码@tcp(地址:端口)/”格式的 URL。
66. # 若不设置该 URL，则默认会使用 [tidb] 部分指定的 TiDB 服务器来存储断点。
67. # 为减少目标 TiDB 集群的压力，建议指定另一台兼容 MySQL 的数据库服务器来存储断点。
68. # dsn = "/tmp/tidb_lightning_checkpoint.pb"

70. # 所有数据导入成功后是否保留断点。设置为 false 时为删除断点。
71. # 保留断点有利于进行调试，但会泄漏关于数据源的元数据。
72. # keep-after-success = false

74. [tikv-importer]
75. # "local"：默认使用该模式，适用于 TB 级以上大数据量，但导入期间下游 TiDB 无法对外提供服务。
76. # "tidb"：TB 级以下数据量也可以采用 "tidb" 后端模式，下游 TiDB 可正常提供服务。
77. # backend = "local"
78. # 是否允许向已存在数据的表导入数据。默认值为 false。
79. # 当使用并行导入模式时，由于多个 TiDB Lightning 实例同时导入一张表，因此此开关必须设置为 true。
80. # incremental-import = false
81. # 当后端是 “importer” 时，tikv-importer 的监听地址（需改为实际地址）。
82. addr = "172.16.31.10:8287"
83. # 当后端是 “tidb” 时，插入重复数据时执行的操作。
84. # - replace：新数据替代已有数据
85. # - ignore：保留已有数据，忽略新数据
86. # - error：中止导入并报错
87. # on-duplicate = "replace"
88. # 当后端模式为 'local' 时，设置是否检测和解决重复的记录（唯一键冲突）。
89. # 目前支持三种解决方法：
90. #  - record: 仅将重复记录添加到目的 TiDB 中的 `lightning_task_info.conflict_error_v1` 表中。注意，该方法要求目的 TiKV 的版本为 v5.2.0 或更新版本。如果版本过低，则会启用下面的 'none' 模式。
91. #  - none: 不检测重复记录。该模式是三种模式中性能最佳的，但是可能会导致目的 TiDB 中出现数据不一致的情况。
92. #  - remove: 记录所有的重复记录，和 'record' 模式相似。但是会删除所有的重复记录，以确保目的 TiDB 中的数据状态保持一致。
93. # duplicate-resolution = 'none'
94. # 当后端是 “local” 时，一次请求中发送的 KV 数量。
95. # send-kv-pairs = 32768
96. # 当后端是 “local” 时，本地进行 KV 排序的路径。如果磁盘性能较低（如使用机械盘），建议设置成与 `data-source-dir` 不同的磁盘，这样可有效提升导入性能。
97. # sorted-kv-dir = ""
98. # 当后端是 “local” 时，TiKV 写入 KV 数据的并发度。当 TiDB Lightning 和 TiKV 直接网络传输速度超过万兆的时候，可以适当增加这个值。
99. # range-concurrency = 16

101. [mydumper]
102. # 设置文件读取的区块大小，确保该值比数据源的最长字符串长。
103. read-block-size = "64KiB" # 默认值

105. # 引擎文件需按顺序导入。由于并行处理，多个数据引擎几乎在同时被导入，
106. # 这样形成的处理队列会造成资源浪费。因此，为了合理分配资源，TiDB Lightning
107. # 稍微增大了前几个区块的大小。该参数也决定了比例系数，即在完全并发下
108. # “导入”和“写入”过程的持续时间比。这个值可以通过计算 1 GiB 大小的
109. # 单张表的（导入时长/写入时长）得到。在日志文件中可以看到精确的时间。
110. # 如果“导入”更快，区块大小的差异就会更小；比值为 0 时则说明区块大小一致。
111. # 取值范围为（0 <= batch-import-ratio < 1）。
112. batch-import-ratio = 0.75

114. # 本地源数据目录或外部存储 URL
115. data-source-dir = "/data/my_database"
116. # 如果 no-schema = true，那么 TiDB Lightning 假设目标 TiDB 集群上
117. # 已有表结构，并且不会执行 `CREATE TABLE` 语句。
118. no-schema = false
119. # 指定包含 `CREATE TABLE` 语句的表结构文件的字符集。只支持下列选项：
120. #  - utf8mb4：表结构文件必须使用 UTF-8 编码，否则会报错。
121. #  - gb18030：表结构文件必须使用 GB-18030 编码，否则会报错。
122. #  - auto：自动判断文件编码是 UTF-8 还是 GB-18030，两者皆非则会报错（默认）。
123. #  - binary：不尝试转换编码。
124. character-set = "auto"

126. # 指定源数据文件的字符集，Lightning 会在导入过程中将源文件从指定的字符集转换为 UTF-8 编码。
127. # 该配置项目前仅用于指定 CSV 文件的字符集。只支持下列选项：
128. #  - utf8mb4：源数据文件使用 UTF-8 编码。
129. #  - GB18030：源数据文件使用 GB-18030 编码。
130. #  - GBK：源数据文件使用 GBK 编码（GBK 编码是对 GB-2312 字符集的拓展，也被称为 Code Page 936）。
131. #  - binary：不尝试转换编码（默认）。
132. # 留空此配置将默认使用 "binary"，即不尝试转换编码。
133. # 需要注意的是，Lightning 不会对源数据文件的字符集做假定，仅会根据此配置对数据进行转码并导入。
134. # 如果字符集设置与源数据文件的实际编码不符，可能会导致导入失败、导入缺失或导入数据乱码。
135. data-character-set = "binary"
136. # 指定在源数据文件的字符集转换过程中，出现不兼容字符时的替换字符。
137. # 此项不可与字段分隔符、引用界定符和换行符号重复。
138. # 默认值为 "\uFFFD"，即 UTF-8 编码中的 "error" Rune 或 Unicode replacement character。
139. # 改变默认值可能会导致潜在的源数据文件解析性能下降。
140. data-invalid-char-replace = "\uFFFD"

142. # “严格”格式的导入数据可加快处理速度。
143. # strict-format = true 要求：
144. # 在 CSV 文件的所有记录中，每条数据记录的值不可包含字符换行符（U+000A 和 U+000D，即 \r 和 \n）
145. # 甚至被引号包裹的字符换行符都不可包含，即换行符只可用来分隔行。
146. # 导入数据源为严格格式时，TiDB Lightning 会快速定位大文件的分割位置进行并行处理。
147. # 但是如果输入数据为非严格格式，可能会将一条完整的数据分割成两部分，导致结果出错。
148. # 为保证数据安全而非追求处理速度，默认值为 false。
149. strict-format = false

151. # 如果 strict-format = true，TiDB Lightning 会将 CSV 大文件分割为多个文件块进行并行处理。max-region-size 是分割后每个文件块的最大大小。
152. # max-region-size = "256MiB" # 默认值

154. # 只导入与该通配符规则相匹配的表。详情见相应章节。
155. filter = ['*.*', '!mysql.*', '!sys.*', '!INFORMATION_SCHEMA.*', '!PERFORMANCE_SCHEMA.*', '!METRICS_SCHEMA.*', '!INSPECTION_SCHEMA.*']

157. # 配置 CSV 文件的解析方式。
158. [mydumper.csv]
159. # 字段分隔符，支持一个或多个字符，默认值为 ','。
160. separator = ','
161. # 引用定界符，设置为空表示字符串未加引号。
162. delimiter = '"'
163. # 行尾定界字符，支持一个或多个字符。设置为空（默认值）表示 "\n"（换行）和 "\r\n" （回车+换行），均表示行尾。
164. terminator = ""
165. # CSV 文件是否包含表头。
166. # 如果 header = true，将跳过首行。
167. header = true
168. # CSV 文件是否包含 NULL。
169. # 如果 not-null = true，CSV 所有列都不能解析为 NULL。
170. not-null = false
171. # 如果 not-null = false（即 CSV 可以包含 NULL），
172. # 为以下值的字段将会被解析为 NULL。
173. null = '\N'
174. # 是否对字段内“\“进行转义
175. backslash-escape = true
176. # 如果有行以分隔符结尾，删除尾部分隔符。
177. trim-last-separator = false

179. # [[mydumper.files]]
180. # 解析 AWS Aurora parquet 文件所需的表达式
181. # pattern = '(?i)^(?:[^/]*/)*([a-z0-9_]+)\.([a-z0-9_]+)/(?:[^/]*/)*(?:[a-z0-9\-_.]+\.(parquet))$'
182. # schema = '$1'
183. # table = '$2'
184. # type = '$3'

186. [tidb]
187. # 目标集群的信息。tidb-server 的地址，填一个即可。
188. host = "172.16.31.1"
189. port = 4000
190. user = "root"
191. password = ""
192. # 表结构信息从 TiDB 的“status-port”获取。
193. status-port = 10080
194. # pd-server 的地址，填一个即可。
195. pd-addr = "172.16.31.4:2379"
196. # tidb-lightning 引用了 TiDB 库，并生成产生一些日志。
197. # 设置 TiDB 库的日志等级。
198. log-level = "error"

200. # 设置 TiDB 会话变量，提升 Checksum 和 Analyze 的速度。
201. # 各参数定义可参阅”控制 Analyze 并发度“文档
202. build-stats-concurrency = 20
203. distsql-scan-concurrency = 100
204. index-serial-scan-concurrency = 20
205. checksum-table-concurrency = 16

207. # 解析和执行 SQL 语句的默认 SQL 模式。
208. sql-mode = "ONLY_FULL_GROUP_BY,NO_ENGINE_SUBSTITUTION"
209. # `max-allowed-packet` 设置数据库连接允许的最大数据包大小，
210. # 对应于系统参数中的 `max_allowed_packet`。 如果设置为 0，
211. # 会使用下游数据库 global 级别的 `max_allowed_packet`。
212. max-allowed-packet = 67_108_864

214. # SQL 连接是否使用 TLS。可选值为：
215. #  * ""            - 如果填充了 [tidb.security] 部分，则强制使用 TLS（与 "cluster" 情况相同），否则与 "false" 情况相同
216. #  * "false"       - 禁用 TLS
217. #  * "cluster"     - 强制使用 TLS 并使用 [tidb.security] 部分中指定的 CA 验证服务器的证书
218. #  * "skip-verify" - 强制使用 TLS，但不验证服务器的证书（不安全！）
219. #  * "preferred"   - 与 "skip-verify" 相同，但是如果服务器不支持 TLS，则会退回到未加密的连接
220. # tls = ""
221. # 指定证书和密钥用于 TLS 连接 MySQL。
222. # 默认为 [security] 部分的副本。
223. # [tidb.security]
224. # CA 的公钥证书。设置为空字符串可禁用 SQL 的 TLS。
225. # ca-path = "/path/to/ca.pem"
226. # 该服务的公钥证书。默认为 `security.cert-path` 的副本
227. # cert-path = "/path/to/lightning.pem"
228. # 此服务的私钥。默认为 `security.key-path` 的副本
229. # key-path = "/path/to/lightning.key"

231. # 对于 Local Backend 模式，数据导入完成后，TiDB Lightning 可以自动执行 Checksum 和 Analyze 操作。
232. # 在生产环境中，建议总是开启 Checksum 和 Analyze。
233. # 执行的顺序为：Checksum -> Analyze。
234. # 注意：对于 TiDB Backend, 无须执行这两个阶段，因此在实际运行时总是会直接跳过。
235. [post-restore]
236. # 配置是否在导入完成后对每一个表执行 `ADMIN CHECKSUM TABLE <table>` 操作来验证数据的完整性。
237. # 可选的配置项：
238. # - "required"（默认）。在导入完成后执行 CHECKSUM 检查，如果 CHECKSUM 检查失败，则会报错退出。
239. # - "optional"。在导入完成后执行 CHECKSUM 检查，如果报错，会输出一条 WARN 日志并忽略错误。
240. # - "off"。导入结束后不执行 CHECKSUM 检查。
241. # 默认值为 "required"。从 v4.0.8 开始，checksum 的默认值由此前的 "true" 改为 "required"。
242. #
243. # 注意：
244. # 1. Checksum 对比失败通常表示导入异常（数据丢失或数据不一致），因此建议总是开启 Checksum。
245. # 2. 考虑到与旧版本的兼容性，依然可以在本配置项设置 `true` 和 `false` 两个布尔值，其效果与 `required` 和 `off` 相同。
246. checksum = "required"
247. # 配置是否在 CHECKSUM 结束后对所有表逐个执行 `ANALYZE TABLE <table>` 操作。
248. # 此配置的可选配置项与 `checksum` 相同，但默认值为 "optional"。
249. analyze = "optional"

252. # 设置周期性后台操作。
253. # 支持的单位：h（时）、m（分）、s（秒）。
254. [cron]
255. # TiDB Lightning 自动刷新导入模式状态的持续时间，该值应小于 TiKV 对应的设定值。
256. switch-mode = "5m"
257. # 在日志中打印导入进度的持续时间。
258. log-progress = "5m"

TiKV Importer 配置参数

1. # TiKV Importer 配置文件模版

3. # 日志文件
4. log-file = "tikv-importer.log"
5. # 日志等级：trace, debug, info, warn, error 和 off
6. log-level = "info"

8. # 状态服务器的监听地址。
9. # Prometheus 可以从这个地址抓取监控指标。
10. status-server-address = "0.0.0.0:8286"

12. [server]
13. # tikv-importer 的监听地址，tidb-lightning 需要连到这个地址进行数据写入。
14. addr = "0.0.0.0:8287"
15. # gRPC 服务器的线程池大小。
16. grpc-concurrency = 16

18. [metric]
19. # 当使用 Prometheus Pushgateway 时会涉及相关设置。通常可以通过 Prometheus 从 状态服务器地址中抓取指标。
20. # 给 Prometheus 客户端推送的 job 名称。
21. job = "tikv-importer"
22. # 给 Prometheus 客户端推送的间隔。
23. interval = "15s"
24. # Prometheus Pushgateway 的地址。
25. address = ""

27. [rocksdb]
28. # background job 的最大并发数。
29. max-background-jobs = 32

31. [rocksdb.defaultcf]
32. # 数据在刷新到硬盘前能存于内存的容量上限。
33. write-buffer-size = "1GB"
34. # 内存中写缓冲器的最大数量。
35. max-write-buffer-number = 8

37. # 各个压缩层级使用的算法。
38. # 第 0 层的算法用于压缩 KV 数据。
39. # 第 6 层的算法用于压缩 SST 文件。
40. # 第 1 至 5 层的算法目前尚未使用。
41. compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"]

43. [rocksdb.writecf]
44. # 同上
45. compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"]

47. [security]
48. # TLS 证书的路径。空字符串表示禁用安全连接。
49. # ca-path = ""
50. # cert-path = ""
51. # key-path = ""

53. [import]
54. # 存储引擎文件的文件夹路径
55. import-dir = "/mnt/ssd/data.import/"
56. # 处理 RPC 请求的线程数
57. num-threads = 16
58. # 导入 job 的并发数。
59. num-import-jobs = 24
60. # 预处理 Region 最长时间。
61. # max-prepare-duration = "5m"
62. # 把要导入的数据切分为这个大小的 Region。
63. #region-split-size = "512MB"
64. # 设置 stream-channel-window 的大小。
65. # channel 满了之后 stream 会处于阻塞状态。
66. # stream-channel-window = 128
67. # 同时打开引擎文档的最大数量。
68. max-open-engines = 8
69. # Importer 上传至 TiKV 的最大速度（字节/秒）。
70. # upload-speed-limit = "512MB"
71. # 目标存储可用空间比率（store_available_space/store_capacity）的最小值。
72. # 如果目标存储空间的可用比率低于该值，Importer 将会暂停上传 SST
73. # 来为 PD 提供足够时间进行 Regions 负载均衡。
74. min-available-ratio = 0.05

命令行参数

tidb-lightning

使用 tidb-lightning 可以对下列参数进行配置：

如果同时对命令行参数和配置文件中的对应参数进行更改，命令行参数将优先生效。例如，在 cfg.toml 文件中，不管对日志等级做出什么修改，运行 ./tidb-lightning -L debug --config cfg.toml 命令总是将日志级别设置为 “debug”。

tidb-lightning-ctl

使用 tidb-lightning-ctl 可以对下列参数进行配置：

tablename 必须是`db`.`tbl` 中的限定表名（包括反引号），或关键词 all。

此外，上表中所有 tidb-lightning 的参数也适用于 tidb-lightning-ctl。

tikv-importer

使用 tikv-importer 可以对下列参数进行配置：