Flyway — comment gérer vos migrations de base de données ?

Écrit par Pascal Niyitegeka

Qu’est-ce que Flyway ?

Flyway est un outil de migrations de base de données.

Avec la constante évolution de nos outils informatiques, nos modèles de données sont amenés à changer souvent. Flyway permet de gérer l’historique de ces changements.

C’est un logiciel open source qui nous aidera à historiser les modifications faites sur notre base de données. Que ça soit pour la création, modification ou suppression des tables, colonnes, séquences ou lignes dans notre base de données.

Création du Projet Spring Boot

Nous allons utiliser https://start.spring.io/ pour générer un squelette de notre projet avec les dépendances nécessaires pour ce projet.

Les dépendances nécessaires :

• Spring Web
• Lombok
• Flyway Migration
• PostgresSQL Driver
• Spring Data JPA

Dépendences Demo FLyway à partir de start.spring.io

Notre projet, ouvert sur Intellij IDEA, ressemblera à ceci

Définitions des propriétés

Nous allons renommer notre fichier application.properties à application.yml. Ceci facilitera la lecture des propriétés.

Dans ce fichier, nous commençons par définir quel pattern utiliser pour nos messages de logs, puis les connexions à notre base de données puis nous finissons avec les propriétés flyway.

1. locations : Dossier contenant l’ensemble de nos scripts à exécuter dans la base de données.
2. out-of-order : Permettra d’exécuter les scripts par désordre de version. Si nous avons déjà migré des données d’une version 1.0 et 3.0 et que plus tard nous ajoutons une version 2.0. La version 2.0 s’exécutera sans souci. Dans notre cas, cette valeur sera à false. Nous souhaitons que les scripts soient supérieurs à la dernière version. Si 3.0 est la dernière version, le 2.0 ne sera pas exécuté.
3. baseline-on-migrate : permet de créer la table flyway_schema_history si celle-ci n’existe pas dans notre base de données. C’est ici qu’on va trouver tous les scripts exécutés par Flyway

Création Modèle

Nous créons ensuite notre modèle en utilisant lombok pour générer les getter (@Getter) et setter(@Setter).

@Entity pour dire que c’est une classe à persister.

@Table pour définir le nom de la table. Notre table ayant le même nom que cet objet, il est inutile de définir le variable name (@Table(name=’’utilisateur’’))

@SequenceGenerator pour définir la séquence à exécuter quand on insère des données dans cette table

Nommage des scripts Flyway

Nous procédons par créer ensuite le script sql qui permettra de créer notre table Utilisateur.

Nous le positionnerons dans le dossier resources/db/migration. C’est là où flyway ira chercher scripts sql.

Le nommage des scripts est la suivante :

V1__creation_table_utilisateur.sql

1. Préfixe : V pour la version
2. Numéro de version : il peut être sur un digit ou plusieurs, séparé par des points. Ex : 1.12.32.0.98
3. Séparateur : 2 underscores (2 tirets du 8) entre le numéro de version et la description
4. Description : Séparer avec des underscores pour séparer les mots. Il est important de le nommer avec l’action des requêtes qui est comprise dans le fichier. Lors de l’exécution, flyway retira les underscores, ce qui en fera un message plus lisible et compréhensible pour toute personne qui ira lire la table d’historisation.
5. Suffixe : .sql

Lancement de l’application

Le lancement de l’application nous montre qu’une nouvelle table flyway_schema_history a été créé.

C’est là où nous allons retrouver l’ensemble des scripts exécutés avec Flyway.

Nous remarquons que la version commence à 1. Ce qui correspond à la création de la table utilisateur.

Nous retrouvons la table d’historisation des exécutions flyway au nom

flyway_schema_history avec la 1er ligne qui correspond à notre 1er script créé au-dessus.

Cette table est composée des champs suivants :

1. Installed_rank : order d’execution des scripts
2. Version : version présente dans le nom du script
3. Description : définit aussi dans le nom du script avec les underscores enlevé pour faciliter la lecture
4. Type : le type de fichier exécuter. Dans notre, cas un SQL
5. Script : le nom complet du script
6. Checksum : générer automatiquement pour assurer que les scripts de migration n’ont pas été modifiés depuis leurs dernières exécutions. Il faudra créer un nouveau script si on souhaite modifier la table utilisateur en ajoutant un champ Ex : V1.0.1_ajouter_colonne_age_dans_table_utilisateur.sql
7. Installed_by : quel utilisateur a lancé la migration des données
8. Execution_time : temps d’exécution
9. Success : état de réussite de l’exécution du script

Nous retrouvons aussi notre table Utilisateur.

Si on relance l’application, flyway n’exécutera pas le script de « V1__creation_table_utilisateurs.sql » car il est déjà présent dans la table d’historique.

À chaque relance de l’application, il vérifiera les scripts dans le dossier db/migration et celle dans la table (flyway_schema_history) pour savoir quels scripts manque et les exécute.

Ajout d’autres scripts flyway

Si on ajoute un nouvel script au nom de « V2__creation_table_voyage.sql », on obtiendra ceci :

La version de la base de données est passée à 2.

Il faut noter que le numéro de version de nos scripts doit s’incrémenter.

Nos futurs scripts devront commencer avec le préfixe « V3 » ou bien « V2.0.1 »

Si nous ajoutons un script avec une version inférieure (ex : V1.0.32__creation_table_charette.sql) à celle présente dans la table d’historique, flyway générera une exception et n’exécutera pas la requête.

Tout au long du cycle de vie de notre projet, nos modèles de données vont évoluer. Flyway nous permet de mettre à jour ces données tout en gardant un historique de ces changements

Il suffira de créer un nouveau script.

Exemple :

Si on souhaite ajouter le prix dans notre objet Voyage cela donnera ceci

On crée un nouveau Script avec le nom suivant V2.0.1__ajouter_prix_dans_table_voyage.sql avec le contenu suivant

alter table voyage
add column prix numeric null;

Nous modifions notre Objet voyage en ajoutant le champ

private BigDecimal prix;

On obtient ceci au lancement de l’application :

La table d’historisation a les informations sur les scripts de l’ajout du champ prix.

La table voyage a le nouveau champ prix.

Structure final du Projet

Conclusion

Nous avons vu comment utiliser flyway pour garder l’historique des scripts exécuter sur notre base de données. Avoir l’ensemble des scripts dans un seul dossier nous permettra facilement de déployer l’application sur différents environnements. Il suffira juste de lancer l’application sur un environnement de DEV, RECETTE, PRODUCTION ou même Docker.