Refactor data migration (#7480)

TOC.md

@@ -37,17 +37,22 @@
     - [用 Sysbench 测试 TiDB](/benchmark/benchmark-tidb-using-sysbench.md)
     - [对 TiDB 进行 TPC-C 测试](/benchmark/benchmark-tidb-using-tpcc.md)
 - 数据迁移
-  - [数据迁移场景](/migration-overview.md)
+  - [数据迁移综述](/migration-overview.md)
   - [迁移工具](/migration-tools.md)
-  - 从 MySQL 迁移至 TiDB
-    - [使用 TiDB Lightning 从 Amazon Aurora MySQL 迁移全量数据](/migrate-from-aurora-using-lightning.md)
-    - [使用 TiDB Lightning 从 MySQL SQL 文件迁移全量数据](/migrate-from-mysql-dumpling-files.md)
-    - [使用 DM 工具从 Amazon Aurora MySQL 迁移数据](/migrate-from-aurora-mysql-database.md)
-  - 从 CSV 文件迁移至 TiDB
-    - [使用 TiDB Lightning 导入 CSV 文件](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md)
-    - [使用 LOAD DATA 语句导入 CSV 文件](/sql-statements/sql-statement-load-data.md)
-  - [从 SQL 文件迁移到 TiDB](/migrate-from-mysql-dumpling-files.md)
-  - [将 TiDB 集群的增量数据同步到另一集群](/incremental-replication-between-clusters.md)
+  - 数据迁移场景
+    - [从 Aurora 迁移数据到 TiDB](/migrate-aurora-to-tidb.md)
+    - [从小数据量 MySQL 迁移数据到 TiDB](/migrate-small-mysql-to-tidb.md)
+    - [从大数据量 MySQL 迁移数据到 TiDB](/migrate-large-mysql-to-tidb.md)
+    - [从小数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-small-mysql-shards-to-tidb.md)
+    - [从大数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-large-mysql-shards-to-tidb.md)
+    - [从 CSV 文件迁移数据到 TiDB](/migrate-from-csv-files-to-tidb.md)
+    - [从 SQL 文件迁移数据到 TiDB](/migrate-from-sql-files-to-tidb.md)
+    - [将 TiDB 集群的增量数据同步到另一集群](/incremental-replication-between-clusters.md)
+  - 复杂迁移操作
+    - [上游使用 pt/gh-ost 工具的持续同步场景](/migrate-with-pt-ghost.md)
+    - [如何根据类型或 DDL 内容过滤 binlog 事件](/filter-binlog-event.md)
+    - [如何通过 SQL 表达式过滤 DML binlog 事件](/filter-dml-event.md)
+    - [下游存在更多列的迁移场景](/migrate-with-more-columns-downstream.md)
 - 运维操作
   - 升级 TiDB 版本
     - [使用 TiUP 升级（推荐）](/upgrade-tidb-using-tiup.md)

_index.md

@@ -48,11 +48,9 @@ aliases: ['/docs-cn/dev/']
 <ColumnTitle>数据迁移</ColumnTitle>
 
 - [概述](/migration-overview.md)
-- [使用 Dumpling 与 TiDB Lightning 进行全量迁移](/migrate-from-mysql-dumpling-files.md)
-- [从 Aurora 全量迁移](/migrate-from-aurora-using-lightning.md)
-- [从 Aurora/MySQL 持续迁移](/migrate-from-aurora-mysql-database.md)
-- [从 CSV 文件迁移](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md)
-- [从 SQL 文件迁移](/migrate-from-mysql-dumpling-files.md)
+- [从 CSV 文件迁移数据到 TiDB](/migrate-from-csv-files-to-tidb.md)
+- [从 SQL 文件迁移数据到 TiDB](/migrate-from-sql-files-to-tidb.md)
+- [从 Aurora 迁移数据到 TiDB](/migrate-aurora-to-tidb.md)
 
 </NavColumn>
 

filter-binlog-event.md

@@ -0,0 +1,116 @@
+---
+title: 如何过滤 binlog 事件
+summary: 介绍如何过滤 binlog 事件。
+---
+
+# 如何过滤 binlog 事件
+
+本文档介绍使用 DM 持续增量数据同步时，如何过滤 binlog 事件。具体迁移操作可参考已有数据迁移场景：
+
+- [从小数据量 MySQL 迁移数据到 TiDB](/migrate-small-mysql-to-tidb.md)
+- [从大数据量 MySQL 迁移数据到 TiDB](/migrate-large-mysql-to-tidb.md)
+- [从小数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-small-mysql-shards-to-tidb.md)
+- [从大数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-large-mysql-shards-to-tidb.md)
+
+## 配置方式
+
+配置 DM 的任务配置文件时，增加如下`filter`，具体配置示例如下图：
+
+```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
+```
+
+- `schema-pattern`/`table-pattern`：对匹配上的 schema 或 table 进行过滤
+- `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 语句，支持正则表达式匹配。
+- `action`：可取值 Do 或 Ignore。
+    - `Do`：白名单。binlog event 如果满足下面两个条件之一将会被同步：
+        - 符合 events 条件；
+        - sql-pattern 不为空，且对应的 SQL 可以匹配上 sql-pattern 中任意一项。
+    - `Ignore`：黑名单。如果满足下面两个条件之一就会被过滤掉：
+        - 符合 events 条件；
+        - sql-pattern 不为空，且对应的 SQL 可以匹配上 sql-pattern 中任意一项
+
+注意：如果同时配置 `Do/Ignore`，则 `Ignore` 优先级更高。`binlog event` 不匹配白名单或者匹配黑名单都将被直接过滤。
+
+## 使用场景举例
+
+### 过滤分库分表的所有删除操作
+
+设置 `filter-table-rule` 和 `filter-schema-rule` 两个过滤规则，具体如下：
+
+```
+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`：
+
+```
+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 语句
+
+```
+filters:
+  filter-procedure-rule:
+    schema-pattern: "*"
+    sql-pattern: [".*\\s+DROP\\s+PROCEDURE", ".*\\s+CREATE\\s+PROCEDURE", "ALTER\\s+TABLE[\\s\\S]*ADD\\s+PARTITION", "ALTER\\s+TABLE[\\s\\S]*DROP\\s+PARTITION"]
+    action: Ignore
+```
+
+> **注意：**
+>
+> 全局过滤规则的设置必须尽可能严格，以避免过滤掉需要迁移的数据。
+
+## 探索更多
+
+- [如何通过 SQL 表达式过滤 binlog](/filter-dml-event.md)

filter-dml-event.md

@@ -0,0 +1,82 @@
+---
+title: 如何通过 SQL 表达式过滤 DML
+summary: 介绍如何通过 SQL 表达式过滤 DML 事件
+---
+
+# 如何通过 SQL 表达式过滤  DML
+
+本文档介绍使用 DM 持续增量数据同步时，如何更加精细的过滤 binlog 事件。具体迁移操作可参考已有数据迁移场景：
+
+- [从小数据量 MySQL 迁移数据到 TiDB](/migrate-small-mysql-to-tidb.md)
+- [从大数据量 MySQL 迁移数据到 TiDB](/migrate-large-mysql-to-tidb.md)
+- [从小数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-small-mysql-shards-to-tidb.md)
+- [从大数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-large-mysql-shards-to-tidb.md)
+
+在进行增量数据迁移时，可以通过[如何过滤 binlog 事件](/filter-binlog-event.md)功能过滤某些类型的 binlog event，例如不向下游迁移 `DELETE` 事件以达到归档、审计等目的。但是 binlog event filter 无法以更细粒度判断某一行的 `DELETE` 事件是否要被过滤。
+
+为了解决上述问题，从 v2.0.5 起，DM 支持在增量数据同步阶段使用`binlog value filter`过滤迁移数据。DM 支持的 `ROW` 格式的 binlog 中，binlog event 带有所有列的值。你可以基于这些值配置 SQL 表达式。如果该表达式对于某条行变更的计算结果是 `TRUE`，DM 就不会向下游迁移该条行变更。
+
+与[如何过滤 binlog 事件](/filter-binlog-event.md)类似，表达式过滤需要在数据迁移任务配置文件里配置，详见下面配置样例。完整的配置及意义，可以参考 [DM 完整配置文件示例](https://docs.pingcap.com/zh/tidb-data-migration/stable/task-configuration-file-full#完整配置文件示例)：
+
+```yaml
+name: test
+task-mode: all
+
+mysql-instances:
+  - source-id: "mysql-replica-01"
+    expression-filters: ["even_c"]
+
+expression-filter:
+  even_c:
+    schema: "expr_filter"
+    table: "tbl"
+    insert-value-expr: "c % 2 = 0"
+```
+
+上面的示例配置了 `even_c` 规则，并让 source ID 为 `mysql-replica-01` 的数据源引用了该规则。`even_c` 规则的含义是：对于 `expr_filter` 库下的 `tbl` 表，当插入的 `c` 的值为偶数 (`c % 2 = 0`) 时，不将这条插入语句迁移到下游。下面展示该规则的使用效果。
+
+在上游数据源增量插入以下数据：
+
+```sql
+INSERT INTO tbl(id, c) VALUES (1, 1), (2, 2), (3, 3), (4, 4);
+```
+
+随后在下游查询 `tbl` 表，可见只有 `c` 的值为单数的行迁移到了下游：
+
+```
+MySQL [test]> select * from tbl;
+
++------+------+
+| id   | c    |
++------+------+
+|    1 |    1 |
+|    3 |    3 |
++------+------+
+
+2 rows in set (0.001 sec)
+```
+
+## 配置参数及规则说明
+
+- `schema`：要匹配的上游数据库库名，不支持通配符匹配或正则匹配。
+- `table`: 要匹配的上游表名，不支持通配符匹配或正则匹配。
+- `insert-value-expr`：配置一个表达式，对 INSERT 类型的 binlog event (WRITE_ROWS_EVENT) 带有的值生效。不能与 `update-old-value-expr`、`update-new-value-expr`、`delete-value-expr` 出现在一个配置项中。
+- `update-old-value-expr`：配置一个表达式，对 UPDATE 类型的 binlog event (UPDATE_ROWS_EVENT) 更新对应的旧值生效。不能与 `insert-value-expr`、`delete-value-expr` 出现在一个配置项中。
+- `update-new-value-expr`：配置一个表达式，对 UPDATE 类型的 binlog event (UPDATE_ROWS_EVENT) 更新对应的新值生效。不能与 `insert-value-expr`、`delete-value-expr` 出现在一个配置项中。
+- `delete-value-expr`：配置一个表达式，对 DELETE 类型的 binlog event (DELETE_ROWS_EVENT) 带有的值生效。不能与 `insert-value-expr`、`update-old-value-expr`、`update-new-value-expr` 出现在一个配置项中。
+
+> **注意：**
+>
+> - `update-old-value-expr` 可以与 `update-new-value-expr` 同时配置。
+> - 当二者同时配置时，会将“更新+旧值“满足`update-old-value-expr` **且**”更新+新值“满足 `update-new-value-expr` 的行过滤掉。
+> - 当只配置一者时，配置的这条表达式会决定是否过滤**整个行变更**，即旧值的删除和新值的插入会作为一个整体被过滤掉。
+
+SQL 表达式可以涉及一列或多列，也可使用 TiDB 支持的 SQL 函数，例如 `c % 2 = 0`、`a*a + b*b = c*c`、`ts > NOW()`。
+
+TIMESTAMP 类型的默认时区是任务配置文件中指定的时区，默认值是下游时区。可以使用 `c_timestamp = '2021-01-01 12:34:56.5678+08:00'` 的方式显式指定时区。
+
+配置项 `expression-filter` 下可以定义多条过滤规则，上游数据源在其 `expression-filters` 配置项中引用需要的规则使其生效。当有多条规则生效时，匹配到**任意一条**规则即会导致某个行变更被过滤。
+
+> **注意：**
+>
+> 为某张表设置过多的表达式过滤会增加 DM 的计算开销，可能导致数据迁移速度变慢。