dumpling: update and refine dumpling doc (pingcap#4857)

* refine dumpling doc * add alias * replace mydumper with dumpling, fix ci * address comment * fix dead link * address comment * Update migrate-from-mysql-dumpling-files.md * delete 2 mydumper name * address comment * Update dumpling-overview.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> * Update dumpling-overview.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> * Update dumpling-overview.md * address comments * address comment Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>
JinheLin · Nov 12, 2020 · d7d4c13 · d7d4c13
1 parent e960457
commit d7d4c13
Show file tree

Hide file tree

Showing 14 changed files with 38 additions and 39 deletions.
diff --git a/TOC.md b/TOC.md
@@ -46,12 +46,12 @@
 + 数据迁移
   + [概述](/migration-overview.md)
   + 从 MySQL 迁移至 TiDB
-    + [从 Mydumper 文件迁移](/migrate-from-mysql-mydumper-files.md)
+    + [使用 Dumpling 与 TiDB Lightning 进行全量迁移](/migrate-from-mysql-dumpling-files.md)
     + [使用 DM 工具从 Amazon Aurora MySQL 迁移](/migrate-from-aurora-mysql-database.md)
   + 从 CSV 文件迁移至 TiDB
     + [使用 TiDB Lightning 导入 CSV 文件](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md)
     + [使用 LOAD DATA 语句导入 CSV 文件](/sql-statements/sql-statement-load-data.md)
-  + [从 SQL 文件迁移到 TiDB](/migrate-from-mysql-mydumper-files.md)
+  + [从 SQL 文件迁移到 TiDB](/migrate-from-mysql-dumpling-files.md)
 + 运维操作
   + 升级 TiDB 版本
     + [使用 TiUP 升级（推荐）](/upgrade-tidb-using-tiup.md)

diff --git a/_index.md b/_index.md
@@ -46,10 +46,10 @@ TiDB 是 PingCAP 公司自主设计、研发的开源分布式关系型数据库
 <ColumnTitle>数据迁移</ColumnTitle>
 
 - [概述](/migration-overview.md)
-- [从 Mydumper 文件迁移](/migrate-from-mysql-mydumper-files.md)
+- [使用 Dumpling 与 TiDB Lightning 进行全量迁移](/migrate-from-mysql-dumpling-files.md)
 - [从 Aurora MySQL 迁移](/migrate-from-aurora-mysql-database.md)
 - [从 CSV 文件迁移](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md)
-- [从 SQL 文件迁移](/migrate-from-mysql-mydumper-files.md)
+- [从 SQL 文件迁移](/migrate-from-mysql-dumpling-files.md)
 
 </NavColumn>
 

diff --git a/br/backup-and-restore-tool.md b/br/backup-and-restore-tool.md
@@ -6,7 +6,7 @@ aliases: ['/docs-cn/dev/br/backup-and-restore-tool/','/docs-cn/dev/reference/too
 
 # 使用 BR 进行备份与恢复
 
-[Backup & Restore](https://github.com/pingcap/br)（以下简称 BR）是 TiDB 分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 [`dumpling`](/dumpling-overview.md) 和 [`mydumper`/`loader`](/backup-and-restore-using-mydumper-lightning.md)，BR 更适合大数据量的场景。本文档介绍了 BR 的使用限制、工作原理、命令行描述、备份恢复用例以及最佳实践。
+[Backup & Restore](https://github.com/pingcap/br)（以下简称 BR）是 TiDB 分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 [`dumpling`](/backup-and-restore-using-dumpling-lightning.md) 和 [`mydumper`](/backup-and-restore-using-mydumper-lightning.md)，BR 更适合大数据量的场景。本文档介绍了 BR 的使用限制、工作原理、命令行描述、备份恢复用例以及最佳实践。
 
 ## 使用限制
 

diff --git a/dumpling-overview.md b/dumpling-overview.md
@@ -217,6 +217,14 @@ Dumpling 可以通过 `--snapshot` 指定导出某个 [tidb_snapshot](/read-hist
 
 即可导出 TSO 为 `417773951312461825` 或 `2020-07-02 17:12:45` 时的 TiDB 历史数据快照。
 
+### 控制导出 TiDB 大表时的内存使用
+
+Dumpling 导出 TiDB 较大单表时，可能会因为导出数据过大导致 TiDB 内存溢出 (OOM)，从而使连接中断导出失败。可以通过以下参数减少 TiDB 的内存使用。
+
++ 设置 `--rows` 参数，可以划分导出数据区块减少 TiDB 扫描数据的内存开销，同时也可开启表内并发提高导出效率。
++ 调小 `--tidb-mem-quota-query` 参数到 `8589934592` (8GB) 或更小。该参数默认为 32GB，可控制 TiDB 单条查询语句的内存使用。
++ 调整 `--params "tidb_distsql_scan_concurrency=5"` 参数，即设置导出时的 session 变量 [`tidb_distsql_scan_concurrency`](/system-variables.md#tidb_distsql_scan_concurrency) 从而减少 TiDB scan 操作的并发度。
+
 ### 导出大规模数据时的 TiDB GC 设置
 
 如果导出的 TiDB 版本大于 v4.0.0，并且 Dumpling 可以访问 TiDB 集群的 PD 地址，Dumpling 会自动配置延长 GC 时间且不会对原集群造成影响。v4.0.0 之前的版本依然需要手动修改 GC。
@@ -280,3 +288,4 @@ update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life
 | --output-filename-template | 以 [golang template](https://golang.org/pkg/text/template/#hdr-Arguments) 格式表示的数据文件名格式 <br/> 支持 `{{.DB}}`、`{{.Table}}`、`{{.Index}}` 三个参数 <br/> 分别表示数据文件的库名、表名、分块 ID | '{{.DB}}.{{.Table}}.{{.Index}}' |
 | --status-addr | Dumpling 的服务地址，包含了 Prometheus 拉取 metrics 信息及 pprof 调试的地址 | ":8281" |
 | --tidb-mem-quota-query | 单条 dumpling 命令导出 SQL 语句的内存限制，单位为 byte，默认为 32 GB | 34359738368 |
+| --params | 为需导出的数据库连接指定 session 变量，可接受的格式: "character_set_client=latin1,character_set_connection=latin1" |
diff --git a/faq/deploy-and-maintain-faq.md b/faq/deploy-and-maintain-faq.md
@@ -468,7 +468,7 @@ TiKV 的内存占用主要来自于 RocksDB 的 block-cache，默认为系统总
 #### TiDB 集群容量 QPS 与节点数之间关系如何，和 MySQL 对比如何？
 
 - 在 10 节点内，TiDB 写入能力（Insert TPS）和节点数量基本成 40% 线性递增，MySQL 由于是单节点写入，所以不具备写入扩展能力。
-- MySQL 读扩容可以通过添加从库进行扩展，但写流量无法扩展，只能通过分库分表，而分库分表有很多问题，具体参考[方案虽好，成本先行：数据库 Sharding+Proxy 实践解析](http://t.cn/RTD18qV)。
+- MySQL 读扩容可以通过添加从库进行扩展，但写流量无法扩展，只能通过分库分表，而分库分表有很多问题，具体参考[方案虽好，成本先行：数据库 Sharding+Proxy 实践解析](http://dbaplus.cn/news-11-1854-1.html)。
 - TiDB 不管是读流量、还是写流量都可以通过添加节点快速方便的进行扩展。
 
 #### 我们的 DBA 测试过 MySQL 性能，单台 TiDB 的性能没有 MySQL 性能那么好？

diff --git a/faq/migration-tidb-faq.md b/faq/migration-tidb-faq.md
@@ -8,14 +8,6 @@ aliases: ['/docs-cn/dev/faq/migration-tidb-faq/']
 
 ## 全量数据导出导入
 
-### TiDB 是否支持 Mydumper
-
-支持，参见 [Mydumper 使用文档](/mydumper-overview.md)。
-
-### TiDB 是否支持 Loader
-
-支持，参见 [Loader 使用文档](/loader-overview.md)。
-
 ### 如何将一个运行在 MySQL 上的应用迁移到 TiDB 上？
 
 TiDB 支持绝大多数 MySQL 语法，一般不需要修改代码。

diff --git a/get-started-with-tidb-lightning.md b/get-started-with-tidb-lightning.md
@@ -5,7 +5,7 @@ aliases: ['/docs-cn/dev/get-started-with-tidb-lightning/','/docs-cn/dev/how-to/g
 
 # TiDB Lightning 教程
 
-TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，目前支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning：
+TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，目前支持 SQL 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning：
 
 - **迅速**导入**大量新**数据。
 - 备份恢复所有数据。
@@ -20,21 +20,20 @@ TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，
 
 ## 准备全量备份数据
 
-我们使用 [`mydumper`](/mydumper-overview.md) 从 MySQL 导出数据，如下：
+我们使用 [`dumpling`](/dumpling-overview.md) 从 MySQL 导出数据，如下：
 
 {{< copyable "shell-regular" >}}
 
 ```sh
-./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/
+./bin/dumpling -h 127.0.0.1 -P 3306 -u root -t 16 -F 256MB -B test -f 'test.t[12]' -o /data/my_database/
 ```
 
 其中：
 
 - `-B test`：从 `test` 数据库导出。
-- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。
+- `-f test.t[12]`：只导出 `test.t1` 和 `test.t2` 这两个表。
 - `-t 16`：使用 16 个线程导出数据。
-- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。
-- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。
+- `-F 256MB`：将每张表切分成多个文件，每个文件大小约为 256 MB。
 
 这样全量备份数据就导出到了 `/data/my_database` 目录中。
 
@@ -71,7 +70,7 @@ TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，
     "sorted-kv-dir" = "/mnt/ssd/sorted-kv-dir"
 
     [mydumper]
-    # Mydumper 源数据目录。
+    # 源数据目录。
     data-source-dir = "/data/my_datasource/"
 
     [tidb]

diff --git a/migrate-from-mysql-mydumper-files.md → migrate-from-mysql-dumpling-files.md b/migrate-from-mysql-mydumper-files.md → migrate-from-mysql-dumpling-files.md
@@ -1,12 +1,12 @@
 ---
 title: 从 MySQL SQL 文件迁移数据
 summary: 使用 TiDB Lightning 从 MySQL 迁移数据。
-aliases: ['/docs-cn/dev/migrate-from-mysql-mydumper-files/']
+aliases: ['/docs-cn/dev/migrate-from-mysql-mydumper-files/','/zh/tidb/dev/migrate-from-mysql-mydumper-files/']
 ---
 
 # 从 MySQL SQL 文件迁移数据
 
-本文介绍如何使用 TiDB Lightning 从 MySQL SQL 文件迁移数据到 TiDB。关于如何生成 MySQL SQL 文件，可以参考 [Mydumper](/mydumper-overview.md) 或者 [Dumpling](/dumpling-overview.md) 文档。
+本文介绍如何使用 TiDB Lightning 从 MySQL SQL 文件迁移数据到 TiDB。关于如何生成 MySQL SQL 文件，可以参考 [Dumpling](/dumpling-overview.md) 文档。
 
 ## 第 1 步：部署 TiDB Lightning
 

diff --git a/migration-overview.md b/migration-overview.md
@@ -12,24 +12,24 @@ aliases: ['/docs-cn/dev/migration-overview/','/docs-cn/dev/data-migration-route'
 
 目前推荐使用以下两种方式将 MySQL 数据迁移到 TiDB。
 
-- [使用 Mydumper 和 TiDB Lightning 迁移全量数据](#使用-mydumper-和-tidb-lightning-迁移全量数据)
+- [使用 Dumpling 和 TiDB Lightning 迁移全量数据](#使用-dumpling-和-tidb-lightning-迁移全量数据)
 - [使用 DM 迁移数据](#使用-dm-迁移数据)
 
-### 使用 Mydumper 和 TiDB Lightning 迁移全量数据
+### 使用 Dumpling 和 TiDB Lightning 迁移全量数据
 
 #### 适合场景
 
 适合 MySQL 全量数据的大小大于 1TB 的场景。该方案只能迁移全量数据，如果需要继续同步增量数据，需要再使用 TiDB Data Migration (DM) 创建增量同步任务。
 
 #### 迁移方法
 
-使用 Mydumper 导出 MySQL 的全量数据，再使用 TiDB Lightning 将全量数据导入到 TiDB，详细信息可参考[从 Mydumper 文件迁移](/migrate-from-mysql-mydumper-files.md)
+使用 Dumpling 导出 MySQL 的全量数据，再使用 TiDB Lightning 将全量数据导入到 TiDB，详细信息可参考[使用 Dumpling 与 TiDB Lightning 进行全量迁移](/migrate-from-mysql-dumpling-files.md)
 
 ### 使用 DM 迁移数据
 
 #### 适合场景
 
-适合迁移 MySQL 全量数据并同步增量数据的场景，且全量数据的大小小于 1TB。如果全量数据的大小大于 1TB，建议使用 Mydumper 和 TiDB Lightning 导入全量数据后，再使用 DM 同步增量数据。
+适合迁移 MySQL 全量数据并同步增量数据的场景，且全量数据的大小小于 1TB。如果全量数据的大小大于 1TB，建议使用 Dumpling 和 TiDB Lightning 导入全量数据后，再使用 DM 同步增量数据。
 
 #### 迁移方法
 
@@ -59,4 +59,4 @@ DM 支持将 MySQL 全量数据迁移到 TiDB，并同步 MySQL 的增量数据
 
 ### 从 SQL 文件迁移到 TiDB
 
-该部分内容与[使用 Mydumper 和 TiDB Lightning 迁移全量数据](#使用-mydumper-和-tidb-lightning-迁移全量数据)相同。
+该部分内容与[使用 Dumpling 和 TiDB Lightning 迁移全量数据](#使用-dumpling-和-tidb-lightning-迁移全量数据)相同。
diff --git a/tidb-lightning/deploy-tidb-lightning.md b/tidb-lightning/deploy-tidb-lightning.md
@@ -54,21 +54,20 @@ aliases: ['/docs-cn/dev/tidb-lightning/deploy-tidb-lightning/','/docs-cn/dev/ref
 
 ## 导出数据
 
-使用 [`mydumper`](/mydumper-overview.md) 从 MySQL 导出数据，如下：
+使用 [`dumpling`](/dumpling-overview.md) 从 MySQL 导出数据，如下：
 
 {{< copyable "shell-regular" >}}
 
 ```sh
-./bin/mydumper -h 127.0.0.1 -P 3306 -u root -t 16 -F 256 -B test -T t1,t2 --skip-tz-utc -o /data/my_database/
+./bin/dumpling -h 127.0.0.1 -P 3306 -u root -t 16 -F 256MB -B test -f 'test.t[12]' -o /data/my_database/
 ```
 
 其中：
 
 - `-B test`：从 `test` 数据库导出。
-- `-T t1,t2`：只导出 `t1` 和 `t2` 这两个表。
+- `-f test.t[12]`：只导出 `test.t1` 和 `test.t2` 这两个表。
 - `-t 16`：使用 16 个线程导出数据。
-- `-F 256`：将每张表切分成多个文件，每个文件大小约为 256 MB。
-- `--skip-tz-utc`：添加这个参数则会忽略掉 TiDB 与导数据的机器之间时区设置不一致的情况，禁止自动转换。
+- `-F 256MB`：将每张表切分成多个文件，每个文件大小约为 256 MB。
 
 如果数据源是 CSV 文件，请参考 [CSV 支持](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md)获取配置信息。
 
@@ -101,7 +100,7 @@ TiDB Lightning 可随 TiDB 集群一起用 [TiDB Ansible 部署](/online-deploym
         # 提供监控告警的端口。需对监控服务器 (monitoring_server) 开放。
         tidb_lightning_pprof_port: 8289
 
-        # 获取数据源（Mydumper SQL dump 或 CSV）的路径。
+        # 获取数据源（Dumpling SQL dump 或 CSV）的路径。
         data_source_dir: "{{ deploy_dir }}/mydumper"
         ```
 

diff --git a/tidb-lightning/tidb-lightning-configuration.md b/tidb-lightning/tidb-lightning-configuration.md
@@ -128,7 +128,7 @@ read-block-size = 65536 # Byte (默认为 64 KB)
 # 取值范围为（0 <= batch-import-ratio < 1）。
 batch-import-ratio = 0.75
 
-# mydumper 本地源数据目录。
+# 本地源数据目录。
 data-source-dir = "/data/my_database"
 # 如果 no-schema = true，那么 TiDB Lightning 假设目标 TiDB 集群上
 # 已有表结构，并且不会执行 `CREATE TABLE` 语句。

diff --git a/tidb-lightning/tidb-lightning-faq.md b/tidb-lightning/tidb-lightning-faq.md
@@ -89,7 +89,7 @@ ADMIN CHECKSUM TABLE `schema`.`table`;
 
 TiDB Lightning 只支持两种格式的数据源：
 
-1. [Mydumper](/mydumper-overview.md) 生成的 SQL dump
+1. [Dumpling](/dumpling-overview.md) 生成的 SQL dump
 2. 储存在本地文件系统的 [CSV](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md) 文件
 
 ## 我已经在下游创建好库和表了，TiDB Lightning 可以忽略建库建表操作吗？

diff --git a/tidb-lightning/tidb-lightning-overview.md b/tidb-lightning/tidb-lightning-overview.md
@@ -7,7 +7,7 @@ aliases: ['/docs-cn/dev/tidb-lightning/tidb-lightning-overview/','/docs-cn/dev/r
 
 TiDB Lightning 是一个将全量数据高速导入到 TiDB 集群的工具，可[在此下载](/download-ecosystem-tools.md#tidb-lightning)。
 
-TiDB Lightning 有以下两个主要的使用场景：一是大量新数据的快速导入；二是全量备份数据的恢复。目前，Lightning 支持 Mydumper 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning：
+TiDB Lightning 有以下两个主要的使用场景：一是大量新数据的快速导入；二是全量备份数据的恢复。目前，Lightning 支持 Dumpling 或 CSV 输出格式的数据源。你可以在以下两种场景下使用 Lightning：
 
 - **迅速**导入**大量新**数据。
 - 恢复所有备份数据。

diff --git a/troubleshoot-tidb-lightning.md b/troubleshoot-tidb-lightning.md
@@ -21,7 +21,7 @@ TiDB Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的
 
 **原因 2**：表结构太复杂。
 
-每条索引都会额外增加键值对。如果有 N 条索引，实际导入的大小就差不多是 Mydumper 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。
+每条索引都会额外增加键值对。如果有 N 条索引，实际导入的大小就差不多是 Dumpling 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。
 
 **原因 3**: 单个文件过大。
 
@@ -44,7 +44,7 @@ strict-format = true
 
 1. 这张表可能本身已有数据，影响最终结果。
 2. 如果目标数据库的校验和全是 0，表示没有发生任何导入，有可能是集群太忙无法接收任何数据。
-3. 如果数据源是由机器生成而不是从 Mydumper 备份的，需确保数据符合表的限制，例如：
+3. 如果数据源是由机器生成而不是从 Dumpling 备份的，需确保数据符合表的限制，例如：
 
     * 自增 (AUTO_INCREMENT) 的列需要为正数，不能为 0。
     * 唯一键和主键 (UNIQUE and PRIMARY KEYs) 不能有重复的值。