diff --git a/dev/TOC.md b/dev/TOC.md index 128a4b9fbbde..9fd27249eaf8 100644 --- a/dev/TOC.md +++ b/dev/TOC.md @@ -348,6 +348,7 @@ - [断点续传](/dev/reference/tools/tidb-lightning/checkpoints.md) - [表库过滤](/dev/reference/tools/tidb-lightning/table-filter.md) - [CSV 支持](/dev/reference/tools/tidb-lightning/csv.md) + - [TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md) - [Web 界面](/dev/reference/tools/tidb-lightning/web.md) - [监控告警](/dev/reference/tools/tidb-lightning/monitor.md) - [故障诊断](/dev/how-to/troubleshoot/tidb-lightning.md) diff --git a/dev/faq/tidb-lightning.md b/dev/faq/tidb-lightning.md index de06198ba73b..1e6b7ac7ad94 100644 --- a/dev/faq/tidb-lightning.md +++ b/dev/faq/tidb-lightning.md @@ -29,11 +29,13 @@ TiDB Lightning 需要以下权限: * CREATE * DROP -存储断点的数据库额外需要以下权限: +如果选择 [TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md) 模式,或目标数据库用于存储断点,则 TiBD Lightning 额外需要以下权限: * INSERT * DELETE ++Importer-backend 无需以上两个权限,因为数据直接被 Ingest 到 TiKV 中,所以绕过了 TiDB 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问,就可以保证安全。 + 如果 TiDB Lightning 配置项 `checksum = true`,则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 ## TiDB Lightning 在导数据过程中某个表报错了,会影响其他表吗?进程会马上退出吗? diff --git a/dev/reference/tools/tidb-lightning/config.md b/dev/reference/tools/tidb-lightning/config.md index a9f0bbdc0911..e590153139a9 100644 --- a/dev/reference/tools/tidb-lightning/config.md +++ b/dev/reference/tools/tidb-lightning/config.md @@ -84,8 +84,15 @@ driver = "file" # keep-after-success = false [tikv-importer] -# tikv-importer 的监听地址,需改为实际地址。 +# 选择后端:“importer” 或 “tidb“ +# backend = "importer" +# 当后端是 “importer” 时,tikv-importer 的监听地址(需改为实际地址)。 addr = "172.16.31.10:8287" +# 当后端是 “tidb” 时,插入重复数据时执行的操作。 +# - replace:新数据替代已有数据 +# - ignore:保留已有数据,忽略新数据 +# - error:中止导入并报错 +# on-duplicate = "replace" [mydumper] # 设置文件读取的区块大小,确保该值比数据源的最长字符串长。 @@ -100,7 +107,7 @@ batch-size = 107_374_182_400 # Byte (默认为 100 GB) # 稍微增大了前几个区块的大小。该参数也决定了比例系数,即在完全并发下 # “导入”和“写入”过程的持续时间比。这个值可以通过计算 1 GB 大小的 # 单张表的(导入时长/写入时长)得到。在日志文件中可以看到精确的时间。 -# 如果“导入”更块,区块大小的差异就会更小;比值为 0 时则说明区块大小一致。 +# 如果“导入”更快,区块大小的差异就会更小;比值为 0 时则说明区块大小一致。 # 取值范围为(0 <= batch-import-ratio < 1)。 batch-import-ratio = 0.75 @@ -159,6 +166,10 @@ checksum-table-concurrency = 16 # 解析和执行 SQL 语句的默认 SQL 模式。 sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" +# `max-allowed-packet` 设置数据库连接允许的最大数据包大小, +# 对应于系统参数中的 `max_allowed_packet`。 如果设置为 0, +# 会使用下游数据库 global 级别的 `max_allowed_packet`。 +max-allowed-packet = 67_108_864 # 数据导入完成后,tidb-lightning 可以自动执行 Checksum、Compact 和 Analyze 操作。 # 在生产环境中,建议这将些参数都设为 true。 @@ -269,6 +280,7 @@ min-available-ratio = 0.05 | -V | 输出程序的版本 | | | -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | | -L *level* | 日志的等级: debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | +| --backend *backend* | 选择后端的模式:`importer` 或 [`tidb`](/dev/reference/tools/tidb-lightning/tidb-backend.md) | `tikv-importer.backend` | | --log-file *file* | 日志文件路径 | `lightning.log-file` | | --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | | --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | diff --git a/dev/reference/tools/tidb-lightning/deployment.md b/dev/reference/tools/tidb-lightning/deployment.md index 341004bb535e..11a358bb9da9 100644 --- a/dev/reference/tools/tidb-lightning/deployment.md +++ b/dev/reference/tools/tidb-lightning/deployment.md @@ -5,7 +5,9 @@ category: reference # TiDB Lightning 部署与执行 -本文主要介绍 TiDB Lightning 单独部署与混合部署的硬件需求,以及使用 Ansible 部署与手动部署这两种部署方式。 +本文主要介绍 TiDB Lightning 使用 Importer-backend(默认)进行数据导入的硬件需求,以及使用 Ansible 部署与手动部署 TiDB Lightning 这两种部署方式。 + +如果你想改用 TiDB-backend 进行数据导入,参考 [TiDB Lightning TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md) 中的硬件需求与部署方式。 ## 注意事项 @@ -269,3 +271,9 @@ TiDB Lightning 可随 TiDB 集群一起用 [Ansible 部署](/dev/how-to/deploy/o #!/bin/bash nohup ./tidb-lightning -config tidb-lightning.toml > nohup.out & ``` + +## 升级 TiDB Lightning + +你可以通过替换二进制文件升级 TiDB Lightning,无需其他配置。重启 TiDB Lightning 的具体操作参见 [FAQ](/dev/faq/tidb-lightning.md#如何正确重启-tidb-lightning)。 + +如果当前有运行的导入任务,推荐任务完成后再升级 TiDB Lightning。否则,你可能需要从头重新导入,因为无法保证断点可以跨版本工作。 diff --git a/dev/reference/tools/tidb-lightning/overview.md b/dev/reference/tools/tidb-lightning/overview.md index 01bd74015323..d897139b4f3a 100644 --- a/dev/reference/tools/tidb-lightning/overview.md +++ b/dev/reference/tools/tidb-lightning/overview.md @@ -38,3 +38,5 @@ TiDB Lightning 整体工作原理如下: 表的自增 ID 是通过行数的**上界**估计值得到的,与表的数据文件总大小成正比。因此,最后的自增 ID 通常比实际行数大得多。这属于正常现象,因为在 TiDB 中自增 ID [不一定是连续分配的](/dev/reference/mysql-compatibility.md#auto-increment-id)。 7. 在所有步骤完毕后,`tidb-lightning` 自动将 TiKV 切换回“普通模式” (normal mode),此后 TiDB 集群可以正常对外提供服务。 + +TiDB Lightning 还支持使用 TiDB-backend 作为后端导入数据。和 Loader 类似,使用 TiDB-backend 时,`tidb-lightning` 将数据转换为 `INSERT` 语句,然后直接在目标集群上执行这些语句。详见 [TiDB Lightning TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md)。 diff --git a/dev/reference/tools/tidb-lightning/table-filter.md b/dev/reference/tools/tidb-lightning/table-filter.md index 3f4ff93a6d6b..00cd77e41c7a 100644 --- a/dev/reference/tools/tidb-lightning/table-filter.md +++ b/dev/reference/tools/tidb-lightning/table-filter.md @@ -26,6 +26,10 @@ ignore-dbs = ["pattern4", "pattern5"] 如果匹配项首字符为 `~`,它会被解析为 [Go 语言的正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。否则会视为普通的字串来匹配数据库名称。 +> **注意:** +> +> 无论你如何设置过滤规则,系统数据库 `information_schema`、`performance_schema`、`mysql` 和 `sys` 总是会被略过。 + ## 过滤表 ```toml diff --git a/dev/reference/tools/tidb-lightning/tidb-backend.md b/dev/reference/tools/tidb-lightning/tidb-backend.md new file mode 100644 index 000000000000..c846f33605c7 --- /dev/null +++ b/dev/reference/tools/tidb-lightning/tidb-backend.md @@ -0,0 +1,208 @@ +--- +title: TiDB Lightning TiDB-Backend +summary: 了解 TiDB Lightning TiDB-backend。 +category: reference +--- + +# TiDB Lightning TiDB-Backend + +TiDB Lightning 的后端决定 `tidb-lightning` 将如何把将数据导入到目标集群中。目前,TiDB Lightning 支持 Importer-backend(默认)和 TiDB-backend 两种后端,两者导入数据的区别如下: + +* **Importer-backend**:`tidb-lightning` 先将 SQL 或 CSV 数据编码成键值对,由 `tikv-importer` 对写入的键值对进行排序,然后把这些键值对 Ingest 到 TiKV 节点中。 + +* **TiDB-backend**:`tidb-lightning` 先将数据编码成 `INSERT` 语句,然后直接在 TiDB 节点上运行这些 SQL 语句进行数据导入。 + +| 后端 | Importer-backend | TiDB-backend | +|:---|:---|:---| +| 速度 | 快 (~300 GB/小时) | 慢 (~50 GB/小时) | +| 资源使用率 | 高 | 低 | +| 导入时是否满足 ACID | 否 | 是 | +| 目标表 | 必须为空 | 可以不为空 | + +## 部署 TiDB-backend + +使用 TiDB-backend 时,你无需部署 `tikv-importer`。与[标准部署过程](/dev/reference/tools/tidb-lightning/deployment.md)相比,部署 TiDB-backend 时有如下不同: + +* 可以跳过所有涉及 `tikv-importer` 的步骤。 +* 必须更改相应配置申明使用的是 TiDB-backend。 + +### 硬件需求 + +使用 TiDB-backend 时, TiDB Lightning 的速度仅受限于 TiDB 执行 SQL 语句的速度。因此,即使是低配的机器也足够发挥出最佳性能。推荐的硬件配置如下: + +* 16 逻辑核 CPU +* 足够储存整个数据源的 SSD 硬盘,读取速度越快越好 +* 千兆网卡 + +### 使用 Ansible 部署 + +1. `inventory.ini` 文件中,`[importer_server]` 部分可以留空。 + + ```ini + ... + + [importer_server] + # keep empty + + [lightning_server] + 192.168.20.10 + + ... + ``` + +2. 忽略 `group_vars/all.yml` 文件中 `tikv_importer_port` 部分的设置,`group_vars/importer_server.yml` 文件也不需要修改。但是你需要在 `conf/tidb-lightning.yml` 文件中将 `backend` 设置更改为 `tidb`。 + + ```yaml + ... + tikv_importer: + backend: "tidb" # <-- 改成 “tidb” + ... + ``` + +3. 启动、部署集群。 + +4. 为 TiDB Lightning 挂载数据源。 + +5. 启动 `tidb-lightning`。 + +### 手动部署 + +手动部署时,你无需下载和配置 `tikv-importer`。 + +在运行 `tidb-lightning` 之前,在配置文件中加上如下几行: + +```toml +[tikv-importer] +backend = "tidb" +``` + +或者在用命令行启动 `tidb-lightning` 时,传入参数 `--backend tidb`。 + +## 冲突解决 + +TiDB-backend 支持导入到已填充的表(非空表)。但是,新数据可能会与旧数据的唯一键冲突。你可以通过使用如下任务配置来控制遇到冲突时的默认行为: + +```toml +[tikv-importer] +backend = "tidb" +on-duplicate = "replace" # 或者 “error”、“ignore” +``` + +| 设置 | 冲突时默认行为 | 对应 SQL 语句 | +|:---|:---|:---| +| replace | 新数据替代旧数据 | `REPLACE INTO ...` | +| ignore | 保留旧数据,忽略新数据 | `INSERT IGNORE INTO ...` | +| error | 中止导入 | `INSERT INTO ...` | + +## 从 Loader 迁移到 TiDB Lightning TiDB-backend + +TiDB Lightning TiDB-backend 可以完全取代 [Loader](/dev/reference/tools/loader.md)。下表说明了如何将 [Loader](/dev/reference/tools/loader.md) 的配置迁移到 [TiDB Lightning 配置](/dev/reference/tools/tidb-lightning/config.md)中: + + + + + + + + + + + +
LoaderTiDB Lightning
+ +```toml +# 日志 +log-level = "info" +log-file = "loader.log" +# Prometheus +status-addr = ":8272" +# 线程数 +pool-size = 16 +``` + + + +```toml +[lightning] +# 日志 +level = "info" +file = "tidb-lightning.log" +# Prometheus +pprof-port = 8289 +# 并发度 (最好使用默认设置) +#region-concurrency = 16 +``` + +
+ +```toml +# 断点数据库名 +checkpoint-schema = "tidb_loader" +``` + + + +```toml +[checkpoint] +# 断点存储 +enable = true +schema = "tidb_lightning_checkpoint" +# 断点默认存储在本地的文件系统,这样更高效。但你也可以 +# 选择将断点存储在目标数据库中,设置如下: +# driver = "mysql" +``` + +
+ +```toml +``` + + + +```toml +[tikv-importer] +# 使用 TiDB-backend +backend = "tidb" +``` + +
+ +```toml +# 数据源目录 +dir = "/data/export/" +``` + + + +```toml +[mydumper] +# 数据源目录 +data-source-dir = "/data/export" +``` + +
+ +```toml +[db] +# TiDB 连接参数 +host = "127.0.0.1" +port = 4000 +user = "root" +password = "" +#sql-mode = "" +``` + + + +```toml +[tidb] +# TiDB 连接参数 +host = "127.0.0.1" +port = 4000 +status-port = 10080 # <- 必须有的参数 +user = "root" +password = "" +#sql-mode = "" +``` + +
diff --git a/v3.0/TOC.md b/v3.0/TOC.md index e672bf1c03a2..5ce36627f84c 100644 --- a/v3.0/TOC.md +++ b/v3.0/TOC.md @@ -345,6 +345,7 @@ - [断点续传](/v3.0/reference/tools/tidb-lightning/checkpoints.md) - [表库过滤](/v3.0/reference/tools/tidb-lightning/table-filter.md) - [CSV 支持](/v3.0/reference/tools/tidb-lightning/csv.md) + - [TiDB-backend](/v3.0/reference/tools/tidb-lightning/tidb-backend.md) - [Web 界面](/v3.0/reference/tools/tidb-lightning/web.md) - [监控告警](/v3.0/reference/tools/tidb-lightning/monitor.md) - [故障诊断](/v3.0/how-to/troubleshoot/tidb-lightning.md) diff --git a/v3.0/faq/tidb-lightning.md b/v3.0/faq/tidb-lightning.md index e126b4bc9822..4e7dc4c36494 100644 --- a/v3.0/faq/tidb-lightning.md +++ b/v3.0/faq/tidb-lightning.md @@ -30,11 +30,13 @@ TiDB Lightning 需要以下权限: * CREATE * DROP -存储断点的数据库额外需要以下权限: +如果选择 [TiDB-backend](/v3.0/reference/tools/tidb-lightning/tidb-backend.md) 模式,或目标数据库用于存储断点,则 TiBD Lightning 额外需要以下权限: * INSERT * DELETE +Importer-backend 无需以上两个权限,因为数据直接被 Ingest 到 TiKV 中,所以绕过了 TiDB 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问,就可以保证安全。 + 如果 TiDB Lightning 配置项 `checksum = true`,则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 ## TiDB Lightning 在导数据过程中某个表报错了,会影响其他表吗?进程会马上退出吗? diff --git a/v3.0/reference/tools/tidb-lightning/config.md b/v3.0/reference/tools/tidb-lightning/config.md index ba059ba256b6..139e0b4f83ff 100644 --- a/v3.0/reference/tools/tidb-lightning/config.md +++ b/v3.0/reference/tools/tidb-lightning/config.md @@ -84,8 +84,15 @@ driver = "file" # keep-after-success = false [tikv-importer] -# tikv-importer 的监听地址,需改为实际地址。 +# 选择后端:“importer” 或 “tidb“ +# backend = "importer" +# 当后端是 “importer” 时,tikv-importer 的监听地址(需改为实际地址)。 addr = "172.16.31.10:8287" +# 当后端是 “tidb” 时,插入重复数据时执行的操作。 +# - replace:新数据替代已有数据 +# - ignore:保留已有数据,忽略新数据 +# - error:中止导入并报错 +# on-duplicate = "replace" [mydumper] # 设置文件读取的区块大小,确保该值比数据源的最长字符串长。 @@ -100,7 +107,7 @@ batch-size = 107_374_182_400 # Byte (默认为 100 GB) # 稍微增大了前几个区块的大小。该参数也决定了比例系数,即在完全并发下 # “导入”和“写入”过程的持续时间比。这个值可以通过计算 1 GB 大小的 # 单张表的(导入时长/写入时长)得到。在日志文件中可以看到精确的时间。 -# 如果“导入”更块,区块大小的差异就会更小;比值为 0 时则说明区块大小一致。 +# 如果“导入”更快,区块大小的差异就会更小;比值为 0 时则说明区块大小一致。 # 取值范围为(0 <= batch-import-ratio < 1)。 batch-import-ratio = 0.75 @@ -159,6 +166,10 @@ checksum-table-concurrency = 16 # 解析和执行 SQL 语句的默认 SQL 模式。 sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" +# `max-allowed-packet` 设置数据库连接允许的最大数据包大小, +# 对应于系统参数中的 `max_allowed_packet`。 如果设置为 0, +# 会使用下游数据库 global 级别的 `max_allowed_packet`。 +max-allowed-packet = 67_108_864 # 数据导入完成后,tidb-lightning 可以自动执行 Checksum、Compact 和 Analyze 操作。 # 在生产环境中,建议这将些参数都设为 true。 @@ -269,6 +280,7 @@ min-available-ratio = 0.05 | -V | 输出程序的版本 | | | -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | | -L *level* | 日志的等级: debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | +| --backend *backend* | 选择后端的模式:`importer` 或 [`tidb`](/v3.0/reference/tools/tidb-lightning/tidb-backend.md) | `tikv-importer.backend` | | --log-file *file* | 日志文件路径 | `lightning.log-file` | | --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | | --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | diff --git a/v3.0/reference/tools/tidb-lightning/deployment.md b/v3.0/reference/tools/tidb-lightning/deployment.md index 2d4e0a786211..11984a06c35c 100644 --- a/v3.0/reference/tools/tidb-lightning/deployment.md +++ b/v3.0/reference/tools/tidb-lightning/deployment.md @@ -6,7 +6,9 @@ aliases: ['/docs-cn/tools/lightning/deployment/'] # TiDB Lightning 部署与执行 -本文主要介绍 TiDB Lightning 单独部署与混合部署的硬件需求,以及使用 Ansible 部署与手动部署这两种部署方式。 +本文主要介绍 TiDB Lightning 使用 Importer-backend(默认)进行数据导入的硬件需求,以及使用 Ansible 部署与手动部署 TiDB Lightning 这两种部署方式。 + +如果你想改用 TiDB-backend 进行数据导入,参考 [TiDB Lightning TiDB-backend](/v3.0/reference/tools/tidb-lightning/tidb-backend.md) 中的硬件需求与部署方式。 ## 注意事项 @@ -270,3 +272,9 @@ TiDB Lightning 可随 TiDB 集群一起用 [Ansible 部署](/v3.0/how-to/deploy/ #!/bin/bash nohup ./tidb-lightning -config tidb-lightning.toml > nohup.out & ``` + +## 升级 TiDB Lightning + +你可以通过替换二进制文件升级 TiDB Lightning,无需其他配置。重启 TiDB Lightning 的具体操作参见 [FAQ](/v3.0/faq/tidb-lightning.md#如何正确重启-tidb-lightning)。 + +如果当前有运行的导入任务,推荐任务完成后再升级 TiDB Lightning。否则,你可能需要从头重新导入,因为无法保证断点可以跨版本工作。 \ No newline at end of file diff --git a/v3.0/reference/tools/tidb-lightning/overview.md b/v3.0/reference/tools/tidb-lightning/overview.md index 4f11135440af..48dd93c937a7 100644 --- a/v3.0/reference/tools/tidb-lightning/overview.md +++ b/v3.0/reference/tools/tidb-lightning/overview.md @@ -38,3 +38,5 @@ TiDB Lightning 整体工作原理如下: 表的自增 ID 是通过行数的**上界**估计值得到的,与表的数据文件总大小成正比。因此,最后的自增 ID 通常比实际行数大得多。这属于正常现象,因为在 TiDB 中自增 ID [不一定是连续分配的](/v3.0/reference/mysql-compatibility.md#auto-increment-id)。 7. 在所有步骤完毕后,`tidb-lightning` 自动将 TiKV 切换回“普通模式” (normal mode),此后 TiDB 集群可以正常对外提供服务。 + +TiDB Lightning 还支持使用 TiDB-backend 作为后端导入数据。和 Loader 类似,使用 TiDB-backend 时,`tidb-lightning` 将数据转换为 `INSERT` 语句,然后直接在目标集群上执行这些语句。详见 [TiDB Lightning TiDB-backend](/v3.0/reference/tools/tidb-lightning/tidb-backend.md)。 \ No newline at end of file diff --git a/v3.0/reference/tools/tidb-lightning/table-filter.md b/v3.0/reference/tools/tidb-lightning/table-filter.md index fdd6421c9f55..19307fc6deaa 100644 --- a/v3.0/reference/tools/tidb-lightning/table-filter.md +++ b/v3.0/reference/tools/tidb-lightning/table-filter.md @@ -27,6 +27,10 @@ ignore-dbs = ["pattern4", "pattern5"] 如果匹配项首字符为 `~`,它会被解析为 [Go 语言的正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。否则会视为普通的字串来匹配数据库名称。 +> **注意:** +> +> 无论你如何设置过滤规则,系统数据库 `information_schema`、`performance_schema`、`mysql` 和 `sys` 总是会被略过。 + ## 过滤表 ```toml diff --git a/v3.0/reference/tools/tidb-lightning/tidb-backend.md b/v3.0/reference/tools/tidb-lightning/tidb-backend.md new file mode 100644 index 000000000000..8718b60962dd --- /dev/null +++ b/v3.0/reference/tools/tidb-lightning/tidb-backend.md @@ -0,0 +1,208 @@ +--- +title: TiDB Lightning TiDB-Backend +summary: 了解 TiDB Lightning TiDB-backend。 +category: reference +--- + +# TiDB Lightning TiDB-Backend + +TiDB Lightning 的后端决定 `tidb-lightning` 将如何把将数据导入到目标集群中。目前,TiDB Lightning 支持 Importer-backend(默认)和 TiDB-backend 两种后端,两者导入数据的区别如下: + +* **Importer-backend**:`tidb-lightning` 先将 SQL 或 CSV 数据编码成键值对,由 `tikv-importer` 对写入的键值对进行排序,然后把这些键值对 Ingest 到 TiKV 节点中。 + +* **TiDB-backend**:`tidb-lightning` 先将数据编码成 `INSERT` 语句,然后直接在 TiDB 节点上运行这些 SQL 语句进行数据导入。 + +| 后端 | Importer-backend | TiDB-backend | +|:---|:---|:---| +| 速度 | 快 (~300 GB/小时) | 慢 (~50 GB/小时) | +| 资源使用率 | 高 | 低 | +| 导入时是否满足 ACID | 否 | 是 | +| 目标表 | 必须为空 | 可以不为空 | + +## 部署 TiDB-backend + +使用 TiDB-backend 时,你无需部署 `tikv-importer`。与[标准部署过程](/v3.0/reference/tools/tidb-lightning/deployment.md)相比,部署 TiDB-backend 时有如下不同: + +* 可以跳过所有涉及 `tikv-importer` 的步骤。 +* 必须更改相应配置申明使用的是 TiDB-backend。 + +### 硬件需求 + +使用 TiDB-backend 时, TiDB Lightning 的速度仅受限于 TiDB 执行 SQL 语句的速度。因此,即使是低配的机器也足够发挥出最佳性能。推荐的硬件配置如下: + +* 16 逻辑核 CPU +* 足够储存整个数据源的 SSD 硬盘,读取速度越快越好 +* 千兆网卡 + +### 使用 Ansible 部署 + +1. `inventory.ini` 文件中,`[importer_server]` 部分可以留空。 + + ```ini + ... + + [importer_server] + # keep empty + + [lightning_server] + 192.168.20.10 + + ... + ``` + +2. 忽略 `group_vars/all.yml` 文件中 `tikv_importer_port` 部分的设置,`group_vars/importer_server.yml` 文件也不需要修改。但是你需要在 `conf/tidb-lightning.yml` 文件中将 `backend` 设置更改为 `tidb`。 + + ```yaml + ... + tikv_importer: + backend: "tidb" # <-- 改成 “tidb” + ... + ``` + +3. 启动、部署集群。 + +4. 为 TiDB Lightning 挂载数据源。 + +5. 启动 `tidb-lightning`。 + +### 手动部署 + +手动部署时,你无需下载和配置 `tikv-importer`。 + +在运行 `tidb-lightning` 之前,在配置文件中加上如下几行: + +```toml +[tikv-importer] +backend = "tidb" +``` + +或者在用命令行启动 `tidb-lightning` 时,传入参数 `--backend tidb`。 + +## 冲突解决 + +TiDB-backend 支持导入到已填充的表(非空表)。但是,新数据可能会与旧数据的唯一键冲突。你可以通过使用如下任务配置来控制遇到冲突时的默认行为: + +```toml +[tikv-importer] +backend = "tidb" +on-duplicate = "replace" # 或者 “error”、“ignore” +``` + +| 设置 | 冲突时默认行为 | 对应 SQL 语句 | +|:---|:---|:---| +| replace | 新数据替代旧数据 | `REPLACE INTO ...` | +| ignore | 保留旧数据,忽略新数据 | `INSERT IGNORE INTO ...` | +| error | 中止导入 | `INSERT INTO ...` | + +## 从 Loader 迁移到 TiDB Lightning TiDB-backend + +TiDB Lightning TiDB-backend 可以完全取代 [Loader](/v3.0/reference/tools/loader.md)。下表说明了如何将 [Loader](/v3.0/reference/tools/loader.md) 的配置迁移到 [TiDB Lightning 配置](/v3.0/reference/tools/tidb-lightning/config.md)中: + + + + + + + + + + + +
LoaderTiDB Lightning
+ +```toml +# 日志 +log-level = "info" +log-file = "loader.log" +# Prometheus +status-addr = ":8272" +# 线程数 +pool-size = 16 +``` + + + +```toml +[lightning] +# 日志 +level = "info" +file = "tidb-lightning.log" +# Prometheus +pprof-port = 8289 +# 并发度 (最好使用默认设置) +#region-concurrency = 16 +``` + +
+ +```toml +# 断点数据库名 +checkpoint-schema = "tidb_loader" +``` + + + +```toml +[checkpoint] +# 断点存储 +enable = true +schema = "tidb_lightning_checkpoint" +# 断点默认存储在本地的文件系统,这样更高效。但你也可以 +# 选择将断点存储在目标数据库中,设置如下: +# driver = "mysql" +``` + +
+ +```toml +``` + + + +```toml +[tikv-importer] +# 使用 TiDB-backend +backend = "tidb" +``` + +
+ +```toml +# 数据源目录 +dir = "/data/export/" +``` + + + +```toml +[mydumper] +# 数据源目录 +data-source-dir = "/data/export" +``` + +
+ +```toml +[db] +# TiDB 连接参数 +host = "127.0.0.1" +port = 4000 +user = "root" +password = "" +#sql-mode = "" +``` + + + +```toml +[tidb] +# TiDB 连接参数 +host = "127.0.0.1" +port = 4000 +status-port = 10080 # <- 必须有的参数 +user = "root" +password = "" +#sql-mode = "" +``` + +
diff --git a/v3.1/TOC.md b/v3.1/TOC.md index edcd029f971d..73fc6f8cccd6 100644 --- a/v3.1/TOC.md +++ b/v3.1/TOC.md @@ -349,6 +349,7 @@ - [断点续传](/v3.1/reference/tools/tidb-lightning/checkpoints.md) - [表库过滤](/v3.1/reference/tools/tidb-lightning/table-filter.md) - [CSV 支持](/v3.1/reference/tools/tidb-lightning/csv.md) + - [TiDB-backend](/v3.1/reference/tools/tidb-lightning/tidb-backend.md) - [Web 界面](/v3.1/reference/tools/tidb-lightning/web.md) - [监控告警](/v3.1/reference/tools/tidb-lightning/monitor.md) - [故障诊断](/v3.1/how-to/troubleshoot/tidb-lightning.md) diff --git a/v3.1/faq/tidb-lightning.md b/v3.1/faq/tidb-lightning.md index a94125d63b89..6833c8063fe4 100644 --- a/v3.1/faq/tidb-lightning.md +++ b/v3.1/faq/tidb-lightning.md @@ -29,11 +29,13 @@ TiDB Lightning 需要以下权限: * CREATE * DROP -存储断点的数据库额外需要以下权限: +如果选择 [TiDB-backend](/v3.1/reference/tools/tidb-lightning/tidb-backend.md) 模式,或目标数据库用于存储断点,则 TiBD Lightning 额外需要以下权限: * INSERT * DELETE +Importer-backend 无需以上两个权限,因为数据直接被 Ingest 到 TiKV 中,所以绕过了 TiDB 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问,就可以保证安全。 + 如果 TiDB Lightning 配置项 `checksum = true`,则 TiDB Lightning 需要有下游 TiDB admin 用户权限。 ## TiDB Lightning 在导数据过程中某个表报错了,会影响其他表吗?进程会马上退出吗? diff --git a/v3.1/reference/tools/tidb-lightning/config.md b/v3.1/reference/tools/tidb-lightning/config.md index 3aa17a5d3963..e85e76a19b80 100644 --- a/v3.1/reference/tools/tidb-lightning/config.md +++ b/v3.1/reference/tools/tidb-lightning/config.md @@ -84,8 +84,15 @@ driver = "file" # keep-after-success = false [tikv-importer] -# tikv-importer 的监听地址,需改为实际地址。 +# 选择后端:“importer” 或 “tidb“ +# backend = "importer" +# 当后端是 “importer” 时,tikv-importer 的监听地址(需改为实际地址)。 addr = "172.16.31.10:8287" +# 当后端是 “tidb” 时,插入重复数据时执行的操作。 +# - replace:新数据替代已有数据 +# - ignore:保留已有数据,忽略新数据 +# - error:中止导入并报错 +# on-duplicate = "replace" [mydumper] # 设置文件读取的区块大小,确保该值比数据源的最长字符串长。 @@ -100,7 +107,7 @@ batch-size = 107_374_182_400 # Byte (默认为 100 GB) # 稍微增大了前几个区块的大小。该参数也决定了比例系数,即在完全并发下 # “导入”和“写入”过程的持续时间比。这个值可以通过计算 1 GB 大小的 # 单张表的(导入时长/写入时长)得到。在日志文件中可以看到精确的时间。 -# 如果“导入”更块,区块大小的差异就会更小;比值为 0 时则说明区块大小一致。 +# 如果“导入”更快,区块大小的差异就会更小;比值为 0 时则说明区块大小一致。 # 取值范围为(0 <= batch-import-ratio < 1)。 batch-import-ratio = 0.75 @@ -159,6 +166,10 @@ checksum-table-concurrency = 16 # 解析和执行 SQL 语句的默认 SQL 模式。 sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION" +# `max-allowed-packet` 设置数据库连接允许的最大数据包大小, +# 对应于系统参数中的 `max_allowed_packet`。 如果设置为 0, +# 会使用下游数据库 global 级别的 `max_allowed_packet`。 +max-allowed-packet = 67_108_864 # 数据导入完成后,tidb-lightning 可以自动执行 Checksum、Compact 和 Analyze 操作。 # 在生产环境中,建议这将些参数都设为 true。 @@ -269,6 +280,7 @@ min-available-ratio = 0.05 | -V | 输出程序的版本 | | | -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | | -L *level* | 日志的等级: debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | +| --backend *backend* | 选择后端的模式:`importer` 或 [`tidb`](/v3.1/reference/tools/tidb-lightning/tidb-backend.md) | `tikv-importer.backend` | | --log-file *file* | 日志文件路径 | `lightning.log-file` | | --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | | --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | diff --git a/v3.1/reference/tools/tidb-lightning/deployment.md b/v3.1/reference/tools/tidb-lightning/deployment.md index 5d872ece81d8..d7e38a1de131 100644 --- a/v3.1/reference/tools/tidb-lightning/deployment.md +++ b/v3.1/reference/tools/tidb-lightning/deployment.md @@ -6,7 +6,9 @@ aliases: ['/docs-cn/tools/lightning/deployment/'] # TiDB Lightning 部署与执行 -本文主要介绍 TiDB Lightning 单独部署与混合部署的硬件需求,以及使用 Ansible 部署与手动部署这两种部署方式。 +本文主要介绍 TiDB Lightning 使用 Importer-backend(默认)进行数据导入的硬件需求,以及使用 Ansible 部署与手动部署 TiDB Lightning 这两种部署方式。 + +如果你想改用 TiDB-backend 进行数据导入,参考 [TiDB Lightning TiDB-backend](/v3.1/reference/tools/tidb-lightning/tidb-backend.md) 中的硬件需求与部署方式。 ## 注意事项 @@ -270,3 +272,9 @@ TiDB Lightning 可随 TiDB 集群一起用 [Ansible 部署](/v3.1/how-to/deploy/ #!/bin/bash nohup ./tidb-lightning -config tidb-lightning.toml > nohup.out & ``` + +## 升级 TiDB Lightning + +你可以通过替换二进制文件升级 TiDB Lightning,无需其他配置。重启 TiDB Lightning 的具体操作参见 [FAQ](/v3.1/faq/tidb-lightning.md#如何正确重启-tidb-lightning)。 + +如果当前有运行的导入任务,推荐任务完成后再升级 TiDB Lightning。否则,你可能需要从头重新导入,因为无法保证断点可以跨版本工作。 \ No newline at end of file diff --git a/v3.1/reference/tools/tidb-lightning/overview.md b/v3.1/reference/tools/tidb-lightning/overview.md index e92f2cbd5e2e..7b03dce68473 100644 --- a/v3.1/reference/tools/tidb-lightning/overview.md +++ b/v3.1/reference/tools/tidb-lightning/overview.md @@ -38,3 +38,5 @@ TiDB Lightning 整体工作原理如下: 表的自增 ID 是通过行数的**上界**估计值得到的,与表的数据文件总大小成正比。因此,最后的自增 ID 通常比实际行数大得多。这属于正常现象,因为在 TiDB 中自增 ID [不一定是连续分配的](/v3.1/reference/mysql-compatibility.md#auto-increment-id)。 7. 在所有步骤完毕后,`tidb-lightning` 自动将 TiKV 切换回“普通模式” (normal mode),此后 TiDB 集群可以正常对外提供服务。 + +TiDB Lightning 还支持使用 TiDB-backend 作为后端导入数据。和 Loader 类似,使用 TiDB-backend 时,`tidb-lightning` 将数据转换为 `INSERT` 语句,然后直接在目标集群上执行这些语句。详见 [TiDB Lightning TiDB-backend](/v3.1/reference/tools/tidb-lightning/tidb-backend.md)。 \ No newline at end of file diff --git a/v3.1/reference/tools/tidb-lightning/table-filter.md b/v3.1/reference/tools/tidb-lightning/table-filter.md index 3f4ff93a6d6b..00cd77e41c7a 100644 --- a/v3.1/reference/tools/tidb-lightning/table-filter.md +++ b/v3.1/reference/tools/tidb-lightning/table-filter.md @@ -26,6 +26,10 @@ ignore-dbs = ["pattern4", "pattern5"] 如果匹配项首字符为 `~`,它会被解析为 [Go 语言的正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。否则会视为普通的字串来匹配数据库名称。 +> **注意:** +> +> 无论你如何设置过滤规则,系统数据库 `information_schema`、`performance_schema`、`mysql` 和 `sys` 总是会被略过。 + ## 过滤表 ```toml diff --git a/v3.1/reference/tools/tidb-lightning/tidb-backend.md b/v3.1/reference/tools/tidb-lightning/tidb-backend.md new file mode 100644 index 000000000000..9703033a2834 --- /dev/null +++ b/v3.1/reference/tools/tidb-lightning/tidb-backend.md @@ -0,0 +1,208 @@ +--- +title: TiDB Lightning TiDB-Backend +summary: 了解 TiDB Lightning TiDB-backend。 +category: reference +--- + +# TiDB Lightning TiDB-Backend + +TiDB Lightning 的后端决定 `tidb-lightning` 将如何把将数据导入到目标集群中。目前,TiDB Lightning 支持 Importer-backend(默认)和 TiDB-backend 两种后端,两者导入数据的区别如下: + +* **Importer-backend**:`tidb-lightning` 先将 SQL 或 CSV 数据编码成键值对,由 `tikv-importer` 对写入的键值对进行排序,然后把这些键值对 Ingest 到 TiKV 节点中。 + +* **TiDB-backend**:`tidb-lightning` 先将数据编码成 `INSERT` 语句,然后直接在 TiDB 节点上运行这些 SQL 语句进行数据导入。 + +| 后端 | Importer-backend | TiDB-backend | +|:---|:---|:---| +| 速度 | 快 (~300 GB/小时) | 慢 (~50 GB/小时) | +| 资源使用率 | 高 | 低 | +| 导入时是否满足 ACID | 否 | 是 | +| 目标表 | 必须为空 | 可以不为空 | + +## 部署 TiDB-backend + +使用 TiDB-backend 时,你无需部署 `tikv-importer`。与[标准部署过程](/v3.1/reference/tools/tidb-lightning/deployment.md)相比,部署 TiDB-backend 时有如下不同: + +* 可以跳过所有涉及 `tikv-importer` 的步骤。 +* 必须更改相应配置申明使用的是 TiDB-backend。 + +### 硬件需求 + +使用 TiDB-backend 时, TiDB Lightning 的速度仅受限于 TiDB 执行 SQL 语句的速度。因此,即使是低配的机器也足够发挥出最佳性能。推荐的硬件配置如下: + +* 16 逻辑核 CPU +* 足够储存整个数据源的 SSD 硬盘,读取速度越快越好 +* 千兆网卡 + +### 使用 Ansible 部署 + +1. `inventory.ini` 文件中,`[importer_server]` 部分可以留空。 + + ```ini + ... + + [importer_server] + # keep empty + + [lightning_server] + 192.168.20.10 + + ... + ``` + +2. 忽略 `group_vars/all.yml` 文件中 `tikv_importer_port` 部分的设置,`group_vars/importer_server.yml` 文件也不需要修改。但是你需要在 `conf/tidb-lightning.yml` 文件中将 `backend` 设置更改为 `tidb`。 + + ```yaml + ... + tikv_importer: + backend: "tidb" # <-- 改成 “tidb” + ... + ``` + +3. 启动、部署集群。 + +4. 为 TiDB Lightning 挂载数据源。 + +5. 启动 `tidb-lightning`。 + +### 手动部署 + +手动部署时,你无需下载和配置 `tikv-importer`。 + +在运行 `tidb-lightning` 之前,在配置文件中加上如下几行: + +```toml +[tikv-importer] +backend = "tidb" +``` + +或者在用命令行启动 `tidb-lightning` 时,传入参数 `--backend tidb`。 + +## 冲突解决 + +TiDB-backend 支持导入到已填充的表(非空表)。但是,新数据可能会与旧数据的唯一键冲突。你可以通过使用如下任务配置来控制遇到冲突时的默认行为: + +```toml +[tikv-importer] +backend = "tidb" +on-duplicate = "replace" # 或者 “error”、“ignore” +``` + +| 设置 | 冲突时默认行为 | 对应 SQL 语句 | +|:---|:---|:---| +| replace | 新数据替代旧数据 | `REPLACE INTO ...` | +| ignore | 保留旧数据,忽略新数据 | `INSERT IGNORE INTO ...` | +| error | 中止导入 | `INSERT INTO ...` | + +## 从 Loader 迁移到 TiDB Lightning TiDB-backend + +TiDB Lightning TiDB-backend 可以完全取代 [Loader](/v3.1/reference/tools/loader.md)。下表说明了如何将 [Loader](/v3.1/reference/tools/loader.md) 的配置迁移到 [TiDB Lightning 配置](/v3.1/reference/tools/tidb-lightning/config.md)中: + + + + + + + + + + + +
LoaderTiDB Lightning
+ +```toml +# 日志 +log-level = "info" +log-file = "loader.log" +# Prometheus +status-addr = ":8272" +# 线程数 +pool-size = 16 +``` + + + +```toml +[lightning] +# 日志 +level = "info" +file = "tidb-lightning.log" +# Prometheus +pprof-port = 8289 +# 并发度 (最好使用默认设置) +#region-concurrency = 16 +``` + +
+ +```toml +# 断点数据库名 +checkpoint-schema = "tidb_loader" +``` + + + +```toml +[checkpoint] +# 断点存储 +enable = true +schema = "tidb_lightning_checkpoint" +# 断点默认存储在本地的文件系统,这样更高效。但你也可以 +# 选择将断点存储在目标数据库中,设置如下: +# driver = "mysql" +``` + +
+ +```toml +``` + + + +```toml +[tikv-importer] +# 使用 TiDB-backend +backend = "tidb" +``` + +
+ +```toml +# 数据源目录 +dir = "/data/export/" +``` + + + +```toml +[mydumper] +# 数据源目录 +data-source-dir = "/data/export" +``` + +
+ +```toml +[db] +# TiDB 连接参数 +host = "127.0.0.1" +port = 4000 +user = "root" +password = "" +#sql-mode = "" +``` + + + +```toml +[tidb] +# TiDB 连接参数 +host = "127.0.0.1" +port = 4000 +status-port = 10080 # <- 必须有的参数 +user = "root" +password = "" +#sql-mode = "" +``` + +