> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Supabase Migration Reliability (Production)

> Pre-flight checks, drift inspection, safe apply, and recovery for production Supabase migrations.

# 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:

```bash theme={null}
scripts/supabase-migration-preflight.sh --workdir .
```

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.

## 2) Link the production project

Authenticate and link this working copy to the production project:

```bash theme={null}
supabase login
supabase link --project-ref jazlpcbhkjtsbxeevesq --workdir .
```

Verify link status:

```bash theme={null}
supabase migration list --linked --workdir .
```

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.

```bash theme={null}
# history alignment (local files vs remote migration table)
supabase migration list --linked --workdir .

# schema drift check (should be empty or explicitly understood)
supabase db diff --linked --schema public --workdir .

# what would be applied, without applying anything
supabase db push --linked --dry-run --workdir .
```

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:

```bash theme={null}
supabase db push --linked --workdir .
```

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:

```bash theme={null}
supabase migration repair <version> --status applied --linked --workdir .
```

1. Migration was marked applied, but schema change was not actually applied:

```bash theme={null}
supabase migration repair <version> --status reverted --linked --workdir .
```

After repair:

```bash theme={null}
supabase migration list --linked --workdir .
supabase db push --linked --workdir .
```

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:

```bash theme={null}
scripts/supabase-migration-preflight.sh --workdir .
```

Optional flags:

```bash theme={null}
scripts/supabase-migration-preflight.sh \
  --workdir . \
  --project-ref jazlpcbhkjtsbxeevesq \
  --snapshot-dir ./logs/migration-preflight
```