Migrations¶

Como gerar uma nova migration¶

1. Edite o schema no arquivo correspondente em supabase/schemas/:

2. Gere o diff:

make db-diff

Isso compara o schema declarativo com o banco local e cria um arquivo em supabase/migrations/ com timestamp. Revise o arquivo gerado antes de continuar — o diff pode incluir mudanças não intencionais (ver Problemas Conhecidos).

3. Valide localmente:

make db-reset

Aplica todas as migrations do zero. Se funcionar sem erros, está pronto.

4. Commite schema + migration juntos:

git add supabase/schemas/ supabase/migrations/
git commit -m "feat(db): descrição da mudança"

O make db-push não é necessário — a esteira de CI/CD aplica as migrations automaticamente no merge para develop e main. Você só comita; o deploy cuida do resto.

Criar arquivo de migration vazio¶

Para migrations de dados (backfill) ou casos onde o diff não captura a mudança:

make db-migration
# → "Migration name (snake_case): add_contact_tags"
# → supabase/migrations/20260310120000_add_contact_tags.sql

Migrations de dados (DDL + DML separados)¶

Quando precisar migrar dados junto com mudança de schema, use migrations separadas em ordem:

20260310000000_add_language_column.sql     ← 1. DDL: ADD COLUMN
20260310000001_backfill_language.sql       ← 2. DML: UPDATE dados existentes
20260310000002_add_not_null_constraint.sql ← 3. DDL: constraint após backfill

O timestamp do DML deve ser posterior ao DDL. O Supabase aplica em ordem crescente de timestamp.

Verificar status das migrations¶

make db-status

Lista todas as migrations e quais já foram aplicadas (útil para debugar discrepâncias entre local e remoto).