tidb-lightning: document backend and that system DBs are filtered

dev/TOC.md

@@ -344,6 +344,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)

dev/faq/tidb-lightning.md

@@ -23,11 +23,13 @@ TiDB Lightning 需要以下权限：
 * CREATE
 * DROP
 
-存储断点的数据库额外需要以下权限：
+如果选择 [TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md) 模式，或目标数据库用于存储断点，则 TiBD Lightning 额外需要以下权限：
 
 * INSERT
 * DELETE
 
++Importer-backend 无需以上两个权限，因为数据直接被 Ingest 到 TiKV 中，所以绕过了 TiBD 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问，就可以保证安全。
+
 如果 TiDB Lightning 配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。
 
 ## TiDB Lightning 在导数据过程中某个表报错了，会影响其他表吗？进程会马上退出吗？

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` |

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#how-to-properly-restart-tidb-lightning)。
+
+如果当前有运行的导入任务，推荐任务完成后再升级 TiDB Lightning。否则，你可能需要从头重新导入，因为无法保证断点可以跨版本工作。

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)。

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

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 支持 Importer-backend （默认）和 TiDB-backend 两种后端，两者导入数据的区别如下：
+
+* **Importer-backend**：`tidb-lightning` 先将 SQL 或 CSV 数据编码成键值对，由 `tikv-importer` 对写入的键值对进行排序，然后把这些键值对 Ingest 到 TiKV 节点中。
+
+* **TiDB-backend**：`tidb-lightning` 先将数据编码到 SQL 的 `INSERT` 语句中，然后直接在 TiDB 节点上运行这些语句进行数据导入。
+
+| 后端 | Importer | TiDB |
+|:---|:---|:---|
+| 速度 | 快 (~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 时， TiBD 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. 引导、部署集群。Bootstrap and deploy the cluster as usual.
+
+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)中：
+
+<table align="left">
+<thead><tr><th>Loader</th><th>TiDB Lightning</th></tr></thread>
+<tbody>
+<tr><td>
+
+```toml
+# 日志
+log-level = "info"
+log-file = "loader.log"
+# Prometheus
+status-addr = ":8272"
+# 线程数
+pool-size = 16
+```
+
+</td><td>
+
+```toml
+[lightning]
+# 日志
+level = "info"
+file = "tidb-lightning.log"
+# Prometheus
+pprof-port = 8289
+# 线程数 (最好使用默认设置)
+#region-concurrency = 16
+```
+
+</td></tr>
+<tr><td>
+
+```toml
+# 断点数据库名
+checkpoint-schema = "tidb_loader"
+```
+
+</td><td>
+
+```toml
+[checkpoint]
+# 断点存储
+enable = true
+schema = "tidb_lightning_checkpoint"
+# 断点默认存储在本地的文件系统，这样更高效。但你也可以
+# 选择将断点存储在兼容 MySQL 但数据库服务器中，设置如下：
+# driver = "mysql"
+```
+
+</td></tr>
+<tr><td>
+
+```toml
+```
+
+</td><td>
+
+```toml
+[tikv-importer]
+# 使用 TiDB-backend
+backend = "tidb"
+```
+
+</td></tr>
+<tr><td>
+
+```toml
+# 数据源目录
+dir = "/data/export/"
+```
+
+</td><td>
+
+```toml
+[mydumper]
+# 数据源目录
+data-source-dir = "/data/export"
+```
+
+</td></tr>
+
+<tr><td>
+
+```toml
+[db]
+# TiDB 连接参数
+host = "127.0.0.1"
+port = 4000
+user = "root"
+password = ""
+#sql-mode = ""
+```
+
+</td><td>
+
+```toml
+[tidb]
+# TiDB 连接参数
+host = "127.0.0.1"
+port = 4000
+status-port = 10080  # <- 必须
+user = "root"
+password = ""
+#sql-mode = ""
+```
+
+</td></tr>
+</tbody>
+</table>