postgres-aiops 0.2.1__tar.gz → 0.4.0__tar.gz

postgres_aiops-0.4.0/.github/workflows/mcp-publish.yml

@@ -0,0 +1,55 @@
+name: mcp-publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish-mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Wait for PyPI
+        # The release event also triggers the PyPI publish workflow; the MCP
+        # registry validates that the package version exists on PyPI, so poll
+        # until it has propagated (every 15s, up to 10 minutes).
+        run: |
+          python3 - <<'EOF'
+          import json
+          import sys
+          import time
+          import urllib.error
+          import urllib.request
+
+          with open("server.json", encoding="utf-8") as f:
+              package = json.load(f)["packages"][0]
+          name, version = package["identifier"], package["version"]
+          url = f"https://pypi.org/pypi/{name}/{version}/json"
+          deadline = time.monotonic() + 600
+          while True:
+              try:
+                  with urllib.request.urlopen(url, timeout=10):
+                      print(f"{name}=={version} is available on PyPI.")
+                      sys.exit(0)
+              except (urllib.error.URLError, OSError) as exc:
+                  print(f"{name}=={version} not on PyPI yet ({exc}); "
+                        "retrying in 15s...")
+              if time.monotonic() >= deadline:
+                  sys.exit(f"Timed out after 10 minutes waiting for "
+                           f"{name}=={version} to appear on PyPI. "
+                           "Check the PyPI publish workflow, then re-run "
+                           "this workflow via workflow_dispatch.")
+              time.sleep(15)
+          EOF
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Login to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+      - name: Publish server.json
+        run: ./mcp-publisher publish

{postgres_aiops-0.2.1 → postgres_aiops-0.4.0}/.gitignore

@@ -5,3 +5,4 @@ __pycache__/
 .pytest_cache/
 .ruff_cache/
 *.egg-info/
+.coverage

{postgres_aiops-0.2.1 → postgres_aiops-0.4.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.3.0 — 2026-07-17
+
+### Added
+- **Undo executor**: `undo list` / `undo apply <id>` (CLI + MCP) — apply a recorded replayable inverse; the dispatched inverse is re-gated by its own risk tier; single-use, dry-run, double-confirm, both wrapper + inverse audited.
+
 ## v0.2.1 — 2026-07-16
 
 ### Fixed

{postgres_aiops-0.2.1 → postgres_aiops-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: postgres-aiops
-Version: 0.2.1
+Version: 0.4.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>
 License-Expression: MIT
@@ -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.2.1 → postgres_aiops-0.4.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.4.0/RELEASE_NOTES.md

@@ -0,0 +1,48 @@
+# Release notes — postgres-aiops 0.4.0
+
+Previous release: 0.3.0.
+
+## Headline: read-only mode
+
+```bash
+export POSTGRES_READ_ONLY=1
+```
+
+With this set the **10 write tools are never registered** — an MCP
+client lists **25 tools instead of 35**. The writes are not hidden
+behind a flag and not merely refused on call: they are absent from the session,
+so a model cannot invoke one and cannot be argued into one. For a reviewer this
+is checkable rather than promised — connect, list the tools, and the writes are
+not there.
+
+Enforcement is two layers deep: the `@governed_tool` harness refuses every
+non-read operation (covering the CLI and in-process callers too), and the MCP
+server removes write tools from `list_tools()`. Changing entry point does not
+get around it.
+
+## BREAKING — return shapes changed
+
+This release changes payloads that callers may be parsing. Both changes exist
+to stop a result from misrepresenting itself:
+
+1. **Absent fields are now `null`, not `""`.** A missing value and an empty value
+   were previously indistinguishable, which invited consumers to invent the
+   difference. Keys are still always present — only the value may be null.
+2. **Anything with a `limit` now returns an envelope** —
+   `{"<items>": [...], "returned": N, "limit": L, "truncated": bool}`. Truncation is
+   *measured* (one extra row is fetched), never inferred from the page happening to
+   be full. Where a genuine pre-cap total is knowable it is reported as `total`;
+   where it isn't, `total` is deliberately omitted rather than echoing `returned`.
+
+## Also in this release
+
+- **`docs/VERIFICATION.md`** — what the mock suite actually guarantees, a live
+  verification checklist, and the criteria for claiming this tool verified.
+- **`skills/postgres-aiops/references/agent-guardrails.md`** — for driving this tool with a
+  smaller / local model: which guardrails are now enforced for you, and a
+  ready-made system prompt for the rest.
+- Expanded operator playbooks in the skill documentation.
+- The advertised tool count now matches what an MCP client actually lists
+  (it includes `undo_list` / `undo_apply`), and a release gate keeps it honest.
+- The `(preview)` label has been dropped. It never meant unreleased; verification
+  status now lives in `docs/VERIFICATION.md` where it can be specific.

postgres_aiops-0.4.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.2.1 → postgres_aiops-0.4.0}/mcp_server/_shared.py

@@ -75,7 +75,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.4.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.2.1 → postgres_aiops-0.4.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()