Documentation Home

Managing Database Versions with Liquibase

Liquibase ( 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.

We recommend reading the Spring Boot Liquibase documentation as well, that is what we based this document on.

Setting up Liquibase in Heat Clinic

  1. Add a liquibase dependency to your core pom.xml dependency section


    Note: If you'd like, you can put the version definition in your root pom.xml and manage the version at the root.

  2. Create your changelog directory and master file under your core project at core/src/main/resource/db/changelog/db.changelog-master.xml:

    <?xml version="1.0" encoding="UTF-8"?>
        <include file="db/changelog/001-my-first-changelog.xml" />

    Note: We currently recommend not using includeAll since it is seems to break every other Liquibase version and is very inconsistent. The last version it consistently worked on is 3.4.2.

  3. Let Liquibase know where to find your changelog files at by adding this property to your file in your core project:

  4. Ensure hibernate does not drop all of your tables and data by disabling in your site and admin

    a. If you want hibernate to do nothing, and manage your schema independently, use this:

    Note: This is the recommended way once you've established your starting database. This allows you to ensure a consistent database schema and dataset.

    b. If you want hibernate to update the schema for you based on Entity annotations, use this:

    Note: This is useful for creating an A and B database to generate a changelog between the two if you are migrating from one schema to another.

By default, Liquibase supports XML, JSON, and SQL files, though we recommend using liquibase xml files. We also recommend using a strict 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), as this will make it easier to manage your changelogs into the future.

Spring Boot and Liquibase will autowire the @Primary DataSource in your context and use that for migrations. Assuming you followed the steps so far, your changelogs should be executed on startup.