TiDB Lightning 后端

    TiDB Lightning 的后端决定 tidb-lightning 组件将如何把将数据导入到目标集群中。目前，TiDB Lightning 支持以下后端：

    以上几种后端导入数据的区别如下：

    • Local-backend：tidb-lightning 先将数据编码成键值对并排序存储在本地临时目录，然后将这些键值对以 SST 文件的形式上传到各个 TiKV 节点，然后由 TiKV 将这些 SST 文件 Ingest 到集群中。和 Importer-backend 原理相同，不过不依赖额外的 tikv-importer 组件。

    • Importer-backend：tidb-lightning 先将 SQL 或 CSV 数据编码成键值对，由 tikv-importer 对写入的键值对进行排序，然后把这些键值对 Ingest 到 TiKV 节点中。

    • TiDB-backend：tidb-lightning 先将数据编码成 INSERT 语句，然后直接在 TiDB 节点上运行这些 SQL 语句进行数据导入。

    • 如果导入的目标集群为 v4.0 或以上版本，请优先考虑使用 Local-backend 模式。Local-backend 部署更简单并且性能也较其他两个模式更高
    • 如果目标集群为 v3.x 或以下，建议使用 Importer-backend 模式
    • 如果需要导入的集群为生产环境线上集群，或需要导入的表中已包含有数据，则最好使用 TiDB-backend 模式

    自 TiDB 4.0.3 版本起，TiDB Lightning 引入了 Local-backend 特性。该特性支持导入数据到 v4.0.0 以上的 TiDB 集群。

    TiDB Lightning Local-backend 模式的部署方法见 TiDB Lightning 部署与执行。

    使用 TiDB-backend 时，你无需部署 tikv-importer。与相比，部署 TiDB-backend 时有如下不同：

    • 可以跳过所有涉及 tikv-importer 的步骤。
    • 必须更改相应配置申明使用的是 TiDB-backend。

    硬件需求

    • 16 逻辑核 CPU
    • 足够储存整个数据源的 SSD 硬盘，读取速度越快越好
    • 千兆网卡

    手动部署

    手动部署时，你无需下载和配置 tikv-importer，TiDB Lightning 可在此下载。

    在运行 tidb-lightning 之前，在配置文件中加上如下几行：

    或者在用命令行启动 tidb-lightning 时，传入参数 --backend tidb。

    配置说明与示例

    1. # tidb-lightning 任务配置
    3. [lightning]
    4. # 启动之前检查集群是否满足最低需求
    5. check-requirements = true
    7. # 每张表被切分成一个用于存储索引的“索引引擎”和若干存储行数据的“数据引擎”
    8. # 这两项设置控制两种引擎文件的最大并发数
    9. # 控制同时允许导入的最大表数量，对于 TiDB-backend，默认值为 CPU 数
    10. index-concurrency = 40
    12. # 控制同时允许导入的最大“数据引擎”数，默认值为 CPU 数，本配置应大于或等于 index-concurrency
    13. table-concurrency = 40
    15. # 执行 SQL 语句的并发数。默认与逻辑 CPU 的数量相同
    16. # TiDB-backend 的瓶颈通常不在 CPU, 可以根据下游集群的实际负载调大此配置以优化写入速度
    17. # 在调整此配置时，建议将 index-concurrency 和 table-concurrency 也调整成相同的值
    18. region-concurrency = 40
    20. # 日志相关的配置
    21. # 输出日志级别
    22. level = "info"
    24. # 日志输出的文件。如果为空（默认），则会输出至 /tmp/lightning.log.{timestamp}；如果希望输出至系统标准输出，请设置为 "-"
    25. # file = "tidb-lightning.log"
    27. [checkpoint]
    28. # 启用断点续传
    29. # 导入数据时，TiDB Lightning 会记录当前表导入的进度
    30. # 若 TiDB Lightning 或其他组件异常退出，在重启时也可以避免重复再导入已完成的数据
    31. enable = true
    33. # 存储断点的方式
    34. #  - file（默认）：存放在本地文件系统（要求 v2.1.1 或以上）
    35. #  - mysql：存放在兼容 MySQL 的数据库服务器
    36. driver = "file"
    38. # 存储断点的数据库名称
    39. # 仅在 driver = "mysql" 时生效
    40. # schema = "tidb_lightning_checkpoint"
    42. # 断点的存放位置
    43. #
    44. # 若 driver = "file"，此参数为断点信息存放的文件路径
    45. # 如果不设置该参数则默认为 `/tmp/CHECKPOINT_SCHEMA.pb`
    46. #
    47. # 若 driver = "mysql"，此参数为数据库连接参数 (DSN)，格式为“用户:密码@tcp(地址:端口)/”
    48. # 默认会重用 [tidb] 设置目标数据库来存储断点
    49. # 为避免加重目标集群的压力，建议另外使用一个兼容 MySQL 的数据库服务器
    50. # dsn = "/tmp/tidb_lightning_checkpoint.pb"
    52. # 导入成功后是否保留断点。默认为删除
    53. # keep-after-success = false
    55. [tikv-importer]
    56. # 后端模式，对于 TiDB-backend 请设置为 “tidb”
    57. backend = "tidb"
    59. # 对于插入重复数据时执行的操作：
    60. # - replace：新数据替代已有数据
    61. # - ignore：保留已有数据，忽略新数据
    62. # - error：中止导入并报错
    63. # on-duplicate = "replace"
    65. [mydumper]
    66. # 设置文件读取的区块大小(默认为 64 KiB)，确保该值比数据源的最长字符串长。
    67. # read-block-size = "64KiB" 
    69. # （源数据文件）单个导入区块大小的最小值（默认为 100 GiB）。
    71. # batch-size = "100GiB"
    73. # 本地源数据目录或外部存储 URL
    74. data-source-dir = "/data/my_database"
    76. # “严格”格式的导入数据可加快处理速度。
    77. # strict-format = true 要求：
    78. # 在 CSV 文件的所有记录中，每条数据记录的值不可包含字符换行符（U+000A 和 U+000D，即 \r 和 \n）
    79. # 甚至被引号包裹的字符换行符都不可包含，即换行符只可用来分隔行。
    80. # 导入数据源为严格格式时，TiDB Lightning 会快速定位大文件的分割位置进行并行处理。
    81. # 但是如果输入数据为非严格格式，可能会将一条完整的数据分割成两部分，导致结果出错。
    82. # 为保证数据安全而非追求处理速度，默认值为 false。
    83. # strict-format = false
    85. # 如果 strict-format = true，TiDB Lightning 会将 CSV 大文件分割为多个文件块进行并行处理。max-region-size 是分割后每个文件块的最大大小。
    86. # max-region-size = "256MiB" # Byte（默认是 256 MiB）
    88. # 只导入与该通配符规则相匹配的表，默认会过滤掉系统表。详情见表库过滤章节。
    89. # filter = ['*.*', '!mysql.*', '!sys.*', '!INFORMATION_SCHEMA.*', '!PERFORMANCE_SCHEMA.*', '!METRICS_SCHEMA.*', '!INSPECTION_SCHEMA.*']
    91. # 配置 CSV 文件的解析方式（如果源文件中不包含 CSV 文件可不设置此项）。
    92. [mydumper.csv]
    93. # 字段分隔符，应为单个 ASCII 字符。
    94. separator = ','
    96. # 引用定界符，可为单个 ASCII 字符或空字符串。
    97. delimiter = '"'
    99. # CSV 文件是否包含表头。
    100. # 如果 header = true，将跳过首行。
    101. header = true
    103. # CSV 文件是否包含 NULL。
    104. # 如果 not-null = true，CSV 所有列都不能解析为 NULL。
    105. not-null = false
    107. # 如果 not-null = false（即 CSV 可以包含 NULL），
    108. # 为以下值的字段将会被解析为 NULL。
    109. null = '\N'
    111. # 是否对字段内“\“进行转义
    112. backslash-escape = true
    114. # 如果有行以分隔符结尾，删除尾部分隔符。
    115. trim-last-separator = false
    117. [tidb]
    118. # 目标集群的信息。tidb-server 的地址，填一个即可。
    119. host = "172.16.31.1"
    120. port = 4000
    121. user = "root"
    122. password = ""
    124. # 解析和执行 SQL 语句的默认 SQL 模式。
    125. # sql-mode = "ONLY_FULL_GROUP_BY,NO_ENGINE_SUBSTITUTION"
    127. # SQL 连接是否使用 TLS。可选值为：
    128. #  * ""            - 如果填充了 [tidb.security] 部分，则强制使用 TLS（与 "cluster" 情况相同），否则与 "false" 情况相同
    129. #  * "false"       - 禁用 TLS
    130. #  * "cluster"     - 强制使用 TLS, 并使用 [tidb.security] 部分中指定的 CA 验证服务器的证书
    131. #  * "skip-verify" - 强制使用 TLS, 但不验证服务器的证书（不安全！）
    132. #  * "preferred"   - 与 "skip-verify" 相同，但是如果服务器不支持 TLS，则会退回到未加密的连接
    133. tls = ""
    135. # 指定证书和密钥用于 TLS 连接 MySQL。
    136. # [tidb.security]
    137. # CA 的公钥证书。设置为空字符串可禁用 SQL 的 TLS。
    138. # ca-path = "/path/to/ca.pem"
    140. # 该服务的公钥证书。默认为 `security.cert-path` 的副本
    141. # cert-path = "/path/to/lightning.pem"
    143. # 此服务的私钥。默认为 `security.key-path` 的副本
    144. # key-path = "/path/to/lightning.key"
    146. # 设置周期性后台操作。
    147. # 支持的单位：h（时）、m（分）、s（秒）。
    148. [cron]
    150. # 在日志中打印导入进度的持续时间。
    151. log-progress = "5m"

    TiDB-backend 支持导入到已填充的表（非空表）。但是，新数据可能会与旧数据的唯一键冲突。你可以通过使用如下任务配置来控制遇到冲突时的默认行为：

    当需要将数据导入到 TiDB 集群时，TiDB Lightning TiDB-backend 可以完全取代 Loader。下表说明了如何将 Loader 的配置迁移到 中：

    本节介绍 TiDB Lightning 使用 Importer 模式的部署方式：手动部署。

    硬件需求

    tidb-lightning 和 tikv-importer 这两个组件皆为资源密集程序，建议各自单独部署。

    为了优化效能，建议硬件配置如下：

    • tidb-lightning

      • 32+ 逻辑核 CPU
      • 足够储存整个数据源的 SSD 硬盘，读取速度越快越好
      • 使用万兆网卡，带宽需 300 MB/s 以上
      • 运行过程默认会占满 CPU资源，因此建议将 tidb-lightning 部署到一台单独的机器上。条件不允许的情况下可以和其他组件（比如 tidb-server）部署在同一台机器上，然后通过配置 region-concurrency 限制 tidb-lightning 使用 CPU 资源。

    • tikv-importer

      • 32+ 逻辑核 CPU
      • 40 GB+ 内存
      • 1 TB+ SSD 硬盘，IOPS 越高越好（要求 ≥8000）
        • 硬盘必须大于最大的 N 个表的大小总和，其中 N = max(index-concurrency, table-concurrency)。
      • 使用万兆网卡，带宽需 300 MB/s 以上
      • 运行过程中 CPU、I/O 和网络带宽资源都可能占满，建议单独部署。

    手动部署 TiDB Lightning

    第 1 步：部署 TiDB 集群

    在开始数据导入之前，需先部署一套要进行导入的 TiDB 集群 (版本要求 2.0.9 以上)，建议使用最新版。部署方法可参考 使用 TiUP 部署 TiDB 集群。

    第 2 步：下载 TiDB Lightning 安装包

    在工具下载页面下载 TiDB Lightning 安装包（需选择与 TiDB 集群相同的版本）。

    第 3 步：启动 tikv-importer

    1. 从安装包上传 bin/tikv-importer。

    2. 配置 tikv-importer.toml。

      1.  # TiKV Importer 配置文件模版
      3.  # 日志文件。
      4.  log-file = "tikv-importer.log"
      5.  # 日志等级：trace、debug、info、warn、error、off。
      6.  log-level = "info"
      8.  # 状态服务器的监听地址。
      9.  status-server-address = "0.0.0.0:8286"
      11.  [server]
      12.  # tikv-importer 监听的地址，tidb-lightning 需要连到这个地址进行数据写入。
      13.  addr = "0.0.0.0:8287"
      15.  [metric]
      16.  # 给 Prometheus 客户端的推送任务名称。
      17.  job = "tikv-importer"
      18.  # 给 Prometheus 客户端的推送间隔。
      19.  interval = "15s"
      20.  # Prometheus Pushgateway 地址。
      21.  address = ""
      23.  [import]
      24.  # 存储引擎文档 (engine file) 的文件夹路径。
      25.  import-dir = "/mnt/ssd/data.import/"

      上面仅列出了 tikv-importer 的基本配置。完整配置请参考tikv-importer 配置说明。

    3. 运行 tikv-importer。

    第 4 步：启动 tidb-lightning

    1. 从安装包上传 bin/tidb-lightning 及 bin/tidb-lightning-ctl。

    2. 将数据源写入到同样的机器。

    3. 配置 tidb-lightning.toml。对于没有出现在下述模版中的配置，TiDB Lightning 给出配置错误的提醒并退出。

      1.  [lightning]
      3.  # 转换数据的并发数，默认为逻辑 CPU 数量，不需要配置。
      4.  # 混合部署的情况下可以配置为逻辑 CPU 的 75% 大小。
      5.  # region-concurrency =
      7.  # 日志
      8.  level = "info"
      9.  file = "tidb-lightning.log"
      11.  [tikv-importer]
      12.  # tikv-importer 的监听地址，需改成 tikv-importer 服务器的实际地址。
      13.  addr = "172.16.31.10:8287"
      15.  [mydumper]
      16.  # 源数据目录。
      17.  data-source-dir = "/data/my_database"
      19.  [tidb]
      20.  # 目标集群的信息。tidb-server 的监听地址，填一个即可。
      21.  host = "172.16.31.1"
      22.  port = 4000
      23.  user = "root"
      24.  password = ""
      25.  # 表架构信息在从 TiDB 的“状态端口”获取。
      26.  status-port = 10080

      上面仅列出了 tidb-lightning 的基本配置信息。完整配置信息请参考tidb-lightning 配置说明。