pg-logstats

pg-logstats is an agent-first PostgreSQL triage gateway. Instead of granting coding agents arbitrary database access, it provides them with pre-packaged, DBA-approved PostgreSQL runbooks.

By bundling database triage logic directly into the gateway CLI, pg-logstats translates raw log analysis and diagnostic SQL into a sequence of safe, bounded next actions. The agent only supplies the judgement at explicit branch points, while the gateway enforces security, protects database load, and generates an auditable history of the incident.

---

Why DBAs Adopt pg-logstats

For database administrators, allowing autonomous coding agents to investigate database incidents requires strict safety boundaries. pg-logstats acts as a secure gateway that protects your database:

• Zero Arbitrary SQL: Agents are restricted to a pre-approved menu of read-only diagnostic SQL queries. They cannot execute arbitrary query strings or modify data/schemas.
• Proactive Load Protection: High-overhead actions (such as EXPLAIN ANALYZE) are dynamically blocked if the database health verdict degrades under locks or query saturation.
• Structured Incident Handoffs: The agent resolves first-pass triage and presents you with structured recommendations (like index creation or local memory adjustments) rather than raw log dumps.
• Full Audit Trail: The gateway logs all agent attempts, parameters, and query results to immutable JSON reports, providing a complete audit record.

---

The Agent Runbook Loop

The gateway enables a structured, three-phase runbook loop for the agent:

1. Local Log Triage: The agent parses PostgreSQL logs offline to rank findings and query families.
2. Bounded Diagnostic Expansion: The agent chooses pre-approved, parameter-bound database actions (run_sql action class) to check active sessions or execution plans.
3. Escalation & Remediation: When the runbook is complete, the agent presents structured remedial recommendations (like B-Tree indexes or local work_mem overrides) directly to the DBA.

---

Quick Start

Install the CLI:

cargo install pg-logstats

Install the agent guidance (supporting Codex, Claude Code, and Gemini):

pg-logstats agent install --harness codex
pg-logstats agent install --harness codex --status
pg-logstats inspect /path/to/postgresql.log

If the investigation requires Amazon RDS or CloudWatch support, compile with the optional AWS SDK feature:

cargo install pg-logstats --features aws-sdk

---

Supported Log Inputs

The current text parser supports:

• Local stderr logs with a prefix shaped like %m [%p] %u@%d %a:
• Amazon RDS text logs with a prefix shaped like %t:%r:%u@%d:[%p]:

For CloudWatch logs, the agent or operator can inspect a bounded RDS log window:

pg-logstats inspect --rds-instance my-db --since 1h

---

Documentation Index

The documentation is organized specifically for DBAs setting up and auditing the gateway:

1. Primary Runbook References

• Slow Query Triage - Triaging slow queries by ranking query families and inspecting execution plans.
• Temporary Files Triage - Triaging disk-write pressure from temporary file spills.

2. Setup & Safety Controls

• Inspect and Readiness - Readiness probes, workspace configuration, and operating-mode checks.
• Investigation Guidance & Policies - The next_actions[] model, safety verdict matrix, and pre-approved SQL actions catalog.
• RDS and CloudWatch Log Input - Configuring remote AWS RDS log windows and IAM policy permissions.

---

Local Development

Checked-in fixtures for smoke tests live in tests/fixtures/cli/.

Run formatters and checks:

make fmt
make check

License

This project is licensed under the MIT License. See LICENSE.