Keep your changelogs organized

The most common way we see changelogs organized 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.

Manage 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.

Keep it to one change per changeset

Avoid multiple changes per changeset so you can avoid failed auto-commit statements that can leave the database in an unexpected state.

Choosing changeset IDs

Choose a changeset ID that works for you. Some use a number sequence starting from 1 and unique within the changelog. Others choose a descriptive name (e.g., ‘new-address-table’).

Document changesets

Always use <comments> in the changesets. As they say, “A stitch in time saves nine!”

Always have a rollback plan

Write changesets in a way that they can be rolled back. For example, use a relevant change clause instead of using a custom <sql> tag. Include a <rollback> clause whenever a change doesn’t support an out-of-box rollback. (e.g., <sql>, <insert>, etc). Learn more about rollbacks.

Manage your reference data

Leverage Liquibase to manage your reference data. Environment separation (DEV, QA, PROD) can be achieved using contexts. Learn about Liquibase contexts.

Typical procedure for the developer

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

Using Liquibase to achieve CI/CD for databases

Database schema migrations are an essential task for every software project. Learn how to integrate Liquibase into your process to achieve CI/CD for databases.

Consider advanced Liquibase features and support

Advanced features and support designed for teams of all sizes is available via

Liquibase Pro

Advanced database change features plus support when you need it. Great for developers and small teams.

Learn More
Liquibase Business

Automation that brings CI/CD to the database plus support SLAs your team can count on. Perfect for businesses that need a solution that scales.

Learn More
Liquibase Enterprise

Fast, safe database deployments that make it easy to enforce governance and stay compliant. Premium support included. Ideal for enterprises and businesses in regulated industries.

Learn More