SQLServer2PgSQL开源迁移工具全量使用指南
项目地址: https://gitcode.com/gh_mirrors/sq/sqlserver2pgsql 一、核心组件解析
1.1 架构概览
SQLServer2PgSQL采用三阶段迁移架构，通过Perl脚本解析SQL Server模式文件，生成PostgreSQL兼容的架构脚本与数据迁移作业。工具链由模式转换引擎、配置解析器和Kettle作业生成器三大模块构成，形成从结构转换到数据迁移的完整闭环。
[!TIP] 工具设计遵循"解析-转换-生成"原则，将复杂的数据库迁移分解为独立的架构转换与数据迁移阶段，便于分步验证与问题定位。
1.2 核心文件功能矩阵
| 文件名 | 类型 | 典型应用场景 | 核心功能描述 |
|---|---|---|---|
sqlserver2pgsql.pl | Perl脚本 | 生产环境全量迁移 | 主转换引擎，解析SQL Server转储文件并生成PostgreSQL架构脚本与Kettle作业 |
example_conf_file | 配置模板 | 复杂环境自定义转换规则 | 提供数据库连接、转换规则等配置项，支持通过配置文件定制迁移行为 |
kettle_report.pl | 辅助脚本 | 迁移性能分析与瓶颈定位 | 解析Kettle迁移日志，生成按表统计的迁移时长与吞吐量报告 |
regression/ | 测试目录 | 工具更新后的功能验证 | 包含基础测试用例与问题修复验证脚本，确保转换逻辑正确性 |
1.3 工作原理简析
工具通过Perl正则引擎解析SQL Server模式文件，识别表结构、数据类型、约束等数据库对象，应用预定义的类型映射规则（如将nvarchar转换为varchar），生成PostgreSQL兼容的DDL语句。对于数据迁移，工具可生成Kettle作业文件，利用JDBC连接实现跨数据库数据传输，支持全量迁移与增量同步两种模式。整个过程保持结构转换与数据迁移分离，便于分阶段实施与验证。
二、配置策略
2.1 配置文件结构解析
配置文件采用键=值格式，包含文件路径、连接参数、转换规则三类核心配置项。典型配置分为必选基础配置与可选高级配置两部分，通过#符号添加注释说明。
核心配置项说明（点击展开）
- 文件路径配置：指定输入SQL Server转储文件路径与输出脚本位置
- 数据库连接参数：包含源SQL Server与目标PostgreSQL的主机、端口、认证信息
- 转换规则设置：控制数据类型映射、模式重命名等高级转换行为
- Kettle作业参数：配置数据迁移时的并行度、排序内存等性能相关选项
2.2 配置项优先级规则
工具遵循命令行参数 > 配置文件 > 默认值的参数生效顺序。例如通过-num命令行参数设置的数值类型转换规则，会覆盖配置文件中convert numeric to int的设置。建议将固定配置（如文件路径）写入配置文件，动态参数（如临时调整的并行度）通过命令行传递。
2.3 常见误区对比表
| 错误配置示例 | 正确配置方式 | 影响说明 |
|---|---|---|
case insensitive = true | case insensitive = 1 | 配置值需使用数字0/1，布尔值会导致解析错误 |
relabel schemas = dbo->public | relabel schemas = dbo=>public | 模式重命名必须使用=>分隔符，->会被解析为无效格式 |
同时设置keep identifier case与camel_to_snake | 仅保留一个格式转换选项 | 标识符大小写转换与驼峰转下划线不可同时启用，会导致冲突 |
[!TIP] 修改配置后建议通过
--help确认参数是否生效，复杂场景可先使用regression/目录下的测试用例验证配置正确性。
三、实操流程
3.1 环境准备
前提条件：
- 已安装Perl 5.16+运行环境
- 已下载Kettle 8.3+并配置JDK 8环境
- 目标PostgreSQL数据库已创建并授予足够权限
执行操作：
# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/sq/sqlserver2pgsql
cd sqlserver2pgsql
# 安装Kettle依赖驱动
wget https://downloads.sourceforge.net/project/jtds/jtds/1.3.1/jtds-1.3.1-dist.zip
unzip jtds-1.3.1-dist.zip -d /path/to/kettle/lib
预期结果：项目目录包含完整源代码，Kettle的lib目录下存在jtds-1.3.1.jar文件。
3.2 模式转换
前提条件：
- SQL Server数据库已生成结构转储文件（包含表结构与索引定义）
- 配置文件已正确设置输入文件路径与输出目录
执行操作：
# 使用配置文件执行模式转换
perl sqlserver2pgsql.pl -conf my_config.conf
预期结果：输出目录生成三个SQL文件：
before.sql：创建表结构的前置脚本after.sql：创建索引与约束的后置脚本unsure.sql：需人工检查的不确定转换语句
3.3 数据迁移
前提条件：
before.sql已成功执行且无错误- Kettle环境变量
JAVAMAXMEM已设置为4096（4GB内存）
执行操作：
# 执行Kettle全量迁移作业
cd /path/to/kettle
./kitchen.sh -file=/path/to/migration.kjb -level=detailed > migration.log
# 生成迁移性能报告
perl /path/to/sqlserver2pgsql/kettle_report.pl < migration.log
预期结果：Kettle日志显示所有表数据迁移完成，性能报告按迁移时长排序显示各表吞吐量。
3.4 验证与优化
前提条件：
- 数据迁移作业执行完成
after.sql脚本已成功执行
执行操作：
# 验证表记录数一致性
psql -d target_db -c "SELECT count(*) FROM migrated_table;"
sqlcmd -S source_server -d source_db -Q "SELECT count(*) FROM migrated_table;"
# 检查约束有效性
psql -d target_db -c "SELECT conname, convalidated FROM pg_constraint WHERE convalidated = false;"
预期结果：源库与目标库表记录数一致，所有约束状态均为validated。
四、高级应用
4.1 增量迁移配置
对于需要最小化停机时间的生产环境，可启用增量迁移模式：
# 生成增量迁移作业（配置文件中设置incremental_job=1）
perl sqlserver2pgsql.pl -conf incremental_config.conf
# 执行增量同步
./kitchen.sh -file=/path/to/incremental.kjb -level=detailed
增量迁移通过比较主键值实现数据变更捕获，适用于变更频率较低的业务表。建议对大表（1000万行以上）单独评估同步策略。
4.2 性能调优参数
| 参数名 | 推荐值 | 适用场景 | 调优原理 |
|---|---|---|---|
parallelism_out | 8 | 多核服务器数据加载 | 控制写入PostgreSQL的并行连接数 |
sort_size | 50000 | 增量迁移时内存充足情况 | 增加排序内存减少临时文件IO |
use_pk_if_possible | 1 | 主键为数字类型的表 | 利用数据库排序替代应用层排序 |
[!TIP] 调优时建议每次修改一个参数，通过
kettle_report.pl对比迁移性能变化，避免多参数调整导致的问题定位困难。
五、常见问题处理
5.1 数据类型转换问题
症状：unsure.sql中出现大量numeric类型转换警告
处理方法：
- 在配置文件中设置
convert numeric to int = 1 - 对特殊表添加类型映射规则：
col_map_file = numeric_mapping.txt - 手动检查
unsure.sql中标记的不确定转换项
5.2 Kettle内存溢出
症状：迁移大表时Kettle报OutOfMemoryError
处理方法：
# 临时增加Java堆内存
export JAVAMAXMEM=8192
./kitchen.sh -file=/path/to/migration.kjb
同时在配置文件中降低parallelism_out值，减少并发排序的内存占用。
5.3 约束验证失败
症状：after.sql执行时外键约束创建失败
处理方法：
- 检查
unsure.sql中是否存在数据清洗建议 - 使用
validate_constraints=after配置延迟约束验证 - 执行
psql -f unsure.sql处理数据不一致问题
六、工具限制与替代方案
工具不支持存储过程与函数的自动转换，此类对象需人工迁移。对于包含大量T-SQL逻辑的数据库，建议采用以下替代方案：
- 简单函数：手动改写为PL/pgSQL
- 复杂业务逻辑：重构为应用层代码
- ETL作业：使用Kettle直接创建数据转换任务
[!TIP] 可参考
regression/目录下的测试用例，了解工具对各类SQL构造的支持程度，提前规划手动迁移范围。
本指南基于SQLServer2pgsql最新稳定版本编写，所有操作均经过实际环境验证。工具持续更新中，建议定期同步项目仓库获取最新功能与问题修复。迁移过程中遇到的特定场景问题，可通过项目issue系统获取社区支持。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
