Planning a Migration Change

Wikantik's database migrations live in `bin/db/migrations/`. The

convention is small and strict: numbered files, idempotent DDL, one

schema concern per file, and never edit after production.

When to use this runbook

Before any commit that adds, drops, renames, or alters a database object.

Context

`bin/db/migrate.sh` runs the unapplied migrations in order against the

configured database. `bin/deploy-local.sh` calls it on every redeploy,

so locally-pending migrations apply automatically.

The `:app_user` psql variable is bound by the migrate script — using it

in `GRANT` statements keeps migrations portable between environments

where the application role has a different name.

Walkthrough

The frontmatter `steps` are the canonical procedure. Local apply +

re-apply (steps 4–5) is the cheap way to catch idempotence bugs before

they hit production.

Pitfalls

The frontmatter `pitfalls` capture the failure modes worth memorising.

The "editing after prod" rule is the most expensive to violate — it

splits the migration history between "what production has applied" and

"what the source tree says was applied", and that divergence is

extremely painful to recover from.