Liquibase Best Practices

This page describes a number of best practices that you can apply on your project.

Organizing your changelogs

The most common way to organize your changelogs is by major release. Choose a package in your classpath to store the changelogs, preferably near your database access classes. In this example, we will use com/example/db/changelog.

Directory structure



The master.xml includes the changelog for the releases in the correct order. In the example above it could look like this:

<?xml version="1.0" encoding="UTF-8"?>   
  <include  file="com/example/db/changelog/db.changelog-1.0.xml"/>   
  <include  file="com/example/db/changelog/db.changelog-1.1.xml"/>   
  <include  file="com/example/db/changelog/db.changelog-2.0.xml"/>   

Each of the included XML files needs to be in the same format as a standard XML database changelog, something like this:

<?xml version="1.0" encoding="UTF-8"?>   
  <changeSet  author="authorName"  id="changelog-1.0">  
    <createTable  tableName="TablesAndTables">  
      <column  name="COLUMN1"  type="TEXT">  
        <constraints  nullable="true"  primaryKey="false"  unique="false"/>  

The db.changelog-master.xml is the changelog you pass to all Liquibase calls.

Managing stored procedures

Try to maintain separate changelog for Stored Procedures and use runOnChange=”true”. This flag forces Liquibase to check if the changeset was modified. If so, Liquibase executes the change again.

One change per changeset

As far as possible, Avoid multiple changes per changeset to avoid failed auto-commit statements that can leave the database in an unexpected state.

changeset ids

Choose what works for you. Some use a sequence number starting from 1 and unique within the changelog , some choose a descriptive name (e.g. ‘new-address-table').

Document changesets

Use <comments> in the changesets. They say “A stitch in time saves nine!”

Always think about rollback

Try to write changesets in a way that they can be rolled back. e.g. use relevant change clause instead of using custom <sql> tag. Include a <rollback> clause whenever a change doesn't support out of box rollback. (e.g. <sql>, <insert>, etc).

Reference data management

Leverage Liquibase to manage your Reference Data. Environment separation (DEV, QA, PROD) can be achieved using “context”. See Contexts to learn more.

Procedure for the developer

  • Using your favorite IDE or editor, create a new local changesets containing the change.
  • Run Liquibase to execute the new changesets (this tests the SQL code).
  • Perform the corresponding changes in the application code (e.g., Java code).
  • Test the new application code together with the database change.
  • Commit both changesets and the application code.

Consider Liquibase Pro or Datical Enterprise

Liquibase Pro

Liquibase Pro offers an extra layer of support so you don't have to go it alone. While Liquibase is a great starting point, teams that want best practices on how to make the most of Liquibase may find Liquibase Pro better suited to their needs. Liquibase Pro also adds features like Targeted Rollback and the ability to work with Stored Logic.

Datical Enterprise

Datical Enterprise is a commercial product which builds on the core Liquibase functionality. Beyond versioning and managing database changes, Datical Enterprise bridges the gap between development and operations with capabilities that enable a fully unified and automated path for database code.

  • Datical Enterprise has a web interface, command line interface, and REST API. All interfaces are secure and require authentication.
  • Datical Enterprise automatically verifies database code against organizational standards to eliminate manual review.
  • Datical Enterprise automatically generates changesets from validated DDL code, eliminating manual effort in crafting changesets and manually updating the changelog.
  • Datical Enterprise generates an immutable artifact for database code for consistent, repeatable, and automation-ready downstream deployments.
  • Datical Enterprise forecasts the impact of database changes with an object-based model of the target database to ensure that there are no errors or issues when deploying database changes.
  • Datical Enterprise integrates with ticketing systems such as JIRA to make it easy to trace database changes back to source code and initial requirements. This same capability also makes it easy to hold or accelerate feature sets.
  • Datical Enterprise can snapshot and compare database schemas to help identify and address drift.

For more information on Datical Enterprise, visit