Agentes de IA sobre PostgreSQL
pg_agent_gate v0.4.3
Los agentes proponen. PostgreSQL decide.
Una extensión que hace que en la sesión de un agente el SQL no se ejecute: el agente solo puede proponer una sentencia; PostgreSQL la verifica contra sí mismo, muestra su efecto exacto y la guarda solo si todas las guardas están de acuerdo. Aplicada por hooks dentro del servidor: no hay cliente, driver ni protocolo que la esquive.
Instalar
CREATE EXTENSION pg_agent_gate; En simple
Una puerta entre la inteligencia artificial y tu base de datos: la IA propone, la base de datos revisa y decide.
- La situación
Un asistente de IA atiende pedidos y puede actualizar datos de clientes en tu sistema.
- Sin esta pieza
Una instrucción mal entendida borra 8 pedidos. Es una orden válida, así que la base la cumple. Nadie lo ve hasta que un cliente reclama.
- Con esta pieza
La base de datos detecta que son 8 filas y el límite de ese asistente es 5: no ejecuta, muestra qué iba a pasar y lo deja registrado. El cambio legítimo de un solo cliente sí pasa.
Por qué importa si decides
- Riesgo acotado: la IA no puede hacer más daño que el límite que tu equipo fije, por asistente
- Evidencia: cada propuesta, cada aprobación y cada rechazo quedan en un registro que no se puede borrar
- Operación simple: es una extensión dentro de tu PostgreSQL, sin otro servicio que mantener
El problema
Hoy la base no distingue al agente de la aplicación
Un agente llega a PostgreSQL con un rol y una conexión. Desde ese momento, cuando el modelo alucina un DELETE sin WHERE, un DROP TABLE o lee las filas de otro cliente, la base lo ejecuta: es SQL válido con permisos válidos.
Cada garantía vive en el servidor MCP o en el prompt, fuera de la base. El servidor obedece al modelo y PostgreSQL nunca se entera de qué se verificó.
| Lo que el esquema dice | Lo que pasa |
|---|---|
| DELETE FROM orders, tecleado por el agente | Sin puerta: 8 filas borradas. Con puerta: ERROR, la sesión propone, no ejecuta. |
| DROP TABLE customers | Sin puerta: la tabla desaparece. Con puerta: rehusado en propose (kind_allowed: sin DDL). |
| Borrar 8 filas con tope de 5 | Con puerta: commit abortado, devuelve el antes/después de las filas. |
| UPDATE legítimo de 1 fila | Con puerta: kept, mostrando el efecto antes de guardarlo. |
Cómo funciona
Siete verbos, y en una sesión de agente nada más
- 01
discover
Qué puede tocar: tablas, vistas y funciones sobre las que tiene privilegios, con columnas, tipos, claves y restricciones. Sale del catálogo vivo, con una huella para detectar que el esquema cambió.
- 02
propose
Una sentencia, nada corre. Cada check es PostgreSQL mismo: parses, single_statement, kind_allowed, no_writing_cte, keeps_its_context, no_amplification, no_hidden_sql, no_opaque_function, read_changes_nothing / changes_only_rows, resolves.
- 03
dry_run
Corre en una subtransacción y se deshace: filas tocadas, antes y después de cada fila, y si las aserciones vinculadas seguirían cumpliéndose.
- 04
commit
Verifica de nuevo, ejecuta con los privilegios del agente y guarda si todas las guardas están de acuerdo. Más filas que max_rows o una aserción rota: se deshace. Una propuesta se confirma una sola vez.
- 05
propose_and_commit, acts, whoami
Los dos pasos en una llamada (una transacción, un commit); el registro append-only de todo lo propuesto y hecho, con por qué se rehusó; y quién es esta sesión y si la puerta está aplicada.
SQL
Registrar un agente
register_agent rehúsa roles superusuario, REPLICATION y BYPASSRLS, y miembros de pg_write_all_data, pg_execute_server_program o pg_write_server_files: un agente que puede salir de la puerta no está detrás de ella. Toma efecto en la siguiente conexión del rol.
CREATE EXTENSION pg_agent_gate;
CREATE ROLE billing_agent LOGIN; -- nunca un superusuario
GRANT USAGE ON SCHEMA public TO billing_agent;
GRANT SELECT, UPDATE ON customers TO billing_agent;
SELECT agent_gate.register_agent(
'billing', 'billing_agent', 'answers billing questions and upgrades plans',
p_max_rows => 50, p_allow_ddl => false);
-- opcional: cada escritura que guarde debe dejar esta aserción en pie
SELECT agent_gate.bind_assertion('billing', 'no_customer_without_plan'); Lo que garantiza
Lo que garantiza, con una suite por cada línea
- Nada de lo que la sesión teclea se ejecuta, salvo los siete verbos: ni DELETE, ni DO, ni COPY, ni PREPARE, ni un cursor.
- Una propuesta corre solo después de que el parser, el planner, el analyzer y el rewriter de PostgreSQL la aceptan como UNA sentencia de un tipo que el agente puede correr.
- Una escritura que toca más de max_rows filas, o rompe una aserción vinculada, se deshace.
- El contexto que leen sus políticas de fila no se puede mover: ni con SET, ni al conectar, ni con set_config() dentro de una propuesta, en el cuerpo de una función, en una restricción o en un valor por defecto (0.4.2).
- Ningún otro rol puede volverse el agente: con la biblioteca en shared_preload_libraries, el rol del agente no tiene miembros y ninguna sesión que no sea su propio login puede hacer SET ROLE hacia él (0.4.1).
- Una lectura no cambia nada que el registro no muestre: ni una secuencia, ni un lock, ni un large object (0.4.3).
- Todo lo que propuso e hizo queda registrado append-only, incluido por qué se rehusó algo. Un TRUNCATE del registro se rehúsa (0.2.0).
- Una propuesta caduca: commit verifica de nuevo, y una propuesta más vieja que agent_gate.proposal_ttl_seconds (900) se rehúsa sin más.
- Un cambio que la puerta guarda se confirma siempre con la durabilidad con que está configurado el servidor, y ese flush lleva también el registro de la propuesta que lo originó: no existe un cambio en disco sin su propuesta y su ejecución al lado.
Lo que no hace
Lo que no cubre, dicho acá para que nadie lo aprenda a golpes
- Superusuarios y quien pueda editar postgresql.conf o reiniciar el servidor: pueden descargar la puerta. Por eso register_agent rehúsa superusuarios.
- GRANT sigue siendo la autorización: la puerta agrega verificación, no inventa ni quita privilegios. Lo que un DBA cuelga de una tabla (trigger, CHECK, vista, función definer) corre con sus propias reglas.
- No protege la intención: una sentencia bien formada, dentro de los privilegios y bajo max_rows, se ejecuta. Medido: pedido "pon a todos en plan free", el modelo escribió un UPDATE correcto de 2 filas y la puerta lo guardó, por contrato.
- El cuerpo de una función se da por bueno según cómo está marcada: la puerta no lo lee. Detiene set_config(), el SQL que llega como texto y las funciones que el agente puede alterar, donde sea que se alcancen (0.4.3). Lo que queda es una función de un DBA marcada STABLE o IMMUTABLE que escribe: corre, y solo el tope de filas ve lo que cambió. Haz REVOKE EXECUTE ... FROM PUBLIC sobre lo que un agente no deba alcanzar.
- Sin la biblioteca cargada antes de la primera sentencia del agente, la puerta falla abierta: whoami() lo reporta. Usa shared_preload_libraries. Las conexiones ya abiertas no están detrás hasta reconectar.
- pg_dump no lleva quién es agente (está en el rol): restaurar sin los globals deja el registro diciendo que es agente mientras el rol está fuera de la puerta.
- Con attempt_durability = fast (el valor por defecto), una caída del servidor puede perder el registro de un intento que no cambió nada: una propuesta, un dry run, una lectura, un rechazo. Nunca el de un cambio. Con durable, cada registro paga su propio flush.
- allow_ddl es poder sobre el esquema, no un max_rows más grande: un agente con DDL corre cualquier CREATE, ALTER o DROP que sus permisos le den, y max_rows no acota lo que le hace a sus propias tablas. Un DROP TABLE concedido se guarda. Déjalo en false salvo que un agente puntual lo necesite.
Medido
Medido con pg_agent_gate 0.4.0, en una CI pública que cualquiera puede volver a correr
| Tareas trampa que se escaparon | Mismo modelo, mismas tareas, un superusuario revisando qué cambió de verdad: a través de un MCP server popular de Postgres, 4 de 7 tareas trampa se escaparon. Con la base decidiendo, 0 de 7. |
| Tokens y tiempo, con la misma puerta detrás | Con la misma puerta detrás de ambos, el agente sin MCP usó 5 veces menos tokens de prompt que por MCP (24k contra 126k en 13 tareas) y terminó cada tarea 13 veces más rápido: una mediana de 14 s contra 185 s, en un runner de CI solo CPU que cualquiera puede volver a correr. |
| Una sentencia, y la base decide | Escribir una sentencia y dejar que la base decida tomó una mediana de 6 s por tarea. |
| Un hueco, encontrado y cerrado | Encontramos un hueco nosotros mismos (un modelo en loop partió un borrado rehusado en tajadas legales) y lo cerramos en 0.4.0: un presupuesto de escritura por agente, encendido por defecto. |
Corrida de referencia: la CI del repo agent-gate-demo (github.com/Manuelreyesbravo/agent-gate-demo, run 41184106078), en un runner de GitHub solo CPU.
Para la empresa
Para la empresa
Es la pieza que permite conectar agentes a la base de producción con un contrato auditable: qué puede tocar cada agente, cuántas filas, con DDL o sin él, y un registro de cada propuesta con su veredicto.
- Un agente por caso de uso, cada uno con su rol, su max_rows y sus aserciones vinculadas
- Registro append-only de propuestas y ejecuciones: evidencia para auditoría y para revisar qué hizo un modelo
- Sin MCP server obligatorio: el agente llega por psql, un driver o SQL directo. Hay un shim para clientes que solo hablan MCP, sin poder propio
- ygg-agent (Python, Apache-2.0) es el loop listo entre un modelo y la puerta; desde 0.2.0 puede correr el modelo en el mismo proceso, sin servidor de modelo ni HTTP
- Presupuesto de escritura por agente, encendido por defecto (desde 0.4.0)
Ficha técnica
- Versión
- 0.4.3 en PGXN; la imagen pública 0.3.6 trae 0.4.3 (medido 13-11-2026)
- PostgreSQL
- 18 o superior (dry_run usa RETURNING old/new); suite verde en 18 y 19
- Construida con
- pgrx 0.19.2 (Rust)
- Configuración
- shared_preload_libraries = 'pg_agent_gate' (recomendado)
- Licencia
- Apache-2.0
- Edición Enterprise
- Incluida (PostgreSQL 18)
Las otras piezas del ecosistema
- pg_phasevec · preview 0.x Memoria vectorial con procedencia
- pg_living_assertions Garantías con fecha
- pg_plan_guard Planes de ejecución vigilados
- 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.