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

# Reliability delle Migrazioni Supabase (Produzione)

> Controlli pre-volo, ispezione del drift, apply sicura e recovery per le migrazioni Supabase in produzione.

# Reliability delle Migrazioni Supabase (Produzione)

Questo runbook è il percorso di migrazione production-safe per Switchbord.

* Ref del progetto Supabase: `jazlpcbhkjtsbxeevesq`
* Repository: `switchbord`
* Fonte di verità delle migrazioni: `supabase/migrations`

Usa questo runbook quando applichi migrazioni in produzione o quando ripari la cronologia delle migrazioni dopo un deployment fallito.

## 1) Controlli pre-volo

Esegui questi controlli prima di qualsiasi comando di migrazione in produzione.

1. Conferma di essere nel repo e nel branch corretti.
2. Conferma che l'SQL della migrazione sia stato revisionato e mergiato.
3. Conferma che un owner del rollback e un canale di comunicazione siano stabiliti.
4. Conferma che la postura di backup/PITR di Supabase sia sana per la finestra target.
5. Esegui lo script helper non distruttivo:

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

Lo script controlla:

* presenza delle chiavi d'ambiente e insidie di parsing
* stato di installazione/login della Supabase CLI
* stato di link per questo repo
* snapshot dell'elenco delle migrazioni (collegate + locali, quando disponibili)

Se lo script segnala fallimenti, risolvili prima di procedere.

## 2) Collega il progetto di produzione

Autentica e collega questa copia di lavoro al progetto di produzione:

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

Verifica lo stato del collegamento:

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

Se questo comando restituisce "Cannot find project ref", il repo non è collegato in questa copia di lavoro.

## 3) Ispeziona il drift delle migrazioni

Prima di applicare nuove migrazioni, ispeziona il drift tra i file di migrazione e lo schema di produzione.

```bash theme={null}
# allineamento della cronologia (file locali vs tabella delle migrazioni remota)
supabase migration list --linked --workdir .

# controllo del drift dello schema (dovrebbe essere vuoto o esplicitamente compreso)
supabase db diff --linked --schema public --workdir .

# cosa verrebbe applicato, senza applicare nulla
supabase db push --linked --dry-run --workdir .
```

Non applicare finché l'output del drift non è compreso e approvato.

## 4) Sequenza di apply sicura per la produzione

Usa questa sequenza esatta:

1. Blocca (freeze) i nuovi merge di migrazioni durante la finestra.
2. Esegui lo script di preflight e archivia i file di snapshot generati.
3. Esegui `supabase db push --linked --dry-run --workdir .` e rivedi l'output.
4. Applica le migrazioni:

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

1. Esegui immediatamente la checklist di verifica (sezione 6).

Se una migrazione fallisce, fermati e passa alla sezione 5 (percorso di riparazione).

## 5) Percorso di recovery con `supabase migration repair`

Usa `migration repair` solo per correggere i metadati della cronologia delle migrazioni dopo aver verificato lo stato effettivo dello schema.
Non applica né annulla l'SQL da solo.

Casi comuni:

1. L'SQL è già stato applicato, ma la cronologia delle migrazioni non riporta quella versione:

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

1. La migrazione era segnata come applicata, ma la modifica dello schema non è stata effettivamente applicata:

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

Dopo la riparazione:

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

Non modificare mai un file di migrazione già applicato per "correggere" la produzione. Crea invece una nuova migrazione forward.

## 6) Checklist di verifica e indicazioni di rollback

Checklist di verifica (da eseguire immediatamente dopo l'apply):

* `supabase migration list --linked --workdir .` mostra le versioni attese come applicate.
* `supabase db diff --linked --schema public --workdir .` non presenta drift inaspettato.
* I controlli di salute del runtime restano verdi (`/health`, `/ready`, endpoint critici).
* I flussi critici vengono testati con smoke test (autenticazione, letture/scritture dell'inbox, percorso coda/worker).
* Nessun nuovo errore nei log relativo a RLS, colonne mancanti o fallimenti di cast enum.

Indicazioni di rollback:

* La strategia predefinita è il forward-fix, non il rollback in-place.
* Se l'apply fallisce a metà, metti in pausa i deploy, valuta lo stato dello schema e usa `migration repair` per riallineare i metadati prima di rieseguire il push.
* Per errori distruttivi o impatti sui dati non recuperabili, usa il restore di backup/PITR di Supabase a un timestamp noto come valido e segui la risposta agli incidenti.
* Documenta l'incidente e i passaggi esatti di riconciliazione prima della prossima finestra di migrazione.

## 7) Insidie note di Switchbord

1. `ALTER TYPE ... ADD VALUE` sugli enum deve essere isolato.
   * Abbiamo note esplicite in migrazioni come:
     * `20260417000002b_outbox_status_enum.sql`
     * `20260418000001_member_role_billing.sql`
   * Non combinare le aggiunte di valori enum con oggetti dello schema che dipendono immediatamente dai nuovi valori enum nella stessa migrazione transazionale.

2. Insidie di parsing dell'ambiente e degli alias.
   * Switchbord attualmente supporta sia gli alias canonici che quelli legacy:
     * `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` e `NEXT_PUBLIC_SUPABASE_ANON_KEY`
     * `SUPABASE_SECRET_KEY` e `SUPABASE_SERVICE_ROLE_KEY`
   * Valori di alias non corrispondenti possono causare comportamenti incoerenti tra i servizi.
   * Spazi bianchi finali, CRLF o quotatura accidentale nei valori d'ambiente possono rompere inaspettatamente l'autenticazione/il collegamento.

3. `SUPABASE_DB_URL` è richiesto per le operazioni dirette su Postgres/Vault.
   * Se manca, i task operativi adiacenti alle migrazioni possono fallire anche quando l'autenticazione tramite chiave API funziona.

## Riferimento allo script helper

Usa questo helper prima di ogni finestra di migrazione in produzione:

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

Flag opzionali:

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