Fale conosco
Desenvolvimento

PostgreSQL 19 sai em 19/11 com pg_plan_advice: hints oficiais e o risco de 9x menos throughput

30 min de leitura
PostgreSQL 19 sai em 19/11 com pg_plan_advice: hints oficiais e o risco de 9x menos throughput

PostgreSQL 19 sai em 19/11 com pg_plan_advice: hints oficiais e o risco de 9x menos throughput

Por duas décadas, a resposta oficial do PostgreSQL para "como eu forço esse plano?" foi um não. O projeto sempre defendeu que o caminho é corrigir estatísticas, criar índice melhor ou reescrever a consulta — e que hints apodrecem no código. Quem precisava do contrário instalava pg_hint_plan por fora.

O PostgreSQL 19 muda essa posição. A versão de disponibilidade geral está marcada para 19 de novembro de 2026 (o RC 1 foi anunciado em 15 de outubro), e ela traz dois módulos contrib novos: pg_plan_advice , que deixa o próprio planner emitir um texto de "conselho" descrevendo o plano que ele escolheu, e pg_stash_advice , que guarda esse texto por query ID e o aplica automaticamente.

O detalhe que interessa a quem escreve SQL: esse é o primeiro mecanismo oficial de hint de plano do Postgres. E a primeira medição pública dele já veio com uma advertência embutida — em um teste de carga com dez clientes simultâneos, um único SET forçando varredura sequencial levou uma consulta indexada de 28 ms para 264 ms e o throughput de 351 para 37,9 transações por segundo , ou 9,3x menos. Nada mais mudou: mesma tabela, mesmos dados, mesmo hardware.

O que o módulo faz de diferente

Hints tradicionais são textos que você inventa. O pg_plan_advice inverte a ordem: você pede ao planner o plano dele e recebe de volta uma string que descreve aquela decisão em uma linguagem pequena e verificável.

A saída inclui, junto ao plano, algo próximo de INDEX_SCAN(orders idx_orders_created_at) JOIN_ORDER(orders customers) . Essa string pode então ser fixada na sessão:

O vocabulário é intencionalmente limitado: ordem de junção, escolha de índice, uso ou não de Gather em paralelismo, decisão de particionamento. Não é uma linguagem de scripting do plano inteiro — e isso é bom, porque reduz a chance de alguém travar algo que não entende. Confira os tokens válidos na documentação da sua compilação antes de colar qualquer coisa em produção.

Já o pg_stash_advice resolve o problema clássico do hint em aplicação de terceiro ou em ORM: você não consegue editar a consulta. Com compute_query_id ligado, o módulo associa o advice ao query ID e o aplica sempre que aquela consulta for replanejada. É o caso de uso mais honesto da ferramenta — não é performance de projeto novo, é contenção de dano em sistema legado.

O experimento que virou alerta

O benchmark publicado em 16/11 sobre o RC 2 fez o caminho inverso do marketing: em vez de mostrar ganho, mediu perda. O autor forçou varredura sequencial em uma consulta que o planner já resolvia com índice e não encontrou um único cenário em que o hint ajudasse no conjunto testado.

Isso não prova que hints são inúteis. Prova algo mais específico e mais útil: a qualidade do advice é responsabilidade de quem o escreve . O planner pode errar por estatística ruim, mas o hint erra por definição — ele não se adapta quando a tabela cresce 10x ou quando o ANALYZE atualiza a seletividade. Em times que mantêm sistemas sob medida com bancos relacionais no centro — o tipo de projeto que a Maquinaweb conduz com stacks Python, Node.js e .NET sobre Postgres —, a diferença entre "hint documentado com teste de regressão" e "hint copiado de um runbook" costuma aparecer só no pico de tráfego.

Vale também registrar o estágio do código: o histórico de commits do módulo mostra correções em torno do tratamento de NO_GATHER no fim de outubro, ou seja, semanas antes do GA. Módulo novo, correções recentes, comportamento que ainda vai assentar.

A 14 saindo de suporte é o argumento de verdade

O outro fato relevante da janela é menos charmoso e mais urgente: a série 14 encerra seu ciclo , com a 14.25 sendo a última atualização menor. Quem ainda roda 14 em produção fica sem patch de correção a partir de agora, e as versões suportadas passam a ser 15, 16, 17, 18 e, a partir do dia 19, a 19.

Isso muda a conta de quem está planejando migração. Sair da 14 direto para a 18 é o caminho conservador; pular para a 19 significa adotar, no mesmo movimento, uma versão recém-lançada e com um módulo de hints que ninguém do time usou ainda. Minha avaliação, com base no padrão histórico do projeto: para bases críticas, a 18 é a escolha natural agora, e a 19 entra primeiro em ambiente de leitura, relatórios e serviços internos.

Na prática, o roteiro é o de sempre, com dois itens a mais:

rode pg_upgrade com --link em cópia de produção antes de qualquer decisão e meça tempo de downtime real, não estimado;

liste todas as extensões instaladas — o pg_plan_advice e o pg_stash_advice precisam ser criados explicitamente com CREATE EXTENSION , eles não vêm ativos;

revise consultas que dependem de pg_hint_plan ; se houver, a migração é a hora de decidir se elas viram advice nativo ou se o índice é refeito;

congele plano de execução de pelo menos as dez consultas mais caras ( pg_stat_statements ordenado por tempo total) e compare antes e depois.

Riscos e armadilhas

O hint vira dívida silenciosa. Ele não aparece no código da aplicação, só em um SET ou em uma tabela do stash. Seis meses depois, a tabela quadruplicou e ninguém lembra que aquele plano está travado.

Query ID não é estável por decreto. O stash casa por identificador da consulta. Mudou a forma do SQL — não a constante, a estrutura — e o advice deixa de se aplicar sem erro nenhum, apenas com o plano antigo voltando.

Advice não substitui estatística. Se a estimativa está errada por correlação entre colunas, o certo é CREATE STATISTICS e revisão de amostragem, não forçar índice.

Precedência entre sessão e stash. Com as duas fontes ativas ao mesmo tempo, é preciso saber qual vence na sua versão antes de depurar um incidente às pressas.

Custo de adoção é cultural. Exigir que todo advice entre com o EXPLAIN de antes e depois e com um teste que dispare o alerta se o plano mudar é mais trabalho que escrever o SET .

Recomendação prática

Se você não tem incidente de plano hoje, não use hints na 19 — use a versão para EXPLAIN (PLAN_ADVICE) , que é um excelente recurso de diagnóstico e leitura, e fique com o planner no comando. Se você tem uma consulta de fornecedor que já quebrou duas vezes, o stash é a solução menos ruim que o Postgres já ofereceu: aplique, documente a data, o motivo e a condição de saída.

E se o seu time está justamente decidindo entre migrar de banco, refazer índices ou revisar a camada de acesso a dados, vale conversar com o time da Maquinaweb: eles trabalham com arquitetura, migração de stack e desenvolvimento sob medida, com times multidisciplinares e atuação nacional — o tipo de conversa que rende mais antes do pg_upgrade do que depois.

Fontes

#PostgreSQL #banco de dados #SQL #performance #query planner #migração #pg_plan_advice #banco relacional #tuning
Contato

Bora conversar?

Três campos. A resposta vem no WhatsApp.

Ou escreva para contato@maquinaweb.com.br.

Você vai para o WhatsApp com a mensagem pronta. Sem spam, sem lista.

Seus dados seguem a nossa política de privacidade.