异构数据库迁移全过程-FGO2ODB工具

FGO2ODB（全称：FGEDU Overseas to Overseas DataBase Migration）是一款专为国外数据库之间数据迁移而设计的高性能统一迁移平台。该平台提供命令行（CLI）和可视化（Web 控制台）两种操作模式，支持 Oracle、MySQL、Percona、MariaDB、PostgreSQL、IBM DB2、Microsoft SQL Server、Redis、MongoDB 等主流国外数据库之间的双向互通迁移。

一、程序介绍

1.1 项目概述

FGO2ODB（全称：FGEDU Overseas to Overseas DataBase Migration）是一款专为国外数据库之间数据迁移而设计的高性能统一迁移平台。该平台提供命令行（CLI）和可视化（Web 控制台）两种操作模式，支持 Oracle、MySQL、Percona、MariaDB、PostgreSQL、IBM DB2、Microsoft SQL Server、Redis、MongoDB 等主流国外数据库之间的双向互通迁移。

本平台适用于以下典型场景：

异构数据库迁移：从 Oracle 迁移至 PostgreSQL、MySQL 迁移至 SQL Server、DB2 迁移至 Oracle 等异构数据库之间的全量迁移。
同构数据库升级/搬迁：MySQL 5.7 迁移至 MySQL 8.0、PostgreSQL 14 升级至 17、Redis 集群迁移、MongoDB 分片集群搬迁。
云上云下搬迁：本地自建数据库迁移至云数据库服务（如云上 PostgreSQL、云上 MongoDB Atlas），或反向回迁。
数据库整合：将多个异构数据库统一整合至单一目标数据库平台，降低运维复杂度。
灾备/测试数据同步：从生产环境全量抽取数据至测试环境，支持增量断点续传。

FGO2ODB 的核心设计理念是「高性能、高可靠、零数据丢失、零乱码」。通过原生 C 引擎加速类型映射与数据转义热路径、流式游标避免内存溢出、多表并行提升吞吐、断点续传保证中断恢复、全链路 UTF-8 强制编码保证字符完整性，实现了 TB 级数据的安全高效迁移。

1.2 作者信息

作者：风哥
官方网站 http://www.fgedu.net.cn
技术社区 http://www.itpux.com
数据库教程 https://edu.51cto.com/lecturer/8020378.html

1.3 项目背景

在企业 IT 架构演进过程中，数据库平台迁移是一项高频需求。传统的迁移方式通常依赖数据库厂商自带的工具（如 Oracle Data Pump、SQL Server SSIS、MySQL Workbench），这些工具存在以下痛点：

仅支持同构迁移，不支持异构数据库之间的迁移；
厂商工具之间存在壁垒，无法统一管理迁移流程；
大数据量迁移性能不足，容易因网络中断导致迁移失败后无法恢复；
类型映射不精确，容易出现精度丢失、乱码等问题；
缺乏可视化操作界面，迁移过程不透明。

FGO2ODB 正是为解决上述痛点而生。它统一了 9 种国外数据库的迁移接口，提供了精确的类型映射矩阵、函数映射规则、流式数据管道、断点续传机制和可视化控制台，让数据库迁移变得可控、可观测、可恢复。

二、功能特性

2.1 核心功能

FGO2ODB 提供完整的数据库迁移全流程覆盖，包括但不限于以下功能模块：

功能模块	说明
表结构 DDL 迁移	自动将源端表结构（列类型、主键、默认值、非空约束、注释）转换为目标端兼容的 DDL 语句并执行建表
数据迁移	流式游标读取源端数据，批量写入目标端，支持 COPY 和 executemany 双模式
索引迁移	自动转换并创建源端的所有索引（唯一索引、普通索引、主键索引）
视图迁移	自动将源端视图定义中的函数和语法重写为目标端兼容语法并创建
函数迁移	将源端自定义函数的 DDL 通过函数映射规则转换后部署至目标端
存储过程迁移	将源端存储过程转换后部署至目标端
触发器迁移	将源端触发器转换后部署至目标端
序列迁移	将源端序列（Oracle/PostgreSQL/DB2/SQL Server）的起始值迁移至目标端
数据校验	迁移完成后自动比对源端与目标端的行数一致性，并可选抽样校验和
迁移评估	迁移前评估源端数据库的表数量、行数、列数，生成评估报告
类型映射查询	提供命令行工具查看任意源类型到目标类型的映射结果
函数映射查询	提供命令行工具查看任意源函数到目标函数的映射结果
DDL 脚本导出	生成完整 DDL 脚本文件，支持人工审核后手动执行
断点续传	每表独立检查点，迁移中断后重启自动跳过已完成表、继续未完成表
可视化控制台	基于 Flask 的 Web 仪表板，支持配置编辑、连接测试、启动/暂停/停止迁移、实时进度查看

2.2 高性能特性

原生 C 引擎：核心类型映射、函数映射、COPY 行编码、行哈希校验等热路径使用 C 语言实现（libfgo2odb.so），性能远超纯 Python 实现。当 C 引擎缺失时自动回退到等价的纯 Python 实现，保证可移植性。
流式游标：源端使用 server-side cursor（MySQL SSCursor、PostgreSQL 命名游标、Oracle arraysize、MongoDB batch_size），逐批读取数据，避免 fetchall 将全表加载至内存导致 OOM。
多表并行：基于 ThreadPoolExecutor 的多表并发迁移，可配置并行度（默认 4 表并发），充分利用 I/O 并发能力。
COPY 批量导入：PostgreSQL 目标端使用 COPY FROM STDIN 流式导入，写入速度可达 executemany 的 5-10 倍；MySQL 目标端使用 executemany 批量插入；SQL Server 使用 fast_executemany 加速。
动态批大小：根据内存使用情况动态调整每批 fetch/insert 大小，在内存安全的前提下追求最大吞吐。
内存保护：按批次估算内存占用，超过软限自动降速，超过硬限强制降速，防 OOM 崩溃。

2.3 高可靠性特性

断点续传（崩溃安全）：每表独立 JSON 检查点文件，采用「临时文件 + fsync + rename」原子写入策略，保证崩溃时检查点文件不会损坏。重启后自动读取检查点，跳过已完成表、继续未完成表。
指数退避重试：单批次写入失败时自动重试（默认 3 次），退避间隔指数增长（1s、2s、4s...），重试前自动检测并重连断开的连接。
连接保活：每个连接器内置 ping() 心跳检测和 ensure_connected() 自动重连机制，长任务期间断线自动恢复。
事务安全：目标端写入采用事务模式，失败自动 rollback，保证不会写入半批脏数据。
DDL 隔离执行：DDL 执行失败不中断整体迁移流程，自动记录到「待手工修复」清单，迁移结束后统一处理。
信号优雅退出：捕获 SIGINT/SIGTERM 信号后设置全局停止标志，正在运行的批次完成当前写入后保存断点并退出，避免数据不一致。
暂停/恢复：支持全局暂停迁移（Web 控制台可操作），暂停期间已完成数据不丢失，恢复后继续。

2.4 零乱码特性

全链路 UTF-8：源端连接强制 UTF-8 编码（MySQL utf8mb4、PostgreSQL UTF8、Oracle AL32UTF8），目标端写入前设置 SET NAMES utf8mb4 或等效字符集。
二进制直传：BLOB/BINARY/VARBINARY 等二进制列以 bytes 原始传输，不做字符串转换，避免二进制数据损坏。
COPY 转义安全：COPY 模式下对 Tab、换行符等特殊字符进行安全转义，NULL 值使用标准 \N 标记。
字符集检测：迁移前自动检测源端字符集，与目标端不一致时给出警告。

2.5 可视化控制台特性

统一界面：所有 9 种数据库的源端/目标端配置在同一 Web 界面完成，动态切换连接参数表单。
在线配置编辑：直接在浏览器中编辑 YAML 配置文件，支持语法高亮。
连接测试：一键测试源端/目标端连接是否可用，返回版本信息和数据库基本信息。
迁移评估：一键评估源端数据库，返回表数量、总行数、列数统计。
实时进度：基于 SSE（Server-Sent Events）的实时进度推送，逐表显示状态（待执行/进行中/完成/失败）、已迁移行数、速率（rows/s）、预计剩余时间。
滚动日志：实时查看迁移日志，支持按级别过滤。
启动/暂停/停止：支持在 Web 界面一键启动、暂停、恢复、停止迁移任务。
HTML 报告：迁移完成后自动生成 HTML 格式的迁移报告，包含每表状态、总行数、耗时、错误清单、待手工修复项。

三、支持环境

3.1 支持的数据库

数据库	源端	目标端	支持版本
Oracle	支持	支持	9i / 10g / 11g R1/R2 / 12c R1/R2 / 18c / 19c / 21c / 23ai /26ai
MySQL	支持	支持	5.6 / 5.7 / 8.0 / 8.1-8.4 /9.X
MariaDB	支持	支持	10.3-10.11 LTS / 11.x
Percona Server for MySQL	支持	支持	5.7 / 8.0 / 8.4 LTS
PostgreSQL	支持	支持	9.6 / 10-13 / 14 / 15 / 16 / 17
IBM DB2	支持	支持	10.5 / 11.1 / 11.5 (LUW)
Microsoft SQL Server	支持	支持	2008 R2 / 2012 / 2014 / 2016 / 2017 / 2019 / 2022
Redis	支持	支持	4.x / 5.x / 6.x / 7.x
MongoDB	支持	支持	3.6 / 4.0-4.4 / 5.0 / 6.0 / 7.0

说明：MariaDB 和 Percona Server 与 MySQL 协议兼容，归入 MySQL 族，复用同一套连接器和类型映射。Redis 为 KV 存储，迁移时将 key/type/value 展平为单表结构。MongoDB 为文档数据库，迁移时通过采样推断列类型并展平为表。

3.2 支持的操作系统

操作系统	版本
CentOS	7.x / 8.x / Stream 8/9
RHEL (Red Hat Enterprise Linux)	7.x / 8.x / 9.x
Ubuntu	18.04 / 20.04 / 22.04 / 24.04 LTS
Debian	10 / 11 / 12
SUSE Linux Enterprise Server	12 / 15
Oracle Linux	7 / 8 / 9
Rocky Linux	8 / 9
AlmaLinux	8 / 9
Fedora	38 / 39 / 40
Windows Server	2016 / 2019 / 2022 / 2025
Windows 桌面	Windows 10 / 11
macOS	11+ (Big Sur / Monterey / Sonoma / Sequoia)
IBM AIX	7.2 / 7.3
麒麟 Kylin	V10 SP1/SP2/SP3, Kylin Server V10
统信 UOS	V20 (1020/1021/1022/1060), UOS Server
深度 Deepin	20.x / 23
openEuler	20.03 / 22.03 / 24.03 LTS
Anolis OS	7.9 / 8.x
openSUSE	Leap 15.x
TencentOS Server	2.4 / 3.1

3.3 支持的 CPU 架构

x86_64 (amd64)
aarch64 (arm64)
loongarch64
mips64el
sw_64 (申威)

3.4 Python 环境要求

Python 版本：3.8 及以上（推荐 3.9+）
依赖包：见 requirements.txt

3.5 核心依赖包

依赖包	用途	必装
PyYAML	配置文件解析	是
Flask	可视化控制台 Web 框架	是
Werkzeug	Flask WSGI 工具库	是
PyMySQL	MySQL/MariaDB/Percona 驱动	按需
psycopg2-binary	PostgreSQL 驱动	按需
oracledb	Oracle 驱动（纯 Python thin 模式）	按需
ibm_db	IBM DB2 驱动	按需
pyodbc	MS SQL Server 驱动	按需
redis	Redis 驱动	按需
pymongo	MongoDB 驱动	按需
dnspython	MongoDB Atlas SRV 解析	可选
xhtml2pdf	评估报告导出 PDF	可选
psutil	实时 CPU/内存监控	可选

所有数据库驱动均为「按需加载」：缺失某驱动时仅影响对应源/目标端可用性，其他功能不受影响，程序不会崩溃。

3.6 系统级依赖

部分数据库驱动需要额外的系统级依赖（pip 无法安装）：

Oracle Instant Client：仅 oracledb thick 模式需要（thin 模式可跳过）
IBM DB2 clidriver：使用 ibm_db 时需要（pip install ibm_db 通常自动下载）
FreeTDS + unixODBC：使用 pyodbc 连接 SQL Server 时需要
gcc + python3-devel + postgresql-devel：仅 psycopg2 需自编译时需要

详细安装方法见 requirements.txt 文件末尾的「系统级依赖」章节。

四、程序使用

4.1 安装

# 1. 克隆项目
cd /opt
# 将项目放置到目标目录

# 2. 安装 Python 依赖
cd FGO2ODB
pip install -r requirements.txt

# 3. 编译原生 C 引擎（可选，缺失时自动回退到 Python）
cd native
make install
cd ..

# 4. 验证安装
python3 fgo2odb.py version

4.2 配置文件

FGO2ODB 使用 YAML 格式配置文件，包含以下主要部分：

# 源端配置
source:
  type: mysql                    # 数据库类型
  host: localhost
  port: 3306
  username: root
  password: password
  database: source_db
  charset: utf8mb4

# 目标端配置
target:
  type: postgresql
  host: localhost
  port: 5432
  username: postgres
  password: password
  database: target_db
  schema: public

# 转换选项
conversion:
  options:
    tableddl: true               # 迁移表结构
    data: true                   # 迁移数据
    indexes: true                # 迁移索引
    views: false                 # 迁移视图
    sequences: false             # 迁移序列
    functions: false             # 迁移函数
    procedures: false            # 迁移存储过程
    triggers: false              # 迁移触发器
    validate_data: true          # 数据校验
    consistent_snapshot: true    # 一致性快照
  limits:
    concurrency: 8               # 并发表数
    batch_insert_size: 50000     # 批量插入行数
    fetch_size: 10000            # 每批 fetch 大小
    parallel_tables: 4           # 多表并行度
    streaming_cursor: true       # 流式游标
    memory_limit_mb: 2048        # 内存软限
    memory_hard_limit_mb: 4096   # 内存硬限
    retry_times: 3               # 重试次数
    retry_delay: 5.0             # 重试退避基数（秒）
    bulk_insert: true            # 是否启用 COPY/bulk
    checkpoint_dir: "./.checkpoint"
    large_table_threshold: 1000000
    huge_table_threshold: 10000000

# 日志配置
log_file: fgo2odb.log
log_level: INFO

生成示例配置文件：

python3 fgo2odb.py gen-config -o config.yml

4.3 命令行子命令

FGO2ODB 提供以下子命令：

子命令	功能说明
`migrate`	完整迁移（DDL + 数据 + 索引 + 视图 + 函数 + 校验）
`ddl`	仅生成/导出 DDL 脚本（不执行）
`data`	仅迁移数据（表结构需已存在）
`validate`	校验迁移后数据行数一致性
`assess`	评估源端数据库（表/行数/列数）
`gen-config`	生成示例配置文件
`typemap`	查看类型映射结果
`funcmap`	查看函数映射结果
`version`	显示版本信息
`web`	启动可视化控制台

4.4 常用命令示例

# 查看版本信息
python3 fgo2odb.py version

# 查看类型映射（Oracle -> MySQL）
python3 fgo2odb.py typemap -s oracle -t mysql

# 查看函数映射（MySQL -> PostgreSQL）
python3 fgo2odb.py funcmap -s mysql -t postgresql

# 生成配置文件
python3 fgo2odb.py gen-config -o config.yml

# 评估源端数据库
python3 fgo2odb.py -c config.yml assess

# 生成 DDL 脚本（不执行）
python3 fgo2odb.py -c config.yml ddl -o output.sql

# 仅迁移数据
python3 fgo2odb.py -c config.yml data

# 完整迁移
python3 fgo2odb.py -c config.yml migrate

# 校验迁移结果
python3 fgo2odb.py -c config.yml validate

# 启动可视化控制台
python3 fgo2odb.py web -c config.yml -H 0.0.0.0 -p 8088

4.5 可视化控制台

启动 Web 控制台：

python3 fgo2odb.py web -c config.yml -H 0.0.0.0 -p 8088
# 或使用专用入口
python3 webctl.py start -c config.yml -H 0.0.0.0 -p 8088

浏览器访问 http://<服务器IP>:8088 即可打开控制台界面。

控制台功能：

配置管理：在线编辑 YAML 配置，一键测试连接
迁移评估：评估源端数据库规模
迁移执行：启动/暂停/恢复/停止迁移
实时监控：SSE 实时进度推送、逐表状态网格、速率与 ETA
日志查看：实时滚动日志
报告查看：迁移完成后查看 HTML 报告

五、案例场景与操作过程

5.1 案例：MySQL 迁移至 PostgreSQL

场景描述：互联网公司业务库 MySQL 5.7 迁移至 PostgreSQL 16，共 120 张表，总数据量约 200GB。

操作步骤：

准备配置文件：

# 使用模板
cp templates/mysql_to_postgresql.yml config.yml
# 编辑配置文件，填入实际的源端和目标端连接信息
vi config.yml

评估源端：

python3 fgo2odb.py -c config.yml assess

输出示例：

源端数据库: mysql (10.0.0.10:3306/source_db)
表数量: 120

表名                                     行数      列数
--------------------------------------------------------------
users                                  15000000       12
orders                                  8000000       15
products                                 500000        8
...
--------------------------------------------------------------
合计                                  200000000

预览 DDL：

python3 fgo2odb.py -c config.yml ddl -o preview.sql
# 人工审核 preview.sql 中的类型映射是否正确

执行完整迁移：

python3 fgo2odb.py -c config.yml migrate

迁移过程中日志输出：

[INFO] 原生引擎: 1.0.0 (loaded=True)
[INFO] 源端: mysql -> 目标端: postgresql
[INFO] MySQL 族源端已连接: 10.0.0.10:3306/source_db
[INFO] PostgreSQL 目标端已连接: 10.0.0.20:5432/target_db
[INFO] 建表成功: users -> users
[INFO] 开始数据迁移: 120 表, 预估 200000000 行, 并行度 4
[INFO] [users] 100000/15000000 行, 25000 rows/s
...
[INFO] 数据迁移完成: 120/120 表成功, 200000000 行, 7200.5s
[INFO] 迁移完成

校验数据：

python3 fgo2odb.py -c config.yml validate

输出示例：

  ✓ users: pass
  ✓ orders: pass
  ✓ products: pass
  ...
校验结果: 120 通过, 0 失败, 120 总计

5.2 案例：Oracle 迁移至 MySQL

场景描述：传统企业 Oracle 19c 迁移至 MySQL 8.0，共 50 张表，含存储过程和触发器。

操作步骤：

准备配置：

cp templates/oracle_to_mysql.yml config.yml
vi config.yml
# 设置 source.type=oracle, source.service_name=ORCLPDB1
# 设置 target.type=mysql

查看类型映射：

python3 fgo2odb.py typemap -s oracle -t mysql

关键映射：

NUMBER(10)               INT
NUMBER(10,2)             DECIMAL
NUMBER(19)               BIGINT
VARCHAR2(4000)           VARCHAR(4000)
CLOB                     LONGTEXT
BLOB                     LONGBLOB
DATE                     DATETIME
TIMESTAMP               TIMESTAMP

启用存储过程和触发器迁移：

conversion:
  options:
    procedures: true
    triggers: true
    functions: true

执行迁移：

python3 fgo2odb.py -c config.yml migrate

检查待手工修复项：迁移结束后检查日志中的「待手工修复」清单，部分复杂存储过程可能需要人工调整后重新部署。

5.3 案例：SQL Server 迁移至 PostgreSQL

场景描述：微软技术栈迁移至开源栈，SQL Server 2019 迁移至 PostgreSQL 16。

操作步骤：

准备配置：

cp templates/sqlserver_to_postgresql.yml config.yml
vi config.yml
# 设置 source.type=sqlserver, source.schema=dbo
# 设置 target.type=postgresql

查看类型映射：

python3 fgo2odb.py typemap -s sqlserver -t postgresql

关键映射：

bigint                   BIGINT
int                      INTEGER
bit                      BOOLEAN
decimal(18,2)            NUMERIC(18,2)
datetime                 TIMESTAMP
datetime2                TIMESTAMP
nvarchar(100)            VARCHAR(100)
varchar(max)             TEXT
varbinary(100)           BYTEA
uniqueidentifier         UUID

执行迁移：

python3 fgo2odb.py -c config.yml migrate

5.4 案例：DB2 迁移至 Oracle

场景描述：金融系统 DB2 11.5 迁移至 Oracle 19c。

操作步骤：

准备配置：

cp templates/db2_to_oracle.yml config.yml
vi config.yml

查看类型映射：

python3 fgo2odb.py typemap -s db2 -t oracle

执行迁移：

python3 fgo2odb.py -c config.yml migrate

5.5 案例：Redis 迁移至 MongoDB

场景描述：缓存数据迁移，Redis 7.x 中的 KV 数据迁移至 MongoDB 7.0 文档库。

操作步骤：

准备配置：

source:
  type: redis
  host: 10.0.0.10
  port: 6379
  password: redis_pwd

target:
  type: mongodb
  host: 10.0.0.20
  port: 27017
  username: admin
  password: mongo_pwd
  database: cache_db

执行迁移：

python3 fgo2odb.py -c config.yml migrate

Redis 中的 string/hash/list/set/zset/stream 类型会自动展平为 MongoDB 文档集合。

5.6 案例：TB 级大数据迁移

场景描述：数据仓库 MySQL 8.0 迁移至 PostgreSQL 16，单表 5TB，总数据量 20TB。

操作步骤：

调整配置：

conversion:
  limits:
    parallel_tables: 8             # 提高并行度
    batch_insert_size: 100000      # 增大批次
    fetch_size: 50000              # 增大 fetch 批次
    memory_limit_mb: 4096          # 提高内存限制
    memory_hard_limit_mb: 8192     # 提高内存硬限
    bulk_insert: true              # 启用 COPY
    retry_times: 5                 # 增加重试次数
    retry_delay: 10.0              # 增大退避间隔
    checkpoint_dir: "/data/checkpoint"  # 检查点放高性能磁盘

启动迁移：

python3 fgo2odb.py -c config.yml migrate

中断恢复：如果迁移中途因网络中断或手动停止，直接重新运行同一命令，已完成的表自动跳过：

python3 fgo2odb.py -c config.yml migrate
# 日志: 表 users 已完成（断点），跳过

清理断点（重新迁移时）：

rm -rf /data/checkpoint/

5.7 案例：使用可视化控制台迁移

场景描述：通过 Web 界面完成 Oracle 到 PostgreSQL 的迁移。

操作步骤：

启动控制台：

python3 fgo2odb.py web -c config.yml -H 0.0.0.0 -p 8088

浏览器访问：打开 http://<服务器IP>:8088
配置连接：在界面左侧填写源端（Oracle）和目标端（PostgreSQL）连接参数，点击「测试连接」
评估迁移：点击「迁移评估」按钮，查看源端表数量和行数
启动迁移：点击「启动迁移」按钮，开始迁移
实时监控：在进度面板查看每张表的迁移状态、行数、速率、ETA
暂停/恢复：如需暂停，点击「暂停」按钮；恢复时点击「恢复」
查看报告：迁移完成后点击「查看报告」，浏览 HTML 格式的迁移报告

5.8 全场景迁移矩阵与操作过程（60 个案例）

以下列出 FGO2ODB 支持的全部 60 个迁移场景，覆盖 9 种数据库两两互通及 5 个高级场景。每个场景均给出：典型业务场景、关键迁移要点、以及完整的操作命令过程。所有场景共享通用流程，命令差异仅在配置文件中的 source.type 与 target.type。

通用操作流程（所有 60 个场景均遵循）：

# 步骤 1：生成配置文件（自动写入源/目标族）
python3 fgo2odb.py gen-config -o config.yml

# 步骤 2：编辑配置文件，填入源端和目标端连接信息
vi config.yml

# 步骤 3：预览类型映射（确认关键类型映射正确）
python3 fgo2odb.py typemap -s <源族> -t <目标族>

# 步骤 4：预览函数映射（如需迁移视图/函数/存储过程）
python3 fgo2odb.py funcmap -s <源族> -t <目标族>

# 步骤 5：生成 DDL 脚本预览（人工审核类型转换）
python3 fgo2odb.py -c config.yml ddl -o preview.sql

# 步骤 6：评估源端规模（表数、行数、数据量）
python3 fgo2odb.py -c config.yml assess

# 步骤 7：执行完整迁移（DDL + 数据 + 索引 + 视图 + 函数 + 校验）
python3 fgo2odb.py -c config.yml migrate

# 步骤 8：校验数据一致性（行数对齐 + 抽样对比）
python3 fgo2odb.py -c config.yml validate

# 步骤 9：（可选）启动可视化控制台监控
python3 fgo2odb.py web -c config.yml -H 0.0.0.0 -p 8088

每个场景的关键配置片段如下表，只需将其替换到步骤 2 的 config.yml 中即可执行完整迁移。

5.8.1 Oracle 作为源端（8 个场景）

序号	迁移路径	典型业务场景	关键迁移要点	关键配置片段
1	Oracle -> MySQL	传统企业去 O 化，降本增效，业务上云	NUMBER(p,s) 精确映射 DECIMAL，CLOB->LONGTEXT，序列->AUTO_INCREMENT	`source.type: oracle` `target.type: mysql`
2	Oracle -> PostgreSQL	开源替代，利用 PG 丰富类型与扩展生态	NUMBER->NUMERIC，SYSDATE->CURRENT_TIMESTAMP，PL/SQL 转 PL/pgSQL	`source.type: oracle` `target.type: postgresql`
3	Oracle -> MariaDB	追求完全开源栈，MariaDB 兼容 MySQL 协议	与 Oracle->MySQL 相同，复用 MySQL 族连接器	`source.type: oracle` `target.type: mariadb`
4	Oracle -> Percona	需要更强性能监控的 MySQL 分支目标	Percona Server 兼容 MySQL 协议，复用 MySQL 族连接器	`source.type: oracle` `target.type: percona`
5	Oracle -> DB2	跨传统商业库迁移，金融行业常见	字符集对齐（AL32UTF8->UTF-8），序列互转	`source.type: oracle` `target.type: db2`
6	Oracle -> SQL Server	微软技术栈整合，企业级迁移	NUMBER->DECIMAL，SYSDATE->GETDATE()，存储过程重写 T-SQL	`source.type: oracle` `target.type: sqlserver`
7	Oracle -> MongoDB	结构化数据转文档化，灵活 schema 场景	表展平为集合，CLOB/BLOB 转 String/Binary，主键 _id	`source.type: oracle` `target.type: mongodb`
8	Oracle -> Redis	缓存预热，将维表/字典表灌入 Redis	需自定义 WHERE 条件过滤，表数据展平为 KV 结构	`source.type: oracle` `target.type: redis`

场景 1：Oracle -> MySQL 完整操作过程

# config.yml 关键配置
source:
  type: oracle
  host: 10.0.0.10
  port: 1521
  user: scott
  password: tiger
  service_name: ORCLPDB1
  schema: SCOTT

target:
  type: mysql
  host: 10.0.0.20
  port: 3306
  user: root
  password: mysql_pwd
  database: scott_db
  charset: utf8mb4

# 1. 生成并编辑配置
python3 fgo2odb.py gen-config -o config.yml && vi config.yml

# 2. 预览 Oracle->MySQL 类型映射
python3 fgo2odb.py typemap -s oracle -t mysql

# 3. 预览 DDL（审核 NUMBER->DECIMAL、CLOB->LONGTEXT 等转换）
python3 fgo2odb.py -c config.yml ddl -o preview.sql

# 4. 评估源端规模
python3 fgo2odb.py -c config.yml assess

# 5. 执行迁移（DDL+数据+索引+校验）
python3 fgo2odb.py -c config.yml migrate

# 6. 校验数据一致性
python3 fgo2odb.py -c config.yml validate

场景 2：Oracle -> PostgreSQL 完整操作过程

source:
  type: oracle
  host: 10.0.0.10
  port: 1521
  user: scott
  password: tiger
  service_name: ORCLPDB1
  schema: SCOTT

target:
  type: postgresql
  host: 10.0.0.20
  port: 5432
  user: postgres
  password: pg_pwd
  database: scott_db
  schema: public

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s oracle -t postgresql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

场景 3-8：Oracle -> 其他目标端操作过程

场景 3-8 与场景 1 流程完全一致，仅需将 target.type 改为 mariadb / percona / db2 / sqlserver / mongodb / redis，并按目标端实际参数填入 host / port / user / password / database 等字段。完整命令链：

# 场景 3：Oracle -> MariaDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=oracle, target.type=mariadb
python3 fgo2odb.py typemap -s oracle -t mariadb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 4：Oracle -> Percona
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=oracle, target.type=percona
python3 fgo2odb.py typemap -s oracle -t percona
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 5：Oracle -> DB2
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=oracle, target.type=db2
python3 fgo2odb.py typemap -s oracle -t db2
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 6：Oracle -> SQL Server
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=oracle, target.type=sqlserver
python3 fgo2odb.py typemap -s oracle -t sqlserver
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 7：Oracle -> MongoDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=oracle, target.type=mongodb
python3 fgo2odb.py typemap -s oracle -t mongodb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 8：Oracle -> Redis
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=oracle, target.type=redis
python3 fgo2odb.py typemap -s oracle -t redis
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

5.8.2 MySQL 作为源端（8 个场景）

序号	迁移路径	典型业务场景	关键迁移要点	关键配置片段
9	MySQL -> Oracle	上云后又回迁商业库，或合规要求	INT->NUMBER(10)，utf8mb4->AL32UTF8，AUTO_INCREMENT->序列	`source.type: mysql` `target.type: oracle`
10	MySQL -> PostgreSQL	互联网业务升级，利用 PG 事务与扩展	TINYINT->SMALLINT，DATETIME->TIMESTAMP，ENUM->VARCHAR	`source.type: mysql` `target.type: postgresql`
11	MySQL -> MariaDB	同协议分支切换，平滑过渡	协议兼容，几乎零转换，直接全量同步	`source.type: mysql` `target.type: mariadb`
12	MySQL -> Percona	需要更强诊断性能的 MySQL 分支	协议兼容，直接全量同步	`source.type: mysql` `target.type: percona`
13	MySQL -> DB2	跨库迁移至金融行业标准库	DECIMAL 精度对齐，字符集 UTF-8 强制	`source.type: mysql` `target.type: db2`
14	MySQL -> SQL Server	微软生态整合，企业 IT 标准化	TEXT->NVARCHAR(MAX)，DATETIME->DATETIME2，索引重写	`source.type: mysql` `target.type: sqlserver`
15	MySQL -> MongoDB	表转文档，业务灵活 schema 需求	每行转文档，主键转 _id，JSON 列展平	`source.type: mysql` `target.type: mongodb`
16	MySQL -> Redis	缓存预热，字典表灌入 Redis	仅迁移小表，自定义 WHERE 条件	`source.type: mysql` `target.type: redis`

场景 9：MySQL -> Oracle 完整操作过程

source:
  type: mysql
  host: 10.0.0.10
  port: 3306
  user: root
  password: mysql_pwd
  database: business_db
  charset: utf8mb4

target:
  type: oracle
  host: 10.0.0.20
  port: 1521
  user: business
  password: oracle_pwd
  service_name: ORCLPDB1
  schema: BUSINESS

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s mysql -t oracle
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

场景 10：MySQL -> PostgreSQL 完整操作过程

source:
  type: mysql
  host: 10.0.0.10
  port: 3306
  user: root
  password: mysql_pwd
  database: business_db

target:
  type: postgresql
  host: 10.0.0.20
  port: 5432
  user: postgres
  password: pg_pwd
  database: business_db
  schema: public

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s mysql -t postgresql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

场景 11-16：MySQL -> 其他目标端操作过程

# 场景 11：MySQL -> MariaDB（协议兼容，零转换）
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mysql, target.type=mariadb
python3 fgo2odb.py typemap -s mysql -t mariadb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 12：MySQL -> Percona（协议兼容，零转换）
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mysql, target.type=percona
python3 fgo2odb.py typemap -s mysql -t percona
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 13：MySQL -> DB2
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mysql, target.type=db2
python3 fgo2odb.py typemap -s mysql -t db2
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 14：MySQL -> SQL Server
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mysql, target.type=sqlserver
python3 fgo2odb.py typemap -s mysql -t sqlserver
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 15：MySQL -> MongoDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mysql, target.type=mongodb
python3 fgo2odb.py typemap -s mysql -t mongodb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 16：MySQL -> Redis
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mysql, target.type=redis
python3 fgo2odb.py typemap -s mysql -t redis
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

5.8.3 MariaDB 作为源端（7 个场景）

序号	迁移路径	典型业务场景	关键迁移要点	关键配置片段
17	MariaDB -> MySQL	回归主线分支，生态兼容性需求	协议兼容，直接全量同步	`source.type: mariadb` `target.type: mysql`
18	MariaDB -> PostgreSQL	开源升级，利用 PG 丰富类型	复用 MySQL 族映射规则	`source.type: mariadb` `target.type: postgresql`
19	MariaDB -> Oracle	合规上商业库，金融/政企场景	utf8mb4->AL32UTF8，AUTO_INCREMENT->序列	`source.type: mariadb` `target.type: oracle`
20	MariaDB -> Percona	分支间切换，性能诊断需求	协议兼容，直接全量同步	`source.type: mariadb` `target.type: percona`
21	MariaDB -> DB2	跨库迁移至金融标准库	DECIMAL 精度对齐，字符集强制	`source.type: mariadb` `target.type: db2`
22	MariaDB -> SQL Server	微软生态整合	TEXT->NVARCHAR(MAX)，函数重写	`source.type: mariadb` `target.type: sqlserver`
23	MariaDB -> MongoDB	表转文档	复用 MySQL 族展平逻辑	`source.type: mariadb` `target.type: mongodb`

场景 17-23：MariaDB -> 各目标端操作过程

# 以场景 19：MariaDB -> Oracle 为例，其他场景替换 target.type 即可
source:
  type: mariadb
  host: 10.0.0.10
  port: 3306
  user: root
  password: mariadb_pwd
  database: business_db

target:
  type: oracle
  host: 10.0.0.20
  port: 1521
  user: business
  password: oracle_pwd
  service_name: ORCLPDB1
  schema: BUSINESS

# 场景 17：MariaDB -> MySQL
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mariadb, target.type=mysql
python3 fgo2odb.py typemap -s mariadb -t mysql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 18：MariaDB -> PostgreSQL
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mariadb, target.type=postgresql
python3 fgo2odb.py typemap -s mariadb -t postgresql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 19：MariaDB -> Oracle
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mariadb, target.type=oracle
python3 fgo2odb.py typemap -s mariadb -t oracle
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 20：MariaDB -> Percona
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mariadb, target.type=percona
python3 fgo2odb.py typemap -s mariadb -t percona
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 21：MariaDB -> DB2
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mariadb, target.type=db2
python3 fgo2odb.py typemap -s mariadb -t db2
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 22：MariaDB -> SQL Server
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mariadb, target.type=sqlserver
python3 fgo2odb.py typemap -s mariadb -t sqlserver
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 23：MariaDB -> MongoDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=mariadb, target.type=mongodb
python3 fgo2odb.py typemap -s mariadb -t mongodb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

5.8.4 Percona 作为源端（7 个场景）

序号	迁移路径	典型业务场景	关键迁移要点	关键配置片段
24	Percona -> MySQL	回归社区主线，减少定制化	协议兼容，直接全量同步	`source.type: percona` `target.type: mysql`
25	Percona -> MariaDB	分支间切换	协议兼容，直接全量同步	`source.type: percona` `target.type: mariadb`
26	Percona -> PostgreSQL	开源升级，类型丰富需求	复用 MySQL 族映射规则	`source.type: percona` `target.type: postgresql`
27	Percona -> Oracle	合规上商业库	utf8mb4->AL32UTF8，序列迁移	`source.type: percona` `target.type: oracle`
28	Percona -> DB2	跨库迁移至金融标准库	精度对齐，字符集强制	`source.type: percona` `target.type: db2`
29	Percona -> SQL Server	微软生态整合	函数重写，索引重建	`source.type: percona` `target.type: sqlserver`
30	Percona -> MongoDB	表转文档	复用 MySQL 族展平逻辑	`source.type: percona` `target.type: mongodb`

场景 24-30：Percona -> 各目标端操作过程

# 以场景 26：Percona -> PostgreSQL 为例，其他场景替换 target.type 即可
source:
  type: percona
  host: 10.0.0.10
  port: 3306
  user: root
  password: percona_pwd
  database: business_db

target:
  type: postgresql
  host: 10.0.0.20
  port: 5432
  user: postgres
  password: pg_pwd
  database: business_db
  schema: public

# 场景 24：Percona -> MySQL
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=percona, target.type=mysql
python3 fgo2odb.py typemap -s percona -t mysql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 25：Percona -> MariaDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=percona, target.type=mariadb
python3 fgo2odb.py typemap -s percona -t mariadb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 26：Percona -> PostgreSQL
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=percona, target.type=postgresql
python3 fgo2odb.py typemap -s percona -t postgresql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 27：Percona -> Oracle
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=percona, target.type=oracle
python3 fgo2odb.py typemap -s percona -t oracle
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 28：Percona -> DB2
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=percona, target.type=db2
python3 fgo2odb.py typemap -s percona -t db2
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 29：Percona -> SQL Server
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=percona, target.type=sqlserver
python3 fgo2odb.py typemap -s percona -t sqlserver
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 30：Percona -> MongoDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=percona, target.type=mongodb
python3 fgo2odb.py typemap -s percona -t mongodb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

5.8.5 PostgreSQL 作为源端（7 个场景）

序号	迁移路径	典型业务场景	关键迁移要点	关键配置片段
31	PostgreSQL -> MySQL	回迁互联网主流，运维简单化	NUMERIC->DECIMAL，BYTEA->BLOB，SERIAL->AUTO_INCREMENT	`source.type: postgresql` `target.type: mysql`
32	PostgreSQL -> Oracle	合规要求上商业库	NUMERIC->NUMBER，TEXT->CLOB，函数重写 PL/SQL	`source.type: postgresql` `target.type: oracle`
33	PostgreSQL -> MariaDB	追求完全开源栈	复用 MySQL 族映射规则	`source.type: postgresql` `target.type: mariadb`
34	PostgreSQL -> Percona	需要性能诊断的 MySQL 分支	复用 MySQL 族映射规则	`source.type: postgresql` `target.type: percona`
35	PostgreSQL -> DB2	跨库迁移至金融标准库	NUMERIC 精度对齐，字符集 UTF-8	`source.type: postgresql` `target.type: db2`
36	PostgreSQL -> SQL Server	微软生态整合	NUMERIC->DECIMAL，TIMESTAMP->DATETIME2	`source.type: postgresql` `target.type: sqlserver`
37	PostgreSQL -> MongoDB	关系转文档，灵活 schema	行转文档，JSONB 展平	`source.type: postgresql` `target.type: mongodb`

场景 31：PostgreSQL -> MySQL 完整操作过程

source:
  type: postgresql
  host: 10.0.0.10
  port: 5432
  user: postgres
  password: pg_pwd
  database: business_db
  schema: public

target:
  type: mysql
  host: 10.0.0.20
  port: 3306
  user: root
  password: mysql_pwd
  database: business_db
  charset: utf8mb4

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s postgresql -t mysql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

场景 32-37：PostgreSQL -> 其他目标端操作过程

# 场景 32：PostgreSQL -> Oracle
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=postgresql, target.type=oracle
python3 fgo2odb.py typemap -s postgresql -t oracle
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 33：PostgreSQL -> MariaDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=postgresql, target.type=mariadb
python3 fgo2odb.py typemap -s postgresql -t mariadb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 34：PostgreSQL -> Percona
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=postgresql, target.type=percona
python3 fgo2odb.py typemap -s postgresql -t percona
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 35：PostgreSQL -> DB2
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=postgresql, target.type=db2
python3 fgo2odb.py typemap -s postgresql -t db2
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 36：PostgreSQL -> SQL Server
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=postgresql, target.type=sqlserver
python3 fgo2odb.py typemap -s postgresql -t sqlserver
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 37：PostgreSQL -> MongoDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=postgresql, target.type=mongodb
python3 fgo2odb.py typemap -s postgresql -t mongodb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

5.8.6 DB2 作为源端（7 个场景）

序号	迁移路径	典型业务场景	关键迁移要点	关键配置片段
38	DB2 -> Oracle	金融行业跨商业库迁移	DECIMAL 精度对齐，字符集 AL32UTF8，序列互转	`source.type: db2` `target.type: oracle`
39	DB2 -> MySQL	降本增效，互联网化	DECIMAL->DECIMAL，CHAR->VARCHAR，GRAPHIC->VARCHAR	`source.type: db2` `target.type: mysql`
40	DB2 -> PostgreSQL	开源替代，金融行业常见	DECIMAL->NUMERIC，LONG VARCHAR->TEXT	`source.type: db2` `target.type: postgresql`
41	DB2 -> MariaDB	追求完全开源栈	复用 MySQL 族映射规则	`source.type: db2` `target.type: mariadb`
42	DB2 -> Percona	需要性能诊断的 MySQL 分支	复用 MySQL 族映射规则	`source.type: db2` `target.type: percona`
43	DB2 -> SQL Server	微软生态整合，跨商业库	DECIMAL->DECIMAL，TIMESTAMP->DATETIME2	`source.type: db2` `target.type: sqlserver`
44	DB2 -> MongoDB	金融数据文档化分析	表展平为集合，BLOB 转 Binary	`source.type: db2` `target.type: mongodb`

场景 38：DB2 -> Oracle 完整操作过程

source:
  type: db2
  host: 10.0.0.10
  port: 50000
  user: db2inst1
  password: db2_pwd
  database: SAMPLE

target:
  type: oracle
  host: 10.0.0.20
  port: 1521
  user: business
  password: oracle_pwd
  service_name: ORCLPDB1
  schema: BUSINESS

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s db2 -t oracle
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

场景 39-44：DB2 -> 其他目标端操作过程

# 场景 39：DB2 -> MySQL
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=db2, target.type=mysql
python3 fgo2odb.py typemap -s db2 -t mysql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 40：DB2 -> PostgreSQL
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=db2, target.type=postgresql
python3 fgo2odb.py typemap -s db2 -t postgresql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 41：DB2 -> MariaDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=db2, target.type=mariadb
python3 fgo2odb.py typemap -s db2 -t mariadb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 42：DB2 -> Percona
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=db2, target.type=percona
python3 fgo2odb.py typemap -s db2 -t percona
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 43：DB2 -> SQL Server
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=db2, target.type=sqlserver
python3 fgo2odb.py typemap -s db2 -t sqlserver
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 44：DB2 -> MongoDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=db2, target.type=mongodb
python3 fgo2odb.py typemap -s db2 -t mongodb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

5.8.7 SQL Server 作为源端（7 个场景）

序号	迁移路径	典型业务场景	关键迁移要点	关键配置片段
45	SQL Server -> MySQL	微软栈转互联网开源	NVARCHAR->VARCHAR，DATETIME->DATETIME，GETDATE()->NOW()	`source.type: sqlserver` `target.type: mysql`
46	SQL Server -> PostgreSQL	微软栈转开源 PG	BIT->BOOLEAN，UNIQUEIDENTIFIER->UUID，函数重写	`source.type: sqlserver` `target.type: postgresql`
47	SQL Server -> Oracle	微软栈转商业 Oracle	NVARCHAR->VARCHAR2，DATETIME->DATE，T-SQL 转 PL/SQL	`source.type: sqlserver` `target.type: oracle`
48	SQL Server -> MariaDB	微软栈转完全开源	复用 MySQL 族映射规则	`source.type: sqlserver` `target.type: mariadb`
49	SQL Server -> Percona	微软栈转 MySQL 性能分支	复用 MySQL 族映射规则	`source.type: sqlserver` `target.type: percona`
50	SQL Server -> DB2	微软栈转金融标准库	精度对齐，函数重写	`source.type: sqlserver` `target.type: db2`
51	SQL Server -> MongoDB	表转文档，T-SQL 场景文档化	行转文档，NVARCHAR(MAX) 转 String	`source.type: sqlserver` `target.type: mongodb`

场景 45：SQL Server -> MySQL 完整操作过程

source:
  type: sqlserver
  host: 10.0.0.10
  port: 1433
  user: sa
  password: sqlserver_pwd
  database: business_db
  schema: dbo

target:
  type: mysql
  host: 10.0.0.20
  port: 3306
  user: root
  password: mysql_pwd
  database: business_db
  charset: utf8mb4

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s sqlserver -t mysql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

场景 46-51：SQL Server -> 其他目标端操作过程

# 场景 46：SQL Server -> PostgreSQL
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=sqlserver, target.type=postgresql
python3 fgo2odb.py typemap -s sqlserver -t postgresql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 47：SQL Server -> Oracle
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=sqlserver, target.type=oracle
python3 fgo2odb.py typemap -s sqlserver -t oracle
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 48：SQL Server -> MariaDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=sqlserver, target.type=mariadb
python3 fgo2odb.py typemap -s sqlserver -t mariadb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 49：SQL Server -> Percona
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=sqlserver, target.type=percona
python3 fgo2odb.py typemap -s sqlserver -t percona
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 50：SQL Server -> DB2
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=sqlserver, target.type=db2
python3 fgo2odb.py typemap -s sqlserver -t db2
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

# 场景 51：SQL Server -> MongoDB
python3 fgo2odb.py gen-config -o config.yml
# 编辑 config.yml，设 source.type=sqlserver, target.type=mongodb
python3 fgo2odb.py typemap -s sqlserver -t mongodb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

5.8.8 Redis 作为源端（2 个场景）

序号	迁移路径	典型业务场景	关键迁移要点	关键配置片段
52	Redis -> MongoDB	缓存数据持久化到文档库	KV 展平为文档，hash->嵌套对象，zset->带分数字段	`source.type: redis` `target.type: mongodb`
53	Redis -> MySQL	缓存回灌关系库，数据分析	KV 展平为单表（key/type/field/value/score），SCAN 遍历	`source.type: redis` `target.type: mysql`

场景 52：Redis -> MongoDB 完整操作过程

source:
  type: redis
  host: 10.0.0.10
  port: 6379
  password: redis_pwd

target:
  type: mongodb
  host: 10.0.0.20
  port: 27017
  username: admin
  password: mongo_pwd
  database: cache_db

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s redis -t mongodb
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
# Redis 中的 string/hash/list/set/zset/stream 会自动展平为 MongoDB 文档集合
python3 fgo2odb.py -c config.yml validate

场景 53：Redis -> MySQL 完整操作过程

source:
  type: redis
  host: 10.0.0.10
  port: 6379
  password: redis_pwd

target:
  type: mysql
  host: 10.0.0.20
  port: 3306
  user: root
  password: mysql_pwd
  database: cache_db
  charset: utf8mb4

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s redis -t mysql
python3 fgo2odb.py -c config.yml ddl -o preview.sql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml migrate
# KV 展平为单表（key/type/field/value/score），SCAN 全量遍历
python3 fgo2odb.py -c config.yml validate

5.8.9 MongoDB 作为源端（2 个场景）

序号	迁移路径	典型业务场景	关键迁移要点	关键配置片段
54	MongoDB -> MySQL	文档转关系，业务结构化	采样推断列类型，文档展平为行，嵌套对象转 JSON 字符串	`source.type: mongodb` `target.type: mysql`
55	MongoDB -> PostgreSQL	文档转关系，利用 PG JSONB	采样推断列类型，嵌套对象可转 JSONB	`source.type: mongodb` `target.type: postgresql`

场景 54：MongoDB -> MySQL 完整操作过程

source:
  type: mongodb
  host: 10.0.0.10
  port: 27017
  username: admin
  password: mongo_pwd
  database: source_db

target:
  type: mysql
  host: 10.0.0.20
  port: 3306
  user: root
  password: mysql_pwd
  database: target_db
  charset: utf8mb4

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s mongodb -t mysql
# 1. 评估 collection 规模
python3 fgo2odb.py -c config.yml assess
# 2. 预览推断列类型（采样后自动推断）
python3 fgo2odb.py -c config.yml ddl -o preview.sql
# 3. 执行迁移（文档展平为行，嵌套对象转 JSON 字符串）
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

场景 55：MongoDB -> PostgreSQL 完整操作过程

source:
  type: mongodb
  host: 10.0.0.10
  port: 27017
  username: admin
  password: mongo_pwd
  database: source_db

target:
  type: postgresql
  host: 10.0.0.20
  port: 5432
  user: postgres
  password: pg_pwd
  database: target_db
  schema: public

python3 fgo2odb.py gen-config -o config.yml && vi config.yml
python3 fgo2odb.py typemap -s mongodb -t postgresql
python3 fgo2odb.py -c config.yml assess
python3 fgo2odb.py -c config.yml ddl -o preview.sql
# 嵌套对象可转 JSONB 类型
python3 fgo2odb.py -c config.yml migrate
python3 fgo2odb.py -c config.yml validate

5.8.10 特殊场景与高级用法（5 个场景）

序号	场景	说明	关键操作
56	白名单迁移（仅指定表）	生产库部分表迁移至测试环境	配置 `include_tables: [users, orders]`
57	黑名单迁移（排除指定表）	迁移全库但跳过日志/临时表	配置 `exclude_tables: [logs, tmp_*]`
58	增量断点续传迁移	大表迁移中断后恢复	直接重跑命令，已完成表自动跳过
59	自定义 WHERE 条件迁移	仅迁移近期数据，历史数据不迁	配置 `where_clauses`
60	表名重命名迁移	目标端使用不同表名	配置 `rename_tables`

场景 56：白名单迁移完整操作过程

# config.yml 中增加 include_tables 配置
include_tables:
  - users
  - orders
  - products

# 编辑 config.yml 加入 include_tables 白名单后执行
python3 fgo2odb.py -c config.yml migrate
# 日志: 开始数据迁移: 3 表（白名单过滤后）
python3 fgo2odb.py -c config.yml validate

场景 57：黑名单迁移完整操作过程

# config.yml 中增加 exclude_tables 配置
exclude_tables:
  - logs
  - tmp_*
  - audit_*

python3 fgo2odb.py -c config.yml migrate
# 日志: 跳过表 logs（黑名单匹配）
# 日志: 跳过表 tmp_20240101（黑名单通配符匹配）
python3 fgo2odb.py -c config.yml validate

场景 58：增量断点续传完整操作过程

# 第一次迁移（中途 Ctrl+C 中断）
python3 fgo2odb.py -c config.yml migrate
# 日志: [orders] 500000/8000000 行, 收到停止信号，已迁移 500000 行
# 日志: 表 users 已完成（断点保存）

# 第二次恢复迁移（直接重跑命令）
python3 fgo2odb.py -c config.yml migrate
# 日志: 表 users 已完成（断点），跳过
# 日志: 表 orders 从 500000 行继续迁移
# 日志: 全部迁移完成

# 第三步校验
python3 fgo2odb.py -c config.yml validate

场景 59：自定义 WHERE 条件迁移完整操作过程

# config.yml 中增加 where_clauses 配置
where_clauses:
  orders: "create_time >= '2024-01-01' AND status = 1"
  logs: "id > 1000000"
  user_sessions: "expire_time >= NOW()"

python3 fgo2odb.py -c config.yml migrate
# 日志: [orders] WHERE 过滤: create_time >= '2024-01-01' AND status = 1
# 日志: [logs] WHERE 过滤: id > 1000000
python3 fgo2odb.py -c config.yml validate

场景 60：表名重命名迁移完整操作过程

# config.yml 中增加 rename_tables 配置
rename_tables:
  users: t_users
  orders: t_orders
  products: t_products

python3 fgo2odb.py -c config.yml migrate
# 日志: 源表 users -> 目标表 t_users
# 日志: 源表 orders -> 目标表 t_orders
python3 fgo2odb.py -c config.yml validate

5.9 全场景快速操作参考

以下表格汇总所有迁移对的快速操作命令，可直接复制使用（需先编辑 config.yml 填入实际连接信息）：

源 -> 目标	模板文件	预览命令
MySQL -> PostgreSQL	`templates/mysql_to_postgresql.yml`	`python3 fgo2odb.py typemap -s mysql -t postgresql`
MySQL -> Oracle	`templates/mysql_to_oracle.yml`	`python3 fgo2odb.py typemap -s mysql -t oracle`
Oracle -> MySQL	`templates/oracle_to_mysql.yml`	`python3 fgo2odb.py typemap -s oracle -t mysql`
Oracle -> PostgreSQL	`templates/oracle_to_postgresql.yml`	`python3 fgo2odb.py typemap -s oracle -t postgresql`
PostgreSQL -> MySQL	`templates/postgresql_to_mysql.yml`	`python3 fgo2odb.py typemap -s postgresql -t mysql`
PostgreSQL -> Oracle	`templates/postgresql_to_oracle.yml`	`python3 fgo2odb.py typemap -s postgresql -t oracle`
SQL Server -> MySQL	`templates/sqlserver_to_mysql.yml`	`python3 fgo2odb.py typemap -s sqlserver -t mysql`
SQL Server -> PostgreSQL	`templates/sqlserver_to_postgresql.yml`	`python3 fgo2odb.py typemap -s sqlserver -t postgresql`
DB2 -> Oracle	`templates/db2_to_oracle.yml`	`python3 fgo2odb.py typemap -s db2 -t oracle`
DB2 -> PostgreSQL	`templates/db2_to_postgresql.yml`	`python3 fgo2odb.py typemap -s db2 -t postgresql`
MariaDB -> 任意	无模板，复用 MySQL 族	`python3 fgo2odb.py typemap -s mariadb -t <target>`
Percona -> 任意	无模板，复用 MySQL 族	`python3 fgo2odb.py typemap -s percona -t <target>`
Redis -> MongoDB	无模板，手写配置	`python3 fgo2odb.py typemap -s redis -t mongodb`
MongoDB -> MySQL	无模板，手写配置	`python3 fgo2odb.py typemap -s mongodb -t mysql`
任意 -> 任意	`python3 fgo2odb.py gen-config -o config.yml`	`python3 fgo2odb.py typemap -s <src> -t <tgt>`

六、常用问题与排查

6.1 连接问题

问题1：MySQL 连接报错 "Access denied for user"

排查：

确认用户名和密码正确
确认用户有远程访问权限：GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' IDENTIFIED BY 'password';
确认 MySQL 配置 bind-address 未限制为 127.0.0.1
确认防火墙未阻断端口

问题2：Oracle 连接报错 "ORA-12154: TNS:could not resolve the connect identifier"

排查：

确认 service_name 或 sid 配置正确
确认 Oracle 监听器已启动：lsnrctl status
确认 host:port 可达：tnsping <host>:<port>/<service_name>
FGO2ODB 使用 oracledb thin 模式，无需安装 Oracle Instant Client

问题3：SQL Server 连接报错 "IM002: Data source name not found"

排查：

确认已安装 ODBC 驱动：odbcinst -j
确认 FreeTDS 已安装并配置正确
确认连接串中 driver 参数正确（默认 "ODBC Driver 17 for SQL Server"）
可在 config.yml 的 source.extra.driver 或 target.extra.driver 中指定驱动名

问题4：DB2 连接报错 "SQL1598N" 或 clidriver 加载失败

排查：

确认 ibm_db 已正确安装：python3 -c "import ibm_db; print(ibm_db.__version__)"
确认 clidriver 库路径在 LD_LIBRARY_PATH 中
手动设置环境变量：export LD_LIBRARY_PATH=/opt/ibm/db2/clidriver/lib:$LD_LIBRARY_PATH

6.2 类型映射问题

问题5：Oracle NUMBER(10,2) 迁移到 MySQL 后变成 INT，小数丢失

排查：

FGO2ODB 已修复此问题，NUMBER(p,s) 带标度时会正确映射为 DECIMAL
确认使用最新版本的原生引擎：python3 fgo2odb.py version 查看 loaded=True
如仍异常，重新编译 C 引擎：cd native && make install
可用 typemap 命令预览映射结果：python3 fgo2odb.py typemap -s oracle -t mysql

问题6：PostgreSQL 的 jsonb 类型迁移到 MySQL 后变成 TEXT

排查：

这是预期行为，MySQL 不原生支持 jsonb，JSON 类型会映射为 MySQL 的 JSON 或 LONGTEXT
如需保留 JSON 语义，确保目标 MySQL 版本 >= 5.7.8（支持 JSON 类型）

问题7：SQL Server 的 datetime 迁移到 PostgreSQL 后时区不对

排查：

SQL Server datetime 无时区，PostgreSQL TIMESTAMP 也无时区，迁移是正确的
如需带时区，在目标端使用 TIMESTAMPTZ，需人工修改 DDL

6.3 数据迁移问题

问题8：迁移过程中报错 "Lost connection to MySQL server during query"

排查：

增大 connect_timeout 和 readTimeout/writeTimeout
增大 MySQL max_allowed_packet 和 wait_timeout
降低 batch_insert_size 以减小单个请求大小
增大 retry_times 以容忍短暂网络波动

问题9：迁移大表时内存持续增长导致 OOM

排查：

确认 streaming_cursor: true（流式游标，避免 fetchall）
降低 fetch_size（如从 10000 降至 5000）
降低 memory_limit_mb 和 memory_hard_limit_mb
降低 parallel_tables（减少并发内存占用）
确认 batch_insert_size 不要过大

问题10：COPY 模式报错 "invalid input syntax for type"

排查：

检查源端数据是否包含 Tab、换行等特殊字符（FGO2ODB 会自动转义）
检查是否有 NULL 值处理异常（COPY 模式使用 \N 标记 NULL）
尝试关闭 COPY 模式：bulk_insert: false，回退到 executemany

问题11：迁移中断后重启，部分表未跳过

排查：

确认 checkpoint_dir 配置正确且目录可写
检查断点文件是否存在：ls .checkpoint/<db_name>/
检查断点文件是否损坏：查看 .json 文件内容是否为有效 JSON
如断点损坏，程序会自动隔离到 .corrupt 后缀并重新迁移该表

6.4 字符编码问题

问题12：迁移后中文乱码

排查：

源端字符集设置正确：MySQL 使用 utf8mb4（非 utf8），Oracle 使用 AL32UTF8
目标端字符集设置正确：PostgreSQL 使用 UTF8，MySQL 使用 utf8mb4
检查 FGO2ODB 配置中 charset 参数
检查终端/客户端编码是否为 UTF-8

问题13：Emoji 表情（4字节字符）丢失

排查：

MySQL 必须使用 utf8mb4 而非 utf8（utf8 仅支持 3 字节）
确认源端和目标端均使用 utf8mb4
确认连接参数中 charset=utf8mb4

6.5 DDL 问题

问题14：建表报错 "ORA-00955: name is already used by an existing object"

排查：

Oracle 不支持 IF NOT EXISTS 语法，如目标表已存在会报错
迁移前先清理目标端：DROP TABLE <table_name> PURGE;
或在配置中设置 tableddl: false（仅迁数据，不建表）

问题15：索引创建报错 "syntax error"

排查：

查看日志中的具体 SQL 语句
部分源端索引定义（如函数索引、全文索引）可能无法自动转换
检查「待手工修复」清单，手动调整索引 DDL 后执行

6.6 性能问题

问题16：迁移速度慢

排查：

确认原生引擎已加载：python3 fgo2odb.py version 查看 loaded=True
增大 parallel_tables（多表并行）
增大 batch_insert_size 和 fetch_size
确认目标端 bulk_insert: true（启用 COPY/bulk）
检查网络带宽是否为瓶颈
检查源端和目标端 CPU/IO 是否打满

问题17：可视化控制台响应慢

排查：

降低 SSE 连接数（默认上限 100）
检查服务器 CPU 和内存是否充足
减少日志输出频率（提高 log_level 至 WARNING）

6.7 其他问题

问题18：原生引擎未加载（loaded=False）

排查：

确认 libfgo2odb.so 文件存在：ls fgo2odb/native/libfgo2odb.so
重新编译：cd native && make install
检查系统是否缺少 C 运行时库：ldd fgo2odb/native/libfgo2odb.so
未加载时程序自动回退到纯 Python 实现，功能正常但性能略低

问题19：SIGINT（Ctrl+C）后数据不一致

排查：

FGO2ODB 捕获 SIGINT 后会设置停止标志，等待当前批次写入完成后保存断点退出
如强制 kill（SIGKILL）可能导致当前批次数据不完整
重启后使用 validate 子命令校验数据一致性
如发现不一致，清理断点后重新迁移该表

问题20：模板配置文件不满足需求

排查：

templates/ 目录下提供了 10 套常用迁移对的配置模板
使用 gen-config 生成基础模板后自行修改
参考完整配置项说明，按需启用/禁用各功能模块

七、项目结构

FGO2ODB/
├── fgo2odb/                    # Python 主包
│   ├── __init__.py             # 包入口、版本、数据库族映射、版本矩阵
│   ├── __main__.py             # 模块入口
│   ├── cli.py                  # 命令行接口（10 个子命令）
│   ├── config.py               # 配置管理（YAML 加载）
│   ├── converter.py            # 迁移转换器（DDL+数据+索引+视图+函数编排）
│   ├── pipeline.py             # 数据迁移管道（流式+并行+重试+断点+内存保护）
│   ├── checkpoint.py           # 断点续传管理（崩溃安全）
│   ├── typemap.py              # 类型映射（纯 Python 实现）
│   ├── funcmap.py              # 函数映射（SQL 函数/语法重写）
│   ├── native.py               # 原生 C 引擎绑定 + Python 兜底
│   ├── assessor.py             # 迁移前评估
│   ├── report.py               # 迁移报告生成
│   ├── web.py                  # 可视化控制台（Flask）
│   ├── native/
│   │   └── libfgo2odb.so       # 原生 C 引擎（编译产物）
│   ├── source/                 # 源端连接器
│   │   ├── base.py             # 源端抽象基类
│   │   ├── mysql.py            # MySQL/MariaDB/Percona 源端
│   │   ├── postgresql.py       # PostgreSQL 源端
│   │   ├── oracle.py           # Oracle 源端
│   │   ├── db2.py              # IBM DB2 源端
│   │   ├── sqlserver.py       # MS SQL Server 源端
│   │   ├── redis.py            # Redis 源端
│   │   └── mongodb.py          # MongoDB 源端
│   └── target/                 # 目标端连接器
│       ├── base.py             # 目标端抽象基类
│       ├── mysql.py            # MySQL/MariaDB/Percona 目标端
│       ├── postgres.py         # PostgreSQL 目标端
│       ├── oracle.py           # Oracle 目标端
│       ├── db2.py              # IBM DB2 目标端
│       ├── sqlserver.py       # MS SQL Server 目标端
│       ├── redis.py            # Redis 目标端
│       └── mongodb.py          # MongoDB 目标端
├── native/                     # C 引擎源码
│   ├── fgconv.c                # C 实现（类型映射+函数映射+转义+哈希）
│   ├── fgconv.h                # C 头文件
│   ├── Makefile                # 编译脚本
│   └── libfgo2odb.so           # 编译产物
├── templates/                  # 配置模板
│   ├── mysql_to_postgresql.yml
│   ├── mysql_to_oracle.yml
│   ├── oracle_to_mysql.yml
│   ├── oracle_to_postgresql.yml
│   ├── postgresql_to_mysql.yml
│   ├── postgresql_to_oracle.yml
│   ├── sqlserver_to_mysql.yml
│   ├── sqlserver_to_postgresql.yml
│   ├── db2_to_oracle.yml
│   └── db2_to_postgresql.yml
├── docs/                      # 文档
│   └── README.md              # 本文档
├── config.example.yml         # 示例配置
├── requirements.txt           # 依赖清单
├── fgo2odb.py                 # CLI 入口
├── webctl.py                  # Web 控制台入口
└── Makefile                   # 项目编译脚本

八、配置参数详解

8.1 源端/目标端配置 (source / target)

参数	类型	默认值	说明
type	string	必填	数据库类型：oracle/mysql/mariadb/percona/postgresql/db2/sqlserver/redis/mongodb
host	string	127.0.0.1	数据库主机地址
port	int	3306	数据库端口
username	string		用户名
password	string		密码
database	string		数据库名（Redis/MongoDB 不需要）
schema	string		Schema 名（PostgreSQL 用 public，Oracle 用用户名，SQL Server 用 dbo）
sid	string		Oracle SID（与 service_name 二选一）
service_name	string		Oracle Service Name（与 sid 二选一）
charset	string	utf8mb4	字符集
connect_timeout	int	10	连接超时（秒）
ssl	dict		SSL 配置
extra	dict		扩展参数（如 SQL Server 的 driver）

8.2 转换选项 (conversion.options)

参数	类型	默认值	说明
tableddl	bool	true	迁移表结构 DDL
data	bool	true	迁移数据
indexes	bool	true	迁移索引
views	bool	false	迁移视图
functions	bool	false	迁移函数
procedures	bool	false	迁移存储过程
triggers	bool	false	迁移触发器
sequences	bool	false	迁移序列
foreign_keys	bool	false	迁移外键
validate_data	bool	true	数据校验
consistent_snapshot	bool	true	一致性快照读取

8.3 性能限制 (conversion.limits)

参数	类型	默认值	说明
concurrency	int	8	并发线程数
batch_insert_size	int	50000	批量插入行数
streaming_cursor	bool	true	流式游标
fetch_size	int	10000	每批 fetch 大小
checkpoint_dir	string	./.checkpoint	断点续传目录
memory_limit_mb	int	2048	内存软限（MB）
memory_hard_limit_mb	int	4096	内存硬限（MB）
retry_times	int	3	重试次数
retry_delay	float	5.0	重试退避基数（秒）
bulk_insert	bool	true	启用 COPY/bulk 模式
parallel_tables	int	4	多表并行度
large_table_threshold	int	1000000	大表阈值
huge_table_threshold	int	10000000	巨表阈值
per_table_timeout	int	86400	单表超时（秒）
global_timeout	int	432000	全局超时（秒）

8.4 表过滤与重命名

参数	类型	默认值	说明
include_tables	list	[]	白名单：仅迁移这些表
exclude_tables	list	[]	黑名单：跳过这些表
where_clauses	dict	{}	自定义 WHERE 条件（按表名）
rename_tables	dict	{}	表名重命名映射

WHERE 条件示例：

where_clauses:
  orders: "create_time >= '2024-01-01'"
  logs: "id > 1000000"

表名重命名示例：

rename_tables:
  users: t_users
  orders: t_orders

九、架构设计

9.1 整体架构

FGO2ODB 采用分层架构设计：

接口层：命令行（CLI）和 Web 控制台，提供用户交互入口。
编排层：Converter 负责协调 DDL 生成、数据迁移、索引/视图/函数迁移的执行顺序和错误隔离。
管道层：Pipeline 负责数据迁移的核心逻辑，包括流式读取、批量写入、并行调度、重试、断点续传、内存保护。
连接器层：Source/Target 连接器抽象了 9 种数据库的连接和操作细节，统一接口。
映射层：typemap/funcmap 提供类型和函数的映射规则，支持原生 C 引擎加速。
原生层：libfgo2odb.so 提供 C 语言实现的热路径加速。

9.2 数据流

源端数据库
    |
    v
SourceConnector.streaming_iter()   -- 流式游标逐批读取
    |
    v
Pipeline._migrate_with_copy_retry()  -- COPY 模式 / 批量模式
    |                                    |
    |  (COPY 模式)                         |  (批量模式)
    v                                    v
TargetConnector.copy_from_stream()   TargetConnector.safe_batch_insert()
    |                                    |
    +------------------------------------+
    |
    v
Checkpoint.save()                   -- 每批保存断点
    |
    v
TargetConnector.commit()           -- 提交事务

9.3 原生引擎

原生 C 引擎（libfgo2odb.so）提供以下热路径加速：

C 函数	功能
fg_engine_version	返回引擎版本
fg_type_map	类型映射（源类型+源族+目标族 -> 目标类型）
fg_quote_ident	标识符引号（按目标族）
fg_func_map	函数映射（源函数+源族+目标族 -> 目标函数）
fg_escape_value	COPY 值转义
fg_encode_copy_row	COPY 单行编码
fg_row_hash	行哈希校验

当 .so 文件缺失或加载失败时，native.py 中的纯 Python 兜底实现自动接管，保证功能不受影响。

十、开发与扩展

10.1 添加新的源端连接器

在 fgo2odb/source/ 下创建新文件，继承 SourceConnector。
实现所有抽象方法：connect、disconnect、list_tables、get_columns、get_indexes、get_table_rowcount、streaming_iter。
在 fgo2odb/source/__init__.py 的 get_source() 中注册。
在 fgo2odb/__init__.py 的 SOURCE_FAMILIES 中添加类型映射。

10.2 添加新的目标端连接器

在 fgo2odb/target/ 下创建新文件，继承 TargetConnector。
实现所有抽象方法：connect、disconnect、execute_ddl、batch_insert。
在 fgo2odb/target/__init__.py 的 get_target() 中注册。
在 fgo2odb/__init__.py 的 TARGET_FAMILIES 中添加类型映射。

10.3 扩展类型映射

在 fgo2odb/native.py 的 _PY_SOURCE_MAP、_PY_TARGET_MAP 和 native/fgconv.c 的对应表中添加新的类型映射条目，然后重新编译 C 引擎。

10.4 扩展函数映射

在 fgo2odb/funcmap.py 的 FUNC_MAP 字典和 native/fgconv.c 的函数映射表中添加新的函数映射条目。

10.5 编译原生引擎

cd native
make clean
make install    # 编译并安装到 fgo2odb/native/

十一、更新日志

v1.0.0

初始版本发布
支持 9 种国外数据库互通迁移（Oracle/MySQL/Percona/MariaDB/PostgreSQL/DB2/SQL Server/Redis/MongoDB）
原生 C 引擎加速类型映射与数据转义热路径
流式游标 + 多表并行 + COPY 批量导入，支撑 TB 级数据迁移
断点续传（崩溃安全）+ 指数退避重试 + 内存保护
全链路 UTF-8 强制编码，零乱码
基于 Flask 的可视化控制台，SSE 实时进度
10 套常用迁移对配置模板
修复 Oracle NUMBER(p,s) 带标度类型映射精度丢失问题
修复 SQL Server 行数统计系统视图名称错误
修复 Oracle/DB2 不支持 CREATE TABLE IF NOT EXISTS 语法问题
为 Redis/MongoDB/DB2 源端和目标端连接器添加 ping() 心跳检测

十二、联系方式

作者：风哥
官方网站 http://www.fgedu.net.cn
技术社区 http://www.itpux.com
数据库教程 https://edu.51cto.com/lecturer/8020378.html

posted @ 2026-09-02 12:44 风哥数据库教程阅读(9) 评论(0) 收藏举报

刷新页面返回顶部

风哥数据库教程

异构数据库迁移全过程-FGO2ODB工具

一、程序介绍

1.1 项目概述

1.2 作者信息

1.3 项目背景

二、功能特性

2.1 核心功能

2.2 高性能特性

2.3 高可靠性特性

2.4 零乱码特性

2.5 可视化控制台特性

三、支持环境

3.1 支持的数据库

3.2 支持的操作系统

3.3 支持的 CPU 架构

3.4 Python 环境要求

3.5 核心依赖包

3.6 系统级依赖

四、程序使用

4.1 安装

4.2 配置文件

4.3 命令行子命令

4.4 常用命令示例

4.5 可视化控制台

五、案例场景与操作过程

5.1 案例：MySQL 迁移至 PostgreSQL

5.2 案例：Oracle 迁移至 MySQL

5.3 案例：SQL Server 迁移至 PostgreSQL

5.4 案例：DB2 迁移至 Oracle

5.5 案例：Redis 迁移至 MongoDB

5.6 案例：TB 级大数据迁移

5.7 案例：使用可视化控制台迁移

5.8 全场景迁移矩阵与操作过程（60 个案例）

5.8.1 Oracle 作为源端（8 个场景）

5.8.2 MySQL 作为源端（8 个场景）

5.8.3 MariaDB 作为源端（7 个场景）

5.8.4 Percona 作为源端（7 个场景）

5.8.5 PostgreSQL 作为源端（7 个场景）

5.8.6 DB2 作为源端（7 个场景）

5.8.7 SQL Server 作为源端（7 个场景）

5.8.8 Redis 作为源端（2 个场景）

5.8.9 MongoDB 作为源端（2 个场景）

5.8.10 特殊场景与高级用法（5 个场景）

5.9 全场景快速操作参考

六、常用问题与排查

6.1 连接问题

6.2 类型映射问题

6.3 数据迁移问题

6.4 字符编码问题

6.5 DDL 问题

6.6 性能问题

6.7 其他问题

七、项目结构

八、配置参数详解

8.1 源端/目标端配置 (source / target)

8.2 转换选项 (conversion.options)

8.3 性能限制 (conversion.limits)

8.4 表过滤与重命名

九、架构设计

9.1 整体架构

9.2 数据流

9.3 原生引擎

十、开发与扩展

10.1 添加新的源端连接器

10.2 添加新的目标端连接器

10.3 扩展类型映射

10.4 扩展函数映射

10.5 编译原生引擎

十一、更新日志

v1.0.0

十二、联系方式

公告