Migrations workflow

Purpose

Every schema change is a reviewed file in git, applied the same way everywhere.

The standard

• All changes via supabase/migrations/<timestamp>_<description>.sql. No hand edits in the dashboard on prod (dev is allowed for exploration, then captured with supabase db diff).

• Forward-only. Reversals are new migrations.

• One concern per migration; RLS policies for a new table live in the same file.

• Migrations are idempotent where practical (if not exists).

• Data migrations (backfills) separate from schema migrations and run in batches.

Procedure

1. npx supabase migration new add_panels_table → edit the SQL.

2. Apply locally: npx supabase db reset (local Docker) or npx supabase db push against dev.

3. npm run db:types; update code; write RLS tests.

4. PR includes the migration; CI validates.

5. On release: npx supabase db push --linked against prod by the owner, before the app deploy that depends on it (make the app tolerate both shapes for one release when needed).

Anti-patterns

Dashboard edits on prod; migrations that drop columns in the same release as the code that stops using them.

Owner: Matt · Last reviewed: 2026-09