主要特性

    Table Routing、Block & Allow Lists、Binlog Event Filter 在匹配库表名时，有以下版本差异：

    • 对于 v1.0.5 版及后续版本，以上功能均支持通配符匹配#Syntax)。但注意所有版本中通配符匹配中的 符号 只能有一个且必须在末尾。
    • 对于 v1.0.5 以前的版本，Table Routing 和 Binlog Event Filter 支持通配符，但不支持 [...] 与 [!...] 表达式。Block & Allow Lists 仅支持正则表达式。

    在简单任务场景下推荐使用通配符匹配。

    Table routing 提供将上游 MySQL/MariaDB 实例的某些表迁移到下游指定表的功能。

    参数解释

    将根据 schema-pattern/table-pattern 匹配上该规则的上游 MySQL/MariaDB 实例的表迁移到下游的 target-schema/target-table。

    使用示例

    下面展示了三个不同场景下的配置示例。

    分库分表合并

    假设存在分库分表场景，需要将上游两个 MySQL 实例的表 test_{1,2,3...}.t_{1,2,3...} 迁移到下游 TiDB 的一张表 test.t。

    为了迁移到下游实例的表 test.t，需要创建以下 table routing 规则：

    • rule-1 用来迁移匹配上 schema-pattern: "test_*" 和 table-pattern: "t_*" 的表的 DML/DDL 语句到下游的 test.t。
    • rule-2 用来迁移匹配上 schema-pattern: "test_*" 的库的 DDL 语句，例如 CREATE/DROP SCHEMA xx。

    注意：

    • 如果下游 TiDB schema: test 已经存在，并且不会被删除，则可以省略 rule-2。
    • 如果下游 TiDB schema: test 不存在，只设置了 rule_1，则迁移会报错 schema test doesn't exist。
    1.   rule-1:
    2.     schema-pattern: "test_*"
    3.     table-pattern: "t_*"
    4.     target-schema: "test"
    5.     target-table: "t"
    6.   rule-2:
    7.     schema-pattern: "test_*"
    8.     target-schema: "test"

    分库合并

    假设存在分库场景，将上游两个 MySQL 实例 test_{1,2,3...}.t_{1,2,3...} 迁移到下游 TiDB 的 test.t_{1,2,3...}，创建一条路由规则即可：

    1.   rule-1:
    2.     schema-pattern: "test_*"
    3.     target-schema: "test"

    错误的 table routing

    假设存在下面两个路由规则，test_1_bak.t_1_bak 可以匹配上 rule-1 和 rule-2，违反 table 路由的限制而报错。

    1.   rule-0:
    2.     schema-pattern: "test_*"
    3.   rule-1:
    4.     schema-pattern: "test_*"
    5.     table-pattern: "t_*"
    6.     target-schema: "test"
    7.     target-table: "t"
    8.   rule-2:
    9.     schema-pattern: "test_1_bak"
    10.     table-pattern: "t_1_bak"
    11.     target-schema: "test"
    12.     target-table: "t_bak"

    上游数据库实例表的黑白名单过滤规则，可以用来过滤或者只迁移某些 database/table 的所有操作。

    参数配置

    参数解释

    • do-dbs：要迁移的库的白名单，类似于 MySQL 中的 。
    • ignore-dbs：要迁移的库的黑名单，类似于 MySQL 中的 replicate-ignore-db。
    • do-tables：要迁移的表的白名单，类似于 MySQL 中的 。必须同时指定 db-name 与 tbl-name。
    • ignore-tables：要迁移的表的黑名单，类似于 MySQL 中的 replicate-ignore-table。必须同时指定 db-name 与 tbl-name。

    以上参数值以 ~ 开头时均支持使用来匹配库名、表名。

    do-dbs 与 ignore-dbs 对应的过滤规则与 MySQL 中的 Evaluation of Database-Level Replication and Binary Logging Options 类似，do-tables 与 ignore-tables 对应的过滤规则与 MySQL 中的 类似。

    1. 首先进行 schema 过滤判断

      • 如果 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 实例包含以下表：

    1. `logs`.`messages_2016`
    2. `logs`.`messages_2017`
    3. `logs`.`messages_2018`
    4. `forum`.`users`
    5. `forum`.`messages`
    6. `forum_backup_2016`.`messages`
    7. `forum_backup_2017`.`messages`
    8. `forum_backup_2018`.`messages`

    配置如下：

    1. block-allow-list:  # 如果 DM 版本早于 v2.0.0-beta.2 则使用 black-white-list。
    2.   bw-rule:
    3.     do-dbs: ["forum_backup_2018", "forum"]
    4.     ignore-dbs: ["~^forum_backup_"]
    5.     do-tables:
    6.     - db-name: "logs"
    7.       tbl-name: "~_2018$"
    8. ​      tbl-name: "messages"
    9.     ignore-tables:
    10.     - db-name: "~.*"
    11. ​      tbl-name: "^messages.*"

    应用 bw-rule 规则后：

    Binlog event filter 是比迁移表黑白名单更加细粒度的过滤规则，可以指定只迁移或者过滤掉某些 schema / table 的指定类型 binlog，比如 INSERT、TRUNCATE TABLE。

    参数配置

    1. filters:
    2.   rule-1:
    3.     schema-pattern: "test_*"
    4.     ​table-pattern: "t_*"
    5.     ​events: ["truncate table", "drop table"]
    6.     sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"]
    7.     ​action: Ignore

    参数解释

    • ：对匹配上的上游 MySQL/MariaDB 实例的表的 binlog events 或者 DDL SQL 语句通过以下规则进行过滤。

    • | 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 中任意一项。

    使用示例

    过滤分库分表的所有删除操作

    需要设置下面两个 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 操作。

    只迁移分库分表的 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。

    1. filters:
    2.   do-table-rule:
    3.     schema-pattern: "test_*"
    4.     table-pattern: "t_*"
    5.     events: ["create table", "all dml"]
    6.     action: Do
    7.   do-schema-rule:
    8.     schema-pattern: "test_*"
    9.     events: ["create database"]
    10.     action: Do

    过滤 TiDB 不支持的 SQL 语句

    可设置如下规则过滤 TiDB 不支持的 PROCEDURE 语句：

    1. filters:
    2.   filter-procedure-rule:
    3.     schema-pattern: "test_*"
    4.     table-pattern: "t_*"
    5.     sql-pattern: ["^DROP\\s+PROCEDURE", "^CREATE\\s+PROCEDURE"]
    6.     action: Ignore

    过滤 TiDB parser 不支持的 SQL 语句

    对于 TiDB parser 不支持的 SQL 语句，DM 无法解析获得 schema/table 信息，因此需要使用全局过滤规则：schema-pattern: "*"。

    可设置如下规则过滤某些版本的 TiDB parser 不支持的 PARTITION 语句：

    1. filters:
    2.   filter-partition-rule:
    3.     schema-pattern: "*"
    4.     sql-pattern: ["ALTER\\s+TABLE[\\s\\S]*ADD\\s+PARTITION", "ALTER\\s+TABLE[\\s\\S]*DROP\\s+PARTITION"]
    5.     action: Ignore

    在 MySQL 生态中，gh-ost 与 pt-osc 等工具较广泛地被使用，DM 对其提供了特殊的支持以避免对不必要的中间数据进行迁移。

    有关 DM 对 online DDL 工具支持的原理、处理流程等，可参考 。

    • 在开启 online-ddl 时，增量复制对应的 checkpoint 应不处于 online DDL 执行过程中。如上游某次 online DDL 操作开始于 binlog position-A、结束于 position-B，则增量复制的起始点应早于 position-A 或晚于 position-B，否则可能出现迁移出错，具体可参考 FAQ。

    参数配置

    在 v2.0.5 及之后的版本，请在 task 配置文件中使用 online-ddl 配置项。 如上游 MySQL/MariaDB （同时）使用 gh-ost 或 pt-osc 工具，则在 task 的配置文件中设置： yml online-ddl: true > 注意： > > 自 v2.0.5 起，online-ddl-scheme 已被弃用，请使用 online-ddl 代替 online-ddl-scheme。如设置 online-ddl: true 会覆盖掉 online-ddl-scheme。如设置 online-ddl-scheme: "pt" 或 online-ddl-scheme: "gh-ost" 会被转换为 online-ddl: true。
    在 v2.0.5 之前的版本（不含 v2.0.5），请在 task 配置文件中使用 online-ddl-scheme 配置项。 如上游 MySQL/MariaDB 使用的是 gh-ost 工具，则在 task 的配置文件中设置： 如上游 MySQL/MariaDB 使用的是 pt-osc 工具，则在 task 的配置文件中设置： yml online-ddl-scheme: "pt"

    DM 支持将上游 MySQL/MariaDB 各分库分表中的 DML、DDL 数据合并后迁移到下游 TiDB 的库表中。

    使用限制

    目前分库分表合并功能仅支持有限的场景，使用该功能前，请仔细阅读和乐观模式分库分表合并迁移使用限制。

    参数配置

    手动处理 Sharding DDL Lock

    如果分库分表合并迁移过程中发生了异常，对于部分场景，可尝试参考进行处理。