Liquibase Introduction and Implementation

Architect Database Change Management CI/CD

flowchart LR
  Dev("Developer\nWrite changeset")
  VCS("Version Control\nGit repository")
  CI("CI Pipeline\nTriggered on commit")
  Pkg("Package Repository\nFat-jar artifact")

  Dev -->|commit| VCS -->|trigger| CI -->|publish| Pkg

  subgraph CI_Detail["CI Validation"]
    direction LR
    S1("Stage 1\nBaseline Validation\nApply released scripts\nVerify schema integrity")
    S2("Stage 2\nUpgrade Validation\nApply new changesets\nValidate syntax & constraints")
    S1 -->|pass| S2
  end

  CI --- CI_Detail

  subgraph Targets["Deployment Targets"]
    direction LR
    LocalDev("Local Dev")
    Test("Test / QA")
    Staging("Staging")
    Prod("Production")
    Tenant("Tenant N")
  end

  Pkg -.->|deploy| Targets

Background

An evolving enterprise application supported multiple deployment environments and customer-specific tenant databases. Database schema changes were managed through ad-hoc SQL scripts with no formal process, leading to inconsistencies and difficulty tracking what had been applied where. The software development lifecycle needed standardization to scale development efforts and improve collaboration across a growing team.

Problem

1. No consistent execution process — Scripts were run manually on an ad-hoc basis, leading to drift between environments and making it difficult to determine which changes had been applied.
2. Poor version control practices — Scripts were not always committed to version control, resulting in lost or duplicated changes.
3. No local development support — There was no way to recreate the production database schema locally, forcing developers to work against shared environments.
4. Missing CI/CD validation — Schema scripts were not validated during the build pipeline, allowing syntax errors and constraint violations to reach production.
5. Expensive environment reproduction — Standing up local or test environments was time-consuming and error-prone, slowing down development and testing cycles.
6. Merge conflicts in schema changes — Incremental changes were difficult to coordinate when multiple developers modified the same tables or objects simultaneously.

Solution

Liquibase was introduced as the database schema change management tool, integrated into the CI/CD pipeline and developer workflow.

1. Liquibase as the single source of truth — All schema changes were authored as Liquibase changesets and committed to version control alongside application code.
2. Containerized CI validation — The CI system spun up a fresh database container for each build. Liquibase applied changesets to this container, verifying script correctness and catching syntax errors before merge.
3. Two-stage upgrade validation:
   • Baseline validation — The CI process applied all previously released changesets to verify existing scripts still applied cleanly, guarding against regressions.
   • Upgrade validation — New changesets were applied on top of the baseline to catch errors in table creation, column additions, and constraint definitions before deployment.
4. Fat-jar distribution — A single executable fat-jar was published to the package repository on each successful build. Developers downloaded this artifact to bootstrap their local database with the correct schema in seconds.
5. Uniform execution across environments — All environments and customer-specific tenants used the identical changeset scripts, eliminating drift and making it straightforward to audit what was deployed where.
6. Pull request-driven code review — All changeset modifications went through a pull request process, ensuring peer review of schema changes before they were merged. This added an additional layer of quality control and knowledge sharing across the team.

Outcome

1. Automated schema management — Consistent, repeatable database changes across all environments with zero manual intervention.
2. Full change traceability — Every schema modification was tracked in version control with a corresponding Liquibase change log entry, enabling easy auditing and rollback.
3. Faster developer onboarding — New team members could set up a fully functional local database in minutes using the fat-jar artifact.
4. Stronger security posture — Production changes were executed exclusively through service accounts with limited permissions. Developers no longer required direct database access, reducing the risk of accidental or unauthorized modifications.
5. Reduced deployment failures — The two-stage CI validation caught schema errors early, significantly reducing upgrade failures in staging and production.
6. Simplified client onboarding — Provisioning a database for a new client became a near error-free process. The same validated changeset scripts were applied to stand up a new tenant schema reliably, reducing onboarding time and eliminating manual setup mistakes.