Migrations SQL à mão e o drift DB↔Drizzle

Tem uma parte do nosso stack que contraria o tutorial padrão de Drizzle — e que, se a IA (ou um dev novo) não souber, gera erro silencioso e confusão. É como a gente lida com migrations. Este post conta a verdade do nosso repo, sem maquiagem.

O que o tutorial diz vs. o que a gente faz

O fluxo "de fábrica" do Drizzle: você altera o schema TS, roda db:generate/db:migrate e o ORM cuida do resto. Não é assim que funciona aqui.

No ClubPetro:

• As migrations são SQL escritas à mão em packages/db/drizzle/NNNN_*.sql.
• O _journal.json está desatualizado (para lá atrás, nos primeiros migrations).
• Por isso, db:migrate não é o mecanismo de aplicar mudança. Quem rodar achando que "migrei" pode não ter migrado nada.

Saber disso evita a frustração clássica: "rodei o migrate e o banco não mudou".

O drift DB ↔ Drizzle

Consequência direta: o schema TypeScript nem sempre reflete o banco real. Há colunas que existem no banco e não no .ts, e vice-versa. Exemplos reais documentados internamente envolvem tabelas onde o DB tem colunas que o Drizzle não conhece.

A regra que sai disso, e que vale pra todo vibe coding com dados:

Nunca assuma que o schema TS é a verdade. Cheque o banco real antes de mexer.

Como trabalhar com isso (e com IA)

1. Antes de criar/alterar dado, inspecione a base — pnpm db:studio, query via Drizzle ou SQL no Supabase Studio. É a regra nº1 da casa: verifique o que já existe.
2. Escreva a migration SQL à mão, no padrão NNNN_*.sql, com RLS incluído (#20).
3. Dê esse contexto pra IA. O CLAUDE.md do packages/db documenta o drift e o processo — então o Claude Code já entra sabendo, mas confira o que ele gerar.
4. Jamais db:push em produção. E lembre: nosso .env.local local aponta pra prod. Um db:push distraído mexe em dado real.

Por que não "arrumamos" o drift de uma vez

Tentador, mas é mudança de alto risco num banco de produção vivo — exatamente o tipo de coisa irreversível que a gente decide devagar, com dado na mão. A postura certa hoje: não aumentar o drift (toda mudança nova feita certa) e remediar com cuidado.

⚠️ Armadilha #21: rodar db:migrate ou confiar no schema TS achando que está tudo sincronizado. Aqui não está. O banco é a fonte da verdade; o .ts é uma aproximação.

Próximo da série: #22 — Auth com Google OAuth.