Migrations
Migrations are goose SQL files embedded in the binary (migrations) and are the single
schema source for both goose and sqlc.
Policy
- Migrations run as an explicit, gated release step (
ims migrate), never on application boot or replica start.release.shruns them before switching thecurrentsymlink. - Expand/contract for multi-instance safety:
- Expand — additive, backwards-compatible changes (new nullable columns, new tables, new
indexes
CONCURRENTLY) ship with the release. - Deploy the code that uses them.
- Contract — removing columns/tables — ships one release later, once nothing reads them.
- Expand — additive, backwards-compatible changes (new nullable columns, new tables, new
indexes
- Never edit a migration that has shipped; add a new one.
internal/dbgenis generated from the migrations — runmake sqlcand commit the result (CI fails on a generated-code diff).
Commands
ims migrate # apply all pending migrationsims migrate:status # applied vs pending versionsims migrate:rollback # revert the most recent migration (goose Down)The health endpoint flags schema drift (embedded vs applied versions), so a release that forgets to migrate surfaces immediately.
Concurrency
ims migrate acquires goose’s advisory lock; run it once per deploy, not per replica. In
multi-instance setups, run migrations from the release step on a single host (or a dedicated
migration job) before rolling the units.
SQLite
Not supported in v1 (PostgreSQL only). The SQLite adapter is deferred to a future version; see design decision 22.
Recovering from a failed migration
- Read the error (
ims migrateoutput / journald). - Fix forward with a new migration where possible.
- To undo the last applied migration:
ims migrate:rollback, then correct the file and re-apply. - Restore from backup if a data migration went wrong (see the DB-specific runbook).