数据迁移兼容性 Cookbook¶
本文是一份面向 MySQL 和 MatrixOne 双向兼容场景的迁移前检查清单,补充本目录中按数据源划分的迁移指南。本文的要求比“SQL 能否解析”更严格:某个 MatrixOne 版本能够接受某条 SQL,并不代表不同数据库、驱动、版本以及备份恢复工具之间的语义和运维行为完全一致。
适用范围与验证版本¶
本文的验证示例于 2026-10-28 在 MatrixOne v4.2.6 上执行。实际迁移时必须在目标 MatrixOne 的准确版本上重新执行检查。单条探测 SQL 成功,不代表所有函数、驱动和备份流程都具备跨引擎可移植性。
迁移兼容性限制¶
范围 |
迁移规则 |
推荐方式 |
|---|---|---|
存储过程和触发器 |
不要把应用行为放入存储过程或触发器。 |
将业务逻辑和完整性处理放在应用或迁移工具中。 |
表级锁 |
不使用 |
使用事务和应用层协调。 |
级联外键 |
不依赖 |
在应用层显式删除或更新关联行,并检查影响行数。 |
字符集 |
只使用 |
显式设置连接、数据库、表和客户端配置。 |
Upsert |
不依赖 |
在事务中先查后写,配合唯一键和重试处理。 |
布尔值 |
不依赖驱动对 |
显式写入和读取 |
标识符 |
不使用中文数据库名或表名。 |
数据库、表、列、索引和约束统一使用 ASCII |
自增列 |
不把自定义 |
让 MatrixOne 分配新 ID;需要稳定 ID 时显式导入,并保留独立业务键。 |
逻辑备份 |
不对 MatrixOne 使用 |
使用 |
窗口函数和 JSON 函数 |
不要仅凭函数名称假设 MySQL 兼容。 |
发布前在目标 MatrixOne 版本上执行完全相同的 SQL 和结果校验。 |
事件和存储函数 |
不要把 MySQL |
只有在审查不同语法和生命周期规则后,才使用 MatrixOne SQL Task 或 SQL/Python 函数。 |
JSON 覆盖范围 |
不要假设完整的 MySQL JSON 能力都可用; |
逐个测试生产 JSON 表达式,并同时比较结果和报错。 |
空间能力 |
不要把解析器接受的 MySQL 空间类型或 GIS 函数当作可用支持。 |
替换这些能力,或在目标版本上通过实际查询测试。 |
索引 |
可移植 Schema 不使用函数索引或表达式索引。 |
DDL 转换后单独审查每个索引定义。 |
批量文件格式 |
不使用 |
使用文档规定的 CSV 或 JSONL |
生成 ID 和结果元数据 |
不假设 MySQL 的自增步长或多行 |
必须保留源端 ID 时显式导入,并在应用中测试生成 ID 的处理。 |
外键动作 |
不使用 |
显式处理关联行,并纳入迁移测试。 |
窗口 frame |
不依赖有序 |
需要 MySQL 兼容结果时显式指定窗口 frame。 |
备份工具 |
不使用 |
逻辑备份使用 |
系统变量 |
不把 |
在 MatrixOne 上验证实际行为。 |
重要: 上表描述的是迁移契约。v4.2.6 探测中,表锁、级联外键、两种常见 Upsert、中文标识符和自定义自增起点仍然可以被接受。它们仍然被禁止,是因为接受语法不等于不同引擎、驱动、版本以及备份恢复工具具有相同的行为。
迁移前还需要核对的语义差异¶
上表解决的是可移植性规则;下面的项目解决的是“语句可以执行,但迁移结果或运行行为仍可能不同”的问题:
标识符大小写: MatrixOne 是否区分库名、表名和列名受
lower_case_table_names影响。迁移前检查源端配置,并处理仅大小写不同的对象;即使目标端能够接受中文标识符,也应继续使用 ASCII 标识符,避免备份、监控和跨平台工具链出现不一致。字符集和排序规则:
latin1、gbk等源数据必须按真实编码转换为utf8mb4,不能只替换 DDL 中的CHARSET。同名COLLATE也不保证大小写、重音和尾随空格的比较语义完全一致;必须针对 JOIN、排序、分组、去重和唯一约束中的关键字段比较实际结果。类型和值映射: 对
DECIMAL、BIGINT UNSIGNED、UUID 和布尔值分别检查驱动及应用语言的序列化精度。不要假定 MySQLUUID()的版本、字符串格式或 ORM 映射与 MatrixOne 相同;业务状态字段不要用布尔类型代替多值整数状态。日期时间和
sql_mode: 明确0000-00-00、非法日期、隐式转换、小数秒以及连接时区的处理策略,分别核对TIMESTAMP的时区转换和DATETIME的值语义。历史零日期不能未经业务确认就静默替换。自增和结果元数据:
REPLACE即使可执行,也可能删除后重新插入,改变未提供列、自增值、关联关系和审计列。导入源端 ID 后,验证后续生成 ID、lastrowid、generated keys 和LAST_INSERT_ID()的行为;不要把自增值当作连续序列或提交顺序。存储过程、函数和触发器: 存储过程或函数即使在目标版本有部分支持,也不能直接假定 MySQL 的定义语法、参数、控制流、返回值和生命周期兼容;触发器逻辑必须迁出,并覆盖批量导入、后台任务和数据修复等全部写入入口。
并发和重试: 不能把 MySQL 的表锁或事务隔离假设直接带到 MatrixOne。冲突重试必须重试完整事务;提交超时不能直接判定为失败,应使用业务幂等键确认提交结果,避免重复写入、扣款或发消息。
保存点和 DDL: 依赖
SAVEPOINT、ROLLBACK TO SAVEPOINT的 ORM 嵌套事务和批处理需要在目标版本验证;DDL 的隐式提交和回滚规则也要单独确认,迁移脚本失败后必须检查对象和数据的实际状态。查询语义和分页: 窗口函数、JSON 函数、CTE 以及 NULL 处理、返回类型和边界行为都要用生产 SQL 验证。没有明确
ORDER BY的查询不能依赖返回顺序;分页排序值不唯一时增加唯一键,避免重复或遗漏,并重新评估真实数据规模下的执行计划。驱动、ORM、CDC 和备份工具: MySQL 协议可连接不代表预编译、批量写入、自动 DDL、受影响行数、错误码、系统库、账号授权、binlog/GTID/复制和 CDC 工具完全兼容。备份必须检查退出码并实际恢复;恢复后核对结构、行数、主键、关联关系、业务汇总,以及中文、二进制、NULL、精度和时间值,大表按主键范围分批校验。
切换和回退: MatrixOne 开始接收新写入后,旧 MySQL 不再包含完整最新数据。切换前明确停写窗口、增量追平和回退策略;回退时处理目标端新增或变更的数据,避免数据丢失、重复或两库分叉。
第一步:盘点源端 Schema¶
导出数据前,应同时扫描 DDL、迁移文件、存储例程、触发器、ORM 模型和应用 SQL,查找以下模式:
CREATE PROCEDURE CREATE FUNCTION CREATE TRIGGER
LOCK TABLES UNLOCK TABLES ON DELETE CASCADE
ON UPDATE CASCADE ON DUPLICATE KEY REPLACE INTO
AUTO_INCREMENT = mysqldump 非 utf8mb4 字符集
中文数据库名或表名
这既是源码扫描,也是数据库元数据扫描。只检查导出的 SQL 不够,因为导出工具可能遗漏或转换对象。
第二步:规范化 Schema¶
使用 ASCII 标识符,并显式指定字符集:
CREATE DATABASE app_data
CHARACTER SET utf8mb4
COLLATE utf8mb4_bin;
CREATE TABLE app_data.customer (
customer_id BIGINT PRIMARY KEY,
display_name VARCHAR(200) NOT NULL,
enabled BOOLEAN NOT NULL DEFAULT TRUE
) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
迁移记录时,如果源端 ID 参与业务关联,优先显式保留稳定 ID。新记录的 ID 不要依赖自定义起点,让目标端分配:
CREATE TABLE app_data.import_log (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
source_key VARCHAR(128) NOT NULL,
UNIQUE KEY uk_import_log_source_key (source_key)
);
不要把 AUTO_INCREMENT=10000 或其他自定义起点作为可移植性要求。如果必须保留源端序列,应先显式导入 ID,校验冲突后再启用自动生成 ID。
第三步:替换不可移植行为¶
级联和触发器¶
不要依赖触发器或级联,而要显式控制操作顺序:
START TRANSACTION;
DELETE FROM app_data.order_item WHERE order_id = ?;
DELETE FROM app_data.orders WHERE order_id = ?;
COMMIT;
应用应检查影响行数;驱动报告临时冲突时重试事务。这样离线迁移脚本也能清楚表达实际行为。
Upsert¶
可移植迁移代码不要使用以下两种写法:
INSERT INTO app_data.customer ... ON DUPLICATE KEY UPDATE ...;
REPLACE INTO app_data.customer ...;
使用应用层显式决策的事务流程:
1. 根据唯一业务键查询。
2. 已存在则 UPDATE,否则 INSERT。
3. 检查影响行数;遇到并发插入导致的重复键时重试。
REPLACE 尤其需要避免,因为它的删除再插入语义可能改变外键关系、自增值和审计列。
布尔值¶
在应用边界显式转换:
INSERT INTO app_data.customer (customer_id, display_name, enabled)
VALUES (?, ?, 1);
SELECT customer_id,
CASE WHEN enabled = 1 THEN TRUE ELSE FALSE END AS enabled
FROM app_data.customer;
不要假设语言驱动对 MySQL 的 BOOLEAN 列和 MatrixOne 的布尔列采用完全相同的绑定方式。
不要在没有显式归一化的情况下把布尔列直接作为数值聚合输入。在 MatrixOne 探针中,
对 BOOLEAN 列执行 SUM(flag) 返回了
invalid argument aggregate function sum, bad value [BOOL];可移植的写法是显式使用条件表达式,
例如 SUM(CASE WHEN flag = 1 THEN 1 ELSE 0 END)。将分析查询上线前,应使用目标版本和实际驱动验证等价表达式。
第四步:导出和导入数据¶
需要区分两类工具:
源端 MySQL 导出: 可以使用源端工具产生待导入数据,但导入前必须清理不支持的 DDL 和应用行为。
MatrixOne 备份或 MatrixOne 到 MatrixOne 的迁移: 使用
mo-dump导出逻辑 SQL/CSV。不要对 MatrixOne 执行mysqldump,因为它依赖 MatrixOne 不提供的 MySQL 系统表行为。物理备份和恢复请遵循mobackup文档。
大批量 CSV 导入时,应先创建并检查目标 Schema,再使用 LOAD DATA。导入 SQL 文件时,只有在检查文件不包含盘点清单中的模式后,才使用 SOURCE。
第五步:校验迁移结果¶
建议分三个层级执行校验:
-- 每张迁移表的行数。
SELECT COUNT(*) FROM app_data.customer;
-- 业务键的空值、重复值和唯一性检查。
SELECT customer_id, COUNT(*)
FROM app_data.customer
GROUP BY customer_id
HAVING COUNT(*) > 1;
-- 与源端约定的确定性样本或校验和。
SELECT customer_id, display_name, enabled
FROM app_data.customer
ORDER BY customer_id
LIMIT 100;
然后执行代表性的应用查询,包括生产环境使用的所有窗口函数和 JSON 函数。要同时对比结果值和报错行为;能够解析的 SQL 仍可能返回不同结果。
MatrixOne 最小兼容性探测¶
在目标版本的临时数据库中执行以下探测。标注为“策略失败”的项目,即使服务器接受,也应在迁移审查中判定为不通过。
SELECT VERSION();
SHOW VARIABLES LIKE 'character_set_server';
SHOW VARIABLES LIKE 'collation_server';
CREATE DATABASE migration_probe CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
-- 即使目标版本接受,也必须作为策略失败处理。
CREATE TABLE migration_probe.parent_t (id INT PRIMARY KEY);
CREATE TABLE migration_probe.child_t (
id INT PRIMARY KEY,
parent_id INT,
FOREIGN KEY (parent_id) REFERENCES migration_probe.parent_t(id)
ON DELETE CASCADE
);
-- 在目标版本上执行生产环境实际使用的窗口函数和 JSON 表达式。
SELECT ROW_NUMBER() OVER (ORDER BY 1) AS row_number_probe;
SELECT JSON_EXTRACT('{"a": 1}', '$.a') AS json_probe;
DROP DATABASE migration_probe;
v4.2.6 探测记录¶
以下结果来自 MatrixOne 8.0.30-MatrixOne-v4.2.6:
探测项 |
结果 |
解释 |
|---|---|---|
服务端字符集/排序规则 |
|
符合迁移契约。 |
存储过程和触发器最小探测 |
SQL parser 拒绝 |
可移植应用行为中都不要使用。 |
|
接受 |
策略失败;迁移代码不要使用。 |
|
接受并删除了子行 |
策略失败;显式处理关联行。 |
|
接受 |
策略失败;使用应用层显式流程。 |
中文数据库名/表名 |
接受 |
策略失败;使用 ASCII 标识符。 |
|
接受并生成 |
策略失败;不要依赖自定义起点。 |
布尔值读写 |
以 |
显式绑定和统一转换。 |
|
最小探测通过 |
仍需测试生产环境实际使用的函数和结果集。 |
该记录与版本绑定;升级兼容性基线后应重新执行并更新。