Migrations DB dans legacy sans ORM : structure et pratique

Système de migration de bases de données pour projets legacy sans ORM

Dans les systèmes legacy sans ORM, la gestion des migrations de scripts DDL/DML exige un contrôle strict. Cette approche organise un dépôt et des tables d'état pour appliquer les changements de manière cohérente dans les environnements de test et de production. Elle garantit la traçabilité, l'intégrité des données et des déploiements prévisibles sur des bases de données relationnelles conformes ACID.

Cette méthode réduit le code boilerplate dans les scripts, automatise la validation et l'enregistrement. Les scripts se divisent en quatre types : initialisation, baseline, versionnés et répétables. Chaque type respecte des règles spécifiques pour éviter les doublons et maintenir la monotonicité des versions.

Structure du dépôt Git

Les scripts sont regroupés par type et appliqués dans un ordre fixe :

• Initialisation d'environnement — exécutée une seule fois pour créer utilisateurs, rôles, bases de données et schémas. Spécifique à l'environnement (test/prod), via psql.
• Baseline — exécutée une seule fois sur un schéma vide pour établir la version initiale de production et les tables de contrôle.
• Versionnés — appliqués séquentiellement par versions entières croissantes, une seule fois, dans une transaction qui enregistre l'horodatage et l'utilisateur.
• Répétables — appliqués si le SHA256 change ou s'il n'y a pas d'enregistrement, après les scripts versionnés, pour vues/procédure/triggers sans modifications de données.

Types d'objets :

• Initialisation : utilisateurs, rôles, bases de données, schémas.
• Baseline : tables, données, vues, procédures, triggers.
• Versionnés : changements de schéma, migrations de données.
• Répétables : vues, procédures, triggers.

Cette structure s'inspire de Flyway mais est adaptée aux processus manuels sans outils externes.

Tables d'état dans le schéma

Chaque schéma dispose de tables de service pour le suivi :

• dbmigration_versions (version_id, is_baseline, created_at, created_by, created_from) — suit l'historique des scripts baseline et versionnés.
• dbmigration_repeatable (sha256sum, relative_path, created_at, created_by, created_from) — suit les scripts répétables, permettant une réapplication en cas de changement.

Ces tables imposent des vérifications avant exécution : un script ne s'exécute que s'il n'existe pas d'enregistrement ou si la somme de contrôle a changé. Les logs capturent l'utilisateur et l'horodatage pour des pistes d'audit complètes.

Déploiements en développement

Dans CI/CD (pipelines GitLab), clonez la branche avec les changements, puis pour chaque schéma :

$ git clone <url avec changements de schéma de base de données>
$ USER_PASSWORD=topsecret123 dbmigration.py update --host <host> --port <port> --dbname <db> --user <user_name> schema1 ./db/schema1
$ USER_PASSWORD=topsecret123 dbmigration.py update --host <host> --port <port> --dbname <db> --user <user_name> schema2 ./db/schema2

Cela applique automatiquement les scripts en attente tout en préservant les données.

Processus en production

Supporte les déploiements à chaud sans interruption. Pré-testé en UAT avec tests smoke.

Étapes :

• Extraire l'archive : tar xzvf system-x.y.z.tar.gz.
• Pour le schéma : cd system-x.y.z/schema1.
• Générer le script de migration : USER_PASSWORD=topsecret123 dbmigration.py verify --host <host> --port <port> --dbname <db> --user <user_name> --build-update-script ./schema1_migrate.sql schema1 ./db/schema1.
• Vérifier schema1_migrate.sql pour détecter les changements cassants.
• Appliquer : PGPASSWORD=topsecret123 psql -h <host> -p <port> -U <user> -d <database> -v schema_name=<schema1> -f "schema1_migrate.sql".

Répéter pour chaque schéma. Le mode verify prévisualise les changements sans les appliquer.

Bonnes pratiques clés

• Réparer en avant : utiliser de nouvelles migrations pour corriger les erreurs au lieu de rollbacks, en préservant les données.
• Changements non cassants : ajouter tables/colonnes d'abord, supprimer après mise en production quand inutilisées. Permet la coexistence multi-versions sur la même base.
• Suivi au niveau schéma : versions suivies par schéma, pas par base de données.
• Pré-vérifications : générer des scripts pour revue.
• Préservation des données : mises à jour incrémentales évitent drop/recreate.

Points clés à retenir

• Suivi automatisé élimine le boilerplate manuel et les erreurs de scripts.
• Versions monotones avec transactions assurent des états cohérents.
• Support de correctifs à chaud sur versions (prod/UAT/dev) via scripts versionnés.
• Pistes d'audit complètes via tables : qui/quand/quoi appliqué.
• Fonctionne avec n'importe quel SGBDR conforme ACID.

— Editorial Team