Skip to main content

​
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:
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:
Verifica lo stato del collegamento:
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.
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:
  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:
  1. La migrazione era segnata come applicata, ma la modifica dello schema non è stata effettivamente applicata:
Dopo la riparazione:
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:
Flag opzionali: