Liquibase plugin

This document describes the functionality provided by the Liquibase plugin.

See the XL Deploy v22.3 Documentation for background information on XL Deploy and deployment concepts.

CI status

Overview

The Liquibase plugin provides a simple way to use Liquibase in XL Deploy.

This plugin supports Liquibase 'roll back to' tag mode.

Installation

You need to install Liquibase on a host accessible by the XL Deploy server.

Execution Logic

• CREATE Operation
  • Upload changelog folder
  • Tag Liquibase with an initial rollback tag.
  • Perform update of the changelog.
  • Tag Liquibase with the rollback tag specified on the deployed.
• DESTROY Operation
  • Upload changelog folder of previous deployed
  • Rollback to the initial rollback tag.
• MODIFY Operation
  • When the rollbackVersion of the new deployed is less than the previous deployed
    • Upload changelog folder of previous deployed
    • Rollback to new deployed rollbackVersion
  • Otherwise
    • Upload changelog folder of new deployed
    • Perform update of the changelog.
    • Tag Liquibase with the rollback tag specified on the deployed.

Sample DARs

There are 2 versions of a sample dar available in the test/resources/sample_dars directory that can be used to demonstrate plugin functionality.

Configuration

Container liquibase.Runner

A liquibase.Runner instance represents a liquibase installation. Below the configuration properties that needs to be set:

• databaseUsername: username for the database to connect to (when left out it will use the value in the properties file).
• databasePassword: password for the specified username (when left out it will use the value in the properties file).
• databaseJDBCURL: JDBC connection URL (when left out it will use the value in the properties file).
• databaseJDBCDriver: name of the JDBC driver to use (when left out it will use the value in the properties file).
• driverClasspath: java classpath used to get database drivers.
• liquibaseLauncher: Location of the Liquibase launch script. If this option is configured the options liquibaseJarPath and javaCmd will be ignored.
• liquibaseConfigurationPath: path to the liquibase configuration file, i.e liquibase.properties.
• liquibaseExtraArguments: Use to pass extra arguments to the liquibase command.
• liquibaseJarPath: path to the main liquibase jar file, i.e. liquibase.jar.
• javaCmd: command that will be used to launch liquibase java process. Default is "java".

Liquibase v4.11.0 and up

With Liquibase version v4.11.0 the preferred way of starting Liquibase CLI is changed to a launcher script. Therefore the plugin provides the liquibaseLauncher option for xld-liquibase-plugin version 5.1.0 and up. If this option is configured the contents of liquibaseJarPath and javaCmd will be ignored. If you wish to use the previous java -jar liquibase-core.jar way leave the field liquibaseLauncher empty. If you do so with version v4.11.0 and up, provide a LIQUIBASE_HOME variable on the client somehow because this variable is required for this version and up.

Deployable liquibase.Changelog

liquibase.Changelog is a folder artifact that contains all the xml liquibase changelog files of the application package.

PLEASE NOTE this plugin requires that each changeset be marked with the logicalFilePath attribute set. This is so that Liquibase will not take the file name that contains the changeset into consideration when writing database log changes, e.g

<changeSet logicalFilePath="path-independent"  author="xxx" id="1403012036690-1">

Properties :

• changeLogFile specifies the entry point xml changelog file for liquibase.
• rollbackVersion specifies the rollback version that will be used to apply a tag after successful changelog update.
• rollbackVersionPrefix specifies the prefix added to the tag. Default is 'v'. The tag is composed as follows: , for example: "v1" or "abc-1".