@yawlabs/postgres-mcp 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,306 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-04-25
+
+### Security
+- User SQL fetches are now memory-bounded by Postgres, not by Node. The
+  prior flow had node-pg materialize the entire result set into memory and
+  then sliced down to `POSTGRES_MAX_ROWS` for output -- so a payload like
+  `SELECT * FROM big1 CROSS JOIN big2` could OOM the MCP process before
+  the 30 s `statement_timeout` fired. User SQL now runs through a
+  server-side `DECLARE ... NO SCROLL CURSOR FOR ...` + `FETCH MAX_ROWS+1`
+  pattern; only the response-sized batch is ever materialized in Node.
+  Non-cursorable statements (DDL, DML without RETURNING, utility commands)
+  fall back to a direct execute via `SAVEPOINT` so the outer transaction
+  stays alive -- those statements never produce a runaway result set
+  anyway.
+- User SQL is now sent with `queryMode: 'extended'`, forcing pg to use the
+  extended query protocol regardless of whether `params` is empty. The
+  extended protocol restricts each request to a single statement, closing
+  the stacked-query injection pattern documented by
+  [Datadog Security Labs](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/)
+  against the now-archived `@modelcontextprotocol/server-postgres`. Without
+  this fix, a payload like `SELECT 1; COMMIT; DROP SCHEMA x CASCADE;` passed
+  to `pg_query` would escape the `BEGIN READ ONLY` wrapper and run DDL in
+  autocommit. Added an integration regression test that asserts the
+  multi-statement request is rejected by Postgres.
+- `pg` minimum bumped from `^8.13.0` to `^8.14.0`. The `queryMode: 'extended'`
+  option that backs the stacked-query guard above is silently ignored on pg
+  8.13.x -- a fresh `npm install` resolving to that range would have regressed
+  the security guard with no visible signal. Today's lockfile pins 8.20.0;
+  the range bump prevents future installs from sliding back.
+- `@types/pg` bumped from `^8.11.10` to `^8.20.0` to track pg 8.20.0 runtime.
+
+### Added
+- New `pg_advisor` tool: rolled-up DBA lints in one call. Returns three
+  categories of findings -- `sequence_exhaustion` (sequences whose
+  last_value is past `seqExhaustionThreshold` of max_value, default 50%;
+  the classic "BIGINT, eventually" incident class), `tables_without_primary_key`
+  (bloat candidates and a sign of design drift), and
+  `public_tables_without_rls` (default `public`; configurable via
+  `rlsSchemas`). Use as the "what should I be looking at?" starting
+  point and drill into `pg_unused_indexes` / `pg_table_bloat` /
+  `pg_seq_scan_tables` for the perf side.
+- `pg_explain` accepts a `hypothetical_indexes` parameter -- list of
+  `{table, columns, using?}` -- which asks the planner "what would the
+  plan be if these indexes existed?". Requires the
+  [HypoPG](https://github.com/HypoPG/hypopg) extension
+  (`CREATE EXTENSION hypopg;`); the tool returns a friendly hint pointing
+  at that command if HypoPG isn't installed. Indexes are session-scoped
+  and torn down at the end of the call via `hypopg_reset()`, so they
+  never persist across MCP requests and never touch real disk. Closes
+  the biggest competitive gap vs. Crystal DBA's Postgres MCP Pro per
+  the comp-landscape audit. WSL setup script now installs the
+  `postgresql-${V}-hypopg` package opportunistically; the matrix test
+  runs against PG17 and PG18 and verifies the planner switches a Seq
+  Scan to an Index/Bitmap scan when a hypothetical index is supplied.
+- `pg_describe_table` now returns four new fields:
+  - `referenced_by` -- incoming FKs (other tables whose foreign keys point at
+    this one). Answers "what depends on this table?" before a destructive
+    change. None of the surveyed competing Postgres MCP servers expose this;
+    in psql you'd run `\d+` on every candidate table and squint.
+  - `constraints` -- CHECK / UNIQUE non-PK / EXCLUDE constraints with each
+    constraint's full definition string from `pg_get_constraintdef()`. PK and
+    FK still live in their dedicated fields, so no double-listing.
+  - `partition_of` -- when the relation is a partition, the parent
+    schema / table.
+  - `partitions` -- when the relation is a `partitioned_table`, the list of
+    children with their `pg_get_expr()` partition bounds.
+- `pg_query` result `fields` now include `dataTypeName` (e.g. `int4`, `text`,
+  `jsonb`) alongside `dataTypeID`. Previously LLMs saw only the OID and had
+  to map it themselves. Resolution is process-cached against `pg_type`, with
+  a single miss-fill query for any OID introduced by `CREATE TYPE` mid-session.
+- npm tarball now ships `LICENSE`, `README.md`, and `CHANGELOG.md` alongside
+  the bundle. Previously the `files` allowlist was `["dist/index.js"]` only,
+  so `npm pack` produced a tarball with no docs and no license file -- bad
+  for downstream consumers and registry surfaces that read README from the
+  tarball rather than the repo.
+- README workflow examples now show three multi-tool sequences (unstick a
+  hung app via `pg_inspect_locks` -> `pg_kill`, chase a slow page via
+  `pg_top_queries` -> `pg_explain` -> `pg_unused_indexes`, oncall triage via
+  `pg_health` -> `pg_inspect_locks` -> `pg_replication_status`). The previous
+  example list was single-tool only.
+- New `pg_table_bloat` integration test asserts every returned `dead_ratio`
+  is a finite number in `[0, 1]`. Locks down the invariant that the recent
+  `dead / (live + dead)` formula change was meant to enforce.
+- New `pg_query` integration tests for the `$1`-without-params error path
+  and the result-count-equals-`POSTGRES_MAX_ROWS` boundary (must NOT flag
+  `truncated: true`).
+- New `pg_explain` integration tests for `analyze: true` on a SELECT in
+  read-only mode (works) and on an INSERT in read-only mode (errors with
+  the ALLOW_WRITES hint).
+- npm `keywords` expanded with `agent`, `claude`, `claude-code`, `cursor`,
+  `llm` so registry / search engine queries for "postgres mcp claude code"
+  surface this package.
+- `POSTGRES_CONNECTION_TIMEOUT_MS` env var (default `10000`). Without it, a
+  dead host hangs the first connection attempt until the OS times out
+  (~2 minutes on most platforms), and the agent waits the whole time before
+  surfacing an error.
+- `pg_describe_table` now returns a `kind` field (`table` / `view` /
+  `materialized_view` / `partitioned_table` / `foreign_table`). Previously
+  the tool silently accepted views and matviews and returned columns with
+  empty `primary_key` / `foreign_keys` / `indexes` -- correct, but an LLM
+  couldn't tell whether the relation was writable.
+
+### Changed
+- README now states the supported Postgres versions: tested on 17 and 18,
+  expected to work on 13+.
+
+### Changed
+- `pg_top_queries` now returns `calls` and `rows` as JS numbers (cast to
+  `float8` in SQL) instead of strings. The previous `::text` cast forced
+  consumers to parse `"42"` to use it; the timing fields next to them were
+  already numbers, so the response shape was inconsistent. float8 is fine
+  -- 2^53 is well above any realistic per-query call/row count.
+- `pg_health` partial-failure shape: failed sub-queries now contribute to a
+  top-level `_warnings: string[]` array, and the affected fields stay null
+  instead of becoming `{error: "..."}`. Previously a failure of the size
+  query made `data.database.size_bytes` resolve to `undefined` with no
+  signal -- LLMs couldn't tell "missing" from "errored". This matches the
+  `_warnings` convention `pg_describe_table` already uses.
+- `shutdown()` now races `pool.end()` against a 5 s timer. `pool.end()`
+  waits for in-flight queries with no upper bound, so a wedged query
+  (frozen NFS, network hang) could leave the MCP server appearing stuck on
+  exit until the OS reaped the TCP sockets.
+- `pg_table_privileges` description tightened to spell out that omitting
+  `table` returns privileges for every table in the schema.
+- README now lists supported PG versions explicitly and groups workflow
+  examples by single-tool / multi-tool intent.
+
+### Fixed
+- `pg_table_bloat` now uses `dead / (live + dead)` for `dead_ratio` instead of
+  `dead / live`. The previous formula reported `0` for tables with `live = 0`
+  even when `dead > 0`, hiding the most-bloated tables (an empty-shell table
+  full of dead tuples is the textbook VACUUM target). The new formula is
+  bounded `[0, 1]`, behaves correctly at edges, and the `WHERE` filter now
+  excludes tables with both counters at 0 entirely. The `minDeadRatio`
+  parameter description was updated to match.
+- `npm test` now serializes test files with `--test-concurrency=1`. Unit tests
+  in `api.test.ts` and `tools/admin.test.ts` both mutate `process.env`
+  (`ALLOW_WRITES`, `POSTGRES_MAX_ROWS`, etc.); under Node's default parallel
+  test-file scheduling these races could flap on CI.
+- README integration-suite paragraph corrected: the schema is named
+  `test_fixture`, not `postgres_mcp_integration`.
+- `scripts/wsl-test-matrix.sh` derives `REPO_SRC` from its own location instead
+  of a hardcoded `/mnt/c/Users/jeff/...` path. Anyone other than the original
+  author can now run the matrix from their own clone.
+- `release.sh` creates annotated tags (`git tag -a`) and pushes with
+  `--follow-tags` instead of `--tags`. The previous `--tags` form pushed every
+  local tag, including any unrelated experimental ones lying around;
+  `--follow-tags` only pushes the tag(s) reachable from the commits being
+  pushed -- but it ignores lightweight tags, so the tag-creation step had to
+  switch to annotated to keep working.
+
+## [0.3.2] - 2026-04-24
+
+### Fixed
+- `pg_explain` with `analyze: true` and `ALLOW_WRITES=1` no longer persists
+  writes executed by `EXPLAIN ANALYZE`. Previously the write ran inside a
+  `BEGIN; ... COMMIT` transaction, so `pg_explain { analyze: true, sql:
+  "INSERT ..." }` would actually insert the row. Now writes run inside a
+  `BEGIN; ... ROLLBACK` transaction — the plan (with real row counts and
+  timing) comes back but the mutation is rolled back. This matches the user
+  expectation when asking for a plan, and the tool description has been
+  updated to reflect it.
+- `pg_health` `table_count` now excludes `pg_temp_%` schemas, matching the
+  filter in `pg_list_schemas`. The `relkind` filter already masked most
+  divergence, but the two queries are now consistent.
+- `pg_seq_scan_tables` ratio column simplified. The previous CASE had a
+  branch that only fired when `idx_scan = 0 AND seq_scan = 0` (practically
+  unreachable given the table was ordered by `seq_scan DESC`), returning
+  `0` and implying a distinction that didn't exist. Now returns `NULL`
+  whenever `idx_scan = 0`, which is the meaningful ratio-undefined case.
+
+### Added
+- `process.stdin` `end` handler cleans up the pg pool when the MCP client
+  disconnects. Previously the server kept running for up to 60 seconds
+  (the pool's idle timeout) after the parent closed the pipe.
+- Shared `src/tools/params.ts` for the `paramValue` zod schema, previously
+  duplicated verbatim in `query.ts` and `explain.ts`.
+
+### Infrastructure
+- Integration test suites now share one `before(setupFixtures)` /
+  `after(teardownFixtures)` per file via an outer `describe`, instead of
+  running DROP/CREATE per inner `describe`. Each file previously reset
+  the fixture schema 3-4 times; now it resets once.
+
+## [0.3.1] - 2026-04-22
+
+### Fixed
+- `pg_list_roles` with `includeSystem: false` (the default) now actually
+  excludes built-in `pg_*` roles. The previous `LIKE 'pg\_%' ESCAPE '\\'`
+  filter ended up as SQL `ESCAPE '\\'` (two backslashes), which Postgres
+  rejects since `ESCAPE` requires a single character — so the whole filter
+  was silently being dropped. Replaced with `starts_with(rolname, 'pg_')`.
+- `pg_describe_table` foreign-key `columns` and `foreign_columns` are now
+  proper JSON arrays. They were previously returned as the raw postgres
+  text form (e.g. `"{user_id}"`) because `array_agg(name)` returns `name[]`,
+  which node-pg doesn't auto-parse. Cast to `text[]` so the driver parses.
+
+### Infrastructure (main branch CI hygiene; no user-facing changes)
+- `.gitattributes` forces LF line endings in the working tree on every OS,
+  so biome's formatter doesn't reject every file on Windows runners after
+  git's auto-CRLF conversion.
+- The integration CI job now starts postgres via `docker run` with
+  `-c shared_preload_libraries=pg_stat_statements` instead of the `services:`
+  block (which passes options to `docker create`, where `-c` means
+  --cpu-shares and collided with the postmaster flag).
+- Cross-platform test discovery via `scripts/run-tests.mjs`. `node --test dist`
+  hangs on Windows; `dist/**/*.test.js` globs only expand in bash with
+  globstar. The wrapper uses `fs.readdirSync({ recursive: true })` (stdlib)
+  and passes explicit paths, plus `--test-concurrency=1` for the integration
+  suite so fixture-schema setup doesn't race.
+
+## [0.3.0] - 2026-04-22
+
+### Added
+- `pg_list_views` — list views and materialized views with SQL definitions.
+- `pg_list_functions` — list functions, procedures, and aggregates with signatures.
+- `pg_list_extensions` — list installed extensions (pgvector, postgis, etc.) with versions.
+- `pg_search_columns` — find columns by name pattern across all user schemas.
+- `pg_top_queries` — top N queries by total/mean execution time from
+  `pg_stat_statements`. Detects extension version and picks the right column
+  names (v1.8+ uses `total_exec_time`, older uses `total_time`). Returns clear
+  setup instructions if the extension is not installed.
+- `pg_list_tables` now accepts `limit` / `offset` for pagination on large schemas.
+- `pg_health` now accepts `activeQueryLimit` (1–100) to override the default of 10.
+- `pg_query` / `pg_explain` `params` now accept arrays and objects (for
+  postgres arrays, `ANY`, and json/jsonb columns) in addition to scalars.
+- `POSTGRES_SSL_REJECT_UNAUTHORIZED` env var to disable TLS cert verification for
+  managed databases using private-CA certs (Supabase, Neon, RDS). Documented in
+  a new "Connecting to managed Postgres" README section.
+- `pg_describe_table` now surfaces partial failures via a `_warnings` array
+  instead of silently collapsing FK/index fetch errors into empty lists.
+- Troubleshooting section in README covering common failure modes (env vars,
+  auth, timeouts, write-blocked, pool exhaustion, cold-start latency).
+- CHANGELOG.md.
+- Dependabot config for npm + github-actions (weekly, grouped dev deps).
+- Windows CI matrix (ubuntu + windows × Node 18/20/22).
+- Integration test suite (`npm run test:integration`) that exercises every
+  tool against a real Postgres instance. Gated on `POSTGRES_MCP_INTEGRATION=1`
+  so local `npm test` stays fast with no DB required. CI runs it on Linux via
+  a `postgres:16` service container with `pg_stat_statements` preloaded.
+- `pg_inspect_locks` — show current blocking locks (blocked PID, blocker PID,
+  relation, lock type, both queries). First tool to reach for when a session
+  hangs or the app feels stuck.
+- `pg_list_roles` — database roles with login/superuser/createdb/createrole
+  flags and inherited group memberships.
+- `pg_table_privileges` — who has SELECT/INSERT/UPDATE/DELETE/etc. on a table,
+  or on all tables in a schema. Useful for pre-migration audits.
+- `pg_seq_scan_tables` — tables with heavy sequential scans relative to index
+  scans. Missing-index candidates.
+- `pg_unused_indexes` — non-unique, non-primary indexes with low/zero scan
+  counts. Drop candidates (each unused index costs write amplification).
+- `pg_kill` — cancel a running query or terminate a backend by PID. Requires
+  `ALLOW_WRITES=1` since it changes session state. Distinguishes `cancel`
+  (SIGINT-equivalent, graceful) from `terminate` (SIGTERM, forceful).
+- `pg_table_bloat` — estimate dead tuples and vacuum-candidate tables from
+  `pg_stat_user_tables`. No extensions required.
+- `pg_replication_status` — replication slots, connected replicas with lag,
+  and current WAL position. Returns empty arrays on a standalone DB rather
+  than erroring, so it's safe to call unconditionally.
+- New "What can an agent do with this?" README section with concrete example
+  conversations mapped to tool calls.
+
+### Changed
+- Loosened identifier validation on `pg_list_tables` and `pg_describe_table`.
+  Quoted identifiers (e.g. `"My Table"`) now work. Length capped at 63 bytes
+  (the postgres limit) via zod schema; the previous regex-based whitelist
+  blocked legitimate identifiers.
+- Pool `idleTimeoutMillis` widened 10s → 60s. MCP sessions routinely have
+  minute-long gaps; the short timeout was forcing a reconnect on every tool
+  call.
+- `pg_query` / `pg_explain` `sql` inputs now hard-capped at 1 MB.
+
+### Fixed
+- `pg_explain` now rejects pre-wrapped SQL (e.g. `"EXPLAIN SELECT 1"`) with a
+  clear error instead of producing a `EXPLAIN (...) EXPLAIN SELECT 1` syntax
+  error. LLMs frequently make this mistake.
+
+## [0.1.1] - 2026-04-21
+
+### Changed
+- Release workflow: widened npm registry propagation wait from 1 min to 10 min
+  to handle occasional stalls observed on initial publish.
+
+## [0.1.0] - 2026-04-21
+
+Initial release.
+
+### Added
+- `pg_query` — run SQL with read-only-by-default safety. Writes opt in via `ALLOW_WRITES=1`.
+- `pg_list_schemas` — list non-system schemas.
+- `pg_list_tables` — list tables (and optionally views) with estimated row counts.
+- `pg_describe_table` — columns, PK, FKs, indexes.
+- `pg_explain` — `EXPLAIN` / `EXPLAIN ANALYZE` with text or JSON output.
+- `pg_health` — server version, db size, connections, active queries, table count.
+- Single-file bundled distribution (zero runtime deps) for fast `npx` cold starts.
+- Result row truncation at `POSTGRES_MAX_ROWS` (default 1000).
+- Parameterized queries via `params` on `pg_query` and `pg_explain`.

package/README.md

@@ -92,29 +92,34 @@ Prefer scoping this to dev/test databases — for production, leave writes off a
 
 ## What can an agent do with this?
 
-Once connected, the agent picks tools automatically based on what you ask. A few real examples:
+Once connected, the agent picks tools automatically based on what you ask. A few single-tool examples:
 
-- **"Describe the users table"** -> `pg_describe_table` -> returns columns, PK, FKs, indexes.
+- **"Describe the users table"** -> `pg_describe_table` -> returns kind, columns, PK, FKs, indexes.
 - **"Which tables have a `user_id` column?"** -> `pg_search_columns` with pattern `user_id` -> one call instead of iterating every table.
 - **"This query is slow, why?"** -> `pg_explain` with `analyze: true` -> returns the plan with actual row counts and timing.
 - **"What's the slowest query we run?"** -> `pg_top_queries` -> returns the top N from `pg_stat_statements` with mean/total/min/max times.
-- **"Why is my app hanging?"** -> `pg_inspect_locks` -> returns blocked PIDs and the queries holding their locks; follow up with `pg_kill` (with `ALLOW_WRITES=1`) to cancel the blocker.
 - **"Do we have any unused indexes?"** -> `pg_unused_indexes` -> returns non-unique, non-primary indexes with zero or low scan counts + their size.
 - **"Is `pgvector` installed?"** -> `pg_list_extensions` -> yes/no with version.
 
+The bigger leverage is multi-tool reasoning. A few real workflows:
+
+- **Unstick a hung app.** `pg_inspect_locks` returns blocked PID + blocking PID + the offending query, then `pg_kill` (`ALLOW_WRITES=1` required) cancels the blocker. The agent can run both in one turn — it's the fastest path from "the app is frozen" to "back up."
+- **Chase a slow page.** `pg_top_queries` ranks the worst queries, `pg_explain` with `analyze: true` shows the plan for the top hit, `pg_seq_scan_tables` and `pg_unused_indexes` say whether the answer is "add an index here" or "drop a dead one there."
+- **Oncall triage.** `pg_health` checks connectivity + active-query count + database size; `pg_inspect_locks` and `pg_replication_status` confirm whether contention or replication lag is in play before paging the on-call DBA.
+
 ## Tools
 
 | Tool | Description |
 |------|-------------|
-| `pg_query` | Run a SQL query. Read-only by default; writes require `ALLOW_WRITES=1`. Supports parameterized queries via `params`. |
+| `pg_query` | Run a SQL query. Read-only by default; writes require `ALLOW_WRITES=1`. 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`. |
-| `pg_describe_table` | Columns, primary key, foreign keys, and indexes for a table. |
+| `pg_describe_table` | Kind, columns, PK, outgoing FKs, incoming FKs (`referenced_by`), CHECK / UNIQUE / EXCLUDE constraints, indexes, and partition parent/children for a relation. |
 | `pg_list_views` | List views and materialized views in a schema, including their SQL definitions. |
 | `pg_list_functions` | List functions, procedures, and aggregates in a schema with signatures and return types. |
 | `pg_list_extensions` | List installed extensions (pgvector, postgis, pg_stat_statements, etc.) with versions. |
 | `pg_search_columns` | Find columns by name pattern across all user schemas. Case-insensitive, supports SQL LIKE wildcards. |
-| `pg_explain` | `EXPLAIN` or `EXPLAIN ANALYZE` for a SQL statement. Text or JSON output. |
+| `pg_explain` | `EXPLAIN` or `EXPLAIN ANALYZE` for a SQL statement. Text or JSON output. Optional `hypothetical_indexes` (requires the [HypoPG](https://github.com/HypoPG/hypopg) extension) lets you ask "what would the plan be with these indexes?" without creating them on disk. |
 | `pg_health` | Server version, database size, connection count, active queries, table count. |
 | `pg_top_queries` | Top N queries by total/mean execution time. Requires the `pg_stat_statements` extension. |
 | `pg_seq_scan_tables` | Tables with heavy sequential scans — missing-index candidates. |
@@ -124,6 +129,7 @@ Once connected, the agent picks tools automatically based on what you ask. A few
 | `pg_table_privileges` | Who has SELECT/INSERT/UPDATE/DELETE/etc. on a table or whole schema. |
 | `pg_table_bloat` | Tables with high dead-tuple ratios — VACUUM candidates. |
 | `pg_replication_status` | Replication slots, connected replicas, and current WAL position. |
+| `pg_advisor` | Rolled-up DBA lints in one call: sequence-exhaustion candidates, tables without a primary key, and (configurable) public tables with RLS disabled. The "what should I be looking at?" starting point. |
 | `pg_kill` | Cancel a running query or terminate a backend connection. Requires `ALLOW_WRITES=1`. |
 
 ## Configuration
@@ -135,10 +141,15 @@ All env vars are read from the MCP server's environment:
 | `DATABASE_URL` | (required) | PostgreSQL connection string. |
 | `ALLOW_WRITES` | unset | Set to `1` or `true` to allow DML/DDL via `pg_query` and `pg_explain` ANALYZE of writes. |
 | `POSTGRES_STATEMENT_TIMEOUT_MS` | `30000` | Per-statement timeout. |
+| `POSTGRES_CONNECTION_TIMEOUT_MS` | `10000` | TCP connect timeout. Without this, a dead host hangs until the OS gives up (~2 minutes). |
 | `POSTGRES_MAX_ROWS` | `1000` | Cap on rows returned by `pg_query`. |
 | `POSTGRES_POOL_MAX` | `5` | Max pool connections. Set to `1` for single-threaded backends (pglite-socket, PgBouncer transaction mode). |
 | `POSTGRES_SSL_REJECT_UNAUTHORIZED` | unset | Set to `false` to skip TLS cert verification (for managed DBs using private-CA certs). Connection is still encrypted. |
 
+### Supported Postgres versions
+
+Tested on **PostgreSQL 17 and 18** in CI. Should work on PG13+ -- a few tools (`pg_replication_status` reading `wal_status`, `pg_top_queries` reading `*_exec_time`) rely on columns that landed in PG13. PG12 and below are out of upstream support and not exercised here.
+
 ### Connecting to managed Postgres (Supabase, Neon, RDS, etc.)
 
 Most managed databases require TLS but serve certs signed by a private CA that Node's default trust store doesn't recognize. The symptom is one of:
@@ -174,6 +185,32 @@ This disables certificate chain verification only -- the TCP connection is still
 
 **First query is slow, subsequent queries are fast** — Expected. The pg driver lazily establishes the first connection; subsequent queries reuse the pool.
 
+## Development
+
+Run the full suite (unit + integration) against a real Postgres:
+
+```bash
+DATABASE_URL='postgres://user:pass@host:5432/db' POSTGRES_MCP_INTEGRATION=1 npm run test:integration
+```
+
+The integration suite assumes a disposable database -- it creates and drops a `test_fixture` schema. Don't point it at anything you care about.
+
+### 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):
+
+```powershell
+wsl --install -d Ubuntu --no-launch
+# reboot, then:
+wsl -d Ubuntu -u root bash -c "apt-get update && apt-get install -y nodejs npm rsync"
+wsl -d Ubuntu -u root bash /mnt/c/path/to/postgres-mcp/scripts/wsl-pg-setup.sh
+wsl -d Ubuntu -u root bash /mnt/c/path/to/postgres-mcp/scripts/wsl-test-matrix.sh
+```
+
+`wsl-pg-setup.sh` installs PG17 and PG18 from the PGDG apt repo on ports 5432 and 5433, sets the `postgres` password to `postgres`, and creates `postgres_mcp_test` in each. `wsl-test-matrix.sh` rsyncs the working tree into `/root/postgres-mcp`, runs `npm ci` once, and runs the integration suite against every cluster found via `pg_lsclusters`.
+
+Tear down when finished: `wsl --unregister Ubuntu`.
+
 ## License
 
 MIT © 2026 YawLabs

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,55 @@ function formatPgError(err) {
   }
   return parts.join(" ");
 }
-function toQueryResult(result, maxRows) {
+async function runUserQueryBounded(client, sql, params, maxRows) {
+  await client.query("SAVEPOINT __pgmcp_sp");
+  try {
+    await client.query({
+      text: `DECLARE __pgmcp_cur NO SCROLL CURSOR FOR ${sql}`,
+      values: params,
+      queryMode: "extended"
+    });
+    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 {
+    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 +35394,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 +35414,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 +35428,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 +35439,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 +35451,12 @@ async function runReadWriteRollback(sql, params = []) {
     }
     return { ok: false, error: formatPgError(err) };
   } finally {
+    if (hooks.teardown) {
+      try {
+        await hooks.teardown(client);
+      } catch {
+      }
+    }
     client.release();
   }
 }
@@ -35394,9 +35469,16 @@ async function runInternal(sql, params = []) {
   }
 }
 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 +35572,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,
@@ -35615,6 +35697,87 @@ 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.",
+    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;
+      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 } : {}
+        }
+      };
+    }
+  },
   {
     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 \u2014 uses `pg_stat_user_tables`, no extensions required.",
@@ -35627,7 +35790,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 +35799,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 +35831,43 @@ 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 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 +35879,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 +35896,23 @@ 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 ?? [];
+      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 ?? [];
@@ -35771,15 +35987,21 @@ var healthTools = [
         )
       ]);
       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] : { error: sizeRes.error },
-          connections: connsRes.ok ? connsRes.data?.[0] : { error: connsRes.error },
+          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
+          table_count: tableCountRes.ok ? tableCountRes.data?.[0]?.count : null,
+          ...warnings.length > 0 ? { _warnings: warnings } : {}
         }
       };
     }
@@ -35883,7 +36105,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 +36119,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,29 +36197,113 @@ var schemaTools = [
           AND c.relname = $2
         ORDER BY i.relname
       `;
-      const [cols, pk, fks, idxs] = await Promise.all([
+      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
+      `;
+      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(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 } : {}
         }
       };
@@ -36167,14 +36487,17 @@ var statsTools = [
       const maxCol = useExecSuffix ? "max_exec_time" : "max_time";
       const orderCol = orderBy === "total_time" ? totalCol : orderBy === "mean_time" ? meanCol : "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.
         `SELECT
            query,
-           calls::text AS calls,
+           calls::float8 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::text AS rows,
+           rows::float8 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
@@ -36283,7 +36606,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.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.3.3",
+  "version": "0.4.0",
   "description": "PostgreSQL MCP server — query, schema introspection, explain, and health checks for AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",
@@ -15,6 +15,11 @@
     "mcp",
     "model-context-protocol",
     "ai",
+    "agent",
+    "claude",
+    "claude-code",
+    "cursor",
+    "llm",
     "sql",
     "schema",
     "explain"
@@ -25,7 +30,10 @@
     "postgres-mcp": "dist/index.js"
   },
   "files": [
-    "dist/index.js"
+    "dist/index.js",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc && node build.mjs",
@@ -44,7 +52,7 @@
     "@types/node": "^25.6.0",
     "@types/pg": "^8.20.0",
     "esbuild": "^0.28.0",
-    "pg": "^8.13.0",
+    "pg": "^8.14.0",
     "typescript": "^6.0.3",
     "zod": "^4.3.6"
   },