Intégration de Flyway ou Liquibase avec Quarkus et Hibernate

Objectifs

Dans cette leçon, nous allons intégrer d'abord Flyway pour présenter le concept de migration de schéma de base de données.

Flyway ou Liquibase

Flyway est un outil open-source de migration de base de données conçu pour simplifier et automatiser le processus de gestion des modifications de schéma. Il permet aux développeurs de versionner et d'appliquer les changements de schéma de manière itérative, garantissant ainsi la cohérence et la traçabilité des modifications dans différents environnements. Avec Flyway, les modifications de schéma sont définies sous forme de scripts SQL stockés dans un répertoire dédié à l'application. Lors du déploiement de l'application, Flyway détecte automatiquement les scripts non appliqués et les exécute séquentiellement dans l'ordre de leur version. Cela permet aux équipes de développement de gérer efficacement l'évolution de la structure de la base de données tout en préservant l'intégrité des données et en facilitant la collaboration entre les membres de l'équipe.

Liquibase est un outil open-source de gestion des modifications de schéma de base de données. Il permet aux équipes de développement de suivre et de gérer de manière transparente les modifications apportées à la structure de la base de données au fil du temps. Avec Liquibase, les développeurs peuvent définir les modifications de schéma sous forme de fichiers XML, YAML ou SQL, et les exécuter de manière cohérente sur différentes instances de base de données, quel que soit le système de gestion de base de données (SGBD) utilisé. Liquibase assure la traçabilité des modifications, ce qui facilite la collaboration entre les membres de l'équipe et garantit l'intégrité des données tout au long du cycle de vie de l'application.

Liquibase et Flyway sont deux outils populaires de gestion des migrations de base de données, chacun avec ses propres avantages et caractéristiques distincts.

Liquibase :

• Liquibase utilise des fichiers XML, YAML ou SQL pour définir les changements de schéma de la base de données.
• Il offre une flexibilité dans la définition des modifications, permettant l'utilisation de conditions, de préconditions et de changements complexes.
• Liquibase prend en charge une variété de bases de données, y compris Oracle, MySQL, PostgreSQL, SQL Server, et plus encore.
• Il fournit un suivi détaillé des modifications apportées à la base de données, ce qui facilite la collaboration entre les membres de l'équipe et la gestion des versions.

Flyway :

• Flyway utilise des scripts SQL pour définir les migrations de la base de données.
• Il suit un modèle de migration basé sur la version, où chaque migration est associée à un numéro de version.
• Flyway est simple à utiliser et facile à intégrer dans les pipelines de développement grâce à ses fonctionnalités de ligne de commande et de plug-ins pour les outils de développement.
• Il offre une approche conventionnelle et prévisible pour gérer les modifications de schéma, ce qui le rend idéal pour les projets nécessitant une gestion simplifiée des migrations.

En résumé, Liquibase est plus flexible et offre des fonctionnalités avancées pour la gestion des modifications de schéma, tandis que Flyway se concentre sur une approche plus simple et basée sur des conventions pour gérer les migrations de base de données.

Intégration de Flyway avec Quarkus et Hibernate

Nous allons nous baser sur la documentation de Flyway pour intégrer Flyway avec Quarkus et Hibernate et la documentation de l'extension Quarkus Flyway.

Commençons par importer les dépendances nécessaires :

Pour ajouter cette extension à votre projet, utilisez la commande appropriée dans le répertoire de votre projet Quarkus backend-monster-adoption-store:

Quarkus CLI

quarkus ext add io.quarkus:quarkus-flyway

Avec Maven

./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-flyway"

Nous devons également ajouter le driver pour PostgreSQL avec Flyway dans le fichier pom.xml du projet Maven :

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>    
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-flyway</artifactId>
</dependency>
<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-database-postgresql</artifactId>
</dependency>

Configuration de Flyway

En résumé, nous allons réaliser les modifications nécessaires pour intégrer Flyway avec Quarkus et Hibernate.

Comme indiqué dans la section "Développer avec Flyway", pour commencer à utiliser Flyway avec votre projet, vous devez simplement :

• Ajouter vos migrations au dossier src/main/resources/db/migration comme vous le faites habituellement avec Flyway.

• Activer l'option migrate-at-start pour migrer automatiquement le schéma ou injecter l'objet Flyway et exécuter votre migration comme d'habitude.

Ajout de votre schéma de migration Flyway

Si vous avez suivi les différents exercices sur Hibernate et notre projet backend-monster-adoption-store, voici un schéma pour Flyway qui devrait focctionner :

Créer le fichier V1.0.0__Adoption.sql dans le dossier src/main/resources/db/migration :

Attention au nommage, si le fichier est mal nommé, il sera ignoré par Flyway.

--
-- Table structure for table `monster`
--

CREATE TABLE monsters (
                         id serial PRIMARY KEY,
                         name varchar(255) NOT NULL,
                         description varchar(255) DEFAULT NULL,
                         image_url varchar(255) DEFAULT NULL,
                         monsterUUID varchar(255) DEFAULT NULL,                         
                         price  int DEFAULT NULL,
                         age int DEFAULT NULL,
                         location varchar(255) DEFAULT NULL,
                         monsterId  int DEFAULT NULL,
                         created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
                         updated_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP
);

Créez un second fichier avec le nom V1.0.1__Adoption.sql dans le dossier src/main/resources/db/migration :

--
-- Dumping data for table `monster`
--

Ajout des options de Flyway dans notre profile

Créer un fichier application-pgql.properties dans le dossier src/main/resources/ :

com.byoskill.adoptions.adapter=h2
# drop and create the database at startup (use `update` to only update the schema)
quarkus.hibernate-orm.active=true
quarkus.hibernate-orm.enabled=true
quarkus.hibernate-orm.database.generation=validate
quarkus.hibernate-orm.generate-ddl=true
quarkus.datasource.db-kind=postgresql
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/monster_adoption_store
quarkus.datasource.username=monster_adoption_store
quarkus.datasource.password=monster_adoption_store
quarkus.hibernate-orm.log.sql=true

# Telemetry + JDBC
quarkus.datasource.jdbc.telemetry=true

quarkus.flyway.enabled=true
quarkus.flyway.migrate-at-start=true

Afficher les informations de Flyway au démarrage

Maintenant, vous pouvez démarrer votre application et Quarkus exécutera la méthode migrate de Flyway en fonction de votre configuration. Avec quarkus.flyway.migrate-at-start=true, comme dans l'exemple ci-dessus, Quarkus exécutera la migration Flyway lors du démarrage de l'application.

@ApplicationScoped
public class MigrationService {
    // Vous pouvez injecter l'objet si vous voulez l'utiliser manuellement
    @Inject
    Flyway flyway;

    @PostConstruct
    public void checkMigration() {
        // Cela affichera 1.0.0
        System.out.println(flyway.info().current().getVersion().toString());
    }
}

Tester FlywayDB

Lancer un container avec la base de données PostgreSql et lancer la migration Flyway :

Voici un exemple de commande Docker pour lancer un container avec la base de données

docker run -d --name backend-monster-adoption-store-db \
  -e POSTGRES_USER=monster_adoption_store \
  -e POSTGRES_PASSWORD=monster_adoption_store \
  -e POSTGRES_DB=monster_adoption_store \
  -p 5432:5432 \
  postgres:15

Explication :

• docker run -d : Cela démarre le conteneur en mode détaché, ce qui signifie qu'il s'exécutera en arrière-plan.
• --name backend-monster-adoption-store-db : Cela donne un nom au conteneur, ce qui facilite sa gestion.
• -e POSTGRES_USER=monster_adoption_store : Cela définit le nom d'utilisateur pour la base de données PostgreSQL.
• -e POSTGRES_PASSWORD=monster_adoption_store : Cela définit le mot de passe pour la base de données PostgreSQL.
• -e POSTGRES_DB=monster_adoption_store : Cela définit le nom de la base de données PostgreSQL.
• -p 5432:5432 : Cela mappe le port 5432 du conteneur sur le port 5432 de l'hôte. Cela vous permet de vous connecter à la base de données depuis votre machine hôte à l'aide d'un client PostgreSQL.
• postgres:15 : Cela spécifie l'image à utiliser pour le conteneur. Dans ce cas, nous utilisons l'image officielle de PostgreSQL, version 15.

Remarque :

• Cette commande suppose que Docker est installé sur votre machine.
• Vous pouvez modifier les valeurs de POSTGRES_USER, POSTGRES_PASSWORD et POSTGRES_DB selon vos besoins.
• Vous pouvez également ajouter des variables d'environnement supplémentaires à la commande pour configurer davantage la base de données PostgreSQL.

Démarrer le backend avec une base de données Postgresql

mvn -Dquarkus.profile=dev,pgql -Dquarkus.http.port=8090 quarkus:dev

Configuration supplémentaire

Changer de schéma dans Quarkus

Il est possible de ne pas utiliser le schéma par défaut sous Postgresql et d'utiliser un schéma custom. Voici les modifications à apporter à votre fichier application-pgql.properties.

quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/monster_adoption_store?currentSchema=monsters
quarkus.flyway.default-schema=monsters

Ressources supplémentaires :

• Image Docker PostgreSQL
• Documentation PostgreSQL

Tester la migration

Lancez l'application avec le profile prod :

Vous devriez obtenir des logs comme suit :

  22:30:08 INFO  traceId=, parentId=, spanId=, sampled= [or.fl.co.in.co.DbValidate] (Quarkus Main Thread) Successfully validated 1 migration (execution time 00:00.015s)
  22:30:08 INFO  traceId=, parentId=, spanId=, sampled= [or.fl.co.in.co.DbMigrate] (Quarkus Main Thread) Current version of schema "public": << Empty Schema >>
  22:30:08 INFO  traceId=, parentId=, spanId=, sampled= [or.fl.co.in.co.DbMigrate] (Quarkus Main Thread) Migrating schema "public" to version "1.0.0 - Adoption"
  22:30:08 INFO  traceId=, parentId=, spanId=, sampled= [or.fl.co.in.co.DbMigrate] (Quarkus Main Thread) Successfully applied 1 migration to schema "public", now at version v1.0.0 (execution time 00:00.027s)

Références

• Flyway
• Liquibase
• https://quarkus.io/guides/flyway
• https://quarkus.io/extensions/io.quarkus/quarkus-flyway/