@yawlabs/postgres-mcp 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-04
+
+### Changed
+- **BREAKING:** `engines.node` raised from `>=18` to `>=20`. The CI matrix
+  has been on `[20, 22]` since 0.4.1 and the integration + release jobs
+  ran exclusively on Node 20+, so Node 18 was effectively unsupported in
+  practice; this release makes the declared support match. esbuild
+  `target` and `release.sh` prerequisite comment updated to match.
+
+## [0.4.1] - 2026-05-04
+
+### Changed
+- Multi-query handlers (`pg_describe_table`, `pg_health`, `pg_advisor`,
+  `pg_replication_status`) now share a single connection across their
+  internal catalog fan-out via a new `withSharedClient` helper, so one
+  tool call's 3-9 query fan-out can no longer saturate the pool (default
+  max 5) and starve concurrent calls. Previously, a single
+  `pg_describe_table` issued 9 parallel `Promise.all` queries against the
+  pool; under concurrent load this could block other tool calls until
+  the describe drained.
+- `pg_top_queries` now returns `calls` and `rows` as text strings,
+  matching the bigint serialization of `pg_seq_scan_tables`,
+  `pg_unused_indexes`, and `pg_table_bloat`. Timing fields stay as JSON
+  numbers since they are inherently fractional milliseconds.
+
+### Fixed
+- `runUserQueryBounded` now distinguishes "DECLARE failed" (re-running
+  on the direct-exec path is safe -- the user SQL never executed) from
+  "FETCH/CLOSE/RELEASE failed" (re-running could double-execute side
+  effects). Previously, a transient FETCH-time failure on a
+  RETURNING-DML statement would silently re-run the mutation.
+- `pg_top_queries` `orderBy: "calls"` now sorts numerically rather than
+  lexically. The 0.4.1 change to return `calls` as `text` shadowed the
+  source bigint column with a text output alias in the ORDER BY, so
+  "9" beat "10". The fix qualifies the ORDER BY expression with the
+  source table. Caught in the post-implementation review before tagging.
+- `pg_describe_table` "not found" error message now escapes user-supplied
+  schema/table names via `JSON.stringify`, so a name containing `"` no
+  longer renders as broken-looking nested quotes.
+- `pg_explain` `hypothetical_indexes` now pre-flight rejects pre-quoted
+  identifiers (`"odd.name"`, `weird"col`) with a clear validation error
+  before opening a database connection, instead of producing a confusing
+  planner error after the fact.
+
+### Added
+- New CI release plumbing mirroring `@yawlabs/tailscale-mcp`:
+  `.github/workflows/ci.yml` (lint + build + test on push/PR across
+  Node 18/20/22), `.github/workflows/integration.yml` (PG17 + PG18
+  service-container matrix, scheduled nightly + on-demand), and
+  `.github/workflows/release.yml` (tag-pushes-trigger-publish gated
+  on integration). `npm publish` now runs in CI with `--provenance`
+  via the org-level `NPM_TOKEN`; `release.sh` retains a local-dev
+  path that runs the WSL integration matrix as a pre-flight when
+  cutting a release from a workstation.
+- New regression tests:
+  - `compareVersions` unit tests covering pre-release tags,
+    missing/longer segments, and the actual `1.8` boundary used by
+    `pg_top_queries`.
+  - Integration guard that partition children inheriting a parent's
+    primary key are correctly excluded from `pg_advisor`'s
+    `tables_without_primary_key` list.
+  - Integration coverage for the cursor-fallback path on both DDL
+    (`CREATE TABLE`) and DML-without-RETURNING (`INSERT`).
+
 ## [0.4.0] - 2026-04-25
 
 ### Security

package/dist/index.js

@@ -35340,12 +35340,14 @@ function formatPgError(err) {
 }
 async function runUserQueryBounded(client, sql, params, maxRows) {
   await client.query("SAVEPOINT __pgmcp_sp");
+  let declareSucceeded = false;
   try {
     await client.query({
       text: `DECLARE __pgmcp_cur NO SCROLL CURSOR FOR ${sql}`,
       values: params,
       queryMode: "extended"
     });
+    declareSucceeded = true;
     const fetched = await client.query(`FETCH ${maxRows + 1} FROM __pgmcp_cur`);
     try {
       await client.query("CLOSE __pgmcp_cur");
@@ -35353,7 +35355,10 @@ async function runUserQueryBounded(client, sql, params, maxRows) {
     }
     await client.query("RELEASE SAVEPOINT __pgmcp_sp");
     return fetched;
-  } catch {
+  } catch (err) {
+    if (declareSucceeded) {
+      throw err;
+    }
     await client.query("ROLLBACK TO SAVEPOINT __pgmcp_sp");
     await client.query("RELEASE SAVEPOINT __pgmcp_sp");
     return client.query({
@@ -35468,6 +35473,22 @@ async function runInternal(sql, params = []) {
     return { ok: false, error: formatPgError(err) };
   }
 }
+async function withSharedClient(fn) {
+  const client = await getPool().connect();
+  try {
+    const runOnClient = async (sql, params = []) => {
+      try {
+        const result = await client.query(sql, params);
+        return { ok: true, data: result.rows };
+      } catch (err) {
+        return { ok: false, error: formatPgError(err) };
+      }
+    };
+    return await fn(runOnClient);
+  } finally {
+    client.release();
+  }
+}
 async function shutdown() {
   typeNameCache = null;
   if (!pool) return;
@@ -35652,49 +35673,51 @@ var adminTools = [
     },
     inputSchema: external_exports3.object({}),
     handler: async () => {
-      const [slotsRes, replicasRes, walRes] = await Promise.all([
-        runInternal(
-          `SELECT
-             slot_name, slot_type, active,
-             restart_lsn::text AS restart_lsn,
-             confirmed_flush_lsn::text AS confirmed_flush_lsn,
-             wal_status, database, plugin
-           FROM pg_catalog.pg_replication_slots
-           ORDER BY slot_name`
-        ),
-        runInternal(
-          `SELECT
-             application_name,
-             client_addr::text AS client_addr,
-             state,
-             sync_state,
-             EXTRACT(EPOCH FROM write_lag)::numeric(10, 2)::float8 AS write_lag_seconds,
-             EXTRACT(EPOCH FROM flush_lag)::numeric(10, 2)::float8 AS flush_lag_seconds,
-             EXTRACT(EPOCH FROM replay_lag)::numeric(10, 2)::float8 AS replay_lag_seconds
-           FROM pg_catalog.pg_stat_replication
-           ORDER BY application_name`
-        ),
-        runInternal(
-          `SELECT
-             pg_is_in_recovery() AS is_in_recovery,
-             CASE
-               WHEN pg_is_in_recovery() THEN pg_last_wal_receive_lsn()::text
-               ELSE pg_current_wal_lsn()::text
-             END AS wal_position`
-        )
-      ]);
-      if (!slotsRes.ok) return slotsRes;
-      if (!replicasRes.ok) return replicasRes;
-      if (!walRes.ok) return walRes;
-      return {
-        ok: true,
-        data: {
-          is_replica: walRes.data?.[0]?.is_in_recovery ?? false,
-          wal_position: walRes.data?.[0]?.wal_position ?? null,
-          slots: slotsRes.data ?? [],
-          replicas: replicasRes.data ?? []
-        }
-      };
+      return withSharedClient(async (run) => {
+        const [slotsRes, replicasRes, walRes] = await Promise.all([
+          run(
+            `SELECT
+               slot_name, slot_type, active,
+               restart_lsn::text AS restart_lsn,
+               confirmed_flush_lsn::text AS confirmed_flush_lsn,
+               wal_status, database, plugin
+             FROM pg_catalog.pg_replication_slots
+             ORDER BY slot_name`
+          ),
+          run(
+            `SELECT
+               application_name,
+               client_addr::text AS client_addr,
+               state,
+               sync_state,
+               EXTRACT(EPOCH FROM write_lag)::numeric(10, 2)::float8 AS write_lag_seconds,
+               EXTRACT(EPOCH FROM flush_lag)::numeric(10, 2)::float8 AS flush_lag_seconds,
+               EXTRACT(EPOCH FROM replay_lag)::numeric(10, 2)::float8 AS replay_lag_seconds
+             FROM pg_catalog.pg_stat_replication
+             ORDER BY application_name`
+          ),
+          run(
+            `SELECT
+               pg_is_in_recovery() AS is_in_recovery,
+               CASE
+                 WHEN pg_is_in_recovery() THEN pg_last_wal_receive_lsn()::text
+                 ELSE pg_current_wal_lsn()::text
+               END AS wal_position`
+          )
+        ]);
+        if (!slotsRes.ok) return slotsRes;
+        if (!replicasRes.ok) return replicasRes;
+        if (!walRes.ok) return walRes;
+        return {
+          ok: true,
+          data: {
+            is_replica: walRes.data?.[0]?.is_in_recovery ?? false,
+            wal_position: walRes.data?.[0]?.wal_position ?? null,
+            slots: slotsRes.data ?? [],
+            replicas: replicasRes.data ?? []
+          }
+        };
+      });
     }
   },
   {
@@ -35714,68 +35737,73 @@ var adminTools = [
     }),
     handler: async (input) => {
       const { seqExhaustionThreshold, rlsSchemas, limit } = input;
-      const [seqRes, noPkRes, rlsRes] = await Promise.all([
-        runInternal(
-          // pg_sequences was added in PG10. last_value can be NULL on a never-
-          // touched sequence; we filter those out (nothing to report yet).
-          `SELECT
-             schemaname AS schema,
-             sequencename AS sequence,
-             last_value::text AS last_value,
-             max_value::text AS max_value,
-             (last_value::float8 / NULLIF(max_value::float8, 0))::numeric(6, 4)::float8 AS pct_used
-           FROM pg_catalog.pg_sequences
-           WHERE last_value IS NOT NULL
-             AND max_value > 0
-             AND (last_value::float8 / max_value::float8) >= $1
-           ORDER BY pct_used DESC NULLS LAST
-           LIMIT $2`,
-          [seqExhaustionThreshold, limit]
-        ),
-        runInternal(
-          `SELECT
-             n.nspname AS schema,
-             c.relname AS "table"
-           FROM pg_catalog.pg_class c
-           JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
-           WHERE c.relkind = 'r'
-             AND n.nspname NOT IN ('pg_catalog', 'information_schema')
-             AND n.nspname NOT LIKE 'pg_%'
-             AND NOT EXISTS (
-               SELECT 1 FROM pg_catalog.pg_index i
-               WHERE i.indrelid = c.oid AND i.indisprimary
-             )
-           ORDER BY n.nspname, c.relname
-           LIMIT $1`,
-          [limit]
-        ),
-        runInternal(
-          `SELECT
-             n.nspname AS schema,
-             c.relname AS "table"
-           FROM pg_catalog.pg_class c
-           JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
-           WHERE c.relkind IN ('r', 'p')
-             AND n.nspname = ANY($1)
-             AND NOT c.relrowsecurity
-           ORDER BY n.nspname, c.relname
-           LIMIT $2`,
-          [rlsSchemas, limit]
-        )
-      ]);
-      const warnings = [];
-      if (!seqRes.ok) warnings.push(`sequence_exhaustion fetch failed: ${seqRes.error}`);
-      if (!noPkRes.ok) warnings.push(`tables_without_primary_key fetch failed: ${noPkRes.error}`);
-      if (!rlsRes.ok) warnings.push(`public_tables_without_rls fetch failed: ${rlsRes.error}`);
-      return {
-        ok: true,
-        data: {
-          sequence_exhaustion: seqRes.ok ? seqRes.data : [],
-          tables_without_primary_key: noPkRes.ok ? noPkRes.data : [],
-          public_tables_without_rls: rlsRes.ok ? rlsRes.data : [],
-          ...warnings.length > 0 ? { _warnings: warnings } : {}
-        }
-      };
+      return withSharedClient(async (run) => {
+        const [seqRes, noPkRes, rlsRes] = await Promise.all([
+          run(
+            // pg_sequences was added in PG10. last_value can be NULL on a never-
+            // touched sequence; we filter those out (nothing to report yet).
+            `SELECT
+               schemaname AS schema,
+               sequencename AS sequence,
+               last_value::text AS last_value,
+               max_value::text AS max_value,
+               (last_value::float8 / NULLIF(max_value::float8, 0))::numeric(6, 4)::float8 AS pct_used
+             FROM pg_catalog.pg_sequences
+             WHERE last_value IS NOT NULL
+               AND max_value > 0
+               AND (last_value::float8 / max_value::float8) >= $1
+             ORDER BY pct_used DESC NULLS LAST
+             LIMIT $2`,
+            [seqExhaustionThreshold, limit]
+          ),
+          run(
+            // Declarative-partition children inherit the parent's primary key
+            // as an indisprimary index, so the NOT EXISTS clause already
+            // excludes them. Nothing extra needed for partitioned schemas.
+            `SELECT
+               n.nspname AS schema,
+               c.relname AS "table"
+             FROM pg_catalog.pg_class c
+             JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+             WHERE c.relkind = 'r'
+               AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+               AND n.nspname NOT LIKE 'pg_%'
+               AND NOT EXISTS (
+                 SELECT 1 FROM pg_catalog.pg_index i
+                 WHERE i.indrelid = c.oid AND i.indisprimary
+               )
+             ORDER BY n.nspname, c.relname
+             LIMIT $1`,
+            [limit]
+          ),
+          run(
+            `SELECT
+               n.nspname AS schema,
+               c.relname AS "table"
+             FROM pg_catalog.pg_class c
+             JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+             WHERE c.relkind IN ('r', 'p')
+               AND n.nspname = ANY($1)
+               AND NOT c.relrowsecurity
+             ORDER BY n.nspname, c.relname
+             LIMIT $2`,
+            [rlsSchemas, limit]
+          )
+        ]);
+        const warnings = [];
+        if (!seqRes.ok) warnings.push(`sequence_exhaustion fetch failed: ${seqRes.error}`);
+        if (!noPkRes.ok) warnings.push(`tables_without_primary_key fetch failed: ${noPkRes.error}`);
+        if (!rlsRes.ok) warnings.push(`public_tables_without_rls fetch failed: ${rlsRes.error}`);
+        return {
+          ok: true,
+          data: {
+            sequence_exhaustion: seqRes.ok ? seqRes.data : [],
+            tables_without_primary_key: noPkRes.ok ? noPkRes.data : [],
+            public_tables_without_rls: rlsRes.ok ? rlsRes.data : [],
+            ...warnings.length > 0 ? { _warnings: warnings } : {}
+          }
+        };
+      });
     }
   },
   {
@@ -35843,6 +35871,19 @@ function quoteIdent(name) {
 function quoteQualifiedTable(name) {
   return name.split(".").map((p) => quoteIdent(p)).join(".");
 }
+function validateHypoIndex(idx) {
+  for (const piece of idx.table.split(".")) {
+    if (piece.includes('"')) {
+      return `Hypothetical index table ${JSON.stringify(idx.table)} contains a double-quote; pass plain identifier names without pre-quoting.`;
+    }
+  }
+  for (const col of idx.columns) {
+    if (col.includes('"')) {
+      return `Hypothetical index column ${JSON.stringify(col)} contains a double-quote; pass plain identifier names without pre-quoting.`;
+    }
+  }
+  return null;
+}
 function buildHypopgHooks(indexes) {
   return {
     setup: async (client) => {
@@ -35897,6 +35938,10 @@ var explainTools = [
       if (format === "json") flags.push("FORMAT JSON");
       const explainSql = flags.length > 0 ? `EXPLAIN (${flags.join(", ")}) ${sql}` : `EXPLAIN ${sql}`;
       const hypoIndexes = hypothetical_indexes ?? [];
+      for (const idx of hypoIndexes) {
+        const err = validateHypoIndex(idx);
+        if (err) return { ok: false, error: err };
+      }
       const hooks = hypoIndexes.length > 0 ? buildHypopgHooks(hypoIndexes) : {};
       if (hypoIndexes.length > 0) {
         const check2 = await runInternal(
@@ -35943,67 +35988,69 @@ var healthTools = [
     }),
     handler: async (input) => {
       const { activeQueryLimit } = input;
-      const [versionRes, sizeRes, connsRes, activeRes, tableCountRes] = await Promise.all([
-        runInternal(`SELECT version() AS version`),
-        runInternal(
-          `SELECT
-             current_database() AS database,
-             pg_size_pretty(pg_database_size(current_database())) AS size_pretty,
-             pg_database_size(current_database())::text AS size_bytes`
-        ),
-        runInternal(
-          `SELECT
-             count(*)::text AS total,
-             count(*) FILTER (WHERE state = 'active')::text AS active,
-             count(*) FILTER (WHERE state = 'idle')::text AS idle,
-             count(*) FILTER (WHERE state = 'idle in transaction')::text AS idle_in_transaction
-           FROM pg_stat_activity
-           WHERE datname = current_database()`
-        ),
-        runInternal(
-          `SELECT
-             pid,
-             state,
-             EXTRACT(EPOCH FROM (now() - query_start))::numeric(10, 2)::float8 AS duration_seconds,
-             query,
-             application_name
-           FROM pg_stat_activity
-           WHERE datname = current_database()
-             AND state IS NOT NULL
-             AND state <> 'idle'
-             AND pid <> pg_backend_pid()
-           ORDER BY query_start ASC NULLS LAST
-           LIMIT $1`,
-          [activeQueryLimit]
-        ),
-        runInternal(
-          `SELECT count(*)::text AS count
-           FROM pg_catalog.pg_class c
-           JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
-           WHERE c.relkind IN ('r', 'p')
-             AND n.nspname NOT IN ('pg_catalog', 'information_schema')
-             AND n.nspname NOT LIKE 'pg_toast%'
-             AND n.nspname NOT LIKE 'pg_temp_%'`
-        )
-      ]);
-      if (!versionRes.ok) return versionRes;
-      const warnings = [];
-      if (!sizeRes.ok) warnings.push(`database fetch failed: ${sizeRes.error}`);
-      if (!connsRes.ok) warnings.push(`connections fetch failed: ${connsRes.error}`);
-      if (!activeRes.ok) warnings.push(`active_queries fetch failed: ${activeRes.error}`);
-      if (!tableCountRes.ok) warnings.push(`table_count fetch failed: ${tableCountRes.error}`);
-      return {
-        ok: true,
-        data: {
-          connected: true,
-          version: versionRes.data?.[0]?.version,
-          database: sizeRes.ok ? sizeRes.data?.[0] : null,
-          connections: connsRes.ok ? connsRes.data?.[0] : null,
-          active_queries: activeRes.ok ? activeRes.data : [],
-          table_count: tableCountRes.ok ? tableCountRes.data?.[0]?.count : null,
-          ...warnings.length > 0 ? { _warnings: warnings } : {}
-        }
-      };
+      return withSharedClient(async (run) => {
+        const [versionRes, sizeRes, connsRes, activeRes, tableCountRes] = await Promise.all([
+          run(`SELECT version() AS version`),
+          run(
+            `SELECT
+               current_database() AS database,
+               pg_size_pretty(pg_database_size(current_database())) AS size_pretty,
+               pg_database_size(current_database())::text AS size_bytes`
+          ),
+          run(
+            `SELECT
+               count(*)::text AS total,
+               count(*) FILTER (WHERE state = 'active')::text AS active,
+               count(*) FILTER (WHERE state = 'idle')::text AS idle,
+               count(*) FILTER (WHERE state = 'idle in transaction')::text AS idle_in_transaction
+             FROM pg_stat_activity
+             WHERE datname = current_database()`
+          ),
+          run(
+            `SELECT
+               pid,
+               state,
+               EXTRACT(EPOCH FROM (now() - query_start))::numeric(10, 2)::float8 AS duration_seconds,
+               query,
+               application_name
+             FROM pg_stat_activity
+             WHERE datname = current_database()
+               AND state IS NOT NULL
+               AND state <> 'idle'
+               AND pid <> pg_backend_pid()
+             ORDER BY query_start ASC NULLS LAST
+             LIMIT $1`,
+            [activeQueryLimit]
+          ),
+          run(
+            `SELECT count(*)::text AS count
+             FROM pg_catalog.pg_class c
+             JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+             WHERE c.relkind IN ('r', 'p')
+               AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+               AND n.nspname NOT LIKE 'pg_toast%'
+               AND n.nspname NOT LIKE 'pg_temp_%'`
+          )
+        ]);
+        if (!versionRes.ok) return versionRes;
+        const warnings = [];
+        if (!sizeRes.ok) warnings.push(`database fetch failed: ${sizeRes.error}`);
+        if (!connsRes.ok) warnings.push(`connections fetch failed: ${connsRes.error}`);
+        if (!activeRes.ok) warnings.push(`active_queries fetch failed: ${activeRes.error}`);
+        if (!tableCountRes.ok) warnings.push(`table_count fetch failed: ${tableCountRes.error}`);
+        return {
+          ok: true,
+          data: {
+            connected: true,
+            version: versionRes.data?.[0]?.version,
+            database: sizeRes.ok ? sizeRes.data?.[0] : null,
+            connections: connsRes.ok ? connsRes.data?.[0] : null,
+            active_queries: activeRes.ok ? activeRes.data : [],
+            table_count: tableCountRes.ok ? tableCountRes.data?.[0]?.count : null,
+            ...warnings.length > 0 ? { _warnings: warnings } : {}
+          }
+        };
+      });
     }
   }
 ];
@@ -36265,48 +36312,53 @@ var schemaTools = [
           AND child.relispartition
         ORDER BY childn.nspname, child.relname
       `;
-      const [kindRes, cols, pk, fks, idxs, constraints, referencedBy, partitionParent, partitionChildren] = await Promise.all([
-        runInternal(kindQuery, [schema, table]),
-        runInternal(columnsQuery, [schema, table]),
-        runInternal(primaryKeyQuery, [schema, table]),
-        runInternal(foreignKeysQuery, [schema, table]),
-        runInternal(indexesQuery, [schema, table]),
-        runInternal(constraintsQuery, [schema, table]),
-        runInternal(referencedByQuery, [schema, table]),
-        runInternal(partitionParentQuery, [schema, table]),
-        runInternal(partitionChildrenQuery, [schema, table])
-      ]);
-      if (!cols.ok) return cols;
-      if (!cols.data || cols.data.length === 0) {
-        return { ok: false, error: `Table "${schema}"."${table}" not found.` };
-      }
-      const kind = kindRes.ok ? kindRes.data?.[0]?.kind ?? "table" : "table";
-      const warnings = [];
-      if (!pk.ok) warnings.push(`primary_key fetch failed: ${pk.error}`);
-      if (!fks.ok) warnings.push(`foreign_keys fetch failed: ${fks.error}`);
-      if (!idxs.ok) warnings.push(`indexes fetch failed: ${idxs.error}`);
-      if (!constraints.ok) warnings.push(`constraints fetch failed: ${constraints.error}`);
-      if (!referencedBy.ok) warnings.push(`referenced_by fetch failed: ${referencedBy.error}`);
-      if (!partitionParent.ok) warnings.push(`partition_of fetch failed: ${partitionParent.error}`);
-      if (!partitionChildren.ok) warnings.push(`partitions fetch failed: ${partitionChildren.error}`);
-      const parentRow = partitionParent.ok ? partitionParent.data?.[0] : void 0;
-      return {
-        ok: true,
-        data: {
-          schema,
-          table,
-          kind,
-          columns: cols.data,
-          primary_key: pk.ok ? (pk.data ?? []).map((r) => r.column_name) : [],
-          foreign_keys: fks.ok ? fks.data : [],
-          referenced_by: referencedBy.ok ? referencedBy.data : [],
-          constraints: constraints.ok ? constraints.data : [],
-          indexes: idxs.ok ? idxs.data : [],
-          ...parentRow ? { partition_of: parentRow } : {},
-          ...partitionChildren.ok && (partitionChildren.data ?? []).length > 0 ? { partitions: partitionChildren.data } : {},
-          ...warnings.length > 0 ? { _warnings: warnings } : {}
+      return withSharedClient(async (run) => {
+        const [kindRes, cols, pk, fks, idxs, constraints, referencedBy, partitionParent, partitionChildren] = await Promise.all([
+          run(kindQuery, [schema, table]),
+          run(columnsQuery, [schema, table]),
+          run(primaryKeyQuery, [schema, table]),
+          run(foreignKeysQuery, [schema, table]),
+          run(indexesQuery, [schema, table]),
+          run(constraintsQuery, [schema, table]),
+          run(referencedByQuery, [schema, table]),
+          run(partitionParentQuery, [schema, table]),
+          run(partitionChildrenQuery, [schema, table])
+        ]);
+        if (!cols.ok) return cols;
+        if (!cols.data || cols.data.length === 0) {
+          return {
+            ok: false,
+            error: `Table ${JSON.stringify(schema)}.${JSON.stringify(table)} not found.`
+          };
         }
-      };
+        const kind = kindRes.ok ? kindRes.data?.[0]?.kind ?? "table" : "table";
+        const warnings = [];
+        if (!pk.ok) warnings.push(`primary_key fetch failed: ${pk.error}`);
+        if (!fks.ok) warnings.push(`foreign_keys fetch failed: ${fks.error}`);
+        if (!idxs.ok) warnings.push(`indexes fetch failed: ${idxs.error}`);
+        if (!constraints.ok) warnings.push(`constraints fetch failed: ${constraints.error}`);
+        if (!referencedBy.ok) warnings.push(`referenced_by fetch failed: ${referencedBy.error}`);
+        if (!partitionParent.ok) warnings.push(`partition_of fetch failed: ${partitionParent.error}`);
+        if (!partitionChildren.ok) warnings.push(`partitions fetch failed: ${partitionChildren.error}`);
+        const parentRow = partitionParent.ok ? partitionParent.data?.[0] : void 0;
+        return {
+          ok: true,
+          data: {
+            schema,
+            table,
+            kind,
+            columns: cols.data,
+            primary_key: pk.ok ? (pk.data ?? []).map((r) => r.column_name) : [],
+            foreign_keys: fks.ok ? fks.data : [],
+            referenced_by: referencedBy.ok ? referencedBy.data : [],
+            constraints: constraints.ok ? constraints.data : [],
+            indexes: idxs.ok ? idxs.data : [],
+            ...parentRow ? { partition_of: parentRow } : {},
+            ...partitionChildren.ok && (partitionChildren.data ?? []).length > 0 ? { partitions: partitionChildren.data } : {},
+            ...warnings.length > 0 ? { _warnings: warnings } : {}
+          }
+        };
+      });
     }
   },
   {
@@ -36485,19 +36537,20 @@ 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 orderCol = orderBy === "total_time" ? totalCol : orderBy === "mean_time" ? meanCol : "calls";
+      const orderCol = orderBy === "total_time" ? totalCol : orderBy === "mean_time" ? meanCol : "pg_stat_statements.calls";
       return runInternal(
-        // calls and rows are bigint counters; cast to float8 so node-pg returns
-        // them as JS numbers (matches the timing fields). Precision is fine --
-        // 2^53 is ~9e15, well above any realistic call/row count.
+        // bigint counters (calls, rows) come back as `.text` for lossless
+        // serialization, matching pg_seq_scan_tables / pg_unused_indexes /
+        // pg_table_bloat. Timing fields stay as float8 because they are
+        // inherently fractional milliseconds.
         `SELECT
            query,
-           calls::float8 AS calls,
+           calls::text AS calls,
            ${totalCol}::numeric(18, 2)::float8 AS total_time_ms,
            ${meanCol}::numeric(18, 2)::float8 AS mean_time_ms,
            ${minCol}::numeric(18, 2)::float8 AS min_time_ms,
            ${maxCol}::numeric(18, 2)::float8 AS max_time_ms,
-           rows::float8 AS rows,
+           rows::text AS rows,
            CASE
              WHEN (shared_blks_hit + shared_blks_read) > 0
              THEN (shared_blks_hit::float8 / (shared_blks_hit + shared_blks_read) * 100)::numeric(5, 2)::float8
@@ -36594,7 +36647,10 @@ var statsTools = [
   }
 ];
 function compareVersions(a, b) {
-  const parse3 = (v) => v.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const parse3 = (v) => v.split(".").map((seg) => {
+    const m = seg.match(/^\d+/);
+    return m ? Number.parseInt(m[0], 10) : 0;
+  });
   const aa = parse3(a);
   const bb = parse3(b);
   const len = Math.max(aa.length, bb.length);
@@ -36606,7 +36662,7 @@ function compareVersions(a, b) {
 }
 
 // src/index.ts
-var version2 = true ? "0.4.0" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.5.0" : (await null).createRequire(import.meta.url)("../package.json").version;
 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.4.0",
+  "version": "0.5.0",
   "description": "PostgreSQL MCP server — query, schema introspection, explain, and health checks for AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",
@@ -57,6 +57,6 @@
     "zod": "^4.3.6"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   }
 }