CI/CD des migrations de schéma (Flyway/Liquibase)

Symptôme

Objectif : gérer les modifications de schéma avec des fichiers de migration versionnés ; les appliquer automatiquement mais de manière contrôlée dans la CI/CD avec Flyway ou Liquibase.

1. Créez des fichiers de migration versionnés (Vxxx__name.sql)

Écrivez chaque modification de schéma dans un fichier nommé avec un numéro de version croissant ; la convention Flyway est V<version>__<description>.sql (par ex. V1__initial_schemas.sql, V2__orders_table.sql). Ces fichiers sont conservés dans Git et appliqués dans l'ordre des versions. Les migrations appliquées sont enregistrées dans une table de suivi (flyway_schema_history dans Flyway), de sorte que chaque migration s'exécute exactement une fois.

PostgreSQL

-- V2__orders_table.sql
CREATE TABLE orders (
  id       bigserial PRIMARY KEY,
  amount    numeric(12,2) NOT NULL,
  created_at   timestamptz DEFAULT now()
);

2. Préservez l'immuabilité grâce aux checksums

Flyway/Liquibase stockent le checksum de chaque migration appliquée. Si vous modifiez ensuite un fichier déjà appliqué, le checksum ne correspond plus et l'outil échoue. Règle : ne modifiez JAMAIS une migration appliquée ; faites la correction dans un nouveau fichier de version. Cela garantit que tous les environnements (dev/staging/prod) partagent le même historique.

PostgreSQL

# repair on checksum mismatch (use with care):
flyway repair
# the right way: add the change in a new Vx file

3. Établissez une baseline sur une base existante

Utilisez baseline lorsque vous rattachez l'outil de migration à une base déjà alimentée sans historique ; il considère l'état actuel comme la « version de départ » et ne tente pas de recréer les objets existants. Les migrations postérieures à baselineVersion sont appliquées. Dans un environnement construit de zéro, aucune baseline n'est nécessaire ; les migrations s'exécutent à partir de V1.

PostgreSQL

flyway baseline -baselineVersion=1 -baselineDescription="existing schema"

4. Migrez automatiquement dans le pipeline CI

Exécutez l'outil de migration dans une étape CI pour appliquer automatiquement les modifications aux bases de test et de préproduction ; la commande migrate n'exécute que les nouveaux fichiers (non appliqués) et est idempotente. Appliquer d'abord la migration à une base temporaire/éphémère et la valider permet de détecter le SQL défectueux avant qu'il n'atteigne la prod. Le schéma doit être migré AVANT le déploiement du code applicatif (avec des modifications rétrocompatibles).

PostgreSQL

# CI step (Flyway)
flyway -url=jdbc:postgresql://staging/appdb \
  -user=ci -password=$PW migrate

MySQL

flyway -url=jdbc:mysql://staging/appdb \
  -user=ci -password=$PW migrate

5. Ajoutez une validation manuelle pour la prod

Le test/la préproduction sont automatiques, mais faites en sorte que le migrate de prod exige une approbation manuelle ; ajoutez une étape d'« approval gate » (approbation manuelle) dans la CI/CD. Avant l'approbation, affichez les migrations qui seront exécutées avec 'flyway info' ou 'liquibase status'. Prenez toujours une sauvegarde récente avant d'appliquer en prod afin de pouvoir revenir en arrière en cas de problème.

PostgreSQL

# what will run before approval?
flyway info
# liquibase equivalent:
liquibase status --verbose

6. Définissez la réversibilité et une stratégie de retour arrière

Flyway Community n'offre pas d'undo automatique ; adoptez le principe de migration forward-only : au lieu d'annuler une erreur, écrivez une nouvelle migration qui la corrige. Les changesets Liquibase peuvent définir un bloc rollback et être annulés avec 'liquibase rollback'. La stratégie la plus robuste : gardez les modifications petites et rétrocompatibles, faites une sauvegarde avant les opérations risquées (suppression de colonnes) et préparez un plan de retour arrière écrit.

PostgreSQL

-- Liquibase rollback example (inside a changeset)
--changeset dev:2
CREATE TABLE orders (...);
--rollback DROP TABLE orders;