postgres-aiops 0.3.0__tar.gz → 0.5.0__tar.gz

{postgres_aiops-0.3.0 → postgres_aiops-0.5.0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.5.0 — 2026-07-20
+
+### Fixed
+- **`terminate_backend` / `cancel_query` refuse this tool's own backend**, and `update_setting` refuses the postmaster settings that would strand the undo at the next restart (`listen_addresses`, `port`, `max_connections`, `ssl`, `hba_file`, …).
+- A connection lost **mid-statement** now raises a dedicated error and is audited as `unknown`, not `error`..
+- Harness: a write whose response is lost is audited `status=unknown`, not `error` — it may have taken effect. Undo tokens gain `effectVerified` (undo.db migrated in place).
+- Harness: a dry-run no longer records an undo token, and no longer requires a named approver. Guards now run on the preview path.
+- Truncated strings end in an ellipsis instead of being cut silently; error messages are capped at 800 chars, not 300.
+
+See RELEASE_NOTES.md for the full detail.
+
 ## v0.3.0 — 2026-07-17
 
 ### Added

{postgres_aiops-0.3.0 → postgres_aiops-0.5.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: postgres-aiops
-Version: 0.3.0
+Version: 0.5.0
 Summary: Governed AI-ops for PostgreSQL DBA operations: slow-query RCA, bloat/vacuum & blocking-lock analysis with a built-in governance harness (audit, budget, undo, risk tiers)
-Author-email: wei <zhouwei008@gmail.com>
+Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.11
@@ -16,7 +16,7 @@ Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.AIops-tools/postgres-aiops -->
 
-# Postgres AIops (preview)
+# Postgres AIops
 
 > **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the PostgreSQL Global Development Group or any vendor.** "PostgreSQL" and the elephant logo are trademarks of the PostgreSQL Community Association; all product/trademark names belong to their respective owners. MIT licensed.
 
@@ -24,7 +24,8 @@ Governed AI-ops for **PostgreSQL DBA operations** — connecting to a server wit
 **psycopg 3** and reading the system catalogs and `pg_stat_*` views — with a
 **built-in governance harness**: unified audit log, policy engine, token/runaway
 budget guard, undo-token recording, and graduated-autonomy risk tiers.
-**Preview — mock-validated only, not run against a live cluster.**
+Beyond the mock test suite, the reads, a governed write, and its undo have been
+exercised against a live PostgreSQL 16.14 instance — see [`docs/VERIFICATION.md`](docs/VERIFICATION.md).
 
 ## What it does
 
@@ -43,12 +44,12 @@ Three flagship signature analyses, plus the guarded reads and writes around them
 ## What works
 
 - **CLI** (`postgres-aiops ...`): `init`, `overview`, `server`, `activity`, `query`, `index`, `table`, `repl`, `analyze`, `remediate`, `secret`, `doctor`, `mcp`.
-- **MCP server** (`postgres-aiops mcp` or `postgres-aiops-mcp`): **33 tools** (24 read, 9 write), every one wrapped with the bundled `@governed_tool` harness.
+- **MCP server** (`postgres-aiops mcp` or `postgres-aiops-mcp`): **35 tools** (25 read, 10 write), every one wrapped with the bundled `@governed_tool` harness.
 - **Encrypted credentials**: the role password lives in an encrypted store `~/.postgres-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `POSTGRES_AIOPS_MASTER_PASSWORD` (MCP/CI) or an interactive prompt (CLI).
 - **Reversibility**: mutating writes fetch the **real before-state first** and record a faithful inverse — `create_index`↔`drop_index`; `drop_index` captures `pg_get_indexdef` so undo recreates it exactly; `update_setting` captures the prior value so undo sets it back. Irreversible ops (`terminate_backend`, `cancel_query`, `run_vacuum`, `run_analyze`, `reindex`, `reset_query_stats`) record prior stats for audit but declare no undo.
 - **Safety**: every state-changing CLI op supports `--dry-run` and requires double confirmation; every write MCP tool takes a `dry_run` preview. All identifiers that cannot be parameterised (table/index/GUC names) are validated and quoted; all values are bound query parameters.
 
-## Capability matrix (33 MCP tools)
+## Capability matrix (35 MCP tools)
 
 | Domain | Tools | Count | R/W |
 |--------|-------|:-----:|:---:|
@@ -62,11 +63,53 @@ Three flagship signature analyses, plus the guarded reads and writes around them
 | **Analysis (flagship)** | `slow_query_rca`, `bloat_and_vacuum_analysis`, `blocking_lock_chain_rca` | 3 | read |
 | **Writes** | `terminate_backend`, `cancel_query`, `drop_index` | 3 | write (high) |
 | | `run_vacuum`, `run_analyze`, `create_index`, `reindex`, `update_setting`, `reset_query_stats` | 6 | write (medium) |
+| **Undo** | `undo_list` | 1 | read |
+| | `undo_apply` | 1 | write (medium) |
 
 The flagship analyses accept injected records for pure/offline analysis, or pull
 live from a configured target. `top_queries`/`slow_query_rca` require the
 `pg_stat_statements` extension; the read role should have `pg_monitor`.
 
+## Security: read-only mode
+
+This tool is meant to be handed to an AI agent, so its safety story is enforced
+by the server rather than requested in a prompt:
+
+```bash
+export POSTGRES_READ_ONLY=1
+```
+
+With that set, the **10 write tools are never registered**. An MCP client
+lists **25 tools instead of 35** — the writes are not hidden, not
+gated behind a flag, and not merely refused when called. They are absent from
+the session. A model cannot invoke a tool it was never offered, and cannot be
+argued into one.
+
+That distinction is the whole point. A tool that exists but refuses still invites
+retry loops and "I'll describe the call instead" behaviour from smaller models,
+and it leaves a reviewer trusting a promise. An absent tool is a fact you can
+check: connect, list the tools, and see that the writes are not there.
+
+Enforcement is two layers deep, so the switch cannot be sidestepped by changing
+entry point:
+
+| Layer | What it does | Covers |
+|---|---|---|
+| `@governed_tool` harness | refuses every non-read operation outright | MCP, CLI, and in-process callers |
+| MCP registration | write tools are removed from `list_tools()` | anything speaking MCP |
+
+Read operations are unaffected, and every call is still audited to
+`~/.postgres-aiops/audit.db`.
+
+> The read/write split is derived from each tool's declared `risk_level`, and a
+> test asserts that this never disagrees with the `[READ]`/`[WRITE]` tag in the
+> tool's own documentation — so a write can't quietly present itself as a read.
+
+Running a smaller / local model? See
+[agent-guardrails.md](skills/postgres-aiops/references/agent-guardrails.md) — it lists
+the guardrails this tool now enforces for you (so you don't spend prompt budget
+restating them) and gives a ready-made system prompt for what's left.
+
 ## Quick start
 
 ```bash
@@ -114,6 +157,9 @@ an issue or PR** — contributions welcome.
 
 ## Status
 
-**Preview — mock-validated only, not run against a live cluster.** The catalog
-queries are modelled from the documented `pg_catalog` / `pg_stat_*` shapes and
-need live verification. `postgres-aiops doctor` is the fastest live check.
+The mock test suite is complemented by a live run: the catalog / `pg_stat_*`
+reads, the `bloat_and_vacuum_analysis` RCA, and the `create_index` / `drop_index`
+governed write path (audit + undo, with `drop_index` capturing
+`pg_get_indexdef` first) were exercised against a live PostgreSQL 16.14 instance running in
+Docker. [`docs/VERIFICATION.md`](docs/VERIFICATION.md) records exactly what was
+and was not covered. `postgres-aiops doctor` is the fastest live check.

{postgres_aiops-0.3.0 → postgres_aiops-0.5.0}/README.md

@@ -1,6 +1,6 @@
 <!-- mcp-name: io.github.AIops-tools/postgres-aiops -->
 
-# Postgres AIops (preview)
+# Postgres AIops
 
 > **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the PostgreSQL Global Development Group or any vendor.** "PostgreSQL" and the elephant logo are trademarks of the PostgreSQL Community Association; all product/trademark names belong to their respective owners. MIT licensed.
 
@@ -8,7 +8,8 @@ Governed AI-ops for **PostgreSQL DBA operations** — connecting to a server wit
 **psycopg 3** and reading the system catalogs and `pg_stat_*` views — with a
 **built-in governance harness**: unified audit log, policy engine, token/runaway
 budget guard, undo-token recording, and graduated-autonomy risk tiers.
-**Preview — mock-validated only, not run against a live cluster.**
+Beyond the mock test suite, the reads, a governed write, and its undo have been
+exercised against a live PostgreSQL 16.14 instance — see [`docs/VERIFICATION.md`](docs/VERIFICATION.md).
 
 ## What it does
 
@@ -27,12 +28,12 @@ Three flagship signature analyses, plus the guarded reads and writes around them
 ## What works
 
 - **CLI** (`postgres-aiops ...`): `init`, `overview`, `server`, `activity`, `query`, `index`, `table`, `repl`, `analyze`, `remediate`, `secret`, `doctor`, `mcp`.
-- **MCP server** (`postgres-aiops mcp` or `postgres-aiops-mcp`): **33 tools** (24 read, 9 write), every one wrapped with the bundled `@governed_tool` harness.
+- **MCP server** (`postgres-aiops mcp` or `postgres-aiops-mcp`): **35 tools** (25 read, 10 write), every one wrapped with the bundled `@governed_tool` harness.
 - **Encrypted credentials**: the role password lives in an encrypted store `~/.postgres-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `POSTGRES_AIOPS_MASTER_PASSWORD` (MCP/CI) or an interactive prompt (CLI).
 - **Reversibility**: mutating writes fetch the **real before-state first** and record a faithful inverse — `create_index`↔`drop_index`; `drop_index` captures `pg_get_indexdef` so undo recreates it exactly; `update_setting` captures the prior value so undo sets it back. Irreversible ops (`terminate_backend`, `cancel_query`, `run_vacuum`, `run_analyze`, `reindex`, `reset_query_stats`) record prior stats for audit but declare no undo.
 - **Safety**: every state-changing CLI op supports `--dry-run` and requires double confirmation; every write MCP tool takes a `dry_run` preview. All identifiers that cannot be parameterised (table/index/GUC names) are validated and quoted; all values are bound query parameters.
 
-## Capability matrix (33 MCP tools)
+## Capability matrix (35 MCP tools)
 
 | Domain | Tools | Count | R/W |
 |--------|-------|:-----:|:---:|
@@ -46,11 +47,53 @@ Three flagship signature analyses, plus the guarded reads and writes around them
 | **Analysis (flagship)** | `slow_query_rca`, `bloat_and_vacuum_analysis`, `blocking_lock_chain_rca` | 3 | read |
 | **Writes** | `terminate_backend`, `cancel_query`, `drop_index` | 3 | write (high) |
 | | `run_vacuum`, `run_analyze`, `create_index`, `reindex`, `update_setting`, `reset_query_stats` | 6 | write (medium) |
+| **Undo** | `undo_list` | 1 | read |
+| | `undo_apply` | 1 | write (medium) |
 
 The flagship analyses accept injected records for pure/offline analysis, or pull
 live from a configured target. `top_queries`/`slow_query_rca` require the
 `pg_stat_statements` extension; the read role should have `pg_monitor`.
 
+## Security: read-only mode
+
+This tool is meant to be handed to an AI agent, so its safety story is enforced
+by the server rather than requested in a prompt:
+
+```bash
+export POSTGRES_READ_ONLY=1
+```
+
+With that set, the **10 write tools are never registered**. An MCP client
+lists **25 tools instead of 35** — the writes are not hidden, not
+gated behind a flag, and not merely refused when called. They are absent from
+the session. A model cannot invoke a tool it was never offered, and cannot be
+argued into one.
+
+That distinction is the whole point. A tool that exists but refuses still invites
+retry loops and "I'll describe the call instead" behaviour from smaller models,
+and it leaves a reviewer trusting a promise. An absent tool is a fact you can
+check: connect, list the tools, and see that the writes are not there.
+
+Enforcement is two layers deep, so the switch cannot be sidestepped by changing
+entry point:
+
+| Layer | What it does | Covers |
+|---|---|---|
+| `@governed_tool` harness | refuses every non-read operation outright | MCP, CLI, and in-process callers |
+| MCP registration | write tools are removed from `list_tools()` | anything speaking MCP |
+
+Read operations are unaffected, and every call is still audited to
+`~/.postgres-aiops/audit.db`.
+
+> The read/write split is derived from each tool's declared `risk_level`, and a
+> test asserts that this never disagrees with the `[READ]`/`[WRITE]` tag in the
+> tool's own documentation — so a write can't quietly present itself as a read.
+
+Running a smaller / local model? See
+[agent-guardrails.md](skills/postgres-aiops/references/agent-guardrails.md) — it lists
+the guardrails this tool now enforces for you (so you don't spend prompt budget
+restating them) and gives a ready-made system prompt for what's left.
+
 ## Quick start
 
 ```bash
@@ -98,6 +141,9 @@ an issue or PR** — contributions welcome.
 
 ## Status
 
-**Preview — mock-validated only, not run against a live cluster.** The catalog
-queries are modelled from the documented `pg_catalog` / `pg_stat_*` shapes and
-need live verification. `postgres-aiops doctor` is the fastest live check.
+The mock test suite is complemented by a live run: the catalog / `pg_stat_*`
+reads, the `bloat_and_vacuum_analysis` RCA, and the `create_index` / `drop_index`
+governed write path (audit + undo, with `drop_index` capturing
+`pg_get_indexdef` first) were exercised against a live PostgreSQL 16.14 instance running in
+Docker. [`docs/VERIFICATION.md`](docs/VERIFICATION.md) records exactly what was
+and was not covered. `postgres-aiops doctor` is the fastest live check.

postgres_aiops-0.5.0/RELEASE_NOTES.md

@@ -0,0 +1,50 @@
+# Release notes — postgres-aiops 0.5.0
+
+Previous release: 0.4.0.
+
+## In this tool
+
+- **`terminate_backend` / `cancel_query` refuse this tool's own backend**, and `update_setting` refuses the postmaster settings that would strand the undo at the next restart (`listen_addresses`, `port`, `max_connections`, `ssl`, `hba_file`, …). The read path already filtered `pg_backend_pid()`; the writes did not.
+- A connection lost **mid-statement** now raises a dedicated error and is audited as `unknown`, not `error`.
+
+## Every tool in the line: previews and undetermined outcomes
+
+This release fixes three harness defects that were silently degrading the audit
+trail and the undo store.
+
+**A write that loses its response is no longer recorded as a failure.** The
+harness assumed a sanitized error meant nothing had happened. That assumption is
+false in exactly the case that matters most: when a write severs its own
+connection, the request has already landed, the response cannot come back, and
+the operation was recorded as `status=error` with **no undo token created at
+all**. Transport-level failures are now audited as `status=unknown`, the result
+says plainly that the operation may have taken effect and should be verified
+before retrying, and a write that stashed its before-state has its inverse
+recorded anyway — flagged `effectVerified: false`, which `undo_list` and
+`undo_apply` both surface. Existing `undo.db` files are migrated in place; their
+rows read as verified, which is accurate, since the old code only ever recorded
+on the confirmed path.
+
+**A dry-run no longer writes an undo token.** Previews were recording inverses
+built from a before-state they never had: the undo callback's permissive default
+filled the gap with a guess, producing a real, applicable token for an operation
+that never happened.
+
+**A dry-run no longer demands a named approver.** Requiring an approval in order
+to ask whether something needs approval inverts what a preview is for. The tier
+is still computed and still audited, so the preview can tell you an approver
+will be needed; it just no longer refuses to answer. The write itself is gated
+exactly as before.
+
+The invariant, now stated: **a dry_run may read; it must never write.** Guards
+run on the preview path, which means a preview can and does report that an
+operation would be refused.
+
+## Also line-wide
+
+- **Truncated text now ends in an ellipsis** instead of being cut silently. This
+  line already treats a silent cut as a defect for lists; it was doing exactly
+  that to strings.
+- **Error messages are capped at 800 characters, not 300.** These messages end
+  with what to do instead, so the cap was removing the most useful sentence of
+  every long refusal.

postgres_aiops-0.5.0/docs/VERIFICATION.md

@@ -0,0 +1,159 @@
+# Live verification
+
+`postgres-aiops` has been **exercised against a live PostgreSQL instance**
+(PostgreSQL **16.14**, running in Docker) in addition to its mock test suite.
+This document records exactly what that run covered, what it did **not**, and the
+checklist any further live run should follow. It is deliberately checklist-shaped
+so the result is reproducible and auditable — not a subjective "seems fine".
+
+**Scope of the claim**: the catalog / `pg_stat_*` reads, the
+`bloat_and_vacuum_analysis` RCA, and the `create_index` / `drop_index` governed
+write path (audit + undo) were run against that instance and behaved as the mock
+suite predicts. Sections left open below are **not** claimed.
+
+## What the mock suite already guarantees
+
+- Every module imports; the CLI builds; every MCP tool carries the
+  `@governed_tool` harness marker (`tests/test_smoke.py`).
+- The three flagship analyses are unit-tested against synthetic rows:
+  `slow_query_rca` (seq scan / cache-hit / temp-spill / call-count findings, each
+  citing its measured number), `bloat_and_vacuum_analysis` (dead-tuple ratio +
+  autovacuum lag ranking), and `blocking_lock_chain_rca` (wait-for tree with the
+  root blocker named, not just the visible victims).
+- SQL safety: all values are bound query parameters; identifiers that cannot be
+  parameterised (table / index / GUC names, `ORDER BY` columns, index methods)
+  are validated against strict allow-lists and quoted; `EXPLAIN` rejects
+  multi-statement input.
+- Reversible writes record the correct inverse: `create_index` ↔ `drop_index`
+  (with `drop_index` capturing `pg_get_indexdef` **before** dropping), and
+  `update_setting` capturing the prior value. Irreversible ops (terminate,
+  cancel, vacuum, analyze, reindex, reset stats) declare no undo.
+- Governance persistence: audited rows land in the SQLite audit DB, and the
+  secure-by-default approver gate refuses high-risk writes with no `rules.yaml`
+  and no `POSTGRES_AUDIT_APPROVED_BY`.
+
+## Prerequisites for a live run
+
+A reachable PostgreSQL server you are willing to write to — a Docker container
+is enough, and is what the recorded run used:
+
+```bash
+docker run -d --name pg-verify -e POSTGRES_PASSWORD=... -p 5432:5432 postgres:16
+```
+
+- A role with `pg_monitor` for the reads; `pg_stat_statements` must be
+  **installed and loaded** (`shared_preload_libraries`) for `top_queries` and
+  `slow_query_rca`.
+- A **throwaway database and table** you are willing to vacuum, index, and drop
+  indexes on. Never verify against production.
+
+```bash
+uv tool install postgres-aiops
+postgres-aiops init            # encrypted secret store for the role password
+```
+
+## Verification checklist
+
+Boxes marked ✅ were confirmed on **PostgreSQL 16.14 (Docker)**. Unticked boxes
+are open — record them as gaps rather than silently passing.
+
+### 1. Connectivity (the fastest live gate)
+- [x] ✅ `postgres-aiops doctor` → green (config, encrypted secret store, and a
+      real connection + `server_version` against the instance).
+
+### 2. Reads return real, well-shaped data
+- [x] ✅ `postgres-aiops overview` → real connection counts, database sizes, and
+      longest-query figures matching the instance.
+- [x] ✅ `postgres-aiops server version` / `server settings` / `server extensions`
+      / `server databases` / `server roles` → real catalog contents.
+- [x] ✅ `postgres-aiops activity list` and `activity long --min-seconds 1` →
+      real `pg_stat_activity` rows; no crash on NULL query text or missing
+      fields.
+- [x] ✅ `postgres-aiops table sizes` / `table bloat` / `table autovacuum` →
+      values agree with a hand query against `pg_stat_user_tables`.
+- [x] ✅ `postgres-aiops index unused` / `index missing` / `index bloat` /
+      `index invalid` → real index rows, correct emptiness on a fresh database.
+- [ ] `postgres-aiops query top` / `query explain "<sql>"` against an instance
+      with `pg_stat_statements` actually loaded (the recorded run did not have
+      the extension preloaded — **open gap**).
+- [ ] `postgres-aiops repl status` / `repl slots` / `repl wal` against a real
+      primary/standby pair (the recorded run was a single node — **open gap**).
+
+### 3. The flagship analyses hold up against real telemetry
+- [x] ✅ `postgres-aiops analyze bloat-vacuum` → on a table deliberately loaded
+      and then bulk-deleted, the RCA correctly ranked the table with ~50% dead
+      tuples first and cited the measured ratio.
+- [x] ✅ `postgres-aiops analyze blocking` → returns cleanly (empty chain) with no
+      contention present.
+- [ ] `analyze blocking` against a **real** blocking pile-up: open a transaction
+      that holds a row lock, block a second session on it, and confirm the
+      wait-for tree names the first session as root blocker (**open gap** —
+      only the empty case was exercised live).
+- [ ] `postgres-aiops analyze slow-query` against real `pg_stat_statements` data
+      (blocked on the same extension gap as section 2).
+
+### 4. A reversible write + its undo (governance closes the loop)
+- [x] ✅ `postgres-aiops remediate create-index <table> <col> --dry-run` → printed
+      the exact DDL, changed nothing.
+- [x] ✅ `create_index` for real → the index appeared in `pg_indexes`; the result
+      carried an `_undo_id`; a row landed in `~/.postgres-aiops/audit.db`.
+- [x] ✅ `drop_index` for real → the index was gone, and the undo descriptor held
+      the **captured** `pg_get_indexdef` definition, not a reconstruction.
+- [x] ✅ `postgres-aiops undo apply <id>` → replayed correctly and recreated the
+      index from the captured definition. (A replay bug found in an earlier
+      round was fixed and is now covered by a regression test.)
+- [ ] `remediate set <guc> <value>` then `undo apply` → the prior value restored
+      (**open gap** — `update_setting` was not exercised live).
+
+### 5. Irreversible writes are honest about it
+- [x] ✅ `remediate vacuum <table> --analyze` → the dead tuples were actually
+      reclaimed (confirmed by re-running `analyze bloat-vacuum`); the audit row
+      records prior stats and declares **no** undo.
+- [ ] `remediate terminate <pid>` / `remediate cancel <pid>` against a real
+      long-running backend (**open gap** — not exercised live).
+- [ ] `remediate reindex` on a real index (**open gap**).
+
+### 6. Governance actually gates
+- [x] ✅ With no `~/.postgres-aiops/rules.yaml`, a high-risk write was refused
+      until `POSTGRES_AUDIT_APPROVED_BY` named an approver (secure-by-default);
+      the approver and `POSTGRES_AUDIT_RATIONALE` appear in the audit row.
+- [x] ✅ Relocation: with `POSTGRES_AIOPS_HOME` set, `audit.db`, the undo store,
+      and `secrets.enc` all land under that directory.
+- [ ] A tight poll loop trips the runaway budget guard rather than hammering the
+      server (verified in the mock suite; not re-run live).
+
+### 7. Cleanup
+- [x] ✅ The test indexes were dropped and the throwaway container removed; every
+      step above is present in the audit DB.
+
+## Criteria to consider it live-verified
+
+1. Every checklist box is ticked against at least one real PostgreSQL version,
+   and the version is recorded. **Current status: satisfied for PostgreSQL
+   16.14 for sections 1, 2 (except `pg_stat_statements` and replication), 3
+   (bloat/vacuum), 4 (index write + undo), 5 (vacuum), 6 and 7.**
+2. Any field-shape mismatch found during a run is fixed and covered by a
+   regression test. **Current status: satisfied — the undo-replay bug found in
+   the live run was fixed and has a regression test.**
+3. The run is written up with the date and package version, matching how the
+   product line records its other live-verified tools. **Current status:
+   satisfied.**
+
+The remaining open boxes are the honest edge of the claim: `pg_stat_statements`
+based analysis, replication reads, session termination, `REINDEX`, and
+`ALTER SYSTEM` + undo have **not** been exercised against a live server.
+
+## Notes for maintainers
+
+- `postgres-aiops doctor` is the single fastest live entry point; start there.
+- To close the `pg_stat_statements` gap, start the container with
+  `-c shared_preload_libraries=pg_stat_statements`, then
+  `CREATE EXTENSION pg_stat_statements;` and generate load before running
+  `analyze slow-query`.
+- To close the blocking gap, hold a row lock in one `psql` session and block a
+  second on it — `analyze blocking` should name the first session's pid as the
+  root blocker.
+- To close the replication gap, add a streaming standby (a second container with
+  `pg_basebackup`) and re-run `repl status` / `repl slots` / `repl wal`.
+- The analyses also accept **injected records**, so exported rows from a cluster
+  you cannot write to still exercise section 3 without any write access.

{postgres_aiops-0.3.0 → postgres_aiops-0.5.0}/mcp_server/_shared.py

@@ -20,14 +20,30 @@ from typing import Any, Optional
 from mcp.server.fastmcp import FastMCP
 
 from postgres_aiops.config import load_config
-from postgres_aiops.connection import ConnectionManager, PgError
-from postgres_aiops.governance import sanitize
+from postgres_aiops.connection import ConnectionManager, PgConnectionLostError, PgError
+from postgres_aiops.governance import mark_unknown, sanitize
 
 logger = logging.getLogger(__name__)
 
 _DOCTOR_HINT = "Run 'postgres-aiops doctor' to verify connectivity and credentials."
 
 
+# Long enough to carry the remediation sentence. These messages teach the
+# caller what to do instead, and that clause comes last — a 300-char cap cut
+# it off silently on every refusal long enough to need one.
+_ERROR_MAX = 800
+
+
+# Failures that leave the statement's fate genuinely undetermined. Raised
+# only from the statement-executing path, so it means an ESTABLISHED link
+# died mid-statement — not that the server was unreachable. The driver gives
+# both the same class, so the connection layer discriminates by position and
+# raises a dedicated class; this layer only has to recognise it.
+# PostgreSQL rolls back on backend termination, so usually nothing landed —
+# but a COMMIT whose acknowledgement was lost did land.
+_UNDETERMINED_ERRORS = (PgConnectionLostError,)
+
+
 def _safe_error(exc: Exception, tool: str) -> str:
     """Return an agent-safe error string; log full detail server-side only."""
     logger.error("Tool %s failed", tool, exc_info=True)
@@ -41,7 +57,7 @@ def _safe_error(exc: Exception, tool: str) -> str:
         PgError,
     )
     if isinstance(exc, _passthrough):
-        return sanitize(str(exc), 300)
+        return sanitize(str(exc), _ERROR_MAX)
     return f"{type(exc).__name__}: operation failed."
 
 
@@ -65,7 +81,13 @@ def tool_errors(shape: str = "dict") -> Callable:
                     return [{"error": msg, "hint": _DOCTOR_HINT}]
                 if shape == "str":
                     return f"Error: {msg} {_DOCTOR_HINT}"
-                return {"error": msg, "hint": _DOCTOR_HINT}
+                payload = {"error": msg, "hint": _DOCTOR_HINT}
+                # Flatten the exception into a dict and its type is gone
+                # for good — so classify here, while it is still known,
+                # whether the operation may nonetheless have taken effect.
+                if isinstance(e, _UNDETERMINED_ERRORS):
+                    return mark_unknown(payload)
+                return payload
 
         return wrapper
 
@@ -75,7 +97,7 @@ def tool_errors(shape: str = "dict") -> Callable:
 mcp = FastMCP(
     "postgres-aiops",
     instructions=(
-        "Governed PostgreSQL DBA operations (preview): a one-shot cluster "
+        "Governed PostgreSQL DBA operations: a one-shot cluster "
         "'overview'; server reads (version/settings/extensions/databases/roles); "
         "activity (sessions, long-running queries, locks); query stats "
         "(pg_stat_statements top-N, EXPLAIN); index and table health (unused / "

postgres_aiops-0.5.0/mcp_server/server.py

@@ -0,0 +1,76 @@
+"""MCP server wrapping postgres-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``postgres_aiops`` ops package and is wrapped with the
+postgres-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed PostgreSQL DBA operations (preview).
+For PostgreSQL servers/clusters via psycopg 3.
+
+Source: https://github.com/AIops-tools/Postgres-AIops
+License: MIT
+"""
+
+import logging
+
+from mcp_server._shared import _safe_error, mcp, tool_errors
+
+# Importing the tool modules registers every @mcp.tool() onto the shared
+# `mcp` instance. Order does not matter; each module is self-contained.
+from mcp_server.tools import (  # noqa: F401 — side effects
+    activity,
+    analysis,
+    indexes,
+    queries,
+    remediation,
+    replication,
+    server,
+    tables,
+    undo,
+)
+from postgres_aiops.governance import READ_ONLY_ENV, is_read_only
+
+__all__ = ["mcp", "main", "_safe_error", "tool_errors", "apply_read_only"]
+
+logger = logging.getLogger(__name__)
+
+
+def apply_read_only() -> list[str]:
+    """Unregister every write tool when read-only mode is on.
+
+    The ``@governed_tool`` harness already refuses writes in this mode, so this
+    is a second layer — and the one that matters for smaller local models:
+    a tool absent from ``list_tools()`` cannot be hallucinated into a call,
+    whereas a tool that exists but refuses invites retry loops. It also gives a
+    compliance reviewer something checkable — the write tools are simply not
+    exposed.
+
+    ``risk_level == "low"`` is the read/write discriminator; a smoke test
+    asserts it stays in agreement with each tool's ``[READ]``/``[WRITE]``
+    docstring tag so the two can never drift apart silently.
+
+    Returns the names that were removed (empty when not in read-only mode).
+    """
+    if not is_read_only():
+        return []
+    registry = mcp._tool_manager._tools
+    dropped = [
+        name
+        for name, tool in registry.items()
+        if getattr(getattr(tool, "fn", None), "_risk_level", "low") != "low"
+    ]
+    for name in dropped:
+        del registry[name]
+    if dropped:
+        logger.info(
+            "%s is set — read-only mode: %d write tool(s) not exposed",
+            READ_ONLY_ENV, len(dropped),
+        )
+    return dropped
+
+
+def main() -> None:
+    """Run the MCP server over stdio."""
+    logging.basicConfig(level=logging.INFO)
+    apply_read_only()
+    mcp.run(transport="stdio")

{postgres_aiops-0.3.0 → postgres_aiops-0.5.0}/mcp_server/tools/analysis.py

@@ -34,14 +34,22 @@ def slow_query_rca(
         target: Target name from config; omit for the default.
     """
     conn = None
+    source: dict = {}
     if statements is None:
         conn = _get_connection(target)
-        statements = query_ops.top_queries(conn, order_by="total_time", limit=limit)["statements"]
+        source = query_ops.top_queries(conn, order_by="total_time", limit=limit)
+        statements = source["statements"]
     explain = None
     if explain_sql:
         conn = conn or _get_connection(target)
         explain = query_ops.explain_query(conn, explain_sql, analyze=False)
-    return ops.slow_query_rca(statements, explain=explain)
+    result = ops.slow_query_rca(statements, explain=explain)
+    # The RCA reads a top-N; if that top-N was itself cut short the verdict is
+    # drawn from a partial view. Say so rather than let it read as complete.
+    if source:
+        result["sourceTruncated"] = source["truncated"]
+        result["sourceLimit"] = source["limit"]
+    return result
 
 
 @mcp.tool()
@@ -62,9 +70,15 @@ def bloat_and_vacuum_analysis(
         limit: How many tables to pull when not injected (default 50).
         target: Target name from config; omit for the default.
     """
+    source: dict = {}
     if tables is None:
-        tables = table_ops.table_bloat(_get_connection(target), limit=limit)["tables"]
-    return ops.bloat_and_vacuum_analysis(tables)
+        source = table_ops.table_bloat(_get_connection(target), limit=limit)
+        tables = source["tables"]
+    result = ops.bloat_and_vacuum_analysis(tables)
+    if source:
+        result["sourceTruncated"] = source["truncated"]
+        result["sourceLimit"] = source["limit"]
+    return result
 
 
 @mcp.tool()