准备连接、样例数据和验收基线

适用范围

这些教程来自实际生态验证,参考 MatrixOne 构建 652c643666428f1c434e03369834f2a9bead7c27,并使用 MySQL 8.4.11 做适用语义的对照。部署版本、驱动版本、读取方向和写入方向都要单独记录;MySQL 协议可连接,不代表 MySQL binlog、所有生成 SQL 或所有类型推断可用。

教程中的代码是从验证路径整理的最小示例,并非把每一份新教程配置都重新部署过一遍。各工具页说明实际验证边界。临时内存文件系统上的功能验证不代表磁盘吞吐、长稳、调度高可用或跨系统 exactly-once 认证。

环境与连接

先安装并启动 MatrixOne。由管理员创建专用测试库 doc_lake、生态用户并授权;下面的建库语句需要建库权限。客户端使用端口 6001。不要直接使用已有业务库;完成验证前保留输入文件、运行日志和目标数据。

在新的工作目录保存样例,使用独立 Python 虚拟环境。把密码通过环境变量或密钥管理器注入。下例的空密码占位符必须替换为实际秘密,不要提交到仓库。远程连接按 TLS 文档 配置 CA;不设置 MO_SSL_CA 的方式仅用于本机隔离实验。

python -m venv .venv
. .venv/bin/activate
python -m pip install pymysql sqlalchemy
export MO_HOST=127.0.0.1
export MO_PORT=6001
export MO_DATABASE=doc_lake
export MO_USER=ecosystem_user
export MO_PASSWORD=''
# export MO_SSL_CA=/path/to/ca.pem
mysql -h "$MO_HOST" -P "$MO_PORT" -u "$MO_USER" -p

建立精确类型样例

保存为 fixtures.sql,在有权限的 MySQL 客户端执行 source fixtures.sql。预期两行:第一行 ID 超过浮点数的连续整数精度范围,第二行刻意区分 SQL NULL、空字节与空字符串。amount 必须保留全部 18 位小数;二进制第一行的十六进制为 00FF80。先确认结果,再运行各工具。此初始化会把这两个样例键恢复为给定值,其他行不会被清空。

CREATE DATABASE IF NOT EXISTS doc_lake;
USE doc_lake;
CREATE TABLE IF NOT EXISTS lake_demo (
    id BIGINT PRIMARY KEY,
    amount DECIMAL(38,18),
    payload VARBINARY(256),
    label VARCHAR(256),
    rev BIGINT
);
INSERT INTO lake_demo VALUES
    (9007199254740993, 12345678901234567890.123456789012345678, UNHEX('00FF80'), '中文😀', 0),
    (2, NULL, UNHEX(''), '', 0)
ON DUPLICATE KEY UPDATE amount=VALUES(amount), payload=VALUES(payload), label=VALUES(label), rev=VALUES(rev);
SELECT id, CAST(amount AS CHAR), HEX(payload), label, rev FROM lake_demo ORDER BY id;

保存共用连接模块

保存下面的完整代码为 mo_common.py。后续脚本与它放在同一目录。engine() 使用结构化 URL,避免密码包含特殊字符时被错误解析;连接池有明确上限。事务失败需回滚,脚本结束关闭连接或释放连接池。

import os
from decimal import getcontext
import pymysql
import sqlalchemy as sa

getcontext().prec = 80

def options():
    return dict(host=os.environ["MO_HOST"], port=int(os.environ["MO_PORT"]),
                user=os.environ["MO_USER"], password=os.environ["MO_PASSWORD"],
                database=os.environ["MO_DATABASE"], charset="utf8mb4",
                connect_timeout=10, read_timeout=45, write_timeout=45)

def connect():
    kw = options()
    if os.environ.get("MO_SSL_CA"):
        kw["ssl"] = {"ca": os.environ["MO_SSL_CA"]}
        kw["ssl_verify_cert"] = True
        kw["ssl_verify_identity"] = True
    return pymysql.connect(**kw, autocommit=False)

def engine():
    kw = options()
    url = sa.URL.create("mysql+pymysql", username=kw["user"], password=kw["password"],
                        host=kw["host"], port=kw["port"], database=kw["database"])
    args = dict(charset="utf8mb4", connect_timeout=10, read_timeout=45, write_timeout=45)
    if os.environ.get("MO_SSL_CA"):
        args.update(ssl={"ca": os.environ["MO_SSL_CA"]},
                    ssl_verify_cert=True, ssl_verify_identity=True)
    return sa.create_engine(url, pool_size=2, max_overflow=0,
                            pool_pre_ping=True, connect_args=args)

验收与排障

保存 SQL 源值、工具内存类型、文件类型、目标新连接回读值以及重复键检查;不要只看行数或任务退出码。精确小数不得转为 float,二进制比较字节,负 TIME 用带符号微秒数或明确的 SQL 时间字符串,DATETIME 使用微秒精度并记录时区语义。JSON 文本 null 与 SQL NULL、空字符串与 NULL 必须分别验收。

重试前确认上一批是否提交。连接异常后原连接的事务状态可能未知,应丢弃连接并通过业务键、事件 ID 或批次凭证查询已提交效果。追加写不能直接重放;删除传播需要带键的删除事件。新增字段、改名、缩窄和非空约束分别做迁移验证。吞吐报告要给出硬件、存储、数据集、实际运行时长、批大小、连接数、失败时间线以及校验结果。

历史生态问题与证据入口:matrixone#29848。问题关闭后,仍需核实修复提交、进入哪个发布版本、在本部署的复测结果。