pg-logstats is an agent-first PostgreSQL triage gateway. Instead of granting coding agents arbitrary database access, it gives them packaged, DBA-approved runbooks that combine PostgreSQL logs with read-only system views.
The CLI parses log evidence, checks live readiness when a DSN is configured, gates diagnostic SQL through named actions, and writes an audit trail under a workspace directory. The goal is to let an agent investigate PostgreSQL incidents without becoming a SQL shell.
- Find slow query families from PostgreSQL statement and duration logs.
- Group PostgreSQL errors by SQLSTATE, normalized message, database, user, and application.
- Attribute temporary file spills to nearby statements when
log_temp_filesevidence is available. - Inspect readiness from logs and PostgreSQL system views before an agent starts triage.
- Run bounded follow-up checks against views such as
pg_stat_activity,pg_stat_database, andpg_stat_statementswhen live access is configured. - Read Amazon RDS logs from CloudWatch with the optional AWS SDK feature.
For database administrators, allowing coding agents to investigate database incidents requires strict boundaries. pg-logstats protects your database by constraining what the agent can do:
- 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. - Operator-Facing Handoffs: The agent resolves first-pass triage and presents recommendations (like index creation or local memory adjustments) rather than raw log dumps.
- Audit Trail: The gateway logs agent attempts, parameters, and query results to JSON reports.
The gateway enables a structured, three-phase runbook loop for the agent:
- Local Log Triage: The agent parses PostgreSQL logs offline to rank findings and query families.
- Bounded Diagnostic Expansion: The agent chooses pre-approved, parameter-bound database actions (
run_sqlaction class) to check active sessions or execution plans. - Escalation & Remediation: When the runbook is complete, the agent presents recommendations (like B-Tree indexes or local
work_memoverrides) directly to the DBA.
Install the CLI:
cargo install pg-logstatsInstall 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
pg-logstats query-families /path/to/postgresql.logIf the investigation requires Amazon RDS or CloudWatch support, compile with the optional AWS SDK feature:
cargo install pg-logstats --features aws-sdkThe 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 and analyze a bounded RDS log window:
pg-logstats inspect --rds-instance my-db --since 1h
pg-logstats query-families --rds-instance my-db --since 1hThe documentation is organized specifically for DBAs setting up and auditing the gateway:
- Slow Query Triage - Triaging slow queries by ranking query families and inspecting execution plans.
- Error Triage - Grouping repeated PostgreSQL errors by SQLSTATE and normalized message.
- Temporary Files Triage - Triaging disk-write pressure from temporary file spills.
- 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.
Checked-in fixtures for smoke tests live in tests/fixtures/cli/.
Run formatters and checks:
make fmt
make checkThis project is licensed under the MIT License. See LICENSE.