MySQL → YMatrix 迁移与校验工具

项目简介

本工具实现 MySQL 到 YMatrix（基于 PostgreSQL 协议）的全量数据迁移与三层数据一致性校验。

技术架构:

• Python 核心脚本：负责全部数据库交互、DDL 生成、数据迁移、三层校验、报告导出
• Python Streamlit 前端：基于 Streamlit 的简易可视化界面，用于配置管理、任务调度、结果展示

功能特性

1. 自动 DDL 转换：读取 MySQL 表结构，自动映射字段类型并生成 YMatrix 建表 SQL
2. 全量数据迁移：流式分页导出 MySQL → CSV → COPY 高速批量导入 YMatrix
3. 三层数据校验：
   • 行数比对
   • 全表 MD5 Checksum 哈希校验
   • 随机抽样逐字段对比
4. 自动生成报告：输出 Markdown 格式迁移报告，含校验明细与差异数据
5. 可视化演示界面：Streamlit Web 界面，实时展示迁移进度与校验结果

环境依赖

Python 环境

依赖	版本要求	说明
Python	≥ 3.8	运行环境
pymysql	≥ 1.0	MySQL 连接
psycopg2-binary	≥ 2.9	PostgreSQL/YMatrix 客户端
PyYAML	≥ 6.0	YAML 配置解析
Streamlit	≥ 1.28	Web 界面框架（可选）
Pandas	≥ 1.5	数据处理与表格展示（可选）

数据库

组件	版本要求	说明
MySQL	≥ 5.7	源数据库
YMatrix	≥ 5.0	目标数据库 (PG 协议兼容)

快速开始

方式一：演示模式（零配置，推荐先试）

无需安装任何数据库，直接运行演示模式，使用 SQLite 模拟 MySQL 和 YMatrix：

cd src/python
python demo.py

演示内容：

• 自动创建 5 张测试表（覆盖全部 6 种要求的字段类型）
• 生成 11,500 行测试数据
• 执行完整的 DDL 转换、数据迁移、三层校验
• 生成完整的迁移报告

输出文件：

• sql/*.sql — 自动生成的建表 SQL
• data/*.csv — 迁移中间数据文件
• results/migration_report.md — 完整迁移报告
• results/validation_diffs.csv — 校验差异明细
• demo/source_mysql.db — 模拟的源数据库
• demo/target_ymatrix.db — 模拟的目标数据库

---

方式二：连接真实数据库

1. 克隆项目

git clone <repo-url>
cd mysql2ymatrix

2. 安装依赖

pip install pymysql psycopg2-binary pyyaml streamlit pandas

3. 配置数据库连接

cp config.example.yaml config.yaml
# 编辑 config.yaml，填写 MySQL 和 YMatrix 连接信息

配置文件说明:

source:
  host: "127.0.0.1"
  port: 3306
  user: "root"
  password: "your_mysql_password"
  database: "test_migration"

target:
  host: "127.0.0.1"
  port: 5432
  user: "ymatrix"
  password: "your_ymatrix_password"
  database: "target_db"

4. 生成测试数据（可选）

cd data_generator
# 生成 SQL 文件（不连接 MySQL）
python generate_test_data.py --sql-only

# 或直接写入 MySQL
python generate_test_data.py --host 127.0.0.1 --user root --password mypass --database test_migration

# 自定义数据量
python generate_test_data.py --tables 3 --rows 5000 --host 127.0.0.1 --user root --password mypass --database test_migration

5. 命令行直接运行迁移

cd src/python
python migrate.py ../../config.yaml

6. 启动可视化前端（可选）

cd src/python
streamlit run app.py

浏览器自动打开 http://localhost:8501，在页面中配置并启动迁移任务。

项目结构

project/
├── README.md                  # 项目说明
├── report.md                  # 方案设计与技术报告
├── ai_usage.md                # AI 辅助开发记录
├── dev_log.md                 # 交互开发过程记录
├── config.example.yaml        # 配置模板
├── config.yaml                # 配置文件
├── src/
│   └── python/                # Python 源码
│       ├── migrate.py         # 迁移主脚本（命令行入口）
│       ├── type_mapper.py     # 字段类型映射
│       ├── ddl_generator.py   # DDL 生成与执行
│       ├── app.py             # Streamlit 主页面
│       └── file_reader.py     # 数据读取工具
├── data_generator/            # 测试数据生成脚本
│   └── generate_test_data.py  # 自动生成 5 张测试表
├── sql/                       # 自动生成的建表 SQL
├── data/                      # 迁移中间 CSV 文件
└── results/                   # 校验明细、报告、日志

支持的字段类型映射

MySQL 类型	YMatrix 类型	说明
INT / INTEGER	INTEGER	整数
BIGINT	BIGINT	长整数
VARCHAR(n)	VARCHAR(n)	变长字符串
CHAR(n)	VARCHAR(n)	定长字符串
TEXT / TINYTEXT / MEDIUMTEXT / LONGTEXT	TEXT	长文本
DATETIME	TIMESTAMP	日期时间
TIMESTAMP	TIMESTAMP	日期时间
DECIMAL(p,s)	NUMERIC(p,s)	精确数值
DATE	DATE	日期
DOUBLE / FLOAT	DOUBLE PRECISION	浮点数
BOOLEAN	BOOLEAN	布尔值
JSON	JSONB	JSON 数据

运行示例

命令行输出示例

╔══════════════════════════════════════════════╗
║   MySQL → YMatrix  迁移与校验工具  v1.0.0   ║
╚══════════════════════════════════════════════╝

[Main] Loading config: ../../config.yaml
[MySQL] Connected to 127.0.0.1:3306/test_migration
[YMatrix] Connected to 127.0.0.1:5432/target_db
[Main] Found 5 tables in source DB
[Main] Tables to migrate: 5
  - test_users
  - test_products
  - test_orders
  - test_logs
  - test_metrics

[Main] ====== Phase 1: DDL Generation ======
[DDL] Processing table: test_users
[DDL] Processing table: test_products
[DDL] Processing table: test_orders
[DDL] Processing table: test_logs
[DDL] Processing table: test_metrics
[DDL] Saved: sql/test_users.sql
[DDL] Saved: sql/test_products.sql
[DDL] Saved: sql/test_orders.sql
[DDL] Saved: sql/test_logs.sql
[DDL] Saved: sql/test_metrics.sql
[DDL] Executed: test_users
[DDL] Executed: test_products
[DDL] Executed: test_orders
[DDL] Executed: test_logs
[DDL] Executed: test_metrics

[Main] ====== Phase 2: Data Migration ======
[Migrate] test_users: source row count = 1000
[Migrate] Exporting test_users to data/test_users.csv...
[Migrate] test_users: exported 1000 rows in 0.12s
[Migrate] Importing test_users to YMatrix...
[Migrate] test_users: imported 1000 rows in 0.05s
[Migrate] test_users: SUCCESS
...

[Main] ====== Phase 3: Data Validation ======

[Validate] ====== Validating: test_users ======
[Validate] Layer 1: Row count check...
[Validate]   MySQL=1000  YMatrix=1000  MATCH
[Validate] Layer 2: Checksum check...
[Validate]   MySQL_Checksum=abc123...  YMatrix_Checksum=abc123...  MATCH
[Validate] Layer 3: Sampling check (100 rows)...
[Validate]   Sampled 100 rows, 0 field differences
[Validate] test_users => ALL PASSED
...

[Main] ====== Phase 4: Report Generation ======
[Report] Migration report written: results/migration_report.md

============================================
  Migration Summary
============================================
  Source DB:      test_migration
  Target DB:      target_db
  Total tables:   5
  Success:        5
  Failed:         0
  Duration:       15.23s
============================================
[Main] All tables migrated and validated successfully!

输出文件说明

results/migration_report.md

完整的迁移报告，包含：

• 迁移状态总览表
• DDL 转换结果
• 数据迁移结果（行数、耗时）
• 三层校验结果（行数、Checksum、抽样）
• 不一致数据样例
• 类型映射风险说明
• 增量迁移建议

results/validation_diffs.csv

校验差异明细，包含所有不一致的数据行和字段。

sql/*.sql

自动生成的 YMatrix 建表 SQL 文件。

data/*.csv

迁移过程中的中间数据文件。

已知限制

1. 仅支持全量迁移：当前版本不支持增量迁移
2. AUTO_INCREMENT 处理：MySQL AUTO_INCREMENT 在 YMatrix 中映射为普通 INTEGER，需手动调整为 SERIAL
3. UNSIGNED 修饰符：MySQL 的 UNSIGNED 修饰符在 PostgreSQL 中无直接等价，会丢失此约束
4. ENUM/SET 类型：不支持 MySQL ENUM 和 SET 类型的自动映射
5. BLOB 类型：不支持二进制大对象类型的迁移

许可证

MIT License