iDempiere数据库升级指南：从migration脚本看跨版本平滑迁移全流程

iDempiere数据库升级指南：从migration脚本看跨版本平滑迁移全流程

【免费下载链接】idempiereiDempiere. Community Powered Enterprise. Full Open Source Business Suite ERP/CRM/MFG/SCM/POS项目地址: https://gitcode.com/gh_mirrors/id/idempiere

iDempiere 数据库升级并不复杂——它的核心是一套按版本归档的 migration SQL 脚本和一条同步命令。iDempiere 是一套完整的开源企业级业务套件（ERP/CRM/MFG/SCM/POS），元数据全部存放在数据库中，因此版本升级的本质就是"按时间顺序补齐数据库脚本"。本文将带你完整走一遍 iDempiere 数据库升级流程，从脚本目录结构讲起，到一键同步与生产监控方案，帮助你安全地完成跨版本平滑迁移。

为什么 iDempiere 的升级是"补脚本"

iDempiere 采用元数据驱动架构：窗口、表格、字段、流程等 UI 与业务定义都以数据形式存放在AD_Window、AD_Table、AD_Column等字典表中。所以：

• 升级应用代码的同时，必须同步升级数据库里的元数据和业务表结构；
• 官方为每个大版本提供成对的postgresql/与oracle/脚本，升级 = 把尚未执行的脚本按时间戳顺序补跑一遍；
• 每个脚本执行后都会调用register_migration_script()函数把文件名登记到AD_MigrationScript表，系统借此判断"哪些脚本还没跑"。

一个典型的脚本开头（migration/iD14/postgresql/202511201738_IDEMPIERE-6733.sql）就是先登记、再改表、再同步字典数据，三步一体：

SELECT register_migration_script('202511201738_IDEMPIERE-6733.sql') FROM dual; ALTER TABLE T_ReportStatement ADD COLUMN Account_ID NUMERIC(10) DEFAULT '0'; INSERT INTO AD_Column (...) VALUES (...);

migration 目录结构：一眼看懂版本迁移路线

所有迁移脚本集中在仓库根目录的migration/下，每个子文件夹对应一个历史版本，按字母序即升级顺序：

版本目录	说明
migration/i4.1~migration/iD9	2008–2021 年间的历史版本脚本（4.1 起步）
migration/iD10~migration/iD14	近年主版本，如 iD14 是最新的 31 个脚本
local_sql/	你自建的安装级定制脚本（见下文）
processes_post_migration/	所有脚本跑完后统一执行的收尾脚本
zip_2pack/	存放自建的 2Pack 元数据包 zip 文件

每个版本目录内部固定分postgresql/和oracle/两个子目录，脚本命名约定为：

yyyymmddHHMM_信息描述.sql（时间戳前缀 + 说明，例如202511201738_IDEMPIERE-6733.sql）

时间戳前缀决定了执行顺序——系统按文件名排序依次应用，与所在文件夹无关，这正是"平滑迁移"的关键设计。

一键升级：用 SyncDB 同步数据库

开发环境：RUN_SyncDBDev.sh

如果你在 Eclipse 中用 install 应用初始化过数据库，仓库根目录的 RUN_SyncDBDev.sh 会直接从idempiere.properties读取连接信息并执行同步：

bash RUN_SyncDBDev.sh # 或指定属性文件和迁移目录 bash RUN_SyncDBDev.sh adempiere.properties migration/iD14

生产/服务器环境：utils.unix 工具集

服务器安装版使用org.adempiere.server-feature/utils.unix/下的工具链：RUN_SyncDB.sh→ 按数据库类型调用postgresql/SyncDB.sh或oracle/SyncDB.sh。核心机制非常直白（见utils.unix/postgresql/SyncDB.sh）：

1. 查询AD_MigrationScript表，得到已执行脚本清单；
2. 扫描migration/目录下当前数据库类型的.sql文件，得到全部脚本清单；
3. 两者求差集，得到待执行脚本，按文件名排序逐个用psql执行；
4. 任一脚本输出中检测到ERROR:/FATAL:等错误标志时立即停止，并把每个脚本的完整输出留存在/tmp/SyncDB_out_*/供排查；
5. 全部成功后，追加执行processes_post_migration/里的收尾脚本。

已同步时会看到友好提示：Database is already in sync - no scripts pending to apply，重复执行完全安全（幂等）。

生产级升级：MonitoredSyncDB 监控模式

正式环境推荐用RUN_MonitoredSyncDB.sh（底层是utils.unix/postgresql/MonitoredSyncDB.sh），它比普通同步多了三样保障：

• 错误留痕：脚本报错时自动把AD_MigrationScript中该记录标记为ER（Error），并保存脚本输出，方便定位；
• 修复包机制（.fix）：供应商/社区可发布修复脚本，命名与原脚本一致但后缀改为.001.fix、.002.fix……放入同一目录即可，程序会自动查找并应用修复，无需手工干预；
• 邮件告警：若AD_System表配置了 SupportEMail 且系统有 sendmail，出错时自动把错误详情发邮件给支持方。

官方建议的流程是：先在测试/预发环境跑一遍→ 集成修复脚本 → 再在生产环境执行，届时修复会被自动带上。

加入自己的定制脚本：local_sql 规范

如果升级时还需要执行安装级定制改动（比如自建字段、视图），把脚本放进migration/local_sql/，规则见该目录的 README.txt：

• 目录内同样分postgresql/和oracle/；
• 命名沿用yyyymmddHHMM_说明.sql约定；
• 它在所有版本目录（i4.1 … iD14）之后、收尾脚本之前被执行。

类似地，自建的元数据包可放入migration/zip_2pack/，命名为yyyymmddHHMM_客户端代码_说明.zip，由org.adempiere.plugin.utils插件在服务器启动后自动应用。

升级前检查清单与常见坑 📋

步骤	要点
1️⃣ 备份数据库	升级前执行一次完整备份（utils 提供RUN_DBExport.sh/RUN_DBRestore.sh工具）
2️⃣ 测试环境先行	用 MonitoredSyncDB 先跑通全量迁移
3️⃣ 版本按序补齐	从 i4.1 一路到 iD14，脚本必须按时间戳顺序执行，不要手工乱序补跑
4️⃣ 注意数据库方言	postgresql 与 oracle 脚本不可混用，脚本按AD_Client/方言独立维护
5️⃣ 检查错误输出	失败时查看/tmp/SyncDB_out_*/下的 .out 日志，按提示手工修复后重跑即可续传
6️⃣ 收尾脚本别漏	processes_post_migration只在有脚本被应用时才执行，手工跳步容易遗漏

💡 小贴士：连接信息模板可参考仓库根目录的adempiere-local-template.properties，把Connection一行的数据库主机、端口、库名、账号改好即可复用给同步脚本。

小结

iDempiere 的数据库升级可以归纳为三句话：

1. 脚本按版本目录 + 时间戳命名归档，天然形成可追溯的迁移流水线；
2. SyncDB 通过AD_MigrationScript表做增量对比，一键补跑、幂等安全；
3. MonitoredSyncDB + .fix 修复包 + 邮件告警，为生产环境提供完整的出错兜底方案。

掌握这套机制后，无论是从 i9 跨到 iD14，还是日常跟进小版本补丁，你都能在测试环境验证后，一条命令完成生产数据库的平滑迁移。

【免费下载链接】idempiereiDempiere. Community Powered Enterprise. Full Open Source Business Suite ERP/CRM/MFG/SCM/POS项目地址: https://gitcode.com/gh_mirrors/id/idempiere