Uma página demora dez segundos e a primeira proposta é aumentar a VPS. Às vezes faltam recursos; em outras situações, o sistema transfere milhares de registros desnecessários, faz centenas de consultas ou espera um bloqueio. Sem localizar a causa, uma máquina maior pode apenas adiar o próximo incidente.
O diagnóstico começa pela jornada lenta, identifica onde o tempo é gasto e modifica uma hipótese por vez. Este manual orienta a análise de sistemas empresariais com PostgreSQL, preservando integridade e estabilidade durante a investigação.
1. Defina o problema com precisão
Registre a operação, horário, organização afetada, volume e duração observada. Separe demora no navegador, rede, API, banco e serviço externo. Compare percentis e distribuição, não apenas média: uma pequena parcela de requisições muito lentas pode bloquear usuários importantes.
Reproduza com dados representativos em um ambiente controlado. Uma consulta com vinte registros não revela necessariamente o comportamento de uma base com milhões. Evite copiar dados sensíveis sem tratamento. Quando a reprodução completa não for viável, obtenha métricas e planos com os cuidados de produção.
2. Encontre as consultas responsáveis
Associe uma requisição às consultas executadas. Conte quantas chamadas ocorrem e qual é o tempo acumulado. O problema pode estar no padrão N+1: uma busca principal seguida de outra para cada linha. Otimizar cada consulta isolada pode ser menos eficaz que reduzir a quantidade total.
Use observabilidade com identificadores de correlação e registro seletivo. Não despeje parâmetros sensíveis em logs. A coleta precisa ser útil para diagnóstico e compatível com a política de dados. O guia de observabilidade complementa a instrumentação.
3. Leia o plano antes de criar índices
A documentação de EXPLAIN do PostgreSQL explica como examinar o plano de execução. Analise estimativas, linhas processadas, filtros, junções e ordenação. O custo do plano não é uma medida direta em milissegundos.
EXPLAIN ANALYZE executa a instrução. Em comandos que alteram dados, isso pode produzir efeitos reais. Não o rode indiscriminadamente em produção. Use ambiente de teste ou um procedimento validado para a operação específica, considerando inclusive efeitos que não são simplesmente desfeitos por rollback.
4. Verifique seletividade e desenho do índice
Um índice é útil quando ajuda a localizar ou ordenar dados com menos trabalho relevante. Não é automaticamente melhor que uma varredura completa. Se a consulta precisa de grande parte da tabela, o planejador pode escolher outra estratégia de forma legítima.
Avalie filtros, ordem das colunas, ordenação e padrões de acesso. Um índice criado para uma consulta rara pode acrescentar custo a todas as gravações sem benefício proporcional. Considere tamanho, manutenção e sobreposição com índices existentes. Não crie um índice por coluna apenas por precaução.
| Sintoma | Hipótese a investigar | Evidência procurada |
|---|---|---|
| Muitas chamadas curtas | N+1 ou requisições redundantes | Contagem por jornada |
| Grande leitura para poucas linhas | Filtro ou índice inadequado | Plano e linhas descartadas |
| Espera irregular | Bloqueio ou saturação | Sessões e eventos de espera |
| Ordenação pesada | Volume, plano ou paginação | Linhas e uso de recursos |
| Aumento gradual | Crescimento ou manutenção | Histórico e distribuição |
5. Reduza o trabalho solicitado
Busque somente os campos necessários, limite resultados e adote paginação compatível com o uso. Paginação por deslocamentos muito altos pode tornar-se cara; paginação por cursor pode ser adequada quando existe ordenação estável e requisitos compatíveis.
Evite carregar um conjunto inteiro para somar no navegador. Ao agregar no banco, defina o período, a organização e o significado dos números. Um cache pode ajudar, desde que tenha chave correta, expiração e política de invalidação. Cache incorreto entrega uma resposta rápida e errada.
6. Investigue bloqueios e transações longas
Uma consulta simples pode ficar lenta porque aguarda outra operação. Procure transações mantidas abertas durante chamadas externas ou interação humana. Elas podem prolongar bloqueios e ampliar o impacto de uma tarefa aparentemente pequena.
Revise o escopo da transação e o acesso concorrente. O manual de isolamento descreve garantias que orientam o desenho. Não reduza a proteção transacional apenas para fazer um teste parecer rápido: primeiro entenda qual invariante depende dela.
7. Exemplo hipotético de melhoria
Um dashboard consulta 100 projetos e depois busca o responsável de cada um separadamente. O total é 101 chamadas. Uma consulta com junção adequada ou carregamento em lote pode reduzir esse número. O resultado deve ser comparado com o mesmo conjunto de dados e as mesmas permissões.
Não conclua que a melhoria será de cem vezes. Rede, banco, serialização e renderização contribuem de formas diferentes. Meça a jornada completa e o consumo no servidor. Confira também se usuários de outra organização continuam sem acesso aos dados.
8. Faça a alteração com critério de aceitação
Defina uma linha de base, a hipótese e o resultado esperado. Aplique uma mudança isolada, repita o cenário e compare latência, recursos, erros e consistência. Registre também o efeito sobre gravações: acelerar leituras à custa de um gargalo de atualização pode piorar a operação.
Planeje implantação e retorno. Alterações de índice, estatísticas ou consultas podem ter comportamento diferente sob carga real. Mantenha acompanhamento após o deploy e evite executar várias otimizações simultâneas sem conseguir atribuir o resultado.
Checklist de diagnóstico
- Jornada, horário e volume identificados.
- Tempo dividido entre navegador, API e banco.
- Quantidade de consultas por requisição conhecida.
- Plano analisado com dados representativos.
- Bloqueios e transações longas investigados.
- Paginação, filtros e campos revisados.
- Hipótese testada antes de aumentar infraestrutura.
- Regressões funcionais e de acesso verificadas.
Checklist para usar com sua equipe
Baixe o checklist editável em CSV e registre responsáveis, verificações e observações da implantação.
Perguntas frequentes
Toda consulta lenta precisa de um índice?
Não. Ela pode sofrer com excesso de dados, concorrência, desenho da consulta, chamadas repetidas ou falta de recursos.
Aumentar memória resolve?
Pode ajudar em determinadas cargas, mas deve ser uma decisão sustentada por métricas. Não corrige automaticamente lógica ineficiente.
Posso medir apenas no ambiente de desenvolvimento?
Ele ajuda a testar hipóteses, mas a validação precisa considerar distribuição dos dados e carga próximas da operação real.
Para investigar a lentidão com evidências, fale com a A2CR.
Autoria: Agência A2CR. Revisão editorial: 9 de novembro de 2026. Procedimento técnico e exemplo hipotético elaborados pela A2CR; referências vinculadas aos mecanismos citados.
