Migration Odoo avec OpenUpgrade : le guide complet (18 vers 19)

Si vous êtes sur Odoo Community, cet article vous montre comment faire une migration entre deux versions d'Odoo avec OpenUpgrade et surtout ce qu'il faut faire pour que vos migrations ne soient pas chaotiques.

Regarder la vidéo

Le premier principe à appliquer : migrer d'abord le code, ensuite les données

C'est ce qu'il faut toujours faire pour ne pas avoir des problèmes de migration.

Et c'est logique, puisque migrer la base de données suppose que le code source soit déjà migré. Et c'est à ce moment qu'il faut utiliser OpenUpgrade.

Par exemple, sur un projet avec trois modules personnalisés :

1. Il faut passer le code de chaque module vers la version cible. Le wiki de l'OCA maintainer-tools contient des instructions détaillées pour chaque module.
2. En fonction des nouvelles mises à jour d'Odoo, vous pourrez décider, module par module, ce qui reste et ce qui disparaît.
3. Ensuite vous aurez besoin d'écrire les scripts de migration pour chaque module.
4. Une fois les scripts écrits, vous pouvez lancer la migration de données avec OpenUpgrade.

Migrer avec OpenUpgrade ne permet pas de passer directement de la 18 à la 20

La migration se fait une version à la fois :

• D'abord de 18 vers 19
• ensuite de 19 vers 20

Chacune est une migration complète que vous exécutez.

Où doit-on installer OpenUpgrade ?

OpenUpgrade s'installe sur l'instance de la version cible.

• Si vous migrez de 18 vers 19, OpenUpgrade 19 doit être installé sur l'instance v19. Le repo contient deux modules qui dépendent de la librairie Python openupgradelib :

  • openupgrade_framework est le module qui contient la logique de migration. Il est chargé au démarrage du serveur (server_wide_modules dans odoo.conf)

  • openupgrade_scripts : contient les scripts de migration pour chaque module standard d'Odoo.

  • Vous pouvez cloner le repo github.com/OCA/OpenUpgrade et les rendre disponibles sur votre instance v19. Prenez soin de cloner la branche de la version cible

  • Installer openupgradelib avec pip install openupgradelib.

• Ensuite, les scripts de migration doivent être écrits pour chaque module Odoo dans la v19 en fonction de la v18 et des nouvelles fonctionnalités.

• Enfin, exécuter la commande de migration avec OpenUpgrade sur cette instance v19.

Quels sont les modules et fonctions qui sont supportés sur la nouvelle version ?

Toutes ces informations sont disponibles sur la doc d'OpenUpgrade et le OCA maintainer-tools :

Le Coverage Analysis liste pour chaque version, les modules ajoutés et les modules supprimés, ainsi que l'état des scripts de migration par module.

Le wiki maintainer-tools liste les changements à appliquer dans votre code, module par module

odoo-module-migrator quant à lui aide à migrer le code source d'une ancienne version d'Odoo vers la nouvelle. Par exemple :

• renommer le fichier __openerp__.py en __manifest__.py
• supprimer # -*- encoding: utf-8 -*- qui n'est plus nécessaire depuis la version 11.0
• remplacer l'import « openerp » par l'import « odoo »
• supprimer les dossiers « migrations »
• remplacer <act_window> par <record model="ir.actions.window">

Les étapes de la migration

1. Faites un backup de la BD d'origine puis dupliquez

Faites un backup réel de la BD de production. Ensuite, dans le gestionnaire de DB, dupliquez-la et donnez à la copie un nom explicite.

Attention : Vous n'allez pas migrer la BD d'origine. Vous migrez plutôt la copie.

2. Ajoutez OpenUpgrade dans l'instance cible

Ajoutez OpenUpgrade dans le chemin des addons de l'instance de la version cible :

[options]
addons_path = /mnt/addons,/mnt/oca,/mnt/openupgrade

3. Lancez la migration

La commande est simple.

odoo \
  -c /etc/odoo/odoo.conf \
  -d LA_BD_COPIEE \
  --upgrade-path=/mnt/openupgrade/openupgrade_scripts/scripts,/mnt/addons-cutom/v19_upgrade/scripts \
  --load=base,web,openupgrade_framework \
  --update all \
  --stop-after-init

Les options de ligne de commande et celles du fichier de configuration font la même chose : choisissez l'une des deux formes.

--upgrade-path pointe vers le dossier scripts d'openupgrade_scripts et de vos scripts personnalisés.

--load va charger openupgrade_framework au démarrage du serveur

--update all va, lors de la mise à jour des modules, déclenche les scripts de pré et post-migration de chaque module.

4. Exécutez, corrigez et relancez

Si le script s'arrête sur une erreur, corrigez la cause et relancez la migration sur une nouvelle BD dupliquée et non sur la BD à demi migrée.

Comment écrire vos scripts de migration ?

OpenUpgrade fournit les scripts des modules standard. Pour vos modules personnalisés, c'est vous qui les écrivez. Faites un tour vers la documentation de OpenUpgrade pour savoir comment écrire vos scripts.

Mais en général, cela se résume à ceci :

mon_module/
└── migrations/
    └── 19.0.1.0.0/
        ├── pre-migration.py
        └── post-migration.py

• Si vous n'avez plus besoin d'un module, supprimez-le et supprimez ses colonnes traînant en base de données.

from openupgradelib import openupgrade

@openupgrade.migrate()
def migrate(env, version):
    openupgrade.drop_columns(
        env.cr,
        [
            ("res_partner", "x_available"),
            ("res_partner", "x_skills"),
        ],
    )

• Il est aussi possible de renommer une table, renommer une colonne, recalculer un champ à partir d'un autre. La documentation de OpenUpgrade couvre tout ça.

Les bonnes pratiques à adopter pour une migration réussie

1. Hériter et surcharger, jamais remplacer

Si on vous avez besoin d'ajouter un comportement à une fonction, ne recopiez pas la méthode entière pour y glisser votre logique. Héritez, ajoutez votre logique, et appelez super().

class ProductCategory(models.Model):
    _inherit = "product.category"

    def copy(self, default=None):
        default = dict(default or {})
        default["name"] = _("%s (copie)") % self.name
        return super().copy(default)

Si la version suivante intègre ce comportement en standard, vous supprimez le module et écrivez un script pour ne pas perdre vos données.

Avec une méthode entièrement recopiée, vous devez d'abord comprendre ce qui a changé dans la version d'origine, ligne par ligne.

2. Cibler les champs précis dans les vues

Pour modifier une vue, visez les champs et non la structure :

<field name="categ_id" position="after">
    <field name="x_category_code"/>
</field>

Les expressions XPath fonctionnent, mais elles décrivent un emplacement dans l'arbre, et l'arbre peut bouger à chaque version.

En ciblant un champ, vous le retrouvez immédiatement à la version suivante.

3. Conserver la logique métier standard

Évitez l'excès de personnalisation : ne personnalisez que sur un problème métier avéré sinon, restez sur le standard.

Quand vous devez intervenir sur un comportement standard, ajoutez votre logique et laissez le standard s'exécuter :

class ProductCategory(models.Model):
    _inherit = "product.category"

    @api.model_create_multi
    def create(self, vals_list):
        for vals in vals_list:
            vals.setdefault("x_category_code", self._next_category_code())
        return super().create(vals_list)

Le super() garantit que le fonctionnement d'Odoo n'est pas cassé.

4. Configurer plutôt que de développer et, le cas échéant, préférez les modules de l'OCA

Avant d'écrire un module, cherchez la configuration standard qui fait la même chose. Tout ceci parce qu'en utilisant un paramétrage vous n'avez quasiment pas besoin de migrer.

Si un module est vraiment nécessaire, cherchez d'abord du côté de l'OCA. Ces modules sont maintenus sérieusement et la communauté fait le travail de migration de code. Vous pouvez aussi intervenir et contribuer à la communauté.

5. Rester modulaire

Ne mélangez pas tout dans un dossier. Séparez les modèles, les vues, les règles de sécurité, les rapports, les fichiers statiques, l'API.

Ouvrez n'importe quel module OCA, vous verrez cette séparation: models/, views/, security/, report/, static/. Cette structure facilite la migration.

6. Documenter et tester

Si vous quittez le projet demain, il doit continuer à tourner. Celui qui reprend doit comprendre comment fontionne le projet pour pouvoir le maintenir à son tour.

Et les tests sont le seul critère objectif de réussite d'une migration. Des tests qui échouent après la migration sont une indication qu'il y'a un problème.

Avez vous besoin d'OpenUpgrade si vous utilisez Odoo Enterprise ?

NON! La migration avec OpenUpgrade concerne Odoo Community.

Sur Odoo Enterprise, Odoo SA fournit les outils de migration sur upgrade.odoo.com

À noter que ces outils migrent uniquement vos données. La migration du code source de vos modules personnalisés reste à votre charge.

Les limites d'OpenUpgrade

• OpenUpgrade migre les données des modules Odoo standard et les modules OCA. Vos modules personnalisés doivent être migrés par vous-même à travers vos propres scripts de migration.
• Le Coverage Analysis vous dit ce qui a changé au niveau des modules Odoo standard et non sur votre métier.
• Aucune migration ne remplace la recette fonctionnelle. Un script qui se termine sans erreur ne prouve pas que vos données sont justes. Il faut toujours faire tester avec les utilisateurs clés.

Ce que vous pouvez faire maintenant

Si vous avez une migration devant vous : lisez le Coverage Analysis et le wiki maintainer-tools de votre version, listez vos modules personnalisés par ordre de dépendance et migrez le code avant de toucher aux données.

→ Vous développez des modules Odoo ? Voici comment aller deux fois plus vite avec l'IA : récupérez OSSE gratuitement, l'outil qui force votre assistant IA à lire le code source installé avant de proposer quoi que ce soit.