Some best practices to keep in mind when using Liquibase

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

  com
       example
         db
           changelog
             db.changelog-master.xml
             db.changelog-1.0.xml
             db.changelog-1.1.xml
             db.changelog-2.0.xml
           DatabasePool.java
           AbstractDAO.java 

db.changelog-master.xml

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"?>   
<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.8.xsd">  

  <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"/>   
</databaseChangeLog> 

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"?>   
<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.8.xsd">   
  <changeSet  author="authorName"  id="changelog-1.0">  
    <createTable  tableName="TablesAndTables">  
      <column  name="COLUMN1"  type="TEXT">  
        <constraints  nullable="true"  primaryKey="false"  unique="false"/>  
      </column>  
    </createTable>  
  </changeSet>  
</databaseChangeLog> 

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