liquibase-migrations

Overview

Per github.com/liquibase/liquibase:

"Liquibase helps millions of developers track, version, and deploy database schema changes."

Liquibase's distinguishing feature vs Flyway: changesets are format-portable (XML / YAML / JSON / SQL) and rollback-aware - each changeset declares its own rollback action, enabling deterministic per-changeset rollback rather than versioned-only migration replay.

State tracked in two tables (per Liquibase docs):

• DATABASECHANGELOG - applied changeset history (id + author + filename + dateExecuted + checksum)
• DATABASECHANGELOGLOCK - distributed lock to serialize concurrent update runs

When to use

• The repo has db.changelog-master.xml / .yaml / .json.
• The user works with Spring Boot Liquibase auto-config or any of the Liquibase Maven / Gradle / Ant plugins.
• The team needs cross-DBMS portable migrations (XML/YAML changesets translate to per-DBMS SQL at apply time).
• Per-changeset rollback support is required (vs Flyway's whole-version rollback).

Step 1 - Install

Per lb-gh the documented quickstart:

# Download installer per platform from liquibase.com/download
# Add liquibase to PATH
liquibase init start-h2    # spin up an H2 dev DB to try it out

For CI / containerized usage:

docker pull liquibase/liquibase:latest
docker run --rm -v "$PWD/changelog:/liquibase/changelog" \
  -e LIQUIBASE_COMMAND_PASSWORD \
  liquibase/liquibase \
  --url=jdbc:postgresql://host/db \
  --username=user \
  --changelog-file=changelog/db.changelog-master.xml \
  update

Keep the password off the command line. Per lb-env, any command option can be set as LIQUIBASE_COMMAND_<option-name>, and the docs recommend it to keep passwords off the command line and out of committed liquibase.properties files. -e LIQUIBASE_COMMAND_PASSWORD with no value forwards the host's variable into the container (docker-env).

Maven dependency / Gradle plugin available for in-build invocation - consult docs.liquibase.com.

Step 2 - Changelog + changeset basics

A changelog is a file (or set of included files) containing one or more changeset entries. Each changeset has an id + author (these are the identity for the DATABASECHANGELOG row).

YAML example:

databaseChangeLog:
  - changeSet:
      id: 1
      author: alice
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: bigint
                  autoIncrement: true
                  constraints: { primaryKey: true, nullable: false }
              - column:
                  name: email
                  type: varchar(255)
                  constraints: { unique: true, nullable: false }
      rollback:
        - dropTable:
            tableName: users
  - changeSet:
      id: 2
      author: alice
      changes:
        - addColumn:
            tableName: users
            columns:
              - column: { name: created_at, type: timestamp }
      rollback:
        - dropColumn: { tableName: users, columnName: created_at }

Equivalent forms in XML / JSON / SQL exist - pick by team preference; they're functionally equivalent at apply time. (Per lb-docs for format-specific syntax.)

Step 3 - Core commands

Per lb-gh and Liquibase command reference:

Command	Use
liquibase update	Apply pending changesets
liquibase status	List pending changesets
liquibase history	Show executed changesets
liquibase rollback <tag>	Roll back to a tagged state
liquibase rollback-count <n>	Roll back the last N changesets
liquibase tag <tag-name>	Mark current state with a tag (for later rollback)
liquibase changelog-sync	Mark all pending changesets as applied without running them (legacy adoption)
liquibase validate	Check changelog syntax + checksums

Step 4 - Preconditions

Changesets can declare preconditions that must hold before they're applied (or the changeset is skipped / failed):

- changeSet:
    id: 3
    author: alice
    preConditions:
      - onFail: MARK_RAN     # if precondition fails, mark as run without executing
      - onError: MARK_RAN
      - tableExists: { tableName: users }
    changes:
      - addColumn: { tableName: users, columns: [{ column: { name: status, type: varchar(20) }}] }

Common precondition predicates: tableExists, columnExists, viewExists, indexExists, foreignKeyConstraintExists, changeSetExecuted, dbms (e.g., only-on-postgresql), primaryKeyExists, sqlCheck (custom SQL returning a single value).

onFail / onError actions: HALT (default - fails the run), CONTINUE, MARK_RAN, WARN.

Step 5 - Contexts and labels

Selective changeset execution per environment / feature:

- changeSet:
    id: 4
    author: alice
    contexts: dev,test          # only run when --contexts dev or test
    labels: experimental         # filterable by --labels selector
    changes:
      - createTable: { tableName: feature_x_audit, columns: [...] }

Run contexts at apply time:

liquibase update --contexts="dev,test"
liquibase update --label-filter="!experimental"  # exclude experimental

Step 6 - Include + includeAll for splitting changelogs

Master changelog references file groups (per docs.liquibase.com/concepts/changelogs):

databaseChangeLog:
  - include: { file: changelog/v1.0/users.yaml }
  - include: { file: changelog/v1.0/orders.yaml }
  - includeAll: { path: changelog/v2.0/, errorIfMissingOrEmpty: true }

The includeAll orders files alphabetically; use prefixes (001-users.yaml, 002-orders.yaml) to enforce order.

Step 7 - CI integration

- run: docker run --rm --network=host \
    -v "$PWD/changelog:/liquibase/changelog" \
    -e LIQUIBASE_COMMAND_PASSWORD \
    liquibase/liquibase:latest \
    --url=jdbc:postgresql://localhost:5432/test \
    --username=postgres \
    --changelog-file=/liquibase/changelog/db.changelog-master.xml \
    update
  env:
    LIQUIBASE_COMMAND_PASSWORD: ${{ secrets.CI_DB_PASSWORD }}
- run: mvn test

Per the testcontainers skill, ephemeral DB + liquibase update is the standard pattern.

Step 8 - Composition with sister tools

Before merge, apply adversarial review of new changesets - classify as additive / breaking / data-loss / locking; estimate downtime.

Anti-patterns

Anti-pattern	Why it fails	Fix
Reuse a changeset id after it's been deployed	Checksum mismatch on next update; deploys fail	New id per change; never edit deployed changesets
Rollback section omitted	liquibase rollback fails silently; downtime	Author rollback per changeset (Step 2)
Use runAlways: true for migrations	Reruns every deploy; data corruption risk	runAlways is for runInTransaction: false admin scripts only
Mix XML + YAML + JSON in one repo	Reviewer cognitive load; sloppy diffs	Pick one format per repo
Skip preconditions on conditional changes	Apply fails on environments where preconditions don't hold	Use dbms/tableExists preconditions (Step 4)

Limitations

• Per-changeset rollback only works if every author writes the rollback section; OSS Liquibase doesn't auto-generate them for most change types.
• Cross-DBMS portability of changesets has limits - DBMS-specific syntax (e.g., Postgres JSONB columns) requires dbms precondition
  • per-DBMS variants.
• The DATABASECHANGELOGLOCK table can deadlock if a previous run crashed mid-update; liquibase release-locks recovers (note: this command name varies between Liquibase versions; consult lb-docs).
• Liquibase Pro features (Quality Checks, Drift Reports, Targeted Rollback) are paid; the OSS edition covers the patterns above.

References

• lb-gh - repository, install, supported databases
• lb-cl - changelog concept page
• lb-docs - full documentation
• lb-env - LIQUIBASE_COMMAND_<option-name> environment variables
• docker-env - docker run -e VAR forwards the host value
• flyway-migrations, atlas-migrations, sqlmesh-migrations - sister tools (Flyway = SQL-first versioned; Atlas = declarative HCL; SQLMesh = data-pipeline + schema)