Skip to content

Database rules

What a schema change MUST satisfy. This binds db/migrations/ and both trees under supabase/migrations/.

Writing a migration

DB-1: A committed migration MUST NOT be edited

  • You MUST express every schema change as a new migration file.
  • DO NOT edit a migration that is already committed.
  • To drop a table, leave the initialization/ baseline creating it. Add an incremental/ migration that drops it.
  • To correct a stale COMMENT, re-issue it from a new migration.
  • A baseline collapse under DB-3 is the one exception.

A Supabase preview branch applies only new migration files, so an edit never runs there.

Enforcement: Review only.

DB-2: A schema migration MUST be compatible with the deployed version

  • The deployed code MUST keep working against the new schema.
  • Adding a column, backfilling it and dropping the old one are three deploys, not one.
  • A destructive step MUST come after the code that stopped using the old shape is deployed everywhere.

Enforcement: squawk (pre-commit) for a subset of unsafe statements. Review only for the rest.

The migration history

DB-3: Migrations SHOULD be collapsed to a baseline periodically

See /db.

Enforcement: none. See enforcement gaps.