v1.3.0 - Deterministic Error Handling

v1.3.0 - Deterministic Error Handling

Every tool now returns structured {success, error} responses — no raw exceptions, no silent failures, no misleading messages. This release represents the most comprehensive reliability improvement in the project's history.

Highlights

🛡️ Deterministic Error Handling (All 20 Tool Groups)

Every one of the 206 tools now returns structured {success: false, error: "..."} responses instead of throwing raw MCP exceptions. Agents get actionable context with clear error messages, suggestions, and P154 object-existence verification instead of cryptic PostgreSQL error codes.

Scope of changes:

• Core tools (8 tools) — pg_read_query, pg_write_query, pg_describe_table, pg_create_table, pg_create_index, pg_object_details, pg_analyze_query_indexes, pg_batch_insert
• Transaction tools (7 tools) — All transaction handlers now return structured errors with autoRolledBack context
• JSONB tools (19 tools) — Schema validation, fake schema detection, JSONPath syntax errors
• Text tools (8 tools) — Tsvector column detection, SQL injection pattern rejection
• Performance tools (6 tools) — Nonexistent tables, syntax errors, explain failures
• Stats tools (8 tools) — Table existence, column validation, numeric type checks
• PostGIS tools (11 tools) — Coordinate validation, WKT/GeoJSON parse errors, SRID auto-detection
• Admin tools (6 tools) — Vacuum, analyze, reindex, cluster, config errors
• Schema tools (6 tools) — Object-type-specific error messages (schema/sequence/view)
• Partitioning tools (4 tools) — Overlapping bounds, PK validation, already-attached partitions
• Backup tools (2 tools) — Dump and copy export errors
• Convenience tools (5 tools) — validateTableExists() now returns errors instead of throwing
• Extension tools — Cron (4), Partman (6), Kcache (6), Citext (4), Ltree (4), Pgcrypto (2), Vector (5)

🔧 Universal Split Schema Pattern

Applied the Split Schema pattern to 22+ remaining tools that used z.preprocess() directly as inputSchema. MCP clients now correctly see all tool parameters via JSON Schema generation.

🔒 Security

• pg_transaction_execute isolation level injection — isolationLevel now uses z.enum() instead of z.string(), preventing arbitrary strings from reaching SQL interpolation
• pg_create_sequence unsanitized ownedBy — Now validated and sanitized through sanitizeIdentifier() before SQL interpolation
• Schema tools SQL parameterization — Converted all SQL string interpolation in schema tool existence checks to parameterized queries ($1, $2)

⚡ Performance

• pg_stat_activity background worker noise — Filters out background workers (checkpointer, bgwriter, walwriter, etc.) that had all-null fields inflating the payload
• pg_query_plan_compare verbose payload — Strips zero-value block statistics, empty triggers arrays, and empty planning objects from EXPLAIN plan JSON

📦 Dependencies

• ESLint 9 → 10 migration with 20 lint error fixes (no-useless-assignment, preserve-caught-error)
• @types/node 25.2.3 → 25.3.0, eslint 10.0.0 → 10.0.1, typescript-eslint 8.55.0 → 8.56.0
• Security audit fixes: ajv, hono, qs transitive dependency upgrades; minimatch npm override for ReDoS CVE

📖 Documentation

• New "What Sets Us Apart" feature-matrix table in README.md and DOCKER_README.md
• "Deterministic Error Handling" highlighted as a core differentiating feature
• Comprehensive ServerInstructions.ts response structure documentation for all tool groups

Breaking Changes

None. All changes are backwards-compatible. Tools that previously threw raw exceptions now return structured {success: false, error} objects, which is strictly more information than before.

Install / Upgrade

# npm
npm install -g @neverinfamous/postgres-mcp@1.3.0

# Docker
docker pull writenotenow/postgres-mcp:v1.3.0

Full changelog: CHANGELOG.md