Blog

Prepared statement que fica lento na sexta execução: plano genérico, plan_cache_mode e parâmetros desiguais

Uma plataforma de pedidos multi-tenant colocou name nas consultas mais chamadas da API para reaproveitar o planejamento, uma otimização comum e quase sempre inofensiva. Quarenta minutos depois do deploy, o relatório diário do maior cliente, um marketplace com 30% dos pedidos da base, começou a estourar o statement_timeout de 30 segundos. O erro era intermitente: a mesma requisição passava ou falhava dependendo da conexão do pool que a atendia, um restart resolvia por uma hora e, no psql, a mesma consulta levava 3,4 s. O que mudou não foi a consulta nem as estatísticas: depois de cinco execuções na mesma conexão, o Postgres passou a usar um plano genérico, montado sem conhecer o tenant nem o intervalo de datas, e esse plano escolhe um nested loop pensado para 125 pedidos quando o marketplace tem 905 mil no mês. Este artigo mostra como o Postgres decide entre plano custom e plano genérico, por que essa decisão erra com parâmetros desiguais, como confirmar o problema e como corrigi-lo sem abrir mão de prepared statements onde eles ajudam.

2026-11-17 / Arquitetura / 12 min

01

O relatório que falhava só para um cliente e só em algumas conexões

O incidente parecia falta de recurso: timeouts esparsos, CPU do banco alta em alguns momentos, nenhuma consulta nova no pg_stat_statements. Mas três detalhes não fechavam com essa hipótese. Só o tenant 7 era afetado, os primeiros 40 minutos depois do deploy foram normais e o restart da aplicação, que não muda nada no banco, resolvia temporariamente.

D0 10:00  deploy: as consultas do relatório passam a usar statement nomeado (name no node-postgres)
          objetivo: economizar parse e planejamento nas rotas mais chamadas
D0 10:00  pool com 20 conexões; tempos iguais aos de antes por 40 minutos
D0 10:41  primeiro timeout de 30 s no relatório do tenant 7 (marketplace, 30% dos pedidos)
D0 11:30  timeouts intermitentes: a mesma requisição passa ou falha dependendo da conexão
D0 14:00  restart do serviço "resolve"; às 14:50 os timeouts voltam
D1 09:00  EXPLAIN da consulta no psql: 3,4 s com o tenant 7, sem nada estranho
D1 10:20  pg_prepared_statements na conexão da aplicação: generic_plans 412, custom_plans 5
D1 11:00  SET LOCAL plan_cache_mode = force_custom_plan no relatório: p95 de volta a 3,6 s

Os três detalhes apontam para estado guardado na conexão. Prepared statements vivem na sessão do Postgres: cada conexão do pool prepara o seu, conta as próprias execuções e decide sozinha quando trocar de plano. O restart fecha as conexões, zera essa contagem e devolve o comportamento antigo até que cada conexão acumule execuções de novo. No psql, uma sessão nova executando a consulta uma vez sempre recebe um plano custom, por isso o problema não aparecia ali.

02

Como o Postgres escolhe entre plano custom e plano genérico

Quando um statement preparado tem parâmetros, o Postgres pode planejar de dois jeitos. O plano custom é montado a cada execução com os valores reais de $1, $2 e $3, como se fossem literais: o planejador consulta as estatísticas do tenant 7 e do intervalo pedido. O plano genérico é montado uma vez, sem valores, e reaproveitado em todas as execuções seguintes. Ele economiza o planejamento, mas precisa estimar a seletividade sem saber o que vai receber.

  1. As cinco primeiras execuções de cada statement na sessão sempre usam plano custom, e o Postgres guarda o custo estimado de cada uma, somado a um pequeno custo estimado de planejamento.
  2. Na sexta execução, ele monta o plano genérico e calcula o custo estimado dele.
  3. Se o custo do genérico for menor que a média de custo dos planos custom, o genérico passa a ser usado. Se não for, continua custom e a comparação se repete a cada execução, com a média atualizada.
  4. Uma vez que o genérico vence, nenhum plano custom novo é montado, a média para de mudar e a decisão fica estável até a sessão acabar ou o plano ser invalidado.

A comparação é entre custos estimados, não entre tempos medidos. É aqui que o problema nasce: o custo do plano genérico é estimado com a seletividade média, e a média esconde o tenant que não se parece com os outros. Com o tenant 7 entre as cinco primeiras execuções, a média dos planos custom ficou em torno de 253 mil unidades de custo, puxada pelo plano dele, e o genérico, estimado em 1.270, pareceu 200 vezes mais barato.

Execução na conexãoTenantPlano usadoCusto estimado
112Custom1.180
288Custom940
37Custom1.264.000
4301Custom1.020
545Custom870
6 em dianteQualquer umGenérico (1.270 contra média de 253.602)1.270

Isso também explica a intermitência. Numa conexão que só atendeu tenants pequenos nas primeiras execuções, os planos custom custavam perto de 1.000 e o genérico, a 1.270, perdia: a conexão continuava custom. Bastava o tenant 7 passar por ela uma vez para a média subir, e na execução seguinte o genérico vencia. Cada conexão do pool virava genérica num momento diferente, conforme a ordem das requisições que recebeu.

03

Por que o plano genérico erra com parâmetros desiguais

Sem o valor de $1, a estimativa para tenant_id = $1 é o número de linhas dividido pelo n_distinct da coluna: 30 milhões de pedidos em 1.200 tenants dão 25 mil linhas, como se todos os clientes fossem do mesmo tamanho. Para o intervalo criado_em >= $2 AND criado_em < $3, sem os limites, o planejador usa uma seletividade fixa de 0,5% para o par de desigualdades. O resultado é 125 pedidos estimados, e para 125 pedidos um nested loop com busca por índice em itens_pedido é de fato o melhor plano.

Tenant e intervaloLinhas estimadas no genéricoLinhas reaisMelhor plano
Tenant 45, outubro125310Nested loop por índice, 9 ms
Tenant 12, outubro1252.140Nested loop por índice, 21 ms
Tenant 7, outubro125905.117Hash join, 3,4 s
Tenant 7, ano inteiro12510,8 milhõesHash join paralelo, 31 s

Para o tenant 7, o mesmo plano faz 905 mil buscas por índice em itens_pedido, 1,2 milhão de páginas lidas do disco e uma ordenação de 2,7 milhões de linhas que estoura o work_mem porque foi dimensionada para 375. São 52 segundos contra 3,4 s do plano custom. O erro não é de estatística desatualizada: um ANALYZE não muda nada, porque o plano genérico não usa o valor do parâmetro para consultar as estatísticas que já estão certas.

  • Coluna com distribuição muito desigual (tenant, status, tipo de evento) é a causa mais comum: a média por valor não representa nenhum valor real.
  • Intervalos de datas são a segunda: um dia e um ano recebem a mesma estimativa de 0,5% no plano genérico.
  • LIKE com parâmetro, IN com lista de tamanho variável e parâmetros opcionais do tipo ($1 IS NULL OR coluna = $1) têm o mesmo problema.
  • Funções PL/pgSQL também guardam planos das consultas internas e seguem a mesma regra das cinco execuções, por sessão.

04

Reproduzir e confirmar no psql

Rodar a consulta uma vez com literais nunca reproduz o problema. Para ver o que a aplicação vê, é preciso preparar o statement, executá-lo cinco vezes na mesma sessão e só então pedir o plano. O sinal mais claro está nas condições do plano: o plano genérico mostra $1, $2 e $3 no Index Cond, enquanto o plano custom mostra os valores.

-- A consulta do relatório, preparada exatamente como a API faz.
PREPARE relatorio_diario(bigint, timestamptz, timestamptz) AS
SELECT date_trunc('day', p.criado_em)        AS dia,
       count(DISTINCT p.id)                  AS pedidos,
       sum(i.quantidade * i.preco_centavos)  AS receita_centavos
  FROM pedidos p
  JOIN itens_pedido i ON i.pedido_id = p.id
 WHERE p.tenant_id = $1
   AND p.criado_em >= $2
   AND p.criado_em <  $3
 GROUP BY 1
 ORDER BY 1;

-- Cinco execuções: cada uma recebe um plano custom, montado com os valores reais.
EXECUTE relatorio_diario(12,  '2026-10-01', '2026-11-01');
EXECUTE relatorio_diario(88,  '2026-10-01', '2026-11-01');
EXECUTE relatorio_diario(7,   '2026-10-01', '2026-11-01');  -- o tenant 7 tem 30% dos pedidos e entra na média de custo
EXECUTE relatorio_diario(301, '2026-10-01', '2026-11-01');
EXECUTE relatorio_diario(45,  '2026-10-01', '2026-11-01');

-- Sexta execução: o plano genérico é montado, comparado com a média e passa a valer.
-- Repare no $1: o plano não sabe qual tenant nem qual intervalo está consultando.
EXPLAIN (ANALYZE, BUFFERS)
EXECUTE relatorio_diario(7, '2026-10-01', '2026-11-01');

GroupAggregate  (cost=1262.40..1270.15 rows=200) (actual time=51874.120..52031.556 rows=31 loops=1)
  ->  Sort  (cost=1262.40..1263.34 rows=375) (actual time=51870.004..51998.231 rows=2741893 loops=1)
        Sort Key: (date_trunc('day'::text, p.criado_em))
        Sort Method: external merge  Disk: 96432kB
        ->  Nested Loop  (cost=1.13..1246.37 rows=375) (actual time=0.061..49702.818 rows=2741893 loops=1)
              Buffers: shared hit=2944120 read=1206345
              ->  Index Scan using pedidos_tenant_criado_idx on pedidos p
                    (cost=0.56..142.10 rows=125) (actual time=0.031..2210.405 rows=905117 loops=1)
                    Index Cond: ((tenant_id = $1) AND (criado_em >= $2) AND (criado_em < $3))
              ->  Index Scan using itens_pedido_pedido_idx on itens_pedido i
                    (cost=0.57..8.80 rows=3) (actual time=0.018..0.051 rows=3 loops=905117)
                    Index Cond: (pedido_id = p.id)
Execution Time: 52088.307 ms

-- A mesma execução com plano custom: o Postgres enxerga tenant_id = 7.
SET plan_cache_mode = force_custom_plan;
EXPLAIN (ANALYZE, BUFFERS)
EXECUTE relatorio_diario(7, '2026-10-01', '2026-11-01');

Sort  (actual time=3412.880..3412.884 rows=31 loops=1)
  ->  HashAggregate  (actual time=3412.102..3412.611 rows=31 loops=1)
        ->  Hash Join  (rows=2703900) (actual time=688.214..2902.731 rows=2741893 loops=1)
              Hash Cond: (i.pedido_id = p.id)
              ...
              ->  Hash  (rows=901300) (actual time=681.540..681.541 rows=905117 loops=1)
                    ->  Bitmap Heap Scan on pedidos p  (rows=901300) ...
                          Recheck Cond: ((tenant_id = 7) AND (criado_em >= '2026-10-01 ...
Execution Time: 3415.204 ms
RESET plan_cache_mode;

-- Quantas vezes cada statement desta sessão usou cada tipo de plano (PostgreSQL 14+).
SELECT name, generic_plans, custom_plans
  FROM pg_prepared_statements;
-- relatorio_diario | 1 | 6

-- PostgreSQL 16+: mostra o plano genérico sem precisar preparar nem executar.
EXPLAIN (GENERIC_PLAN)
SELECT count(*) FROM pedidos WHERE tenant_id = $1 AND criado_em >= $2 AND criado_em < $3;

Em produção, o auto_explain com log_min_duration ajustado para alguns segundos registra os planos lentos com os $1 visíveis, o que já basta para apontar o plano genérico. A view pg_prepared_statements, a partir do PostgreSQL 14, mostra as colunas generic_plans e custom_plans, mas só enxerga os statements da própria sessão: precisa ser consultada pela mesma conexão da aplicação, não por um psql aberto ao lado. No PostgreSQL 16, EXPLAIN (GENERIC_PLAN) mostra o plano genérico de uma consulta com $1 sem precisar prepará-la.

05

Onde a aplicação prepara statements sem você perceber

Neste caso o prepare foi explícito, mas muitas vezes ele vem do driver ou do ORM. O comportamento depende da biblioteca, e vale conferir antes de concluir que a aplicação não usa prepared statements.

BibliotecaComportamento padrãoRisco de plano genérico
node-postgres (pg) sem nameStatement sem nome, refeito a cada consultaNenhum: todo plano é custom
node-postgres (pg) com namePrepara uma vez por conexão e reaproveitaSim, a partir da sexta execução na conexão
postgres.jsprepare: true por padrão em consultas estáticasSim; prepare: false desliga
Prisma (engine padrão)Cache de prepared statements por conexão (statement_cache_size)Sim; statement_cache_size=0 desliga
PgBouncer 1.21+ em modo transaçãomax_prepared_statements compartilha statements entre clientesSim, e a contagem soma requisições de clientes diferentes
PgJDBCprepareThreshold=5: prepara no servidor depois de 5 usosSim, mais cinco execuções custom depois disso

O caso do PgBouncer merece atenção: com max_prepared_statements, o statement preparado fica na conexão do servidor e é compartilhado por todos os clientes que passam por ela. A sexta execução chega bem mais rápido, e uma única requisição do tenant grande no começo do dia decide o plano de muitas outras.

06

Corrigir com plan_cache_mode no lugar certo

O parâmetro plan_cache_mode, disponível desde o PostgreSQL 12, controla essa decisão: auto é o padrão descrito acima, force_custom_plan monta plano custom em toda execução e force_generic_plan usa o genérico desde a primeira. Ele é avaliado a cada execução, não no prepare, então um SET LOCAL dentro da transação vale até para um statement que já estava preso no plano genérico.

// relatorio-repositorio.js
import pg from 'pg';

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20,
  statement_timeout: 30_000,
});

const SQL_RELATORIO = `
  SELECT date_trunc('day', p.criado_em)        AS dia,
         count(DISTINCT p.id)                  AS pedidos,
         sum(i.quantidade * i.preco_centavos)  AS receita_centavos
    FROM pedidos p
    JOIN itens_pedido i ON i.pedido_id = p.id
   WHERE p.tenant_id = $1
     AND p.criado_em >= $2
     AND p.criado_em <  $3
   GROUP BY 1
   ORDER BY 1`;

// Antes: statement nomeado, preparado uma vez por conexão e reaproveitado.
// Depois de cinco execuções na mesma conexão, o plano genérico pode assumir.
export async function relatorioAntes(tenantId, inicio, fim) {
  const { rows } = await pool.query({
    name: 'relatorio-diario',
    text: SQL_RELATORIO,
    values: [tenantId, inicio, fim],
  });
  return rows;
}

// Correção: mantém o prepare, mas força plano custom só nesta transação.
export async function relatorioDiario(tenantId, inicio, fim) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN READ ONLY');
    // SET LOCAL morre no COMMIT: não vaza para a próxima requisição que pegar esta conexão.
    await client.query("SET LOCAL plan_cache_mode = 'force_custom_plan'");
    const { rows } = await client.query({
      name: 'relatorio-diario',
      text: SQL_RELATORIO,
      values: [tenantId, inicio, fim],
    });
    await client.query('COMMIT');
    return rows;
  } catch (err) {
    await client.query('ROLLBACK').catch(() => {});
    throw err;
  } finally {
    client.release();
  }
}

// Diagnóstico: precisa rodar na mesma conexão, porque prepared statements são por sessão.
export async function planosPreparados(client) {
  const { rows } = await client.query(
    'SELECT name, generic_plans, custom_plans FROM pg_prepared_statements ORDER BY name',
  );
  return rows;
}
OpçãoAlcanceCustoQuando usar
Tirar o name da consultaUma consultaParse e planejamento a cada execuçãoConsulta com parâmetros desiguais e sem ganho real do prepare
SET LOCAL plan_cache_mode = force_custom_planUma transaçãoPlanejamento a cada execução, só aliManter o prepare no serviço e proteger a consulta sensível
ALTER ROLE relatorios SET plan_cache_mode = force_custom_planTodas as sessões do papelPlanejamento em todas as consultas do papelServiço de relatórios com usuário próprio no banco
ALTER FUNCTION ... SET plan_cache_mode = force_custom_planUma funçãoPlanejamento a cada chamadaConsulta sensível dentro de PL/pgSQL
Prepare só para tenants pequenosPor rotaLógica na aplicaçãoConsulta OLTP muito quente em que o planejamento pesa
  • Use SET LOCAL, nunca SET de sessão, quando a conexão volta para um pool: o SET de sessão vaza para a próxima requisição e, atrás de um PgBouncer em modo transação, para outro cliente.
  • Não force plano genérico para economizar planejamento sem medir. Com pg_stat_statements.track_planning ligado, compare total_plan_time com total_exec_time: num relatório de segundos, 0,4 ms de planejamento é irrelevante.
  • Separar statements por nome não ajuda sozinho: o plano genérico de qualquer nome é estimado com a mesma média. O que resolve é a rota do tenant grande não usar plano genérico.
  • Para detectar a volta do problema, acompanhe no pg_stat_statements a distância entre mean_exec_time e max_exec_time da consulta e mantenha o auto_explain registrando planos acima de alguns segundos.

No incidente, a correção foi o SET LOCAL na transação do relatório. As consultas curtas da API, em que o prepare economiza planejamento de verdade e os parâmetros são uniformes, continuaram com name e plano genérico. O relatório do tenant 7 voltou a 3,6 s de p95, e o dos tenants pequenos ganhou menos de 1 ms de planejamento por chamada.

FAQ

Perguntas frequentes

Por que exatamente na sexta execução?

Porque o Postgres usa as cinco primeiras execuções de cada statement preparado para formar uma média de custo dos planos custom. O número é fixo no código do planejador e não é configurável. Na sexta, ele monta o plano genérico, compara o custo estimado com essa média e decide. Se o genérico perder, a comparação continua nas execuções seguintes, então a troca pode acontecer muito depois da sexta, assim que um parâmetro caro elevar a média.

Devo colocar force_custom_plan no banco inteiro?

Normalmente não. Consultas curtas e uniformes, como busca por chave primária, ganham com o plano genérico porque deixam de pagar planejamento a cada chamada, e em tabelas com muitas partições ou joins grandes o planejamento pode custar mais que a execução. O mais seguro é aplicar force_custom_plan onde a distribuição dos parâmetros é desigual: numa transação, numa função ou no papel de um serviço específico.

Um ANALYZE ou mais estatísticas resolvem o plano genérico ruim?

Não diretamente. O plano genérico ignora o valor do parâmetro, então histogramas mais detalhados, SET STATISTICS maior e estatísticas estendidas não mudam a estimativa de tenant_id = $1, que continua sendo a média por valor distinto. O ANALYZE invalida os planos em cache e pode dar a sensação de que resolveu, mas depois de cinco execuções a mesma decisão volta a acontecer.

O plano que serve para a média não serve para o maior cliente

Prepared statements economizam planejamento, mas o plano genérico que eles acabam usando é estimado para um parâmetro médio que não existe. Em bases multi-tenant, com clientes de tamanhos muito diferentes, ou em consultas por intervalo de datas, essa média erra por ordens de grandeza, e o erro aparece de forma intermitente, por conexão, depois de algumas execuções. Saber que a decisão acontece na sexta execução, conferir pg_prepared_statements na conexão certa e aplicar plan_cache_mode só onde os parâmetros são desiguais resolve sem abrir mão do ganho do prepare no resto da aplicação. Se o seu sistema tem consultas que ficam lentas só para alguns clientes ou só depois de um tempo no ar, eu posso revisar os planos, o uso de prepared statements e a configuração do pool.