# 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
```bash
# npm
npm install -g @neverinfamous/postgres-mcp@1.3.0
# Docker
docker pull writenotenow/postgres-mcp:v1.3.0
```
**Full changelog:** [CHANGELOG.md](https://github.com/neverinfamous/postgresql-mcp/blob/master/CHANGELOG.md)
