Desenvolvedor cria com IA a CLI Terox em poucos dias para consultar 128 shards do PostgreSQL de uma só vez

Quando você tem uma centena de shards do PostgreSQL, a pergunta simples «Em qual deles está este registro?» vira uma saga: encontrar o host, lembrar a porta e o banco de dados, abrir o psql, executar a consulta e passar para o próximo. Um desenvolvedor backend que antes trabalhava como DBA se cansou dessa rotina. Com ajuda da IA, criou o Terox em um par de dias: uma CLI interativa para clusters distribuídos em shards.

Qual problema ele resolve

No psql e no pgAdmin, a unidade de trabalho é uma conexão. Em um sistema distribuído em shards, é todo um conjunto de conexões. Um loop em bash em torno do psql serve para uma tarefa pontual, mas não se sustenta como ferramenta de uso diário: faltam limites de concorrência, cancelamento de consultas, registro de erros por shard e proteção contra acesso acidental ao ambiente de produção.

O Terox introduz entidades de nível superior: serviço → armazenamento → um, vários ou todos os shards. Hosts e bancos de dados são definidos por modelos; por exemplo, pgbouncer-shop-rs{p1:03}.example.net se expande em 128 endereços. Uma consulta direcionada a all é executada em todos os shards, os resultados são reunidos em uma única tabela com uma coluna shard, e os erros aparecem separadamente.

Como funciona na prática

O comando \find items item_id = 424242 percorre os shards, informa que o registro foi encontrado no shard_37 e muda automaticamente o contexto para ele. Sem precisar copiar o host ou adivinhar onde está o registro.

A implementação interna é cuidadosa. O parâmetro fanout_concurrency impede que o cliente acesse todos os 128 shards ao mesmo tempo. O pool de conexões de cada shard é criado sob demanda, cada shard tem seu próprio prazo limite e Ctrl+C cancela as consultas em execução. As leituras ocorrem em uma transação READ ONLY real do PostgreSQL, sem depender da análise do texto SQL. A escrita precisa ser habilitada explicitamente com \write on e é desativada quando o contexto muda.

Também há recursos específicos de diagnóstico (\activity, \blockers, \longtx, \sizes, \diff, \doctor) e um linter que detecta DELETE sem WHERE ou NOT IN com valores que podem ser NULL.

Migrações para casos excepcionais

O autor ressalta que as migrações habituais acompanham o deploy. O Terox atende a exceções em tabelas grandes e com alta carga. Sem a opção --allowed, o comando \migrate funciona como dry-run. Há suporte a execuções canary, lotes e --resume, enquanto uma soma de verificação impede que o rollout continue com um arquivo modificado.

Não existe uma transação compartilhada pelos 128 servidores, então alguns shards podem já ter confirmado as alterações. O relatório mostra explicitamente a aplicação parcial, e as migrações devem ser idempotentes. Para CREATE INDEX CONCURRENTLY e VACUUM, que não podem ser envolvidos em uma transação com SET LOCAL, o Terox alerta sobre a execução sem proteção e exige uma confirmação adicional em produção.

O que isso diz sobre vibe coding

O processo foi descrever o problema, encontrar um modelo mínimo de comportamento, obter uma implementação da IA, verificá-la manualmente e com testes, e transformar cada caso extremo em um novo teste. Assim surgiram o fechamento dos pools ao sair, um histórico sem senhas e os testes de condições de corrida.

A principal conclusão do autor: a IA implementa uma ideia equivocada com a mesma rapidez e o mesmo cuidado, em doze arquivos de uma só vez. Por isso, defina primeiro os invariantes: nenhuma conexão permanece aberta após a saída, o PostgreSQL garante o acesso somente leitura, a mudança de contexto desativa a escrita e uma falha parcial não aparece como sucesso. Assim, a conversa com a IA se torna trabalho de engenharia.

Limitações

A análise estática do Terox é heurística. Os limites de segurança continuam sendo definidos pelas permissões da role, pelas transações READ ONLY, pelo TLS e pelos timeouts. A ferramenta não substitui monitoramento, backups nem a compreensão dos planos de consulta, e não corrige a arquitetura de sharding.

A conclusão prática: se você acessa dezenas de bancos de dados regularmente, transforme seu loop em uma ferramenta que lembre as regras por você. E, ao trabalhar com IA, comece pelos invariantes antes de partir para o código.