Liquibase Plugin Reference 26.1.x

The XL Deploy Liquibase plugin allows you to apply database changelogs and roll back database changes to deployment tags. The plugin runs the Liquibase CLI on a host configured in XL Deploy.

Requirements

• Install the Liquibase CLI on a host accessible by the XL Deploy server.
• Configure the host with access to the target database and the required database drivers.
• For Liquibase 4.11.0 and later, make LIQUIBASE_HOME available in the execution environment on the host.
• Package the changelog files in a liquibase.Changelog folder artifact.

Limitations

• Rollback uses Liquibase tags rather than a changeset count or date.
• Changesets must support rollback for the selected target tag.
• Set the logicalFilePath attribute on each changeset so that uploaded file paths do not affect changeset identification.

Configure a Liquibase Runner

Create a liquibase.Runner on the host where Liquibase is installed. Configure the database connection and Liquibase command settings:

| Property | Description | | --- | --- | | databaseUsername | Database username. When omitted, use the value in the Liquibase properties file. | | databasePassword | Database password. When omitted, use the value in the Liquibase properties file. | | databaseJDBCURL | JDBC connection URL. When omitted, use the value in the Liquibase properties file. | | databaseJDBCDriver | JDBC driver class. When omitted, use the value in the Liquibase properties file. | | driverClasspath | Java classpath for the database drivers. | | liquibaseLauncher | Location of the Liquibase CLI. Defaults to /usr/local/bin. | | isNoSQL | Set to true for a NoSQL database. Defaults to false. | | liquibaseConfigurationPath | Path to the Liquibase properties file. | | liquibaseExtraArguments | Additional arguments passed to the Liquibase command. |

Run Check Connection on the runner to verify database connectivity before deployment.

Configure a Changelog

Add a liquibase.Changelog folder artifact to the deployment package and map it to a liquibase.Runner.

| Property | Description | | --- | --- | | changeLogFile | Entry-point changelog file within the artifact. Required. | | rollbackVersion | Integer used for the deployment rollback tag and version comparisons. | | rollbackVersionPrefix | Prefix for the deployment rollback tag. Defaults to v. |

The deployment tag combines rollbackVersionPrefix and rollbackVersion. For example, prefix v and version 1 produce tag v1.

Use a stable logical path for each changeset:

<changeSet logicalFilePath="path-independent" author="example" id="1">
    <!-- Database changes -->
</changeSet>

Deployment Behavior

Create

1. Upload the changelog folder.
2. Create the initial rollback tag, xld_liquibase_base_version.
3. Apply the changelog.
4. Create the deployment rollback tag.

Modify

• If the new rollbackVersion is lower than the previous version, upload the previous deployment's changelog folder and roll back to the new deployment's tag.
• Otherwise, upload the new changelog folder, apply the changelog, and create the deployment rollback tag.

Destroy

1. Upload the previous deployment's changelog folder.
2. Roll back to the initial rollback tag, xld_liquibase_base_version.

For relational databases, the plugin runs updateSQL before update. When isNoSQL is true, it skips updateSQL.