5 mars 2024 09:28:56 Pablo Abreu avatar
Home Edit History fr en

Utilisation du plugin Liquibase

Présentation

Liquibase

Liquibase est un outil open source pour la gestion et l'application des changements de base de données. Autrement dit, il s'agit d'un composant capable de lancer automatiquement les scripts SQL nécessaires au démarrage d'une application.

Le plugin liquibase de Lutece

Le plugin liquibase de Lutece est à intégrer dans le pom.xml votre application Lutece. L'utilisation qui est ici faite de liquibase diffère quelque peu d'une utilisation habituelle puisque sont gérées les particularités de Lutece :

  • Présence d'un core et de plugins
  • Scripts différenciés : createXXX.sql, initXXX.sql et updateXXX.sql

Dans l'esprit Lutece, les scripts createXXX.sql doivent comporter l'ensemble des modifications apportées par les versions successives d'un composant. Or liquibase, de façon générale, considère que les scripts SQL sont immuables et que les modifications se font exclusivement par ajout de nouveaux fichiers. C'est pourquoi le plugin liquibase Lutece intègre une logique particulière permettant de gérer ces différences.

Le plugin supporte ainsi plusieurs cas d'utilisation :

  • Création : en cas de toute première installation de l'application, la base de données est vide. Tous les scripts createXXX et initXX seront joués, mais pas les updateXXX.
  • Migration de l'application vers le plugin liquibase : en cas de première utilisation du plugin liquibase, la base de données sera mise à jour pour commencer l'utilisation du plugin.
    • Soit la migration ne concerne que l'ajout du plugin liquibase : il suffit de l'inclure.
    • Soit la migration, en plus d'intégrer le plugin liquibase, embarque d'autres nouveautés : il faudra alors passer quelques requêtes SQL manuellement au préalable.
  • Mise à jour : en cas de nouvelle version du core, de nouvelle version d'un plugin, ou d'ajout d'un nouveau plugin, les scripts adéquats seront exécutés dans le bon ordre.

Utilisation

Intégration

Rajoutez la dépendance suivante dans le pom.xml de votre application :

<dependency>
	<groupId>fr.paris.lutece.plugins</groupId>
	<artifactId>plugin-liquibase</artifactId>
	<version>1.0.0</version>
	<type>lutece-plugin</type>
</dependency>

Le plugin liquibase requiert une version minimale de lutece-core (7.0.11 au moment où ces lignes sont écrites), qu'il faut respecter.

Configuration

Le plugin liquibase est inactif par défaut. Pour l'activer, il faut déclarer la property suivante : 

liquibase.enabled.at.startup=true

Pré-requis

Voici la liste des pré-requis pour faire fonctionner le plugin liquibase avec succès :

  • Utiliser des versions compatibles du core et des plugins
  • Migrer vos propres scripts SQL

La migration de vos scripts peut être très simple :

Le plugin maven lutece inclut un utilitaire permettant d'ajouter des balises spécifiques à liquibase dans l'ensemble des scripts SQL de votre arborescence de code source. Il suffit de taper la commande suivante à la racine de votre projet: 

mvn fr.paris.lutece.tools:lutece-maven-plugin:liquibase-sql

L'absence des balises en question dans un fichier SQL fait qu'il sera ignoré par le processus de build maven de l'application, et qu'il ne sera donc pas joué au démarrage.

Pour que vos scripts puissent être pris en compte automatiquement au démarrage, ils doivent bien sûr être exempts d'erreurs. L'exécution de scripts via liquibase peut présenter un comportement différent qu'avec le précédent système utilisant ant : il est indispensable de bien tester sur un environnement de développement pour s'assurer que les scripts fonctionnent correctement.

Construction

Construisez votre site web de la même façon que d'habitude : 

mvn clean lutece:site-assembly -P dev
Cette commande va construire le .war du site en y incorporant les scripts SQL.

De façon optionnelle, vous pouvez utiliser un paramètre de ligne de commande supplémentaire pour spécifier le type de SGBD cible (mysql, oracle, postgresql, hsqldb, ou la valeur spéciale "auto", qui détermine le bon SGBD en lisant le contenu de votre fichier db.properties) : 

mvn clean lutece:site-assembly -P dev -DtargetDatabaseVendor=auto
Dans ce cas, les fichiers SQL seront modifiés avant incorporation au .war pour s'adapter au SGBD cible.

Dans le cas par défaut, les fichiers SQL sont incorporés sans modification. Ils seront alors adaptés à la volée au démarrage de votre site web en fonction du type réel de SGBD rencontré.

Exécution

Une fois votre application migrée, configurée, buildée, vous pourrez observer les traces suivantes au lancement : 

LiquibaseRunner starting
LiquibaseRunner ended

Les lignes présentes entre ces deux traces présentent les actions entreprises par le plugin liquibase pour mettre à jour la base de données.

Limites

Certains cas d'utilisation ne sont pas, et ne seront pas, supportés.

  • Support simultané de plusieurs pools de connexions => peu de besoins connus
  • Support de code SQL hors lutece-core et plugins => là aussi peu de besoins