# Zero-Downtime Supabase Migration Checklist

Use this checklist in the pull request that introduces a production Supabase migration.

## Classification

- [ ] Migration type is identified: expand, bridge, backfill, validate, switch, or contract.
- [ ] The PR explains which application version reads or writes the old schema.
- [ ] The PR explains which application version reads or writes the new schema.
- [ ] The migration does not combine expand and contract in one release.

## Compatibility

- [ ] Old application code can still run after this migration.
- [ ] New application code can run before all rows are backfilled.
- [ ] Reads use a fallback while data is mixed.
- [ ] Writes dual-write when old and new fields must stay in sync.
- [ ] RLS policies support both old and new access paths during rollout.

## Postgres Safety

- [ ] Risky statements use `lock_timeout`.
- [ ] Long-running statements use `statement_timeout`.
- [ ] Large updates run in batches.
- [ ] Backfills use a resumable key, such as `id`, `created_at`, or `FOR UPDATE SKIP LOCKED`.
- [ ] New foreign keys or checks use `NOT VALID` before `VALIDATE CONSTRAINT`.
- [ ] Large hot-table indexes have a concurrent index plan.
- [ ] Any `DROP COLUMN`, `RENAME COLUMN`, or `SET NOT NULL` has explicit review.

## Supabase Workflow

- [ ] Migration was created with `supabase migration new`.
- [ ] Migration was tested locally with `supabase db reset`.
- [ ] Remote changes were not made manually through the production dashboard.
- [ ] `supabase migration list --linked` does not show unexpected drift.
- [ ] `supabase db push --dry-run` output is reviewed.
- [ ] Generated TypeScript types are updated when schema shape changes.

## Rollback and Monitoring

- [ ] Rollback plan starts with application rollback, not destructive SQL.
- [ ] Backfill can be paused safely.
- [ ] Latest usable backup or PITR restore point is confirmed for high-risk work.
- [ ] Owner is assigned for the deploy window.
- [ ] Monitoring covers error rate, database CPU, locks, and slow queries.
- [ ] Contract cleanup is scheduled for a later release.

## PR Notes Template

```md
## Migration Plan

Phase:
Tables touched:
Expected lock risk:
Backfill required:
RLS impact:
Type generation impact:

## Rollout Plan

1.
2.
3.

## Rollback Plan

1.
2.
3.
```