Skip to content

ADR: Apply schema changes only through an explicit migrator

Record

Field Value
Date 2026-07-15
Status Accepted
Owner Maintainers
Author Danny Sauer
Scope How the database schema changes and how a running service checks it. It doesn't cover backup tooling or retention.
Related Why database migrations are explicit, upgrade procedure
Implementation PR #17, issue #6

Business driver

The database holds pending revocations, generations, leases, and audit evidence that the authorization path depends on. A database with the wrong schema can still answer a health query while missing state the service needs, and the first symptom could be a check that succeeds when it shouldn't.

Constraints

  • Webhook replicas shouldn't need schema-changing database privileges.
  • Replicas from two application versions must not race to change the schema during a rollout.
  • A failed migration must be visible before traffic moves.

Decision

Y statement: We will change the schema only through an explicit Alembic migration command, run as its own Helm Job, and have every service process refuse to start unless the database matches its one expected head and release contract, because a silently wrong schema can turn into a wrong authorization result, so operators see exactly one bounded change before traffic moves.

The decision has these boundaries:

  • Normal startup never creates or alters tables.
  • Each application artifact accepts exactly one Alembic head. Every head change is a restore boundary, even for an additive change.
  • Alembic downgrades aren't an operator interface. Rollback across a head change means restoring the backup taken before the migration.
  • The migration Job gets its own Secret, environment, and ServiceAccount, and doesn't inherit the runtime App credentials.

Consequences

  • Every schema-changing pull request needs a revision, fresh-install and upgrade tests, and an entry in the database upgrade notes.
  • Rolling back an image after a head change takes a database restore, not just an older image.
  • A deployment can give the runtime role no schema privileges at all.

Alternatives considered

Keep the current approach

Before this decision, the service created tables from ORM metadata at startup. That works for a first install, but it can't change an existing schema safely, needs schema privileges in every replica, and lets replicas from different versions race during a rollout.

Migrate automatically at startup

Run Alembic from each process before it serves traffic. This removes a deployment step, but it keeps schema privileges in every replica, invites concurrent migrations during rollouts, and hides a half-finished migration behind repeated pod restarts.