Migrations de base de données avec Flyway

1. introduction

Cet article décrit les concepts clés deFlyway et comment nous pouvons utiliser ce framework pour remodeler en continu le schéma de base de données de notre application de manière fiable et simple. À la fin, nous présenterons un exemple de gestion d'une base de données H2 en mémoire à l'aide d'un plugin Maven Flyway.

Flyway met à jour une base de données d'une version à une autre à l'aide des migrations. Nous pouvons écrire des migrations soit en SQL avec une syntaxe spécifique à la base de données, soit en Java pour des transformations de base de données avancées.

Les migrations peuvent être versionnées ou répétées. Le premier a une version unique et est appliqué exactement une fois. Ce dernier n'a pas de version. Au lieu de cela, ils sont (ré) appliqués à chaque fois que leur somme de contrôle change.

Dans une seule migration, les migrations répétables sont toujours appliquées en dernier, après l'exécution des migrations versionnées en attente. Les migrations répétables sont appliquées dans l'ordre de leur description. Pour une migration unique, toutes les instructions sont exécutées dans une transaction de base de données unique.

Dans cet article, nous nous intéressons principalement à l'utilisation du plug-in Maven pour effectuer des migrations de bases de données.

2. Plugin Flyway Maven

Pour installer un plugin Flyway Maven, ajoutez la définition de plugin suivante à vospom.xml:


    org.flywaydb
    flyway-maven-plugin
    4.0.3

Vous pouvez vérifier la dernière version du plugin disponible surMaven repository.

Ce plugin Maven peut être configuré de quatre manières différentes. Veuillez vous référer auxdocumentation pour obtenir une liste de toutes les propriétés configurables.

2.1. Configuration du plugin

Nous pouvons configurer le plugin directement en utilisant la balise<configuration> dans la définition du plugin despom.xml:


    org.flywaydb
    flyway-maven-plugin
    4.0.3
    
        databaseUser
        databasePassword
        
            schemaName
        
        ...

2.2. Propriétés Maven

Nous pouvons également configurer le plugin en spécifiant des propriétés configurables comme Mavenproperties danspom.xml:


    ...
    
        databaseUser
        databasePassword
        schemaName
        ...
    
    ...

2.3. Fichier de configuration externe

Nous pouvons également fournir la configuration du plugin dans un fichier.properties séparé:

flyway.user=databaseUser
flyway.password=databasePassword
flyway.schemas=schemaName
...

Le nom du fichier de configuration par défaut estflyway.properties et doit résider dans le même répertoire que le fichierpom.xml. Le codage est spécifié parflyway.encoding (la valeur par défaut estUTF-8).

Si vous utilisez un autre nom (par exemplecustomConfig.properties) comme fichier de configuration, il doit être spécifié explicitement lors de l'appel de la commande Maven:

$ mvn -Dflyway.configFile=customConfig.properties

2.4. Propriétés du système

Enfin, toutes les propriétés de configuration peuvent également être spécifiées en tant que propriétés système lors de l'appel de Maven sur la ligne de commande:

$ mvn -Dflyway.user=databaseUser -Dflyway.password=databasePassword
  -Dflyway.schemas=schemaName

Voici un ordre de priorité lorsqu'une configuration est spécifiée de plusieurs manières:

Propriétés du système
Fichier de configuration externe
Propriétés Maven
Configuration du plugin

3. Exemple de migration

Dans cette section, nous passons en revue les étapes requises pour migrer un schéma de base de données vers une base de données H2 en mémoire à l'aide du plug-in Maven. Nous utilisons un fichier externe pour configurer Flyway.

3.1. Mettre à jour le POM

Ajoutez une dépendance de pilote de base de données appropriée pour la base de données H2 dans lespom.xml:


    com.h2database
    h2
    1.4.196

Vous pouvez vérifier la dernière version du pilote disponible surMaven repository. Ajoutez le plugin Flyway àpom.xml comme expliqué dans la section 2 ci-dessus.

3.2. Configurer Flyway à l'aide d'un fichier externe

Créez un fichiermyFlywayConfig.properties en$PROJECT_ROOT avec le contenu suivant:

flyway.user=databaseUser
flyway.password=databasePassword
flyway.schemas=app-db
flyway.url=jdbc:h2:mem:DATABASE
flyway.locations=filesystem:db/migration

La configuration ci-dessus spécifie que nos scripts de migration se trouvent dans le répertoiredb/migration. Il se connecte à une instance H2 en mémoire en utilisantdatabaseUser etdatabasePassword.

Le schéma de la base de données d'application estapp-db. Veuillez remplacerflyway.user, flyway.password, flyway.url par votre nom d'utilisateur de base de données, votre mot de passe de base de données et votre hôte / port de base de données de manière appropriée.

3.3. Définir la première migration

Flyway adhère à la convention de dénomination suivante pour les scripts de migration:

<Prefix><Version>_ .sql_

Où:

<Prefix> - Le préfixe par défaut estV, qui peut être configuré dans le fichier de configuration ci-dessus à l'aide de la propriétéflyway.sqlMigrationPrefix.
<Version> - Numéro de version de migration. Les versions majeures et mineures peuvent être séparées par ununderscore. La version de migration doit toujours commencer par 1.
<Description> - Description textuelle de la migration. La description doit être séparée des numéros de version par un double trait de soulignement.

Exemple:V1_1_0__my_first_migration.sql

Créez un répertoiredb/migration dans$PROJECT_ROOT avec un script de migration nomméV1_0__create_employee_schema.sql contenant des instructions SQL à créer, par ex. une table d'employé:

CREATE TABLE IF NOT EXISTS `employee` (

    `id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `name` varchar(20),
    `email` varchar(50),
    `date_of_birth` timestamp

)ENGINE=InnoDB DEFAULT CHARSET=UTF8;

3.4. Exécuter les migrations

Appelez la commande Maven suivante à partir de$PROJECT_ROOT pour exécuter les migrations de base de données:

$ mvn clean flyway:migrate -Dflyway.configFile=myFlywayConfig.properties

Cela devrait aboutir à une première migration réussie. Le schéma de base de données peut maintenant être décrit comme suit:

employee:
+----+------+-------+---------------+
| id | name | email | date_of_birth |
+----+------+-------+---------------+

Répétez les étapes des sous-sections 3.3. et 3.4. définir et exécuter de nouvelles migrations à volonté.

3.5. Définir et exécuter la deuxième migration

Créez un deuxième fichier de migration avec le nomV2_0_create_department_schema.sql contenant les deux requêtes suivantes:

CREATE TABLE IF NOT EXISTS `department` (

`id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,
`name` varchar(20)

)ENGINE=InnoDB DEFAULT CHARSET=UTF8;

ALTER TABLE `employee` ADD `dept_id` int AFTER `email`;

Exécutez une migration similaire à celle mentionnée dans la section 3.4 ci-dessus. Le schéma de base de données ressemble à ce qui suit après avoir exécuté avec succès la deuxième migration.

employee:
+----+------+-------+---------+---------------+
| id | name | email | dept_id | date_of_birth |
+----+------+-------+---------+---------------+

department:
+----+------+
| id | name |
+----+------+

Nous pouvons maintenant vérifier que les deux migrations ont bien abouti en appelant la commande Maven suivante:

$ mvn flyway:info -Dflyway.configFile=myFlywayConfig.properties

4. Comment fonctionne Flyway

Pour savoir quelles migrations ont déjà été appliquées, quand et par qui, une table de comptabilité spéciale est ajoutée à votre schéma. Cette table de métadonnées suit également les sommes de contrôle de la migration et détermine si les migrations ont abouti ou non.

L'infrastructure effectue les étapes suivantes pour s'adapter aux schémas de base de données en évolution:

Il vérifie un schéma de base de données pour localiser sa table de métadonnées (SCHEMA_VERSION par défaut). Si la table de métadonnées n’existe pas, elle en créera une.
Il analyse un chemin d'accès aux classes pour les migrations disponibles.
Il compare les migrations à la table de métadonnées. Si un numéro de version est inférieur ou égal à une version marquée actuelle, elle est ignorée.
Il marque toutes les migrations restantes en tant que migrations en attente. Ceux-ci sont triés en fonction du numéro de version et sont exécutés dans l'ordre
Au fur et à mesure que chaque migration est appliquée, la table de métadonnées est mise à jour en conséquence

5. Commandes

Flyway prend en charge les commandes de base suivantes pour gérer les migrations de bases de données.

Info: Imprime l'état / la version actuelle d'un schéma de base de données. Il indique quelles migrations sont en attente, quelles migrations ont été appliquées, quel est le statut des migrations appliquées et à quel moment elles ont été appliquées.
Migrate: Migre un schéma de base de données vers la version actuelle. Il analyse le chemin d'accès aux classes pour rechercher les migrations disponibles et applique les migrations en attente.
Baseline: Baseline une base de données existante, à l'exclusion de toutes les migrations, y comprisbaselineVersion. Baseline aide à démarrer avec Flyway dans une base de données existante. Les nouvelles migrations peuvent ensuite être appliquées normalement.
Validate: Valide le schéma de base de données actuel par rapport aux migrations disponibles.
Repair: Répare la table de métadonnées.
Clean: Supprime tous les objets dans un schéma configuré. Tous les objets de base de données sont supprimés. Bien sûr, vous ne devriez jamais utiliser clean sur une base de données de production.

6. Conclusion

Dans cet article, nous avons montré comment Flyway fonctionne et comment nous pouvons utiliser ce framework pour remodeler de manière fiable notre base de données d'applications.

Le code accompagnant cet article est disponible surGithub.

TOC

Migrations de base de données avec Flyway