Liquibase Plugin Reference 25.3.x

    XL Deploy Liquibase Plugin Manual

    The XL Deploy Liquibase plugin enables XL Deploy to work with Liquibase database schema change management. Liquibase is a database schema change management tool that tracks, versions, and deploys changes across environments with rollback capabilities.

    This document contains information that is specific to this version of the plugin. For information about plugin features, refer to Introduction to the XL Deploy Liquibase plugin. For general information about database management, refer to Database Management through XL Deploy.

    Requirements

    • XL Deploy 25.1.0 or later
    • Liquibase CLI installed on a host accessible by the XL Deploy server
    • Database JDBC drivers
    • Database connection credentials

    Features

    • Apply Changelog: Execute Liquibase changelog files to update database schema
    • Rollback Support: Roll back database changes to a specific version or tag
    • Multiple Database Support: Compatible with SQL and NoSQL databases
    • Configuration Management: Support for Liquibase configuration files
    • Tag Management: Automatic tagging for rollback points

    Installation

    1. Install Liquibase CLI on the target host where database operations will be executed
    2. Ensure the Liquibase installation is accessible via the configured path
    3. Install appropriate JDBC drivers for your target database
    4. Configure database connection parameters

    Liquibase v4.11.0 and Later

    With Liquibase version v4.11.0, the preferred way of starting Liquibase CLI changed to use launcher scripts. For these versions:

    • Provide a LIQUIBASE_HOME environment variable on the client
    • Use the liquibaseLauncher property to specify the launcher script location

    Using the Deployables and Deployeds

    The following table shows the possible containers a deployable can be targeted to and the deployed that will be created as a result.

    Deployable vs. Containers Table

    Deployable Containers Deployed
    liquibase.Changelog liquibase.Runner liquibase.ExecutedChangelog

    Configuration Items

    Container: liquibase.Runner

    A liquibase.Runner instance represents a Liquibase installation and database configuration.

    Database Parameters

    • databaseUsername: Username for the database connection (optional if specified in configuration file)
    • databasePassword: Password for the specified username (optional if specified in configuration file)
    • databaseJDBCURL: JDBC connection URL for the target database (optional if specified in configuration file)
    • databaseJDBCDriver: The JDBC driver class to use for database connectivity (optional if specified in configuration file)
    • driverClasspath: Java classpath containing database drivers
    • isNoSQL: Set to true if the target database is a NoSQL database (default: false)

    Liquibase Parameters

    • liquibaseLauncher: Location of the Liquibase CLI executable or launcher script (default: /usr/local/bin)
    • liquibaseConfigurationPath: Path to the Liquibase configuration file (e.g., liquibase.properties)
    • liquibaseExtraArguments: Additional command-line arguments to pass to Liquibase

    Available Methods

    • Check Connection: Verify database connectivity from Liquibase

    Deployable: liquibase.Changelog

    A liquibase.Changelog is a folder artifact containing Liquibase changelog files for database schema management.

    Properties

    • changeLogFile: Name of the main changelog file that serves as the entry point for Liquibase execution (required)
    • rollbackVersion: Specific version number for rollback operations (integer)
    • rollbackVersionPrefix: Prefix added to rollback tags (default: v)

    Important Notes

    • Each changeset must include the logicalFilePath attribute to ensure Liquibase doesn't consider the file name when writing database log changes
    • Example changeset format: 
      <changeSet logicalFilePath="path-independent" author="developer" id="1403012036690-1">

    Execution Logic

    CREATE Operation

    1. Upload changelog folder to the target location
    2. Apply an initial rollback tag using the base tag name
    3. Execute the changelog update against the database
    4. Apply a rollback tag with the specified version for future rollback operations

    DESTROY Operation

    1. Upload the changelog folder from the previous deployment
    2. Roll back the database to the initial rollback tag, effectively undoing all changes

    MODIFY Operation

    The behavior depends on the rollback version comparison:

    When new rollback version is less than the previous version:

    1. Upload the changelog folder from the previous deployment
    2. Roll back the database to the new deployment's rollback version

    When new rollback version is greater than or equal to the previous version:

    1. Upload the changelog folder from the new deployment
    2. Execute the changelog update against the database
    3. Apply a rollback tag with the specified version

    CI Reference

    Configuration Item Overview

    Deployables

    CIDescription
    liquibase.Changelog Executed liquibase changelog (deployable)

    Deployeds

    CIDescription
    liquibase.ExecutedChangelog Executed liquibase changelog

    Containers

    CIDescription
    liquibase.Runner Liquibase CLI Configuration

    Configuration Item Details

    liquibase.Changelog

    Type Hierarchy file.Folder >> udm.BaseDeployableFolderArtifact >> udm.BaseDeployableArtifact >> udm.BaseDeployable >> udm.BaseConfigurationItem
    Interfaces udm.Artifact, udm.Deployable, udm.DeployableArtifact, udm.FolderArtifact, udm.SourceArtifact, udm.Taggable

    Executed liquibase changelog (deployable)

      Public properties
     
     
    changeLogFile: STRING
    Name of the changelog file containing database changesets that Liquibase will execute. (string)
     
     
    checksum: STRING
    The checksum used to detect differences on the artifact. If not provided, it will be calculated by XL Deploy.
     
     
    createTargetPath: STRING
    Create the targetPath on the host if it does not exist.
     
     
    credentials: CI<credentials.Credentials>
    Credentials of the URI.
     
     
    defaultCopyStrategy: CI<file.FileCopyStrategy>
    Default copy strategy for this folder artifact.
     
     
    excludeFileNamesRegex: STRING
    Regular expression that matches file names that must be excluded from scanning
     
     
    excludeFileNamesRegexToTranscode: STRING
    A regex of file type that needs to be ignored for transcode
     
     
    fileEncodings: MAP_STRING_STRING = { .+\.properties=ISO-8859-1 }
    Specifies file encodings in this artifact. Key: regular expression matching file names; value: character set. Character set encoding is used for placeholder replacement and transcoding files to z/OS.
     
     
    fileUri: STRING
    The URI pointing to the (remote) location of the file this artifact represents
     
     
    isRescanned: BOOLEAN
    Indicates if the artifact has been rescanned
     
     
    members: SET_OF_STRING
    Only these files or directories will be extracted from the archive.
     
     
    placeholders: SET_OF_STRING
    Placeholders detected in this artifact
     
     
    preScannedPlaceholders: BOOLEAN
    Whether this artifact has been pre-scanned by the packager (ie. scanned for placeholders and checksum is set)
     
     
    proxySettings: CI<credentials.ProxySettings>
    Proxy Settings for artifact location
     
     
    rollbackVersion: STRING
    A specific point in the database changelog history to which Liquibase will revert the database, undoing changes made after that version. (integer)
     
     
    rollbackVersionPrefix: STRING
    Prefix added to rollback tag. Defaults to 'v' (string) default(v)
     
     
    scanPlaceholders: BOOLEAN = true
    Whether to scan this artifact to replace placeholders when it is imported
     
     
    stripComponents: STRING = 0
    Number of leading folder levels (path components) to remove from each file path before extraction.
     
     
    tags: SET_OF_STRING
    If set, this deployable will only be mapped automatically to containers with the same tag.
     
     
    targetPath: STRING
    Path to which artifact must be copied to when being deployed.
     
     
    targetPathShared: STRING
    Is the targetPath shared by others on the host. When true, the targetPath is not deleted during undeployment; only the artifacts copied to it.
     
     
    textFileNamesRegexToTranscode: STRING = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)
    Regular expression that matches file names of text files to transcode to EBCDIC
      Hidden properties
     
     
    textFileNamesRegex: STRING = .+\.(cfg | conf | config | ini | properties | props | txt | asp | aspx | htm | html | jsf | jsp | xht | xhtml | sql | xml | xsd | xsl | xslt)
    Regular expression that matches file names of text files
     
     
    boundTemplates: SET_OF_CI<udm.Template>
    The set of CI templates.
     
     
    delimiters: STRING = {{ }}
    The delimiters used indicate placeholders, defaults to '{{ }}'. This is a 5 character string with a space in the middle, the first two are the leading delimiter, the last two are the closing delimiter
     
     
    isForceArchive: BOOLEAN = true
    Force Archive
    Control taskParameter CIAttributesDescription
    rescanArtifacts

    delegate = rescanArtifact

    No description.

    liquibase.ExecutedChangelog

    Type Hierarchy udm.BaseDeployedArtifact >> udm.BaseDeployed >> udm.BaseConfigurationItem
    Interfaces udm.Artifact, udm.Deployed, udm.DerivedArtifact, udm.EmbeddedDeployedContainer

    Executed liquibase changelog

      Parent
     
     
    container: CI<udm.Container>
    The container on which this deployed runs.
      Public properties
     
     
    changeLogFile: STRING
    Name of the changelog file containing database changesets that Liquibase will execute.
     
     
    rollbackVersion: INTEGER
    A specific point in the database changelog history to which Liquibase will revert the database, undoing changes made after that version.
     
     
    deployable: CI<udm.Deployable>
    The deployable that this deployed is derived from.
     
     
    placeholders: MAP_STRING_STRING
    A Map containing all the placeholders mapped to their values. Special values are <ignore> or <empty>
     
     
    rollbackVersionPrefix: STRING = v
    Prefix added to rollback tag. Defaults to 'v'
      Hidden properties
     
     
    baseRollbackTag: STRING = xld_liquibase_base_version
    Base Rollback Tag
     
     
    boundConfigurationItems: SET_OF_CI<udm.ConfigurationItem>
    The set of created CIs.

    liquibase.Runner

    Type Hierarchy generic.Container >> generic.BaseGenericContainer >> udm.BaseContainer >> udm.BaseConfigurationItem
    Interfaces udm.Container, generic.GenericContainer, overthere.HostContainer, udm.Taggable

    Liquibase CLI Configuration

      Parent
     
     
    host: CI<overthere.Host>
    Host upon which the container resides
      Public properties
     
     
    databaseJDBCDriver: STRING
    The JDBC driver class to use
     
     
    databaseJDBCURL: STRING
    JDBC connection URL for the database
     
     
    databasePassword: STRING
    Password for the specified database username.
     
     
    databaseUsername: STRING
    Username for the database to connect to.
     
     
    driverClasspath: STRING
    Java classpath used to get database drivers
     
     
    envVars: MAP_STRING_STRING
    Environment variables for container
     
     
    isNoSQL: BOOLEAN
    Set to true if the database is a NoSQL database
     
     
    liquibaseConfigurationPath: STRING
    Path to the liquibase configuration file.
     
     
    liquibaseExtraArguments: STRING
    Use to pass additional arguments to the liquibase command.
     
     
    liquibaseLauncher: STRING = /usr/local/bin
    Location of the Liquibase CLI path
     
     
    stopStartRestartConnection: CI<overthere.Host>
    If set, the connection settings to use to connect to the target system to execute start, stop, restart etc. operations for the container.
     
     
    tags: SET_OF_STRING
    If set, only deployables with the same tag will be automatically mapped to this container.
      Hidden properties
     
     
    restartOrder: INTEGER = 90
    The order of the restart container step in the step list.
     
     
    restartWaitTime: INTEGER
    The time to wait in seconds for a container restart action.
     
     
    startOrder: INTEGER = 90
    The order of the start container step in the step list.
     
     
    startWaitTime: INTEGER
    The time to wait in seconds for a container start action.
     
     
    stopOrder: INTEGER = 10
    The order of the stop container step in the step list.
     
     
    stopWaitTime: INTEGER
    The time to wait in seconds for a container stop action.
     
     
    inspectClasspathResources: SET_OF_STRING
    Additional classpath resources that should be uploaded to the working directory before executing the inspect script.
     
     
    inspectScript: STRING
    Classpath to the script used to inspect the generic container.
     
     
    inspectTemplateClasspathResources: SET_OF_STRING
    Additional template classpath resources that should be uploaded to the working directory before executing the inspect script.The template is first rendered and the rendered content copied to a file, with the same name as the template, in the working directory.
     
     
    restartClasspathResources: SET_OF_STRING
    Additional classpath resources that should be uploaded to the working directory before executing the restart script.
     
     
    restartScript: STRING
    Classpath to the script used to restart the generic container.
     
     
    restartTemplateClasspathResources: SET_OF_STRING
    Additional template classpath resources that should be uploaded to the working directory before executing the restart script.The template is first rendered and the rendered content copied to a file, with the same name as the template, in the working directory.
     
     
    startClasspathResources: SET_OF_STRING
    Additional classpath resources that should be uploaded to the working directory before executing the start script.
     
     
    startScript: STRING
    Classpath to the script used to start the generic container.
     
     
    startTemplateClasspathResources: SET_OF_STRING
    Additional template classpath resources that should be uploaded to the working directory before executing the start script.The template is first rendered and the rendered content copied to a file, with the same name as the template, in the working directory.
     
     
    stopClasspathResources: SET_OF_STRING
    Additional classpath resources that should be uploaded to the working directory before executing the stop script.
     
     
    stopScript: STRING
    Classpath to the script used to stop the generic container.
     
     
    stopTemplateClasspathResources: SET_OF_STRING
    Additional template classpath resources that should be uploaded to the working directory before executing the stop script.The template is first rendered and the rendered content copied to a file, with the same name as the template, in the working directory.
    Control taskParameter CIAttributesDescription
    checkConnection

    delegate = jythonScript, script = liquibase/check_connection.py

    Verify the connection to the database from liquibase.
    Copyright 2025. Digital.ai, Inc. All rights reserved