Odoo Major Version Upgrade

Overview

The environment is based on templates:

• certified Nginx
• certified PostgreSQL
• Official Odoo Docker image

Redeploy of certified templates and the Odoo container is supported, but upgrading the Odoo application version itself is not automatic and must be performed manually according to official Odoo and OpenUpgrade documentation.

Official References

• Odoo Docker: https://github.com/odoo/docker/
• Docker Hub Odoo: https://hub.docker.com/_/odoo
• Odoo Docker Upgrade Guide: https://hub.docker.com/_/odoo#how-to-upgrade-this-image
• OpenUpgrade: https://oca.github.io/OpenUpgrade/

Available Upgrade Options

https://oca.github.io/OpenUpgrade/010_introduction.html#alternative-to-openupgrade

There are three possible approaches to upgrading Odoo between major versions:

1. Odoo S.A. Official Upgrade Service

Odoo provides an official upgrade service:
https://upgrade.odoo.com/

• Available only for Odoo Enterprise Edition
• Migration scripts are closed-source
• Requires an active Enterprise subscription

2. Manual Data Export and Import

This approach consists of:

• Exporting selected data (e.g. products, customers) from the old Odoo environment
• Importing the exported data into the new Odoo environment

Limitations:

• Only partial data is migrated
• No historical records (e.g. invoices, accounting history)
• No relationships between records are preserved
• Not suitable when full data continuity is required

3. OpenUpgrade (Selected Approach)

https://oca.github.io/OpenUpgrade/

OpenUpgrade is the official Open Source migration framework maintained by the Odoo Community Association (OCA).

• Supports full database migration
• Preserves data history and relational integrity
• Designed specifically for Odoo Community Edition
• Requires manual execution and validation

This approach was selected because it provides the most reliable way to fully migrate data while preserving business history, without requiring an Enterprise subscription.

ODOO Limitations for OpenUpgrade

• Only sequential major upgrades are supported (e.g. 15 → 16 → 17 → 18)
  https://oca.github.io/OpenUpgrade/010_introduction.html#migration-of-several-versions
• Migration scripts must be executed after each major version
• Logs and logic must be validated after each upgrade
• Downgrade is not supported (rollback only via full backup restore)

Recommended Upgrade Strategy

Deploy a new environment from MP with the next Odoo version, migrate data, test it, and then switch traffic.

Advantages

• No data loss
• Minimal downtime
• Old environment remains intact
• Instant rollback by switching traffic back

Step-by-Step Migration Flow (for example, from Odoo 17 → Odoo 18)

1. Backup data from the old environment (with Odoo 17)

Create a backup directory

mkdir -p /tmp/backup

Database backup

Get database credentials

grep -E "db_user|db_password|db_host|db_port" /etc/odoo/odoo.conf

List databases (get db_name for db_user)

psql -h db_host -p 5432 -U db_user -d postgres -c "\l"

The db_name is "test" for this example

Create compressed database dump

pg_dump -Fc -h db_host -p 5432 -U db_user -f /tmp/backup/db.dump db_name

Filesystem backup

Filestore

tar -czf /tmp/backup/filestore.tar.gz /var/lib/odoo/filestore

Extra addons

tar -czf /tmp/backup/extra_addons.tar.gz /mnt/extra-addons

2. Create a new environment and restore Data on the New Environment

Create the new environment from MP with the next major Odoo version (Odoo 18 in our example)

Create a backup directory

mkdir -p /tmp/backup

Mount /tmp/backup between old and new envs

On the new env

Stop Odoo

systemctl stop odoo

Verify process stopped

ps aux | grep odoo

Restore filestore

rm -rf /var/lib/odoo/filestore/*;
tar -xzf /tmp/backup/filestore.tar.gz -C /;
chown -R odoo:odoo /var/lib/odoo;

Restore database

Verify filestore name (MUST match DB name, for example, "test")

ls -la /var/lib/odoo/filestore

The odoo_db should be "test" too

Get database credentials on the new environment

grep -E "db_user|db_password|db_host|db_port" /etc/odoo/odoo.conf

Drop existing database (if exists)

dropdb -h db_host -p 5432 -U db_user odoo_db

Create database

createdb -h db_host -p 5432 -U db_user odoo_db

Restore dump

pg_restore --no-owner --no-acl -h db_host -p 5432 -U db_user -d odoo_db /tmp/backup/db.dump

3. Install OpenUpgrade (Odoo 18)

Download OpenUpgrade (version 18.0)

curl -L https://github.com/OCA/OpenUpgrade/archive/refs/heads/18.0.zip -o /tmp/openupgrade.zip

Extract and prepare

unzip /tmp/openupgrade.zip -d /opt;
mv /opt/OpenUpgrade-18.0 /opt/openupgrade;

Install dependencies

apt update && apt install -y git

Install openupgradelib

pip3 install git+https://github.com/OCA/openupgradelib.git --break-system-packages

4. Run OpenUpgrade Migration (17 → 18)

odoo -c /etc/odoo/odoo.conf -d odoo_db --addons-path=/usr/lib/python3/dist-packages/odoo/addons,/opt/openupgrade --upgrade-path=/opt/openupgrade/openupgrade_scripts/scripts -u all --stop-after-init --log-level=info

5. Handling Expected Migration Errors

During migration, some standard modules may fail due to removed fields or changed views.
Correct handling:

• Temporarily uninstall the problematic module

• Continue migration

• Re-enable or refactor later if required

This behaviour is expected during major Odoo upgrades and documented in OpenUpgrade practices.

6. Run Odoo after migration

systemctl start odoo