Documentation Home

Managing Database Versions with Liquibase

Liquibase (http://www.liquibase.org/index.html) is a very powerful Database versioning and management tool that we highly recommend you consider using to help manage your Database upgrades and migrations.

Depending on your development and release processes, you may not want Liquibase to directly update your database. Reasons for this may include a desire to tweak the resulting SQL, have the SQL approved by a DBA, or for SOX compliance. For this reason, all update and rollback Liquibase commands have a “sql output” mode which do not execute anything against the database but instead save the resulting SQL to standard out or a specified file which you can also then review with your DBA before applying the final script.

Please read the Liquibase documentation for more details on best practices.

Setting up Liquibase in Heat Clinic

1) Add a liquibase dependency to your root pom.xml dependency managment section

<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
    <version>3.4.1</version>
</dependency>

2) Add a liquibase dependency you core pom.xml

<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
</dependency>

3) Create a directory named sql in the resources directory of core, and create another directory inside of that one named changelog

4) Create a file in the sql directory named changelog.master.xml with the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
            http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.3.xsd">

    <includeAll path="sql/changelog" />

</databaseChangeLog>

This master changelog file tells liquibase to execute all files in the sql/changelog directory you created. By default, both xml files and sql files will be picked up by liquibase, though we recommend using liquibase xml files. Also, liquibase will execute all files in the directory in alphabetical order, so we recommend using a versioned naming convention (e.g. db.changelog-1.0.0.xml, db.changelog-1.0.1.xml or 0001-initial-schema.xml, 0002-second-change.xml)

6) Add a SpringLiquibase bean to the core applicationContext.xml, example:

<bean id="liquibase" class="liquibase.integration.spring.SpringLiquibase">
    <property name="dataSource" ref="webDS" />
    <property name="changeLog" value="classpath:sql/changelog.master.xml" />
    <property name="shouldRun" value="${liquibase.autorun.enabled}" />
</bean>

This bean lets you specify a lot options. For one, you can specify which datasource and master changelog file it uses. This allows you to specify multiple SpringLiquibase beans each with different datasources and different master changelogs, so that you can manage each database independently. Also, the shouldRun property can be provided with a property value from a property file. This allows you to specify the liquibase.autorun.enabled property in your property files to determine if liquibase should execute.