teqo/docs/plans/ops51-db-neon-para-homeserver.md
Francisco Solla 8d16b8a0cb
Some checks failed
Agent PR Ready + auto-merge / ready-automerge (pull_request) Has been skipped
CI (PR) / scope (pull_request) Failing after 4s
CI (PR) / lint (pull_request) Failing after 3s
CI (PR) / format (pull_request) Failing after 4s
CI (PR) / docs-guards (pull_request) Failing after 3s
CI (PR) / plans-only-closes (pull_request) Failing after 4s
CI (PR) / typecheck (pull_request) Has been skipped
CI (PR) / knip (pull_request) Has been skipped
CI (PR) / cycles (pull_request) Has been skipped
CI (PR) / unit (pull_request) Has been skipped
CI (PR) / int (pull_request) Has been skipped
CI (PR) / build (pull_request) Has been skipped
CI (PR) / e2e (pull_request) Has been skipped
CI (PR) / checks (pull_request) Failing after 2s
Agent pool supervisor / tick (pull_request) Failing after 5s
Main merge flips claimed issues to done + in-prod / issue-done (pull_request) Failing after 3s
Promote plan-issue Related on main merge / plan-issue-ready (pull_request) Failing after 3s
CI / static (push) Failing after 3s
CI / int (push) Failing after 4s
CI / build (push) Failing after 3s
CI / e2e (2) (push) Failing after 3s
CI / checks (push) Failing after 2s
CI / deploy (push) Has been skipped
CI / requeue (push) Failing after 4s
CI / e2e (1) (push) Failing after 4s
plan(OPS50-52): planos de intenção — CI Forgejo, DB Neon→homeserver, Blob→Garage
Related #1 #2 #3
2026-08-16 21:54:25 -03:00

4.6 KiB
Raw Blame History

Migrar o banco de produção do Neon para o Postgres do homeserver

Status: registrado Atualizado em: 2026-08-16 Issue: #2 Priority: P1 Model: cursor-grok-4.5-high Impeccable: A — N/A Rascunho UI: N/A — sem UI Appetite: ~1–2 dias eng; um outcome verificável Responsável: —

Intenção

O banco de produção (pt.jorgesolla.com.br) vive no Neon. O homeserver já roda Postgres 17 com o banco teqo_1313 (cadeia completa de migrations aplicada, mas sem conteúdo/PII de produção) e o container teqo-1313 saudável. Falta a parte cara: mover os dados reais — contatos, assinaturas, apoiadores, campanha — para casa, com LGPD fail-closed e rollback documentado (o Neon continua vivo até o cutover de hospedagem, que é outro lote).

Persona e fluxo

  • Persona / contexto: o dev (humano) conduzindo a migração; a equipe de campanha usando /campanha sem perceber a troca.
  • Job principal: o banco de prod viver no homeserver, com os mesmos dados e sem queda perceptível.
  • Fluxo desejado: dump seguro do Neon feito no homeserver (nunca em máquina de trabalho) → restore num banco de destino dedicado → deploy apontando para ele → smoke completo (login, WebAuthn, convites, revalidate) → Neon congelado como rollback.
  • Anti-goals de produto: despejar PII em disco de máquina de trabalho; misturar o conteúdo de produção com o banco do site 1313 (que tem vida própria); cortar o Neon antes de provar o rollback.

Objetivo e aceite

  • Dump completo do Neon restaurado no homeserver, com PII íntegra e sem cópias intermediárias fora do homeserver.
  • O deploy (container no homeserver) lê o banco local; /campanha funciona de ponta a ponta (login, WebAuthn, convites, revalidate).
  • Rollback documentado e testável: o Neon permanece operacional e o caminho de volta é re-apontar o DATABASE_URL.
  • Guardrails de produto: nenhum dado de produção toca bancos de dev/test (teqo, teqo_test, worktrees); o processo é fail-closed — qualquer passo que falhe deixa o Neon como fonte viva.

Dados (intenção)

  • Vou apresentar dados? Não
  • Decisões desbloqueadas: nenhuma de produto — migração de infra.
  • Forma: N/A

Direção no codebase (hipótese)

  • Áreas prováveis: env do deploy (DATABASE_URL no compose do homeserver, ~/stack/); migração em si é operação (pg_dump/restore), não código; pnpm migrate + pnpm db:seed:minimal já provados no teqo_1313.
  • Precedente a olhar: infra-solla plano-implementacao.md §7.3 (backup Neon → teqo_prod_pre_migracao no homeserver); local-database skill (guards que provam a higiene local); nota de "Mandatory production blocker" no AGENTS.md (LGPD/PII).
  • Risco de acoplamento: a media (Vercel Blob) continua sendo servida de fora até o OPS52 — os posts restaurados devem continuar renderizando capas; o container teqo-1313 (site 1313) é outro banco e não deve ser tocado.

Dependências

  • OPS50 (suave — o pipeline Forgejo→homeserver precisa existir para o deploy do novo apontamento)

Fora de escopo

  • Cutover de DNS/hospedagem de pt.jorgesolla.com.br (infra §7.5–7.6, manual).
  • Migração da media (Vercel Blob → Garage) — OPS52.
  • Excluir/cancelar a conta Neon — só depois do cutover estável.
  • Replicação contínua Neon→casa — dump + janela basta para este appetite.

Rabbit holes de produto

  • Sincronização contínua / zero-downtime. Para este appetite, janela de manutenção com dump é suficiente; replicação em tempo real triplica o risco sem pedido. Corte neste item: dump + smoke + rollback.
  • Unificar com o banco do 1313. Sites diferentes, conteúdos diferentes, rollbacks diferentes. Corte neste item: banco de destino dedicado para a produção.

Questões em aberto (produto)

  • Banco de destino: novo (teqo_prod) ou reusar teqo_1313? Opções: A) novo banco dedicado | B) reusar o existente. Recomendação: A — o teqo_1313 serve o site da campanha 1313 (vida própria); misturar complica rollback e privacidade. (assumido — validar)
  • Janela de manutenção? Opções: A) congelar escrita durante o dump | B) dump com leitura consistente em produção aberta. Recomendação: A para simplicidade (apetite pequeno; campanha interna tolera minutos de leitura na janela). (assumido — validar)

Referências

  • infra-solla: STATE.md (homeserver: postgres 17, DBs forgejo/teqo_1313), plano-implementacao.md §7.3
  • AGENTS.md — regras de banco local/PII e guardas (db:start, guard-dev-db)
  • Container teqo-1313 (imagem teqo-1313:21b3c00d) já no homeserver