Skip to content

Servlet Listener

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

To configure the servlet listener, add the liquibase.jar file to your WEB-INF/lib directory. Then add 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>

Note: If your application server uses the jakarta.servlet packages, use this listener instead:

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

Available context-parameters

Parameter Description
liquibase.changelog Specifies the changelog file to run. Required
liquibase.datasource JNDI data source to use for running Liquibase. Note that the LIQUIBASE_DATA_SOURCE can be different than the data source that the rest of your web app uses if that data source does not have sufficient privileges to create or alter tables. Required
liquibase.host.excludes Specify host names on which you do not 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.includes Specify 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.fail Specify 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.contexts A comma-separated lists of the Contexts to run in.

If you want to control servers that run Liquibase but do not want to set the liquibase.host.includes/liquibase.host.excludes attributes, specify the liquibase.should.run=[true/false] system property.