dm: split dm features into several docs (#11878) (#12097)

pingcap · Nov 23, 2022 · 50ae012 · 50ae012
1 parent 1fa2913
commit 50ae012
Show file tree

Hide file tree

Showing 19 changed files with 634 additions and 626 deletions.
diff --git a/TOC.md b/TOC.md
@@ -421,10 +421,12 @@
       - [创建数据源](/dm/quick-start-create-source.md)
       - [数据源操作](/dm/dm-manage-source.md)
       - [任务配置向导](/dm/dm-task-configuration-guide.md)
-      - [Table routing](/dm/dm-key-features.md#table-routing)
-      - [Block & Allow Lists](/dm/dm-key-features.md#block--allow-table-lists)
-      - [过滤 binlog 事件](/dm/dm-key-features.md#binlog-event-filter)
+      - [分库分表合并](/dm/dm-shard-merge.md)
+      - [表路由](/dm/dm-table-routing.md)
+      - [黑白名单](/dm/dm-block-allow-table-lists.md)
+      - [过滤 binlog 事件](/dm/dm-binlog-event-filter.md)
       - [通过 SQL 表达式过滤 DML](/dm/feature-expression-filter.md)
+      - [Online DDL 工具支持](/dm/dm-online-ddl-tool-support.md)
       - 迁移任务操作
         - [任务前置检查](/dm/dm-precheck.md)
         - [创建任务](/dm/dm-create-task.md)

diff --git a/dm/dm-binlog-event-filter.md b/dm/dm-binlog-event-filter.md
@@ -0,0 +1,145 @@
+---
+title: TiDB Data Migration Binlog 事件过滤
+summary: 了解 DM 的关键特性 binlog 事件过滤 (Binlog event filter) 的使用方法和注意事项。
+---
+
+## TiDB Data Migration Binlog 事件过滤
+
+TiDB Data Migration (DM) 的 Binlog 事件过滤 (Binlog event filter) 是比迁移表[黑白名单](/dm/dm-block-allow-table-lists.md)更加细粒度的过滤规则，可以指定只迁移或者过滤掉某些 `schema / table` 的指定类型 binlog，比如 `INSERT`、`TRUNCATE TABLE`。
+
+## 配置 Binlog 事件过滤
+
+在迁移任务配置文件中，添加如下配置：
+
+```yaml
+filters:
+  rule-1:
+    schema-pattern: "test_*"
+    table-pattern: "t_*"
+    events: ["truncate table", "drop table"]
+    sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"]
+    action: Ignore
+```
+
+从 DM v2.0.2 开始，你也可以在上游数据库配置文件中配置 Binlog 事件过滤。见[上游数据库配置文件介绍](/dm/dm-source-configuration-file.md)。
+
+在简单任务场景下，推荐使用通配符匹配库表名，但需注意以下版本差异：
+
++ 对于 v1.0.5 版及后续版本，Binlog 事件过滤支持[通配符匹配](https://en.wikipedia.org/wiki/Glob_(programming)#Syntax)。但注意所有版本中通配符匹配中的 `*` 符号 **只能有一个，且必须在末尾**。
++ 对于 v1.0.5 以前的版本，Binlog Event Filter 支持通配符，但不支持 `[...]` 与 `[!...]` 表达式。
+
+## 参数解释
+
+- [`schema-pattern`/`table-pattern`](/dm/table-selector.md)：对匹配上的上游 MySQL/MariaDB 实例的表的 binlog events 或者 DDL SQL 语句通过以下规则进行过滤。
+
+- `events`：binlog events 数组，仅支持从以下 `Event` 中选择一项或多项。
+
+    | Event           | 分类 | 解释                           |
+    | --------------- | ---- | ----------------------------- |
+    | all             |      | 代表包含下面所有的 events        |
+    | all dml         |      | 代表包含下面所有 DML events     |
+    | all ddl         |      | 代表包含下面所有 DDL events     |
+    | none            |      | 代表不包含下面所有 events        |
+    | none ddl        |      | 代表不包含下面所有 DDL events    |
+    | none dml        |      | 代表不包含下面所有 DML events    |
+    | insert          | DML  | insert DML event              |
+    | update          | DML  | update DML event              |
+    | delete          | DML  | delete DML event              |
+    | create database | DDL  | create database event         |
+    | drop database   | DDL  | drop database event           |
+    | create table    | DDL  | create table event            |
+    | create index    | DDL  | create index event            |
+    | drop table      | DDL  | drop table event              |
+    | truncate table  | DDL  | truncate table event          |
+    | rename table    | DDL  | rename table event            |
+    | drop index      | DDL  | drop index event              |
+    | alter table     | DDL  | alter table event             |
+
+- `sql-pattern`：用于过滤指定的 DDL SQL 语句，支持正则表达式匹配，例如上面示例中的 `"^DROP\\s+PROCEDURE"`。
+
+- `action`：string (`Do` / `Ignore`)；进行下面规则判断，满足其中之一则过滤，否则不过滤。
+
+    - `Do`：白名单。binlog event 如果满足下面两个条件之一就会被过滤掉：
+        - 不在该 rule 的 `events` 中。
+        - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 没有匹配上 `sql-pattern` 中任意一项。
+    - `Ignore`：黑名单。如果满足下面两个条件之一就会被过滤掉：
+        - 在该 rule 的 `events` 中。
+        - 如果规则的 `sql-pattern` 不为空的话，对应的 SQL 可以匹配上 `sql-pattern` 中任意一项。
+    - 同一个表匹配上多个规则时，将会顺序应用这些规则，并且黑名单的优先级高于白名单，即如果同时存在规则 `Ignore` 和 `Do` 应用在某个表上，那么 `Ignore` 生效。
+
+## 使用示例
+
+### 过滤分库分表的所有删除操作
+
+需要设置下面两个 `Binlog event filter rule` 来过滤掉所有的删除操作：
+
+- `filter-table-rule` 过滤掉所有匹配到 pattern `test_*`.`t_*` 的 table 的 `turncate table`、`drop table`、`delete statement` 操作。
+- `filter-schema-rule` 过滤掉所有匹配到 pattern `test_*` 的 schema 的 `drop database` 操作。
+
+```yaml
+filters:
+  filter-table-rule:
+    schema-pattern: "test_*"
+    table-pattern: "t_*"
+    events: ["truncate table", "drop table", "delete"]
+    action: Ignore
+  filter-schema-rule:
+    schema-pattern: "test_*"
+    events: ["drop database"]
+    action: Ignore
+```
+
+### 只迁移分库分表的 DML 操作
+
+需要设置下面两个 `Binlog event filter rule` 只迁移 DML 操作：
+
+- `do-table-rule` 只迁移所有匹配到 pattern `test_*`.`t_*` 的 table 的 `create table`、`insert`、`update`、`delete` 操作。
+- `do-schema-rule` 只迁移所有匹配到 pattern `test_*` 的 schema 的 `create database` 操作。
+
+> **注意：**
+>
+> 迁移 `create database/table` 的原因是创建库和表后才能迁移 `DML`。
+
+```yaml
+filters:
+  do-table-rule:
+    schema-pattern: "test_*"
+    table-pattern: "t_*"
+    events: ["create table", "all dml"]
+    action: Do
+  do-schema-rule:
+    schema-pattern: "test_*"
+    events: ["create database"]
+    action: Do
+```
+
+### 过滤 TiDB 不支持的 SQL 语句
+
+可设置如下规则过滤 TiDB 不支持的 `PROCEDURE` 语句：
+
+```yaml
+filters:
+  filter-procedure-rule:
+    schema-pattern: "test_*"
+    table-pattern: "t_*"
+    sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"]
+    action: Ignore
+```
+
+### 过滤 TiDB parser 不支持的 SQL 语句
+
+对于 TiDB parser 不支持的 SQL 语句，DM 无法解析获得 `schema`/`table` 信息，因此需要使用全局过滤规则：`schema-pattern: "*"`。
+
+> **注意：**
+>
+> 全局过滤规则的设置必须尽可能严格，以避免过滤掉需要迁移的数据。
+
+可设置如下规则过滤某些版本的 TiDB parser 不支持的 `PARTITION` 语句：
+
+```yaml
+filters:
+  filter-partition-rule:
+    schema-pattern: "*"
+    sql-pattern: ["ALTER\\s+TABLE[\\s\\S]*ADD\\s+PARTITION", "ALTER\\s+TABLE[\\s\\S]*DROP\\s+PARTITION"]
+    action: Ignore
+```
diff --git a/dm/dm-block-allow-table-lists.md b/dm/dm-block-allow-table-lists.md
@@ -0,0 +1,142 @@
+---
+title: TiDB Data Migration 黑白名单过滤
+summary:  了解 DM 的关键特性黑白名单过滤 (Block & Allow List) 的使用方法和注意事项。
+---
+
+# TiDB Data Migration 黑白名单过滤
+
+使用 TiDB Data Migration (DM) 迁移数据时，你可以配置上游数据库实例表的黑白名单过滤 (Block & Allow List) 规则，用来过滤或者只迁移某些 `database/table` 的所有操作。
+
+## 配置黑白名单
+
+在迁移任务配置文件中，添加如下配置：
+
+```yaml
+block-allow-list:             # 如果 DM 版本早于 v2.0.0-beta.2 则使用 black-white-list。
+  rule-1:
+    do-dbs: ["test*"]         # 非 ~ 字符开头，表示规则是通配符；v1.0.5 及后续版本支持通配符规则。
+    do-tables:
+    - db-name: "test[123]"    # 匹配 test1、test2、test3。
+      tbl-name: "t[1-5]"      # 匹配 t1、t2、t3、t4、t5。
+    - db-name: "test"
+      tbl-name: "t"
+  rule-2:
+    do-dbs: ["~^test.*"]      # 以 ~ 字符开头，表示规则是正则表达式。
+    ignore-dbs: ["mysql"]
+    do-tables:
+    - db-name: "~^test.*"
+      tbl-name: "~^t.*"
+    - db-name: "test"
+      tbl-name: "t"
+    ignore-tables:
+    - db-name: "test"
+      tbl-name: "log"
+```
+
+在简单任务场景下，推荐使用通配符匹配库表名，但需注意以下版本差异：
+
++ 对于 v1.0.5 版及后续版本，黑白名单支持[通配符匹配](https://en.wikipedia.org/wiki/Glob_(programming)#Syntax)。但注意所有版本中通配符匹配中的 `*` 符号 **只能有一个，且必须在末尾**。
++ 对于 v1.0.5 以前的版本，黑白名单仅支持正则表达式。
+
+## 参数解释
+
+- `do-dbs`：要迁移的库的白名单，类似于 MySQL 中的 [`replicate-do-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-replica.html#option_mysqld_replicate-do-db)。
+- `ignore-dbs`：要迁移的库的黑名单，类似于 MySQL 中的 [`replicate-ignore-db`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-replica.html#option_mysqld_replicate-ignore-db)。
+- `do-tables`：要迁移的表的白名单，类似于 MySQL 中的 [`replicate-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-replica.html#option_mysqld_replicate-do-table)。必须同时指定 `db-name` 与 `tbl-name`。
+- `ignore-tables`：要迁移的表的黑名单，类似于 MySQL 中的 [`replicate-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-replica.html#option_mysqld_replicate-ignore-table)。必须同时指定 `db-name` 与 `tbl-name`。
+
+以上参数值以 `~` 开头时均支持使用[正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)来匹配库名、表名。
+
+## 过滤规则
+
+- `do-dbs` 与 `ignore-dbs` 对应的过滤规则与 MySQL 中的 [Evaluation of Database-Level Replication and Binary Logging Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-db-options.html) 类似。
+- `do-tables` 与 `ignore-tables` 对应的过滤规则与 MySQL 中的 [Evaluation of Table-Level Replication Options](https://dev.mysql.com/doc/refman/5.7/en/replication-rules-table-options.html) 类似。
+
+> **注意：**
+>
+> DM 中黑白名单过滤规则与 MySQL 中相应规则存在以下区别：
+>
+> - MySQL 中存在 [`replicate-wild-do-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-replica.html#option_mysqld_replicate-wild-do-table) 与 [`replicate-wild-ignore-table`](https://dev.mysql.com/doc/refman/5.7/en/replication-options-replica.html#option_mysqld_replicate-wild-ignore-table) 用于支持通配符，DM 中各配置参数直接支持以 `~` 字符开头的正则表达式。
+> - DM 当前只支持 `ROW` 格式的 binlog，不支持 `STATEMENT`/`MIXED` 格式的 binlog，因此应与 MySQL 中 `ROW` 格式下的规则对应。
+> - 对于 DDL，MySQL 仅依据默认的 database 名称（`USE` 语句显式指定的 database）进行判断，而 DM 优先依据 DDL 中的 database 名称部分进行判断，并当 DDL 中不包含 database 名称时再依据 `USE` 部分进行判断。假设需要判断的 SQL 为 `USE test_db_2; CREATE TABLE test_db_1.test_table (c1 INT PRIMARY KEY)`，且 MySQL 配置了 `replicate-do-db=test_db_1`、DM 配置了 `do-dbs: ["test_db_1"]`，则对于 MySQL 该规则不会生效，而对于 DM 该规则会生效。
+
+判断 table `test`.`t` 是否应该被过滤的流程如下：
+
+1. 首先进行 **schema 过滤判断**
+
+    - 如果 `do-dbs` 不为空，判断 `do-dbs` 中是否存在一个匹配的 schema。
+
+        - 如果存在，则进入 **table 过滤判断**。
+        - 如果不存在，则过滤 `test`.`t`。
+
+    - 如果 `do-dbs` 为空并且 `ignore-dbs` 不为空，判断 `ignore-dbs` 中是否存在一个匹配的 schema。
+
+        - 如果存在，则过滤 `test`.`t`。
+        - 如果不存在，则进入 **table 过滤判断**。
+
+    - 如果 `do-dbs` 和 `ignore-dbs` 都为空，则进入 **table 过滤判断**。
+
+2. 进行 **table 过滤判断**
+
+    1. 如果 `do-tables` 不为空，判断 `do-tables` 中是否存在一个匹配的 table。
+
+        - 如果存在，则迁移 `test`.`t`。
+        - 如果不存在，则过滤 `test`.`t`。
+
+    2. 如果 `ignore-tables` 不为空，判断 `ignore-tables` 中是否存在一个匹配的 table。
+
+        - 如果存在，则过滤 `test`.`t`.
+        - 如果不存在，则迁移 `test`.`t`。
+
+    3. 如果 `do-tables` 和 `ignore-tables` 都为空，则迁移 `test`.`t`。
+
+> **注意：**
+>
+> 如果是判断 schema `test` 是否应该被过滤，则只进行 **schema 过滤判断**。
+
+## 使用示例
+
+假设上游 MySQL 实例包含以下表：
+
+```
+`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`
+```
+
+配置如下：
+
+{{< copyable "" >}}
+
+```yaml
+block-allow-list:  # 如果 DM 版本早于 v2.0.0-beta.2 则使用 black-white-list。
+  bw-rule:
+    do-dbs: ["forum_backup_2018", "forum"]
+    ignore-dbs: ["~^forum_backup_"]
+    do-tables:
+    - db-name: "logs"
+      tbl-name: "~_2018$"
+    - db-name: "~^forum.*"
+      tbl-name: "messages"
+    ignore-tables:
+    - db-name: "~.*"
+      tbl-name: "^messages.*"
+```
+
+应用 `bw-rule` 规则后：
+
+| table | 是否过滤| 过滤的原因 |
+|:----|:----|:--------------|
+| `logs`.`messages_2016` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 |
+| `logs`.`messages_2017` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 |
+| `logs`.`messages_2018` | 是 | schema `logs` 没有匹配到 `do-dbs` 任意一项 |
+| `forum_backup_2016`.`messages` | 是 | schema `forum_backup_2016` 没有匹配到 `do-dbs` 任意一项 |
+| `forum_backup_2017`.`messages` | 是 | schema `forum_backup_2017` 没有匹配到 `do-dbs` 任意一项 |
+| `forum`.`users` | 是 | 1. schema `forum` 匹配到 `do-dbs`，进入 table 过滤判断<br/> 2. schema 和 table 没有匹配到 `do-tables` 和 `ignore-tables` 中任意一项，并且 `do-tables` 不为空，因此过滤 |
+| `forum`.`messages` | 否 | 1. schema `forum` 匹配到 `do-dbs`，进入 table 过滤判断<br/> 2. schema 和 table 匹配到 `do-tables` 的 `db-name: "~^forum.*",tbl-name: "messages"` |
+| `forum_backup_2018`.`messages` | 否 | 1. schema `forum_backup_2018` 匹配到 `do-dbs`，进入 table 过滤判断<br/> 2. schema 和 table 匹配到 `do-tables` 的  `db-name: "~^forum.*",tbl-name: "messages"` |
diff --git a/dm/dm-dml-replication-logic.md b/dm/dm-dml-replication-logic.md
@@ -14,8 +14,8 @@ Sync 单元对 DML 的处理步骤如下：
 1. 从 MySQL、MariaDB 或 relay log 中，读取 binlog event。
 2. 转换读取到的 binlog event：
 
-    1. [Binlog filter](/dm/dm-key-features.md#binlog-event-filter)：根据 binlog 表达式过滤 binlog event，通过 `filters` 配置。
-    2. [Table routing](/dm/dm-key-features.md#table-routing)：根据“库/表”路由规则对“库/表”名进行转换，通过 `routes` 配置。
+    1. [Binlog filter](/dm/dm-binlog-event-filter.md)：根据 binlog 表达式过滤 binlog event，通过 `filters` 配置。
+    2. [Table routing](/dm/dm-table-routing.md)：根据“库/表”路由规则对“库/表”名进行转换，通过 `routes` 配置。
     3. [Expression filter](/filter-dml-event.md)：根据 SQL 表达式过滤 binlog event，通过 `expression-filter` 配置。
 
 3. 优化 DML 执行：

diff --git a/dm/dm-faq.md b/dm/dm-faq.md
@@ -179,7 +179,7 @@ curl -X POST -d "tidb_general_log=0" http://{TiDBIP}:10080/settings
 if the DDL is not needed, you can use a filter rule with \"*\" schema-pattern to ignore it.\n\t : parse statement: line 1 column 11 near \"EVENT `event_del_big_table` \r\nDISABLE\" %!!(MISSING)(EXTRA string=ALTER EVENT `event_del_big_table` \r\nDISABLE
 ```
 
-出现报错的原因是 TiDB parser 无法解析上游的 DDL，例如 `ALTER EVENT`，所以 `sql-skip` 不会按预期生效。可以在任务配置文件中添加 [Binlog 过滤规则](/dm/dm-key-features.md#binlog-event-filter)进行过滤，并设置 `schema-pattern: "*"`。从 DM 2.0.1 版本开始，已预设过滤了 `EVENT` 相关语句。
+出现报错的原因是 TiDB parser 无法解析上游的 DDL，例如 `ALTER EVENT`，所以 `sql-skip` 不会按预期生效。可以在任务配置文件中添加 [Binlog 过滤规则](/dm/dm-binlog-event-filter.md)进行过滤，并设置 `schema-pattern: "*"`。从 DM 2.0.1 版本开始，已预设过滤了 `EVENT` 相关语句。
 
 在 DM v6.0 版本之后 `sql-skip`、`handle-error` 均已经被 `binlog` 替代，使用 `binlog` 命令可以跳过该类错误。
 

diff --git a/dm/dm-glossary.md b/dm/dm-glossary.md
@@ -19,7 +19,7 @@ MySQL/MariaDB 生成的 Binlog 文件中的数据变更信息，具体请参考
 
 ### Binlog event filter
 
-比 Block & allow table list 更加细粒度的过滤功能，具体可参考 [Binlog Event Filter](/dm/dm-key-features.md#binlog-event-filter)。
+比 Block & allow table list 更加细粒度的过滤功能，具体可参考 [Binlog Event Filter](/dm/dm-binlog-event-filter.md)。
 
 ### Binlog position
 
@@ -31,7 +31,7 @@ DM-worker 内部用于读取上游 Binlog 或本地 Relay log 并迁移到下游
 
 ### Block & allow table list
 
-针对上游数据库实例表的黑白名单过滤功能，具体可参考 [Block & Allow Table Lists](/dm/dm-key-features.md#block--allow-table-lists)。该功能与 [MySQL Replication Filtering](https://dev.mysql.com/doc/refman/5.6/en/replication-rules.html) 及 [MariaDB Replication Filters](https://mariadb.com/kb/en/library/replication-filters/) 类似。
+针对上游数据库实例表的黑白名单过滤功能，具体可参考 [Block & Allow Table Lists](/dm/dm-block-allow-table-lists.md)。该功能与 [MySQL Replication Filtering](https://dev.mysql.com/doc/refman/5.6/en/replication-rules.html) 及 [MariaDB Replication Filters](https://mariadb.com/kb/en/library/replication-filters/) 类似。
 
 ## C
 
@@ -127,7 +127,7 @@ DM-worker 内部用于从上游拉取 Binlog 并写入数据到 Relay log 的处
 
 ### Table routing
 
-用于支持将上游 MySQL/MariaDB 实例的某些表迁移到下游指定表的路由功能，可以用于分库分表的合并迁移，具体可参考 [Table routing](/dm/dm-key-features.md#table-routing)。
+用于支持将上游 MySQL/MariaDB 实例的某些表迁移到下游指定表的路由功能，可以用于分库分表的合并迁移，具体可参考 [Table routing](/dm/dm-table-routing.md)。
 
 ### Task
 

diff --git a/dm/dm-handle-performance-issues.md b/dm/dm-handle-performance-issues.md
@@ -71,7 +71,7 @@ Binlog replication 模块会根据配置选择从上游 MySQL/MariaDB 或 relay
 
 ### binlog event 转换
 
-Binlog replication 模块从 binlog event 数据中尝试构造 DML、解析 DDL 以及进行 [table router](/dm/dm-key-features.md#table-routing) 转换等，主要的性能指标是 `transform binlog event duration`。
+Binlog replication 模块从 binlog event 数据中尝试构造 DML、解析 DDL 以及进行 [table router](/dm/dm-table-routing.md) 转换等，主要的性能指标是 `transform binlog event duration`。
 
 这部分的耗时受上游写入的业务特点影响较大，如对于 `INSERT INTO` 语句，转换单个 `VALUES` 的时间和转换大量 `VALUES` 的时间差距很多，其波动范围可能从几十微秒至上百微秒，但一般不会成为系统的瓶颈。