From 5241a659aa920fd7ac6ea0c44a8c72c63f7660f0 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 25 Dec 2024 18:17:24 +0800 Subject: [PATCH] lightning: reformat task configuration > mydumper --- .../tidb-lightning-configuration.md | 127 ++++++++++-------- 1 file changed, 71 insertions(+), 56 deletions(-) diff --git a/tidb-lightning/tidb-lightning-configuration.md b/tidb-lightning/tidb-lightning-configuration.md index 1dda65ad302f..d832168a3b07 100644 --- a/tidb-lightning/tidb-lightning-configuration.md +++ b/tidb-lightning/tidb-lightning-configuration.md @@ -346,62 +346,77 @@ TiDB Lightning 的配置文件分为“全局”和“任务”两种类别， - 在逻辑导入模式下，该参数控制是否使用预处理语句和语句缓存来提高性能。 - 默认值：`false` -[mydumper] -# 设置文件读取的区块大小，确保该值比数据源的最长字符串长。 -read-block-size = "64KiB" # 默认值 - -# 引擎文件需按顺序导入。由于并行处理，多个数据引擎几乎在同时被导入， -# 这样形成的处理队列会造成资源浪费。因此，为了合理分配资源，TiDB Lightning -# 稍微增大了前几个区块的大小。该参数也决定了比例系数，即在完全并发下 -# “导入”和“写入”过程的持续时间比。这个值可以通过计算 1 GiB 大小的 -# 单张表的（导入时长/写入时长）得到。在日志文件中可以看到精确的时间。 -# 如果“导入”更快，区块大小的差异就会更小；比值为 0 时则说明区块大小一致。 -# 取值范围为（0 <= batch-import-ratio < 1）。 -batch-import-ratio = 0.75 - -# 本地源数据目录或外部存储 URI。关于外部存储 URI 详情可参考 https://docs.pingcap.com/zh/tidb/v6.6/backup-and-restore-storages#uri-%E6%A0%BC%E5%BC%8F。 -data-source-dir = "/data/my_database" - -# 指定包含 `CREATE TABLE` 语句的表结构文件的字符集。只支持下列选项： -# - utf8mb4：表结构文件必须使用 UTF-8 编码，否则会报错。 -# - gb18030：表结构文件必须使用 GB-18030 编码，否则会报错。 -# - auto：自动判断文件编码是 UTF-8 还是 GB-18030，两者皆非则会报错（默认）。 -# - latin1：源数据文件使用 MySQL latin1 字符集编码（也被称为 Code Page 1252）。 -# - binary：不尝试转换编码。 -character-set = "auto" - -# 指定源数据文件的字符集，Lightning 会在导入过程中将源文件从指定的字符集转换为 UTF-8 编码。 -# 该配置项目前仅用于指定 CSV 文件的字符集。只支持下列选项： -# - utf8mb4：源数据文件使用 UTF-8 编码。 -# - GB18030：源数据文件使用 GB-18030 编码。 -# - GBK：源数据文件使用 GBK 编码（GBK 编码是对 GB-2312 字符集的拓展，也被称为 Code Page 936）。 -# - latin1：源数据文件使用 MySQL latin1 字符集编码（也被称为 Code Page 1252）。 -# - binary：不尝试转换编码（默认）。 -# 留空此配置将默认使用 "binary"，即不尝试转换编码。 -# 需要注意的是，Lightning 不会对源数据文件的字符集做假定，仅会根据此配置对数据进行转码并导入。 -# 如果字符集设置与源数据文件的实际编码不符，可能会导致导入失败、导入缺失或导入数据乱码。 -data-character-set = "binary" -# 指定在源数据文件的字符集转换过程中，出现不兼容字符时的替换字符。 -# 此项不可与字段分隔符、引用界定符和换行符号重复。 -# 默认值为 "\uFFFD"，即 UTF-8 编码中的 "error" Rune 或 Unicode replacement character。 -# 改变默认值可能会导致潜在的源数据文件解析性能下降。 -data-invalid-char-replace = "\uFFFD" - -# “严格”格式的导入数据可加快处理速度。 -# strict-format = true 要求： -# 在 CSV 文件的所有记录中，每条数据记录的值不可包含字符换行符（U+000A 和 U+000D，即 \r 和 \n） -# 甚至被引号包裹的字符换行符都不可包含，即换行符只可用来分隔行。 -# 导入数据源为严格格式时，TiDB Lightning 会快速定位大文件的分割位置进行并行处理。 -# 但是如果输入数据为非严格格式，可能会将一条完整的数据分割成两部分，导致结果出错。 -# 为保证数据安全而非追求处理速度，默认值为 false。 -strict-format = false - -# 如果 strict-format = true，TiDB Lightning 会将 CSV 大文件分割为多个文件块进行并行处理。 -# max-region-size 是分割后每个文件块的最大大小。 -# max-region-size = "256MiB" # 默认值 - -# 只导入与该通配符规则相匹配的表。详情见相应章节。 -filter = ['*.*', '!mysql.*', '!sys.*', '!INFORMATION_SCHEMA.*', '!PERFORMANCE_SCHEMA.*', '!METRICS_SCHEMA.*', '!INSPECTION_SCHEMA.*'] +#### mydumper + +##### `read-block-size` + +- 设置文件读取的区块大小，确保该值比数据源的最长字符串长。 +- 默认值：`"64KiB"` + +##### `batch-import-ratio` + +- 引擎文件需按顺序导入。由于并行处理，多个数据引擎几乎在同时被导入，这样形成的处理队列会造成资源浪费。因此，为了合理分配资源，TiDB Lightning 稍微增大了前几个区块的大小。该参数也决定了比例系数，即在完全并发下“导入”和“写入”过程的持续时间比。这个值可以通过计算 1 GiB 大小的 单张表的（导入时长/写入时长）得到。在日志文件中可以看到精确的时间。 +- 如果“导入”更快，区块大小的差异就会更小；比值为 0 时则说明区块大小一致。 +- 取值范围：`[0, 1)` + + + +##### `data-source-dir` + +- 本地源数据目录或外部存储 URI。关于外部存储 URI 详情可参考 [URI 格式](/br/backup-and-restore-storages.md#uri-格式)。 + + + +##### `character-set` + +- 指定包含 `CREATE TABLE` 语句的表结构文件的字符集。 +- 可选值： + - `"utf8mb4"`：表结构文件必须使用 UTF-8 编码，否则会报错 + - `"gb18030"`：表结构文件必须使用 GB-18030 编码，否则会报错 + - `"auto"`：自动判断文件编码是 UTF-8 还是 GB-18030，两者皆非则会报错 + - `"latin1"`：源数据文件使用 MySQL latin1 字符集编码（也被称为 Code Page 1252） + - `"binary"`：不尝试转换编码 +- 默认值：`"auto"` + +##### `data-character-set` + +- 指定源数据文件的字符集，Lightning 会在导入过程中将源文件从指定的字符集转换为 UTF-8 编码。 +- 该配置项目前仅用于指定 CSV 文件的字符集。留空此配置将默认使用 `"binary"`，即不尝试转换编码。 +- Lightning 不会对源数据文件的字符集做假定，仅会根据此配置对数据进行转码并导入。 +- 如果字符集设置与源数据文件的实际编码不符，可能会导致导入失败、导入缺失或导入数据乱码。 +- 可选值： + - `"utf8mb4"`：源数据文件使用 UTF-8 编码 + - `"GB18030"`：源数据文件使用 GB-18030 编码 + - `"GBK"`：源数据文件使用 GBK 编码（GBK 编码是对 GB-2312 字符集的拓展，也被称为 Code Page 936） + - `"latin1"`：源数据文件使用 MySQL latin1 字符集编码（也被称为 Code Page 1252） + - `"binary"`：不尝试转换编码 +- 默认值：`"binary"` + +##### `data-invalid-char-replace` + +- 指定在源数据文件的字符集转换过程中，出现不兼容字符时的替换字符。 +- 此项不可与字段分隔符、引用界定符和换行符号重复。改变默认值可能会导致潜在的源数据文件解析性能下降。 +- 默认值：`"\uFFFD"`，即 UTF-8 编码中的 "error" Rune 或 Unicode replacement character + +##### `strict-format` + +- “严格”格式的导入数据可加快处理速度。为保证数据安全而非追求处理速度，默认值为 `false`。 +- 默认值：`false` +- 当设置为 `true` 时的要求： + - 在 CSV 文件的所有记录中，每条数据记录的值不可包含字符换行符（`U+000A` 和 `U+000D`，即 `\r` 和 `\n`）甚至被引号包裹的字符换行符都不可包含，即换行符只可用来分隔行。 + - 导入数据源为严格格式时，TiDB Lightning 会快速定位大文件的分割位置进行并行处理。 + - 但是如果输入数据为非严格格式，可能会将一条完整的数据分割成两部分，导致结果出错。 + +##### `max-region-size` + +- 如果 [`strict-format`](#strict-format) 设置为 `true`，TiDB Lightning 会将 CSV 大文件分割为多个文件块进行并行处理。`max-region-size` 是分割后每个文件块的最大大小。 +- 默认值：`"256MiB"` + +##### `filter` + +- 只导入与该通配符规则相匹配的表。 + + #### mydumper.csv