@yawlabs/postgres-mcp 0.6.20 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,105 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+> **Version note:** the "Changed (breaking)" entries below alter the shape of
+> tool output and the CLI's exit behavior. Under SemVer-for-0.x that makes the
+> next release a MINOR bump -- `0.8.0`, not `0.7.1`. `release.sh` performs the
+> actual bump (`npm version`) and syncs `server.json`, so nothing is pre-bumped
+> here; pass `0.8.0` when cutting the release.
+
+### Changed (breaking)
+
+- `QueryResult.command` is now OPTIONAL, and is omitted entirely for statements
+  that run on the cursor path (every SELECT and other row-returning statement).
+  Previously it reported `"FETCH"` for all of them -- the command tag of the
+  internal `FETCH`, not of the user's statement. Postgres does not surface the
+  inner tag through a cursor and there is no source of truth to substitute, so
+  the field is absent rather than wrong. It is still present and correct on the
+  direct-exec path (DDL and DML without `RETURNING`), where node-pg reports the
+  first word of the real tag: `CREATE`, `INSERT`, etc.
+- `rowCount` no longer exceeds `rows.length` on a truncated cursor-path result.
+  The bounded fetch deliberately reads `POSTGRES_MAX_ROWS + 1` rows to detect
+  truncation, and that extra probe row was leaking into `rowCount` -- callers
+  saw `rowCount: 1001` next to 1000 rows. The direct-exec path is unchanged and
+  still reports the AFFECTED-row count, which is independent of how many rows
+  come back: a truncated `INSERT ... RETURNING` of 10 rows correctly reports
+  `rowCount: 10`, `rows.length: 3`, `truncated: true`.
+- `pg_top_queries` is now scoped to the database in `DATABASE_URL`.
+  `pg_stat_statements` is cluster-wide, so on a shared cluster the tool
+  previously returned normalized query text from unrelated databases. Results
+  are filtered by `dbid`, matching every other tool in this server. Callers who
+  relied on the cluster-wide view will see fewer rows.
+- The CLI now exits 1 with a usage message on an unrecognized bare argument
+  instead of silently starting the stdio server. `postgres-mcp doctor` used to
+  print nothing and appear to hang while the server waited for MCP framing on
+  stdin. Arguments beginning with `-` are still passed through untouched so
+  host-supplied flags keep working, and a positionally-passed connection string
+  gets a targeted message pointing at the `DATABASE_URL` env block.
+
+### Fixed
+
+- `pg_describe_table` no longer reports `INCLUDE` (covering) columns as part of
+  `primary_key`. PostgreSQL 11+ allows `PRIMARY KEY (id) INCLUDE (label)`, and
+  the covering column sits in `pg_index.indkey` next to the key column; the
+  query matched the whole vector. An agent reading that would build an invalid
+  `ON CONFLICT (id, label)` target. The key columns are now bounded by
+  `indnkeyatts`.
+- `resolveTypeNames` no longer throws when `shutdown()` lands mid-flight. The
+  module-scoped type cache is nulled by `shutdown()`, and dereferencing it after
+  an await (SIGTERM during a tool call, or a test calling `shutdown()` between
+  calls) raised on null -- silently costing the response its `dataTypeName`
+  fields. The cache is now bound to a local before the first await.
+- Zod schema defaults are re-applied consistently by every tool handler for
+  direct (non-MCP) callers, which bypass schema parsing. Previously only
+  `pg_explain` and `pg_table_bloat` did this; `pg_advisor` in particular bound
+  `undefined` into `n.nspname = ANY($1)` and errored at bind time. `pg_kill`
+  defaults to the safer `cancel` mode, so an omitted `mode` can never escalate
+  to `terminate`.
+
+### Documentation
+
+- `pg_readonly`'s description and the README now state the actual scope of
+  `BEGIN READ ONLY`: it bounds writes to the DATABASE, not every side effect.
+  Functions whose effect lands outside the table data -- `pg_terminate_backend`,
+  `pg_cancel_backend`, `pg_read_file`, `lo_export`, `COPY ... TO PROGRAM` -- are
+  not blocked by it and are not behind the `ALLOW_WRITES` gate that `pg_kill`
+  sits behind. All of them still require privileges the `DATABASE_URL` role must
+  hold, so the ROLE is what actually bounds this tool. Auto-allow `pg_readonly`
+  with a least-privileged role.
+- `release.sh` no longer suggests `npm login --auth-type=web` on an E401/E404.
+  That command overwrites the automation token in `~/.npmrc` with a
+  WebAuthn-bound session, and the next publish then fails on a challenge no
+  script can answer. It now points at restoring the automation token.
+- Removed stale references to a CI pipeline this repo does not have: there is no
+  `.github/`, the binary build and the lint gate are both local.
+
+### Testing
+
+- `src/index.test.ts`: the CLI entrypoint had no automated coverage at all (it
+  cannot be imported -- it calls `server.connect` at the top level), including
+  the argv handling that runs before server startup. Now driven as a child
+  process: both version flags, the argv guard's three branches, and a full MCP
+  `initialize` + `tools/list` handshake that covers the tool-registration wiring.
+- Coverage for the `DECLARE`-succeeded / `FETCH`-failed branch of
+  `runUserQueryBounded`, which prevents re-executing a statement whose side
+  effects already landed. Engineered with a short `statement_timeout`; a
+  sequence acts as the double-execution detector, since `nextval` is
+  non-transactional and survives the rollback.
+- Coverage for `dbid` scoping (with a positive control proving the assertion is
+  not vacuous), the truncated `INSERT ... RETURNING` row count, `command`
+  presence on both paths, `PRIMARY KEY ... INCLUDE`, composite-PK ordering,
+  `shutdown()` mid-bootstrap, and `getPool()` without `DATABASE_URL` including
+  the win32-only hint branch.
+- `scripts/wsl-pg-setup.sh` now provisions PostgreSQL 15 alongside 17 and 18,
+  adds `pg_stat_statements` to `shared_preload_libraries`, and creates
+  `pg_stat_statements` + `pgstattuple`. Without those extensions present, every
+  `pg_top_queries` test and both `pg_table_bloat` `approx`/`exact` tests took
+  their "extension not installed" early return and proved nothing about the
+  tool's SQL. PG15 is there for column coverage, not recency:
+  `pg_stat_statements` renamed `blk_read_time` to `shared_blk_read_time` in 1.11
+  (PG17), and with only 17/18 in the matrix the pre-1.11 branch was never
+  selected.
+
 ## [0.6.20] - 2026-06-04
 
 ### Fixed
@@ -88,6 +187,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a local-only pre-tag gate; this is just an opt-in fail-fast.
 - `package.json` `package-lock.json` and `server.json` all bumped to 0.6.20.
 
+## [0.6.19] - 2026-06-02
+
+Release-flow hardening; no library behavior changes shipped in this version.
+
+### Fixed
+- `release.sh` refuses to push when origin already has `v<version>` pointing
+  at a different commit (rewound tag elsewhere, parallel release race) --
+  previously `git push --follow-tags` silently skipped the stale tag and the
+  GitHub release linked the wrong commit. Compares tag-object SHAs so resume
+  runs don't false-abort.
+- README "Add to Yaw MCP" badge points at the https forwarder so it renders
+  as a link on github.com (raw `yaw://` hrefs are stripped).
+
+### Added
+- `SKIP_LINT=1` escape hatch in `release.sh` for hosts where the npm
+  run-script wrapper segfaults on exit-cleanup (MINGW64-ARM64).
+- `wrapToolHandler` extracted from `index.ts` for testability, with unit
+  coverage of the MCP result wrapper and the connect-failure path (expanded
+  further in 0.6.20).
+
+## [0.6.18] - 2026-05-28
+
+### Changed
+- Release publishing consolidated into `release.sh`: the MCP Registry publish
+  moved into the script and `release.yml` (plus the non-release CI workflows)
+  was dropped. The script hands off to CI when a CI publish path exists and
+  publishes from the workstation otherwise.
+
+### Fixed
+- `release.sh` syncs `server.json` unconditionally, not only inside the bump
+  branch, so a resume run no longer asks mcp-publisher to re-publish the
+  previous version (400 duplicate-version).
+- `release.sh` falls back to the gh CLI session token when
+  `MCP_REGISTRY_TOKEN` is unset.
+- The release confirmation prompt is tty-gated so non-interactive runs don't
+  hang on `read`.
+
+### Docs
+- README install badge swapped to the "Add to Yaw MCP" deep link; `npx`
+  spawn examples pinned to `@latest` for auto-update.
+
+## [0.6.17] - 2026-05-19
+
+### Added
+- `release.sh` accepts an optional pre-release commit message as a second
+  argument: runs the pre-commit checklist, commits tracked changes, then
+  proceeds with the release.
+- Post-publish smoke script (`scripts/post-publish-smoke.sh`) wired into the
+  release flow -- exercises the published tarball via a real `npx` install
+  instead of trusting `npm view` registry metadata.
+
 ## [0.6.16] - 2026-05-18
 
 ### Tests

package/README.md

@@ -27,7 +27,7 @@ None of them position themselves as a general-purpose daily driver you'd hand to
 
 ## Why this one?
 
-- **Read-only by default, with an unconditional read-only tool too** - `pg_query` runs user SQL in a `BEGIN READ ONLY` transaction, so postgres itself (not string parsing) blocks writes; opt in to writes with `ALLOW_WRITES=1`. `pg_readonly` is a separate tool that stays read-only regardless of `ALLOW_WRITES`, so hosts that gate tools individually (Claude Code permissions, mcp.hosting) can safely auto-allow it.
+- **Read-only by default, with an unconditional read-only tool too** - `pg_query` runs user SQL in a `BEGIN READ ONLY` transaction, so postgres itself (not string parsing) blocks writes; opt in to writes with `ALLOW_WRITES=1`. `pg_readonly` is a separate tool that stays read-only regardless of `ALLOW_WRITES`, so hosts that gate tools individually (Claude Code permissions, mcp.hosting) can auto-allow it -- paired with a least-privileged role, since `READ ONLY` bounds writes to the database rather than every side effect ([details](#per-tool-gating-in-the-host)).
 - **Role-based access as the primary control** - the recommended posture is to use a least-privileged postgres role in `DATABASE_URL` (e.g. one with `GRANT pg_read_all_data`); postgres itself then enforces the boundary, no env var needed. See [Configuring access](#configuring-access).
 - **Extended query protocol for all user SQL** - `pg_query` sends user input with `queryMode: 'extended'`, which restricts each request to a single statement. This closes the [stacked-query injection class](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/) (`COMMIT; DROP SCHEMA x CASCADE;`) that defeated the reference server's `BEGIN READ ONLY` wrapper. Integration test asserts the rejection.
 - **Parameterized queries** - `pg_query` takes a `params` array for `$1`, `$2`, etc. No string-interpolated SQL in our code path.
@@ -132,6 +132,8 @@ Tools split cleanly across two authority classes:
 
 Claude Code's `permissions` block and mcp.hosting's per-tool toggle both honor this split.
 
+> **What `READ ONLY` does and does not cover.** A `BEGIN READ ONLY` transaction blocks writes to the *database* -- INSERT/UPDATE/DELETE, DDL, `nextval`/`setval`. It does not block functions whose effect lands outside the table data. `SELECT pg_terminate_backend(...)`, `pg_cancel_backend`, `pg_read_file`, `lo_export`, and `COPY ... TO PROGRAM` all run to completion inside `pg_readonly`, which means auto-allowing `pg_readonly` reaches the same capability that `pg_kill` puts behind `ALLOW_WRITES=1`. Every one of them still requires a privilege the `DATABASE_URL` role must actually hold (`pg_signal_backend`, `pg_read_server_files`, superuser), so **the role is the control that bounds this tool, not the transaction mode.** If you auto-allow `pg_readonly`, use a least-privileged role -- see [Configuring access](#configuring-access).
+
 **`ALLOW_WRITES` as defense-in-depth:**
 
 `ALLOW_WRITES` is a secondary belt-and-braces gate. Useful when:
@@ -161,7 +163,7 @@ The bigger leverage is multi-tool reasoning. A few real workflows:
 
 | Tool | Description |
 |------|-------------|
-| `pg_readonly` | Run a SQL statement guaranteed read-only - always inside `BEGIN READ ONLY`, regardless of `ALLOW_WRITES`. The recommended tool for read access; safe for hosts to auto-allow. |
+| `pg_readonly` | Run a SQL statement with no persistent data changes - always inside `BEGIN READ ONLY`, regardless of `ALLOW_WRITES`. The recommended tool for read access, and the one to auto-allow; pair it with a least-privileged role ([why](#per-tool-gating-in-the-host)). |
 | `pg_query` | Run a SQL query. Writes gated by the role in `DATABASE_URL` first, `ALLOW_WRITES` second. Supports parameterized queries via `params`. Result fields include `dataTypeName` (e.g. `int4`, `jsonb`) alongside `dataTypeID`. |
 | `pg_list_schemas` | List non-system schemas. |
 | `pg_list_tables` | List tables (and optionally views) in a schema with estimated row counts. Paginated via `limit`/`offset`. |
@@ -246,6 +248,12 @@ DATABASE_URL='postgres://user:pass@host:5432/db' POSTGRES_MCP_INTEGRATION=1 npm
 
 The integration suite assumes a disposable database -- it creates and drops a `test_fixture` schema. Don't point it at anything you care about.
 
+To also run the destructive tests (REVOKE / restricted-role path), add `POSTGRES_MCP_DESTRUCTIVE_TESTS=1`. Only safe on a disposable cluster:
+
+```bash
+DATABASE_URL='postgres://user:pass@host:5432/db' POSTGRES_MCP_INTEGRATION=1 POSTGRES_MCP_DESTRUCTIVE_TESTS=1 npm run test:integration
+```
+
 ### Windows: integration tests via WSL2
 
 Native Postgres on Windows ARM64 is fragile (UCRT runtime gaps, missing ARM64 builds). The reliable path is a disposable Ubuntu under WSL2 with the integration suite running inside WSL (WSL2's NAT blocks the Windows host from reaching :5432, so don't try to run the tests from PowerShell):

package/dist/index.js

@@ -11996,6 +11996,9 @@ var require_lib2 = __commonJS({
   }
 });
 
+// src/index.ts
+import { writeSync } from "node:fs";
+
 // node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
@@ -36144,22 +36147,24 @@ function getPool() {
 var typeNameCache = null;
 async function resolveTypeNames(client, oids) {
   if (oids.length === 0) return {};
-  if (!typeNameCache) {
-    typeNameCache = /* @__PURE__ */ new Map();
+  let cache = typeNameCache;
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    typeNameCache = cache;
     const res = await client.query("SELECT oid, typname FROM pg_catalog.pg_type");
-    for (const row of res.rows) typeNameCache.set(row.oid, row.typname);
+    for (const row of res.rows) cache.set(row.oid, row.typname);
   }
-  const missing = oids.filter((o) => !typeNameCache?.has(o));
+  const missing = oids.filter((o) => !cache.has(o));
   if (missing.length > 0) {
     const res = await client.query(
       "SELECT oid, typname FROM pg_catalog.pg_type WHERE oid = ANY($1)",
       [missing]
     );
-    for (const row of res.rows) typeNameCache.set(row.oid, row.typname);
+    for (const row of res.rows) cache.set(row.oid, row.typname);
   }
   const out = {};
   for (const oid of oids) {
-    const n = typeNameCache.get(oid);
+    const n = cache.get(oid);
     if (n !== void 0) out[oid] = n;
   }
   return out;
@@ -36192,18 +36197,19 @@ async function runUserQueryBounded(client, sql, params, maxRows) {
     } catch {
     }
     await client.query("RELEASE SAVEPOINT __pgmcp_sp");
-    return fetched;
+    return { result: fetched, viaCursor: true };
   } catch (err) {
     if (declareSucceeded) {
       throw err;
     }
     await client.query("ROLLBACK TO SAVEPOINT __pgmcp_sp");
     await client.query("RELEASE SAVEPOINT __pgmcp_sp");
-    return client.query({
+    const direct = await client.query({
       text: sql,
       values: params,
       queryMode: "extended"
     });
+    return { result: direct, viaCursor: false };
   }
 }
 async function safeResolveTypeNames(client, fields) {
@@ -36214,17 +36220,29 @@ async function safeResolveTypeNames(client, fields) {
     return {};
   }
 }
-function toQueryResult(result, maxRows, typeNames = {}) {
+function toQueryResult(result, maxRows, typeNames, viaCursor) {
   const truncated = result.rows.length > maxRows;
   const rows = truncated ? result.rows.slice(0, maxRows) : result.rows;
   return {
     rows,
-    rowCount: result.rowCount,
+    // Cursor path only: we deliberately FETCH maxRows + 1 to detect
+    // truncation, so `result.rowCount` is one MORE than what we return --
+    // consumers saw rowCount=1001 next to 1000 rows. Report what's in `rows`.
+    //
+    // The direct-exec path must NOT be rewritten. There `rowCount` is the
+    // affected-row count, which is independent of how many rows came back:
+    // `INSERT ... RETURNING` is non-cursorable (DECLARE rejects it with
+    // 42601), so a 10-row insert truncated to 3 must still report 10 rows
+    // affected. Collapsing it to rows.length told the caller 3 rows were
+    // written when 10 were committed.
+    rowCount: truncated && viaCursor ? rows.length : result.rowCount,
     fields: result.fields.map((f) => {
       const name = typeNames[f.dataTypeID];
       return name !== void 0 ? { name: f.name, dataTypeID: f.dataTypeID, dataTypeName: name } : { name: f.name, dataTypeID: f.dataTypeID };
     }),
-    command: result.command,
+    // See QueryResult.command -- omitted on the cursor path because the tag
+    // there describes the FETCH, not the user's statement.
+    ...viaCursor ? {} : { command: result.command },
     ...truncated ? { truncated: true } : {}
   };
 }
@@ -36234,10 +36252,10 @@ async function runReadOnly(sql, params = [], hooks = {}) {
   try {
     await client.query("BEGIN READ ONLY");
     if (hooks.setup) await hooks.setup(client);
-    const result = await runUserQueryBounded(client, sql, params, maxRows);
+    const { result, viaCursor } = await runUserQueryBounded(client, sql, params, maxRows);
     await client.query("ROLLBACK");
     const typeNames = await safeResolveTypeNames(client, result.fields);
-    return { ok: true, data: toQueryResult(result, maxRows, typeNames) };
+    return { ok: true, data: toQueryResult(result, maxRows, typeNames, viaCursor) };
   } catch (err) {
     try {
       await client.query("ROLLBACK");
@@ -36265,10 +36283,10 @@ async function runReadWrite(sql, params = []) {
   const maxRows = getMaxRows();
   try {
     await client.query("BEGIN");
-    const result = await runUserQueryBounded(client, sql, params, maxRows);
+    const { result, viaCursor } = await runUserQueryBounded(client, sql, params, maxRows);
     await client.query("COMMIT");
     const typeNames = await safeResolveTypeNames(client, result.fields);
-    return { ok: true, data: toQueryResult(result, maxRows, typeNames) };
+    return { ok: true, data: toQueryResult(result, maxRows, typeNames, viaCursor) };
   } catch (err) {
     try {
       await client.query("ROLLBACK");
@@ -36291,10 +36309,10 @@ async function runReadWriteRollback(sql, params = [], hooks = {}) {
   try {
     await client.query("BEGIN");
     if (hooks.setup) await hooks.setup(client);
-    const result = await runUserQueryBounded(client, sql, params, maxRows);
+    const { result, viaCursor } = await runUserQueryBounded(client, sql, params, maxRows);
     await client.query("ROLLBACK");
     const typeNames = await safeResolveTypeNames(client, result.fields);
-    return { ok: true, data: toQueryResult(result, maxRows, typeNames) };
+    return { ok: true, data: toQueryResult(result, maxRows, typeNames, viaCursor) };
   } catch (err) {
     try {
       await client.query("ROLLBACK");
@@ -36445,7 +36463,7 @@ var adminTools = [
       limit: external_exports.number().int().min(1).max(100).default(50).describe("Max blocked/blocker pairs (default 50).")
     }),
     handler: async (input) => {
-      const { limit } = input;
+      const { limit = 50 } = input;
       return runInternal(
         `SELECT
            blocked.pid AS blocked_pid,
@@ -36519,7 +36537,7 @@ var adminTools = [
       includeSystem: external_exports.boolean().default(false).describe("If true, include built-in `pg_*` roles (pg_read_all_data, pg_monitor, etc.).")
     }),
     handler: async (input) => {
-      const { includeSystem } = input;
+      const { includeSystem = false } = input;
       const filter = includeSystem ? "" : "WHERE NOT starts_with(r.rolname, 'pg_')";
       return runInternal(
         // Cast member_of to text[] so node-pg parses it into a JS array.
@@ -36560,7 +36578,7 @@ var adminTools = [
       table: identSchema.optional().describe("Table name. Omit to list privileges for all tables in the schema.")
     }),
     handler: async (input) => {
-      const { schema, table } = input;
+      const { schema = "public", table } = input;
       const tableFilter = table ? "AND table_name = $2" : "";
       const params = [schema];
       if (table) params.push(table);
@@ -36593,7 +36611,7 @@ var adminTools = [
       mode: external_exports.enum(["cancel", "terminate"]).default("cancel").describe("`cancel` aborts the current query; `terminate` closes the connection entirely.")
     }),
     handler: async (input) => {
-      const { pid, mode } = input;
+      const { pid, mode = "cancel" } = input;
       if (!isWritesAllowed()) {
         return {
           ok: false,
@@ -36691,7 +36709,7 @@ var adminTools = [
   },
   {
     name: "pg_advisor",
-    description: "Rolled-up DBA lint pass. One call returns three categories of findings:\n- sequence_exhaustion: SERIAL / BIGSERIAL / IDENTITY sequences whose `last_value` is above `seqExhaustionThreshold` of `max_value`. The classic incident class.\n- tables_without_primary_key: user tables with no PK. Bloat candidates and a sign of design drift; some replication setups also need PKs.\n- public_tables_without_rls: tables in `public` (or any schema in `rlsSchemas`) with row-level security disabled. Useful as a security baseline check.\nUse this as the 'what should I be looking at?' starting point, then drill into `pg_unused_indexes`, `pg_table_bloat`, `pg_seq_scan_tables` for the perf side.",
+    description: "Rolled-up DBA lint pass. One call returns three categories of findings:\n- sequence_exhaustion: SERIAL / BIGSERIAL / IDENTITY sequences whose `last_value` is above `seqExhaustionThreshold` of `max_value`. The classic incident class.\n- tables_without_primary_key: user tables (plain and partitioned) with no PK defined. Bloat candidates and a sign of design drift; some replication setups also need PKs. Foreign tables are excluded -- PostgreSQL forbids declaring PKs on foreign tables.\n- public_tables_without_rls: tables in `public` (or any schema in `rlsSchemas`) with row-level security disabled. Useful as a security baseline check.\nUse this as the 'what should I be looking at?' starting point, then drill into `pg_unused_indexes`, `pg_table_bloat`, `pg_seq_scan_tables` for the perf side.",
     annotations: {
       title: "Database advisor (DBA lints)",
       readOnlyHint: true,
@@ -36705,7 +36723,11 @@ var adminTools = [
       limit: external_exports.number().int().min(1).max(500).default(50).describe("Max rows per category (default 50).")
     }),
     handler: async (input) => {
-      const { seqExhaustionThreshold, rlsSchemas, limit } = input;
+      const {
+        seqExhaustionThreshold = 0.5,
+        rlsSchemas = ["public"],
+        limit = 50
+      } = input;
       return withSharedClient(async (run) => {
         const [seqRes, noPkRes, rlsRes] = await Promise.all([
           run(
@@ -36744,6 +36766,10 @@ var adminTools = [
             // Partition children (relkind='r') inherit the parent's PK as an
             // indisprimary index on the child, so the NOT EXISTS clause keeps
             // already filtering them out.
+            //
+            // Foreign tables (relkind='f') are excluded: PostgreSQL forbids
+            // PRIMARY KEY (and UNIQUE) constraints on foreign tables entirely,
+            // so they would always appear here with no possible remediation.
             `SELECT
                n.nspname AS schema,
                c.relname AS "table"
@@ -36792,7 +36818,7 @@ var adminTools = [
   },
   {
     name: "pg_table_bloat",
-    description: "Estimate table bloat (dead tuples + free space) for tables in a schema. Returns live tuples, dead tuples, dead-tuple ratio, last_vacuum / last_autovacuum timestamps, and total relation size. A high dead_ratio with a stale last_autovacuum is a sign a table needs VACUUM. Cheap - uses `pg_stat_user_tables`, no extensions required.",
+    description: "Estimate table bloat (dead tuples + free space) for tables in a schema. Returns live tuples, dead tuples, dead-tuple ratio, last_vacuum / last_autovacuum timestamps, and total relation size. A high dead_ratio with a stale last_autovacuum is a sign a table needs VACUUM.\n\nThree methods are available via the `method` parameter:\n- `estimate` (default): reads pg_stat_user_tables -- fast, no extensions, ANALYZE-driven approximations. Use this first.\n- `approx`: uses pgstattuple_approx() -- fast sampling pass, more accurate than estimates, requires the pgstattuple extension.\n- `exact`: uses pgstattuple() -- full table scan, exact counts, slow on large tables, requires the pgstattuple extension. Always pass `schema` with method='exact' -- scanning all user tables in one statement will hit statement_timeout on non-trivial databases.\nInstall pgstattuple with `CREATE EXTENSION pgstattuple` (requires superuser).",
     annotations: {
       title: "Estimate table bloat",
       readOnlyHint: true,
@@ -36803,13 +36829,59 @@ var adminTools = [
     inputSchema: external_exports.object({
       schema: identSchema.optional().describe("Limit to one schema. If omitted, all user schemas are included."),
       minDeadRatio: external_exports.number().min(0).max(1).default(0.1).describe("Minimum dead-tuple fraction to include - dead / (live + dead). Default 0.1 = 10%."),
-      limit: external_exports.number().int().min(1).max(200).default(50).describe("Max rows to return (default 50).")
+      limit: external_exports.number().int().min(1).max(200).default(50).describe("Max rows to return (default 50)."),
+      method: external_exports.enum(["estimate", "approx", "exact"]).default("estimate").describe(
+        "Bloat measurement method. 'estimate' (default) uses pg_stat_user_tables (fast, no extensions). 'approx' uses pgstattuple_approx() (fast sampling, more accurate). 'exact' uses pgstattuple() (full scan, exact but slow). Both 'approx' and 'exact' require the pgstattuple extension."
+      )
     }),
     handler: async (input) => {
-      const { schema, minDeadRatio, limit } = input;
+      const {
+        schema,
+        minDeadRatio = 0.1,
+        limit = 50,
+        method = "estimate"
+      } = input;
       const schemaFilter = schema ? "AND schemaname = $3" : "AND schemaname NOT IN ('pg_catalog', 'information_schema') AND schemaname NOT LIKE 'pg_%'";
       const params = [minDeadRatio, limit];
       if (schema) params.push(schema);
+      if (method !== "estimate") {
+        const check2 = await runInternal(
+          `SELECT EXISTS (
+             SELECT 1 FROM pg_catalog.pg_extension WHERE extname = 'pgstattuple'
+           ) AS installed`
+        );
+        if (!check2.ok) return check2;
+        if (!check2.data?.[0]?.installed) {
+          return {
+            ok: false,
+            error: `pgstattuple extension is not installed. Install with \`CREATE EXTENSION pgstattuple;\` (requires superuser), then retry with method='${method}'.`
+          };
+        }
+        const fn = method === "approx" ? "pgstattuple_approx" : "pgstattuple";
+        const liveTuplesCol = method === "approx" ? "approx_tuple_count" : "tuple_count";
+        return runInternal(
+          `SELECT
+             s.schemaname AS schema,
+             s.relname AS "table",
+             (p.${liveTuplesCol})::text AS live_tuples,
+             p.dead_tuple_count::text AS dead_tuples,
+             (p.dead_tuple_count::float8 / NULLIF(p.${liveTuplesCol} + p.dead_tuple_count, 0))::numeric(6, 3)::float8 AS dead_ratio,
+             pg_size_pretty(pg_total_relation_size(s.relid)) AS size_pretty,
+             pg_total_relation_size(s.relid)::text AS size_bytes,
+             s.last_vacuum::text AS last_vacuum,
+             s.last_autovacuum::text AS last_autovacuum,
+             s.last_analyze::text AS last_analyze
+           FROM pg_catalog.pg_stat_user_tables s
+           JOIN pg_catalog.pg_class c ON c.oid = s.relid AND c.relkind IN ('r', 'm')
+           CROSS JOIN LATERAL ${fn}(s.relid::regclass) p
+           WHERE (p.${liveTuplesCol} + p.dead_tuple_count) > 0
+             AND (p.dead_tuple_count::float8 / NULLIF(p.${liveTuplesCol} + p.dead_tuple_count, 0)) >= $1
+             ${schemaFilter}
+           ORDER BY p.dead_tuple_count DESC
+           LIMIT $2`,
+          params
+        );
+      }
       return runInternal(
         // dead_ratio = dead / (live + dead): bounded [0, 1]. A 100%-dead table
         // (live=0, dead>0) correctly reports 1.0 instead of 0. Tables with both
@@ -36855,14 +36927,14 @@ function quoteQualifiedTable(name) {
   return name.split(".").map((p) => quoteIdent(p)).join(".");
 }
 function validateHypoIndex(idx) {
+  if (idx.table.includes('"')) {
+    return `Hypothetical index table ${JSON.stringify(idx.table)} contains a double-quote; pass plain identifier names without pre-quoting.`;
+  }
   const pieces = idx.table.split(".");
   if (pieces.length > 2) {
     return `Hypothetical index table ${JSON.stringify(idx.table)} is over-qualified; use only \`schema.table\` or \`table\`.`;
   }
   for (const piece of pieces) {
-    if (piece.includes('"')) {
-      return `Hypothetical index table ${JSON.stringify(idx.table)} contains a double-quote; pass plain identifier names without pre-quoting.`;
-    }
     if (Buffer.byteLength(piece, "utf8") > 63) {
       return `Hypothetical index table piece ${JSON.stringify(piece)} exceeds PostgreSQL's 63-byte NAMEDATALEN limit (multi-byte characters count as multiple bytes).`;
     }
@@ -36922,13 +36994,11 @@ var explainTools = [
     handler: async (input) => {
       const {
         sql,
-        analyze: rawAnalyze,
-        format: rawFormat,
+        analyze = false,
+        format = "text",
         params,
         hypothetical_indexes
       } = input;
-      const analyze = rawAnalyze ?? false;
-      const format = rawFormat ?? "text";
       if (/^\s*EXPLAIN\b/i.test(sql)) {
         return {
           ok: false,
@@ -36995,7 +37065,7 @@ var healthTools = [
       activeQueryLimit: external_exports.number().int().min(1).max(100).default(10).describe("Max active queries to return (default 10, max 100).")
     }),
     handler: async (input) => {
-      const { activeQueryLimit } = input;
+      const { activeQueryLimit = 10 } = input;
       return withSharedClient(async (run) => {
         const [versionRes, sizeRes, connsRes, activeRes, tableCountRes] = await Promise.all([
           run(`SELECT version() AS version`),
@@ -37070,7 +37140,18 @@ var healthTools = [
 var queryTools = [
   {
     name: "pg_readonly",
-    description: "Run a SQL statement guaranteed read-only. Always executes inside a `BEGIN READ ONLY` transaction regardless of `ALLOW_WRITES`, so postgres itself rejects any write attempt. Use this whenever the goal is to read - SELECT, EXPLAIN, SHOW, VALUES, WITH ... SELECT, etc. Hosts that gate tools individually (Claude Code permissions, mcp.hosting) can safely auto-allow this one. Use `params` for parameterized queries to avoid SQL injection. Params can be strings, numbers, booleans, null, arrays (for postgres arrays / ANY), or objects (for json/jsonb columns). Large result sets are truncated to POSTGRES_MAX_ROWS (default 1000) with a `truncated: true` flag.",
+    description: "Run a SQL statement with no persistent data changes. Always executes inside a `BEGIN READ ONLY` transaction regardless of `ALLOW_WRITES`, so postgres itself rejects any INSERT/UPDATE/DELETE/DDL and the transaction is always rolled back. Use this whenever the goal is to read - SELECT, EXPLAIN, SHOW, VALUES, WITH ... SELECT, etc. Scope caveat for hosts that auto-allow this tool: `READ ONLY` constrains writes to the DATABASE, not every side effect. Functions whose effect is outside the table data - `pg_cancel_backend` / `pg_terminate_backend`, `pg_read_file`, `lo_export`, `COPY ... TO PROGRAM` - are NOT blocked here and are NOT behind the `ALLOW_WRITES` gate that `pg_kill` sits behind. They still require the privileges the `DATABASE_URL` role holds, so a least-privileged role (e.g. `pg_read_all_data`) is what actually bounds this tool. Use `params` for parameterized queries to avoid SQL injection. Params can be strings, numbers, booleans, null, arrays (for postgres arrays / ANY), or objects (for json/jsonb columns). Large result sets are truncated to POSTGRES_MAX_ROWS (default 1000) with a `truncated: true` flag.",
+    // DELIBERATE, do not "fix" to match the caveat in the description above.
+    // `BEGIN READ ONLY` does not block side-effecting functions
+    // (pg_terminate_backend, pg_read_file, COPY ... TO PROGRAM), so these
+    // hints are arguably too generous, and a review pass will keep noticing
+    // that. The decision is to keep them: staying in the host auto-allow class
+    // is the entire reason pg_readonly exists as a separate tool from
+    // pg_query, and the DATABASE_URL role -- not the transaction mode -- is
+    // the control that actually bounds this tool. The description and the
+    // README carry the caveat; a least-privileged role is the enforcement.
+    // Flipping these to destructive would move pg_readonly to "always prompt"
+    // in every existing host config for a bound the role already provides.
     annotations: {
       title: "Run read-only SQL",
       readOnlyHint: true,
@@ -37140,7 +37221,7 @@ var schemaTools = [
   },
   {
     name: "pg_list_tables",
-    description: "List tables (and optionally views) in a schema. Returns name, type (table/view/materialized view/foreign), and estimated row count (from `reltuples`; approximate - 0 until ANALYZE runs). Paginate via `limit`/`offset` on very large schemas.",
+    description: "List tables (and optionally views) in a schema. Returns name, type (table/view/materialized view/foreign), and estimated row count (from `reltuples`; null = no ANALYZE yet on PG 14+; 0 may mean empty or unanalyzed on PG <= 13). Paginate via `limit`/`offset` on very large schemas.",
     annotations: {
       title: "List tables in a schema",
       readOnlyHint: true,
@@ -37155,7 +37236,12 @@ var schemaTools = [
       offset: external_exports.number().int().min(0).default(0).describe("Rows to skip for pagination (default 0).")
     }),
     handler: async (input) => {
-      const { schema, includeViews, limit, offset } = input;
+      const {
+        schema = "public",
+        includeViews = false,
+        limit = 500,
+        offset = 0
+      } = input;
       const kinds = includeViews ? "('r', 'v', 'm', 'f', 'p')" : "('r', 'f', 'p')";
       return runInternal(
         `SELECT
@@ -37168,7 +37254,7 @@ var schemaTools = [
              WHEN 'p' THEN 'partitioned_table'
              ELSE c.relkind::text
            END AS type,
-           c.reltuples::bigint AS estimated_rows
+           NULLIF(round(c.reltuples), -1)::float8 AS estimated_rows
          FROM pg_catalog.pg_class c
          JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
          WHERE n.nspname = $1
@@ -37194,7 +37280,7 @@ var schemaTools = [
       table: identSchema.describe("Table name.")
     }),
     handler: async (input) => {
-      const { schema, table } = input;
+      const { schema = "public", table } = input;
       const kindQuery = `
         SELECT
           CASE c.relkind
@@ -37231,11 +37317,12 @@ var schemaTools = [
         FROM pg_catalog.pg_index i
         JOIN pg_catalog.pg_class c ON c.oid = i.indrelid
         JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
-        JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(i.indkey)
+        JOIN LATERAL unnest(i.indkey[0:i.indnkeyatts - 1]) WITH ORDINALITY AS k(attnum, ord) ON TRUE
+        JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid AND a.attnum = k.attnum
         WHERE n.nspname = $1
           AND c.relname = $2
           AND i.indisprimary
-        ORDER BY array_position(i.indkey, a.attnum)
+        ORDER BY k.ord
       `;
       const foreignKeysQuery = `
         SELECT
@@ -37415,7 +37502,7 @@ var schemaTools = [
       includeMaterialized: external_exports.boolean().default(true).describe("If true, include materialized views.")
     }),
     handler: async (input) => {
-      const { schema, includeMaterialized } = input;
+      const { schema = "public", includeMaterialized = true } = input;
       const kinds = includeMaterialized ? "('v', 'm')" : "('v')";
       return runInternal(
         `SELECT
@@ -37445,7 +37532,7 @@ var schemaTools = [
       schema: identSchema.default("public").describe("Schema name (defaults to 'public').")
     }),
     handler: async (input) => {
-      const { schema } = input;
+      const { schema = "public" } = input;
       return runInternal(
         `SELECT
            p.proname AS name,
@@ -37509,7 +37596,7 @@ var schemaTools = [
       limit: external_exports.number().int().min(1).max(1e3).default(100).describe("Max rows to return (default 100).")
     }),
     handler: async (input) => {
-      const { pattern, schema, limit } = input;
+      const { pattern, schema, limit = 100 } = input;
       const schemaFilter = schema ? "AND n.nspname = $3" : "AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'";
       const params = [pattern, limit];
       if (schema) params.push(schema);
@@ -37540,7 +37627,7 @@ var schemaTools = [
 var statsTools = [
   {
     name: "pg_top_queries",
-    description: "Top N queries by total or mean execution time. Requires the `pg_stat_statements` extension to be installed and enabled (most managed Postgres providers have it on by default). Returns normalized query text (constants replaced with `?`), call count, total/mean/min/max time in ms, rows returned, and cache hit ratio. Use this to find slow queries worth optimizing.",
+    description: "Top N queries by total or mean execution time. Requires the `pg_stat_statements` extension to be installed and enabled (most managed Postgres providers have it on by default). Returns normalized query text (constants replaced with `?`), call count, total/mean/min/max time in ms, rows returned, and cache hit ratio. Use this to find slow queries worth optimizing. On pg_stat_statements >= 1.10 (Postgres 15+), also returns `io_read_time_ms` and `io_write_time_ms` to separate IO-bound from CPU-bound queries (null when track_io_timing = off or the query did no measurable IO -- enable track_io_timing in postgresql.conf to get non-null values). Scoped to the database in DATABASE_URL: pg_stat_statements is cluster-wide, so results are filtered by `dbid` to match every other tool here rather than leaking query text from unrelated databases sharing the cluster.",
     annotations: {
       title: "Top queries by execution time",
       readOnlyHint: true,
@@ -37553,7 +37640,7 @@ var statsTools = [
       limit: external_exports.number().int().min(1).max(100).default(20).describe("Number of rows to return (default 20).")
     }),
     handler: async (input) => {
-      const { orderBy, limit } = input;
+      const { orderBy = "total_time", limit = 20 } = input;
       const versionRes = await runInternal(
         `SELECT extversion AS version FROM pg_catalog.pg_extension WHERE extname = 'pg_stat_statements'`
       );
@@ -37570,6 +37657,11 @@ var statsTools = [
       const meanCol = useExecSuffix ? "mean_exec_time" : "mean_time";
       const minCol = useExecSuffix ? "min_exec_time" : "min_time";
       const maxCol = useExecSuffix ? "max_exec_time" : "max_time";
+      const hasIoTiming = compareVersions(extVersion, "1.10") >= 0;
+      const hasSharedBlkCols = compareVersions(extVersion, "1.11") >= 0;
+      const ioTimingCols = hasIoTiming ? `,
+           NULLIF(${hasSharedBlkCols ? "shared_blk_read_time" : "blk_read_time"}, 0)::numeric(18, 2)::float8 AS io_read_time_ms,
+           NULLIF(${hasSharedBlkCols ? "shared_blk_write_time" : "blk_write_time"}, 0)::numeric(18, 2)::float8 AS io_write_time_ms` : "";
       const orderCol = orderBy === "total_time" ? totalCol : orderBy === "mean_time" ? meanCol : "pg_stat_statements.calls";
       return runInternal(
         // bigint counters (calls, rows) come back as `.text` for lossless
@@ -37588,8 +37680,9 @@ var statsTools = [
              WHEN (shared_blks_hit + shared_blks_read) > 0
              THEN (shared_blks_hit::float8 / (shared_blks_hit + shared_blks_read) * 100)::numeric(5, 2)::float8
              ELSE NULL
-           END AS hit_percent
+           END AS hit_percent${ioTimingCols}
          FROM pg_stat_statements
+         WHERE dbid = (SELECT oid FROM pg_catalog.pg_database WHERE datname = current_database())
          ORDER BY ${orderCol} DESC NULLS LAST
          LIMIT $1`,
         [limit]
@@ -37612,7 +37705,11 @@ var statsTools = [
       limit: external_exports.number().int().min(1).max(100).default(20).describe("Max rows to return (default 20).")
     }),
     handler: async (input) => {
-      const { schema, minSize, limit } = input;
+      const {
+        schema,
+        minSize = 1e3,
+        limit = 20
+      } = input;
       const schemaFilter = schema ? "AND schemaname = $3" : "AND schemaname NOT IN ('pg_catalog', 'information_schema') AND schemaname NOT LIKE 'pg_%'";
       const params = [minSize, limit];
       if (schema) params.push(schema);
@@ -37653,7 +37750,11 @@ var statsTools = [
       limit: external_exports.number().int().min(1).max(200).default(50).describe("Max rows to return (default 50).")
     }),
     handler: async (input) => {
-      const { schema, maxScans, limit } = input;
+      const {
+        schema,
+        maxScans = 10,
+        limit = 50
+      } = input;
       const schemaFilter = schema ? "AND s.schemaname = $3" : "AND s.schemaname NOT IN ('pg_catalog', 'information_schema') AND s.schemaname NOT LIKE 'pg_%'";
       const params = [maxScans, limit];
       if (schema) params.push(schema);
@@ -37695,12 +37796,25 @@ function compareVersions(a, b) {
 }
 
 // src/index.ts
-var version2 = true ? "0.6.20" : await readPackageVersion();
+var version2 = true ? "0.8.0" : await readPackageVersion();
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
   process.exit(0);
 }
+if (subcommand !== void 0 && !subcommand.startsWith("-")) {
+  const looksLikeDsn = /^postgres(ql)?:\/\//i.test(subcommand);
+  const message = looksLikeDsn ? `postgres-mcp: connection strings are not accepted as an argument.
+Set DATABASE_URL in the MCP server env instead:
+  "env": { "DATABASE_URL": "postgres://..." }
+` : `postgres-mcp: unknown subcommand '${subcommand}'
+Usage:
+  postgres-mcp            start the MCP server on stdio
+  postgres-mcp version    print the version and exit
+`;
+  writeSync(2, message);
+  process.exit(1);
+}
 var allTools = [...queryTools, ...schemaTools, ...explainTools, ...healthTools, ...statsTools, ...adminTools];
 var server = new McpServer({
   name: "@yawlabs/postgres-mcp",
@@ -37716,9 +37830,14 @@ for (const tool of allTools) {
   );
 }
 var transport = new StdioServerTransport();
-await server.connect(transport);
-var writesNote = isWritesAllowed() ? "writes ENABLED" : "read-only";
-console.error(`@yawlabs/postgres-mcp v${version2} ready (${allTools.length} tools, ${writesNote})`);
+server.connect(transport).then(() => {
+  const writesNote = isWritesAllowed() ? "writes ENABLED" : "read-only";
+  console.error(`@yawlabs/postgres-mcp v${version2} ready (${allTools.length} tools, ${writesNote})`);
+}).catch((err) => {
+  process.stderr.write(`postgres-mcp: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});
 var exiting = false;
 var cleanup = async () => {
   if (exiting) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/postgres-mcp",
-  "version": "0.6.20",
+  "version": "0.8.0",
   "mcpName": "io.github.YawLabs/postgres-mcp",
   "description": "PostgreSQL MCP server - query, schema introspection, explain, and health checks for AI assistants",
   "license": "MIT",
@@ -54,6 +54,7 @@
     "@types/pg": "^8.20.0",
     "esbuild": "^0.28.0",
     "pg": "^8.14.0",
+    "postject": "^1.0.0-alpha.6",
     "typescript": "^6.0.3",
     "zod": "^4.3.6"
   },