Odoo OpenUpgrade Library

Common errors

• ImportError: No module named openupgradelib.openupgrade_tools

  cause This error often occurs in older Odoo migration setups (e.g., Odoo 7.0/8.0) when `openupgradelib` or `OpenUpgrade` migration scripts are incorrectly installed or their versions are mismatched.
  fix Ensure `openupgradelib` is correctly installed via pip in the Odoo environment. For complex setups or older Odoo versions, verify that the `OpenUpgrade` framework (which uses `openupgradelib`) and `openupgradelib` itself are compatible versions and accessible on the Python path. Using `pip install git+https://github.com/OCA/openupgradelib.git@master#egg=openupgradelib` for the library and cloning the corresponding OpenUpgrade branch for migration scripts often resolves such issues.

• TypeError: migrate() got an unexpected keyword argument 'use_env'

  cause This error typically arises when the installed `openupgradelib` version is out of sync with the `OpenUpgrade` (migration scripts) codebase, specifically when a newer `OpenUpgrade` expects a `migrate` function signature that the installed `openupgradelib` version doesn't support.
  fix Ensure that the `openupgradelib` installed matches the version expected by the `OpenUpgrade` migration scripts you are using. It's often recommended to install `openupgradelib` directly from the `master` branch of its GitHub repository using `pip install git+https://github.com/OCA/openupgradelib.git@master#egg=openupgradelib` to ensure the latest compatible version.

• KeyError: 'pkg' (or similar error when accessing module name in migration)

  cause In `openupgradelib` versions prior to 3.13, the library attempted to retrieve the module name from `frame.locals['pkg'].name`. Recent changes in Odoo's core (specifically related to how upgrade scripts are run and arguments are passed) caused the `'pkg'` key to become unavailable.
  fix Upgrade `openupgradelib` to version 3.13 or newer, which includes a fix for this issue (commit OCA/openupgradelib#410). This version correctly accesses the module name from the `addon` parameter.

Warnings

• deprecated The `norecompute` argument for `merge_records` was deprecated in Odoo v17 and removed from `openupgradelib` version 3.11.0. Using it will lead to errors in newer Odoo versions.
  Fix: Remove the `norecompute` argument when calling `openupgrade.merge_records`. Review the logic to ensure computed fields are handled correctly post-merge.
• breaking Direct Python 2 support has been dropped. Installing `openupgradelib` (especially recent versions) in an Odoo environment running Python 2 will result in `SyntaxError` or other compatibility issues.
  Fix: Ensure your Odoo instance is running on Python 3 when using recent `openupgradelib` versions. If migrating older Odoo versions that require Python 2, use an older `openupgradelib` version known to be compatible (e.g., <=1.x.x).
• gotcha When developing custom Odoo modules that utilize `openupgradelib` for their own migrations, it is crucial to declare `openupgradelib` in the `external_dependencies` section of your Odoo module's `__manifest__.py` file. Failure to do so can lead to `ModuleNotFoundError` in environments that auto-install Python dependencies based on Odoo manifests.
  Fix: Add `"openupgradelib"` to the `python` list in the `external_dependencies` dictionary within your `__manifest__.py`: `'external_dependencies': {'python': ['openupgradelib']},`
• gotcha The OpenUpgrade project, and thus `openupgradelib`, is designed for sequential major version upgrades (e.g., Odoo 15.0 to 16.0, then 16.0 to 17.0). Skipping intermediate major Odoo versions (e.g., directly from 15.0 to 17.0) is not officially supported and will likely result in data inconsistencies or migration failures.
  Fix: Plan your Odoo migrations as a series of sequential upgrades, migrating one major version at a time, ensuring each step completes successfully before proceeding to the next.

Install

• pip install openupgradelib Stable release
• pip install git+https://github.com/OCA/openupgradelib.git@master#egg=openupgradelib Latest development version (recommended for migrations)

Imports

• openupgrade
  wrong:

  from openupgradelib.openupgrade_tools import ...

  correct:

  from openupgradelib import openupgrade

  The primary API is exposed through the `openupgrade` module directly under `openupgradelib`. Older or internal modules like `openupgrade_tools` should not be imported directly.

Quickstart

To use `openupgradelib`, create a Python file within your Odoo module's `migrations/<ODOO_VERSION>/` directory (e.g., `my_module/migrations/16.0.1.0/pre-migrate.py`). Decorate your `migrate` function with `@openupgrade.migrate()` to ensure it runs correctly within the OpenUpgrade framework, providing access to the `env` (Odoo environment) and `version` (migration version) objects. This example demonstrates running a logged SQL query and adding a new column, two common migration tasks.

import logging
from openupgradelib import openupgrade

_logger = logging.getLogger(__name__)

@openupgrade.migrate()
def migrate(env, version):
    _logger.info("Starting migration script for version %s", version)

    # Example 1: Execute a raw SQL query with logging
    openupgrade.logged_query(
        env.cr,
        "UPDATE res_users SET company_id = 1 WHERE company_id IS NULL",
        "Setting default company for users without one"
    )

    # Example 2: Add a new column to an existing model
    # This is typically done in a 'pre-migrate' script to prepare the database schema
    openupgrade.add_columns(
        env,
        [
            ('res.partner', 'x_migrated_status', 'char', None, 'res_partner', 'varchar(64)', False),
        ]
    )

    # Note: After adding columns or fields, Odoo's ORM cache often needs to be cleared or re-initialized
    # For schema changes, _auto_init() or _fields.clear() might be needed for ORM awareness in later steps.
    # env['res.partner']._fields.clear()
    # env.cr.commit() # Commit changes if needed before further ORM operations

    _logger.info("Migration script completed.")