Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

dumpling, lightning: add document for compressed files support #12083

Merged
merged 11 commits into from
Dec 2, 2022
9 changes: 9 additions & 0 deletions dumpling-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,14 @@ dumpling -u root -P 4000 -h 127.0.0.1 --filetype sql -t 8 -o /tmp/test -r 200000
>
> Dumpling 导出不区分*字符串*与*关键字*。如果导入的数据是 Boolean 类型的 `true` 和 `false`,导出时会被转换为 `1` 和 `0` 。

### 压缩导出的数据文件

你可以通过使用 `--compress gzip` 压缩导出的 csv/sql 数据与表结构文件。该参数支持 `gzip`、`snappy`、`zstd` 压缩算法,默认不压缩。

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

### 输出文件格式

+ `metadata`:此文件包含导出的起始时间,以及 master binary log 的位置。
Expand Down Expand Up @@ -346,3 +354,4 @@ SET GLOBAL tidb_gc_life_time = '10m';
| --status-addr | Dumpling 的服务地址,包含了 Prometheus 拉取 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 | 压缩所有导出的数据文件为指定格式,支持 "gzip", "snappy", "zstd" | "" |
hfxsd marked this conversation as resolved.
Show resolved Hide resolved
11 changes: 11 additions & 0 deletions tidb-lightning/tidb-lightning-data-source.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ TiDB Lightning 运行时将查找 `data-source-dir` 中所有符合命令规则
|Schema 文件|包含 `CREATE DATABASE` DDL 语句的文件|`${db_name}-schema-create.sql`|
|数据文件|包含整张表的数据文件,该文件会被导入 `${db_name}.${table_name}` 表 | <code>\${db_name}.\${table_name}.\${csv\|sql\|parquet}</code>|
|数据文件| 如果一个表分布于多个数据文件,这些文件命名需加上文件编号的后缀 | <code>\${db_name}.\${table_name}.001.\${csv\|sql\|parquet}</code> |
|压缩文件| 上述所有类型文件如带压缩文件名后缀,lightning 会流式解压后进行导入 | <code>\${db_name}.\${table_name}.\${csv\|sql\|parquet}.{compress}</code> |
hfxsd marked this conversation as resolved.
Show resolved Hide resolved

TiDB Lightning 尽量并行处理数据,由于文件必须顺序读取,所以数据处理协程是文件级别的并发(通过 `region-concurrency` 配置控制)。因此导入大文件时性能比较差。通常建议单个文件尺寸为 256MiB,以获得最好的性能。

Expand Down Expand Up @@ -283,6 +284,16 @@ type = '$3'

关于 `mydumper.files`,请参考[自定义文件匹配](/tidb-lightning/tidb-lightning-data-source.md#自定义文件匹配)。

## 压缩文件

TiDB Lightning 目前支持由 Dumpling 导出的压缩文件或满足符合上文命名规则的压缩文件,目前支持 `gzip`, `snappy`, `zstd` 压缩算法的压缩文件。在文件名符合命名规则时,TiDB Lightning 会自动识别压缩算法在流式解压后导入,无需额外配置。

注意:
1. 由于 TiDB Lightning 无法对单个大压缩文件进行并发解压,因此压缩文件的大小会直接影响导入速度。建议压缩数据文件解压后的源文件大小不超过 256 MiB。
2. TiDB Lightning 仅支持导入各自独立压缩的数据文件,不支持导入多个数据文件组成的单个压缩文件集合包。
3. TiDB Lightning 不支持二次压缩的 `parquet` 文件,例如 `db.table.parquet.snappy`,如需压缩 `parquet` 文件用户可配置 `parquet` 文件数据存储的压缩格式。
4. v6.4 及之后版本的 TiDB Lightning 会识别带有非 `.bak` 后缀的数据文件为 TiDB Lightning 不支持的压缩数据文件并报错,用户需要提前清理通过文件改名或将该类文件移出导入数据目录来避免此类错误。

## 自定义文件匹配

TiDB Lightning 仅识别符合命名要求的数据文件,但在某些情况下已提供的数据文件并不符合要求,因此可能出现 TiDB Lightning 在极短的时间结束,处理文件数量为 0 的情况。
Expand Down
4 changes: 4 additions & 0 deletions tidb-lightning/troubleshoot-tidb-lightning.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,3 +210,7 @@ header = false
### `Unknown character set`

由于 TiDB 只支持部分 MySQL 字符集,因此,在导入流程中,如果创建表结构时使用了 TiDB 不支持的字符集,TiDB Lightning 会报这个错误。你可以结合数据内容选择 [TiDB 支持的字符集](/character-set-and-collation.md),预先在下游创建表结构以绕过这个错误。

### `invalid compression type ...`

v6.4 及之后版本的 TiDB Lightning 会识别带有非 `.bak` 后缀的数据文件为 TiDB Lightning 不支持的压缩数据文件并报错,因此需要提前清理通过文件改名或将该类文件移出导入数据目录来避免此类错误。
hfxsd marked this conversation as resolved.
Show resolved Hide resolved