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 sequencialmente que transforma o schema do banco de forma incremental e reversível. O Wrangler CLI gerencia o ciclo de vida completo: criação, aplicação local para teste e aplicação remota em produção.

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

2. Testar localmente com pnpm db:migrate:local, verificando se o schema resultante está correto
3. Aplicar em staging com pnpm db:migrate:remote --env staging para validar em ambiente próximo de produção
4. Aplicar em produção com pnpm db:migrate:remote --env production

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.

Migrações Existentes

O projeto possui 13 migrações aplicadas:

#	Arquivo	Descrição
1	0001_init.sql	Schema inicial convertido de PostgreSQL para D1/SQLite — tabelas core: users, students, attendance_events, event_log, audit_log, idempotency_ledger, classes, nuclei, class_students
2	0002_auth_sessions.sql	Tabela auth_sessions para refresh tokens — suporte a múltiplos dispositivos por usuário e detecção de compromised sessions
3	0003_student_fields.sql	Campos estendidos de aluno — endereço, telefones, status, responsáveis, observações e campos customizáveis
4	0004_family_membership.sql	Coluna family_membership_status na tabela students — classificação familiar (membro, frequentador, visitante)
5	0005_compromise_detection.sql	Suporte a detecção de compromised sessions — flag de revogação e rastreamento de reuso de refresh token
6	0006_roles.sql	Tabela roles — roles customizáveis com permissões granulares, substituindo enum fixo de roles
7	0007_rate_limits.sql	Tabela rate_limits — armazenamento de contadores de rate limit com janela deslizante e expiração automática

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

⚠️ Seção em expansão.

---

Fonte: migrations/ + workers/CONTEXT.md