Ir al contenido
← Ecosistema

Planes de ejecución vigilados

pg_plan_guard v1.1.11

¿El plan de esta consulta sigue siendo el que aprobaste?

PostgreSQL 19 trae pg_plan_advice (generar y forzar un plan) y pg_stash_advice (guardarlo por query_id). Ambos son actos manuales: decides que un plan es bueno y lo fijas. Ninguno vigila. pg_plan_guard responde la pregunta que faltaba.

Instalar

CREATE EXTENSION pg_plan_guard;

En simple

Vigila que las consultas importantes de tu sistema sigan siendo rápidas, y avisa el día que dejan de serlo.

  1. La situación

    La búsqueda de productos de tu tienda responde en milisegundos porque usa un índice.

  2. Sin esta pieza

    Un cambio interno hace que la misma búsqueda tarde cincuenta veces más. Nada falla, nada avisa: solo se vuelve lenta. Te enteras semanas después, por los clientes.

  3. Con esta pieza

    Tu equipo aprobó cómo debe resolverse esa búsqueda. Un chequeo periódico avisa el día que cambia, antes de que lo note un cliente.

Por qué importa si decides

  • Rendimiento vigilado, no supuesto: un aviso cuando cambia, no una queja cuando duele
  • Historial de qué cambió y cuándo, para entender después
  • Hoy requiere PostgreSQL 19: está en la imagen pública, no todavía en la edición Enterprise
Para el equipo técnico

El problema

Una regresión de plan no falla: se vuelve lenta en silencio

La consulta sigue devolviendo las mismas filas; solo dejó de usar el índice y empezó a escanear. Nada da error, nada se registra, nada alerta.

El caso para el que se construyó: una búsqueda por similitud sobre un índice DiskANN de ~40.000 embeddings. Si el planner deja de elegirlo, los resultados son idénticos y correctamente ordenados. Solo que ahora es un seq scan. Correcto, silencioso y lento; te enteras semanas después por un gráfico de latencia, si acaso.

Cómo funciona

Capturar, verificar, apuntar el monitor a una vista

  1. 01

    capture(name, query_sql, description)

    Aprueba el plan de hoy como línea base. Explícito, nunca automático: una base que se capturara sola bendeciría el plan que esté, incluida la regresión que buscas.

  2. 02

    verify([name])

    Re-planifica cada línea base y reporta la deriva. Se compara el advice (la forma: qué scan sobre qué relación, qué orden de join), no el texto de EXPLAIN, que cambia con estimaciones y costos aunque la forma sea la misma.

  3. 03

    status y drift_log

    Una vista para el monitor, peor primero; y un historial append-only de cada deriva, registrada una vez por transición, no una por chequeo. Una línea base rota (tabla borrada) se reporta como error y el resto se sigue verificando.

  4. 04

    sync_stash(stash)

    Empuja el advice aprobado a un stash de pg_stash_advice. La tabla es la fuente de verdad: el stash es una caché que siempre se puede reconstruir.

SQL

Uso

capture() registra el search_path de la sesión que captura; verify() y sync_stash() re-planifican bajo él con pg_temp al final, así una tabla temporal de la sesión que verifica no puede responder por una vigilada (test/pg_temp.sh).

psql · pg_plan_guardsql
CREATE EXTENSION pg_plan_guard;

-- Aprobar el plan de hoy para una consulta crítica.
SELECT plan_guard.capture(
    'semantic_search',
    'SELECT id FROM docs ORDER BY embedding <=> ''[...]'' LIMIT 10',
    'must use the diskann index');

-- Después, en un cron: ¿algo derivó?
SELECT cron.schedule('plan-guard', '37 */6 * * *',
    $$SELECT * FROM plan_guard.verify()$$);

-- Y el monitor mira una sola vista.
SELECT * FROM plan_guard.status WHERE state <> 'ok';

Lo que garantiza

Decisiones de diseño

  • Se compara advice, no EXPLAIN: cambia solo cuando cambia la decisión del planner.
  • La captura es explícita. La deriva se registra una vez por transición. Una base rota no aborta la corrida.
  • La línea base se re-planifica contra las tablas que su autor quiso (search_path grabado, pg_temp al final).
  • La tabla es la fuente de verdad, no la memoria compartida: si la persistencia del stash falla, la fijación desaparece en silencio, el mismo fallo que esta extensión existe para cazar.
  • Planificar no es gratis: el planner evalúa una función IMMUTABLE llamada con argumentos constantes, así que una consulta guardada puede correr código. Desde 1.1.5 cada EXPLAIN de texto guardado corre sellado: en una subtransacción de solo lectura que siempre se deshace.
  • Desde 1.1.7 una línea base se planifica como el rol que la escribió, y desde 1.1.9 el EXPLAIN corre dentro de una función SECURITY DEFINER temporal de su autor: una consulta guardada no puede hacer más que lo que su autor podría hacer directamente.

Lo que no hace

Limitaciones

  • Las consultas se guardan como texto y se re-planifican como están: las parametrizadas deben capturarse en forma ejecutable (literales).
  • La detección vale lo que vale la línea base: capturar un plan malo fija un plan malo. Revisa lo que devuelve capture().
  • verify() planifica con los settings de la sesión que lo corre, no del rol de la aplicación.
  • Un query_id ignora constantes: dos bases de una misma sentencia con literales distintos comparten slot en el stash, y gana la última sync_stash().
  • Requiere PostgreSQL 19 (pg_plan_advice). Verificado 2026-09-16: 10 a 18 fallan en la primera captura con "requires pg_plan_advice". Por eso hoy NO está en la edición Enterprise (PostgreSQL 18); sí en la imagen pública.

Para la empresa

Para la empresa

Es un sentinela de rendimiento para las consultas que pagan el negocio: una línea base aprobada por consulta y un monitor que avisa el día que el planner cambia de idea, no el día que un usuario se queja.

  • Una vista (plan_guard.status) para enchufar al monitoreo existente
  • Historial de derivas para post-mortems
  • Disponible cuando tu base esté en PostgreSQL 19

Esta pieza no viene en la imagen Enterprise 0.3.1, que trae pg_agent_gate, pg_living_assertions, pg_promise_guard y pg_grammar_guard. Se instala aparte desde PGXN.

Ficha técnica

Versión medida
1.1.11 (imagen pública 0.3.6, 13-11-2026)
PostgreSQL
19 o superior, con pg_plan_advice; sync_stash() requiere pg_stash_advice preloaded y stash_name
Licencia
Apache-2.0
Edición Enterprise
No todavía (la edición va sobre PostgreSQL 18)
Pruébala Hablar