6 janv. 2026, 10:22:37

François-Eric Merlin

Utilisation du plugin Liquibase

Table des matières

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 de 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-SNAPSHOT</version>
    <type>lutece-plugin</type>
</dependency>

Le plugin liquibase requiert une version minimale de lutece-core (7.1.4-SNAPSHOT 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

par défaut le plugin liquibase gère les versions SNAPSHOT,BETA,RC, ALPHA de la même manière que les versions stables en ne fournissant pas à liquibase au démarrage de l’application les scripts d’update des versions courantes. Pour permettre de prendre en compte des modification sur les scripts d’update de version non stable il faut activer les propriétés suivante

#true pour qu'à chaque démarrage de l'application les fichiers d'updates des versions courantes soit transmis à liquibase. Cette propriété est prise en compte uniquement pour les versions BETA,RC,ALPHA
liquibase.accept.unstable.versions=false

#true pour qu'à chaque démarrage de l'application les fichiers d'updates des versions courantes soit transmis à liquibase.
Cette propriété est prise en compte uniquement pour la version SNAPSHOT
liquibase.accept.snapshot.versions=false

#true pour activer le mode dry run afin de générer un script SQL au lieu d'appliquer les modifications à la base de données
liquibase.dryrun=false

Par défaut le plugin liquibase charge la propriété liquibase.readyToRun pour déterminer si les scripts sql peuvent être fournies au moteur liquibase. cette propriété est valoriseé au build du site dans le fichier WEB-INF/classes/META-INF/microprofile-config.properties dans le cas ou vous souhaitez que cette propriété ne soit pas prise en compte par le plugin il faudra valoriser la propriété liquibase.safeRun à false (cas d’un site comportant des composants lutece non migrés vers liquibase)

liquibase.safeRun=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 global pom du plugin doit être en version minimal 7.0.2

   <parent>
        <artifactId>lutece-global-pom</artifactId>
        <groupId>fr.paris.lutece.tools</groupId>
        <version>7.0.2</version>
    </parent>

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 lutece: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.

Avertissement : 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.

Cas d’une mise à jour d’un script d’update

Dans le cas ou un script d’update d’un composant doit être modifié, il faut que ces modifications se fassent dans un changeset dédié. exemple si il y a besoin d’ajouter des ordres sql au fichier update_db_lutece_core-7.1.0-7.1.1.sql ci dessous

--  liquibase formatted sql
--  changeset core:update_db_lutece_core-7.1.0-7.1.1.sql
--  preconditions onFail:MARK_RAN onError:WARN
--
-- Switch tinymce to tinymce6
--
INSERT INTO core_text_editor VALUES ('tinymce6', 'portal.admindashboard.editors.labelBackTinyMCE6', 1);
UPDATE core_datastore SET entity_value='tinymce6' where entity_key ='core.backOffice.defaultEditor' and entity_value = 'tinymce';
DELETE FROM core_text_editor WHERE editor_name='tinymce';

il faut les ajouter dans un change set nommé update_db_lutece_core-7.1.0-7.1.1-rev1.sql à la suite des ordres précédents

--  changeset core:update_db_lutece_core-7.1.0-7.1.1-rev1.sql

UPDATE core_datastore SET entity_key='portal.site.site_property.layout.login.image' WHERE entity_key='portal.site.site_property.login.image';
DELETE FROM core_datastore WHERE entity_key='portal.site.site_property.login.image';

Gestion des Thèmes

1. Structure générale

Pour qu’un thème soit pris en compte par Liquibase, ses scripts SQL doivent être placés dans le répertoire suivant : src/sql/themes/$nom_du_theme/

Chaque thème est composé de :

un script d’initialisation
des scripts de mise à jour (upgrade)
un fichier de configuration définissant la version du thème

2. Script d’initialisation du thème

2.1 Emplacement

Le script d’initialisation doit se trouver à la racine du répertoire du thème : src/sql/themes/$nom_du_theme/

2.2 Convention de nommage

Le fichier doit être préfixé par init
Exemple :init_db_theme_parisfr.sql Chemin complet :src/sql/themes/parisfr/init_db_theme_parisfr.sql

2.3 En-tête obligatoire

Le fichier d’initialisation doit obligatoirement contenir l’en-tête Liquibase suivant :

-- liquibase formatted sql
-- changeset theme-$nom_du_theme:$nom_du_fichier_init.sql
-- preconditions onFail:MARK_RAN onError:WARN

3. Scripts de mise à jour (upgrade)

3.1 Emplacement

Les scripts de mise à jour doivent être placés dans le sous-répertoire : src/sql/themes/$nom_du_theme/upgrade/

3.2 Convention de nommage

Les fichiers doivent être préfixé par update
Le nom du fichier doit indiquer la version source et la version cible
Exemple : update_db_theme_parisfr-1.0.0-1.1.0.sql

3.3 En-tête obligatoire

Chaque script d’upgrade doit contenir l’en-tête suivant :

-- liquibase formatted sql
-- changeset theme-$nom_du_theme:$nom_du_fichier_update.sql
-- preconditions onFail:MARK_RAN onError:WARN## Construction

4. Gestion de la version du thème

La version d’un thème est définie dans un fichier de propriétés.

4.1 Emplacement

WEB-INF/conf/themes/$nom_du_theme.properties

4.2 Propriété de version

Le fichier doit contenir la propriété suivante :

themes.$nom_du_theme.version=1.0.0

Exemple pour le thème parisfr : themes.parisfr.version=1.0.0

5. Récapitulatif des conventions

Élément	Emplacement	Préfixe requis
Script d’initialisation	`src/sql/themes/$nom_du_theme/`	`init`
Scripts d’upgrade	`src/sql/themes/$nom_du_theme/upgrade/`	`update`
Fichier de version	`WEB-INF/conf/themes/`

Construction

le lutece-sitenpom du site doit être en version minimal 7.0.2-SNAPSHOT

  <parent>
        <artifactId>lutece-site-pom</artifactId>
        <groupId>fr.paris.lutece.tools</groupId>
        <version>7.0.2-SNAPSHOT</version>
    </parent>

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 ayant comme entête un changeset liquibase dans le répertoire WEB-INF/classes du site le fichier WEB-INF/classes/META-INF/microprofile-config.properties est créé et possède la propriété liquibase.readyToRun indiquant que l’ensemble des composants lutece du site sont compatibles liquibase. Cette propriété est lue par le plugin liquibase au démarage de la webapp la propriété liquibase.fileErrors liste l’ensemble des fichiers sql de la webapp non pris en compte par liquibase

# Generated file - do not edit
liquibase.readyToRun=true
# Lists SQL files not managed by Liquibase
liquibase.fileErrors=

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

Top of the page