mo_cdc 数据同步

迁移方向说明:本页 mo_cdc 以 MatrixOne 为源端,MySQL/MatrixOne 为下游;URI 的 mysql:// 是协议,不能据此当作 MySQL 到 MO 的源日志连接器。全量/增量边界、保留窗口与切换要求见迁移流程。

**CDC(Change Data Capture)**是一种实时捕获数据库中数据变更的技术,能够记录插入、更新和删除操作。它通过监控数据库的变更,实现数据的实时同步和增量处理,确保不同系统间数据的一致性。CDC 适用于实时数据同步、数据迁移、灾难恢复和审计跟踪等场景,通过读取事务日志等方式,减少全量数据复制的压力,并提升系统的性能和效率。其优势在于低延迟、高实时性,灵活支持多种数据库和系统,适应不断变化的大规模数据环境。

在进行 CDC 同步之前,必须提前创建包含同步范围的 PITR(时间点恢复)能力,且建议覆盖至少 2 小时的变更范围。这样可以确保在同步任务发生中断或异常时,系统能回溯并重新读取变更数据,避免数据丢失或不一致。

MatrixOne 支持通过 mo_cdc 实用工具进行租户/数据库/表级别的数据同步。本章节将介绍 mo_cdc 的使用方法。

备注

CDC 引擎运行在 MatrixOne 服务端,mo_cdc 是管理 CDC 任务的命令行入口。

安装并启动 MatrixOne

CDC 引擎已经内置在 MatrixOne 服务端,不需要再安装或启动一个独立的 CDC 服务。 按照当前环境的标准方式安装并启动 MatrixOne,然后确认 MySQL 客户端可以连接其 SQL 端口。例如,本地 Docker 实例可以使用:

docker run -d -p 6001:6001 --name matrixone matrixorigin/matrixone:latest
mysql -h127.0.0.1 -P6001 -uroot -p111 -e "SELECT VERSION()"

本页的 mo_cdc 命令是管理 MatrixOne 内部 CDC 任务的命令行入口,不会再启动一个 数据库服务。在提供该管理工具的环境中执行 ./mo_cdc help 或 mo_cdc help。 help 成功表示管理入口可用,SELECT VERSION() 成功表示 MatrixOne 服务端连接 正常;二者都不会创建 CDC 任务。创建任务前,仍需先创建覆盖同步范围的 PITR, 然后执行下面的任务命令。

文档规定的主要方向是 MatrixOne 作为源端、MySQL 作为下游;任务语法也包含 MatrixOne 到 MatrixOne 的同步示例。mo_cdc 不是 MySQL 到 MatrixOne 的 binlog 源端连接器。

参考命令指南

help - 打印参考指南

(base) admin@admindeMBP mo-backup % ./mo_cdc help
This command allows you to manage CDC Task, including task create, task show, task pause, task resume, task restart, and task drop.

Usage:
  mo_cdc [flags]
  mo_cdc [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  task        Manage Task

Flags:
  -h, --help   help for mo_cdc

Use "mo_cdc [command] --help" for more information about a command.

创建任务

语法结构

mo_cdc task create
    --task-name
    --source-uri
    --sink-type
    --sink-uri
    --level
      account|database|table
    --databases
    --tables
    --no-full
    --start-ts
    --end-ts
    --send-sql-timeout
    --max-sql-length
    --exclude
    --error-handle-option

参数说明

参数

说明

task-name

同步任务名称

source-uri

源端 (matrixone) 连接串

sink-type

下游类型,目前支持 mysql 和 matrixone

sink-uri

下游连接串;与 sink-type 对应,包含下游地址和认证信息。

level

同步的范围,account|database|table

databases

可选,同步范围为数据库级别时需指定

tables

可选,同步范围为表级别时需指定

no-full

可选,默认开启全量,添加此参数表示全量关闭

start-ts

可选,从数据库中的特定时间戳开始拉取数据,需小于当前时间。

end-ts

可选,数据拉取将停止于数据库中的指定时间戳,在指定 start-ts 时,需大于 start-ts。

send-sql-timeout

向下游发送 SQL 的超时;单位和默认值请以所安装工具的 task create --help 为准。

max-sql-length

可选,发送单条 sql 长度限制,默认为 4MB 和下游 max_packet_size 变量的较小值

exclude

可选,指定过滤对象,即这部分对象不同步,支持正则表达式

error-handle-option

可选,stop|ignore,用来控制当向下游同步数据的时候,如果遇到了错误并到达重试时间:5 分钟后如何工作,默认 stop,表示停止该表的同步,可设置为 ignore,表示跳过此错误,继续往下同步

示例

>./mo_cdc task create --task-name "ms_task1" --source-uri "mysql://root:111@127.0.0.1:6001" --sink-uri "mysql://root:111@127.0.0.1:3306" --sink-type "mysql" --level table --tables "db1.t1:db1.t1"

>./mo_cdc task create --task-name "ms_task2" --source-uri "mysql://acc1:admin:111@127.0.0.1:6001" --sink-uri "mysql://root:111@127.0.0.1:3306" --sink-type "mysql" --level "account"

>./mo_cdc task create --task-name "mo_task1" --source-uri "mysql://root:111@127.0.0.1:6001" --sink-uri "mysql://root:111@10.222.xx.xx:6001" --sink-type "matrixone" --level database --databases "db1:db2"

查看任务

查看 cdc 任务只能查看当前连接用户创建的任务。

语法结构

mo_cdc task show
    --source-uri
    --all
    --task-name

参数说明

参数

说明

source-uri

源端服务器地址

all

查看所有同步任务

task-name

同步任务名称

返回信息

字段

说明

task-id

任务 id

task-name

任务名称

source-uri

源端服务器地址

sink-uri

下游标识资源

state

任务状态,running 或 stopped

checkpoint

同步进度

timestamp

当前时间戳

示例

#查看所有同步任务
> ./mo_cdc task show --source-uri "mysql://root:111@127.0.0.1:6001"  --all
[
  {
    "task-id": "0195db8d-1a36-73d0-9fa3-e37839638b4b",
    "task-name": "mo_task1",
    "source-uri": "mysql://root:******@127.0.0.1:6001",
    "sink-uri": "mysql://root:******@10.222.xx.xx:6001",
    "state": "running",
    "err-msg": "",
    "checkpoint": "{\n  \"db1.t1\": 2025-03-28 15:00:35.790209 +0800 CST,\n}",
    "timestamp": "2025-03-28 15:00:36.207296 +0800 CST"
  },
  {
    "task-id": "0195db5c-6406-73d8-bbf6-25fb8b9dd45d",
    "task-name": "task1",
    "source-uri": "mysql://root:******@127.0.0.1:6001",
    "sink-uri": "mysql://root:******@127.0.0.1:3306",
    "state": "running",
    "err-msg": "",
    "checkpoint": "{\n  \"source_db.orders\": 2025-03-28 15:00:35.620173 +0800 CST,\n}",
    "timestamp": "2025-03-28 15:00:36.207296 +0800 CST"
  },
  {
    "task-id": "0195db82-7d6f-7f2a-a6d0-24cbe6ae8896",
    "task-name": "ms_task1",
    "source-uri": "mysql://root:******@127.0.0.1:6001",
    "sink-uri": "mysql://root:******@127.0.0.1:3306",
    "state": "running",
    "err-msg": "",
    "checkpoint": "{\n  \"db1.t1\": 2025-03-28 15:00:35.632194 +0800 CST,\n}",
    "timestamp": "2025-03-28 15:00:36.207296 +0800 CST"
  }
]


#查看特定同步任务
>./mo_cdc task show --source-uri "mysql://acc1:admin:111@127.0.0.1:6001"   --task-name "ms_task2"
[
  {
    "task-id": "0195db8c-c15a-742e-8d0d-598529ab3f1e",
    "task-name": "ms_task2",
    "source-uri": "mysql://acc1:admin:******@127.0.0.1:6001",
    "sink-uri": "mysql://root:******@127.0.0.1:3306",
    "state": "running",
    "err-msg": "",
    "checkpoint": "{\n  \"db1.t1\": 2025-03-28 15:01:44.030821 +0800 CST,\n  \"db1.table1\": 2025-03-28 15:01:43.998759 +0800 CST,\n}",
    "timestamp": "2025-03-28 15:01:44.908341 +0800 CST"
  }
]

暂停任务

语法结构

mo_cdc task pause
    --source-uri
    --all
    --task-name

参数说明

参数

说明

source-uri

源端服务器地址

all

暂停所有同步任务

task-name

同步任务名称

示例

#暂停特定任务
./mo_cdc task pause  --source-uri "mysql://acc1:admin:111@127.0.0.1:6001" --task-name "ms_task2"

#暂停所有任务
./mo_cdc task pause --source-uri "mysql://root:111@127.0.0.1:6001"  --all

恢复任务

任务只能在其状态为停止时进行恢复,恢复过程会进行断点续传。如果任务暂停的时间超过了 GC 的保留期限,则在此期间的操作将无法被同步,系统仅会同步任务最终的数据状态。

语法结构

mo_cdc task resume
    --source-uri
    --task-name

参数说明

参数

说明

source-uri

源端服务器地址

task-name

同步任务名称

示例

./mo_cdc task resume  --source-uri "mysql://acc1:admin:111@127.0.0.1:6001" --task-name "ms_task2"

重启任务

重启 cdc 任务会忽略任务之前的同步进度记录,从头重新开始同步。

语法结构

mo_cdc task restart
    --source-uri
    --task-name

参数说明

参数

说明

source-uri

源端服务器地址

task-name

同步任务名称

示例

./mo_cdc task restart  --source-uri "mysql://acc1:admin:111@127.0.0.1:6001" --task-name "ms_task2"

删除任务

语法结构

mo_cdc task drop
    --source-uri
    --all
    --task-name

参数说明

参数

说明

source-uri

源端服务器地址

all

删除所有同步任务

task-name

删除特定名称的同步任务

示例

#删除特定任务
./mo_cdc task drop  --source-uri "mysql://acc1:admin:111@127.0.0.1:6001" --task-name "ms_task2"

#删除所有任务
./mo_cdc task drop  --source-uri  "mysql://root:111@127.0.0.1:6001" --all

备注

SQL 层面的 DROP CDC 语句支持 IF EXISTS 子句。指定 IF EXISTS 后,删除不存在的 CDC 任务将静默成功而非报错。SQL 语法如下:

DROP CDC [IF EXISTS] [TASK] <task_name>

TASK 关键字为可选。例如 DROP CDC IF EXISTS my_task 与 DROP CDC IF EXISTS TASK my_task 等价。此外,SHOW CDC 不带参数时默认显示所有 CDC 任务(等同于 SHOW CDC ALL)。

同步验收与中断处理

记录 MO、mo_cdc 和下游版本,并先执行 mo_cdc task create --help 核对参数。PITR 保留窗口应覆盖最大计划停机时间、追赶时间和余量,不能把“两小时”视为所有负载的保证。

  1. 在专用测试表执行插入、更新、删除,等待 checkpoint 推进后,用下游独立连接核对主键和全部字段。行数相同不代表数据一致。

  2. 记录 checkpoint、当前时间和 err-msg;结合业务新鲜度要求监控延迟,检查下游错误和保留窗口剩余时间。

  3. resume 使用已有进度;restart 会忽略原进度。超出保留窗口后,先检查缺失范围并制定全量重建及校验方案,不直接假定 resume 能补齐历史。

  4. ignore 可能跳过写入错误;必须保留错误记录并校验、修复受影响数据。重复应用、DDL、新增表及无主键表的行为需按工具版本单独验证。

这些检查是验收方法,不构成未经测试的 exactly-once 或自动 DDL 传播承诺。