PostgreSQL MCP Server

# v1.2.0 - Stabilization & Quality Hardening **Release Date:** February 10, 2026 ## Highlights 🛡️ **Object existence verification** for convenience tools, **metadata caching** for high-frequency schema queries, **systematic eslint-disable elimination**, and **60+ bug fixes** across vector, kcache, partitioning, PostGIS, and text search tool groups. ## What's New ### Object Existence Verification (P154) Convenience tools (`pg_count`, `pg_exists`, `pg_upsert`, `pg_batch_insert`, `pg_truncate`) and 11 vector tools now perform pre-flight table/column existence checks before executing queries. Returns high-signal error messages (e.g., `Table "public.nonexistent" does not exist`) instead of raw PostgreSQL errors. ### New Parameters - **`pg_list_tables` `exclude`** — Filter out extension/system schemas (e.g., `exclude: ['cron', 'topology', 'partman']`) - **`--server-host` CLI argument** — Bind address configuration for containerized deployments (default: `localhost`, Dockerfile defaults to `0.0.0.0`) - **`pg_analyze_workload_indexes` `queryPreviewLength`** — Configurable max characters for query preview (default: 200) - **`pg_kcache_top_cpu` / `pg_kcache_top_io` `queryPreviewLength`** — Configurable query preview length (default: 100, max: 500) - **`pg_regexp_match` / `pg_like_search` default limit** — Both tools now default to `LIMIT 100`, preventing unbounded result sets - **`pg_geo_transform` SRID auto-detection** — `fromSrid` is now optional; auto-detects source SRID from catalog tables ## Bug Fixes ### Response Consistency - **`pg_upsert`** — Removed `sql` field from default response to prevent SQL leakage and reduce token usage - **`pg_ltree_convert_column`** — Already-ltree response now includes `table` and `previousType` fields - **`pg_ltree_create_index`** — Already-exists response now includes `table`, `column`, and `indexType` fields - **`pg_drop_schema`** — Renamed response key `dropped` → `schema` to align with sibling drop tools - **`pg_list_tables` / `pg_describe_table` `rowCount`** — Returns `0` for empty tables instead of being silently omitted - **`pg_stat_statements`** — Response now includes `count` field, consistent with all other paginated performance tools - **`pg_write_query`** — DDL statements no longer fail output schema validation; `rowsAffected` defaults to `0` ### Correctness - **`pg_kcache_top_io`** — Now filters by type-specific I/O column when `ioType` is `reads` or `writes` - **Kcache race condition guard** — All 4 kcache count-then-query tools use `Math.max(totalCount, rowCount)` to prevent misleading `truncated` flags - **`pg_kcache_query_stats` / `pg_kcache_resource_analysis`** — Default limit reduced from 50 to 20 (use `limit: 50` to restore) - **`pg_pgcrypto_gen_random_uuid` `count` parameter** — Now visible to MCP clients via Split Schema pattern - **`pg_buffer` / `pg_geo_transform` truncation** — Correctly return `truncated: true` + `totalCount` for explicit limits - **`pg_hybrid_search` tsvector support** — `textColumn` auto-detects column type; tsvector columns used directly without wrapping - **`pg_vector_batch_insert` tool filtering** — Fixed missing registration in `ToolConstants.ts` tool filtering registry - **`pg_list_functions` extension aliases** — `pgvector`, `partman`, `fuzzymatch`, `fuzzy` aliases now correctly filter extension functions - **`runningQueries` Code Mode alias** — Now correctly routes to `longRunningQueries()` instead of `statActivity()` ### Partitioning - **`pg_create_partition` / `pg_attach_partition` / `pg_detach_partition`** — Return structured `{success: false, error}` instead of raw PostgreSQL errors for missing/non-partitioned tables ## Performance - **Metadata caching** — `listTables` and `describeTable` now use TTL-based metadata cache (default 30s, configurable via `METADATA_CACHE_TTL_MS`), reducing database load for repeated schema queries ## Code Quality - **Systematic `eslint-disable` elimination** — Removed ~43 `eslint-disable` comments. Only 7 justified suppressions remain (5 `no-deprecated` for SDK limitations, 2 `no-control-regex` for security patterns), all with inline justification - Refactored `require-await` (~30 handlers), `no-misused-promises`, `no-unused-vars`, and `no-unsafe-argument` suppressions with proper fixes ## Documentation - **Code Mode token efficiency guidance** — Added recommendations to README, Docker README, and Code Mode wiki - **Tool count synchronization** — Reconciled counts across `ToolConstants.ts`, README, Docker README, and 7 wiki pages (total: 206 tools) - **Docker README corrections** — Fixed 6 prompt names, 1 resource URI, and added 3 missing extensions - **Code Mode wiki expansion** — Full API documentation for all 19 `pg.{group}.{method}()` groups - **ServerInstructions.ts** — Comprehensive updates for response structures, parameter descriptions, help() consistency, and PostGIS code mode aliases - **Troubleshooting wiki** — Fixed `pg_cancel_query` → `pg_cancel_backend` tool name reference ## Dependencies - `@modelcontextprotocol/sdk` 1.25.3 → 1.26.0 - `@types/node` 25.1.0 → 25.2.3 - `commander` 14.0.2 → 14.0.3 - `globals` 17.2.0 → 17.3.0 - `pg` 8.17.2 → 8.18.0 - `typescript-eslint` 8.54.0 → 8.55.0 - Skipped `eslint` 10.0.0 — major version blocked by `typescript-eslint` v8.55 ## Links - [GitHub Repository](https://github.com/neverinfamous/postgresql-mcp) - [Docker Hub](https://hub.docker.com/r/writenotenow/postgres-mcp) - [npm Package](https://www.npmjs.com/package/@neverinfamous/postgres-mcp) - [Full Changelog](https://github.com/neverinfamous/postgresql-mcp/blob/master/CHANGELOG.md)