Pular para conteúdo

0009 — Resetar Powersync

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-11 · Decidido em: 2026-05-04

Contexto

Mudanças estruturais ou estados corrompidos às vezes exigem zerar o estado replicado (slot de replicação no Postgres + base do PowerSync no MongoDB) e forçar um re-sync limpo nos clientes. É uma operação destrutiva e arriscada se feita à mão.

Decisão

Encapsular num ResetarPowersyncService com 9 steps idempotentes: VALIDAR, LOCK, PAUSE, SNAPSHOT_PRE, RESET_SLOT, DROP_MONGO, RESUME, SAMPLE_POST, FINALIZAR. Dois gatilhos para o mesmo serviço: endpoint REST (POST /api/transporte/admin/resetar-powersync, com Bearer + X-Confirm-Nuke) e a tela /admin (modal anti-acidente, palavra RESETAR). Restart do recurso PowerSync automático opcional via API do Coolify.

Consequências

  • Operação auditável e repetível (snapshot antes/depois), não um conjunto de comandos soltos.
  • Sem COOLIFY_API_TOKEN, o restart do PowerSync é manual.
  • O procedimento operacional vive no runbook operacao/resetar-powersync.md; o porquê/como funciona fica aqui.

Alternativas consideradas

  • Reset manual no banco/Mongo: propenso a erro, sem snapshot nem auditoria. Descartado.
  • Não suportar o reset: clientes ficariam presos a um SQLite local stale após mudanças estruturais. Descartado.