reference refine the ecosystem tools user guide

TOC.md

@@ -55,7 +55,9 @@
     - [从 CSV 迁移](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md)
   + 运维
     - [Ansible 常见运维操作](/maintain-tidb-using-ansible.md)
-    + [备份与恢复](/backup-and-restore-using-mydumper-lightning.md)
+    + [备份与恢复]
+      - [使用 Mydumper 和 TiDB Lightning 进行备份与恢复](/backup-and-restore-using-mydumper-lightning.md)
+      - [使用 Dumpling 导出或备份 TiDB 数据](/export-or-backup-using-dumpling.md)
     + 定位异常查询
       - [定位慢查询](/identify-slow-queries.md)
       - [定位消耗系统资源多的查询](/identify-expensive-queries.md)
@@ -288,7 +290,8 @@
       - [常见错误修复](/tidb-binlog/handle-tidb-binlog-errors.md)
     - [FAQ](/tidb-binlog/tidb-binlog-faq.md)
   + 周边工具
-    - [工具使用指南](/ecosystem-tool-user-guide.md)
+    - [功能概览](/ecosystem-tool-user-guide.md)
+    - [适用场景](/ecosystem-tool-user-case.md)
     - [Mydumper](/mydumper-overview.md)
     - [Loader](/loader-overview.md)
     - [Syncer](/syncer-overview.md)

ecosystem-tool-user-case.md

@@ -0,0 +1,39 @@
+---
+title: TiDB 生态工具适用场景
+category: reference
+summary: 本文档介绍 TiDB 生态工具的常见适用场景与工具选择。
+---
+
+# TiDB 生态工具适用场景
+
+本文档从生态工具的适用场景出发，介绍部分常见场景下的生态工具选择。
+
+## 从 CSV 导入数据到 TiDB
+
+当需要将其他工具导出的格式兼容的 CSV files 导入到 TiDB 时，可使用 [TiDB Lightning](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md)。
+
+## 从 MySQL/Aurora 导入全量数据
+
+当需要从 MySQL/Aurora 导入全量数据时，可先使用 [Dumpling](/export-or-backup-using-dumpling.md) 将数据导出为 SQL dump files，然后再使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 将数据导入到 TiDB 集群。
+
+## 从 MySQL/Aurora 迁移数据
+
+当既需要从 MySQL/Aurora 导入全量数据，又需要迁移增量数据时，可使用 [TiDB Data Migration (DM)](https://pingcap.com/docs-cn/tidb-data-migration/stable/overview/) 完成全量数据和增量数据的迁移。
+
+如果全量数据量较大（TB 级别），则可先使用 [Dumpling](/export-or-backup-using-dumpling.md) 与 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 完成全量数据的迁移，再使用 DM 完成增量数据的迁移。
+
+## TiDB 集群备份与恢复
+
+当需要对 TiDB 集群进行备份时，可使用 [Dumpling](/export-or-backup-using-dumpling.md)。
+
+当需要将备份文件恢复到 TiDB 集群时，可使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md)。
+
+## 迁出数据到 MySQL/TiDB
+
+当需要将 TiDB 集群的数据迁出到 MySQL 或其他 TiDB 集群时，可使用 [Dumpling](/export-or-backup-using-dumpling.md) 从 TiDB 将全量数据导出为 SQL dump files，然后再使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 将数据导入到 MySQL/TiDB。
+
+如果还需要执行增量数据的迁移，则可使用 [TiDB Binlog](/tidb-binlog/tidb-binlog-overview.md)。
+
+## TiDB 增量数据订阅
+
+当需要订阅 TiDB 增量数据的变更时，可使用 [TiDB Binlog](/tidb-binlog/binlog-slave-client.md)。

ecosystem-tool-user-guide.md

@@ -1,135 +1,81 @@
 ---
-title: TiDB 生态工具使用指南
+title: TiDB 生态工具功能概览
 category: reference
 aliases: ['/docs-cn/v3.0/reference/tools/user-guide/','/docs-cn/v3.0/how-to/migrate/from-mysql/', '/docs-cn/v3.0/how-to/migrate/incrementally-from-mysql/', '/docs-cn/v3.0/how-to/migrate/overview/', '/docs-cn/v3.0/reference/tools/use-guide/']
 ---
 
-# TiDB 生态工具使用指南
+# TiDB 生态工具功能概览
 
-目前 TiDB 生态工具较多，有些工具之间有功能重叠，也有些属于版本迭代关系。本文档将对各个工具进行介绍，说明各个工具之间的关系，并且说明各个版本、场景下应该使用哪些工具。
+本文档从生态工具的功能出发，介绍部分生态工具的功能以及它们之间的替代关系。
 
-## TiDB 生态工具概览
+## 全量导出
 
-TiDB 生态工具可以分为几种：
+[Dumpling](/export-or-backup-using-dumpling.md) 是一个用于从 MySQL/TiDB 进行全量逻辑导出的工具。
 
-- 数据导入类，包括全量导入工具、备份和恢复工具、增量导入工具等
-- 数据导出类，包括全量导出工具、增量导出工具等
+基本信息：
 
-下面将分别介绍这两类工具。
-
-### 数据导入类
-
-#### 全量导入工具 Loader（停止维护，不推荐使用）
-
-[Loader](/loader-overview.md) 是一款轻量级的全量数据导入工具，数据以 SQL 的形式导入到 TiDB 中。目前这个工具正在逐步被 [TiDB Lightning](#全量导入工具-tidb-lightning) 替换掉，参见 [TiDB Lightning TiDB-backend 文档](/tidb-lightning/tidb-lightning-tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)。
-
-以下是 Loader 的一些基本信息：
-
-- Loader 的输入：Mydumper 输出的文件
-- Loader 的输出：以 SQL 形式写入 TiDB
+- Dumpling 的输入：MySQL/TiDB 集群
+- Dumpling 的输出：SQL/CSV 文件
 - 适用 TiDB 版本：所有版本
-- Kubernetes 支持：[备份与恢复](https://pingcap.com/docs-cn/tidb-in-kubernetes/stable/backup-and-restore-using-helm-charts/)
+- Kubernetes 支持：尚未支持
 
-#### 全量导入工具 TiDB Lightning
+## 全量导入
 
-[TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 是将全量数据快速导入到一个新的 TiDB 集群的工具。
+[TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 是一个用于将全量数据导入到 TiDB 集群的工具。
 
-注意用 TiDB Lightning 导入数据到 TiDB 的时候，有两种模式：
+使用 TiDB Lightning 导入数据到 TiDB 时，有两种模式：
 
-- 默认模式：`tikv-importer` 为后端，这种模式下导入数据过程中集群无法提供正常的服务，用于导入大量的数据（TB 级别）。
-- 第二种模式：`TiDB` 为后端（相当于 Loader 的功能），相对默认模式导入速度较慢，但是可以在线导入。
+- `importer` 模式：以 TiKV-importer 作为后端，这种模式一般用于导入大量的数据（TB 级别）到新集群，但在数据导入过程中集群无法提供正常的服务。
+- `tidb` 模式：以 TiDB/MySQL 作为后端，这种模式相比 `importer` 模式的导入速度较慢，但是可以在线导入，同时也支持将数据导入到 MySQL。
 
-以下是 TiDB Lightning 的一些基本信息：
+基本信息：
 
-- Lightning 的输入
-    - Mydumper 输出文件
-    - CSV 格式文件
+- Lightning 的输入：
+    - Dumpling 输出文件
+    - 其他格式兼容的 CSV 文件
 - 适用 TiDB 版本：v2.1 及以上
-- Kubernetes 支持：[使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据](https://pingcap.com/docs-cn/tidb-in-kubernetes/stable/restore-data-using-tidb-lightning/)
-
-#### 增量导入工具 Syncer（已停止维护，不推荐使用）
-
-[Syncer](/syncer-overview.md) 是将 MySQL/MariaDB 增量 binlog 数据实时复制导入到 TiDB 的工具。目前推荐使用 [TiDB Data Migration](#增量导入工具-tidb-data-migration) 替换该工具。
-
-以下是 Syncer 的一些基本信息：
+- Kubernetes 支持：[使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据](https://pingcap.com/docs-cn/tidb-in-kubernetes/v1.0/restore-data-using-tidb-lightning/)
 
-- Syncer 的输入：MySQL/MariaDB 的 binlog
-- Syncer 的输出：以 SQL 形式写入 TiDB
-- 适用 TiDB 版本：所有版本
-- Kubernetes 支持：不支持
-
-#### 增量导入工具 TiDB Data Migration
-
-[TiDB Data Migration (DM)](https://pingcap.com/docs-cn/tidb-data-migration/stable/overview/) 是将 MySQL/MariaDB 数据迁移到 TiDB 的工具，支持全量数据和增量数据的同步。
-
-以下是 DM 的一些基本信息：
+> **注意：**
+>
+> 原 Loader 工具已停止维护，不再推荐使用。相关场景请使用 TiDB Lightning 的 `tidb` 模式进行替代，详细信息请参考 [TiDB Lightning TiDB-backend 文档](/tidb-lightning/tidb-lightning-tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)。
 
-- DM 的输入：MySQL/MariaDB 的全量数据以及 binlog
-- DM 的输出：以 SQL 形式写入 TiDB
-- 适用 TiDB 版本：所有版本
-- Kubernetes 支持：开发中
+## 备份和恢复
 
-### 数据导出类
+[Dumpling](/export-or-backup-using-dumpling.md) 可用于将 TiDB 集群备份到 SQL 或 CSV 格式的文件，可参考[全量导出](#全量导出)。
 
-#### 全量导出工具 Mydumper
+[TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 可用于将 Dumpling 导出的 SQL 或 CSV 格式的文件恢复到 TiDB 集群，可参考 [全量导入](#全量导入)。
 
-[Mydumper](/mydumper-overview.md) 用于对 MySQL/TiDB 进行全量逻辑备份。
+## TiDB 增量日志同步
 
-以下是 Mydumper 的一些基本信息：
-
-- Mydumper 的输入：MySQL/TiDB 集群
-- Mydumper 的输出：SQL 文件
-- 适用 TiDB 版本：所有版本
-- Kubernetes 支持：[备份与恢复](https://pingcap.com/docs-cn/tidb-in-kubernetes/stable/backup-and-restore-using-helm-charts/)
+[TiDB Binlog](/tidb-binlog/tidb-binlog-overview.md) 是收集 TiDB 的增量 binlog 数据，并提供准实时同步和备份的工具。该工具可用于 TiDB 集群间的增量数据同步，如将其中一个 TiDB 集群作为另一个 TiDB 集群的从集群。
 
-#### 增量导出工具 TiDB Binlog
-
-[TiDB Binlog](/tidb-binlog/tidb-binlog-overview.md) 是收集 TiDB 的 binlog，并提供准实时同步和备份的工具。
-
-以下是 TiDB Binlog 的一些基本信息：
+基本信息：
 
 - TiDB Binlog 的输入：TiDB 集群
-- TiDB Binlog 的输出：MySQL、TiDB、Kafka 或者增量备份文件
+- TiDB Binlog 的输出：TiDB 集群、MySQL、Kafka 或者增量备份文件
 - 适用 TiDB 版本：v2.1 及以上
-- Kubernetes 支持：[TiDB Binlog 运维文档](https://pingcap.com/docs-cn/tidb-in-kubernetes/stable/deploy-tidb-binlog/)，[Kubernetes 上的 TiDB Binlog Drainer 配置](https://pingcap.com/docs-cn/tidb-in-kubernetes/stable/configure-tidb-binlog-drainer/)
-
-## 工具演进路线
-
-下面简单的介绍一下 TiDB 生态工具集的演进，方便大家了解工具之间的关系。
-
-### MySQL 数据迁移
-
-- Mydumper、Loader、Syncer -> DM：
-
-    使用 Mydumper、Loader、Syncer 将 MySQL 数据迁移到 TiDB，迁移过程比较繁琐。DM 提供了一体化的数据迁移方案，提高了易用性，而且 DM 还支持分库分表的合并。
-
-- Loader -> TiDB Lightning：
+- Kubernetes 支持：[TiDB Binlog 运维文档](https://pingcap.com/docs-cn/tidb-in-kubernetes/v1.0/deploy-tidb-binlog/)，[Kubernetes 上的 TiDB Binlog Drainer 配置](https://pingcap.com/docs-cn/tidb-in-kubernetes/v1.0/configure-tidb-binlog-drainer/)
 
-    TiDB Lightning 集成了 Loader 的逻辑导入数据功能，参见 [TiDB Lightning TiDB-backend 文档](/tidb-lightning/tidb-lightning-tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)，由 TiDB Lightning 统一提供全量数据恢复功能。
+## 数据迁入
 
-## 数据迁移解决方案
+[TiDB Data Migration (DM)](https://pingcap.com/docs-cn/tidb-data-migration/stable/overview/) 是将 MySQL/MariaDB 数据迁移到 TiDB 的工具，支持全量数据和增量数据的迁移。
 
-针对 TiDB 的 2.1，3.0 以及 3.1 版本，下面给出典型业务场景下的数据迁移方案。
+基本信息：
 
-### TiDB 3.0 全链路数据迁移方案
-
-#### MySQL 数据迁移到 TiDB
-
-如果 MySQL 数据量在 TB 级别以上，推荐迁移步骤如下：
-
-1. 使用 Mydumper 导出 MySQL 全量数据
-2. 使用 TiDB Lightning 将 MySQL 全量备份数据导入 TiDB 集群
-3. 使用 DM 同步 MySQL 增量数据到 TiDB
-
-如果 MySQL 数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL 数据到 TiDB（迁移的过程包括全量导入和增量的同步）。
-
-#### TiDB 集群数据的同步
+- DM 的输入：MySQL/MariaDB
+- DM 的输出：TiDB 集群
+- 适用 TiDB 版本：所有版本
+- Kubernetes 支持：开发中
 
-使用 TiDB Binlog 将 TiDB 数据同步到下游 TiDB/MySQL。
+如果数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL/MariaDB 数据到 TiDB（迁移的过程包括全量数据的导出导入和增量数据的同步）。
 
-#### TiDB 集群数据的全量备份及恢复
+如果数据量在 TB 级别，推荐的迁移步骤如下：
 
-推荐步骤：
+1. 使用 [Dumpling](/export-or-backup-using-dumpling.md) 导出 MySQL/MariaDB 全量数据。
+2. 使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 将全量导出数据导入 TiDB 集群。
+3. 使用 DM 迁移 MySQL/MariaDB 增量数据到 TiDB。
 
-1. 使用 Mydumper 进行全量数据的备份
-2. 使用 TiDB Lightning 将全量数据恢复到 TiDB/MySQL
+> **注意：**
+>
+> - 原 Syncer 工具已停止维护，不再推荐使用，相关场景请使用 DM 的增量迁移模式进行替代。

export-or-backup-using-dumpling.md

@@ -0,0 +1,114 @@
+---
+title: 使用 Dumpling 导出或备份 TiDB 数据
+summary: 使用新的导出工具 Dumpling 导出或者备份数据。
+category: how-to
+---
+
+# 使用 Dumpling 导出或备份 TiDB 数据
+
+本文档介绍如何使用数据导出工具 [Dumpling](https://github.com/pingcap/dumpling)。该工具可以把存储在 TiDB 中的数据导出为 SQL 或者 CSV 格式，可以用于完成逻辑上的全量备份或者导出。
+
+使用 Dumpling 时，需要在已经启动的集群上执行导出命令。本文假设在 `127.0.0.1:4000` 有一个 TiDB 实例，并且这个 TiDB 实例中有无密码的 root 用户。 
+
+## 从 TiDB 导出数据
+
+使用如下命令导出数据：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+dumpling \
+  -u root \
+  -P 4000 \
+  -H 127.0.0.1 \
+  --filetype sql \
+  --threads 32 \
+  -o /tmp/test \
+  -F $(( 1024 * 1024 * 256 ))
+```
+
+上述命令中，`-H`、`-P`、`-u` 分别是地址，端口，用户。如果需要密码验证，可以用 `-p $YOUR_SECRET_PASSWORD` 传给 Dumpling。
+
+默认情况下，除了系统数据库中的表之外，Dumpling 会导出整个数据库的表。你可以使用 `--where <SQL where expression>` 来选定要导出的记录。假如导出数据的格式是 CSV（使用 `--filetype csv` 即可导出 CSV 文件），还可以使用 `--sql <SQL>` 导出指定 SQL 选择出来的记录，例如，导出 `test.sbtest1` 中所有 `id < 100` 的记录：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+./dumpling \
+  -u root \
+  -P 4000 \
+  -H 127.0.0.1 \
+  -o /tmp/test \
+  --filetype csv \
+  --sql "select * from `test`.`sbtest1` where id < 100"
+```
+
+注意，`--sql` 选项暂时仅仅可用于导出 csv 的场景。但是仍旧可以用 `--where` 来过滤要导出的行，使用以下指令，可以导出所有 `id < 100` 的记录：
+
+> **注意：**
+> 
+> 这里需要在要导出的所有表上执行 `select * from <table-name> where id < 100` 语句。如果部分表没有指定的字段，那么导出会失败。
+
+{{< copyable "shell-regular" >}}
+
+```shell
+./dumpling \
+  -u root \
+  -P 4000 \
+  -H 127.0.0.1 \
+  -o /tmp/test \
+  --where "id < 100"
+```
+
+> **注意：**
+> 
+> 目前 Dumpling 不支持仅导出用户指定的某几张表（即 `-T` 标志，见[这个 issue](https://github.com/pingcap/dumpling/issues/76)）。如果你确实需要这些功能，可以先使用 [MyDumper](/backup-and-restore-using-mydumper-lightning.md)。
+
+默认情况下，导出的文件会存储到 `./export-<current local time>` 目录下。常用参数如下：
+
+- `-o` 用于选择存储导出文件的目录。
+- `-F` 选项用于指定单个文件的最大大小（和 MyDumper 不同，这里的单位是字节）。
+- `-r` 选项用于指定单个文件的最大记录数（或者说，数据库中的行数）。
+
+利用以上参数可以让 Dumpling 的并行度更高。
+
+还有一个尚未在上面展示出来的标志是 `--consistency <consistency level>`，这个标志控制导出数据“一致性保证”的方式。对于 TiDB 来说，默认情况下，会通过获取某个时间戳的快照来保证一致性（即 `--consistency snapshot`）。在使用 snapshot 来保证一致性的时候，可以使用 `--snapshot` 参数指定要备份的时间戳。还可以使用以下的一致性级别：
+
+- `flush`：使用 [`FLUSH TABLES WITH READ LOCK`](https://dev.mysql.com/doc/refman/8.0/en/flush.html#flush-tables-with-read-lock) 来保证一致性。
+- `snapshot`：获取指定时间戳的一致性快照并导出。
+- `lock`：为待导出的所有表上读锁。
+- `none`：不做任何一致性保证。
+- `auto`：对 MySQL 使用 `flush`，对 TiDB 使用 `snapshot`。
+
+一切完成之后，你应该可以在 `/tmp/test` 看到导出的文件了：
+
+```shell
+$ ls -lh /tmp/test | awk '{print $5 "\t" $9}'
+
+140B  metadata
+66B   test-schema-create.sql
+300B  test.sbtest1-schema.sql
+190K  test.sbtest1.0.sql
+300B  test.sbtest2-schema.sql
+190K  test.sbtest2.0.sql
+300B  test.sbtest3-schema.sql
+190K  test.sbtest3.0.sql
+```
+
+另外，假如数据量非常大，可以提前调长 GC 时间，以避免因为导出过程中发生 GC 导致导出失败：
+
+{{< copyable "sql" >}}
+
+```sql
+update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time';
+```
+
+在操作结束之后，再将 GC 时间调回原样（默认是 `10m`）：
+
+{{< copyable "sql" >}}
+
+```sql
+update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time';
+```
+
+最后，所有的这些导出数据都可以用 [Lightning](/tidb-lightning/tidb-lightning-tidb-backend.md) 导入回 TiDB。