@yawlabs/postgres-mcp 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-08
+
+### Added
+
+- **An opt-in `--permission` sandbox under oam**, via `POSTGRES_MCP_SANDBOX=1`.
+  The network grant is derived from `DATABASE_URL` at launch rather than
+  hardcoded, so the one endpoint the server may reach is the one it was
+  configured to reach. Host and port are both pinned, because oam matches grants
+  by prefix and a bare host would also admit every other port on it. Filesystem
+  and child-process are denied outright.
+
+  Opt-in rather than default because a wrong grant does not fail loudly: oam
+  denies a non-granted environment variable by making it **absent** from
+  `process.env` rather than throwing, so an under-granted `DATABASE_URL` would
+  read as "not configured" instead of "denied". The environment allow-list is
+  derived from what the shipped bundle actually reads, which is why it includes
+  the pg driver's own lookups (`PGSSLMODE`, `PGCONNECT_TIMEOUT` and friends) that
+  a hand-written list would have missed.
+
+### Changed
+
+- **oam 0.9.0 is now the minimum**, enforced in `bin/postgres-mcp.mjs`. Older
+  releases ran `child_process.execFile` arguments through a shell, accepted
+  `exec`'s `timeout` and ignored it, truncated `spawnSync` at `maxBuffer` while
+  reporting success, and treated `stdio: 'inherit'` as `'pipe'`. This server
+  spawns nothing, so the floor is enforced for consistency across
+  `@yawlabs/*-mcp` rather than because this launcher was exposed. An older oam is
+  not an error: the launcher falls back to Node and says so on stderr, and
+  `POSTGRES_MCP_RUNTIME=oam` turns that into a hard error.
+
+### Fixed
+
+- **`release.sh` aborted instead of releasing when `[Unreleased]` was empty.**
+  The body extraction pipes through `grep -v` to drop blank lines, and `grep`
+  exits non-zero when it matches nothing — so under `set -e` an empty section
+  killed the script at that line, and the `warn` branch written to handle
+  exactly that case could never run.
+
+## [0.9.1] - 2026-08-07
+
+### Fixed
+
+- **Corrected the runtime startup figures published in 0.9.0.** They were wrong
+  in both magnitude and direction, and the README used them to advise opting
+  out of the faster runtime.
+
+  The 0.9.0 numbers (Node ~650-900ms, oam ~980-1290ms, launcher-to-oam ~1.8s)
+  were measured against cold, freshly-built binaries. On Windows a binary that
+  is not in the on-access scanner's cache is rescanned on every exec, while
+  `node` resolved from PATH was cached long ago -- so the comparison measured
+  the scanner and put the entire penalty on the binary under test.
+
+  Re-measured on the same hardware with every binary warmed first, mean of 12
+  runs, `postgres-mcp version` (full module init):
+
+  | path | startup |
+  |---|---|
+  | standalone binary (`oam compile`) | 298ms |
+  | `oam run dist/index.js` | 306ms |
+  | `node dist/index.js` | 358ms |
+  | launcher -> Node (in-process) | 370ms |
+  | launcher -> oam (spawn) | 409ms |
+
+  oam starts faster than Node. What the launcher costs is the spawn: reaching
+  oam means Node has already booted, and that ~100ms hop outweighs oam's ~52ms
+  advantage, so the two land within ~40ms of each other through the npm `bin`.
+  `POSTGRES_MCP_RUNTIME=node` remains available but is now a marginal
+  difference, not the meaningful one 0.9.0 described.
+
+  No behavior changed -- `auto` (prefer oam) was and remains the default, and
+  it was the right default for the wrong stated reason. README, CHANGELOG, and
+  the launcher's header comment are corrected; the launcher comment also
+  records the measurement trap so the mistake is not repeated.
+
+## [0.9.0] - 2026-08-07
+
 ### Added
 
 - The `postgres-mcp` command is now a runtime launcher (`bin/postgres-mcp.mjs`)
@@ -31,11 +107,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a one-time cost per MCP session rather than per tool call, but it is a real
   regression against plain Node -- `POSTGRES_MCP_RUNTIME=node` opts out.
 
-> **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.
+  > **These figures are wrong. See 0.9.1.** They were measured against cold,
+  > freshly-built binaries and reflect the Windows on-access virus scanner, not
+  > either runtime. oam is in fact faster than Node here. Left in place rather
+  > than rewritten so the correction has something to point at.
+
+## [0.8.0] - 2026-08-07
 
 ### Changed (breaking)
 
@@ -130,6 +207,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (PG17), and with only 17/18 in the matrix the pre-1.11 branch was never
   selected.
 
+## [0.7.0] - 2026-07-21
+
+Backfilled from `git log v0.6.20..v0.7.0` -- this release shipped without a
+CHANGELOG entry. Summarized from commit subjects rather than re-derived from
+the diff, so it is less detailed than the entries around it.
+
+### Added
+
+- `pg_table_bloat`: `approx` and `exact` methods via `pgstattuple` (#19).
+- `pg_top_queries`: `io_read_time_ms` / `io_write_time_ms` on
+  `pg_stat_statements` >= 1.10 (#16).
+- Cross-platform single-binary release pipeline (Scoop + Homebrew), released
+  as 0.6.21.
+
+### Fixed
+
+- `pg_list_tables`: cast `reltuples` to `float8` so `estimated_rows` is a
+  number rather than a string (#17).
+- 10 confirmed findings from a review of `f7b7cb3..a736200` (#21).
+
+### Removed
+
+- GitHub Actions workflows and the dependabot config (#24). This is why the
+  repo has no `.github/` directory and why `release.sh` is the only release
+  path; several stale comments referring to CI survived until 0.8.0.
+
 ## [0.6.20] - 2026-06-04
 
 ### Fixed

package/README.md

@@ -213,7 +213,21 @@ The published `postgres-mcp` command is a small launcher that prefers the [oam](
 
 **If you do have oam,** the server runs under it. Verified equivalent on both runtimes: all 21 tools register, queries return identical rows and `dataTypeName` values, and the error paths match. oam supplies every `node:` builtin the driver needs, including `net`, `tls`, `crypto`, and `dns` (SCRAM auth and the extended query protocol both work).
 
-**Cost, stated plainly.** Taking the oam path means Node has already booted, so you pay both startups. Measured on windows-arm64 against the 1.4 MB bundle: Node alone ~650-900ms, oam alone ~980-1290ms, launcher-to-oam ~1.8s. This is a **one-time cost per MCP session**, not per tool call -- hosts spawn the server once and hold it open -- but if you care about launch latency, set `POSTGRES_MCP_RUNTIME=node`.
+**Startup cost, measured.** windows-arm64, 1.4 MB bundle, `postgres-mcp version` (full module init), every binary warmed first, mean of 12 runs:
+
+| path | startup |
+|---|---|
+| standalone binary (`oam compile`) | 298ms |
+| `oam run dist/index.js` | 306ms |
+| `node dist/index.js` | 358ms |
+| launcher -> Node (in-process) | 370ms |
+| launcher -> oam (spawn) | 409ms |
+
+oam starts **faster** than Node here. What the launcher costs is the *spawn*: reaching oam means Node has already booted, and that hop (~100ms) is larger than oam's ~52ms advantage. So through the npm `bin`, the two land within ~40ms of each other, and `POSTGRES_MCP_RUNTIME=node` is a marginal win rather than a meaningful one.
+
+Either way it is a **one-time cost per MCP session**, not per tool call -- hosts spawn the server once and hold it open. If startup genuinely matters, the standalone binary avoids the launcher entirely and is the fastest option.
+
+> Earlier releases of this README reported ~650-900ms for Node and ~980-1290ms for oam, and advised opting out of oam on that basis. Those figures were measured against cold, freshly-built binaries and reflected the Windows on-access virus scanner rather than either runtime. They were wrong in both magnitude and direction. Corrected in 0.9.1.
 
 ```jsonc
 {

package/bin/postgres-mcp.mjs

@@ -15,26 +15,66 @@
  * resolving a few paths (a handful of `existsSync` calls, no subprocess).
  *
  * WHAT THE OAM PATH COSTS
- * Taking the oam path means node has already booted, so the total is node's
- * startup plus oam's. Measured on windows-arm64 against the 1.4 MB bundle:
- * node alone ~650-900ms, oam alone ~980-1290ms, so the oam path lands near
- * ~1.8s. This is a ONE-TIME cost per MCP session, not per tool call -- hosts
- * spawn the server once and keep it -- but it is a real regression against
- * plain node and the reason `POSTGRES_MCP_RUNTIME=node` exists.
+ * The spawn, not the runtime. windows-arm64, 1.4 MB bundle, warmed binaries,
+ * mean of 12 runs: oam run 306ms, node 358ms -- oam is the FASTER of the two.
+ * But reaching oam from here means node has already booted, and that hop
+ * (~100ms) outweighs oam's ~52ms advantage: launcher -> node 370ms,
+ * launcher -> oam 409ms. So the two land within ~40ms through the npm bin.
+ * A one-time cost per MCP session either way, not per tool call.
+ *
+ * The `oam compile` standalone binary sidesteps this entirely (298ms, no
+ * launcher, no spawn) and is the right answer if startup actually matters.
+ *
+ * DO NOT re-measure this by timing a freshly built binary. On Windows a
+ * binary that is not in the on-access scanner's cache gets rescanned on every
+ * exec, while `node` from PATH was cached long ago -- the comparison then
+ * measures the scanner and dumps the whole penalty on the new binary. That
+ * mistake produced the numbers published in 0.9.0 (node ~650-900ms, oam
+ * ~980-1290ms), which were wrong in both magnitude and direction. Warm every
+ * candidate first, or stage it out of the build directory.
+ *
+ * THE `--permission` SANDBOX (oam 0.9.0+, opt-in)
+ * `POSTGRES_MCP_SANDBOX=1` runs the server under oam's permission model.
+ *
+ * The database host is not knowable ahead of time, so the net grant is DERIVED
+ * from DATABASE_URL at launch: the one endpoint this server may reach is the one
+ * it was configured to reach. Both host and port are pinned, because grants are
+ * prefix-matched and a bare host would also admit every other port on it.
+ * Filesystem and child-process stay denied.
+ *
+ * Opt-in, not default. A denied environment variable is ABSENT from process.env
+ * rather than throwing, so an under-granted DATABASE_URL would look like "not
+ * configured" instead of "denied". The env list is derived from the shipped
+ * bundle and includes the pg driver's own reads (PGSSLMODE, PGCONNECT_TIMEOUT
+ * and friends) -- a hand-written list misses those.
+ *
+ * MINIMUM OAM VERSION
+ * 0.9.0. Below it `child_process.execFile` ran its arguments through a SHELL,
+ * `exec` accepted `timeout` and ignored it, `spawnSync` truncated at
+ * `maxBuffer` while reporting success, and `stdio: 'inherit'`/`'ignore'` both
+ * behaved as `'pipe'`. This server spawns nothing, so the floor is
+ * enforced for consistency across @yawlabs/*-mcp rather than because this
+ * launcher was exposed.
+ * An older oam is not an error: the launcher falls back to Node and says so on
+ * stderr. Pinning the floor here is what makes that fallback automatic.
  *
  * SELECTION
  *   POSTGRES_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
  *   POSTGRES_MCP_RUNTIME=node   never use oam
  *   POSTGRES_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
+ *   POSTGRES_MCP_SANDBOX=1      run oam under --permission (oam 0.9.0+)
  *   OAM_BIN=/path/to/oam        explicit binary, checked before any discovery
  */
 
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { constants, homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** Oldest oam whose `child_process` matches Node. See MINIMUM OAM VERSION above. */
+const OAM_MIN = [0, 9, 0];
+
 // Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
 // with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
 // in-process fallback must use the file:// URL. spawn(), conversely, needs a
@@ -79,6 +119,72 @@ function findOam() {
   return null;
 }
 
+/**
+ * `oam --version` -> [major, minor, patch], or null when it cannot be read.
+ * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
+ */
+function oamVersion(cmd) {
+  try {
+    const out = execFileSync(cmd, ["--version"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(out);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  } catch {
+    // Not executable, wrong arch, or deleted since the stat. Caller degrades.
+    return null;
+  }
+}
+
+/** True when `v` is at least `min`, comparing major/minor/patch in order. */
+function atLeast(v, min) {
+  if (!v) return false;
+  for (let i = 0; i < min.length; i++) {
+    if (v[i] > min[i]) return true;
+    if (v[i] < min[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * The `--permission` grant list, or [] when the sandbox is not requested.
+ *
+ * These are oam's PROCESS-level flags: they belong before the `run` subcommand,
+ * not after it. `oam run --permission file.js` is rejected outright, which is a
+ * good failure but only because it is loud -- ordering here is load-bearing.
+ *
+ * Net grants prefix-match `host` for fetch and `host:port` for sockets.
+ * A denied environment variable is ABSENT from process.env rather than throwing,
+ * so the env list below is derived from what the bundle actually reads; trimming
+ * it produces silent misbehaviour, not a clear denial.
+ */
+function sandboxFlags() {
+  if (process.env.POSTGRES_MCP_SANDBOX !== "1") return [];
+
+  // Derived, not hardcoded: the only endpoint this server may reach is the one
+  // it was configured to reach. Grants are prefix-matched against "host:port"
+  // for sockets, so host alone would also admit any other port on that host --
+  // pin both. A DSN we cannot parse falls back to a bare grant rather than a
+  // broken one, because a wrong narrow grant fails at connect time.
+  const dsn = process.env.DATABASE_URL ?? null;
+  let netFlag = "--allow-net";
+  if (dsn) {
+    try {
+      const u = new URL(dsn);
+      if (u.hostname) netFlag = `--allow-net=${u.hostname}:${u.port || 5432}`;
+    } catch {
+      // Unparseable DATABASE_URL: leave the grant open. The server will fail on
+      // its own connection error, which names the real problem.
+    }
+  }
+
+  const env = ["ALLOW_WRITES","DATABASE_URL","NODE_PG_FORCE_NATIVE","PGCONNECT_TIMEOUT","PGSSLMODE","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;
+}
+
 /** Run the server in THIS process. The zero-overhead fallback. */
 async function runInProcess() {
   await import(SERVER_URL.href);
@@ -105,11 +211,30 @@ if (mode === "node") {
       process.exit(1);
     }
     await runInProcess();
+  } else if (!atLeast(oamVersion(oam), OAM_MIN)) {
+    // Discovery itself stays stat-only; this is the first subprocess, and it
+    // runs only once we have already decided to spawn oam anyway. Measured 26ms
+    // median (n=12, windows-arm64), paid once per MCP session.
+    const min = OAM_MIN.join(".");
+    if (mode === "oam") {
+      const { writeSync } = await import("node:fs");
+      writeSync(
+        2,
+        `postgres-mcp: POSTGRES_MCP_RUNTIME=oam but ${oam} is older than oam ${min}.\n` +
+          `Run \`oam self-update\`, or use POSTGRES_MCP_RUNTIME=node.\n`,
+      );
+      process.exit(1);
+    }
+    // auto: an old oam is a reason to prefer Node, not to fail. Say so, because
+    // a silent downgrade is how someone keeps running an oam they meant to
+    // update. stderr is safe -- MCP frames travel on stdout.
+    process.stderr.write(`postgres-mcp: oam at ${oam} is older than ${min}; using Node instead.\n`);
+    await runInProcess();
   } else {
     // `--` separates oam's own flags from the script's argv. Everything after
     // it lands in process.argv for the server, so `postgres-mcp version` and
     // any host-supplied flags survive the hop unchanged.
-    const child = spawn(oam, ["run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
+    const child = spawn(oam, [...sandboxFlags(), "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
       // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
       // stdin/stdout is untouched and the host's stdin-close still reaches the
       // server's shutdown path.

package/dist/index.js

@@ -37796,7 +37796,7 @@ function compareVersions(a, b) {
 }
 
 // src/index.ts
-var version2 = true ? "0.9.0" : await readPackageVersion();
+var version2 = true ? "0.10.0" : await readPackageVersion();
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/postgres-mcp",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "mcpName": "io.github.YawLabs/postgres-mcp",
   "description": "PostgreSQL MCP server - query, schema introspection, explain, and health checks for AI assistants",
   "license": "MIT",