Skip to main content

​
Confiabilidade de Migração do Supabase (Produção)

Este runbook é o caminho seguro para migrações em produção do Switchbord.
  • Ref do projeto Supabase: jazlpcbhkjtsbxeevesq
  • Repositório: switchbord
  • Fonte de verdade das migrações: supabase/migrations
Use isto ao aplicar migrações em produção ou ao reparar o histórico de migração após um deployment falho.

​
1) Verificações de pré-voo

Execute estas verificações antes de qualquer comando de migração em produção.
  1. Confirme que você está no repositório e branch corretos.
  2. Confirme que o SQL da migração foi revisado e mesclado (merged).
  3. Confirme que um responsável pelo rollback e um canal de comunicação estão definidos.
  4. Confirme que a postura de backup/PITR do Supabase está saudável para a janela alvo.
  5. Execute o script auxiliar não destrutivo:
O script verifica:
  • presença de chaves de env e possíveis armadilhas de parsing
  • status de instalação/login da Supabase CLI
  • status de link para este repositório
  • snapshots da lista de migrações (linked + local quando disponível)
Se o script reportar falhas, resolva-as primeiro. Autentique e vincule esta cópia de trabalho ao projeto de produção:
Verifique o status do link:
Se este comando disser “Cannot find project ref”, o repositório não está vinculado nesta cópia de trabalho.

​
3) Inspecionar o drift de migração

Antes de aplicar novas migrações, inspecione o drift entre os arquivos de migração e o schema de produção.
Não aplique até que a saída do drift esteja compreendida e aprovada.

​
4) Sequência de aplicação segura para produção

Use exatamente esta sequência:
  1. Congele novos merges de migração durante a janela.
  2. Execute o script de pré-voo e arquive os arquivos de snapshot gerados.
  3. Execute supabase db push --linked --dry-run --workdir . e revise a saída.
  4. Aplique as migrações:
  1. Execute imediatamente a checklist de verificação (seção 6).
Se qualquer migração falhar, pare e mude para a seção 5 (caminho de reparo).

​
5) Caminho de recuperação usando supabase migration repair

Use migration repair apenas para corrigir os metadados do histórico de migração após verificar o estado real do schema. Ele não aplica nem reverte SQL por si só. Casos comuns:
  1. SQL já aplicado, mas o histórico de migração não tem essa versão registrada:
  1. A migração foi marcada como aplicada, mas a alteração de schema não foi realmente aplicada:
Após o reparo:
Nunca edite um arquivo de migração já aplicado para “corrigir” a produção. Em vez disso, crie uma nova migração para frente (forward migration).

​
6) Checklist de verificação e orientação de rollback

Checklist de verificação (execute imediatamente após aplicar):
  • supabase migration list --linked --workdir . mostra as versões esperadas aplicadas.
  • supabase db diff --linked --schema public --workdir . não apresenta drift inesperado.
  • As verificações de saúde do runtime permanecem verdes (/health, /ready, endpoints críticos).
  • Os fluxos críticos passam por smoke test (auth, leituras/escritas de inbox, caminho de queue/worker).
  • Não há novos erros nos logs para RLS, colunas ausentes ou falhas de cast de enum.
Orientação de rollback:
  • A estratégia padrão é a correção para frente (forward-fix), não o rollback no local.
  • Se a aplicação falhar no meio do caminho, pause os deploys, avalie o estado do schema e use migration repair para realinhar os metadados antes de executar o push novamente.
  • Para erros destrutivos ou impacto de dados irrecuperável, use a restauração de backup/PITR do Supabase para um timestamp conhecido como bom e siga a resposta a incidentes.
  • Documente o incidente e os passos exatos de reconciliação antes da próxima janela de migração.

​
7) Armadilhas conhecidas do Switchbord

  1. ALTER TYPE ... ADD VALUE em enum deve ser isolado.
    • Temos notas explícitas em migrações como:
      • 20260417000002b_outbox_status_enum.sql
      • 20260418000001_member_role_billing.sql
    • Não combine adições de valor de enum com objetos de schema que dependem imediatamente dos novos valores de enum na mesma migração transacional.
  2. Armadilhas de parsing de env e de aliases.
    • O Switchbord atualmente suporta tanto aliases canônicos quanto legados:
      • NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY e NEXT_PUBLIC_SUPABASE_ANON_KEY
      • SUPABASE_SECRET_KEY e SUPABASE_SERVICE_ROLE_KEY
    • Valores de alias inconsistentes podem causar comportamento inconsistente entre serviços.
    • Espaços em branco no final, CRLF ou aspas acidentais em valores de env podem quebrar auth/linking de forma inesperada.
  3. SUPABASE_DB_URL é necessário para operações diretas de Postgres/Vault.
    • Se estiver ausente, tarefas operacionais adjacentes à migração podem falhar mesmo quando a autenticação via chave de API funciona.

​
Referência do script auxiliar

Use este auxiliar antes de cada janela de migração em produção:
Flags opcionais: