Skip to content

The Runbook Model

pg-logstats is not a SQL shell or a command runner for AI agents. It is a PostgreSQL-specific triage gateway that turns logs and approved live checks into runbook reports.

As a Database Administrator (DBA), granting agents direct or arbitrary access to your PostgreSQL instance carries operational and security risks. pg-logstats solves this by making log evidence the default path and restricting live database access to named, pre-defined actions.

Runbook Structure & Division of Labor

The core design is a clean separation between runbook structure and agent judgement:

  • The Gateway Enforces the Runbook: pg-logstats defines the diagnostic evidence model, the log-parsing logic, the allowed database queries, and the safety policies.
  • The Agent Supplies the Judgement: The agent acts as a navigator. It reads the gateway's findings and decides which branch of the runbook to pursue next based on the incident context.

This design prevents agents from inventing raw database queries, running arbitrary commands, or degrading database performance during an active incident.

The Runbook Execution Loop

When an incident occurs, the agent follows a runbook in three phases:

graph TD
    A["PostgreSQL Logs / Alert"] --> B["Phase 1: Local Log Triage"]
    B -->|"Generates Ranked Findings & next_actions[]"| C["Phase 2: Bounded Diagnostic Expansion"]
    C -->|"Choose Action ID"| D{"run-sql Action?"}
    D -->|Yes| E["Gateway executes pre-approved SQL"]
    D -->|No: prompt_user| F["Agent escalates to DBA"]
    E -->|"Appends insights & new next_actions[]"| C
    F --> G["Phase 3: DBA Handoff & Remediation"]

Phase 1: Local Log Triage

The agent initiates triage offline by analyzing a database log source. The gateway parses these logs, normalizes the queries, groups related events, and generates a structured report containing ranked findings.

Phase 2: Optional Bounded Diagnostic Expansion

To help the agent investigate further, the gateway attaches a list of pre-approved, context-specific diagnostic SQL actions (next_actions[]) directly to the findings. * If the agent wants to inspect lock waits or check query plans, it must select a specific, pre-defined action_id. * The agent executes the action by invoking the gateway's run-sql interface. The gateway validates the action, binds any required parameters (like a query ID or application name), and executes its own built-in query. The agent has no way to supply raw SQL text.

Phase 3: DBA Handoff & Remediation

When the diagnostic path is exhausted or requires human intervention (such as modifying schema or adjusting global parameters), the agent stops. It hands off the investigation to the DBA, with recommendations like creating specific indexes or adjusting session memory.

Safety & Database Protection Guardrails

To protect your production database from runaway agent queries, the gateway enforces three key guardrails:

  1. Strict Parameter Binding: Pre-approved diagnostic actions only accept specific identifiers (e.g., queryid or application_name). Raw SQL execution is impossible.
  2. Active Load Shedding (The Safety Verdict): Running diagnostic queries—especially EXPLAIN ANALYZE, which actually executes the query—can add harmful overhead to a stressed database. The gateway evaluates database health (e.g., active session counts and wait events) to determine a health verdict (clear, busy, or saturated). Bounded-risk actions are automatically blocked if the database is under load.
  3. Audit Trail: The gateway persists triage steps and follow-up query results as JSON reports under the workspace directory.