Liquibase: Getting Started

This section documents schema/database evolution using version-controlled migration tools — Liquibase (relational/SQL), Mongock (MongoDB, Java-native) and Flamingock (Mongock’s successor, generalized to any external system) — as described by each tool’s own official documentation: liquibase.org and docs.liquibase.com for Liquibase, docs.mongock.io for Mongock, and docs.flamingock.io for Flamingock — which are the references these pages are written and verified against.

This content was generated with the assistance of AI and should be verified against those official docs before being relied on in production.

Mongock is now maintained under the Flamingock GitHub organization (github.com/flamingock/mongock), and Flamingock is positioned as its successor — see Coming from Mongock. Readers starting a new project should default to Flamingock unless they have a specific reason to stay on Mongock.

This section’s bibliography lists the reference material consulted while preparing these pages.

Liquibase tracks and applies relational schema changes from a version-controlled changelog. This page covers the three common ways to run it and the four formats a changelog can be written in, then walks through a first minimal example.

Running Liquibase

The CLI

Liquibase ships a standalone command-line tool. Once installed and pointed at a changelog and a JDBC URL, the core commands are:

liquibase update              # apply every pending changeset
liquibase updateSQL           # print the SQL that update would run, without running it
liquibase status              # list pending changesets
liquibase rollback <tag>      # see database/schema-evolution/liquibase-rollback.adoc

See the User guide for the full CLI reference and installation instructions per platform.

Maven / Gradle Plugin

For a JVM project, the liquibase-maven-plugin or the community Gradle plugin runs the same commands as part of the build:

<plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <version>4.33.0</version>
    <configuration>
        <changeLogFile>src/main/resources/db/changelog/db.changelog-master.yaml</changeLogFile>
        <url>jdbc:postgresql://localhost:5432/app</url>
    </configuration>
</plugin>

mvn liquibase:update

Spring Boot Auto-Run-on-Startup

With liquibase-core on the classpath, Spring Boot runs update automatically on application startup, before the rest of the context finishes initializing:

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

This is the most common setup for an application that owns its own schema — the schema is always current the moment the application is up, with no separate deployment step.

The Four Changelog Formats

A Liquibase changelog is a list of changesets and can be written in any of four formats — mix and match across include/includeAll as needed:

Format Notes

Format	Notes
SQL	Plain SQL with `--liquibase formatted sql` structured comments marking each changeset. Most familiar to a DBA, least portable across database vendors.
XML	The original, most fully-featured format — every Liquibase change type has an XML representation.
YAML	Same structure as XML, less verbose; the most common choice for new projects.
JSON	Same structure as XML/YAML, in JSON; useful when changelogs are generated programmatically.

SQL

Plain SQL with --liquibase formatted sql structured comments marking each changeset. Most familiar to a DBA, least portable across database vendors.

XML

The original, most fully-featured format — every Liquibase change type has an XML representation.

YAML

Same structure as XML, less verbose; the most common choice for new projects.

JSON

Same structure as XML/YAML, in JSON; useful when changelogs are generated programmatically.

See What is a Changelog? for the full format reference.

A First Minimal Example

A YAML changelog with a single changeset creating a table:

databaseChangeLog:
  - changeSet:
      id: 1
      author: alberto
      changes:
        - createTable:
            tableName: person
            columns:
              - column:
                  name: id
                  type: bigint
                  autoIncrement: true
                  constraints:
                    primaryKey: true
              - column:
                  name: name
                  type: varchar(255)
                  constraints:
                    nullable: false

Applied from the CLI:

liquibase --changelog-file=db.changelog-master.yaml update

This creates the person table and records one row in DATABASECHANGELOG for changeset 1::alberto (see Liquibase: Tracking & Locking for what gets recorded). The next page, Liquibase: Changelogs & Changesets, covers changeset identity and organizing changelogs across multiple files in more depth.