Neon Postgres Egress Optimizer: encontre consultas que transferem dados demais

ANÁLISE EDITORIAL

Uma consulta ao Postgres pode funcionar perfeitamente e, ainda assim, devolver muito mais dados do que a aplicação usa. Na Neon, a transferência de saída passa pelo proxy da plataforma e entra na métrica de uso de rede. A Neon Postgres Egress Optimizer é uma Skill oficial para investigar esse desperdício no código: ela procura consultas frequentes, resultados largos e listas sem limite, propõe mudanças pequenas e pede medição depois. Ela não acessa seu banco sozinha. O pacote oferecido aqui contém somente instruções e documentos de origem, não um cliente de banco nem um otimizador automático.

O que esta Skill faz

O roteiro tem quatro partes: diagnosticar as consultas que devolvem muitas linhas ou são chamadas repetidamente, relacioná-las ao código da aplicação, corrigir padrões de busca excessiva e verificar se a resposta continua correta. Entre os casos concretos estão SELECT * quando a tela usa poucas colunas, listagens sem paginação, agregações feitas depois de baixar todas as linhas e junções que repetem dados de uma linha larga para cada registro filho. Uma camada de cache também é considerada para leituras muito repetidas de dados pouco mutáveis.

O texto sugere consultar pg_stat_statements para ver calls, rows e tempo de execução. Esses campos ajudam a encontrar candidatos, mas não são uma medição direta de bytes transferidos. A própria documentação da Neon inclui exportações, replicação lógica e outros fluxos na transferência de rede. Por isso, se a métrica do projeto subir sem consultas excessivas, o diagnóstico não pode parar no SQL. Em 19/10/2026, o repositório oficial neondatabase/agent-skills registrava 101 estrelas no GitHub. Esta é uma exceção à preferência editorial por projetos acima de mil estrelas: a fonte é a equipe da própria Neon, com documentação, pacote publicado e licença verificados. O número não mede adoção desta Skill.

Para quem serve e quando não usar

Ela é útil a desenvolvedores e responsáveis por aplicações que já usam Postgres na Neon e precisam entender por que o tráfego de saída cresceu. Um exemplo é uma rota que busca registros de pedidos com uma coluna JSON extensa, embora a lista mostre somente identificador, data e estado. A Skill ajuda a localizar o ponto de leitura, propor seleção de colunas e conferir se a resposta da API continua oferecendo os campos de que o cliente depende. Também cabe em uma revisão preventiva de consultas antes de ampliar o uso do produto.

Não a use como prova de economia garantida, benchmark, detector de cobrança incorreta ou autorização para mudar produção. Uma alta de uso pode vir de pg_dump, replicação ou exportação de logs; esses casos exigem outro caminho de investigação. Também não é a ferramenta certa para otimizar tempo de execução de toda consulta: tempo de banco e volume transferido são problemas relacionados, mas distintos. Se você não tem acesso a estatísticas de produção, a análise estática do código pode apontar riscos, porém não confirma qual consulta gerou o tráfego observado.

Compatibilidade e pré-requisitos

O arquivo SKILL.md segue o formato de Agent Skills. É necessário um agente capaz de ler esse formato e o código da aplicação, ou uma pessoa que use o documento como checklist. A Skill manda ler primeiro a Skill pai neon, obtida na pasta oficial. Ela não está dentro do ZIP local. Para diagnóstico com dados reais, são necessários acesso autorizado ao projeto Neon, métricas de transferência e, se aplicável, permissão de leitura de pg_stat_statements. Para testar mudanças, use uma branch e uma aplicação de teste com tráfego representativo.

A extensão pg_stat_statements pode precisar ser criada no banco; não presuma que o usuário do aplicativo possa fazê-lo. A documentação do PostgreSQL explica que textos de consultas de outros usuários podem exigir privilégios adicionais. O roteiro foi auditado no commit 51c7d594c0568d52a15eede61cc43f9f1227607a; a publicação @neon/skills consultada era a versão 2.3.0. Verifique a documentação da sua versão de Postgres, do cliente e do plano Neon antes de executar comandos ou interpretar métricas.

Instalação e configuração

Use o card de download local para obter o ZIP, confira o SHA-256 abaixo e leia ORIGEM.md e LICENSE. Extraia SKILL.md na pasta de Skills reconhecida pelo seu agente. O pacote não instala a dependência neon; instale-a ou abra-a a partir da origem oficial antes de usar a Skill de egress. A Neon também documenta a instalação pelo npx skills add neondatabase/agent-skills, que consulta a rede e pode instalar mais Skills do repositório. Revise o destino e o conteúdo antes de executar um instalador. O botão “Abrir repositório oficial” desta página leva ao diretório fixado no commit, enquanto o card entrega a cópia documental hospedada no Bastidores.

Na configuração do trabalho, delimite a branch de banco, o repositório e as rotas a examinar. Conceda somente leitura para a fase inicial. Conexões e chaves ficam no gerenciador de segredos do ambiente, nunca no prompt ou dentro do ZIP. Se a equipe não permitir pg_stat_statements, peça ao agente uma revisão estática de consultas e registre a limitação. Não execute CREATE EXTENSION ou redefinição de estatísticas em produção como etapa automática de instalação.

Primeiro uso e resultado esperado

Comece com uma pergunta pequena: “Analise a rota de listagem de pedidos nesta branch. Mostre onde ela lê colunas não usadas e onde falta limite, sem alterar o banco. Proponha um diff e um plano de teste”. Se houver métricas disponíveis, compare a tendência de transferência no painel do projeto com a janela em que essa rota foi chamada. Use calls e rows de pg_stat_statements para priorizar hipóteses; confirme no esquema se as colunas retornadas são largas. Antes de editar, escolha junto com o responsável o contrato de resposta que deve ser preservado.

O resultado esperado é uma mudança revisável no código, como seleção explícita de campos, paginação com ordem estável ou agregação no SQL, mais testes de regressão da API. Depois, rode carga representativa em ambiente controlado e compare a métrica de transferência da Neon antes e depois, com janelas equivalentes. Isso descreve como validar, não um teste executado pelo Bastidores. A Skill sugere redefinir estatísticas para uma janela limpa; em ambiente compartilhado, essa operação apaga a série que outras pessoas usam. Prefira registrar o valor inicial e combine qualquer reset com o administrador. A imagem a seguir é uma captura real da documentação oficial que mostra onde observar uso no painel da organização.

Permissões, dados e riscos

O documento é texto, mas aplicar suas sugestões pode revelar estruturas e consultas do banco, modificar código, alterar respostas da API, criar uma extensão, redefinir estatísticas ou mudar recursos do projeto. Dê ao agente escopo de leitura no início e aprove alterações somente após revisar o diff. Uma listagem paginada pode quebrar um consumidor que esperava o conjunto completo; uma coluna removida pode parecer dispensável na tela atual e ser usada por outra integração. Cache sem invalidação adequada pode devolver dados antigos. Separe testes de mudanças em produção e registre uma forma de reversão.

Os textos SQL em pg_stat_statements e os registros do aplicativo podem revelar nomes de tabelas, padrões de acesso e informações operacionais. Não cole consultas sensíveis em serviços externos sem autorização. A licença Apache-2.0 permite redistribuir esta documentação com os avisos de licença, mas não torna seguro executar qualquer comando com credenciais amplas. A métrica de rede da Neon também depende do tipo de tráfego e do plano; evitamos publicar preços e percentuais de economia porque variam e não foram medidos neste projeto.

Se algo der errado

Se a visualização pg_stat_statements não existir, confira com o administrador se a extensão está disponível e se pode ser habilitada naquele banco. Se os contadores vierem vazios após o compute acordar, não conclua que não houve transferência; use a métrica de rede do projeto e recolha uma janela representativa. Se faltar permissão para ver o texto de outras consultas, peça acesso apropriado em vez de ampliar privilégios da conta da aplicação. Sem estatísticas, investigue as chamadas SQL no código e no ORM, marcando as conclusões como hipóteses.

Se o tráfego não cair após reduzir colunas, confira exportações, replicação, consultas em réplicas, frequência de chamadas e o mesmo intervalo de observação. Se a API quebrar, restaure o contrato de resposta e revise paginação, ordem e agregações antes de repetir a medição. Se um cache mostrar valores antigos, revise a política de invalidação e o tempo de vida. A documentação oficial de transferência descreve outras fontes de tráfego e opções de monitoramento; a referência PostgreSQL detalha exatamente o que os contadores significam.

Versão, licença e download local

Esta cópia corresponde ao arquivo da Neon no commit 51c7d594c0568d52a15eede61cc43f9f1227607a, consultado em 19/10/2026. O repositório informa licença Apache-2.0, que permite a redistribuição com os avisos exigidos. O ZIP contém somente SKILL.md, LICENSE e ORIGEM.md; não traz a Skill pai, executáveis, scripts, biblioteca Postgres, dependências ou credenciais. A origem, o commit e os hashes dos arquivos estão em ORIGEM.md.

Download próprio: neon-postgres-egress-optimizer-2026-10-19-docs.zip. SHA-256: 05c0fdcc8799c23828143a47990b411861174d47f02ff5a79a9ac47eaefa820d. Confira o hash antes de extrair. A documentação pode mudar depois deste commit; instale a versão atual somente após ler seu conteúdo e confrontá-lo com a configuração real do seu ambiente.

Fontes primárias

Diretório oficial da Skill no commit auditado; instalação e catálogo da Neon; transferência de rede na Neon; otimização de custos da Neon; documentação do PostgreSQL sobre pg_stat_statements.