https://github.com/jamesnetherton/wildfly-liquibase
WildFly subsystem extension for Liquibase
https://github.com/jamesnetherton/wildfly-liquibase
liquibase wildfly
Last synced: 20 days ago
JSON representation
WildFly subsystem extension for Liquibase
- Host: GitHub
- URL: https://github.com/jamesnetherton/wildfly-liquibase
- Owner: jamesnetherton
- License: apache-2.0
- Created: 2017-11-27T22:13:24.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T07:48:31.000Z (over 2 years ago)
- Last Synced: 2024-10-19T21:18:02.332Z (7 months ago)
- Topics: liquibase, wildfly
- Language: Java
- Homepage:
- Size: 454 KB
- Stars: 4
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# wildfly-liquibase
[](http://www.apache.org/licenses/LICENSE-2.0)
[](http://search.maven.org/#search%7Cga%7C1%7Cg%3Acom.github.jamesnetherton%20a%3Awildfly-liquibase-distro)
[WildFly](http://wildfly.org) subsystem extension for [Liquibase](http://www.liquibase.org/). 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](https://github.com/jamesnetherton/wildfly-liquibase/releases) 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 `` tag:
```
```
2. Configure the subsystem by adding it under the `` element (more on this later):
```
```
### Galleon provisioning
Alternatively, you may use WildFly [Galleon](https://github.com/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](http://www.liquibase.org/documentation/changelog_parameters.html) named `datasource`.
> NOTE: In previous wildfly-liquibase releases this parameter was named `datasource-ref`.
```xml
...
```
For [Liquibase formatted](http://www.liquibase.org/documentation/sql_format.html) SQL change log files, the `datasource` parameter must be specified within an SQL comment block. For example:
```sql
--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
context1,context2
prod,!dev
false
some.host.com,another.host.net
contextA,contextB
prod,!qa
some.host.com,another.host.net
```
#### 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 `` 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.
```xml
]]>
```
**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](http://www.liquibase.org/documentation/cdi.html) 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](https://www.liquibase.org/documentation/servlet_listener.html).
## Examples
Take a look at the [examples](https://github.com/jamesnetherton/wildfly-liquibase/tree/master/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
```