数据迁移兼容性 Cookbook

本文是一份面向 MySQL 和 MatrixOne 双向兼容场景的迁移前检查清单,补充本目录中按数据源划分的迁移指南。本文的要求比“SQL 能否解析”更严格:某个 MatrixOne 版本能够接受某条 SQL,并不代表不同数据库、驱动、版本以及备份恢复工具之间的语义和运维行为完全一致。

适用范围与验证版本

本文的验证示例于 2026-10-28 在 MatrixOne v4.2.6 上执行。实际迁移时必须在目标 MatrixOne 的准确版本上重新执行检查。单条探测 SQL 成功,不代表所有函数、驱动和备份流程都具备跨引擎可移植性。

迁移兼容性限制

范围

迁移规则

推荐方式

存储过程和触发器

不要把应用行为放入存储过程或触发器。

将业务逻辑和完整性处理放在应用或迁移工具中。

表级锁

不使用 LOCK TABLES 或 UNLOCK TABLES。

使用事务和应用层协调。

级联外键

不依赖 ON DELETE CASCADE 或 ON UPDATE CASCADE。

在应用层显式删除或更新关联行,并检查影响行数。

字符集

只使用 utf8mb4;除非有明确的排序需求,否则使用 utf8mb4_bin。

显式设置连接、数据库、表和客户端配置。

Upsert

不依赖 ON DUPLICATE KEY UPDATE 或 REPLACE。

在事务中先查后写,配合唯一键和重试处理。

布尔值

不依赖驱动对 BOOLEAN 的绑定差异。

显式写入和读取 0/1,或在应用边界统一转换。

标识符

不使用中文数据库名或表名。

数据库、表、列、索引和约束统一使用 ASCII snake_case。

自增列

不把自定义 AUTO_INCREMENT 起始值写入迁移契约。

让 MatrixOne 分配新 ID;需要稳定 ID 时显式导入,并保留独立业务键。

逻辑备份

不对 MatrixOne 使用 mysqldump。

使用 mo-dump;物理备份使用文档规定的 mobackup 流程。

窗口函数和 JSON 函数

不要仅凭函数名称假设 MySQL 兼容。

发布前在目标 MatrixOne 版本上执行完全相同的 SQL 和结果校验。

事件和存储函数

不要把 MySQL EVENT、event_scheduler 或 MySQL 风格的复合存储函数体当作可移植能力迁移。

只有在审查不同语法和生命周期规则后,才使用 MatrixOne SQL Task 或 SQL/Python 函数。

JSON 覆盖范围

不要假设完整的 MySQL JSON 能力都可用;JSON_SEARCH、JSON_TABLE、JSON_ARRAYAGG 和 JSON_OBJECTAGG 需要单独审查。

逐个测试生产 JSON 表达式,并同时比较结果和报错。

空间能力

不要把解析器接受的 MySQL 空间类型或 GIS 函数当作可用支持。

替换这些能力,或在目标版本上通过实际查询测试。

索引

可移植 Schema 不使用函数索引或表达式索引。

DDL 转换后单独审查每个索引定义。

批量文件格式

不使用 LOAD XML。

使用文档规定的 CSV 或 JSONL LOAD DATA 语法,并测试 MatrixOne 特有选项。

生成 ID 和结果元数据

不假设 MySQL 的自增步长或多行 LAST_INSERT_ID() 行为。

必须保留源端 ID 时显式导入,并在应用中测试生成 ID 的处理。

外键动作

不使用 SET DEFAULT 外键动作。

显式处理关联行,并纳入迁移测试。

窗口 frame

不依赖有序 LAST_VALUE 或 NTH_VALUE 的 MySQL 隐式 frame。

需要 MySQL 兼容结果时显式指定窗口 frame。

备份工具

不使用 xtrabackup 或 mariabackup 处理 MatrixOne。

逻辑备份使用 mo-dump,物理恢复使用 MatrixOne 文档规定的物理备份工具。

系统变量

不把 SET 成功当作 MySQL 系统变量已具有相同效果。

在 MatrixOne 上验证实际行为。

重要: 上表描述的是迁移契约。v4.2.6 探测中,表锁、级联外键、两种常见 Upsert、中文标识符和自定义自增起点仍然可以被接受。它们仍然被禁止,是因为接受语法不等于不同引擎、驱动、版本以及备份恢复工具具有相同的行为。

迁移前还需要核对的语义差异

上表解决的是可移植性规则;下面的项目解决的是“语句可以执行,但迁移结果或运行行为仍可能不同”的问题:

  • 标识符大小写: MatrixOne 是否区分库名、表名和列名受 lower_case_table_names 影响。迁移前检查源端配置,并处理仅大小写不同的对象;即使目标端能够接受中文标识符,也应继续使用 ASCII 标识符,避免备份、监控和跨平台工具链出现不一致。

  • 字符集和排序规则: latin1、gbk 等源数据必须按真实编码转换为 utf8mb4,不能只替换 DDL 中的 CHARSET。同名 COLLATE 也不保证大小写、重音和尾随空格的比较语义完全一致;必须针对 JOIN、排序、分组、去重和唯一约束中的关键字段比较实际结果。

  • 类型和值映射: 对 DECIMAL、BIGINT UNSIGNED、UUID 和布尔值分别检查驱动及应用语言的序列化精度。不要假定 MySQL UUID() 的版本、字符串格式或 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)。将分析查询上线前,应使用目标版本和实际驱动验证等价表达式。

第四步:导出和导入数据

需要区分两类工具:

  1. 源端 MySQL 导出: 可以使用源端工具产生待导入数据,但导入前必须清理不支持的 DDL 和应用行为。

  2. 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:

探测项

结果

解释

服务端字符集/排序规则

utf8mb4 / utf8mb4_bin

符合迁移契约。

存储过程和触发器最小探测

SQL parser 拒绝

可移植应用行为中都不要使用。

LOCK TABLES / UNLOCK TABLES

接受

策略失败;迁移代码不要使用。

ON DELETE CASCADE

接受并删除了子行

策略失败;显式处理关联行。

ON DUPLICATE KEY UPDATE / REPLACE

接受

策略失败;使用应用层显式流程。

中文数据库名/表名

接受

策略失败;使用 ASCII 标识符。

AUTO_INCREMENT=10000

接受并生成 10000

策略失败;不要依赖自定义起点。

布尔值读写

以 1 和 0 读写成功

显式绑定和统一转换。

ROW_NUMBER() 和 JSON_EXTRACT()

最小探测通过

仍需测试生产环境实际使用的函数和结果集。

该记录与版本绑定;升级兼容性基线后应重新执行并更新。

相关文档