Liquibase in Spring Boot – Developer's Guide

Source: Dev.to

What Liquibase Is and Why It Matters

Liquibase is essentially Git for your database schema. Instead of running SQL scripts manually and hoping everyone runs them correctly, you define changes in a structured format and Liquibase tracks which ones have been applied.

Example XML Changeset

Liquibase keeps track of applied migrations in a table called DATABASECHANGELOG, ensuring:

• Changes are applied only once
• Order is maintained
• Rollbacks are possible

Key Benefits

• Consistent environments – dev, staging, and prod stay in sync
• Migration history – see who changed what and when
• Automatic migrations – Spring Boot can run them on startup
• Rollbacks – undo changes safely if needed

Setting Up Liquibase in Spring Boot

Maven Dependency

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

Gradle Dependency

implementation 'org.liquibase:liquibase-core'

Spring Boot will automatically detect Liquibase and run migrations.

Configuration (application.yml)

spring:
  liquibase:
    change-log: "classpath:/db/changelog/changelog.xml"
    contexts: "dev"

Typical Project Structure

src/main/resources
 └─ db
    └─ changelog
        └─ changelog.xml

Writing Migrations

Full XML Changelog Example (changelog.xml)

Formatted SQL Changeset Example

-- liquibase formatted sql
-- changeset dev:create-users
CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP
);

-- changeset dev:add-email-index
CREATE INDEX idx_users_email ON users(email);

-- changeset dev:add-phone-column
ALTER TABLE users ADD COLUMN phone_number VARCHAR(20);
-- rollback: ALTER TABLE users DROP COLUMN phone_number;

Best Practices

• Never edit executed migrations – migrations are immutable.
• One changeset = one change – keep each changeset focused (e.g., a single table, column, or index).
• Number your files if using multiple files to avoid Git conflicts.
• Test locally – drop the DB, run the app, and ensure migrations work from scratch.
• Be careful on production – avoid ALTER COLUMN TYPE, DROP COLUMN, or adding NOT NULL constraints on large tables without proper planning.

Feature Comparison

Flyway is simpler, but Liquibase offers more flexibility for enterprise setups.

Conclusion

Liquibase is a lifesaver for keeping database schema consistent across environments. Stick to the golden rules:

• Immutable migrations
• One change per changeset
• Test migrations locally

Thanks for reading!