Comment utiliser Flyway migrations DB 2026

Introduction

Flyway est un outil open-source puissant pour gérer les migrations de schémas de base de données de manière versionnée et reproductible. Contrairement aux scripts SQL manuels, Flyway applique des changements atomiques numérotés (V1__, V2__, etc.), garantissant que toutes les environnements (dev, staging, prod) restent synchronisés.

Pourquoi l'utiliser en 2026 ? Les équipes distribuées et les déploiements CI/CD exigent une traçabilité parfaite : Flyway tracke l'historique via une table flyway_schema_history, supporte undo pour les rollbacks et s'intègre nativement avec Maven, Gradle ou Docker. Idéal pour PostgreSQL, MySQL ou SQL Server, il réduit les downtimes et les erreurs humaines.

Ce tutoriel intermediate vous guide pas à pas : de l'installation CLI à des migrations complexes, en passant par la validation et les baselines. À la fin, vous maîtriserez un workflow pro, prêt pour la prod. (128 mots)

Prérequis

Java 17+ installé (Flyway CLI est un JAR exécutable)
PostgreSQL 14+ avec une base de test (flyway_demo)
Client SQL comme psql pour vérifier les changements
Outils CLI : curl, unzip (Linux/Mac) ou équivalent Windows
Connaissances de base en SQL et Git pour versionner les migrations

Télécharger et installer Flyway CLI

install.sh

curl -L https://repo1.maven.org/maven2/org/flywaydb/flyway-commandline/10.20.1/flyway-commandline-10.20.1-linux-x64.tar.gz | tar -xz

# Ou pour macOS
curl -L https://repo1.maven.org/maven2/org/flywaydb/flyway-commandline/10.20.1/flyway-commandline-10.20.1-macosx-x64.tar.gz | tar -xz

# Ajouter au PATH (exemple Linux)
export PATH=$PWD/flyway-10.20.1:$PATH
flyway -v

Ce script télécharge la dernière version stable de Flyway CLI (10.20.1 en 2026), l'extrait et vérifie l'installation via -v. Utilisez la variante OS appropriée ; évitez les versions obsolètes pour les nouvelles features comme les repeatables migrations.

Configurer la connexion à la base

Créez un fichier de configuration pour centraliser les params DB. Flyway supporte flyway.conf (format INI-like) ou YAML. Placez-le à la racine de votre projet migrations.

Analogie : C'est comme un .env pour votre DB, mais versionnable en Git. Toujours exclure les creds sensibles via .gitignore et utiliser des variables d'environnement en prod.

Fichier de configuration flyway.conf

flyway.conf

flyway.url=jdbc:postgresql://localhost:5432/flyway_demo
flyway.user=postgres
flyway.password=secret
flyway.schemas=public
flyway.locations=filesystem:./sql
flyway.baselineOnMigrate=true
flyway.validateOnMigrate=true
flyway.outOfOrder=false

Ce conf connecte à PostgreSQL local, cible le schéma public et scanne les migrations dans ./sql. baselineOnMigrate=true initialise les DB existantes ; validateOnMigrate vérifie la cohérence avant apply. Piège : Oubliez schemas et Flyway applique partout.

Première migration : Créer table users

sql/V1__Creer_table_users.sql

-- Version: 1
-- Description: Création de la table users initiale

CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(100) NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

COMMENT ON TABLE users IS 'Table des utilisateurs';

Migration V1__ : Crée une table users avec contraintes PK/UNIQUE et timestamp auto. Le préfixe V1__ est obligatoire pour l'ordre ; la description suit les doubles underscores. Testez toujours en local avant commit.

Exécuter la première migration

Placez flyway.conf et le dossier sql/ à la racine. Lancez flyway migrate : Flyway crée flyway_schema_history, applique V1 et logue tout. Vérifiez via psql : \dt pour les tables, SELECT * FROM flyway_schema_history; pour l'historique.

Appliquer les migrations

migrate.sh

./flyway-10.20.1/flyway -configFiles=flyway.conf migrate

# Vérifier l'état
./flyway-10.20.1/flyway -configFiles=flyway.conf info

migrate applique les pendings migrations séquentiellement ; info affiche l'état (applied, pending, future). En CI/CD, chainnez avec validate pour fail fast si drift.

Deuxième migration : Ajouter colonne role

sql/V2__Ajouter_role_users.sql

-- Version: 2
-- Description: Ajout colonne role à users

ALTER TABLE users ADD COLUMN role VARCHAR(20) DEFAULT 'USER' NOT NULL;

CREATE INDEX idx_users_role ON users(role);

-- Insert sample data
INSERT INTO users (username, email, role) VALUES
('admin', 'admin@ex.com', 'ADMIN'),
('user1', 'user1@ex.com', 'USER');

V2__ étend V1 sans downtime : ADD COLUMN avec default pour compatibilité. Index pour perf queries. Toujours inclure data init si pertinent ; Flyway applique idempotement via checks internes.

Migration repeatable : Mise à jour vue

sql/R__Vue_utilisateurs_actifs.sql

-- Repeatable: R__ exécuté à chaque migrate si changé

DROP VIEW IF EXISTS vue_users_actifs;

CREATE OR REPLACE VIEW vue_users_actifs AS
SELECT id, username, email, role
FROM users
WHERE created_at > NOW() - INTERVAL '30 days';

Préfixe R__ pour repeatables : re-exécutées si checksum change (idéal pour views/procs). CREATE OR REPLACE assure idempotence. Utile pour configs dynamiques sans versionner tout.

Gérer les rollbacks avec undo

Feature clé intermediate : Flyway supporte undo depuis v8. Créez U2__ pour revert V2. Lancez flyway undo 1 pour revenir à V1. Parfait pour hotfixes sans downtime.

Undo migration pour V2

sql/U2__Supprimer_role_users.sql

-- Undo Version: 2
-- Revert: Supprime role et index

DROP INDEX IF EXISTS idx_users_role;

ALTER TABLE users DROP COLUMN IF EXISTS role;

U2__ matche V2 et revert exactement. IF EXISTS pour safety. Testez undo 1 : revient à V1 cleanly, met à jour flyway_schema_history. Limite : Pas pour data destructive sans backup.

Intégration Maven pour builds auto

pom.xml

<project>
  <groupId>com.example</groupId>
  <artifactId>flyway-demo</artifactId>
  <version>1.0</version>
  <dependencies>
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>42.7.4</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-maven-plugin</artifactId>
        <version>10.20.1</version>
        <configuration>
          <url>jdbc:postgresql://localhost:5432/flyway_demo</url>
          <user>postgres</user>
          <password>secret</password>
          <locations>
            <location>filesystem:./sql</location>
          </locations>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Plugin Maven pour mvn flyway:migrate en CI. Copie conf CLI dans . Avantage : Transact SQL auto, rollback on fail. Ajoutez clean pour reset dev.

Bonnes pratiques

Versionnez tout : Committez sql/ et flyway.conf en Git ; ignorez creds via env vars (flyway.password=${DB_PASS}).
Migrations courtes : < 2s chacune pour zero-downtime ; splitez ALTERs complexes.
Tests automatisés : Intégrez flyway validate en pre-commit hook.
Environnements : Utilisez flyway.baselineVersion=1 pour prod legacy.
Repeatables prioritaires : Pour views/triggers, toujours R__ au lieu de V__.

Erreurs courantes à éviter

OutOfOrder=true : Permet skips mais casse reproductibilité ; gardez false en équipe.
Checksum mismatch : Ne modifiez JAMAIS une migration applied ; créez Vn+1__fix.
Transactions manquantes : Flyway wrappe auto, mais testez nested TX en Postgres.
Locations multiples : Oubliez filesystem:sql, classpath:db/migration et miss migrations.

Pour aller plus loin

Plongez dans Flyway docs officielles pour Docker/Cloud. Intégrez avec Spring Boot via @Flyway ou Liquibase hybrid.

Découvrez nos formations Learni sur DevOps et bases de données pour maîtriser CI/CD avec migrations avancées.

Comment utiliser Flyway pour migrations DB en 2026