Servlet Listener

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

To configure it, simply add the following to your web.xml file:

<context-param>
    <param-name>MIGRATOR_FILE</param-name>
    <param-value>com/example/db.changelog.xml</param-value>
</context-param>
<context-param>
    <param-name>MIGRATOR_DATA_SOURCE</param-name>
    <param-value>java:comp/env/jdbc/default</param-value>
</context-param>

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

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

<listener>
    <listener-class>liquibase.migrator.ServletMigrator</listener-class>
</listener>

Then, simply add the liquibase.jar to your WEB-INF/lib directory.

The MIGRATOR_FILE context param gives the location of your db.changelog.xml in the classpath.  THe MIGRATOR_DATA_SOURCE is the JNDI location to get the connection from.  Note that the MIGRATOR_DATA_SOURCE can be different than the data source the rest of your web app uses if that data source does not have sufficient privilages to create/alter tables etc.

The MIGRATOR_HOST_EXCLUDES and MIGRATOR_HOST_INCLUDES parameters are optional and are used when you don’t want the migrator to run in all environments.  For example, if you don’t want it to run in the production environment, use the MIGRATOR_HOST_EXCLUDES parameter to specify the host name of your production machine(s).  If you would rather specify only which machines to run on, use the MIGRATOR_HOST_INCLUDES paramter.

The MIGRATOR_FAIL_ON_ERROR parameter is option and controls if an exception is thrown by the migrator 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.

A “database.migrator.should.run” system property can be set that blocks the migrator from running if set to “false”