Por que uma GUI de banco de dados nunca deveria escrever diretamente

Toda GUI de banco de dados tem um momento em que um clique se transforma em uma escrita contra produção. Decidimos que esse momento não deveria existir. No DynoTable, nada do que você faz — nem uma edição de item, nem uma exclusão em massa, nem a alteração de um agente de IA — toca no DynamoDB diretamente. Toda escrita cai em uma área de staging como um diff revisável por atributo, e só é enviada quando um humano faz o commit.

O modelo mental que buscamos é o git: uma área de staging para revisão e um commit que se comporta como git push --force-with-lease — ele só tem sucesso se o remoto ainda estiver do jeito que você o viu pela última vez. Este post é a engenharia por baixo: o bug entre abas que remodelou todo o design, o refactor cujo principal resultado foi código deletado, e por que a chegada dos agentes de IA transformou um agrado de UX na parede mestra de segurança.

Escritas são diffs

As edições se acumulam em um stage local apoiado em SQLite e são renderizadas como cards de diff — valor antigo, valor novo, por atributo — em um painel lateral. As linhas ganham um tom na grade, então o estado em staging fica visível a partir dos dados, não só do painel. O commit envia o conjunto em staging como transações do DynamoDB, fatiado nos limites do serviço (100 itens por transação, com orçamentos de bytes por operação e por requisição), sequencialmente, com um timeout de 30 segundos por lote.

A documentação de staging cobre o fluxo de trabalho do dia a dia. O que ela não cobre é por qual chave o stage é indexado — o que acabou sendo a decisão mais consequente do sistema.

Indexado pela tabela, não pela aba

A primeira versão limitava cada stage à aba que o criou. Esse design produziu um bug de verdade: a ferramenta de staging da IA derivava seu alvo da aba ativa, e sua guarda pulava abas que não são visões de tabela. Então, se você pedisse ao assistente para corrigir uma linha enquanto uma aba do SQL Workbench estava focada, a edição ia para o stage do Workbench — e o chip "revelar alteração em staging" abria a aba errada.

Pior, o lock de commit também era por aba. Duas abas vendo a mesma tabela seguravam dois locks independentes — ou seja, ambas podiam fazer o commit das mesmas linhas em staging para o DynamoDB real de forma concorrente. Uma corrida de commit duplo contra produção, embutida no modelo de dados.

A correção foi reindexar tudo pela identidade da tabela — {profile, region, tableName} — em vez de pela aba:

• Um stage por tabela, visível de todas as suas visões, sobrevivendo ao fechar e reabrir a aba. A IA pode fazer staging sem nenhuma aba de tabela aberta.
• Um lock de commit por tabela. A corrida de commit duplo não é "tratada" — ela é irrepresentável.
• A classe de bug da aba errada sumiu por construção: não há aba na chave.

E a reindexação deletou mais código do que adicionou. A varredura de inicialização que fazia garbage collection dos stages de abas fechadas? Um revisor a apontou como destruidora de funcionalidade sob o novo modelo — os stages não morrem mais com as abas — então ela foi removida de vez. O descarte ao fechar a aba e seu diálogo de confirmação: removidos. O único órfão verdadeiro que resta é um perfil de conexão deletado, que faz cascata explicitamente.

A migração em si foi a primeira do repositório a mutar linhas: uma reconstrução manual da tabela SQLite que deduplicava as linhas legadas por aba com uma janela ROW_NUMBER() OVER (PARTITION BY …) (a edição mais nova vence) e preenchia a nova chave com separadores char(0), byte a byte idênticos ao construtor de chave do runtime. As migrações que mutam linhas ganharam seu próprio harness de teste seed-then-migrate naquele dia.

--force-with-lease, para o DynamoDB

Uma UI de revisão não vale nada se aquilo que você revisou não for aquilo que é escrito. Entre o staging e o commit, outra pessoa pode ter alterado a linha. Então toda operação de commit carrega expressões de condição que fixam a escrita ao snapshot exato que você revisou — bloqueio otimista, atributo por atributo:

• Um create afirma que o item ainda não existe.
• Um update afirma que cada atributo que você está alterando ainda mantém o valor que você viu quando o colocou em staging.
• Até uma remoção afirma que o atributo ainda é igual ao seu valor antigo — se um colega de equipe mudou note de "old" para "new" enquanto sua remoção de note estava em staging, o commit não pode deletar silenciosamente a edição dele.

Quando uma condição falha, o DynamoDB cancela a transação inteira e nos diz qual item divergiu. Essa linha ganha um banner de conflito — fazer rebase contra o valor ao vivo ou abortar — em vez de uma sobrescrita silenciosa em qualquer direção.

E em qualquer falha de lote, o committer para. Os lotes já commitados continuam commitados, o lote que falhou sofre rollback atomicamente, nada mais é tentado. Rejeitamos deliberadamente a continuação best-effort: uma ferramenta de revisão que continua escrevendo depois de um conflito está aplicando um conjunto de alterações que ninguém revisou.

O refactor que deletou um subsistema

Os commits são de longa duração: o app registra cada um em um replay registry para que um reload do renderer — ou uma segunda janela — possa se reconectar e observá-lo terminar. Com o tempo, três caminhos de código diferentes anexavam cada um dois observadores por commit, e um mecanismo de arbitragem inteiro cresceu em volta de uma pergunta: qual observador tem permissão para liberar o lock de commit? Ele tinha seu próprio nome assustador (ownsLockOnBeforeRegistration), um bloco de comentário explicando uma corrida de ordenação de IPC e um rastreador de toasts de 230 linhas.

A correção foi um único dono: uma Commit Session que se anexa exatamente uma vez por commit, é dona exclusiva do lock, projeta o progresso na store e garante que sua chamada de start se resolve em todo caminho de saída — nunca trava, nunca rejeita. A maquinaria de arbitragem e o rastreador não foram realocados; foram deletados. O benchmark de memória que castiga o painel de staging perdeu cerca de um terço do seu heap. O melhor comentário de code review que recebemos naquele mês: "este PR é quase todo vermelho."

Dois comportamentos surgem desse modelo de propriedade que consideramos o mínimo para qualquer ferramenta que escreve em produção: um commit em andamento sobrevive a um reload do renderer (a sessão se reconecta e conclui), e ele até sobrevive à sua licença virando somente leitura no meio do commit — novos commits são bloqueados, mas uma escrita já em andamento é observada até o fim, nunca abandonada pela metade.

Por que o formato de transporte é deliberadamente feio

Os valores em staging são armazenados como envelopes tipados brutos do DynamoDB — {N: "42"}, {S: "42"} — não como um JSON unmarshalled amigável. Dois motivos. O diff precisa ser ciente de tipo: {N: "1"} e {S: "1"} são valores diferentes, e um hash de chave primária construído sobre valores unmarshalled os colidiria. E o ida-e-volta precisa ser sem perdas: os wrappers de número unmarshalled do SDK não sobrevivem à serialização em JSON para dentro do SQLite e de volta, e a igualdade profunda contra a entrada do usuário quebra. O caminho de commit usa o cliente bruto pelo mesmo motivo — o que você revisou é, byte a byte, o que é usado como condição e escrito.

Então os agentes chegaram

O staging é anterior aos nossos recursos de IA, mas é a razão de eles terem podido ser lançados. A ferramenta de escrita do assistente faz staging; sua própria descrição diz ao modelo — verbatim:

The user reviews + commits from the staging panel —
this tool never writes to DynamoDB directly.

Não existe ferramenta de commit. Não é restrita por permissão, não é auditada — ausente. O servidor MCP expõe a mesma fronteira estruturalmente: seu escopo de consentimento do meio se chama literalmente "read + stage". Um agente com prompt injection nesse escopo pode propor lixo, e o raio de explosão é um card de diff que um humano lê. E como os commits carregam locks otimistas por atributo, mesmo uma edição desatualizada de um agente não pode sobrescrever silenciosamente uma edição humana concorrente — ela aparece como um conflito, como tudo o mais.

Escrevemos sobre como tornar as queries do agente confiáveis; o staging é a outra metade — tornar suas escritas entediantes.

O que exigir de qualquer ferramenta que escreve no seu banco de dados

• Uma etapa de revisão entre a intenção e a escrita — diffs, não diálogos de confirmação.
• Concorrência otimista sobre o snapshot revisado, incluindo exclusões e remoções — nunca o último a escrever vence.
• Lotes atômicos com parada em caso de falha, não continuação best-effort depois de um conflito.
• Um caminho de escrita que sobrevive a um crash ou reload sem deixar um conjunto aplicado pela metade.
• Para IA: o staging como a única primitiva de escrita que um agente tem — uma capacidade ausente é melhor que uma protegida.

A documentação de staging mostra o fluxo de trabalho, e editar dados do DynamoDB cobre o básico que ele protege. Ou baixe o DynoTable, coloque algumas edições em staging com ⌘S, e veja uma alteração em massa virar algo que você consegue de fato ler antes que aconteça.