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.
- La situación
La búsqueda de productos de tu tienda responde en milisegundos porque usa un índice.
- 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.
- 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
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
- 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.
- 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.
- 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.
- 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).
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)
Las otras piezas del ecosistema
- pg_agent_gate Agentes de IA sobre PostgreSQL
- pg_phasevec · preview 0.x Memoria vectorial con procedencia
- pg_living_assertions Garantías con fecha
- pg_recall_guard Recall de índices vectoriales
- pg_promise_guard Garantías del esquema
- pg_grammar_guard Salida estructurada que no inventa nombres
- ygg-agent v0.2.0 · PyPI El loop del agente sobre pg_agent_gate, sin MCP: el modelo escribe SQL y la base decide.