diff --git a/TOC.md b/TOC.md index 2166f439eb39..8324fde5aa66 100644 --- a/TOC.md +++ b/TOC.md @@ -303,6 +303,7 @@ + 周边工具 - [功能概览](/ecosystem-tool-user-guide.md) - [适用场景](/ecosystem-tool-user-case.md) + - [表库过滤](/table-filter.md) - [Mydumper](/mydumper-overview.md) - [Loader](/loader-overview.md) - [Syncer](/syncer-overview.md) @@ -312,7 +313,7 @@ - [部署执行](/tidb-lightning/deploy-tidb-lightning.md) - [参数说明](/tidb-lightning/tidb-lightning-configuration.md) - [断点续传](/tidb-lightning/tidb-lightning-checkpoints.md) - - [表库过滤](/tidb-lightning/tidb-lightning-table-filter.md) + - [表库过滤](/table-filter.md) - [CSV 支持](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md) - [TiDB-backend](/tidb-lightning/tidb-lightning-tidb-backend.md) - [Web 界面](/tidb-lightning/tidb-lightning-web-interface.md) diff --git a/export-or-backup-using-dumpling.md b/export-or-backup-using-dumpling.md index 01cc4292fd31..78994f524a15 100644 --- a/export-or-backup-using-dumpling.md +++ b/export-or-backup-using-dumpling.md @@ -80,7 +80,7 @@ dumpling \ #### 使用 `--filter` 指令筛选数据 -Dumpling 可以通过 `--filter` 指定 table-filter 来筛选特定的库表。table-filter 的语法与 .gitignore 相似,[详细语法参考](https://github.com/pingcap/tidb-tools/blob/master/pkg/table-filter/README.md)。 +Dumpling 可以通过 `--filter` 指定 table-filter 来筛选特定的库表。table-filter 的语法与 .gitignore 相似,详细语法参考[表库过滤](/table-filter.md)。 {{< copyable "shell-regular" >}} diff --git a/table-filter.md b/table-filter.md new file mode 100644 index 000000000000..8551b9168278 --- /dev/null +++ b/table-filter.md @@ -0,0 +1,229 @@ +--- +title: 表库过滤 +summary: 在 TiDB 生态工具中使用表库过滤功能。 +aliases: ['/docs-cn/v3.0/tidb-lightning/tidb-lightning-table-filter/','/docs-cn/v3.0/reference/tools/tidb-lightning/table-filter/','/zh/tidb/v3.0/tidb-lightning-table-filter/'] +--- + +# 表库过滤 + +TiDB 生态工具默认情况下作用于所有数据库,但实际使用中,往往只需要作用于其中的部分子集。例如,用户只想处理 `foo*` 和 `bar*` 形式的表,而无需对其他表进行操作。 + +所有 TiDB 生态系统工具都使用一个通用的过滤语法来定义子集。本文档介绍如何使用表库过滤功能。 + +## 使用表库过滤 + +### 命令行 + +在命令行中使用多个 `-f` 或 `--filter` 参数,即可在 TiDB 生态工具中应用表库过滤规则。每个过滤规则均采用 `db.table` 形式,支持通配符(详情见[下一节](#使用通配符))。以下为各个工具中的使用示例: + +* [Dumpling](/export-or-backup-using-dumpling.md): + + {{< copyable "shell-regular" >}} + + ```shell + ./dumpling -f 'foo*.*' -f 'bar*.*' -P 3306 -o /tmp/data/ + # ^~~~~~~~~~~~~~~~~~~~~~~ + ``` + +* [Lightning](/tidb-lightning/tidb-lightning-overview.md): + + {{< copyable "shell-regular" >}} + + ```shell + ./tidb-lightning -f 'foo*.*' -f 'bar*.*' -d /tmp/data/ --backend tidb + # ^~~~~~~~~~~~~~~~~~~~~~~ + ``` + +### TOML 配置文件 + +在 TOML 文件中,表库过滤规则以[字符串数组](https://toml.io/cn/v1.0.0-rc.1#%E6%95%B0%E7%BB%84)的形式指定。以下为各个工具中的使用示例: + +* Lightning: + + ```toml + [mydumper] + filter = ['foo*.*', 'bar*.*'] + ``` + +## 表库过滤语法 + +### 直接使用表名 + +每条表库过滤规则由“库”和“表”组成,两部分之间以英文句号 (`.`) 分隔。只有表名与规则完全相符的表才会被接受。 + +``` +db1.tbl1 +db2.tbl2 +db3.tbl3 +``` + +表名只由有效的[标识符](/schema-object-names.md)组成,例如: + +* 数字(`0` 到 `9`) +* 字母(`a` 到 `z`,`A` 到 `Z`) +* `$` +* `_` +* 非 ASCII 字符(`U+0080` 到 `U+10FFFF`) + +其他 ASCII 字符均为保留字。部分标点符号有特殊含义,详情见下一节。 + +### 使用通配符 + +表名的两个部分均支持使用通配符(详情见 [fnmatch(3)](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_13))。 + +* `*`:匹配零个或多个字符。 +* `?`:匹配一个字符。 +* `[a-z]`:匹配 “a” 和 “z” 之间的一个字符。 +* `[!a-z]`:匹配不在 “a” 和 “z” 之间的一个字符。 + +``` +db[0-9].tbl[0-9a-f][0-9a-f] +data.* +*.backup_* +``` + +此处,“字符”指的是一个 Unicode 码位,例如: + +* `U+00E9` (é) 是 1 个字符。 +* `U+0065 U+0301` (é) 是 2 个字符。 +* `U+1F926 U+1F3FF U+200D U+2640 U+FE0F` (🤦🏿‍♀️) 是 5 个字符。 + +### 使用文件导入 + +如需导入一个文件作为过滤规则,请在规则的开头加上一个 “@” 来指定文件名。库表过滤解析器将导入文件中的每一行都解析为一条额外的过滤规则。 + +例如,`config/filter.txt` 文件有以下内容: + +``` +employees.* +*.WorkOrder +``` + +以下两条表库过滤命令是等价的: + +```bash +./dumpling -f '@config/filter.txt' +./dumpling -f 'employees.*' -f '*.WorkOrder' +``` + +导入的文件里不能使用过滤规则导入另一个文件。 + +### 注释与空行 + +导入的过滤规则文件中,每一行开头和结尾的空格都会被去除。此外,空行(空字符串)也将被忽略。 + +行首的 `#` 表示该行是注释,会被忽略。而不在行首的 `#` 则会被认为是语法错误。 + +``` +# 这是一行注释 +db.table # 这一部分不是注释,且可能引起错误 +``` + +### 排除规则 + +在一条过滤规则的开头加上 `!`,则表示符合这条规则的表不会被 TiDB 生态工具处理。通过应用排除规则,库表过滤可以作为屏蔽名单来使用。 + +``` +*.* +#^ 注意:必须先添加 *.* 规则来包括所有表 +!*.Password +!employees.salaries +``` + +### 转义字符 + +如果需要将特殊字符转化为标识符,可以在特殊字符前加上反斜杠 `\`。 + +``` +db\.with\.dots.* +``` + +为了简化语法并向上兼容,**不支持**下列字符序列: + +- 在行尾去除空格后使用 `\`(使用 `[ ]` 来匹配行尾的空格)。 +- 在 `\` 后使用数字或字母 (`[0-9a-zA-Z]`)。特别是类似 C 的转义序列,如 `\0`、`\r`、`\n`、`\t` 等序列,目前在表库过滤规则中无意义。 + +### 引号包裹的标识符 + +除了 `\` 之外,还可以用 `"` 和 `` ` `` 来控制特殊字符。 + +``` +"db.with.dots"."tbl\1" +`db.with.dots`.`tbl\2` +``` + +也可以通过输入两次引号,将引号包含在标识符内。 + +``` +"foo""bar".`foo``bar` +# 等价于: +foo\"bar.foo\`bar +``` + +用引号包裹的标识符不可以跨越多行。 + +用引号只包裹标识符的一部分是无效的,例如: + +``` +"this is "invalid*.* +``` + +### 正则表达式 + +如果你需要使用较复杂的过滤规则,可以将每个匹配模型写为正则表达式,以 `/` 为分隔符: + +``` +/^db\d{2,}$/./^tbl\d{2,}$/ +``` + +这类正则表示使用 [Go dialect](https://pkg.go.dev/regexp/syntax?tab=doc)。只要标识符中有一个子字符串与正则表达式匹配,则视为匹配该模型。例如,`/b/` 匹配 `db01`。 + +> **注意:** +> +> 正则表达式中的每一个 `/` 都需要转义为 `\/`,包括在 `[...]` 里面的 `/`。不允许在 `\Q...\E` 之间放置一个未转义的 `/`。 + +## 使用多个过滤规则 + +当表的名称与过滤列表中所有规则均不匹配时,默认情况下这些表被忽略。 + +要建立一个屏蔽名单,必须使用显式的 `*.*` 作为第一条过滤规则,否则所有表均被排除。 + +```bash +# 所有表均被过滤掉 +./dumpling -f '!*.Password' + +# 只有 “Password” 表被过滤掉,其余表仍保留 +./dumpling -f '*.*' -f '!*.Password' +``` + +如果一个表的名称与过滤列表中的多个规则匹配,则以最后匹配的规则为准。例如: + +``` +# rule 1 +employees.* +# rule 2 +!*.dep* +# rule 3 +*.departments +``` + +过滤结果如下: + +| 表名 | 规则 1 | 规则 2 | 规则 3 | 结果 | +|-----------------------|--------|--------|--------|------------------| +| irrelevant.table | | | | 默认(拒绝) | +| employees.employees | ✓ | | | 规则 1(接受) | +| employees.dept_emp | ✓ | ✓ | | 规则 2(拒绝) | +| employees.departments | ✓ | ✓ | ✓ | 规则 3(接受) | +| else.departments | | ✓ | ✓ | 规则 3(接受) | + +> **注意:** +> +> 在 TiDB 生态工具中,无论表库过滤如何设置,系统库总是被排除。系统库有以下六个: +> +> * `INFORMATION_SCHEMA` +> * `PERFORMANCE_SCHEMA` +> * `METRICS_SCHEMA` +> * `INSPECTION_SCHEMA` +> * `mysql` +> * `sys` diff --git a/tidb-lightning/tidb-lightning-configuration.md b/tidb-lightning/tidb-lightning-configuration.md index f865021c110b..b604527c6785 100644 --- a/tidb-lightning/tidb-lightning-configuration.md +++ b/tidb-lightning/tidb-lightning-configuration.md @@ -125,6 +125,9 @@ no-schema = false # 注意:**数据** 文件始终解析为 binary 文件。 character-set = "auto" +# 只导入与该通配符规则相匹配的表。详情见相应章节。 +filter = ['*.*'] + # 配置 CSV 文件的解析方式。 [mydumper.csv] # 字段分隔符,应为单个 ASCII 字符。 @@ -195,10 +198,6 @@ analyze = true switch-mode = "5m" # 在日志中打印导入进度的持续时间。 log-progress = "5m" - -# 设置表库过滤。详情参见“TiDB Lightning 表库过滤”文档。 -# [black-white-list] -# ... ``` ### TiKV Importer 配置参数 @@ -281,6 +280,7 @@ min-available-ratio = 0.05 | -V | 输出程序的版本 | | | -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | | -L *level* | 日志的等级: debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | +| -f *rule* | [表库过滤的规则](/table-filter.md) (可多次指定) | `mydumper.filter` | | --backend *backend* | 选择后端的模式:`importer` 或 [`tidb`](/tidb-lightning/tidb-lightning-tidb-backend.md) | `tikv-importer.backend` | | --log-file *file* | 日志文件路径 | `lightning.log-file` | | --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | diff --git a/tidb-lightning/tidb-lightning-glossary.md b/tidb-lightning/tidb-lightning-glossary.md index 80ddb2de7290..7cf687dfbd93 100644 --- a/tidb-lightning/tidb-lightning-glossary.md +++ b/tidb-lightning/tidb-lightning-glossary.md @@ -35,12 +35,6 @@ aliases: ['/docs-cn/v3.0/reference/tools/tidb-lightning/glossary/'] 详情参阅 [TiDB Lightning TiDB-backend](/tidb-lightning/tidb-lightning-tidb-backend.md)。 -### Black-white list - -黑白名单配置列表。用于指定要导入、忽略哪些表和库。 - -详情参阅 [TiDB Lightning 表库过滤](/tidb-lightning/tidb-lightning-table-filter.md)。 - ## C @@ -105,6 +99,16 @@ TiDB Lightning 通过引擎将数据传送到 TiKV Importer 中。Lightning 先 另见[数据引擎](#data-engine)和[索引引擎](#index-engine)。 + + +## F + +### Filter + +配置列表,用于指定需要导入或不允许导入的表。 + +详情见[表库过滤](/table-filter.md)。 + ## I diff --git a/tidb-lightning/tidb-lightning-table-filter.md b/tidb-lightning/tidb-lightning-table-filter.md deleted file mode 100644 index 7e6972ce55fd..000000000000 --- a/tidb-lightning/tidb-lightning-table-filter.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: TiDB Lightning 表库过滤 -summary: 使用黑白名单把一些表剔出要导入的范围。 -category: reference -aliases: ['/docs-cn/v3.0/reference/tools/tidb-lightning/table-filter/','/docs-cn/tools/lightning/filter/','/docs-cn/v3.0/reference/tools/tidb-lightning/filter/'] ---- - -# TiDB Lightning 表库过滤 - -TiDB Lightning 支持使用黑名单和白名单来过滤掉某些数据库和表。这可以用来跳过一些用作暂存、毋须迁移的表,或用来手动切分数据源,让多机同时导入。 - -这些过滤规则与 MySQL 的 `replication-rules-db`/`replication-rules-table` 类似。 - -## 过滤数据库 - -```toml -[black-white-list] -do-dbs = ["pattern1", "pattern2", "pattern3"] -ignore-dbs = ["pattern4", "pattern5"] -``` - -* 如果 `[black-white-list]` 下的 `do-dbs` 列表不为空, - * 如数据库名称匹配 `do-dbs` 列表中**任何**一项,则数据库会被导入。 - * 否则,数据库会被略过。 -* 否则,如果数据库名称匹配 `ignore-dbs` 列表中**任何**一项,数据库会被略过。 -* 如果数据库名称**同时**匹配 `do-dbs` 和 `ignore-dbs` 列表,数据库会被导入。 - -如果匹配项首字符为 `~`,它会被解析为 [Go 语言的正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。否则会视为普通的字串来匹配数据库名称。 - -> **注意:** -> -> 无论你如何设置过滤规则,系统数据库 `information_schema`、`performance_schema`、`mysql` 和 `sys` 总是会被略过。 - -## 过滤表 - -```toml -[[black-white-list.do-tables]] -db-name = "db-pattern-1" -tbl-name = "table-pattern-1" - -[[black-white-list.do-tables]] -db-name = "db-pattern-2" -tbl-name = "table-pattern-2" - -[[black-white-list.do-tables]] -db-name = "db-pattern-3" -tbl-name = "table-pattern-3" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-4" -tbl-name = "table-pattern-4" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-5" -tbl-name = "table-pattern-5" -``` - -* 如果 `do-tables` 列表不为空, - * 如果表的限定名称匹配 `do-tables` 列表中**任何**一对,则表会被导入。 - * 否则,表会被略过。 -* 否则,如果表的限定名称匹配 `ignore-tables` 列表中**任何**一对,表会被略过。 -* 如果表的限定名称**同时**匹配 `do-tables` 和 `ignore-tables` 列表,表会被导入。 - -> **注意:** -> -> Lightning 会先执行数据库过滤规则,之后才执行表的过滤规则。所以,如果一个数据库已被 `ignore-dbs` 略过,即使其下的表匹配 `do-tables` 也不会再被导入。 - -## 例子 - -以下例子演示过滤规则的操作原理。假设数据源包含这些表: - -``` -`logs`.`messages_2016` -`logs`.`messages_2017` -`logs`.`messages_2018` -`forum`.`users` -`forum`.`messages` -`forum_backup_2016`.`messages` -`forum_backup_2017`.`messages` -`forum_backup_2018`.`messages` -`admin`.`secrets` -``` - -我们使用以下设置: - -```toml -[black-white-list] -do-dbs = [ - "forum_backup_2018", # 规则 A - "~^(logs|forum)$", # 规则 B -] -ignore-dbs = [ - "~^forum_backup_", # 规则 C -] - -[[black-white-list.do-tables]] # 规则 D -db-name = "logs" -tbl-name = "~_2018$" - -[[black-white-list.ignore-tables]] # 规则 E -db-name = "~.*" -tbl-name = "~^messages.*" - -[[black-white-list.do-tables]] # 规则 F -db-name = "~^forum.*" -tbl-name = "messages" -``` - -首先进行数据库过滤: - -| 数据库 | 结果 | -|---------------------------|--------------| -| `` `logs` `` | 导入(规则 B) | -| `` `forum` `` | 导入(规则 B) | -| `` `forum_backup_2016` `` | 略过(规则 C) | -| `` `forum_backup_2017` `` | 略过(规则 C) | -| `` `forum_backup_2018` `` | 导入(规则 A)(不会考虑规则 C) | -| `` `admin` `` | 略过(`do-dbs` 不为空,且没有匹配的项目) | - -然后进行表过滤: - -| 表 | 结果 | -|--------------------------------------|--------------| -| `` `logs`.`messages_2016` `` | 略过(规则 E) | -| `` `logs`.`messages_2017` `` | 略过(规则 E) | -| `` `logs`.`messages_2018` `` | 导入(规则 D)(不会考虑规则 E) | -| `` `forum`.`users` `` | 略过(`do-tables` 不为空,且没有匹配的项目) | -| `` `forum`.`messages` `` | 导入(规则 F)(不会考虑规则 E) | -| `` `forum_backup_2016`.`messages` `` | 略过(数据库已被剔除) | -| `` `forum_backup_2017`.`messages` `` | 略过(数据库已被剔除) | -| `` `forum_backup_2018`.`messages` `` | 导入(规则 F)(不会考虑规则 E) | -| `` `admin`.`secrets` `` | 略过(数据库已被剔除) |