Mar 5, 2024 9:28:56 AM Pablo Abreu

Using the Liquibase plugin

Presentation

Liquibase

Liquibase is an open source tool aiming to manage and apply changes on databases. In other words, it's a component that can automatically run SQL scripts when a web site starts up.

The liquibase plugin in Lutece

The liquibase plugin in Lutece must be declared in the pom.xml of your Lutece web site. The way liquibase is used here differs from the usual because some Lutece peculiarities are managed:

• Presence of a core and plugins
• Differentiated scripts : createXXX.sql, initXXX.sql and updateXXX.sql

In the Lutece way of managing scripts, the createXXX.sql scripts must include all the modifications brought by successive versions of a component. But liquibase generally considers that SQL scripts are immutable and that all modifications should exclusively be done with new files. That is why the liquibase plugin from Lutece includes some dedicated logic to manage thoses differences.

So the plugin handles several use cases:

• Creation: when installing a web site for th first time, the database is empty. All scripts named createXXX et initXX will be run, but the scripts named updateXXX will not.
• Migration of the web site to the liquibase plugin: whan using the liquibase plugin for the first time, the database will be updated to begin using the plugin.
  • Either the migration is only adding the liquibase plugin: you just need to include it.
  • Or the migration, in addition to including the liquibase plugin, include other novelties: you will have to run some SQL queries beforehand manually.
• Update: whan updating the core version, updating a plugin version, or adding a new plugin, the needed scripts will be run in the right order

Usage

Integration

Add the following dependency in the pom.xml of your web site:

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

The liquibase plugin requires a minimal version for lutece-core (7.0.11 at the moment of writing) that you must obey..

Configuration

The liquibase plugin is disabled by default. To enable it, you have to declare this property:

liquibase.enabled.at.startup=true

Requirements

Here is the list of requirements to make the liquibase plugin successfully work:

• Use compatible versions for the core and plugins
• Migrate your own SQL scripts

Migrating your scripts can be quite simple:

The lutece maven plugin includes a tool allowing you to add liquibase specific tags to all the SQL scripts of your source code tree. You just need to type this command at your project's root:

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

When those tags are absent from an SQL script, the maven build process will ignore this script, which will not then run at start-up.

Build

Build your web site as usual:

mvn clean lutece:site-assembly -P dev

Optionally, you can use an additional command line parameter to specify the target RDBMS (mysql, oracle, postgresql, hsqldb, or the special value"auto", which finds the right RDBMS by reading the contents of your db.properties file) :

mvn clean lutece:site-assembly -P dev -DtargetDatabaseVendor=auto

In the default case, the SQL scripts are included without modification. They will be transformed on the fly when your web site starts depending on the detected actual RDBMS type.

Run

Once your web site is migrated, configured and built, you will be able to see the following traces when running it:

LiquibaseRunner starting

LiquibaseRunner ended

The lines between these two traces show the actions by the liquibase plugin to update the database.

Limitations

Some use case are not, and will not be, supported.

• Support for several simultaneous connection pools => little need
• Support for SQL code neither in core nor in plugins => little need