@yawlabs/postgres-mcp 0.3.3 → 0.4.1

package/dist/index.js

@@ -35255,6 +35255,12 @@ function getStatementTimeoutMs() {
   const parsed = Number(raw);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : 3e4;
 }
+function getConnectionTimeoutMs() {
+  const raw = process.env.POSTGRES_CONNECTION_TIMEOUT_MS;
+  if (!raw) return 1e4;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 1e4;
+}
 function getMaxRows() {
   const raw = process.env.POSTGRES_MAX_ROWS;
   if (!raw) return 1e3;
@@ -35284,6 +35290,7 @@ function getPool() {
   pool = new esm_default.Pool({
     connectionString: getDatabaseUrl(),
     statement_timeout: getStatementTimeoutMs(),
+    connectionTimeoutMillis: getConnectionTimeoutMs(),
     max: getPoolMax(),
     // MCP sessions can have minutes-long gaps between tool calls. A short
     // idleTimeout forces a reconnect on every tool call. 60s keeps the pool
@@ -35296,6 +35303,29 @@ function getPool() {
   });
   return pool;
 }
+var typeNameCache = null;
+async function resolveTypeNames(client, oids) {
+  if (oids.length === 0) return {};
+  if (!typeNameCache) {
+    typeNameCache = /* @__PURE__ */ new Map();
+    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);
+  }
+  const missing = oids.filter((o) => !typeNameCache?.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);
+  }
+  const out = {};
+  for (const oid of oids) {
+    const n = typeNameCache.get(oid);
+    if (n !== void 0) out[oid] = n;
+  }
+  return out;
+}
 function formatPgError(err) {
   if (!(err instanceof Error)) return String(err);
   const errObj = err;
@@ -35308,25 +35338,60 @@ function formatPgError(err) {
   }
   return parts.join(" ");
 }
-function toQueryResult(result, maxRows) {
+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");
+    } catch {
+    }
+    await client.query("RELEASE SAVEPOINT __pgmcp_sp");
+    return fetched;
+  } catch (err) {
+    if (declareSucceeded) {
+      throw err;
+    }
+    await client.query("ROLLBACK TO SAVEPOINT __pgmcp_sp");
+    await client.query("RELEASE SAVEPOINT __pgmcp_sp");
+    return client.query({
+      text: sql,
+      values: params,
+      queryMode: "extended"
+    });
+  }
+}
+function toQueryResult(result, maxRows, typeNames = {}) {
   const truncated = result.rows.length > maxRows;
   const rows = truncated ? result.rows.slice(0, maxRows) : result.rows;
   return {
     rows,
     rowCount: result.rowCount,
-    fields: result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID })),
+    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,
     ...truncated ? { truncated: true } : {}
   };
 }
-async function runReadOnly(sql, params = []) {
+async function runReadOnly(sql, params = [], hooks = {}) {
   const client = await getPool().connect();
   const maxRows = getMaxRows();
   try {
     await client.query("BEGIN READ ONLY");
-    const result = await client.query({ text: sql, values: params, queryMode: "extended" });
+    if (hooks.setup) await hooks.setup(client);
+    const result = await runUserQueryBounded(client, sql, params, maxRows);
     await client.query("ROLLBACK");
-    return { ok: true, data: toQueryResult(result, maxRows) };
+    const typeNames = await resolveTypeNames(client, [...new Set(result.fields.map((f) => f.dataTypeID))]);
+    return { ok: true, data: toQueryResult(result, maxRows, typeNames) };
   } catch (err) {
     try {
       await client.query("ROLLBACK");
@@ -35334,6 +35399,12 @@ async function runReadOnly(sql, params = []) {
     }
     return { ok: false, error: formatPgError(err) };
   } finally {
+    if (hooks.teardown) {
+      try {
+        await hooks.teardown(client);
+      } catch {
+      }
+    }
     client.release();
   }
 }
@@ -35348,9 +35419,10 @@ async function runReadWrite(sql, params = []) {
   const maxRows = getMaxRows();
   try {
     await client.query("BEGIN");
-    const result = await client.query({ text: sql, values: params, queryMode: "extended" });
+    const result = await runUserQueryBounded(client, sql, params, maxRows);
     await client.query("COMMIT");
-    return { ok: true, data: toQueryResult(result, maxRows) };
+    const typeNames = await resolveTypeNames(client, [...new Set(result.fields.map((f) => f.dataTypeID))]);
+    return { ok: true, data: toQueryResult(result, maxRows, typeNames) };
   } catch (err) {
     try {
       await client.query("ROLLBACK");
@@ -35361,7 +35433,7 @@ async function runReadWrite(sql, params = []) {
     client.release();
   }
 }
-async function runReadWriteRollback(sql, params = []) {
+async function runReadWriteRollback(sql, params = [], hooks = {}) {
   if (!isWritesAllowed()) {
     return {
       ok: false,
@@ -35372,9 +35444,11 @@ async function runReadWriteRollback(sql, params = []) {
   const maxRows = getMaxRows();
   try {
     await client.query("BEGIN");
-    const result = await client.query({ text: sql, values: params, queryMode: "extended" });
+    if (hooks.setup) await hooks.setup(client);
+    const result = await runUserQueryBounded(client, sql, params, maxRows);
     await client.query("ROLLBACK");
-    return { ok: true, data: toQueryResult(result, maxRows) };
+    const typeNames = await resolveTypeNames(client, [...new Set(result.fields.map((f) => f.dataTypeID))]);
+    return { ok: true, data: toQueryResult(result, maxRows, typeNames) };
   } catch (err) {
     try {
       await client.query("ROLLBACK");
@@ -35382,6 +35456,12 @@ async function runReadWriteRollback(sql, params = []) {
     }
     return { ok: false, error: formatPgError(err) };
   } finally {
+    if (hooks.teardown) {
+      try {
+        await hooks.teardown(client);
+      } catch {
+      }
+    }
     client.release();
   }
 }
@@ -35393,10 +35473,33 @@ 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() {
-  if (pool) {
-    await pool.end();
-    pool = null;
+  typeNameCache = null;
+  if (!pool) return;
+  const ending = pool;
+  pool = null;
+  try {
+    await Promise.race([
+      ending.end(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("pool shutdown timed out after 5s")), 5e3))
+    ]);
+  } catch {
   }
 }
 
@@ -35490,7 +35593,7 @@ var adminTools = [
   },
   {
     name: "pg_table_privileges",
-    description: "Show which roles have which privileges (SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER) on a table or on all tables in a schema. Use this to answer 'who can write to this table?' or to audit schema-wide access before a migration.",
+    description: "Show which roles have which privileges (SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER) on a table or on every table in a schema. If `table` is omitted, the result spans every table in `schema`, ordered by table then grantee. Use this to answer 'who can write to this table?' or to audit schema-wide access before a migration.",
     annotations: {
       title: "Show table privileges",
       readOnlyHint: true,
@@ -35570,49 +35673,137 @@ 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 ?? []
+          }
+        };
+      });
+    }
+  },
+  {
+    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.",
+    annotations: {
+      title: "Database advisor (DBA lints)",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      seqExhaustionThreshold: external_exports3.number().min(0).max(1).default(0.5).describe("Minimum used-fraction (last_value / max_value) to flag a sequence (default 0.5 = 50%)."),
+      rlsSchemas: external_exports3.array(external_exports3.string().min(1).max(63)).default(["public"]).describe("Schemas where RLS-missing should be flagged. Defaults to ['public']."),
+      limit: external_exports3.number().int().min(1).max(500).default(50).describe("Max rows per category (default 50).")
+    }),
+    handler: async (input) => {
+      const { seqExhaustionThreshold, rlsSchemas, limit } = input;
+      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 } : {}
+          }
+        };
+      });
     }
   },
   {
@@ -35627,7 +35818,7 @@ var adminTools = [
     },
     inputSchema: external_exports3.object({
       schema: external_exports3.string().min(1).max(63).optional().describe("Limit to one schema. If omitted, all user schemas are included."),
-      minDeadRatio: external_exports3.number().min(0).max(1).default(0.1).describe("Minimum dead/live ratio to include (default 0.1 = 10%)."),
+      minDeadRatio: external_exports3.number().min(0).max(1).default(0.1).describe("Minimum dead-tuple fraction to include \u2014 dead / (live + dead). Default 0.1 = 10%."),
       limit: external_exports3.number().int().min(1).max(200).default(50).describe("Max rows to return (default 50).")
     }),
     handler: async (input) => {
@@ -35636,22 +35827,23 @@ var adminTools = [
       const params = [minDeadRatio, limit];
       if (schema) params.push(schema);
       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
+        // counters at 0 are filtered out -- nothing to report.
         `SELECT
            schemaname AS schema,
            relname AS "table",
            n_live_tup::text AS live_tuples,
            n_dead_tup::text AS dead_tuples,
-           CASE
-             WHEN n_live_tup = 0 THEN 0
-             ELSE (n_dead_tup::float8 / GREATEST(n_live_tup, 1))::numeric(6, 3)::float8
-           END AS dead_ratio,
+           (n_dead_tup::float8 / (n_live_tup + n_dead_tup))::numeric(6, 3)::float8 AS dead_ratio,
            pg_size_pretty(pg_total_relation_size(relid)) AS size_pretty,
            pg_total_relation_size(relid)::text AS size_bytes,
            last_vacuum::text AS last_vacuum,
            last_autovacuum::text AS last_autovacuum,
            last_analyze::text AS last_analyze
          FROM pg_catalog.pg_stat_user_tables
-         WHERE (n_dead_tup::float8 / GREATEST(n_live_tup, 1)) >= $1
+         WHERE (n_live_tup + n_dead_tup) > 0
+           AND (n_dead_tup::float8 / (n_live_tup + n_dead_tup)) >= $1
            ${schemaFilter}
          ORDER BY n_dead_tup DESC
          LIMIT $2`,
@@ -35667,10 +35859,56 @@ var paramValue = external_exports3.lazy(
 );
 
 // src/tools/explain.ts
+var indexAccessMethod = external_exports3.enum(["btree", "hash", "gin", "gist", "brin", "spgist"]);
+var hypotheticalIndex = external_exports3.object({
+  table: external_exports3.string().min(1).max(127).describe("Target table. Use `schema.table` (e.g. `public.users`) or just `table` for the search_path."),
+  columns: external_exports3.array(external_exports3.string().min(1).max(63)).min(1).describe("Column names in index order. Quoted identifiers are not supported here -- pass plain names."),
+  using: indexAccessMethod.default("btree").describe("Index access method. btree is the right answer for almost every query.")
+});
+function quoteIdent(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+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) => {
+      for (const idx of indexes) {
+        const cols = idx.columns.map(quoteIdent).join(", ");
+        const tbl = quoteQualifiedTable(idx.table);
+        const createSql = `CREATE INDEX ON ${tbl} USING ${idx.using} (${cols})`;
+        const r = await client.query(
+          "SELECT (hypopg_create_index($1)).indexname AS indexname",
+          [createSql]
+        );
+        if (!r.rows[0]?.indexname) {
+          throw new Error(`hypopg_create_index returned no index for: ${createSql}`);
+        }
+      }
+    },
+    teardown: async (client) => {
+      await client.query("SELECT hypopg_reset()");
+    }
+  };
+}
 var explainTools = [
   {
     name: "pg_explain",
-    description: "Get the query plan for a SQL statement. By default, this uses plain EXPLAIN (no execution). Set `analyze: true` to run the query with EXPLAIN ANALYZE \u2014 for non-SELECT statements, ALLOW_WRITES=1 is required (since ANALYZE actually executes the statement). Writes executed during EXPLAIN ANALYZE are always rolled back, so you can inspect a plan for an INSERT/UPDATE/DELETE without persisting the mutation. Format is `text` (default) or `json`. Pass the raw SQL (not an EXPLAIN-prefixed statement).",
+    description: "Get the query plan for a SQL statement. By default, this uses plain EXPLAIN (no execution). Set `analyze: true` to run the query with EXPLAIN ANALYZE \u2014 for non-SELECT statements, ALLOW_WRITES=1 is required (since ANALYZE actually executes the statement). Writes executed during EXPLAIN ANALYZE are always rolled back, so you can inspect a plan for an INSERT/UPDATE/DELETE without persisting the mutation. Format is `text` (default) or `json`. Pass the raw SQL (not an EXPLAIN-prefixed statement). Set `hypothetical_indexes` to a list of `{table, columns, using?}` to ask the planner 'what would the plan be if these indexes existed?' -- requires the HypoPG extension (`CREATE EXTENSION hypopg`). The hypothetical indexes are torn down at the end of the call, never touching real disk.",
     annotations: {
       title: "Explain query plan",
       readOnlyHint: false,
@@ -35682,10 +35920,13 @@ var explainTools = [
       sql: external_exports3.string().min(1).max(1e6).describe("The SQL statement to explain. Do NOT prefix with EXPLAIN."),
       analyze: external_exports3.boolean().default(false).describe("Run EXPLAIN ANALYZE (actually executes the query)."),
       format: external_exports3.enum(["text", "json"]).default("text").describe("Output format."),
-      params: external_exports3.array(paramValue).optional().describe("Positional parameters referenced as $1, $2, ... in the SQL.")
+      params: external_exports3.array(paramValue).optional().describe("Positional parameters referenced as $1, $2, ... in the SQL."),
+      hypothetical_indexes: external_exports3.array(hypotheticalIndex).optional().describe(
+        "List of indexes the planner should pretend exist for this EXPLAIN. Requires the HypoPG extension. Indexes are session-scoped and reset at the end of the call."
+      )
     }),
     handler: async (input) => {
-      const { sql, analyze, format, params } = input;
+      const { sql, analyze, format, params, hypothetical_indexes } = input;
       if (/^\s*EXPLAIN\b/i.test(sql)) {
         return {
           ok: false,
@@ -35696,7 +35937,27 @@ var explainTools = [
       if (analyze) flags.push("ANALYZE");
       if (format === "json") flags.push("FORMAT JSON");
       const explainSql = flags.length > 0 ? `EXPLAIN (${flags.join(", ")}) ${sql}` : `EXPLAIN ${sql}`;
-      const result = analyze && isWritesAllowed() ? await runReadWriteRollback(explainSql, params ?? []) : await runReadOnly(explainSql, params ?? []);
+      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(
+          `SELECT EXISTS (
+             SELECT 1 FROM pg_catalog.pg_extension WHERE extname = 'hypopg'
+           ) AS installed`
+        );
+        if (!check2.ok) return check2;
+        if (!check2.data?.[0]?.installed) {
+          return {
+            ok: false,
+            error: "hypothetical_indexes requires the HypoPG extension. Install with `CREATE EXTENSION hypopg;` (a superuser-equivalent role usually). HypoPG is read-only at the disk level \u2014 it lives entirely in shared memory."
+          };
+        }
+      }
+      const result = analyze && isWritesAllowed() ? await runReadWriteRollback(explainSql, params ?? [], hooks) : await runReadOnly(explainSql, params ?? [], hooks);
       if (!result.ok) return result;
       const data = result.data;
       const rows = data?.rows ?? [];
@@ -35727,61 +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;
-      return {
-        ok: true,
-        data: {
-          connected: true,
-          version: versionRes.data?.[0]?.version,
-          database: sizeRes.ok ? sizeRes.data?.[0] : { error: sizeRes.error },
-          connections: connsRes.ok ? connsRes.data?.[0] : { error: connsRes.error },
-          active_queries: activeRes.ok ? activeRes.data : [],
-          table_count: tableCountRes.ok ? tableCountRes.data?.[0]?.count : null
-        }
-      };
+      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 } : {}
+          }
+        };
+      });
     }
   }
 ];
@@ -35883,7 +36152,7 @@ var schemaTools = [
   },
   {
     name: "pg_describe_table",
-    description: "Describe a table: columns (name, type, nullable, default), primary key, foreign keys, and indexes.",
+    description: "Describe a relation: kind (table / view / materialized_view / partitioned_table / foreign_table), columns (name, type, nullable, default), primary key, foreign keys (outgoing), `referenced_by` (other tables whose FKs point at this one), `constraints` (CHECK / UNIQUE non-PK / EXCLUDE), indexes, and partition info (`partition_of` parent, `partitions` children). Works on views and materialized views too -- PK/FK/constraint/index lists will simply be empty for a plain view. Use `kind` to disambiguate before assuming you can write to the relation.",
     annotations: {
       title: "Describe table",
       readOnlyHint: true,
@@ -35897,6 +36166,20 @@ var schemaTools = [
     }),
     handler: async (input) => {
       const { schema, table } = input;
+      const kindQuery = `
+        SELECT
+          CASE c.relkind
+            WHEN 'r' THEN 'table'
+            WHEN 'p' THEN 'partitioned_table'
+            WHEN 'v' THEN 'view'
+            WHEN 'm' THEN 'materialized_view'
+            WHEN 'f' THEN 'foreign_table'
+            ELSE c.relkind::text
+          END AS kind
+        FROM pg_catalog.pg_class c
+        JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = $1 AND c.relname = $2
+      `;
       const columnsQuery = `
         SELECT
           a.attname AS name,
@@ -35961,32 +36244,121 @@ var schemaTools = [
           AND c.relname = $2
         ORDER BY i.relname
       `;
-      const [cols, pk, fks, idxs] = await Promise.all([
-        runInternal(columnsQuery, [schema, table]),
-        runInternal(primaryKeyQuery, [schema, table]),
-        runInternal(foreignKeysQuery, [schema, table]),
-        runInternal(indexesQuery, [schema, table])
-      ]);
-      if (!cols.ok) return cols;
-      if (!cols.data || cols.data.length === 0) {
-        return { ok: false, error: `Table "${schema}"."${table}" not found.` };
-      }
-      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}`);
-      return {
-        ok: true,
-        data: {
-          schema,
-          table,
-          columns: cols.data,
-          primary_key: pk.ok ? (pk.data ?? []).map((r) => r.column_name) : [],
-          foreign_keys: fks.ok ? fks.data : [],
-          indexes: idxs.ok ? idxs.data : [],
-          ...warnings.length > 0 ? { _warnings: warnings } : {}
+      const constraintsQuery = `
+        SELECT
+          con.conname AS name,
+          CASE con.contype
+            WHEN 'c' THEN 'check'
+            WHEN 'u' THEN 'unique'
+            WHEN 'x' THEN 'exclude'
+            ELSE con.contype::text
+          END AS type,
+          pg_catalog.pg_get_constraintdef(con.oid, true) AS definition
+        FROM pg_catalog.pg_constraint con
+        JOIN pg_catalog.pg_class c ON c.oid = con.conrelid
+        JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = $1
+          AND c.relname = $2
+          AND con.contype IN ('c', 'u', 'x')
+        ORDER BY con.contype, con.conname
+      `;
+      const referencedByQuery = `
+        SELECT
+          con.conname AS constraint_name,
+          srcn.nspname AS schema,
+          src.relname AS "table",
+          array_agg(srcatt.attname::text ORDER BY u.attposition) AS columns,
+          array_agg(refatt.attname::text ORDER BY u.attposition) AS referenced_columns
+        FROM pg_catalog.pg_constraint con
+        JOIN pg_catalog.pg_class src ON src.oid = con.conrelid
+        JOIN pg_catalog.pg_namespace srcn ON srcn.oid = src.relnamespace
+        JOIN pg_catalog.pg_class ref ON ref.oid = con.confrelid
+        JOIN pg_catalog.pg_namespace refn ON refn.oid = ref.relnamespace
+        JOIN LATERAL unnest(con.conkey) WITH ORDINALITY AS u(attnum, attposition) ON TRUE
+        JOIN pg_catalog.pg_attribute srcatt ON srcatt.attrelid = con.conrelid AND srcatt.attnum = u.attnum
+        JOIN LATERAL unnest(con.confkey) WITH ORDINALITY AS fu(attnum, attposition) ON fu.attposition = u.attposition
+        JOIN pg_catalog.pg_attribute refatt ON refatt.attrelid = con.confrelid AND refatt.attnum = fu.attnum
+        WHERE refn.nspname = $1
+          AND ref.relname = $2
+          AND con.contype = 'f'
+        GROUP BY con.conname, srcn.nspname, src.relname
+        ORDER BY srcn.nspname, src.relname, con.conname
+      `;
+      const partitionParentQuery = `
+        SELECT
+          parn.nspname AS schema,
+          par.relname AS "table"
+        FROM pg_catalog.pg_inherits i
+        JOIN pg_catalog.pg_class child ON child.oid = i.inhrelid
+        JOIN pg_catalog.pg_namespace childn ON childn.oid = child.relnamespace
+        JOIN pg_catalog.pg_class par ON par.oid = i.inhparent
+        JOIN pg_catalog.pg_namespace parn ON parn.oid = par.relnamespace
+        WHERE childn.nspname = $1
+          AND child.relname = $2
+          AND child.relispartition
+      `;
+      const partitionChildrenQuery = `
+        SELECT
+          childn.nspname AS schema,
+          child.relname AS "table",
+          pg_catalog.pg_get_expr(child.relpartbound, child.oid) AS bound
+        FROM pg_catalog.pg_inherits i
+        JOIN pg_catalog.pg_class par ON par.oid = i.inhparent
+        JOIN pg_catalog.pg_namespace parn ON parn.oid = par.relnamespace
+        JOIN pg_catalog.pg_class child ON child.oid = i.inhrelid
+        JOIN pg_catalog.pg_namespace childn ON childn.oid = child.relnamespace
+        WHERE parn.nspname = $1
+          AND par.relname = $2
+          AND child.relispartition
+        ORDER BY childn.nspname, child.relname
+      `;
+      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 } : {}
+          }
+        };
+      });
     }
   },
   {
@@ -36165,8 +36537,12 @@ 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(
+        // 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::text AS calls,
@@ -36271,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);
@@ -36283,7 +36662,7 @@ function compareVersions(a, b) {
 }
 
 // src/index.ts
-var version2 = true ? "0.3.3" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.4.1" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);