Formations — 1 037 leçons en français

Accueil › Spring Boot › Migrer le schéma avec Flyway

Migrer le schéma avec Flyway

Migrations de base de donnéesintermediaire

spring.jpa.hibernate.ddl-auto=update (ou create) est pratique en développement, mais inadapté en production : le schéma généré dépend de la version du code au moment du démarrage, rien n'est versionné, rien n'est rejouable à l'identique d'un environnement à l'autre, et Hibernate ne supprime jamais une colonne devenue inutile. Flyway résout ça en traitant le schéma comme du code : chaque évolution est un script SQL numéroté, versionné avec le reste du projet.

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>
<!-- Depuis Flyway 10, certaines bases (ex. PostgreSQL) demandent en plus : -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
</dependency>

Les scripts vont par défaut dans src/main/resources/db/migration, nommés V<version>__<description>.sql :

-- V1__creer_table_produits.sql
CREATE TABLE produits (
    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    nom VARCHAR(100) NOT NULL,
    prix NUMERIC(10, 2) NOT NULL
);

Au démarrage, Flyway compare les scripts présents à une table flyway_schema_history qu'il gère lui-même, et exécute uniquement ceux qui n'ont pas encore été appliqués, dans l'ordre des versions. Une migration déjà appliquée ne doit jamais être modifiée : Flyway détecterait le changement (via un checksum) et refuserait de démarrer. Pour corriger une erreur, on écrit une nouvelle migration.

Les termes à connaître

Migration versionnée

Script SQL (ou Java) nommé V<version>__<description>.sql, exécuté une seule fois, dans l'ordre des versions. C'est l'unité de base de Flyway : chaque évolution du schéma passe par un nouveau fichier, jamais par la modification d'un fichier existant.

flyway_schema_history

Table créée automatiquement par Flyway dans le schéma cible. Elle enregistre chaque migration appliquée : version, description, script, checksum, date, durée, succès ou échec. C'est elle que Flyway consulte pour savoir quelles migrations restent à jouer.

Checksum

Empreinte calculée à partir du contenu d'un script de migration, stockée dans flyway_schema_history. Au démarrage suivant, Flyway recalcule le checksum du fichier et le compare à celui enregistré : s'ils diffèrent, la migration a été modifiée après coup et Flyway refuse de démarrer.

Migration répétable (R__)

Script nommé R__<description>.sql, sans numéro de version. Rejoué à chaque fois que son contenu change (nouveau checksum), après toutes les migrations versionnées. Utile pour les vues, fonctions, procédures stockées ou données de référence.

spring.flyway.baseline-on-migrate

Propriété (défaut false) qui permet à Flyway de fonctionner sur un schéma déjà existant et non vide (créé avant l'adoption de Flyway). Activée, elle crée une ligne de « baseline » dans l'historique à la version spring.flyway.baseline-version (défaut 1) sans exécuter les scripts antérieurs ou égaux à cette version.

flyway-core

Dépendance principale de Flyway. Depuis Flyway 10, la prise en charge de certains SGBD (par exemple PostgreSQL) a été extraite dans des modules séparés — flyway-database-postgresql notamment — à ajouter en plus de flyway-core pour ces bases.

ddl-auto=validate

Réglage Hibernate recommandé quand Flyway (ou Liquibase) gère le schéma : Hibernate ne crée ni ne modifie plus aucune table, il vérifie seulement que les entités correspondent au schéma existant, et signale une erreur au démarrage sinon.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.