使用 Dumpling 导出数据

使用数据导出工具Dumpling，你可以把存储在 TiDB 或 MySQL 中的数据导出为 SQL 或 CSV 格式，用于逻辑全量备份。Dumpling 也支持将数据导出到 Amazon S3 中。

要快速了解 Dumpling 的基本功能，建议先观看下面的培训视频（时长 28 分钟）。注意本视频只作为功能介绍、学习参考，具体操作步骤和最新功能，请以文档内容为准。

你可以通过下列任意方式获取 Dumpling：

• TiUP 执行tiup install dumpling命令。获取后，使用tiup dumpling ...命令运行 Dumpling。
• 下载包含 Dumpling 的tidb-toolkit 安装包。

更多详情，可以使用 --help 选项查看，或参考Dumpling 主要选项表。

使用 Dumpling 时，需要在已经启动的集群上执行导出命令。

TiDB 还提供了其他工具，你可以根据需要选择使用：

• 如果需要直接备份 SST 文件（键值对），或者对延迟不敏感的增量备份，请使用备份工具BR。
• 如果需要实时的增量备份，请使用TiCDC。
• 所有的导出数据都可以用TiDB Lightning导回到 TiDB。

相比 Mydumper，Dumpling 做了如下改进：

• 支持导出多种数据形式，包括 SQL/CSV。
• 支持全新的table-filter，筛选数据更加方便。
• 支持导出到 Amazon S3 云盘。
• 针对 TiDB 进行了更多优化：
  • 支持配置 TiDB 单条 SQL 内存限制。
  • 针对 TiDB v4.0.0 及更新版本，如果 Dumpling 能够直接连接到 PD，则支持自动调整 TiDB GC 时间。
  • 使用 TiDB 的隐藏列_tidb_rowid优化了单表内数据的并发导出性能。
  • 对于 TiDB 可以设置tidb_snapshot的值指定备份数据的时间点，从而保证备份的一致性，而不是通过FLUSH TABLES WITH READ LOCK来保证备份一致性。

从 TiDB/MySQL 导出数据

需要的权限

• PROCESS：需要该权限用于查询集群信息以获取 PD 地址，从而通过 PD 控制 GC。
• SELECT：导出目标表时需要。
• RELOAD：使用 consistency flush 时需要。注意，只有 TiDB 支持该权限，当上游为 RDS 或采用托管服务时，可忽略该权限。
• LOCK TABLES：使用 consistency lock 时需要，需要导出的库表都有该权限。
• REPLICATION CLIENT：导出 metadata 记录数据快照点时需要，可选，如果不需要导出 metadata，可忽略该权限。

导出为 SQL 文件

本文假设在127.0.0.1:4000有一个 TiDB 实例，并且这个 TiDB 实例中有无密码的 root 用户。

Dumpling 默认导出数据格式为 SQL 文件。也可以通过设置--filetype sql导出数据到 SQL 文件：

              

               dumpling -u root -P 4000 -h 127.0.0.1 --filetype sql -t 8 -o /tmp/test -r 200000 -F256MiB

               
               

以上命令中：

• -h、-P、-u分别代表地址、端口、用户。如果需要密码验证，可以使用-p $YOUR_SECRET_PASSWORD将密码传给 Dumpling。
• -o（或--output）用于选择存储导出文件的目录，支持本地文件的绝对路径或外部存储 URI 格式。
• -t用于指定导出的线程数。增加线程数会增加 Dumpling 并发度提高导出速度，但也会加大数据库内存消耗，因此不宜设置过大。一般不超过 64。
• -r用于开启表内并发加速导出。默认值是0，表示不开启。取值大于 0 表示开启，取值是 INT 类型。当数据源为 TiDB 时，设置-r参数大于 0 表示使用 TiDB region 信息划分区间，同时减少内存使用。具体取值不影响划分算法。对数据源为 MySQL 且表的主键是 INT 的场景，该参数也有表内并发效果。
• -F选项用于指定单个文件的最大大小，单位为MiB，可接受类似5GiB或8KB的输入。如果你想使用 TiDB Lightning 将该文件加载到 TiDB 实例中，建议将-F选项的值保持在 256 MiB 或以下。

导出为 CSV 文件

你可以通过使用--filetype csv导出数据到 CSV 文件。

当你导出 CSV 文件时，你可以使用--sql 导出指定 SQL 选择出来的记录。例如，导出test.sbtest1中所有id < 100的记录：

              

               ./dumpling -u root -P 4000 -h 127.0.0.1 -o /tmp/test --filetype csv --sql'select * from `test`.`sbtest1` where id < 100'-F 100MiB --output-filename-template'test.sbtest1.{{.Index}}'
              

               
               

以上命令中：

• --sql选项仅仅可用于导出 CSV 文件的场景。上述命令将在要导出的所有表上执行SELECT * FROM WHERE id < 100语句。如果部分表没有指定的字段，那么导出会失败。
• 使用--sql配置导出时，Dumpling 无法获知导出的表库信息，此时可以使用--output-filename-template选项来指定 CSV 文件的文件名格式，以方便后续使用TiDB Lightning导入数据文件。例如--output-filename-template='test.sbtest1.{{.Index}}'指定导出的 CSV 文件为test.sbtest1.000000000、test.sbtest1.000000001等。
• 你可以使用--csv-separator、--csv-delimiter等选项，配置 CSV 文件的格式。具体信息可查阅Dumpling 主要选项表。

压缩导出的数据文件

你可以使用--compress 压缩导出的 CSV、SQL 数据与表结构文件。该参数支持gzip、snappy、zstd压缩算法。默认不压缩。

• 该选项只能压缩单个数据与表结构文件，无法直接压缩整个文件夹生成单个压缩集合包。
• 该选项可以节省磁盘空间，但也会导致导出速度变慢，并增加 CPU 消耗。对导出速度要求较高的场景需慎用。
• TiDB Lightning v6.5.0 及以上版本支持直接使用 Dumpling 压缩文件作为数据源导入，无需额外配置。

输出文件格式

• metadata：此文件包含导出的起始时间，以及 master binary log 的位置。

  
                  
  
                   catmetadata
  
                   
                   

  
                  
  
                   Started dump at: 2020-11-10 10:40:19 SHOW MASTER STATUS: Log: tidb-binlog Pos: 420747102018863124 Finished dump at: 2020-11-10 10:40:20
  
                   
                   

• {模式}-schema-create.sql：创建 schema 的 SQL 文件。

  
                  
  
                   cattest-schema-create.sql
  
                   
                   

  
                  
  
                   CREATE DATABASE `test` /*!40100 DEFAULT CHARACTER SET utf8mb4 */;
  
                   
                   

• {schema}.{table}-schema.sql：创建 table 的 SQL 文件

  
                  
  
                   cattest.t1-schema.sql
  
                   
                   

  
                  
  
                   CREATE TABLE `t1` ( `id` int(11) DEFAULT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
  
                   
                   

• {schema}.{table}.{0001}.{sql|csv}：数据源文件

  
                  
  
                   cattest.t1.0.sql
  
                   
                   

  
                  
  
                   /*!40101 SET NAMES binary*/; INSERT INTO `t1` VALUES (1);
  
                   
                   

• *-schema-view.sql、*-schema-trigger.sql、*-schema-post.sql：其他导出文件

导出到 Amazon S3 云盘

Dumpling 在 v4.0.8 及更新版本支持导出到 Amazon S3 云盘。如果需要将数据备份到 Amazon S3 后端存储，那么需要在-o参数中指定 Amazon S3 的存储路径。

可以参照AWS 官方文档 - 如何创建 S3 存储桶在指定的Region区域中创建一个 S3 桶Bucket。如有需要，还可以参照AWS 官方文档 - 创建文件夹在 Bucket 中创建一个文件夹Folder。

将有权限访问该 Amazon S3 后端存储的账号的SecretKey和AccessKey作为环境变量传入 Dumpling 节点。

              

               exportAWS_ACCESS_KEY_ID=${AccessKey}
               exportAWS_SECRET_ACCESS_KEY =${SecretKey}
              

               
               

Dumpling 同时还支持从~/.aws/credentials读取凭证文件。Dumpling 导出到 Amazon S3 的配置参数与 BR 大致相同，更多参数描述，请参考外部存储 URI 格式。

              

               ./dumpling -u root -P 4000 -h 127.0.0.1 -r 200000 -o"s3://${Bucket}/${Folder}"
              

               
               

筛选导出的数据

使用--where选项筛选数据

默认情况下，Dumpling 会导出排除系统数据库（包括mysql、sys、INFORMATION_SCHEMA、PERFORMANCE_SCHEMA、METRICS_SCHEMA和INSPECTION_SCHEMA）外所有其他数据库。你可以使用--where 来指定要导出的记录。

              

               ./dumpling -u root -P 4000 -h 127.0.0.1 -o /tmp/test --where
               "id < 100"
              

               
               

上述命令将会导出各个表的 id < 100 的数据。注意--where参数无法与--sql一起使用。

使用--filter选项筛选数据

Dumpling 可以通过--filter指定 table-filter 来筛选特定的库表。table-filter 的语法与.gitignore相似，详细语法参考表库过滤。

              

               ./dumpling -u root -P 4000 -h 127.0.0.1 -o /tmp/test -r 200000 --filter"employees.*"--filter"*.WorkOrder"
              

               
               

上述命令将会导出employees数据库的所有表，以及所有数据库中的WorkOrder表。

使用-B或- t选项筛选数据

Dumpling 也可以通过-B或- t选项导出特定的数据库/数据表。

例如通过指定：

• -B employees导出employees数据库
• - temployees.WorkOrder导出employees.WorkOrder数据表

通过并发提高 Dumpling 的导出效率

默认情况下，导出的文件会存储到./export-目录下。常用选项如下：

• -t用于指定导出的线程数。增加线程数会增加 Dumpling 并发度提高导出速度，但也会加大数据库内存消耗，因此不宜设置过大。
• -r选项用于指定单个文件的最大记录数，或者说，数据库中的行数。开启后 Dumpling 会开启表内并发，提高导出大表的速度。当上游为 TiDB 且版本为 v3.0 或更新版本时，设置-r参数大于 0 表示使用 TiDB region 信息划分表内并发，具体取值不影响划分算法。对上游为 MySQL 且表的主键是 int 的场景，该参数也有表内并发效果。
• --compress 选项可以用于压缩导出的数据，支持gzip、snappy、zstd压缩算法。压缩可以显著降低导出数据的大小，同时如果存储的写入 I/O 带宽不足，可以使用该选项来加速导出。但该选项也有副作用，由于该选项会对每个文件单独压缩，因此会增加 CPU 消耗。

利用以上选项可以提高 Dumpling 的导出速度。

调整 Dumpling 的数据一致性选项

Dumpling 通过--consistency 标志控制导出数据“一致性保证”的方式。在使用 snapshot 来保证一致性的时候，可以使用--snapshot选项指定要备份的时间戳。还可以使用以下的一致性级别：

• flush：使用FLUSH TABLES WITH READ LOCK短暂地中断备份库的 DML 和 DDL 操作、保证备份连接的全局一致性和记录 POS 信息。所有的备份连接启动事务后释放该锁。推荐在业务低峰或者 MySQL 备份库上进行全量备份。
• snapshot：获取指定时间戳的一致性快照并导出。
• lock：为待导出的所有表上读锁。
• none：不做任何一致性保证。
• auto：对 MySQL 使用flush，对 TiDB 使用snapshot。

操作完成之后，你可以在/tmp/test查看导出的文件：

              

               $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

               
               

导出 TiDB 的历史数据快照

Dumpling 可以通过--snapshot指定导出某个tidb_snapshot的数据。

--snapshot选项可设为 TSO（SHOW MASTER STATUS输出的Position字段）或有效的datetime时间（YYYY-MM-DD hh:mm:ss形式），例如：

              

               ./dumpling --snapshot 417773951312461825 ./dumpling --snapshot"2020-07-02 17:12:45"
              

               
               

即可导出 TSO 为417773951312461825或2020-07-02 17:12:45时的 TiDB 历史数据快照。

控制导出 TiDB 大表（超过 1 TB）时的内存使用

Dumpling 导出 TiDB 较大单表（超过 1 TB）时，可能会因为导出数据过大导致 TiDB 内存溢出 (OOM)，从而使连接中断导出失败。可以通过以下参数减少 TiDB 的内存使用。

• 设置-r参数，可以划分导出数据区块减少 TiDB 扫描数据的内存开销，同时也可开启表内并发提高导出效率。当上游为 TiDB 且版本为 v3.0 或更新版本时，设置-r参数大于 0 表示使用 TiDB region 信息划分表内并发，具体取值不影响划分算法。
• 调小--tidb-mem-quota-query参数到8589934592(8GB) 或更小。可控制 TiDB 单条查询语句的内存使用。
• 调整--params "tidb_distsql_scan_concurrency=5"参数，即设置导出时的 session 变量tidb_distsql_scan_concurrency从而减少 TiDB scan 操作的并发度。

手动设置 TiDB GC 时间

如果导出的 TiDB 版本为 v4.0.0 或更新版本，并且 Dumpling 可以访问 TiDB 集群的 PD 地址，Dumpling 会自动配置延长 GC 时间且不会对原集群造成影响。

但是，在以下场景中，Dumpling 无法自动调整 GC 时间：

• 数据量非常大（超过 1 TB）。
• Dumpling 无法直接连接到 PD，例如 TiDB 集群运行在 TiDB Cloud 上，或者 TiDB 集群运行在 Kubernetes 上且与 Dumpling 分离。

在这些场景中，你必须提前手动调长 GC 时间，以避免因为导出过程中发生 GC 导致导出失败。

使用以下 SQL 语句手动调整 GC 时间：

              

               SET
               GLOBALtidb_gc_life_time=
               '720h';

               
               

在 Dumpling 退出后，无论导出是否成功，都必须将 GC 时间恢复为其原始值（默认值为10m）。

              

               SET
               GLOBALtidb_gc_life_time=
               '10m';

               
               

Dumpling 主要选项表

主要选项	用途	默认值
-V 或 --version	输出 Dumpling 版本并直接退出
-B 或 --database	导出指定数据库
- t或 --tables-list	导出指定数据表
-f 或 --filter	导出能匹配模式的表，语法可参考table-filter	[\*.\*,!/^( mysql # 124; sys # 124; INFORMATION_SCHEMA|PERFORMANCE_SCHEMA|METRICS_SCHEMA|INSPECTION_SCHEMA)$/.\*]（导出除系统库外的所有库表）
--case-sensitive	过滤是否大小写敏感	false，大小写不敏感
-h 或 --host	连接的数据库主机的地址	"127.0.0.1"
-t 或 --threads	备份并发线程数	4
-r 或 --rows	用于开启表内并发加速导出。默认值是0，表示不开启。取值大于 0 表示开启，取值是 INT 类型。当数据源为 TiDB 时，设置-r参数大于 0 表示使用 TiDB region 信息划分区间，同时减少内存使用。具体取值不影响划分算法。对数据源为 MySQL 且表的主键是 INT 的场景，该参数也有表内并发效果。
-L 或 --logfile	日志输出地址，为空时会输出到控制台	""
--loglevel	日志级别 {debug,info,warn,error,dpanic,panic,fatal}	"info"
--logfmt	日志输出格式 {text,json}	"text"
-d 或 --no-data	不导出数据，适用于只导出 schema 场景
--no-header	导出 csv 格式的 table 数据，不生成 header
-W 或 --no-views	不导出 view	true
-m 或 --no-schemas	不导出 schema，只导出数据
-s 或--statement-size	控制INSERTSQL 语句的大小，单位 bytes
-F 或 --filesize	将 table 数据划分出来的文件大小，需指明单位（如128B,64KiB,32MiB,1.5GiB）
--filetype	导出文件类型（csv/sql）	"sql"
-o 或 --output	导出本地文件的绝对路径或外部存储 URI 格式	"./export-${time}"
-S 或 --sql	根据指定的 sql 导出数据，该选项不支持并发导出
--consistency	flush: dump 前用 FTWRL snapshot: 通过 TSO 来指定 dump 某个快照时间点的 TiDB 数据 lock: 对需要 dump 的所有表执行lock tables read命令 none: 不加锁 dump，无法保证一致性 auto: 对 MySQL 使用 --consistency flush；对 TiDB 使用 --consistency snapshot	"auto"
--snapshot	snapshot tso，只在 consistency=snapshot 下生效
--where	对备份的数据表通过 where 条件指定范围
-p 或 --password	连接的数据库主机的密码
-P 或 --port	连接的数据库主机的端口	4000
-u 或 --user	连接的数据库主机的用户名	"root"
--dump-empty-database	导出空数据库的建库语句	true
--ca	用于 TLS 连接的 certificate authority 文件的地址
--cert	用于 TLS 连接的 client certificate 文件的地址
--key	用于 TLS 连接的 client private key 文件的地址
--csv-delimiter	csv 文件中字符类型变量的定界符	'"'
--csv-separator	csv 文件中各值的分隔符，如果数据中可能有逗号，建议源文件导出时分隔符使用非常见组合字符	','
--csv-null-value	csv 文件空值的表示	"\N"
--escape-backslash	使用反斜杠 (\) 来转义导出文件中的特殊字符	true
--output-filename-template	以golang template格式表示的数据文件名格式 支持{{.DB}}、{{.Table}}、{{.Index}}三个参数 分别表示数据文件的库名、表名、分块 ID	'{{.DB}}.{{.Table}}.{{.Index}}'
--status-addr	饺子的服务地址,包含了舞会etheus 拉取 metrics 信息及 pprof 调试的地址	":8281"
--tidb-mem-quota-query	单条 dumpling 命令导出 SQL 语句的内存限制，单位为 byte。对于 v4.0.10 或以上版本，若不设置该参数，默认使用 TiDB 中的mem-quota-query配置项值作为内存限制值。对于 v4.0.10 以下版本，该参数值默认为 32 GB	34359738368
--params	为需导出的数据库连接指定 session 变量，可接受的格式: "character_set_client=latin1,character_set_connection=latin1"
-c 或 --compress	压缩 Dumpling 导出的 CSV、SQL 数据与表结构文件为指定格式，支持 "gzip"、"snappy" 和 "zstd" 压缩算法	""