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

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

> Verificações de pré-voo, inspeção de drift, aplicação segura e recuperação para migrações do Supabase em produção.

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

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

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.

## 2) Vincular (link) o projeto de produção

Autentique e vincule esta cópia de trabalho ao projeto de produção:

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

Verifique o status do link:

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

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.

```bash theme={null}
# alinhamento de histórico (arquivos locais vs tabela de migração remota)
supabase migration list --linked --workdir .

# verificação de drift de schema (deve estar vazia ou explicitamente compreendida)
supabase db diff --linked --schema public --workdir .

# o que seria aplicado, sem aplicar nada
supabase db push --linked --dry-run --workdir .
```

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:

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

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:

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

1. A migração foi marcada como aplicada, mas a alteração de schema não foi realmente aplicada:

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

Após o reparo:

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

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:

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

Flags opcionais:

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