Odoo 19 中升级（迁移）脚本的使用方法

Odoo 19 中升级（迁移）脚本的使用方法

将 Odoo 系统升级到新版本时，仅更新代码是远远不够的。模型、字段及业务逻辑的变更，往往需要对现有数据进行调整，使其适配新的结构。这时，升级（迁移）脚本就成了必不可少的工具。

在 Odoo 19 中，升级脚本提供了一套结构化的方式，用于在模块升级期间转换和对齐数据。它们能确保系统在应用变更后依旧正常运行。

本文将讲解升级脚本的工作原理、结构组织，以及如何在实际业务场景中高效实施。

---

什么是 Odoo 中的升级脚本？

升级脚本是在模块升级时自动运行的 Python 文件。其作用是修改数据库中的现有记录，使其与更新后的代码保持兼容。

常见用途包括：

• 结构变更后调整数据
• 重命名字段或模型
• 重新计算存储字段值
• 清理过时或不一致的数据

无需在升级后手动修复数据，这些脚本可以可控、可重复地自动完成处理。

---

升级脚本的重要性

版本升级过程中，系统结构常会发生以下变化：

• 字段可能被重命名或移除
• 模型可能被合并或重构
• 业务逻辑可能发生变更

若无合适的数据迁移，可能出现：

• 界面报错
• 数据不一致
• 功能无法正常使用

升级脚本可以保障：

• 版本间平滑过渡
• 数据完整性得以保留
• 与更新后的模块兼容

尤其对于自定义模块，Odoo 不会自动处理迁移，升级脚本就更为重要。

---

升级脚本的目录结构

升级脚本必须在模块目录内遵循固定结构：

your_module/
 └── migrations/
     └── 19.0.1.0/
         ├── pre-migration.py
         └── post-migration.py

说明：

• migrations/：存放所有升级脚本
• 版本文件夹：与模块版本号一致
• pre-migration.py：在模块更新之前执行
• post-migration.py：在模块更新之后执行

版本文件夹名称决定了脚本的执行时机。

---

迁移脚本类型

1. 预迁移脚本（Pre-Migration）

此类脚本在模块升级之前运行。

用途：

• 准备或清理数据
• 重命名字段或数据表
• 确保与新结构兼容

示例：

def migrate(cr, version):
    cr.execute("""
        UPDATE res_partner
        SET name = 'Default Name'
        WHERE name IS NULL
    """)

2. 后迁移脚本（Post-Migration）

此类脚本在模块升级完成后运行。

用途：

• 转换数据
• 填充新字段
• 重新计算字段值

示例：

def migrate(cr, version):
    cr.execute("""
        UPDATE sale_order
        SET note = 'Updated during migration'
        WHERE note IS NULL
    """)

---

常见应用场景

1. 重命名字段

当代码中的字段名称变更时，数据库也必须同步修改。

示例场景：
customer_name → partner_name

若无迁移脚本，数据将会丢失或无法访问。

2. 在模型间迁移数据

因结构调整需要转移数据时：

def migrate(cr, version):
    cr.execute("""
        UPDATE new_model nm
        SET value = old_model.value
        FROM old_model
        WHERE old_model.id = nm.old_id
    """)

3. 重新计算存储字段

若计算字段的逻辑发生变化，原有值可能失效。迁移脚本可触发更新，保证数据一致。

4. 清理废弃数据

升级脚本可删除：

• 已弃用的记录
• 无效配置
• 未使用的关联数据

以此保持数据库整洁高效。

---

编写升级脚本

所有升级脚本必须定义 migrate 函数：

def migrate(cr, version):
    # cr：数据库游标
    # version：上一个模块版本
    cr.execute("UPDATE res_partner SET active = TRUE WHERE active IS NULL")

要点：

• 使用数据库游标（cr）
• 执行 SQL 或受控操作
• 在模块升级时自动运行

---

升级脚本何时执行？

升级脚本在以下情况触发：

• 使用 -u module_name 参数升级模块
• 数据库迁移至新版本

脚本会按照模块中定义的版本文件夹顺序依次执行。

---

编写升级脚本的最佳实践

1. 务必备份数据库

   执行任何迁移操作前，确保已完成完整备份。

2. 在测试环境验证

   切勿直接在生产环境运行未测试的迁移脚本。

3. 保证脚本可安全重复执行

   确保脚本多次运行不会报错或产生重复数据。

4. 大数据更新优先使用 SQL

   出于性能考虑，批量操作使用 SQL 通常比 ORM 更高效。

5. 尽量避免使用类似 sudo 的逻辑

   除非必要，否则不要绕过权限规则。

6. 谨慎处理依赖关系

   修改数据前，确保相关模型与字段已存在。

---

需避免的常见错误

• 自定义模块忽略迁移脚本
• 编写脚本后不做测试
• 无备份情况下执行不可逆操作
• 忽略数据依赖关系
• 在大数据集上使用低效查询语句

---

总结

Odoo 19 中的升级脚本对保障系统更新后数据的一致性与可用性至关重要。它们可以安全地处理模型结构、业务逻辑及关联关系的变更。

通过规范组织脚本、选择合适的迁移阶段，并遵循最佳实践，开发者可以避开常见问题，实现平滑升级。

完善的迁移流程是任何 Odoo 实施项目保持稳定可靠的关键。

正确实施升级脚本，您可以放心地管理 Odoo 升级，同时保障数据完整性与系统稳定性。