Upgrade Odoo to a new major version

Introduction

Every year around November, Odoo releases a shiny new version with tons of new features called a “major version”. Aside from new features, a lot of improvements happen under the hood and cause significant changes in the database structure. This makes it difficult for Odoo to release a simple “Update”-button to upgrade your Odoo instance to a newer major version.

Fortunately, whether you are using Odoo Community or Odoo Enterprise, there are upgrade scripts to upgrade your database to a newer version.

This guide will focus on how to upgrade your Odoo Enterprise instance using Odoo’s Upgrade Service.

Odoo Upgrade Service vs OCA OpenUpgrade

Odoo Upgrade Service for Enterprise users

Odoo has an Odoo Upgrade Service for Enterprise customers to upgrade your current database structure to the newer version (excluding any customizations).

If the automated upgrade fails or your situation is more involved, Enterprise customers can also use Option 2 on the Odoo on-premise upgrade page to request a premium upgrade directly from Odoo. As an active Enterprise subscriber you are eligible for this premium support, so contact Odoo first whenever the standard upgrade does not complete cleanly.

OCA OpenUpgrade for Odoo Open Source users

OCA, the Odoo Community Association, is a vibrant community that releases Odoo upgrade scripts for Odoo Open Source. You can check their documentation page to see if the upgrade scripts are ready. There are also several ways to contribute to the open source project.

Requirements

SSH Access to your Odoo server provisioned by Cloudpepper (How to generate and install an SSH key with Termius)
Odoo Production instance with Enterprise active (How to enable Enterprise)
Odoo Upgrade Service ready for production
A Cloudpepper-provisioned server for the target Odoo major version

FAQ

When is it safe to upgrade to a newer version?

It is recommended to delay upgrading for at least 6 months following a major release. This waiting period ensures that any critical bugs are addressed through stability patches.

When is Odoo Upgrade Service ready for production?

The Odoo upgrade scripts need to be released and ready for production, which can take up to 3-4 months after the release of a major version. The script for test databases is usually ready almost immediately after a major release. You can check the Odoo Upgrade Service website to see if the upgrade scripts are available.

Any alternative to using Upgrade Scripts?

Upgrading your Odoo database can be a tedious process and perhaps you do not need to upgrade all your existing data to the newer Odoo version.

Instead of using a script to upgrade your database, you can simply export your Master Data: Partners (Customers and Suppliers), Products, Categories, Tax configuration, Units of Measure, Users and other static data, and import the data using the import functionality of your newer Odoo instance. Do note that in this case you won’t have all relational documents like vendor bills, purchase and sales orders, accounting entries, etc.

What about upgrading custom modules and third-party apps?

The Odoo Upgrade Service only upgrades standard Odoo apps, database structures, and Odoo Studio customizations. It does not upgrade the source code of custom modules or third-party apps. Before upgrading, you must ensure that all your custom and third-party modules have a version that is compatible with the target Odoo release.

Step 1. Upload your database to the Odoo upgrade service

Running the following command from your SSH console will upload your database to the Odoo upgrade service for testing:

cd /tmp
sudo -u odoo bash -c "python3 <(curl -s https://upgrade.odoo.com/upgrade) test -d <your db name> -t <target version>"

Removing the keyword “test” will request a production-ready database. You can find your db name under Odoo specifics on your Instance details in your Cloudpepper dashboard.

Odoo will send status updates to your Odoo contracts email address, but make sure to check the output from the command and save the value of the “The secret token is …” line when it appears, just in case.

Step 2. Restore your upgraded database as an Odoo instance

The upgraded package you download from Odoo contains a dump.sql file with the upgraded database. This file is essential for Cloudpepper to restore the database on the platform without it, moving forward to the further steps will cause importing errors.

Once you receive the download link of your upgraded database, import it as a backup into Cloudpepper and restore it to a Cloudpepper-provisioned server that supports the newer Odoo version.

In most cases this means provisioning a new server first. A Cloudpepper server is tied to one Odoo major version, so you cannot restore an upgraded Odoo database onto a server that only supports the previous version.

Step 3. Copying your filestore

The upgrade you download from Odoo doesn’t contain the original filestore, so you will need to copy the filestore manually into the new instance.

If you’re going to restore the instance on the same server, you can just copy one filestore into the other:

cp -r -n \
  /var/lib/odoo/.local/share/Odoo/filestore/original-database \
  /var/lib/odoo/.local/share/Odoo/filestore/upgraded-database

However, if you need to copy to another server, that will be slightly harder:

ssh server01 "tar -cf - -C /var/lib/odoo/.local/share/Odoo/filestore/original-database ." | \
  ssh server02 "tar -xkf - -C /var/lib/odoo/.local/share/Odoo/filestore/upgraded-database"