Migrações D1

As migrações do banco de dados D1 (SQLite) ficam no diretório migrations/ na raiz do monorepo. Cada migração é um arquivo SQL numerado que transforma o schema do banco de forma incremental. O Wrangler CLI gerencia o ciclo de vida completo: criação, aplicação local para teste e aplicação remota em produção.

Estado atual (pós-v1.0.0)

Baseline: migrations/0001_init.sql — baseline consolidada no v1.0.0 (2026-08-12), equivalente ao schema final de produção. Ela substitui as 32 migrações pré-1.0 (0001_init.sql original + 0002–0029, incl. os 0018/0023 duplicados e o backfill-events.sql), geradas a partir do export do D1 remoto (wrangler d1 export neemias --remote --no-data) após a migração 0029. O histórico das migrações antigas está preservado no git e em docs/backend/d1-schema.md (§ Histórico de Migrações).

Migrações futuras começam em 0002. A primeira pós-baseline é migrations/0002_fix_student_fk_refs.sql (corrige FKs de student_credentials/waiting_list que apontavam para students(id) — a PK é student_id). Bancos novos aplicam a baseline + as subsequentes em ordem; bancos já migrados não re-aplicam a baseline porque o nome 0001_init.sql já está registrado em d1_migrations (a tabela de bookkeeping do wrangler).

Incrementais atuais (0002–0005):

Migração	Propósito
0002_fix_student_fk_refs.sql	Corrige FKs de student_credentials/waiting_list para students(student_id)
0003_backfill_usernames.sql	Backfill de username para usuários existentes
0004_idempotency_response_headers.sql	Headers de idempotência (respostas)
0005_normalize_legacy_class_ids.sql	Normaliza ids de classe legados (00000000-…-000N) para os UUIDs canônicos do baseline squashado + demo seed (#703) — FK-safe (students.class_id primeiro); no-op em bancos pós-squash

Comandos

Comando	Descrição
pnpm db:migrate:local	Aplica todas as migrações pendentes no banco D1 local (--local)
pnpm db:migrate:remote	Aplica todas as migrações pendentes no banco D1 remoto (produção)

Fluxo de Trabalho

O ciclo típico de uma migração é:

1. Escrever a migração como migrations/0002_<nome>.sql (números sequenciais; uma alteração de schema por arquivo)
2. Testar localmente com pnpm db:migrate:local, verificando se o schema resultante está correto
3. Aplicar em produção com pnpm db:migrate:remote

Sempre execute as migrações antes de fazer o deploy do worker. O worker espera que o schema do banco esteja atualizado; executar migrações após o deploy pode causar erros em produção durante a janela de inconsistência.

Squash de migrações (referência)

Se um dia for necessário consolidar de novo (ex.: numa próxima release major):

1. Exportar o schema final do banco migrado: wrangler d1 export neemias --remote --no-data --output /tmp/schema.sql
2. Substituir os arquivos 0001_init.sql + incrementais por um único 0001_init.sql com o DDL final (remover PRAGMA, d1_migrations, _cf_KV e DELETE FROM sqlite_sequence; usar CREATE ... IF NOT EXISTS)
3. Verificar equivalência: aplicar a nova baseline num SQLite limpo e comparar objeto a objeto com o banco remoto (tabelas, índices, triggers)
4. Não é preciso mexer no d1_migrations remoto se o nome 0001_init.sql já estiver registrado (é o caso desde o v1.0.0); caso contrário, inserir a linha manualmente antes de rodar pnpm db:migrate:remote
5. Rodar bash scripts/schema-sql-lint.sh (valida o SQL literal do worker contra a baseline) e a suíte de integração (pnpm --dir workers test:integration), que aplica __D1_MIGRATIONS__ nos bancos de teste

Boas Práticas

• Escreva migrações idempotentes usando CREATE TABLE IF NOT EXISTS e ALTER TABLE com verificações
• Prefira migrações pequenas e focadas — uma alteração de schema por arquivo
• Inclua comentários no SQL explicando o propósito da alteração e eventuais breaking changes
• Teste a migração localmente com dados realistas (use pnpm db:seed para popular o banco local antes de testar)
• Coordene migrações de schema com deploys do worker: migração primeiro, deploy depois

---

Fonte: migrations/ + workers/CONTEXT.md