mo_cdc Data Synchronization¶
Migration direction: this mo_cdc reads from MatrixOne and writes to MySQL/MatrixOne. The mysql:// URI identifies the protocol, not an inbound MySQL-to-MO log connector. See migration workflow for full/incremental boundaries, retention, and cutover.
CDC (Change Data Capture) is a technology that captures real-time changes in a database, recording insert, update, and delete operations. By monitoring database changes, it enables real-time data synchronization and incremental processing, ensuring consistency across different systems. CDC is suitable for scenarios such as real-time data synchronization, data migration, disaster recovery, and audit tracking. It reads transaction logs to reduce the pressure of full data replication and improves system performance and efficiency. Its advantages include low latency, high real-time capability, flexible support for multiple databases and systems, and adaptability to evolving large-scale data environments.
Before performing CDC synchronization, it is necessary to first establish PITR (Point-in-Time Recovery) capabilities covering the synchronization scope, with a recommended coverage of at least 2 hours of changes. This ensures that if the synchronization task is interrupted or encounters an exception, the system can backtrack and re-read the changed data, avoiding data loss or inconsistency.
MatrixOne supports data synchronization at the tenant/database/table level through the mo_cdc utility. This section introduces the usage of mo_cdc.
Note
The CDC engine runs inside MatrixOne. mo_cdc is the command-line management interface for CDC tasks.
Install and Start MatrixOne for CDC¶
The CDC engine is built into the MatrixOne server. There is no separate CDC server to install or start. Install and start MatrixOne using the normal deployment method for the environment, then verify that a SQL client can reach its endpoint. For example, a local Docker instance can be started with:
docker run -d -p 6001:6001 --name matrixone matrixorigin/matrixone:latest
mysql -h127.0.0.1 -P6001 -uroot -p111 -e "SELECT VERSION()"
The mo_cdc commands in this page are the command-line management interface for
CDC tasks running inside MatrixOne; they do not start a second database service.
Run ./mo_cdc help or mo_cdc help in the environment where the management
utility is available. A successful help output verifies the client entry point,
while a successful SELECT VERSION() verifies the MatrixOne server connection.
Neither check creates a CDC task. Before creating one, create a PITR covering the
synchronization scope and then use the task commands below.
The documented direction is MatrixOne as the source and MySQL as the sink. The
task syntax also includes MatrixOne as a sink for MatrixOne-to-MatrixOne
synchronization. mo_cdc is not a MySQL-to-MatrixOne binlog connector.
Command Reference Guide¶
help - Print the reference guide.
(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.
Create a Task¶
Syntax¶
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
Parameter Description
Parameter |
Description |
|---|---|
|
Synchronization task name |
|
Source (MatrixOne) connection string |
|
Downstream type, currently supports |
|
Sink connection URI matching sink-type, including address and authentication. |
|
Synchronization scope: |
|
Optional, required when the scope is database-level |
|
Optional, required when the scope is table-level |
|
Optional, enables full synchronization by default; adding this parameter disables it |
|
Optional, starts pulling data from a specific timestamp in the database (must be earlier than the current time) |
|
Optional, stops pulling data at a specified timestamp (must be later than |
|
SQL-send timeout; check installed |
|
Optional, limits the length of a single SQL statement (defaults to the smaller of 4MB or the downstream |
|
Optional, specifies objects to exclude (supports regex) |
|
Optional, |
Examples¶
>./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"
View Tasks¶
Only tasks created by the current connected user can be viewed.
Syntax¶
mo_cdc task show
--source-uri
--all
--task-name
Parameter Description
Parameter |
Description |
|---|---|
|
Source server address |
|
View all synchronization tasks |
|
Synchronization task name |
Response Fields
Field |
Description |
|---|---|
|
Task ID |
|
Task name |
|
Source server address |
|
Downstream resource identifier |
|
Task status ( |
|
Synchronization progress |
|
Current timestamp |
Examples¶
# View all synchronization tasks
> ./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"
}
]
# View a specific task
>./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"
}
]
Pause a Task¶
Syntax¶
mo_cdc task pause
--source-uri
--all
--task-name
Parameter Description
Parameter |
Description |
|---|---|
|
Source server address |
|
Pause all synchronization tasks |
|
Synchronization task name |
Examples¶
# Pause a specific task
./mo_cdc task pause --source-uri "mysql://acc1:admin:111@127.0.0.1:6001" --task-name "ms_task2"
# Pause all tasks
./mo_cdc task pause --source-uri "mysql://root:111@127.0.0.1:6001" --all
Resume a Task¶
A task can only be resumed if its status is stopped. The resumption process supports checkpoint recovery. If the pause duration exceeds the GC retention period, operations during that time will not be synchronized, and only the final data state will be synced.
Syntax¶
mo_cdc task resume
--source-uri
--task-name
Parameter Description
Parameter |
Description |
|---|---|
|
Source server address |
|
Synchronization task name |
Examples¶
./mo_cdc task resume --source-uri "mysql://acc1:admin:111@127.0.0.1:6001" --task-name "ms_task2"
Restart a Task¶
Restarting a CDC task ignores previous synchronization progress and starts from the beginning.
Syntax¶
mo_cdc task restart
--source-uri
--task-name
Parameter Description
Parameter |
Description |
|---|---|
|
Source server address |
|
Synchronization task name |
Examples¶
./mo_cdc task restart --source-uri "mysql://acc1:admin:111@127.0.0.1:6001" --task-name "ms_task2"
Delete a Task¶
Syntax¶
mo_cdc task drop
--source-uri
--all
--task-name
Parameter Description
Parameter |
Description |
|---|---|
|
Source server address |
|
Delete all synchronization tasks |
|
Delete a specific task |
Examples¶
# Delete a specific task
./mo_cdc task drop --source-uri "mysql://acc1:admin:111@127.0.0.1:6001" --task-name "ms_task2"
# Delete all tasks
./mo_cdc task drop --source-uri "mysql://root:111@127.0.0.1:6001" --all
Note
The SQL-level DROP CDC statement supports the IF EXISTS clause. When IF EXISTS is specified, dropping a non-existent CDC task succeeds silently instead of raising an error. The SQL syntax is:
DROP CDC [IF EXISTS] [TASK] <task_name>
The TASK keyword is optional. For example, DROP CDC IF EXISTS my_task and DROP CDC IF EXISTS TASK my_task are equivalent. SHOW CDC without arguments now defaults to showing all CDC tasks (same as SHOW CDC ALL).
Acceptance and interrupted tasks¶
Record the MO, mo_cdc and sink versions; check mo_cdc task create --help before using flags. Size PITR retention for maximum downtime, catch-up time and a margin. Two hours is not a guarantee for every workload.
Insert, update and delete rows in a dedicated test table. After checkpoint progress, compare keys and every field using an independent sink connection. Equal row counts do not prove equality.
Record checkpoint, current time and err-msg. Monitor lag against business freshness requirements, sink errors and the remaining retention window.
resumeuses existing progress;restartdiscards it. After retention expires, identify the missing range and plan full rebuild and validation rather than assuming resume recovers all history.ignorecan skip write errors. Preserve errors and reconcile affected rows. Validate repeated application, DDL, new tables and tables without primary keys for the exact tool version.
These are acceptance checks, not an untested exactly-once or automatic DDL propagation guarantee.