Skip to content

Database Migrations with Liquibase

Generated artifact. Do not edit manually.

Generated by: scripts/build_compendia.py Regenerate with: python3 scripts/build_compendia.py --compendium dev-handbook --web-and-tex Source of truth: docs/dev/source/

Language / Sprache: English (EN) · Deutsch (DE) | PDF: English PDF · Deutsches PDF

Compendium: §1 Documentation Guidelines · §2 Landscape JSON Reference · §3 Minimal Schema & Fallback · §4 Authoring Editors · §5 Graph Editor · §6 Flashcard Editor · §7 Node Ordering · §8 Liquibase · §9 Auto-Update (SSE)

8. Database Migrations with Liquibase

The Spring Boot backend enforces spring.jpa.hibernate.ddl-auto=validate: Hibernate validates JPA entities against the live schema on startup, while Liquibase exclusively owns every schema creation and migration.

8.1. Changelog Layout and Four-Step Migration Workflow

  • Master changelog: backend/src/main/resources/db/changelog/db.changelog-master.yaml includes ordered versioned files under backend/src/main/resources/db/changelog/changes/ (starting from 001-initial-schema.yaml, which uses preConditions with onFail: MARK_RAN so existing pre-Liquibase databases adopt tracking cleanly via DATABASECHANGELOG).
  • Four-step workflow for schema changes:
  • Update the JPA @Entity class in backend/src/main/java/com/skillpilot/backend/domain/.
  • Add a new numbered YAML file NNN-short-description.yaml under db/changelog/changes/ with a unique (id, author) changeset and explicit types/constraints.
  • Append an include entry to db.changelog-master.yaml.
  • Start the backend (./gradlew bootRun or ./gradlew test) so Liquibase applies the migration and Hibernate validate confirms exact JPA-to-SQL parity.
  • Immutability rule: Never edit an already committed and executed changeset (Liquibase checksum validation will fail startup); always append a new corrective changeset instead.