Prendre un thé
Tapoter des doights
Monsieur fantôme
Quelle heure est-il ?
BazinGa's Tips & tuto IT
BazinGa's - Tips & tuto IT

Flyway – Maitrisez la mise à jour de vos BDD

1 – Introduction

Flyway est un programme de migration de base de données. Il permet la création, la mise à jour, la validation et la rétro mise à jour de bases de données.

Son utilisation se fait en ligne de commande et permet l’utilisation de script SQL et JAVA.

Les bases de données supportées sont (entre autres) :

  • PostgreSQL
  • MySQL
  • Oracle
  • MariaDB
  • SQL Server
  • SQLite

Attention, selon la version de Flyway, il n’est pas possible de se connecter à certaines versions des BDD.

Dans Flyway, une migration correspond à une initialisation, une montée de version ou une descente de version d’un ou plusieurs schémas d’une base de données.

Cette documentation est basée sur la version 5 de Flyway.

2 – Installation

L’installation est simple : il n’y en a pas, le programme est portable.

Vous pouvez le télécharger sur le site officiel : https://flywaydb.org/download/

Si vous souhaitez d’autres version, rendez-vous ici : https://repo1.maven.org/maven2/org/flywaydb/flyway-commandline/

3 – Utilisation

L’utilisation se fait en 3 temps :

  • D’abord la configuration de Flyway.
  • Ensuite la création d’un script de migration contenant les instructions SQL.
  • Enfin la migration.

Il existe 3 types de migration :

  • Les migrations versionnées : c’est la montée de version d’une BDD.
  • Les migrations d’annulation : c’est l’inverse de la précédente, les instructions vont annuler ce qui a été fait précédemment (très peu utilisé et uniquement dans la version payante mais il suffit d’utiliser les migrations versionnées en adaptant la description).
  • Les migrations répétables : ce sont des migrations qui vont être répétées à chaque fois qu’une migration versionnée est appliquée où qu’un élément de la BDD change.

3.1 – Configuration

Flyway n’a pas besoin d’être installé, il suffit simplement de placer son répertoire là où bon vous semble.

Il faut ensuite créer un fichier de configuration dédié à votre base de données et à sa gestion (vous pouvez ainsi avoir plusieurs fichiers de configuration si vous gérez en parallèle plusieurs bases). Le fichier de configuration est stocké dans le répertoire suivant : /conf/ma_configuration.conf

Ce fichier peut être commenté en débutant la ligne par un dièse (#).

Vous pouvez y inclure les paramètres suivants (entre autres) :

  • Connexion à la base de données :
    • url=jdbc:postgresql://127.0.0.1:5432/ma_bdd
    • url=jdbc:mysql:// 127.0.0.1:5432/ma_bdd
    • url=jdbc:oracle:thin:@// 127.0.0.1:1521/ma_bdd
  • User à utiliser pour la connexion :
    • user=
  • Mot de passe à utiliser lors de la connexion :
    • password=
  • Schéma(s) géré(s) par Flyway (le premier schéma est le schéma par défaut qui contiendra notamment la table d’historique) :
    • schemas=mon_schema,mon_schema_2
  • Nom de la table d’historique :
    • table= flyway_schema_history
  • Localisation des scripts :
    • locations=classpath:./sql/mon_arborescence/
    • locations=filesystem:C:/mon_arborescence/sql/
  • Préfixe du nom des fichiers de migration SQL ( défaut : V)
    • sqlMigrationPrefix=
  • Séparateur du nom des fichiers de migration SQL (défaut : __, double underscore)
    • sqlMigrationSeparator=
  • Suffixe des fichiers de migration SQL (défaut : .sql)
    • sqlMigrationSuffixes=
  • Variable pouvant être utilisée dans les scripts :
    • placeholders.nom_variable=ma_valeur
  • Préfixe des variables utilisées dans les scripts (défaut : ${) :
    • placeholderPrefix=
  • Suffixe des variables utilisées dans les scripts (défaut : }) :
    • placeholderSuffix=
  • Version jusqu’à laquelle Flyway doit faire migrer la BDD (défaut : <<latest version>>) :
    • target=
  • Version à tagger au schéma lors de l’exécution de la baseline (voir le paragraphe 3.3.1 – Principe) (défaut : 1) :
    • baselineVersion=
  • Description à tagger au schéma lors de l’exécution de la baseline (voir le paragraphe 3.3.1 – Principe) (défaut : << Flyway Baseline >>) :
    • baselineDescription=
  • Autoriser les migrations périmée à être exécutée (par exemple : les migrations 1 et 3 ont déjà été appliquées et une migration 2 est découverte, alors elle sera appliquée au lieu d’être ignorée) (défaut : false) :
    • outOfOrder=
  • Ignorer les migrations manquante lors de l’exécution (par exemple : les migrations 1, 2 et 3 sont répertoriées dans la table d’historisation mais la migration 2 n’est pas présente dans le répertoire de script) (défaut : false) :
    • ignoreMissingMigrations=
  • Ignorer les migrations futures lors de l’exécution (par exemple : les migrations 1 à 4 répertoriées dans la table d’historisation mais la migration 4 n’est pas présente dans le répertoire de script) (défaut : true) :
    • ignoreFutureMigrations=
  • Nom d’utilisateur à utiliser dans la table d’historisation lors de la migration (défaut : <<blank>>) :
    • installedBy=

3.2 – Script de migration

Le script de migration contient l’ensemble des instructions de migration de la base.

Il est important de bien versionner chaque script et de les décrire. Pour cela, les scripts doivent suivre la règle de nommage suivante :

V1.0.0__Mon_script.sql

Avec :

  • Le préfixe: V pour versionné, U pour undo (annuler) et R pour répétable.
  • La version(sauf avec le préfixe R qui n’a pas de version) : par exemple :
    • 1
    • 001
    • 2
    • 2.3.4.5.6.7.8.9
    • 68
    • 20130115113556
    • 1.15.11.35.56
    • 01.15.11.35.56
  • Le séparateur : __, double underscore (qui peut être modifié dans la configuration).
  • La description: qui sera renseignée dans la table d’historisation.
  • Le sufixe : .sql, celui-ci peut être modifié dans la configuration (même s’il contient des instructions SQL).

Ces scripts se placent dans les répertoires suivants :

  • script SQL : /sql/mon_script.sql
  • Script Java : /jar/mon_java.jar

Vous pouvez créer votre propre arborescence. Il faudra simplement indiquer où chercher vos fichiers dans la configuration (voir paragraphe 3.2 – Configuration).

Les scripts peuvent contenir des variables. Celles-ci sont définies dans le fichier de configuration et prennent ainsi la valeur qui leur a été attribuée. La variable doit avoir cette forme (modifiable via le fichier de conf) dans le script :

${ma_variable}

3.2.1 – Script d’initialisation

Ce script permet de créer la structure du modèle de données. Vous pourrez également y ajouter des instructions pour ajouter des valeurs de référence…

Voici un exemple de script d’initialisation :

CREATE TABLE table_1 (
    id serial NOT NULL PRIMARY KEY,
    champ_1 varchar(10),
    champ_2 varchar,
    geom geometry(polygon,${srid})
);

CREATE TABLE table_ref (
    id serial NOT NULL PRIMARY KEY,
    code varchar(10),
    denomination varchar
);


INSERT INTO table_ref (
    code,
    denomination
)
VALUES
    ('CODE_01', 'Valeur A'),
    ('CODE_02', 'Valeur B'),
    ('CODE_03', 'Valeur C')
;

Ce script sera enregistrer dans le fichier V1.0.0__Initialisation.sql (mais on aurait pu choisir tout autre nom).

Une variable est utilisée pour définir le système de coordonnées de la colonne géométrique. La valeur sera définie dans le fichier de configuration sous la forme suivante :

flyway.placeholders.srid=2154

Le script présenté ne fait jamais mention du schéma dans lequel il va s’exécuter. Ceci indique que les instructions seront exécutées dans le schéma par défaut, le premier schéma mentionné par l’option flyway.schemas dans le fichier de configuration. Il est tout à fait possible de mentionner le schéma d’exécution de deux façons :

  • En dur : CREATE TABLE mon_schema.table_1
  • Avec une variable définie dans la configuration : CREATE TABLE ${schema_variable}.table_1

La dernière version permet d’appliquer le script de migration sur différents schémas, dans des environnements différents.

3.2.2 – Script de montée de version

Ce script permet de faire évoluer la base.

Voici un exemple de script de montée de version :

ALTER TABLE table_1
ADD CONSTRAINT table_1_champ_1_table_ref_fkey FOREIGN KEY (champ_1)
      REFERENCES table_ref (code) MATCH SIMPLE
      ON UPDATE CASCADE ON DELETE CASCADE
;

Ce script sera enregistrer dans le fichier V1.0.1__Ajout_cle_etrangere.sql (mais on aurait pu choisir tout autre nom, il faut simplement débuter par le n° de version).

La même règle que précédemment s’applique pour la mention du schéma.

3.3 – Utilisation

3.3.1 – Principe

Une fois vos scripts créés et placés au bon endroit ainsi que votre fichier de configuration créé, vous pouvez lancer les migrations.

Flyway s’utilise en ligne de commande. Il faut ainsi se placer dans le répertoire de celui-ci ou ajouter son chemin dans le PATH. Il suffit ensuite de respecter la syntaxe suivante :

flyway [options] commande [flag]

En fonction de la commande, différentes options sont disponibles.

Voici les commandes disponibles :

  • migrate : migrer un schéma.
  • clean : vider complètement un schéma.
  • info : obtenir la liste des migrations effectuées.
  • validate : vérifier que le schéma correspond bien aux scripts de migration disponibles.
  • baseline : attribuer un numéro de version à un schéma préexistant.
  • repair : réparer la table d’historisation pour qu’elle corresponde au schéma existant.

Retenez que la « baseline » correspond à la version 1 du schéma. Cette première version correspond soit à la création initiale de votre modèle de donnée, soit à une attribution ponctuelle sur un schéma préexistant lui permettant d’intégrer le cycle de mise à jour sous Flyway.

3.3.2 – Les options

Les options doivent être rédigées sous cette forme :

flyway -MonOption=Ma_valeur,Ma_valeur2 -MonOption2=Ma_valeur command

L’option suivante est disponible pour toutes les commandes et permet de spécifier un fichier de configuration spécifique (plusieurs fichiers peuvent être indiqués pour lancer plusieurs migrations en même temps) :

-configFiles=chemin/vers/mon_fichier.conf,chemin2/vers/mon_fichier2.conf

Pour Flyway 4.2 (pas de s à la fin de configFile) :

-configFile=chemin/vers/mon_fichier.conf,chemin2/vers/mon_fichier2.conf

Les options sont les mêmes que celles disponibles pour le fichier de configuration (ce dernier devra être adapté en fonction de la commande utilisée et donc des options disponibles).
Pour chaque option, la liste des commande dans lesquelles elle peut être utilisée est indiquée en utilisant le code suivant :

  • migrate : M
  • clean : C
  • info : I
  • validate : V
  • baseline : B
  • repair : R
  • Connexion à la base de données (M-C-I-V-B-R) :
    • -url=jdbc:postgresql://127.0.0.1:5432/ma_bdd
    • -url=jdbc:mysql://127.0.0.1:5432/ma_bdd
    • -url=jdbc:oracle:thin:@//127.0.0.1:1521/ma_bdd
  • User à utiliser pour la connexion (M-C-I-V-B-R) :
    • -user=
  • Mot de passe à utiliser lors de la connexion (M-C-I-V-B-R) :
    • -password=
  • Schéma(s) géré(s) par Flyway (le premier schéma est le schéma par défaut qui contiendra notamment la table d’historique) (M-C-I-V-B-R) :
    • -schemas=mon_schema,mon_schema_2
  • Nom de la table d’historique (défaut : flyway_schema_history ou schema_version) (M–I-V-B-R) :
    • -table=
  • Localisation des scripts (M–I-V–R) :
    • Pour les jars :
    • -locations=classpath:./sql/mon_arborescence/
    • Pour les sql :
    • -locations=filesystem:C:/chemin/vers/script/sql/mon_arborescence/
  • Préfixe du nom des fichiers de migration SQL (défaut : V) (M–I-V–R):
    • -sqlMigrationPrefix=
  • Séparateur du nom des fichiers de migration SQL (défaut __, double underscore) (M–I-V–R):
    • -sqlMigrationSeparator=
  • Suffixe des fichiers de migration SQL (défaut : .sql) (M–I-V–R):
    • -sqlMigrationSuffixes=
  • Variable pouvant être utilisée dans les scripts (M–I-V–R) :
    • -placeholders.nom_variable=ma_valeur
  • Préfixe des variables utilisées dans les scripts (défaut : ${) (M–I-V–R) :
    • -placeholderPrefix=
  • Suffixe des variables utilisées dans les scripts (défaut : } )(M–I-V–R) :
    • -placeholderSuffix=
  • Version jusqu’à laquelle Flyway doit faire migrer la BDD (défaut : <<latest version>>) (M–I-V–) :
    • -target=
  • Version à tagger au schéma lors de l’exécution de la baseline (défaut : 1) (M—-B-) :
    • -baselineVersion=
  • Description à tagger au schéma lors de l’exécution de la baseline (défaut : << Flyway Baseline >>) (M—-B-) :
    • -baselineDescription=
  • Autoriser les migrations périmée à être exécutée (par exemple : les migrations 1 et 3 ont déjà été appliquées et une migration 2 est découverte, alors elle sera appliquée au lieu d’être ignorée) (défaut : false) (M–I-V–) :
    • -outOfOrder=
  • Ignorer les migrations manquante lors de l’exécution (par exemple : les migrations 1, 2 et 3 sont répertoriées dans la table d’historisation mais la migration 2 n’est pas présente dans le répertoire de script) (défaut : false) (M—V–) :
    • -ignoreMissingMigrations=
  • Ignorer les migrations futures lors de l’exécution (par exemple : les migrations 1 à 4 répertoriées dans la table d’historisation mais la migration 4 n’est pas présente dans le répertoire de script) (défaut : true) (M—V–) :
    • -ignoreFutureMigrations=
  • Nom d’utilisateur à utiliser dans la table d’historisation lors de la migration (défaut : <<blank>>) (M—–) :
    • -installedBy=

3.3.3 – Les drapeaux

Vous pouvez spécifier certains drapeaux :

  • -n: connexion anonyme à la base
  • -X: sortir les logs de débug
  • -q: aucune sortie

3.3.4 – La table d’historisation

Nommée par défaut flyway_schema_history (ou schema_version dans Flyway < 5.0) cette table contient la liste des migrations effectuées.

C’est sur cette table que s’appuie Flyway pour savoir s’il doit faire évoluer la base de donnée en comparant la liste des migrations effectuées avec la liste des scripts de migration disponible en se basant sur le nom du script et son checksum.

3.3.5 – Erreur de migration

Deux types d’erreurs principales peuvent être remontés lors d’une migration :

L’erreur SQL :

Le script ne s’applique pas correctement en raison d’un problème de droit, d’une erreur dans le script…

Flyway fait remonter l’erreur ce qui permet alors de la corriger. Les modifications apportées par le script ne sont alors pas appliquées.

La table d’historisation indique alors 0 dans la colonne success.

Vous avez alors deux choix :

  • Corriger votre script et relancer le flyway.
  • Corriger la BDD et indiquer la valeur 1 dans le champ success de la ligne correspondant à la migration en question (mais c’est vrai très sale de faire comme ça).
L’erreur de checksum :

Cette erreur survient si l’un des scripts de migration déjà utilisé a été modifié. Dans ce cas, Flyway le détecte et empêche toute nouvelle migration tant que le problème n’est pas résolu.

Vous avez alors deux choix :

  • Remettre le script initial en place.
  • Modifier la valeur de checksum stockée dans la table d’historisation en la remplaçant par la valeur du checksum du nouveau fichier qui est fourni par Flyway lors de la remontée de l’erreur.
    Attention à bien répercuter les modifications faites dans le fichier dans votre BDD.

4 – Migration répétées

Si vous faite souvent des migrations ou des créations de base de données, vous pouvez créer un fichier .bat afin de lancer rapidement Flyway.

Voici simplement ce qu’il devra contenir :

C:/chemin/vers/flyway -configFiles=conf1.conf,conf2.conf,conf3.conf migrate


Cet article vous a plu ?

N'hésitez pas à le partager, il interessera surement certains de vos contacts.

Les thèmes suivants contiennent des articles en lien avec celui-ci, allez faire un tour :

OraclePostgreSQL

50%