From c543ad7f5fa531070cd5e14963d001c611599fa3 Mon Sep 17 00:00:00 2001 From: Xuecheng Zhang Date: Fri, 5 Jun 2020 18:18:35 +0800 Subject: [PATCH 1/6] cherry pick #3519 to release-2.1 Signed-off-by: sre-bot --- TOC.md | 14 ++++ ecosystem-tool-user-case.md | 39 ++++++++++ ecosystem-tool-user-guide.md | 81 ++++++++++++++++++++ export-or-backup-using-dumpling.md | 114 +++++++++++++++++++++++++++++ 4 files changed, 248 insertions(+) create mode 100644 ecosystem-tool-user-case.md create mode 100644 ecosystem-tool-user-guide.md create mode 100644 export-or-backup-using-dumpling.md diff --git a/TOC.md b/TOC.md index d616c343b039..9c0ec7e73a75 100644 --- a/TOC.md +++ b/TOC.md @@ -55,8 +55,17 @@ - [从 CSV 迁移](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md) + 运维 - [Ansible 常见运维操作](/maintain-tidb-using-ansible.md) +<<<<<<< HEAD + [备份与恢复](/backup-and-restore.md) - [定位慢查询](/identify-slow-queries.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) +>>>>>>> e57d8a8... reference refine the ecosystem tools user guide (#3519) + 扩容缩容 - [使用 Ansible 扩容缩容](/scale-tidb-using-ansible.md) + 升级 @@ -264,6 +273,11 @@ - [常见错误修复](/tidb-binlog/handle-tidb-binlog-errors.md) - [FAQ](/tidb-binlog/tidb-binlog-faq.md) + 周边工具 +<<<<<<< HEAD +======= + - [功能概览](/ecosystem-tool-user-guide.md) + - [适用场景](/ecosystem-tool-user-case.md) +>>>>>>> e57d8a8... reference refine the ecosystem tools user guide (#3519) - [Mydumper](/mydumper-overview.md) - [Loader](/loader-overview.md) - [Syncer](/syncer-overview.md) diff --git a/ecosystem-tool-user-case.md b/ecosystem-tool-user-case.md new file mode 100644 index 000000000000..407418881f13 --- /dev/null +++ b/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)。 diff --git a/ecosystem-tool-user-guide.md b/ecosystem-tool-user-guide.md new file mode 100644 index 000000000000..509d6b707e9d --- /dev/null +++ b/ecosystem-tool-user-guide.md @@ -0,0 +1,81 @@ +--- +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 生态工具功能概览 + +本文档从生态工具的功能出发，介绍部分生态工具的功能以及它们之间的替代关系。 + +## 全量导出 + +[Dumpling](/export-or-backup-using-dumpling.md) 是一个用于从 MySQL/TiDB 进行全量逻辑导出的工具。 + +基本信息： + +- Dumpling 的输入：MySQL/TiDB 集群 +- Dumpling 的输出：SQL/CSV 文件 +- 适用 TiDB 版本：所有版本 +- Kubernetes 支持：尚未支持 + +## 全量导入 + +[TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 是一个用于将全量数据导入到 TiDB 集群的工具。 + +使用 TiDB Lightning 导入数据到 TiDB 时，有两种模式： + +- `importer` 模式：以 TiKV-importer 作为后端，这种模式一般用于导入大量的数据（TB 级别）到新集群，但在数据导入过程中集群无法提供正常的服务。 +- `tidb` 模式：以 TiDB/MySQL 作为后端，这种模式相比 `importer` 模式的导入速度较慢，但是可以在线导入，同时也支持将数据导入到 MySQL。 + +基本信息： + +- Lightning 的输入： + - Dumpling 输出文件 + - 其他格式兼容的 CSV 文件 +- 适用 TiDB 版本：v2.1 及以上 +- Kubernetes 支持：[使用 TiDB Lightning 快速恢复 Kubernetes 上的 TiDB 集群数据](https://pingcap.com/docs-cn/tidb-in-kubernetes/v1.0/restore-data-using-tidb-lightning/) + +> **注意：** +> +> 原 Loader 工具已停止维护，不再推荐使用。相关场景请使用 TiDB Lightning 的 `tidb` 模式进行替代，详细信息请参考 [TiDB Lightning TiDB-backend 文档](/tidb-lightning/tidb-lightning-tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)。 + +## 备份和恢复 + +[Dumpling](/export-or-backup-using-dumpling.md) 可用于将 TiDB 集群备份到 SQL 或 CSV 格式的文件，可参考[全量导出](#全量导出)。 + +[TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 可用于将 Dumpling 导出的 SQL 或 CSV 格式的文件恢复到 TiDB 集群，可参考 [全量导入](#全量导入)。 + +## TiDB 增量日志同步 + +[TiDB Binlog](/tidb-binlog/tidb-binlog-overview.md) 是收集 TiDB 的增量 binlog 数据，并提供准实时同步和备份的工具。该工具可用于 TiDB 集群间的增量数据同步，如将其中一个 TiDB 集群作为另一个 TiDB 集群的从集群。 + +基本信息： + +- TiDB Binlog 的输入：TiDB 集群 +- TiDB Binlog 的输出：TiDB 集群、MySQL、Kafka 或者增量备份文件 +- 适用 TiDB 版本：v2.1 及以上 +- 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 Data Migration (DM)](https://pingcap.com/docs-cn/tidb-data-migration/stable/overview/) 是将 MySQL/MariaDB 数据迁移到 TiDB 的工具，支持全量数据和增量数据的迁移。 + +基本信息： + +- DM 的输入：MySQL/MariaDB +- DM 的输出：TiDB 集群 +- 适用 TiDB 版本：所有版本 +- Kubernetes 支持：开发中 + +如果数据量在 TB 级别以下，推荐直接使用 DM 迁移 MySQL/MariaDB 数据到 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。 + +> **注意：** +> +> - 原 Syncer 工具已停止维护，不再推荐使用，相关场景请使用 DM 的增量迁移模式进行替代。 diff --git a/export-or-backup-using-dumpling.md b/export-or-backup-using-dumpling.md new file mode 100644 index 000000000000..3d1ebf7bb9e4 --- /dev/null +++ b/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 ` 来选定要导出的记录。假如导出数据的格式是 CSV（使用 `--filetype csv` 即可导出 CSV 文件），还可以使用 `--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 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-` 目录下。常用参数如下： + +- `-o` 用于选择存储导出文件的目录。 +- `-F` 选项用于指定单个文件的最大大小（和 MyDumper 不同，这里的单位是字节）。 +- `-r` 选项用于指定单个文件的最大记录数（或者说，数据库中的行数）。 + +利用以上参数可以让 Dumpling 的并行度更高。 + +还有一个尚未在上面展示出来的标志是 `--consistency `，这个标志控制导出数据“一致性保证”的方式。对于 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。 From dc0643b9b72e09f85856337b0a86935023331e04 Mon Sep 17 00:00:00 2001 From: Xuecheng Zhang Date: Fri, 5 Jun 2020 18:37:11 +0800 Subject: [PATCH 2/6] TOC: resolve conflicts --- TOC.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/TOC.md b/TOC.md index 9c0ec7e73a75..30ff33cbbd38 100644 --- a/TOC.md +++ b/TOC.md @@ -55,17 +55,10 @@ - [从 CSV 迁移](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md) + 运维 - [Ansible 常见运维操作](/maintain-tidb-using-ansible.md) -<<<<<<< HEAD - + [备份与恢复](/backup-and-restore.md) - - [定位慢查询](/identify-slow-queries.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) ->>>>>>> e57d8a8... reference refine the ecosystem tools user guide (#3519) + - [定位慢查询](/identify-slow-queries.md) + 扩容缩容 - [使用 Ansible 扩容缩容](/scale-tidb-using-ansible.md) + 升级 @@ -273,11 +266,8 @@ - [常见错误修复](/tidb-binlog/handle-tidb-binlog-errors.md) - [FAQ](/tidb-binlog/tidb-binlog-faq.md) + 周边工具 -<<<<<<< HEAD -======= - [功能概览](/ecosystem-tool-user-guide.md) - [适用场景](/ecosystem-tool-user-case.md) ->>>>>>> e57d8a8... reference refine the ecosystem tools user guide (#3519) - [Mydumper](/mydumper-overview.md) - [Loader](/loader-overview.md) - [Syncer](/syncer-overview.md) From b6cd18880307be3b414f5e8e7cca08a10d683cb7 Mon Sep 17 00:00:00 2001 From: Xuecheng Zhang Date: Fri, 5 Jun 2020 18:43:53 +0800 Subject: [PATCH 3/6] *: udpate aliases --- ecosystem-tool-user-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ecosystem-tool-user-guide.md b/ecosystem-tool-user-guide.md index 509d6b707e9d..32af0197aade 100644 --- a/ecosystem-tool-user-guide.md +++ b/ecosystem-tool-user-guide.md @@ -1,7 +1,7 @@ --- 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/'] +aliases: ['/docs-cn/v2.1/reference/tools/user-guide/','/docs-cn/v2.1/how-to/migrate/from-mysql/', '/docs-cn/v2.1/how-to/migrate/incrementally-from-mysql/', '/docs-cn/v2.1/how-to/migrate/overview/', '/docs-cn/v2.1/reference/tools/use-guide/'] --- # TiDB 生态工具功能概览 From 590389ba97fdb40426867f2f182872fc4a0522e2 Mon Sep 17 00:00:00 2001 From: Xuecheng Zhang Date: Fri, 5 Jun 2020 18:49:53 +0800 Subject: [PATCH 4/6] TOC: fix dead link --- TOC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TOC.md b/TOC.md index 30ff33cbbd38..b1dd90cb8046 100644 --- a/TOC.md +++ b/TOC.md @@ -56,7 +56,7 @@ + 运维 - [Ansible 常见运维操作](/maintain-tidb-using-ansible.md) + [备份与恢复] - - [使用 Mydumper 和 TiDB Lightning 进行备份与恢复](/backup-and-restore-using-mydumper-lightning.md) + - [使用 Mydumper 和 Loader 进行备份与恢复](/backup-and-restore.md) - [使用 Dumpling 导出或备份 TiDB 数据](/export-or-backup-using-dumpling.md) - [定位慢查询](/identify-slow-queries.md) + 扩容缩容 From ec9c5f6264ea3c87ace83058af72985f2be0c9af Mon Sep 17 00:00:00 2001 From: Xuecheng Zhang Date: Fri, 5 Jun 2020 18:54:11 +0800 Subject: [PATCH 5/6] Update ecosystem-tool-user-guide.md --- ecosystem-tool-user-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ecosystem-tool-user-guide.md b/ecosystem-tool-user-guide.md index 32af0197aade..f9c780eea35c 100644 --- a/ecosystem-tool-user-guide.md +++ b/ecosystem-tool-user-guide.md @@ -38,7 +38,7 @@ aliases: ['/docs-cn/v2.1/reference/tools/user-guide/','/docs-cn/v2.1/how-to/migr > **注意：** > -> 原 Loader 工具已停止维护，不再推荐使用。相关场景请使用 TiDB Lightning 的 `tidb` 模式进行替代，详细信息请参考 [TiDB Lightning TiDB-backend 文档](/tidb-lightning/tidb-lightning-tidb-backend.md#从-loader-迁移到-tidb-lightning-tidb-backend)。 +> 原 Loader 工具已停止维护，不再推荐使用。相关场景请使用 TiDB Lightning 的 `tidb` 模式进行替代，详细信息请参考 [TiDB Lightning TiDB-backend 文档](/tidb-lightning/tidb-lightning-overview.md)。 ## 备份和恢复 From 6c94f942450f165ee746b0f09785740abae5874d Mon Sep 17 00:00:00 2001 From: Xuecheng Zhang Date: Fri, 5 Jun 2020 18:57:06 +0800 Subject: [PATCH 6/6] Update export-or-backup-using-dumpling.md --- export-or-backup-using-dumpling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/export-or-backup-using-dumpling.md b/export-or-backup-using-dumpling.md index 3d1ebf7bb9e4..9203e39507fc 100644 --- a/export-or-backup-using-dumpling.md +++ b/export-or-backup-using-dumpling.md @@ -62,7 +62,7 @@ dumpling \ > **注意：** > -> 目前 Dumpling 不支持仅导出用户指定的某几张表（即 `-T` 标志，见[这个 issue](https://github.com/pingcap/dumpling/issues/76)）。如果你确实需要这些功能，可以先使用 [MyDumper](/backup-and-restore-using-mydumper-lightning.md)。 +> 目前 Dumpling 不支持仅导出用户指定的某几张表（即 `-T` 标志，见[这个 issue](https://github.com/pingcap/dumpling/issues/76)）。如果你确实需要这些功能，可以先使用 [MyDumper](/mydumper-overview.md)。 默认情况下，导出的文件会存储到 `./export-` 目录下。常用参数如下： @@ -111,4 +111,4 @@ update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_lif update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time'; ``` -最后，所有的这些导出数据都可以用 [Lightning](/tidb-lightning/tidb-lightning-tidb-backend.md) 导入回 TiDB。 +最后，所有的这些导出数据都可以用 [Lightning](/tidb-lightning/tidb-lightning-overview.md) 导入回 TiDB。