@neverinfamous/postgres-mcp 1.2.0 → 2.0.0

package/README.md

@@ -2,38 +2,108 @@
 
 <!-- mcp-name: io.github.neverinfamous/postgres-mcp -->
 
-**Last Updated February 10, 2026**
+**Last Updated March 2, 2026**
 
-**PostgreSQL MCP Server** enabling AI assistants (AntiGravity, Claude, Cursor, etc.) to interact with PostgreSQL databases through the Model Context Protocol. Features connection pooling, HTTP/SSE Transport, OAuth 2.1 authentication, Code Mode, tool filtering, and extension support for citext, ltree, pgcrypto, pg_cron, pg_stat_kcache, pgvector, PostGIS, and HypoPG.
+**PostgreSQL MCP Server** enabling AI assistants (AntiGravity, Claude, Cursor, etc.) to interact with PostgreSQL databases through the Model Context Protocol. Features **Code Mode** — a revolutionary approach that provides access to all 227 tools through a single, secure JavaScript sandbox, eliminating the massive token overhead of multi-step tool calls. Also includes schema introspection and migration tracking, smart tool filtering, deterministic error handling, connection pooling, HTTP/SSE Transport, OAuth 2.1 authentication, and extension support for citext, ltree, pgcrypto, pg_cron, pg_stat_kcache, pgvector, PostGIS, and HypoPG.
 
-**206 specialized tools** · **20 resources** · **19 AI-powered prompts**
+**227 Specialized Tools** · **20 Resources** · **19 AI-Powered Prompts**
 
-[![GitHub](https://img.shields.io/badge/GitHub-neverinfamous/postgres--mcp-blue?logo=github)](https://github.com/neverinfamous/postgresql-mcp)
-![GitHub Release](https://img.shields.io/github/v/release/neverinfamous/postgresql-mcp)
+[![GitHub](https://img.shields.io/badge/GitHub-neverinfamous/postgres--mcp-blue?logo=github)](https://github.com/neverinfamous/postgres-mcp)
+![GitHub Release](https://img.shields.io/github/v/release/neverinfamous/postgres-mcp)
 [![Docker Pulls](https://img.shields.io/docker/pulls/writenotenow/postgres-mcp)](https://hub.docker.com/r/writenotenow/postgres-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![MCP](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/postgres-mcp)
 [![npm](https://img.shields.io/npm/v/@neverinfamous/postgres-mcp)](https://www.npmjs.com/package/@neverinfamous/postgres-mcp)
-[![Security](https://img.shields.io/badge/Security-Enhanced-green.svg)](https://github.com/neverinfamous/postgresql-mcp/blob/master/SECURITY.md)
+[![Security](https://img.shields.io/badge/Security-Enhanced-green.svg)](https://github.com/neverinfamous/postgres-mcp/blob/main/SECURITY.md)
 ![Status](https://img.shields.io/badge/status-Production%2FStable-brightgreen)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://github.com/neverinfamous/postgresql-mcp)
-[![Tests](https://img.shields.io/badge/Tests-2108_passed-success.svg)](https://github.com/neverinfamous/postgresql-mcp)
-[![Coverage](https://img.shields.io/badge/Coverage-84.5%25-green.svg)](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)** • **[MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/postgres-mcp)** • **[Wiki](https://github.com/neverinfamous/postgresql-mcp/wiki)**
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://github.com/neverinfamous/postgres-mcp)
+[![Tests](https://img.shields.io/badge/Tests-3176_passed-success.svg)](https://github.com/neverinfamous/postgres-mcp)
+[![Coverage](https://img.shields.io/badge/Coverage-93.58%25-brightgreen.svg)](https://github.com/neverinfamous/postgres-mcp)
+
+**[Docker Hub](https://hub.docker.com/r/writenotenow/postgres-mcp)** • **[npm Package](https://www.npmjs.com/package/@neverinfamous/postgres-mcp)** • **[MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/postgres-mcp)** • **[Wiki](https://github.com/neverinfamous/postgres-mcp/wiki)** • **[Changelog](https://github.com/neverinfamous/postgres-mcp/blob/main/CHANGELOG.md)**
+
+## 🎯 What Sets Us Apart
+
+| Feature                                | Description                                                                                                                                                                                                                                                                                                  |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **227 Specialized Tools**              | The largest PostgreSQL tool collection for MCP — from core CRUD and native JSONB to pgvector, PostGIS, pg_cron, ltree, pgcrypto, introspection analysis, schema version tracking, and 8 extension ecosystems                                                                                                 |
+| **20 Observability Resources**         | Real-time schema, performance metrics, connection pool status, replication lag, vacuum stats, lock contention, and extension diagnostics                                                                                                                                                                     |
+| **19 AI-Powered Prompts**              | Guided workflows for query building, schema design, performance tuning, and extension setup                                                                                                                                                                                                                  |
+| **Code Mode**                          | **Massive Token Savings:** Execute complex, multi-step operations inside a fast, secure JavaScript sandbox. Instead of spending thousands of tokens on back-and-forth tool calls, Code Mode exposes all 227 capabilities locally, reducing token overhead by up to 90% and supercharging AI agent reasoning. |
+| **OAuth 2.1 + Access Control**         | Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (`read`, `write`, `admin`, `full`, `db:*`, `table:*:*`), and Keycloak integration                                                                                                                                                   |
+| **Smart Tool Filtering**               | 21 tool groups + 16 shortcuts let you stay within IDE limits while exposing exactly what you need                                                                                                                                                                                                            |
+| **HTTP Streaming Transport**           | SSE-based streaming with `/mcp`, and `/health` endpoints for remote deployments                                                                                                                                                                                                                              |
+| **High-Performance Pooling**           | Built-in connection pooling with health checks for efficient, concurrent database access                                                                                                                                                                                                                     |
+| **8 Extension Ecosystems**             | First-class support for **pgvector**, **PostGIS**, **pg_cron**, **pg_partman**, **pg_stat_kcache**, **citext**, **ltree**, and **pgcrypto**                                                                                                                                                                  |
+| **Introspection & Migration Tracking** | Simulate cascade impacts, generate safe DDL ordering, analyze constraint health, and track schema migrations with SHA-256 dedup — 12 agent-optimized tools that let AI assistants reason about schema changes before executing them                                                                          |
+| **Deterministic Error Handling**       | Every tool returns structured `{success, error}` responses — no raw exceptions, no silent failures, no misleading messages. Agents get actionable context instead of cryptic PostgreSQL codes                                                                                                                |
+| **Production-Ready Security**          | SQL injection protection, parameterized queries, input validation, sandboxed code execution, SSL certificate verification by default, and HTTP body size enforcement                                                                                                                                         |
+| **Strict TypeScript**                  | 100% type-safe codebase with 3176 tests and 93.58% coverage                                                                                                                                                                                                                                                  |
+| **MCP 2025-11-25 Compliant**           | Full protocol support with tool safety hints, resource priorities, and progress notifications                                                                                                                                                                                                                |
 
 ## 🚀 Quick Start
 
 ### Prerequisites
 
-- Node.js 24+ (LTS)
 - PostgreSQL 12-18 (tested with PostgreSQL 18.1)
-- npm or yarn
+- **Docker** (recommended) or Node.js 24+ (LTS)
 
-### Installation
+### Docker (Recommended)
 
 ```bash
-git clone https://github.com/neverinfamous/postgresql-mcp.git
+docker pull writenotenow/postgres-mcp:latest
+```
+
+```json
+{
+  "mcpServers": {
+    "postgres-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "POSTGRES_HOST",
+        "-e",
+        "POSTGRES_PORT",
+        "-e",
+        "POSTGRES_USER",
+        "-e",
+        "POSTGRES_PASSWORD",
+        "-e",
+        "POSTGRES_DATABASE",
+        "writenotenow/postgres-mcp:latest",
+        "--tool-filter",
+        "starter"
+      ],
+      "env": {
+        "POSTGRES_HOST": "host.docker.internal",
+        "POSTGRES_PORT": "5432",
+        "POSTGRES_USER": "your_username",
+        "POSTGRES_PASSWORD": "your_password",
+        "POSTGRES_DATABASE": "your_database"
+      }
+    }
+  }
+}
+```
+
+> **Note for Docker**: Use `host.docker.internal` to connect to PostgreSQL running on your host machine.
+
+📖 **Full Docker guide:** [DOCKER_README.md](DOCKER_README.md) · [Docker Hub](https://hub.docker.com/r/writenotenow/postgres-mcp)
+
+### npm
+
+```bash
+npm install -g @neverinfamous/postgres-mcp
+postgres-mcp --transport stdio --postgres postgres://user:password@localhost:5432/database
+```
+
+### From Source
+
+```bash
+git clone https://github.com/neverinfamous/postgres-mcp.git
 cd postgres-mcp
 npm install
 npm run build
@@ -42,35 +112,87 @@ node dist/cli.js --transport stdio --postgres postgres://user:password@localhost
 
 ---
 
-## Development
+## Code Mode: Maximum Efficiency
 
-**Clone and install:**
+Code Mode (`pg_execute_code`) dramatically reduces token usage (70–90%) and is included by default in all presets.
 
-```bash
-git clone https://github.com/neverinfamous/postgresql-mcp.git
-cd postgres-mcp
-npm install
-```
+Code executes in a **sandboxed VM context** with multiple layers of security. All `pg.*` API calls execute against the database within the sandbox, providing:
 
-**Build:**
+- **Static code validation** — blocked patterns include `require()`, `process`, `eval()`, and filesystem access
+- **Rate limiting** — 60 executions per minute per client
+- **Hard timeouts** — configurable execution limit (default 30s)
+- **Full API access** — all 20 tool groups are available via `pg.*` (e.g., `pg.core.readQuery()`, `pg.jsonb.extract()`, `pg.introspection.dependencyGraph()`)
+- **Requires `admin` OAuth scope** — execution is logged for audit
 
-```bash
-npm run build
+### ⚡ Code Mode Only (Maximum Token Savings)
+
+If you control your own setup, you can run with **only Code Mode enabled** — a single tool that provides access to all 227 tools' worth of capability through the `pg.*` API:
+
+```json
+{
+  "mcpServers": {
+    "postgres-mcp": {
+      "command": "node",
+      "args": [
+        "/path/to/postgres-mcp/dist/cli.js",
+        "--transport",
+        "stdio",
+        "--tool-filter",
+        "codemode"
+      ],
+      "env": {
+        "POSTGRES_HOST": "localhost",
+        "POSTGRES_PORT": "5432",
+        "POSTGRES_USER": "your_user",
+        "POSTGRES_PASSWORD": "your_password",
+        "POSTGRES_DATABASE": "your_database"
+      }
+    }
+  }
+}
 ```
 
-**Run checks:**
+This exposes just `pg_execute_code`. The agent writes JavaScript against the typed `pg.*` SDK — composing queries, chaining operations across all 20 tool groups, and returning exactly the data it needs — in one execution. This mirrors the [Code Mode pattern](https://blog.cloudflare.com/code-mode-mcp/) pioneered by Cloudflare for their entire API: fixed token cost regardless of how many capabilities exist.
 
-```bash
-npm run lint && npm run typecheck
+> [!TIP]
+> **Maximize Token Savings:** Instruct your AI agent to prefer Code Mode over individual tool calls:
+>
+> _"When using postgres-mcp, prefer `pg_execute_code` (Code Mode) for multi-step database operations to minimize token usage."_
+>
+> For maximum savings, use `--tool-filter codemode` to run with Code Mode as your only tool. See the [Code Mode wiki](https://github.com/neverinfamous/postgres-mcp/wiki/Code-Mode) for full API documentation.
+
+> [!NOTE]
+> **AntiGravity Users:** Server instructions are automatically sent to MCP clients during initialization. However, AntiGravity does not currently support MCP server instructions. For optimal Code Mode usage in AntiGravity, manually provide the contents of [`src/constants/ServerInstructions.ts`](src/constants/ServerInstructions.ts) to the agent in your prompt or user rules.
+
+#### Disabling Code Mode (Non-Admin Users)
+
+If you don't have admin access or prefer individual tool calls, exclude codemode:
+
+```json
+{
+  "args": ["--tool-filter", "starter,-codemode"]
+}
 ```
 
-**Test CLI:**
+📖 **Full documentation:** [docs/CODE_MODE.md](docs/CODE_MODE.md)
+
+---
+
+## Development
+
+See **[From Source](#from-source)** above for setup. After cloning:
 
 ```bash
-node dist/cli.js info
-node dist/cli.js list-tools
+npm run lint && npm run typecheck  # Run checks
+npm run bench                      # Run performance benchmarks
+node dist/cli.js info              # Test CLI
+node dist/cli.js list-tools        # List available tools
 ```
 
+### Benchmarks
+
+Run `npm run bench` to execute the performance benchmark suite (9 files, 75+ scenarios) powered by [Vitest Bench](https://vitest.dev/guide/features.html#benchmarking). Benchmarks cover schema parsing, handler dispatch, identifier sanitization, auth middleware, connection pooling, Code Mode, logging, and more. Use `npm run bench:verbose` for detailed table output.
+
 ---
 
 ## ⚡ MCP Client Configuration
@@ -141,53 +263,10 @@ node dist/cli.js list-tools
 
 ---
 
-## Code Mode: Maximum Efficiency
-
-Code Mode (`pg_execute_code`) dramatically reduces token usage (70–90%) and is included by default in all presets.
-
-> [!TIP]
-> **Maximize Token Savings:** For the best results, instruct your AI agent to prefer Code Mode over individual tool calls. Add a rule like this to your agent's prompt or system configuration:
->
-> _"When using postgres-mcp, prefer `pg_execute_code` (Code Mode) for multi-step database operations to minimize token usage."_
->
-> This ensures the agent batches operations into single calls instead of making many individual tool calls. See the [Code Mode wiki](https://github.com/neverinfamous/postgresql-mcp/wiki/Code-Mode) for full API documentation.
-
-> [!NOTE]
-> **AntiGravity Users:** Server instructions are automatically sent to MCP clients during initialization. However, AntiGravity does not currently support MCP server instructions. For optimal Code Mode usage in AntiGravity, manually provide the contents of [`src/constants/ServerInstructions.ts`](src/constants/ServerInstructions.ts) to the agent in your prompt or user rules.
-
-#### Disabling Code Mode (Non-Admin Users)
-
-If you don't have admin access or prefer individual tool calls, exclude codemode:
-
-```json
-{
-  "args": ["--tool-filter", "starter,-codemode"]
-}
-```
-
-### Isolation Modes
-
-| Mode     | Isolation          | When to Use                  |
-| -------- | ------------------ | ---------------------------- |
-| `vm`     | Same process       | **Default, recommended**     |
-| `worker` | Separate V8 thread | Not recommended (incomplete) |
-
-The `vm` mode is fully functional and is the default. No configuration needed.
-
-### Security
-
-- Requires `admin` OAuth scope
-- Blocked: `require()`, `process`, `eval()`, filesystem
-- Rate limited: 60 executions/minute
-
-📖 **Full documentation:** [docs/CODE_MODE.md](docs/CODE_MODE.md)
-
----
-
 ## 🛠️ Tool Filtering
 
 > [!IMPORTANT]
-> AI IDEs like Cursor have tool limits. With 206 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend `starter` (59 tools) as a starting point. Code Mode is included in all presets by default for 70-90% token savings on multi-step operations.
+> AI IDEs like Cursor have tool limits. With 227 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend `starter` (59 tools) as a starting point. Code Mode is included in all presets by default for 70-90% token savings on multi-step operations.
 
 ### What Can You Filter?
 
@@ -206,50 +285,52 @@ All shortcuts and tool groups include **Code Mode** (`pg_execute_code`) by defau
 
 > Tool counts include Code Mode (`pg_execute_code`) which is included in all presets by default.
 
-| Shortcut       | Tools  | Use Case                 | What's Included                                          |
-| -------------- | ------ | ------------------------ | -------------------------------------------------------- |
-| `starter`      | **59** | 🌟 **Recommended**       | Core, trans, JSONB, schema, codemode                     |
-| `essential`    | 47     | Minimal footprint        | Core, trans, JSONB, codemode                             |
-| `dev-power`    | 54     | Power Developer          | Core, trans, schema, stats, part, codemode               |
-| `ai-data`      | 60     | AI Data Analyst          | Core, JSONB, text, trans, codemode                       |
-| `ai-vector`    | 50     | AI/ML with pgvector      | Core, vector, trans, part, codemode                      |
-| `dba-monitor`  | 59     | DBA Monitoring           | Core, monitoring, perf, trans, codemode                  |
-| `dba-manage`   | 58     | DBA Management           | Core, admin, backup, part, schema, codemode              |
-| `dba-stats`    | 57     | DBA Stats/Security       | Core, admin, monitoring, trans, stats, codemode          |
-| `geo`          | 43     | Geospatial Workloads     | Core, PostGIS, trans, codemode                           |
-| `base-core`    | 59     | Base Building Block      | Core, JSONB, trans, schema, codemode                     |
-| `base-ops`     | 51     | Operations Block         | Admin, monitoring, backup, part, stats, citext, codemode |
-| `ext-ai`       | 26     | Extension: AI/Security   | pgvector, pgcrypto, codemode                             |
-| `ext-geo`      | 24     | Extension: Spatial       | PostGIS, ltree, codemode                                 |
-| `ext-schedule` | 19     | Extension: Scheduling    | pg_cron, pg_partman, codemode                            |
-| `ext-perf`     | 28     | Extension: Perf/Analysis | pg_stat_kcache, performance, codemode                    |
-
-### Tool Groups (20 Available)
+| Shortcut        | Tools  | Use Case                 | What's Included                                          |
+| --------------- | ------ | ------------------------ | -------------------------------------------------------- |
+| `starter`       | **59** | 🌟 **Recommended**       | Core, trans, JSONB, schema, codemode                     |
+| `essential`     | 47     | Minimal footprint        | Core, trans, JSONB, codemode                             |
+| `dev-schema`    | 52     | Dev Schema & Migrations  | Core, trans, schema, introspection, codemode             |
+| `dev-analytics` | 42     | Dev Analytics            | Core, trans, stats, partitioning, codemode               |
+| `ai-data`       | 60     | AI Data Analyst          | Core, JSONB, text, trans, codemode                       |
+| `ai-vector`     | 50     | AI/ML with pgvector      | Core, vector, trans, part, codemode                      |
+| `dba-monitor`   | 59     | DBA Monitoring           | Core, monitoring, perf, trans, codemode                  |
+| `dba-schema`    | 45     | DBA Schema & Migrations  | Core, schema, introspection, codemode                    |
+| `dba-infra`     | 46     | DBA Infrastructure       | Core, admin, backup, partitioning, codemode              |
+| `dba-stats`     | 57     | DBA Stats                | Core, admin, monitoring, trans, stats, codemode          |
+| `geo`           | 43     | Geospatial Workloads     | Core, PostGIS, trans, codemode                           |
+| `base-ops`      | 51     | Operations Block         | Admin, monitoring, backup, part, stats, citext, codemode |
+| `ext-ai`        | 26     | Extension: AI/Security   | pgvector, pgcrypto, codemode                             |
+| `ext-geo`       | 24     | Extension: Spatial       | PostGIS, ltree, codemode                                 |
+| `ext-schedule`  | 19     | Extension: Scheduling    | pg_cron, pg_partman, codemode                            |
+| `ext-perf`      | 28     | Extension: Perf/Analysis | pg_stat_kcache, performance, codemode                    |
+
+### Tool Groups (21 Available)
 
 > Tool counts include Code Mode (`pg_execute_code`) which is added to all groups by default.
 
-| Group          | Tools | Description                                                 |
-| -------------- | ----- | ----------------------------------------------------------- |
-| `core`         | 21    | Read/write queries, tables, indexes, convenience/drop tools |
-| `transactions` | 8     | BEGIN, COMMIT, ROLLBACK, savepoints                         |
-| `jsonb`        | 20    | JSONB manipulation and queries                              |
-| `text`         | 14    | Full-text search, fuzzy matching                            |
-| `performance`  | 21    | EXPLAIN, query analysis, optimization                       |
-| `admin`        | 11    | VACUUM, ANALYZE, REINDEX                                    |
-| `monitoring`   | 12    | Database sizes, connections, status                         |
-| `backup`       | 10    | pg_dump, COPY, restore                                      |
-| `schema`       | 13    | Schemas, views, sequences, functions, triggers              |
-| `partitioning` | 7     | Native partition management                                 |
-| `stats`        | 9     | Statistical analysis                                        |
-| `vector`       | 17    | pgvector (AI/ML similarity search)                          |
-| `postgis`      | 16    | PostGIS (geospatial)                                        |
-| `cron`         | 9     | pg_cron (job scheduling)                                    |
-| `partman`      | 11    | pg_partman (auto-partitioning)                              |
-| `kcache`       | 8     | pg_stat_kcache (OS-level stats)                             |
-| `citext`       | 7     | citext (case-insensitive text)                              |
-| `ltree`        | 9     | ltree (hierarchical data)                                   |
-| `pgcrypto`     | 10    | pgcrypto (encryption, UUIDs)                                |
-| `codemode`     | 1     | Code Mode (sandboxed code execution)                        |
+| Group           | Tools | Description                                                 |
+| --------------- | ----- | ----------------------------------------------------------- |
+| `codemode`      | 1     | Code Mode (sandboxed code execution)                        |
+| `core`          | 21    | Read/write queries, tables, indexes, convenience/drop tools |
+| `transactions`  | 8     | BEGIN, COMMIT, ROLLBACK, savepoints                         |
+| `jsonb`         | 20    | JSONB manipulation and queries                              |
+| `text`          | 14    | Full-text search, fuzzy matching                            |
+| `performance`   | 21    | EXPLAIN, query analysis, optimization                       |
+| `admin`         | 11    | VACUUM, ANALYZE, REINDEX                                    |
+| `monitoring`    | 12    | Database sizes, connections, status                         |
+| `backup`        | 10    | pg_dump, COPY, restore                                      |
+| `schema`        | 13    | Schemas, views, sequences, functions, triggers              |
+| `introspection` | 13    | Dependency graphs, cascade simulation, migration tracking   |
+| `partitioning`  | 7     | Native partition management                                 |
+| `stats`         | 9     | Statistical analysis                                        |
+| `vector`        | 17    | pgvector (AI/ML similarity search)                          |
+| `postgis`       | 16    | PostGIS (geospatial)                                        |
+| `cron`          | 9     | pg_cron (job scheduling)                                    |
+| `partman`       | 11    | pg_partman (auto-partitioning)                              |
+| `kcache`        | 8     | pg_stat_kcache (OS-level stats)                             |
+| `citext`        | 7     | citext (case-insensitive text)                              |
+| `ltree`         | 9     | ltree (hierarchical data)                                   |
+| `pgcrypto`      | 10    | pgcrypto (encryption, UUIDs)                                |
 
 ---
 
@@ -399,6 +480,9 @@ The server exposes metadata at `/.well-known/oauth-protected-resource`.
 
 > **Note for Keycloak users:** Add an **Audience mapper** to your client (Client → Client scopes → dedicated scope → Add mapper → Audience) to include the correct `aud` claim in tokens.
 
+> [!NOTE]
+> **Per-tool scope enforcement:** Scopes are enforced at the tool level — each tool group maps to a required scope (`read`, `write`, or `admin`). When OAuth is enabled, every tool invocation checks the calling token's scopes before execution. When OAuth is not configured, scope checks are skipped entirely.
+
 ---
 
 ## ⚡ Performance Tuning
@@ -429,7 +513,7 @@ This server includes **19 intelligent prompts** for guided workflows:
 | `pg_quick_query`           | Quick SQL query guidance for common operations     | core                          | `starter`      |
 | `pg_quick_schema`          | Quick reference for exploring database schema      | core                          | `starter`      |
 | `pg_database_health_check` | Comprehensive database health assessment           | core, performance, monitoring | `dba-monitor`  |
-| `pg_backup_strategy`       | Enterprise backup planning with RTO/RPO            | core, monitoring, backup      | `dba-manage`   |
+| `pg_backup_strategy`       | Enterprise backup planning with RTO/RPO            | core, monitoring, backup      | `dba-infra`    |
 | `pg_index_tuning`          | Index analysis and optimization workflow           | core, performance             | `dba-monitor`  |
 | `pg_extension_setup`       | Extension installation and configuration guide     | core                          | `starter`      |
 | `pg_setup_pgvector`        | Complete pgvector setup for semantic search        | core, vector                  | `ai-vector`    |
@@ -491,37 +575,7 @@ This server provides **20 resources** for structured data access:
 | `ltree`              | Hierarchical tree labels       | 8 ltree tools              |
 | `pgcrypto`           | Hashing, encryption, UUIDs     | 9 pgcrypto tools           |
 
-> Extension tools gracefully handle cases where extensions are not installed.
-
----
-
-## 🔥 Core Capabilities
-
-- 📊 **Full SQL Support** - Execute any PostgreSQL query with parameter binding
-- 🔍 **JSONB Operations** - Native JSONB functions and path queries
-- 🔐 **Connection Pooling** - Efficient connection management with health checks
-- 🎛️ **Tool Filtering** - Control which operations are exposed
-- ⚡ **Performance Tools** - EXPLAIN ANALYZE, buffer analysis, index hints
-- 🗺️ **PostGIS Support** - Geospatial queries and spatial indexes
-- 🧠 **pgvector Support** - AI/ML vector similarity search
-
-### 🏢 Enterprise Features
-
-- 🔐 **OAuth 2.1 Authentication** - RFC 9728/8414 compliant
-- 🛡️ **Tool Filtering** - Control which database operations are exposed
-- 📈 **Monitoring** - Process lists, replication lag, cache hit ratios
-
----
-
-## 🏆 Why Choose postgres-mcp?
-
-✅ **TypeScript Native** - Full type safety with strict mode  
-✅ **206 Specialized Tools** - Comprehensive PostgreSQL coverage  
-✅ **Tool Annotations** - UX hints for read-only, destructive, and idempotent operations  
-✅ **Connection Pooling** - Efficient PostgreSQL connection management  
-✅ **Extension Support** - pgvector, PostGIS, pg_stat_statements, pg_cron  
-✅ **Tool Filtering** - Stay within AI IDE tool limits  
-✅ **Modern Architecture** - Built on MCP SDK 1.25+
+> Extension tools gracefully handle cases where extensions are not installed. Extension tool counts include `create_extension` helpers but exclude Code Mode; the [Tool Groups](#-tool-filtering) table above adds +1 per group for Code Mode.
 
 ---
 

package/dist/__tests__/benchmarks/codemode.bench.d.ts

@@ -0,0 +1,10 @@
+/**
+ * postgres-mcp - Code Mode Sandbox Performance Benchmarks
+ *
+ * Measures VM context creation, sandbox pool lifecycle, security
+ * validation, and execution overhead using vitest bench (tinybench).
+ *
+ * Run: npm run bench
+ */
+export {};
+//# sourceMappingURL=codemode.bench.d.ts.map

package/dist/__tests__/benchmarks/codemode.bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codemode.bench.d.ts","sourceRoot":"","sources":["../../../src/__tests__/benchmarks/codemode.bench.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/__tests__/benchmarks/codemode.bench.js

@@ -0,0 +1,159 @@
+/**
+ * postgres-mcp - Code Mode Sandbox Performance Benchmarks
+ *
+ * Measures VM context creation, sandbox pool lifecycle, security
+ * validation, and execution overhead using vitest bench (tinybench).
+ *
+ * Run: npm run bench
+ */
+import { describe, bench, beforeEach, afterEach, vi } from "vitest";
+import { CodeModeSandbox, SandboxPool } from "../../codemode/sandbox.js";
+import { CodeModeSecurityManager } from "../../codemode/security.js";
+// Suppress logger stderr output during benchmarks
+vi.mock("../../utils/logger.js", () => ({
+    logger: {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        warning: vi.fn(),
+        error: vi.fn(),
+        notice: vi.fn(),
+        critical: vi.fn(),
+        alert: vi.fn(),
+        emergency: vi.fn(),
+        setLevel: vi.fn(),
+        setMcpServer: vi.fn(),
+    },
+}));
+// ---------------------------------------------------------------------------
+// 1. Sandbox Creation
+// ---------------------------------------------------------------------------
+describe("Sandbox Creation", () => {
+    bench("CodeModeSandbox.create() cold start", () => {
+        const sandbox = CodeModeSandbox.create();
+        sandbox.dispose();
+    }, { iterations: 200, warmupIterations: 5 });
+    bench("sandbox dispose() (idempotent)", () => {
+        const sandbox = CodeModeSandbox.create();
+        sandbox.dispose();
+        sandbox.dispose(); // Idempotent call
+    }, { iterations: 200, warmupIterations: 5 });
+});
+// ---------------------------------------------------------------------------
+// 2. Sandbox Pool Lifecycle
+// ---------------------------------------------------------------------------
+describe("SandboxPool Lifecycle", () => {
+    bench("pool initialization (minInstances=2)", () => {
+        const pool = new SandboxPool({ minInstances: 2, maxInstances: 10, idleTimeoutMs: 60000 }, { timeoutMs: 30000, memoryLimitMb: 128, cpuLimitMs: 10000 });
+        pool.initialize();
+        pool.dispose();
+    }, { iterations: 100, warmupIterations: 3 });
+    let sandboxPool;
+    describe("pool operations", () => {
+        beforeEach(() => {
+            sandboxPool = new SandboxPool({ minInstances: 2, maxInstances: 10, idleTimeoutMs: 60000 }, { timeoutMs: 30000, memoryLimitMb: 128, cpuLimitMs: 10000 });
+            sandboxPool.initialize();
+        });
+        afterEach(() => {
+            sandboxPool?.dispose();
+        });
+        bench("acquire/release round trip", () => {
+            const sandbox = sandboxPool.acquire();
+            sandboxPool.release(sandbox);
+        }, { iterations: 1000, warmupIterations: 10 });
+        bench("getStats() overhead", () => {
+            sandboxPool.getStats();
+        }, { iterations: 5000, warmupIterations: 20 });
+    });
+});
+// ---------------------------------------------------------------------------
+// 3. Sandbox Execution
+// ---------------------------------------------------------------------------
+describe("Sandbox Execution", () => {
+    let sandbox;
+    beforeEach(() => {
+        sandbox = CodeModeSandbox.create();
+    });
+    afterEach(() => {
+        sandbox?.dispose();
+    });
+    bench('trivial code execution ("return 42")', async () => {
+        await sandbox.execute("return 42;", {});
+    }, { iterations: 30, warmupIterations: 3, time: 5000 });
+    bench("execution with 20-group API bindings", async () => {
+        const apiBindings = {};
+        const groupNames = [
+            "core",
+            "transactions",
+            "jsonb",
+            "text",
+            "performance",
+            "admin",
+            "monitoring",
+            "backup",
+            "schema",
+            "partitioning",
+            "stats",
+            "vector",
+            "postgis",
+            "cron",
+            "partman",
+            "kcache",
+            "citext",
+            "ltree",
+            "pgcrypto",
+            "codemode",
+        ];
+        for (const group of groupNames) {
+            apiBindings[group] = {
+                readQuery: () => ({ rows: [], rowCount: 0 }),
+                writeQuery: () => ({ rowsAffected: 0 }),
+                help: () => [],
+            };
+        }
+        await sandbox.execute("const result = pg.core.readQuery(); return result;", apiBindings);
+    }, { iterations: 20, warmupIterations: 3, time: 5000 });
+    bench("console output capture", async () => {
+        await sandbox.execute('console.log("test output"); console.warn("warning");', {});
+        sandbox.clearConsoleOutput();
+    }, { iterations: 30, warmupIterations: 3, time: 5000 });
+});
+// ---------------------------------------------------------------------------
+// 4. Security Validation
+// ---------------------------------------------------------------------------
+describe("Security Validation", () => {
+    const security = new CodeModeSecurityManager();
+    bench("validateCode() safe short code (50 chars)", () => {
+        security.validateCode('const result = await pg.core.readQuery("SELECT 1");');
+    }, { iterations: 5000, warmupIterations: 50 });
+    bench("validateCode() safe large code (10KB)", () => {
+        const lines = [];
+        for (let i = 0; i < 200; i++) {
+            lines.push(`const result${String(i)} = await pg.core.readQuery("SELECT * FROM table${String(i)} LIMIT 10");`);
+        }
+        security.validateCode(lines.join("\n"));
+    }, { iterations: 1000, warmupIterations: 10 });
+    bench("validateCode() blocked code (early rejection)", () => {
+        security.validateCode('require("fs").readFileSync("/etc/passwd")');
+    }, { iterations: 5000, warmupIterations: 50 });
+    bench("checkRateLimit() throughput", () => {
+        const secManager = new CodeModeSecurityManager({
+            maxExecutionsPerMinute: 10000,
+        });
+        secManager.checkRateLimit("client-1");
+    }, { iterations: 5000, warmupIterations: 50 });
+    bench("sanitizeResult() small payload", () => {
+        security.sanitizeResult({ users: [{ id: 1, name: "test" }] });
+    }, { iterations: 3000, warmupIterations: 30 });
+    bench("sanitizeResult() medium payload (100 rows)", () => {
+        const medium = {
+            data: Array.from({ length: 100 }, (_, i) => ({
+                id: i,
+                name: `user_${String(i)}`,
+                email: `user${String(i)}@example.com`,
+            })),
+        };
+        security.sanitizeResult(medium);
+    }, { iterations: 1000, warmupIterations: 10 });
+});
+//# sourceMappingURL=codemode.bench.js.map

package/dist/__tests__/benchmarks/codemode.bench.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codemode.bench.js","sourceRoot":"","sources":["../../../src/__tests__/benchmarks/codemode.bench.ts"],"names":[],"mappings":"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"}