Guide de migration Liquibase : Migrations de base de données sans risque

Le Problème Sans Liquibase

Structure du Changelog

src/main/resources/db/changelog/
├── db.changelog-master.yaml     ← Master (importe tous les autres)
├── 2024/
│   ├── 001-create-users-table.yaml
│   ├── 002-add-email-index.yaml
│   └── 003-create-orders-table.yaml
└── 2025/
    ├── 001-add-last-login-column.yaml
    └── 002-create-audit-log.yaml

# db.changelog-master.yaml
databaseChangeLog:
  - includeAll:
      path: db/changelog/2024/
  - includeAll:
      path: db/changelog/2025/

Changeset : Créer une Table

# 2024/001-create-users-table.yaml
databaseChangeLog:
  - changeSet:
      id: 2024-001-create-users
      author: [email protected]
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: VARCHAR(36)
                  constraints:
                    primaryKey: true
                    nullable: false
              - column:
                  name: email
                  type: VARCHAR(255)
                  constraints:
                    nullable: false
                    unique: true
              - column:
                  name: created_at
                  type: TIMESTAMP
                  defaultValueComputed: CURRENT_TIMESTAMP
      rollback:
        - dropTable:
            tableName: users

Migration Complexe avec Contexte

# 2025/001-add-last-login.yaml
databaseChangeLog:
  - changeSet:
      id: 2025-001-add-last-login
      author: [email protected]
      preConditions:
        onFail: MARK_RAN
        tableExists:
          tableName: users
      changes:
        - addColumn:
            tableName: users
            columns:
              - column:
                  name: last_login_at
                  type: TIMESTAMP

  # Exécuter uniquement en test/dev
  - changeSet:
      id: 2025-002-insert-test-data
      context: "test,development"
      changes:
        - insert:
            tableName: users
            columns:
              - column: { name: email, value: "[email protected]" }

Rollback

# Via le plugin Maven
mvn liquibase:rollback -Dliquibase.rollbackCount=1

# Via CLI
liquibase rollback --tag=v1.0
liquibase rollbackCount 3

Bonnes Pratiques

• Les changesets sont immuables – ne jamais modifier ceux déjà exécutés
• Toujours définir les instructions de rollback
• Utiliser des contextes pour les migrations spécifiques à l'environnement (test, development)
• Préfixe numérique (001-, 002-) pour une exécution ordonnée
• En CI/CD : exécuter mvn liquibase:validate avant chaque déploiement

Conclusion

• Reproductible : Chaque environnement est garanti au même état
• Versionné : Historique complet de toutes les modifications de schéma
• Rollback possible : Les migrations peuvent être annulées
• CI/CD-ready : Exécution automatique à chaque déploiement