Servlet Listener

Liquibase can be run via a servlet listener. This allows you to have your database be updated automatically whenever the site is deployed. Since Liquibase uses distributed locking, this method will work just fine even if you have a cluster of application servers.

To configure the servlet listener, simply add liquibase.jar to your WEB-INF/lib directory and the following to your web.xml file:

<context-param>
    <param-name>liquibase.changelog</param-name>
    <param-value>com/example/db.changelog.xml</param-value>
</context-param>

<context-param>
    <param-name>liquibase.datasource</param-name>
    <param-value>java:comp/env/jdbc/default</param-value>
</context-param>

<context-param>
    <param-name>liquibase.host.includes</param-name>
    <param-value>production1.example.com, production2.example.com</param-value>
</context-param>

<context-param>
    <param-name>liquibase.onerror.fail</param-name>
    <param-value>true</param-value>
</context-param>

<context-param>
    <param-name>liquibase.contexts</param-name>
    <param-value>production</param-value>
</context-param>

<listener>
    <listener-class>liquibase.integration.servlet.LiquibaseServletListener</listener-class>
</listener>

If using Liquibase 1.9.x

<context-param>
    <param-name>LIQUIBASE_CHANGELOG</param-name>
    <param-value>com/example/db.changelog.xml</param-value>
</context-param>

<context-param>
    <param-name>LIQUIBASE_DATA_SOURCE</param-name>
    <param-value>java:comp/env/jdbc/default</param-value>
</context-param>

<context-param>
    <param-name>LIQUIBASE_HOST_EXCLUDES</param-name>
    <param-value>production1.example.com, production2.example.com</param-value>
</context-param>

<context-param>
    <param-name>LIQUIBASE_FAIL_ON_ERROR</param-name>
    <param-value>true</param-value>
</context-param>

<context-param>
    <param-name>LIQUIBASE_CONTEXTS</param-name>
    <param-value>production</param-value>
</context-param>

<listener>
    <listener-class>liquibase.servlet.LiquibaseServletListener</listener-class>
</listener>

Available context-parameters:

Parameter1.9 versionDescription
liquibase.changelogLIQUIBASE_CHANGELOGSpecifies the changelog file to run required
liquibase.datasourceLIQUIBASE_DATA_SOURCEJNDI datasource to use for running Liquibase. Note that the LIQUIBASE_DATA_SOURCE can be different than the data source the rest of your web app uses if that data source does not have sufficient privileges to create/alter tables etc. required
liquibase.host.excludesLIQUIBASE_HOST_EXCLUDESSpecify host names on which you do NO want Liquibase to run. Specifying this parameter allows you to deploy the same WAR/EAR to multiple machines in different environments and not have Liquibase run on all of them.
liquibase.host.includesLIQUIBASE_HOST_INCLUDESSpecify the ONLY host names on which want Liquibase to run. Specifying this parameter allows you to deploy the same WAR/EAR to multiple machines in different environments and not have Liquibase run on all of them.
liquibase.onerror.failLIQUIBASE_FAIL_ON_ERRORSpecify if an exception is thrown by Liquibase if an error occurs. Setting the value to "true" (default) will cause the exception to be thrown and keep the site from initializing properly. Setting the value to "false" will allow the site to deploy as normal, but the database will be in an undefined state.
liquibase.contextsLIQUIBASE_CONTEXTSA comma separated lists of the [contexts](contexts.html) to run in.

If you want to control servers that run Liquibase but don’t want to set the LIQUIBASE_HOST_EXCLUDES/LIQUIBASE_HOST_INCLUDES attributes, you can specify the “liquibase.should.run=[true/false]” system property.


Missing, incomplete or wrong information? Please send a pull request