Intégration de Flyway avec Spring Boot

Pourquoi intégrer Flyway ?

Lorsque vous développez une application qui utilise une base de données, le schéma de cette base (tables, colonnes, index, etc.) évolue au fil du temps. Gérer ces changements manuellement à travers différents environnements (développement, test, production) est source d'erreurs, difficile à suivre et non reproductible. Flyway est un outil de migration de base de données open-source populaire qui résout ce problème en apportant le versionnage et l'automatisation à vos changements de schéma.

Intégrer Flyway dans un projet Spring Boot permet d'appliquer automatiquement les migrations de base de données nécessaires au démarrage de l'application, garantissant ainsi que le schéma de la base est toujours dans l'état attendu par le code applicatif. Cela simplifie les déploiements, facilite le travail en équipe et assure la cohérence entre les environnements.

Ajouter la dépendance Flyway

Pour commencer, vous devez ajouter la dépendance principale de Flyway à votre projet. Spring Boot gère la version de `flyway-core` via son propre BOM (Bill of Materials), vous n'avez donc généralement pas besoin de spécifier la version explicitement.

Avec Maven (pom.xml) :

    org.flywaydb
    flyway-core

Avec Gradle (build.gradle) :

implementation 'org.flywaydb:flyway-core'

// Assurez-vous d'avoir aussi une dépendance pour l'accès aux données
// (ex: implementation 'org.springframework.boot:spring-boot-starter-data-jpa')
// et le driver JDBC (ex: runtimeOnly 'org.postgresql:postgresql')

Il est crucial d'avoir également configuré une DataSource dans votre application (via spring-boot-starter-data-jpa ou spring-boot-starter-data-jdbc et les propriétés `spring.datasource.*`), car Flyway l'utilisera pour se connecter à la base de données.

Auto-configuration et fonctionnement par défaut

La magie de Spring Boot opère ici : si la dépendance `flyway-core` est présente sur le classpath et qu'un bean DataSource est configuré, Spring Boot auto-configure et exécute Flyway pour vous.

Au démarrage de l'application, avant même l'initialisation complète du contexte applicatif et notamment avant que JPA/Hibernate ne tente de valider ou de modifier le schéma, Spring Boot va :

1. Créer une instance de org.flywaydb.core.Flyway configurée avec la DataSource principale.
2. Rechercher les scripts de migration SQL dans un emplacement par défaut sur le classpath.
3. Vérifier l'état de la base de données en consultant une table de métadonnées spéciale (par défaut `flyway_schema_history`).
4. Appliquer toutes les migrations SQL trouvées qui n'ont pas encore été exécutées, dans l'ordre de leur version.

Par défaut, Flyway recherche les scripts de migration dans le dossier classpath:db/migration. Vous devez donc créer ce dossier dans vos ressources (src/main/resources/db/migration) et y placer vos fichiers de migration SQL.

Ecrire les scripts de migration SQL

Les scripts de migration Flyway sont de simples fichiers SQL qui contiennent les instructions DDL (Data Definition Language - CREATE TABLE, ALTER TABLE, etc.) et potentiellement DML (Data Manipulation Language - INSERT, UPDATE pour des données de référence) nécessaires pour faire évoluer votre schéma.

Ils doivent respecter une convention de nommage stricte pour que Flyway puisse les détecter et les ordonner :

V__.sql

• V : Préfixe indiquant une migration versionnée (obligatoire).
• : Le numéro de version de la migration. Les versions peuvent utiliser des chiffres, des points ou des underscores (ex: 1, 1.1, 2024.01.15.1, 002_). Flyway ordonne les scripts en fonction de ce numéro.
• __ : Deux underscores séparent la version de la description (obligatoire).
• : Une description textuelle de ce que fait la migration (les underscores sont remplacés par des espaces). Exemple : Create_user_table, Add_email_to_users.
• .sql : L'extension du fichier.

Exemple (`src/main/resources/db/migration/V1__Create_user_table.sql`) :

CREATE TABLE app_user (
    id BIGINT PRIMARY KEY,
    username VARCHAR(100) NOT NULL UNIQUE,
    password VARCHAR(255) NOT NULL,
    email VARCHAR(150) UNIQUE,
    active BOOLEAN DEFAULT TRUE
);

Exemple (`src/main/resources/db/migration/V1.1__Add_registration_date.sql`) :

ALTER TABLE app_user 
ADD COLUMN registration_date TIMESTAMP;

Flyway exécute ces scripts séquentiellement en fonction de leur numéro de version. Il enregistre chaque migration appliquée (nom du script, version, date, succès) dans sa table de métadonnées (flyway_schema_history) pour savoir quelles migrations ont déjà été exécutées.

Configuration via `application.properties`/`yml`

Vous pouvez personnaliser le comportement de Flyway via les propriétés de l'application :

# application.properties

# Activer/Désactiver Flyway (défaut: true si flyway-core est présent)
spring.flyway.enabled=true

# Emplacement(s) des scripts de migration (défaut: classpath:db/migration)
# Peut être une liste séparée par des virgules
spring.flyway.locations=classpath:db/migration,classpath:db/data 

# Nom de la table de métadonnées (défaut: flyway_schema_history)
# spring.flyway.table=schema_version

# Schéma(s) géré(s) par Flyway (utile si vous avez plusieurs schémas)
# spring.flyway.schemas=myschema

# Initialiser la table de métadonnées si elle n'existe pas sur une base existante ?
# Utile la première fois que vous activez Flyway sur une base non vide.
spring.flyway.baseline-on-migrate=false 
# Version de référence pour baseline-on-migrate (défaut: 1)
# spring.flyway.baseline-version=1.0
# Description pour baseline-on-migrate
# spring.flyway.baseline-description=Base initiale

# Valider les migrations au démarrage (vérifie les checksums des migrations déjà appliquées)
# spring.flyway.validate-on-migrate=true 

# Réparer la table de métadonnées si nécessaire (ex: après un échec de migration)
# spring.flyway.repair-on-migrate=false

# Nettoyer la base de données avant migration (supprime tous les objets! A utiliser avec EXTREME précaution, jamais en prod)
# spring.flyway.clean-on-validation-error=false 
# spring.flyway.clean-disabled=true # Sécurité supplémentaire pour désactiver clean

# Autoriser l'exécution de migrations dans un ordre non séquentiel (par rapport aux versions déjà appliquées)
# spring.flyway.out-of-order=false

Consultez la documentation de Spring Boot et Flyway pour la liste complète des options de configuration.

Coordination avec JPA/Hibernate

Comme Flyway s'exécute avant l'initialisation de JPA/Hibernate, il est essentiel de s'assurer qu'ils ne se marchent pas sur les pieds. Si vous utilisez JPA, vous devez configurer la propriété de génération de schéma Hibernate pour qu'elle ne tente pas de créer ou modifier les tables gérées par Flyway.

La configuration recommandée est généralement :

# application.properties
spring.jpa.hibernate.ddl-auto=validate # ou none

• validate : Hibernate vérifie au démarrage si le schéma de la base de données (créé/modifié par Flyway) correspond au mapping des entités JPA. Si une incohérence est détectée (colonne manquante, type incorrect), l'application échoue au démarrage, ce qui est souvent souhaitable pour détecter les problèmes tôt.
• none : Hibernate ne fait aucune vérification ni modification du schéma. C'est l'option la plus sûre en production, mais elle ne détecte pas les incohérences potentielles au démarrage.
• Evitez create, create-drop, update en production lorsque vous utilisez Flyway, car Hibernate pourrait entrer en conflit avec les migrations gérées par Flyway ou annuler leurs effets.

Conclusion : Versionner votre base de données comme votre code

L'intégration de Flyway avec Spring Boot offre une solution robuste et automatisée pour gérer l'évolution du schéma de votre base de données. En traitant vos migrations de base de données comme du code versionné (fichiers SQL dans votre système de contrôle de version), vous améliorez la fiabilité, la reproductibilité et la maintenabilité de votre application. L'auto-configuration de Spring Boot rend la mise en place initiale extrêmement simple, vous permettant de vous concentrer sur l'écriture de vos migrations SQL.