wildfly-liquibase

The WildFly Liquibase Subsystem

License

License

Categories

Categories

WildFly Container Application Servers Net Liquibase Data Databases
GroupId

GroupId

com.github.jamesnetherton
ArtifactId

ArtifactId

wildfly-liquibase
Last Version

Last Version

2.2.0
Release Date

Release Date

Type

Type

pom
Description

Description

wildfly-liquibase
The WildFly Liquibase Subsystem
Project URL

Project URL

https://github.com/jamesnetherton/wildfly-liquibase
Source Code Management

Source Code Management

https://github.com/jamesnetherton/wildfly-liquibase

Download wildfly-liquibase

How to add to project

<!-- https://jarcasting.com/artifacts/com.github.jamesnetherton/wildfly-liquibase/ -->
<dependency>
    <groupId>com.github.jamesnetherton</groupId>
    <artifactId>wildfly-liquibase</artifactId>
    <version>2.2.0</version>
    <type>pom</type>
</dependency>
// https://jarcasting.com/artifacts/com.github.jamesnetherton/wildfly-liquibase/
implementation 'com.github.jamesnetherton:wildfly-liquibase:2.2.0'
// https://jarcasting.com/artifacts/com.github.jamesnetherton/wildfly-liquibase/
implementation ("com.github.jamesnetherton:wildfly-liquibase:2.2.0")
'com.github.jamesnetherton:wildfly-liquibase:pom:2.2.0'
<dependency org="com.github.jamesnetherton" name="wildfly-liquibase" rev="2.2.0">
  <artifact name="wildfly-liquibase" type="pom" />
</dependency>
@Grapes(
@Grab(group='com.github.jamesnetherton', module='wildfly-liquibase', version='2.2.0')
)
libraryDependencies += "com.github.jamesnetherton" % "wildfly-liquibase" % "2.2.0"
[com.github.jamesnetherton/wildfly-liquibase "2.2.0"]

Dependencies

There are no dependencies for this project. It is a standalone project that does not depend on any other jars.

Project Modules

  • subsystem
  • feature-pack
  • distro
  • testextension
  • itests

wildfly-liquibase

WildFly Liquibase CI License Maven Central

WildFly subsystem extension for Liquibase. Enables you to execute Liquibase change logs for your JavaEE applications without having to configure the LiquibaseServletListener or bundle Liquibase with your application.

Installation

Distribution overlay

Download one of the release distribution zip files and unpack it inside of your WildFly installation directory.

cd $JBOSS_HOME
wget https://github.com/jamesnetherton/wildfly-liquibase/releases/download/2.2.0/wildfly-liquibase-distro-2.2.0.zip
unzip wildfly-liquibase-distro-2.2.0.zip

Check the release notes to ensure that the distribution is compatible with your WildFly version.

For convenience, the distribution provides a standalone-liquibase.xml configuration file which you can reference when starting WildFly:

$JBOSS_HOME/bin/standalone.sh -c standalone-liquibase.xml

Otherwise you can manually configure the Liquibase subsystem in one of the existing configuration files as follows.

  1. Add the extension as a child element to the <extensions> tag:
<extension module="com.github.jamesnetherton.extension.liquibase"/>
  1. Configure the subsystem by adding it under the <profile> element (more on this later):
<subsystem xmlns="urn:com.github.jamesnetherton.liquibase:1.0"/>

Galleon provisioning

Alternatively, you may use WildFly Galleon to provision a server.

First install the base server:

galleon.sh install wildfly:current --dir=wildfly

Next install the Liquibase subsystem layer:

galleon.sh install com.github.jamesnetherton:wildfly-liquibase-galleon-pack:2.2.0 --dir=wildfly --layers=liquibase

Configuration

Change logs

Change logs can be configured in three ways.

1. Change log files within deployments

You can package Liquibase change log files within your deployment. The following file extensions are supported:

  • .json
  • .sql
  • .xml
  • .yaml
  • .yml

The Liquibase subsystem will search for change log files which match the regex .*changelog.(json|sql|xml|yaml|yml)$ and will attempt to apply them before the deployment is successfully installed.

In order for the Liquibase subsystem to discover your DataSource, you must add it to the WildFly datasources subsystem configuration. You must then reference the datasource JNDI binding in your change log file via a change log parameter named datasource.

NOTE: In previous wildfly-liquibase releases this parameter was named datasource-ref.

<databaseChangeLog>

    <property name="datasource" value="java:jboss/datasources/ExampleDS" />

    ...
</databaseChangeLog>

For Liquibase formatted SQL change log files, the datasource parameter must be specified within an SQL comment block. For example:

--liquibase formatted sql

--datasource java:jboss/datasources/ExampleDS

CREATE TABLE test (
    ...
);
Additional deployment configuration options

To configure the various aspects of Liquibase change log execution, you can provide an optional META-INF/jboss-all.xml or WEB-INF/jboss-all.xml.

For example to define the contexts and other attributes for specific change log files:

<?xml version="1.0" encoding="UTF-8"?>
<jboss xmlns="urn:jboss:1.0">
    <liquibase xmlns="urn:com.github.jamesnetherton.liquibase:1.0" changelog="changelog.xml">
        <contexts>context1,context2</contexts>
        <labels>prod,!dev</labels>
        <fail-on-error>false</fail-on-error>
        <host-includes>some.host.com,another.host.net</host-includes>
    </liquibase>
    <liquibase xmlns="urn:com.github.jamesnetherton.liquibase:1.0" changelog="other-changelog.xml">
        <contexts>contextA,contextB</contexts>
        <labels>prod,!qa</labels>
        <host-excludes>some.host.com,another.host.net</host-excludes>
    </liquibase>
</jboss>

2. Standalone XML change log file deployment

You can execute XML change logs without the requirement of a deployment archive wrapper. Simply place a file suffixed with changelog.xml into the WildFly deployments directory, and the Liquibase subsystem will attempt to execute it.

3. Change log files within Liquibase subsystem configuration

Change logs can be defined as part of the Liquibase subsystem configuration. When WildFly starts, it will attempt to apply change logs before any applications are deployed.

The change log definition body must be wraped within a CDATA block in order for it to be parsed correctly. Change log definitions can be defined in JSON, SQL, XML or YAML formats. You may specify multiple <databaseChangeLog> elements if you wish.

When defining a change log as XML, the usual Liquibase namespace declarations are not required as these are automatically added for you.

<subsystem xmlns="urn:com.github.jamesnetherton.liquibase:1.0"/>
    <databaseChangeLog name="changelog.xml" datasource="java:jboss/datasources/ExampleDS" contexts="test">
        <![CDATA[
            <preConditions>
                <runningAs username="SA"/>
            </preConditions>

            <changeSet id="1" author="wildfly" context="test" labels="test">
                <createTable tableName="person">
                    <column name="id" type="int" autoIncrement="true">
                        <constraints primaryKey="true" nullable="false"/>
                    </column>
                    <column name="firstname" type="varchar(50)"/>
                    <column name="lastname" type="varchar(50)">
                        <constraints nullable="false"/>
                    </column>
                    <column name="state" type="char(2)"/>
                </createTable>
            </changeSet>
        ]]>
    </databaseChangeLog>
</subsystem>

Change Log Attributes

Attribute Name Required Description
contexts No A comma separated list of Liquibase contexts to run in
datasource Yes A reference to a DataSource JNDI binding configured in the WildFly datasources susbsystem
fail-on-error No Either true or false to prevent the deployment or server startup proceeding in the event that changelog execution fails
host-excludes No Comma separated list of host names to exclude from executing the changelog
host-includes No Comma separated list of host names to include for executing the changelog
labels No Comma separated list of label expressions for Liquibase to chose the labels you want to execute
name Yes Unique identifier for the change log which is ideally a file name. You should include a file extension to help the Liquibase subsystem determine what type of content it is handling

CDI Support

If the Liquibase subsystem detects that a deployment is CDI enabled, it will automatically add a dependency on Liquibase CDI for you. This provides the capability to load and execute change logs via CDI annotations.

Servlet Listener

If you prefer to use LiquibaseServletListener, the Liquibase subsystem automatically makes the listener class available to deployments. All you need to do is configure web.xml as per the servlet listener documentation.

Examples

Take a look at the examples to see some basic use cases.

Docker Image

To run wildfly-liquibase in a Docker container run:

docker run -ti --rm -p 8080:8080 -p 9990:9990 jamesnetherton/wildfly-liquibase:latest

By default this runs the server in standalone mode with the standalone-liquibase.xml configuration. To override this, simply specify a custom command line:

docker run -ti --rm jamesnetherton/wildfly-liquibase:latest /opt/jboss/wildfly/bin/standalone.sh -c standalone-full-liquibase.xml

Versions

Version
2.2.0
2.1.0
2.0.0
1.1.1
1.1.0
1.0.0
0.9.0
0.8.0
0.7.0
0.6.0
0.5.0
0.4.0
0.3.0
0.2.0
0.1.0