How to Use Liquibase with Spring Boot for Database Migrations

To use Liquibase with Spring Boot, add the liquibase-core dependency to your project and place your database change scripts in src/main/resources/db/changelog. Spring Boot auto-configures Liquibase to run these scripts on application startup, managing your database schema changes smoothly.

Syntax

Liquibase integration in Spring Boot requires adding the liquibase-core dependency and configuring the changelog file location. The main parts are:

• Dependency: Adds Liquibase library to your project.
• ChangeLog file: XML, YAML, or JSON file describing database changes.
• Spring Boot auto-configuration: Detects Liquibase and runs migrations on startup.

groovy

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.liquibase:liquibase-core'
}

spring.liquibase.change-log=classpath:/db/changelog/db.changelog-master.xml

Example

This example shows a Spring Boot application using Liquibase to create a person table on startup. The changelog XML defines the table and columns.

plaintext

/* build.gradle (dependencies section) */
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.liquibase:liquibase-core'
    runtimeOnly 'com.h2database:h2'
}

/* application.properties */
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.liquibase.change-log=classpath:/db/changelog/db.changelog-master.xml

/* src/main/resources/db/changelog/db.changelog-master.xml */
<?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 id="1" author="user">
        <createTable tableName="person">
            <column name="id" type="BIGINT" autoIncrement="true">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="first_name" type="VARCHAR(50)"/>
            <column name="last_name" type="VARCHAR(50)"/>
        </createTable>
    </changeSet>

</databaseChangeLog>

Output

INFO  --- Liquibase: Successfully released change log lock
INFO  --- Liquibase: Update has been successfully applied to database

Common Pitfalls

Common mistakes when using Liquibase with Spring Boot include:

• Not adding the liquibase-core dependency, so migrations don't run.
• Incorrect spring.liquibase.change-log path causing Liquibase to not find changelog files.
• Using incompatible database URLs or missing datasource configuration.
• Forgetting to commit changelog files to version control, losing migration history.

Always verify your changelog syntax and test migrations on a test database before production.

groovy

/* Wrong: Missing liquibase-core dependency */
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
}

/* Right: Add liquibase-core */
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.liquibase:liquibase-core'
}

Quick Reference

• Dependency: Add org.liquibase:liquibase-core to your build.
• Changelog location: Configure spring.liquibase.change-log to point to your changelog file.
• Database config: Set datasource properties for your database.
• Run: Liquibase runs automatically on Spring Boot startup.

Key Takeaways

Add the liquibase-core dependency to enable Liquibase in Spring Boot.

Place your database change scripts in a changelog file and configure its path in application properties.

Liquibase runs automatically on application startup to apply pending migrations.

Verify datasource settings and changelog paths to avoid migration failures.

Keep changelog files under version control to track database changes safely.