Skip to main content

​
Supabase Migration Reliability (Production)

This runbook is the production-safe migration path for Switchbord.
  • Supabase project ref: jazlpcbhkjtsbxeevesq
  • Repository: switchbord
  • Migration source of truth: supabase/migrations
Use this when you are applying migrations to production or repairing migration history after a failed deployment.

​
1) Pre-flight checks

Run these checks before any production migration command.
  1. Confirm you are in the correct repo and branch.
  2. Confirm migration SQL is reviewed and merged.
  3. Confirm a rollback owner and communication channel are in place.
  4. Confirm Supabase backup/PITR posture is healthy for the target window.
  5. Run the non-destructive helper script:
The script checks:
  • env key presence and parsing pitfalls
  • Supabase CLI install/login status
  • link status for this repo
  • migration list snapshots (linked + local when available)
If the script reports failures, resolve those first. Authenticate and link this working copy to the production project:
Verify link status:
If this command says “Cannot find project ref”, the repo is not linked in this working copy.

​
3) Inspect migration drift

Before applying new migrations, inspect drift between migration files and production schema.
Do not apply until drift output is understood and approved.

​
4) Safe apply sequence for production

Use this exact sequence:
  1. Freeze new migration merges during the window.
  2. Run preflight script and archive the generated snapshot files.
  3. Run supabase db push --linked --dry-run --workdir . and review output.
  4. Apply migrations:
  1. Immediately run verification checklist (section 6).
If any migration fails, stop and switch to section 5 (repair path).

​
5) Recovery path using supabase migration repair

Use migration repair only to correct migration history metadata after you verify actual schema state. It does not apply or revert SQL by itself. Common cases:
  1. SQL already applied, but migration history is missing that version:
  1. Migration was marked applied, but schema change was not actually applied:
After repair:
Never edit an already-applied migration file to “fix” production. Create a new forward migration instead.

​
6) Verification checklist and rollback guidance

Verification checklist (run immediately after apply):
  • supabase migration list --linked --workdir . shows expected versions applied.
  • supabase db diff --linked --schema public --workdir . has no unexpected drift.
  • Runtime health checks remain green (/health, /ready, critical endpoints).
  • Critical flows are smoke-tested (auth, inbox reads/writes, queue/worker path).
  • No new errors in logs for RLS, missing columns, or enum cast failures.
Rollback guidance:
  • Default strategy is forward-fix, not in-place rollback.
  • If apply fails mid-flight, pause deploys, assess schema state, and use migration repair to realign metadata before re-running push.
  • For destructive mistakes or unrecoverable data impact, use Supabase backup/PITR restore to a known-good timestamp and follow incident response.
  • Document the incident and the exact reconciliation steps before the next migration window.

​
7) Known Switchbord pitfalls

  1. Enum ALTER TYPE ... ADD VALUE must be isolated.
    • We have explicit notes in migrations like:
      • 20260417000002b_outbox_status_enum.sql
      • 20260418000001_member_role_billing.sql
    • Do not combine enum value additions with schema objects that immediately depend on new enum values in the same transactional migration.
  2. Env parsing and alias pitfalls.
    • Switchbord currently supports both canonical and legacy aliases:
      • NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY and NEXT_PUBLIC_SUPABASE_ANON_KEY
      • SUPABASE_SECRET_KEY and SUPABASE_SERVICE_ROLE_KEY
    • Mismatched alias values can cause inconsistent behavior across services.
    • Trailing whitespace, CRLF, or accidental quoting in env values can break auth/linking unexpectedly.
  3. SUPABASE_DB_URL is required for direct Postgres/Vault operations.
    • If missing, migration-adjacent operational tasks can fail even when API key auth works.

​
Helper script reference

Use this helper before each production migration window:
Optional flags: