Structure des scripts de migration SQL (convention de nommage)

L'importance d'une structure pour les migrations

Lorsque vous utilisez un outil de migration de base de données comme Flyway, le coeur de son fonctionnement repose sur des scripts SQL qui décrivent les changements successifs apportés à votre schéma de base de données. Pour que Flyway puisse découvrir, ordonner et exécuter ces scripts de manière fiable et répétable à travers différents environnements (développement, test, production), il s'appuie sur une structure de fichiers et une convention de nommage très précises.

Respecter cette convention n'est pas une simple suggestion, c'est une exigence fondamentale pour que Flyway fonctionne correctement. Elle permet à Flyway de déterminer la version de chaque migration, son ordre d'exécution et de savoir quelles migrations ont déjà été appliquées à une base de données cible (via sa table de métadonnées, souvent nommée flyway_schema_history).

Emplacement par défaut des scripts

Par défaut, lorsque vous utilisez Flyway avec Spring Boot (via le starter flyway-core ou des starters spécifiques à une base de données qui l'incluent), Flyway recherche les scripts de migration dans un emplacement spécifique du classpath : db/migration.

Dans une structure de projet Maven ou Gradle standard, cela correspond au répertoire : src/main/resources/db/migration/.

Vous devez créer ce répertoire et y placer tous vos fichiers de script SQL respectant la convention de nommage. Il est possible de configurer d'autres emplacements via les propriétés Spring Boot (spring.flyway.locations), mais classpath:db/migration est la convention la plus courante et recommandée.

La convention de nommage des migrations versionnées

Le format standard pour les scripts de migration dits "versionnés" (ceux qui ne sont exécutés qu'une seule fois par base de données dans un ordre précis) est le suivant :

V__.sql

Décortiquons chaque partie :

• V (Préfixe) : La lettre 'V' majuscule indique qu'il s'agit d'une migration versionnée standard. C'est le préfixe le plus courant. D'autres préfixes existent (comme U pour les migrations d'annulation/undo, moins utilisées, ou R pour les migrations répétables, voir section suivante).
• (Version) :
  • C'est l'identifiant unique de la version de la migration. Il est crucial pour l'ordonnancement.
  • Il peut être composé de chiffres séparés par des points (.) ou des underscores (_). Les underscores sont généralement préférés car ils facilitent le tri lexicographique correct (ex: V1_10__Desc.sql vient après V1_2__Desc.sql, alors qu'avec des points, V1.10 pourrait être trié avant V1.2 par certains systèmes).
  • Exemples de versions valides : 1, 2, 1_1, 1_2_1, 20240726110000 (basé sur un timestamp, utile pour éviter les conflits en équipe).
  • Flyway exécute les scripts dans l'ordre croissant de leur numéro de version.
• __ (Séparateur) : Deux underscores consécutifs séparent la version de la description. C'est un séparateur obligatoire.
• (Description) :
  • Un texte descriptif indiquant le but de la migration.
  • Utilisez des underscores (_) ou des espaces pour séparer les mots (les espaces sont autorisés mais les underscores sont plus courants et plus sûrs pour la compatibilité multi-systèmes). CamelCase est aussi possible.
  • La description n'affecte pas l'ordre d'exécution mais est stockée dans la table d'historique de Flyway et aide grandement à comprendre le contenu du script sans avoir à l'ouvrir.
  • Exemples : Create_user_table, Add_email_column_to_users, Insert_initial_roles.
• .sql (Suffixe) : L'extension du fichier indique qu'il s'agit d'un script SQL. Flyway supporte aussi des migrations basées sur des classes Java (préfixe V ou R, pas de suffixe .sql, mais c'est moins courant pour les changements de schéma classiques).

Exemples de noms de fichiers valides :

• V1__Initial_schema.sql
• V1_1__Create_users_table.sql
• V1_2__Create_orders_table.sql
• V2_0_1__Add_index_on_user_email.sql
• V20240726111500__Add_product_description_column.sql

Migrations répétables (Repeatable Migrations)

Outre les migrations versionnées qui ne s'exécutent qu'une fois, Flyway supporte également les migrations répétables. Celles-ci sont utiles pour gérer des objets de base de données qui peuvent être recréés ou mis à jour plusieurs fois, comme les vues, les procédures stockées, les fonctions, ou pour insérer/mettre à jour des données de référence.

La convention de nommage pour les migrations répétables est :

R__.sql

• R (Préfixe) : La lettre 'R' majuscule indique une migration répétable.
• __ (Séparateur) : Deux underscores.
• : Une description du contenu du script.
• .sql (Suffixe) : Extension SQL.

Fonctionnement :

• Les migrations répétables sont toujours exécutées après toutes les migrations versionnées en attente.
• Elles n'ont pas de version. Flyway les identifie par leur description et leur checksum (une somme de contrôle calculée à partir du contenu du fichier).
• Lors d'une migration, Flyway exécute une migration répétable si :
  • Elle n'a jamais été exécutée auparavant.
  • Son checksum a changé depuis la dernière exécution (ce qui signifie que le contenu du fichier a été modifié).
• Elles sont idéales pour maintenir la définition des vues, procédures, etc., à jour avec votre code applicatif.

Exemple : R__Create_or_update_user_summary_view.sql

Structure de répertoire exemple

Voici à quoi pourrait ressembler votre répertoire src/main/resources/db/migration/ :

src/main/resources/
└── db/
    └── migration/
        ├── V1__Initial_schema_baseline.sql
        ├── V1_1__Create_users_table.sql
        ├── V1_2__Create_products_table.sql
        ├── V1_3__Add_email_constraint_to_users.sql
        ├── V2_0__Create_orders_and_order_items_tables.sql
        ├── V2_1__Add_foreign_keys_for_orders.sql
        ├── R__Create_product_summary_view.sql
        └── R__Update_reference_data_categories.sql

Contenu des scripts SQL

A l'intérieur de chaque fichier .sql, vous placez les instructions SQL (DDL - Data Definition Language, comme CREATE TABLE, ALTER TABLE ; et DML - Data Manipulation Language, comme INSERT, UPDATE, DELETE) nécessaires pour effectuer la migration décrite.

Il est crucial que chaque script représente une étape atomique et cohérente de l'évolution de votre schéma. Par défaut, Flyway exécute chaque script de migration dans sa propre transaction (si la base de données le supporte), garantissant que soit l'ensemble du script réussit, soit il échoue et est annulé (rollback). Vous pouvez écrire plusieurs instructions SQL dans un seul fichier, séparées par des points-virgules (;) ou par le séparateur configuré (spring.flyway.sql-migration-separator).

Conclusion : La clé de l'automatisation par Flyway

La convention de nommage des scripts Flyway (V__.sql pour les migrations versionnées et R__.sql pour les répétables) est la pierre angulaire de son fonctionnement. Elle permet à l'outil d'ordonner, d'appliquer et de suivre les changements apportés à votre base de données de manière automatique et fiable. En plaçant vos scripts correctement nommés dans le répertoire src/main/resources/db/migration/, vous permettez à Spring Boot et Flyway de prendre en charge l'évolution de votre schéma de base de données de façon transparente au démarrage de l'application, assurant la cohérence entre votre code et la structure de la base à travers tous les environnements.