Changing the schema
Liquibase is the only entry point; applied scripts are frozen and append-only.
The only entry point
Every schema change goes through a Liquibase migration. Editing the database by hand is forbidden, for a very practical reason: a hand-edited database cannot be reproduced on another machine.
Discipline
- Changesets are append-only: applied scripts are frozen; editing, deleting or renaming one fails the build.
- Column comments must be accurate — they are the first source for the next person (and for AI) trying to understand the table.
- Between tables use logical references, never physical foreign keys.
- The soft-delete column is NOT NULL DEFAULT 0.
Common operations
./gradlew bootRun # applies pending migrations at startup
./gradlew build # verifies no script was tampered with
When you got it wrong
- A changeset already applied: do not edit it, add a new changeset that fixes it.
- A changeset not yet applied: you may edit it directly.
- The test is simple: has this script run on another machine yet?
Tip: what this discipline buys you: any fresh machine that clones the code gets a schema identical to the rest of the team.
Last updated 2026-10-09Edit this page →