@yawlabs/postgres-mcp 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-08-23
+
+### Added
+
+- **`pg_index_advisor`, an index RECOMMENDATION tool.** The server already had
+  every input -- HypoPG for hypothetical indexes, `pg_stat_statements` via
+  `pg_top_queries`, and `pg_seq_scan_tables` -- and lacked only the search layer.
+  Candidates are costed by creating hypothetical indexes, re-running EXPLAIN, and
+  keeping what actually lowers cost, under a caller-set bound on candidates and
+  EXPLAIN round trips. Hypothetical indexes are session-scoped, so `hypopg_reset()`
+  runs in a teardown that fires even on error; leaking them would poison every
+  later plan in the session.
+
+  Encoded correctness note: PostgreSQL 18's skip scan means a multi-column btree
+  with an unconstrained LEADING column can now be used, so the classic "leading
+  column never filtered = dead index" heuristic is wrong on PG18+. That reasoning
+  is version-gated.
+
+- **Structured tool output.** Every tool now declares an `outputSchema` and
+  returns `structuredContent` alongside the existing serialized text block.
+  Tools that return a bare array wrap it as `{ rows: [...] }`, because
+  `structuredContent` must be a JSON object; the `content` block is unchanged, so
+  nothing that reads it today breaks. Version-gated fields are modelled as
+  OPTIONAL rather than nullable -- absence is a deliberate signal in this codebase
+  and a nullable schema would erase the distinction.
+
+- **Opt-in audit logging of agent SQL** via `POSTGRES_AUDIT_LOG` /
+  `POSTGRES_AUDIT_LOG_FILE` / `POSTGRES_AUDIT_REDACT`, off by default. One JSON
+  line per statement: timestamp, tool, SQL, parameter COUNT, duration, rows, and
+  ok/SQLSTATE. Parameter VALUES are never logged -- they routinely carry PII and
+  credentials. A redacting mode logs only the leading keyword plus a hash for
+  operators who want the trail without the content. An unopenable sink fails
+  LOUDLY at startup rather than degrading to no trail, since an audit control that
+  quietly disables itself is worse than none.
+
+- **PostgreSQL 19 forward-compatibility.** PG19 renames
+  `pg_stat_subscription_stats.sync_error_count` to `sync_table_error_count` and
+  wait event type `BUFFERPIN` to `BUFFER`. Wait-event values are asserted to pass
+  through untouched, so a future filter on the old literal -- which would silently
+  match nothing on PG19 -- cannot be added without failing a test.
+
+### Changed
+
+- **Dual-era MCP protocol support.** The server was legacy-only: it pinned SDK
+  v1, which tops out at protocol revision 2025-11-25, and the current revision's
+  compatibility matrix states that a modern client talking to a legacy server
+  FAILS. It now serves both eras via SDK v2's `serveStdio`. The existing
+  process-level tests still drive a real `initialize` handshake against the
+  emitted bundle, which is what proves the legacy path still works.
+
+### Fixed
+
+- **`release.sh` could report a failed release as a success.** The status lived
+  in a value a caller could easily discard, and a pipeline returns its LAST
+  command's status -- so a release that died at the push step read as exit 0. The
+  failure banner is now the final thing written, on both streams, naming the step
+  and its remedy. Re-entry is also guarded: a local tag that does not match the
+  commit being released now fails loudly instead of building a GitHub release
+  from an orphaned tag.
+
+- **`wsl-test-matrix.sh` tested against stale dependencies.** It ran `npm ci`
+  only when `node_modules` was ABSENT, so a branch that changed a dependency was
+  silently tested against the previous branch's tree. It reinstalls on a
+  lockfile-hash change, and a failing install aborts instead of proceeding. This
+  produced a red matrix on all three majors during this very change set.
+
+- **The oam sandbox allowlist dropped the new audit variables.** oam removes an
+  undeclared variable rather than denying it, so `POSTGRES_MCP_SANDBOX=1` would
+  have silently disabled the audit trail. Caught by the bundle-scanning test
+  added in 0.11.0. Also documented that the sandbox denies the filesystem, so a
+  FILE audit sink cannot open under it -- use the stderr sink there.
+
+- **Integration tests called handlers with arguments no MCP client could send.**
+  Several call sites passed a `limit` above the declared schema maximum; direct
+  handler calls bypass Zod, so they silently worked and a cap regression would
+  not have been caught. Bounds are now respected, and a schema-level test pins
+  the cap.
+
+
 ## [0.11.2] - 2026-08-23
 
 ### Fixed

package/README.md

@@ -190,6 +190,7 @@ The bigger leverage is multi-tool reasoning. A few real workflows:
 | `pg_list_extensions` | List installed extensions (pgvector, postgis, pg_stat_statements, etc.) with versions. |
 | `pg_search_columns` | Find columns by name pattern across all user schemas. Case-insensitive, supports SQL LIKE wildcards. |
 | `pg_explain` | `EXPLAIN` or `EXPLAIN ANALYZE` for a SQL statement. Text or JSON output. Planner options: `buffers` (on by default with `analyze`), `settings`, `verbose`, `wal`, `costs`, `timing`, plus `generic_plan` (PG16+, plan a parameterized query with no values) and `memory` / `serialize` (PG17+). Optional `hypothetical_indexes` (requires the [HypoPG](https://github.com/HypoPG/hypopg) extension) lets you ask "what would the plan be with these indexes?" without creating them on disk. |
+| `pg_index_advisor` | Recommend indexes for a workload and prove each one pays for itself first. Takes `statements` you pass or the top N from `pg_stat_statements`, harvests candidate columns from what the **planner** reports as filters / join keys / sort keys (no SQL parser - every token is intersected with the real `pg_attribute` column list), then costs each candidate with [HypoPG](https://github.com/HypoPG/hypopg) hypothetical indexes and keeps only what measurably lowers estimated cost. Greedy and bounded via `max_candidates` / `max_explains`, so a big workload cannot run away; `budget_exhausted` flags a truncated search. Returns the `CREATE INDEX` (plus a `CONCURRENTLY` form), cost before/after, which statements each index helps, and the estimated size. **PG18-aware:** PG18 added B-tree skip scan, so a multi-column index whose leading column is never filtered is no longer useless - that classic prune is gated on the server version rather than applied blindly. Requires HypoPG; indexes are session-scoped and reset on every exit path. |
 | `pg_health` | Server version, database size, connections against `max_connections`, active queries with wait events and transaction age, `pg_stat_database` rollup (deadlocks, temp files, cache hit ratio), table count. |
 | `pg_top_queries` | Top N queries by total/mean execution time. Requires the `pg_stat_statements` extension. Returns `stats_reset` (from `pg_stat_statements_info`, a different clock from the other stats tools) and `dealloc` on extension 1.9+ - a non-zero `dealloc` means entries were evicted past `pg_stat_statements.max`, so the ranking is drawn from an incomplete population. |
 | `pg_seq_scan_tables` | Tables with heavy sequential scans - missing-index candidates. Returns the `stats_reset` window alongside the rows, since the counters mean nothing without it. `last_seq_scan` / `last_idx_scan` on PG16+. |

package/bin/postgres-mcp.mjs

@@ -190,7 +190,14 @@ function sandboxFlags() {
   // getApplicationName() in src/api.ts; PGAPPNAME is pg's own env fallback for
   // the same setting (connection-parameters.js: val('application_name', config,
   // 'PGAPPNAME')), so omitting it would drop a name set the driver's way.
-  const env = ["ALLOW_WRITES","DATABASE_URL","NODE_PG_FORCE_NATIVE","PGAPPNAME","PGCONNECT_TIMEOUT","PGSSLMODE","POSTGRES_APPLICATION_NAME","POSTGRES_CONNECTION_TIMEOUT_MS","POSTGRES_MAX_ROWS","POSTGRES_POOL_MAX","POSTGRES_SSL_REJECT_UNAUTHORIZED","POSTGRES_STATEMENT_TIMEOUT_MS","USER","USERNAME"];
+  // POSTGRES_AUDIT_LOG_FILE is granted as a VARIABLE here, but the sandbox
+  // still denies the filesystem, so the file sink cannot actually open its
+  // target under POSTGRES_MCP_SANDBOX=1. The audit module fails loudly on an
+  // unopenable sink rather than silently dropping the trail, so the combination
+  // refuses to start -- which is the correct outcome (an audit control that
+  // quietly disables itself is worse than none), but it is a surprising one to
+  // hit at runtime. Use the stderr sink under the sandbox.
+  const env = ["ALLOW_WRITES","DATABASE_URL","NODE_PG_FORCE_NATIVE","PGAPPNAME","PGCONNECT_TIMEOUT","PGSSLMODE","POSTGRES_APPLICATION_NAME","POSTGRES_AUDIT_LOG","POSTGRES_AUDIT_LOG_FILE","POSTGRES_AUDIT_REDACT","POSTGRES_CONNECTION_TIMEOUT_MS","POSTGRES_MAX_ROWS","POSTGRES_POOL_MAX","POSTGRES_SSL_REJECT_UNAUTHORIZED","POSTGRES_STATEMENT_TIMEOUT_MS","USER","USERNAME"];
 
   const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
   return flags;