Prérequis

• Odoo 19 installé (T01 Ubuntu).
• Un module Odoo 18 fonctionnel à migrer — ou le module démo qu'on va construire dans cet article.
• Base PostgreSQL de test dédiée (jamais la prod — règle numéro un d'une migration).
• Familiarité avec le manifeste Odoo, les modèles et les tests automatisés (T24) — la migration n'est sérieuse que si une suite de tests la valide.

2. Les 3 hooks du manifest

Différents des scripts de migration (versionnés), les hooks du manifest s'exécutent à des moments fixes du cycle de vie du module :

# __manifest__.py
{
    'name': 'Mon module',
    'version': '19.0.1.0.0',
    'depends': ['base'],
    'data': ['...'],

    'pre_init_hook': 'my_pre_init_function',     # fonction dans __init__.py
    'post_init_hook': 'my_post_init_function',   # id.
    'uninstall_hook': 'my_uninstall_function',   # id.
}

Dans __init__.py, tu définis ces fonctions avec une signature légèrement différente des scripts : elles reçoivent env directement, pas cr.

# __init__.py
def my_pre_init_function(env):
    """Exécuté AVANT registry.load() — à l'installation uniquement."""
    # À ce stade les modèles ne sont pas encore chargés.
    # Tu as env, mais les modèles métier de ce module ne sont pas accessibles.
    env.cr.execute("CREATE INDEX IF NOT EXISTS ...")


def my_post_init_function(env):
    """Exécuté APRÈS load_data() et translations — à l'installation uniquement."""
    # Tous les modèles sont chargés, tu peux écrire des records.
    env['res.config.settings'].create({...})


def my_uninstall_function(env):
    """Exécuté à la désinstallation du module."""
    env.cr.execute("DROP INDEX IF EXISTS ...")

Attention : ces hooks ne s'exécutent qu'à l'installation (ou à la désinstallation pour le dernier). Ils ne tournent pas lors d'un simple upgrade. Pour migrer entre deux versions, utilise les scripts versionnés décrits ci-dessous.

4. Le stage pre — avant l'ORM

Le stage pre s'exécute avant que l'ORM ne charge le modèle. C'est ta seule chance de modifier le schéma SQL avant qu'Odoo décide de créer des colonnes neuves (et d'abandonner les anciennes).

Cas typique : tu as renommé legacy_status en state dans ton modèle Python. Si tu ne fais rien, l'ORM va créer une colonne state vide à côté de legacy_status. Avec un pre-*.py, tu renommes la colonne SQL avant que l'ORM la voie :

# migrations/19.0.1.1.0/pre-10-rename-columns.py
"""Pre-migration 19.0.1.0.0 → 19.0.1.1.0 — rename SQL columns."""
import logging

_logger = logging.getLogger(__name__)


def migrate(cr, version):
    _logger.info("T25 migration — pre: rename columns legacy_* → *")

    # 1. Renommer la colonne selection
    cr.execute("""
        SELECT column_name FROM information_schema.columns
         WHERE table_name = 'mig_demo_item' AND column_name = 'legacy_status'
    """)
    if cr.fetchone():
        cr.execute("ALTER TABLE mig_demo_item RENAME COLUMN legacy_status TO state")
        _logger.info("  legacy_status → state")

    # 2. Renommer la table de liaison Many2many
    cr.execute("""
        SELECT table_name FROM information_schema.tables
         WHERE table_name = 'mig_demo_item_legacy_user_rel'
    """)
    if cr.fetchone():
        cr.execute(
            "ALTER TABLE mig_demo_item_legacy_user_rel "
            "RENAME TO mig_demo_item_res_users_rel"
        )
        _logger.info("  table Many2many renommée")

Trois détails à retenir :

• Idempotent toujours : on vérifie d'abord que la vieille colonne existe avant de renommer. Un upgrade peut être relancé plusieurs fois après une interruption — le script doit tolérer ça.
• Pas d'ORM ici : le modèle n'est pas encore chargé. Tu es en SQL pur via cr.execute().
• Les tables Many2many se renomment aussi. Odoo nomme les tables de liaison <model>_<target>_rel — si tu renommes le champ, la convention change.

6. Le stage end — une fois tous les modules chargés

Le stage end s'exécute après que tous les modules (pas seulement le tien) soient passés par leurs pre + post. Utile pour des opérations qui dépendent d'autres modules ou pour des validations finales.

# migrations/19.0.1.1.0/end-10-cleanup.py
"""End-migration 19.0.1.0.0 → 19.0.1.1.0 — cleanup."""
import logging

_logger = logging.getLogger(__name__)


def migrate(cr, version):
    _logger.info("T25 migration — end: cleanup")

    # S'assurer qu'aucune vieille valeur n'a échappé à la conversion post-
    cr.execute(
        "SELECT COUNT(*) FROM mig_demo_item WHERE state IN ('confirm', 'cancel')"
    )
    stale = cr.fetchone()[0]
    if stale:
        _logger.warning(
            "  %d records ont encore une valeur legacy — intervention manuelle",
            stale,
        )
    else:
        _logger.info("  aucune valeur legacy résiduelle — migration propre")

Trois usages canoniques du stage end :

• Validations post-migration : scanner les tables pour détecter une donnée qui aurait échappé à la conversion — comme ici.
• Déclenchement de crons ou d'actions serveur qui nécessitent que tous les modules soient chargés (triggers cross-module).
• Invalidation de caches : forcer un recompute global via env.invalidate_all() après d'importantes modifications de données.

8. Pièges à éviter

Dernier point, moins un piège qu'une discipline : écris des tests qui valident la migration. Un test TransactionCase (T24) qui crée des records avec les anciennes valeurs, simule le bump de version, et vérifie que les données sont correctement converties. Sans test, une migration est une roulette russe le jour du déploiement.