@neverinfamous/postgres-mcp 1.3.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +177 -129
- package/dist/__tests__/benchmarks/codemode.bench.d.ts +10 -0
- package/dist/__tests__/benchmarks/codemode.bench.d.ts.map +1 -0
- package/dist/__tests__/benchmarks/codemode.bench.js +159 -0
- package/dist/__tests__/benchmarks/codemode.bench.js.map +1 -0
- package/dist/__tests__/benchmarks/connection-pool.bench.d.ts +10 -0
- package/dist/__tests__/benchmarks/connection-pool.bench.d.ts.map +1 -0
- package/dist/__tests__/benchmarks/connection-pool.bench.js +123 -0
- package/dist/__tests__/benchmarks/connection-pool.bench.js.map +1 -0
- package/dist/__tests__/benchmarks/handler-dispatch.bench.d.ts +11 -0
- package/dist/__tests__/benchmarks/handler-dispatch.bench.d.ts.map +1 -0
- package/dist/__tests__/benchmarks/handler-dispatch.bench.js +199 -0
- package/dist/__tests__/benchmarks/handler-dispatch.bench.js.map +1 -0
- package/dist/__tests__/benchmarks/logger-sanitization.bench.d.ts +15 -0
- package/dist/__tests__/benchmarks/logger-sanitization.bench.d.ts.map +1 -0
- package/dist/__tests__/benchmarks/logger-sanitization.bench.js +155 -0
- package/dist/__tests__/benchmarks/logger-sanitization.bench.js.map +1 -0
- package/dist/__tests__/benchmarks/resource-prompts.bench.d.ts +10 -0
- package/dist/__tests__/benchmarks/resource-prompts.bench.d.ts.map +1 -0
- package/dist/__tests__/benchmarks/resource-prompts.bench.js +181 -0
- package/dist/__tests__/benchmarks/resource-prompts.bench.js.map +1 -0
- package/dist/__tests__/benchmarks/schema-parsing.bench.d.ts +11 -0
- package/dist/__tests__/benchmarks/schema-parsing.bench.d.ts.map +1 -0
- package/dist/__tests__/benchmarks/schema-parsing.bench.js +209 -0
- package/dist/__tests__/benchmarks/schema-parsing.bench.js.map +1 -0
- package/dist/__tests__/benchmarks/tool-filtering.bench.d.ts +9 -0
- package/dist/__tests__/benchmarks/tool-filtering.bench.d.ts.map +1 -0
- package/dist/__tests__/benchmarks/tool-filtering.bench.js +83 -0
- package/dist/__tests__/benchmarks/tool-filtering.bench.js.map +1 -0
- package/dist/__tests__/benchmarks/transport-auth.bench.d.ts +10 -0
- package/dist/__tests__/benchmarks/transport-auth.bench.d.ts.map +1 -0
- package/dist/__tests__/benchmarks/transport-auth.bench.js +128 -0
- package/dist/__tests__/benchmarks/transport-auth.bench.js.map +1 -0
- package/dist/__tests__/benchmarks/utilities.bench.d.ts +10 -0
- package/dist/__tests__/benchmarks/utilities.bench.d.ts.map +1 -0
- package/dist/__tests__/benchmarks/utilities.bench.js +164 -0
- package/dist/__tests__/benchmarks/utilities.bench.js.map +1 -0
- package/dist/adapters/DatabaseAdapter.d.ts.map +1 -1
- package/dist/adapters/DatabaseAdapter.js +12 -0
- package/dist/adapters/DatabaseAdapter.js.map +1 -1
- package/dist/adapters/postgresql/PostgresAdapter.d.ts.map +1 -1
- package/dist/adapters/postgresql/PostgresAdapter.js +3 -0
- package/dist/adapters/postgresql/PostgresAdapter.js.map +1 -1
- package/dist/adapters/postgresql/schemas/backup.d.ts +37 -23
- package/dist/adapters/postgresql/schemas/backup.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/backup.js +53 -22
- package/dist/adapters/postgresql/schemas/backup.js.map +1 -1
- package/dist/adapters/postgresql/schemas/extensions.d.ts +56 -37
- package/dist/adapters/postgresql/schemas/extensions.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/extensions.js +68 -36
- package/dist/adapters/postgresql/schemas/extensions.js.map +1 -1
- package/dist/adapters/postgresql/schemas/index.d.ts +3 -2
- package/dist/adapters/postgresql/schemas/index.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/index.js +8 -2
- package/dist/adapters/postgresql/schemas/index.js.map +1 -1
- package/dist/adapters/postgresql/schemas/introspection.d.ts +445 -0
- package/dist/adapters/postgresql/schemas/introspection.d.ts.map +1 -0
- package/dist/adapters/postgresql/schemas/introspection.js +478 -0
- package/dist/adapters/postgresql/schemas/introspection.js.map +1 -0
- package/dist/adapters/postgresql/schemas/jsonb.d.ts +8 -0
- package/dist/adapters/postgresql/schemas/jsonb.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/jsonb.js +26 -2
- package/dist/adapters/postgresql/schemas/jsonb.js.map +1 -1
- package/dist/adapters/postgresql/schemas/monitoring.d.ts +41 -25
- package/dist/adapters/postgresql/schemas/monitoring.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/monitoring.js +49 -16
- package/dist/adapters/postgresql/schemas/monitoring.js.map +1 -1
- package/dist/adapters/postgresql/schemas/partitioning.d.ts +16 -20
- package/dist/adapters/postgresql/schemas/partitioning.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/partitioning.js +21 -10
- package/dist/adapters/postgresql/schemas/partitioning.js.map +1 -1
- package/dist/adapters/postgresql/schemas/partman.d.ts +69 -0
- package/dist/adapters/postgresql/schemas/partman.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/partman.js +46 -33
- package/dist/adapters/postgresql/schemas/partman.js.map +1 -1
- package/dist/adapters/postgresql/schemas/performance.d.ts +37 -19
- package/dist/adapters/postgresql/schemas/performance.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/performance.js +54 -12
- package/dist/adapters/postgresql/schemas/performance.js.map +1 -1
- package/dist/adapters/postgresql/schemas/postgis.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/postgis.js +20 -0
- package/dist/adapters/postgresql/schemas/postgis.js.map +1 -1
- package/dist/adapters/postgresql/schemas/schema-mgmt.d.ts +15 -7
- package/dist/adapters/postgresql/schemas/schema-mgmt.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/schema-mgmt.js +36 -7
- package/dist/adapters/postgresql/schemas/schema-mgmt.js.map +1 -1
- package/dist/adapters/postgresql/schemas/text-search.d.ts +26 -14
- package/dist/adapters/postgresql/schemas/text-search.d.ts.map +1 -1
- package/dist/adapters/postgresql/schemas/text-search.js +41 -9
- package/dist/adapters/postgresql/schemas/text-search.js.map +1 -1
- package/dist/adapters/postgresql/tools/admin.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/admin.js +82 -67
- package/dist/adapters/postgresql/tools/admin.js.map +1 -1
- package/dist/adapters/postgresql/tools/backup/dump.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/backup/dump.js +27 -24
- package/dist/adapters/postgresql/tools/backup/dump.js.map +1 -1
- package/dist/adapters/postgresql/tools/citext.js +114 -82
- package/dist/adapters/postgresql/tools/citext.js.map +1 -1
- package/dist/adapters/postgresql/tools/codemode/index.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/codemode/index.js +2 -11
- package/dist/adapters/postgresql/tools/codemode/index.js.map +1 -1
- package/dist/adapters/postgresql/tools/core/convenience.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/core/convenience.js +23 -8
- package/dist/adapters/postgresql/tools/core/convenience.js.map +1 -1
- package/dist/adapters/postgresql/tools/core/indexes.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/core/indexes.js +3 -2
- package/dist/adapters/postgresql/tools/core/indexes.js.map +1 -1
- package/dist/adapters/postgresql/tools/core/tables.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/core/tables.js +4 -4
- package/dist/adapters/postgresql/tools/core/tables.js.map +1 -1
- package/dist/adapters/postgresql/tools/cron.js +59 -27
- package/dist/adapters/postgresql/tools/cron.js.map +1 -1
- package/dist/adapters/postgresql/tools/introspection.d.ts +15 -0
- package/dist/adapters/postgresql/tools/introspection.d.ts.map +1 -0
- package/dist/adapters/postgresql/tools/introspection.js +1682 -0
- package/dist/adapters/postgresql/tools/introspection.js.map +1 -0
- package/dist/adapters/postgresql/tools/jsonb/advanced.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/jsonb/advanced.js +26 -17
- package/dist/adapters/postgresql/tools/jsonb/advanced.js.map +1 -1
- package/dist/adapters/postgresql/tools/jsonb/basic.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/jsonb/basic.js +92 -23
- package/dist/adapters/postgresql/tools/jsonb/basic.js.map +1 -1
- package/dist/adapters/postgresql/tools/ltree.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/ltree.js +17 -4
- package/dist/adapters/postgresql/tools/ltree.js.map +1 -1
- package/dist/adapters/postgresql/tools/monitoring.js +32 -21
- package/dist/adapters/postgresql/tools/monitoring.js.map +1 -1
- package/dist/adapters/postgresql/tools/partman/management.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/partman/management.js +32 -52
- package/dist/adapters/postgresql/tools/partman/management.js.map +1 -1
- package/dist/adapters/postgresql/tools/partman/operations.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/partman/operations.js +5 -5
- package/dist/adapters/postgresql/tools/partman/operations.js.map +1 -1
- package/dist/adapters/postgresql/tools/performance/analysis.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/performance/analysis.js +15 -8
- package/dist/adapters/postgresql/tools/performance/analysis.js.map +1 -1
- package/dist/adapters/postgresql/tools/performance/monitoring.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/performance/monitoring.js +10 -7
- package/dist/adapters/postgresql/tools/performance/monitoring.js.map +1 -1
- package/dist/adapters/postgresql/tools/performance/stats.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/performance/stats.js +62 -28
- package/dist/adapters/postgresql/tools/performance/stats.js.map +1 -1
- package/dist/adapters/postgresql/tools/pgcrypto.js +31 -11
- package/dist/adapters/postgresql/tools/pgcrypto.js.map +1 -1
- package/dist/adapters/postgresql/tools/postgis/advanced.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/postgis/advanced.js +30 -25
- package/dist/adapters/postgresql/tools/postgis/advanced.js.map +1 -1
- package/dist/adapters/postgresql/tools/postgis/basic.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/postgis/basic.js +24 -15
- package/dist/adapters/postgresql/tools/postgis/basic.js.map +1 -1
- package/dist/adapters/postgresql/tools/schema.js +79 -5
- package/dist/adapters/postgresql/tools/schema.js.map +1 -1
- package/dist/adapters/postgresql/tools/stats/advanced.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/stats/advanced.js +61 -39
- package/dist/adapters/postgresql/tools/stats/advanced.js.map +1 -1
- package/dist/adapters/postgresql/tools/stats/basic.d.ts.map +1 -1
- package/dist/adapters/postgresql/tools/stats/basic.js +45 -30
- package/dist/adapters/postgresql/tools/stats/basic.js.map +1 -1
- package/dist/adapters/postgresql/tools/text.js +327 -148
- package/dist/adapters/postgresql/tools/text.js.map +1 -1
- package/dist/auth/auth-context.d.ts +28 -0
- package/dist/auth/auth-context.d.ts.map +1 -0
- package/dist/auth/auth-context.js +37 -0
- package/dist/auth/auth-context.js.map +1 -0
- package/dist/auth/scope-map.d.ts +20 -0
- package/dist/auth/scope-map.d.ts.map +1 -0
- package/dist/auth/scope-map.js +40 -0
- package/dist/auth/scope-map.js.map +1 -0
- package/dist/auth/scopes.d.ts.map +1 -1
- package/dist/auth/scopes.js +2 -0
- package/dist/auth/scopes.js.map +1 -1
- package/dist/cli.js +1 -1
- package/dist/cli.js.map +1 -1
- package/dist/codemode/api.d.ts +1 -0
- package/dist/codemode/api.d.ts.map +1 -1
- package/dist/codemode/api.js +34 -0
- package/dist/codemode/api.js.map +1 -1
- package/dist/codemode/index.d.ts +0 -2
- package/dist/codemode/index.d.ts.map +1 -1
- package/dist/codemode/index.js +0 -4
- package/dist/codemode/index.js.map +1 -1
- package/dist/codemode/sandbox.d.ts +14 -1
- package/dist/codemode/sandbox.d.ts.map +1 -1
- package/dist/codemode/sandbox.js +58 -19
- package/dist/codemode/sandbox.js.map +1 -1
- package/dist/codemode/types.d.ts.map +1 -1
- package/dist/codemode/types.js +3 -0
- package/dist/codemode/types.js.map +1 -1
- package/dist/constants/ServerInstructions.d.ts +5 -1
- package/dist/constants/ServerInstructions.d.ts.map +1 -1
- package/dist/constants/ServerInstructions.js +91 -43
- package/dist/constants/ServerInstructions.js.map +1 -1
- package/dist/filtering/ToolConstants.d.ts +22 -19
- package/dist/filtering/ToolConstants.d.ts.map +1 -1
- package/dist/filtering/ToolConstants.js +48 -37
- package/dist/filtering/ToolConstants.js.map +1 -1
- package/dist/filtering/ToolFilter.d.ts.map +1 -1
- package/dist/filtering/ToolFilter.js +10 -13
- package/dist/filtering/ToolFilter.js.map +1 -1
- package/dist/pool/ConnectionPool.js +1 -1
- package/dist/pool/ConnectionPool.js.map +1 -1
- package/dist/transports/http.d.ts +1 -0
- package/dist/transports/http.d.ts.map +1 -1
- package/dist/transports/http.js +75 -21
- package/dist/transports/http.js.map +1 -1
- package/dist/types/filtering.d.ts +2 -2
- package/dist/types/filtering.d.ts.map +1 -1
- package/dist/utils/icons.d.ts.map +1 -1
- package/dist/utils/icons.js +5 -0
- package/dist/utils/icons.js.map +1 -1
- package/dist/utils/where-clause.d.ts.map +1 -1
- package/dist/utils/where-clause.js +24 -0
- package/dist/utils/where-clause.js.map +1 -1
- package/package.json +15 -12
- package/dist/codemode/sandbox-factory.d.ts +0 -72
- package/dist/codemode/sandbox-factory.d.ts.map +0 -1
- package/dist/codemode/sandbox-factory.js +0 -88
- package/dist/codemode/sandbox-factory.js.map +0 -1
- package/dist/codemode/worker-sandbox.d.ts +0 -82
- package/dist/codemode/worker-sandbox.d.ts.map +0 -1
- package/dist/codemode/worker-sandbox.js +0 -244
- package/dist/codemode/worker-sandbox.js.map +0 -1
- package/dist/codemode/worker-script.d.ts +0 -8
- package/dist/codemode/worker-script.d.ts.map +0 -1
- package/dist/codemode/worker-script.js +0 -113
- package/dist/codemode/worker-script.js.map +0 -1
package/README.md
CHANGED
|
@@ -2,56 +2,108 @@
|
|
|
2
2
|
|
|
3
3
|
<!-- mcp-name: io.github.neverinfamous/postgres-mcp -->
|
|
4
4
|
|
|
5
|
-
**Last Updated
|
|
5
|
+
**Last Updated March 2, 2026**
|
|
6
6
|
|
|
7
|
-
**PostgreSQL MCP Server** enabling AI assistants (AntiGravity, Claude, Cursor, etc.) to interact with PostgreSQL databases through the Model Context Protocol. Features deterministic error handling, connection pooling, HTTP/SSE Transport, OAuth 2.1 authentication,
|
|
7
|
+
**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.
|
|
8
8
|
|
|
9
|
-
**
|
|
9
|
+
**227 Specialized Tools** · **20 Resources** · **19 AI-Powered Prompts**
|
|
10
10
|
|
|
11
|
-
[](https://github.com/neverinfamous/
|
|
12
|
-
](https://github.com/neverinfamous/postgres-mcp)
|
|
12
|
+

|
|
13
13
|
[](https://hub.docker.com/r/writenotenow/postgres-mcp)
|
|
14
14
|
[](https://opensource.org/licenses/MIT)
|
|
15
15
|
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/postgres-mcp)
|
|
16
16
|
[](https://www.npmjs.com/package/@neverinfamous/postgres-mcp)
|
|
17
|
-
[](https://github.com/neverinfamous/
|
|
17
|
+
[](https://github.com/neverinfamous/postgres-mcp/blob/main/SECURITY.md)
|
|
18
18
|

|
|
19
|
-
[](https://github.com/neverinfamous/
|
|
20
|
-
[](https://github.com/neverinfamous/postgres-mcp)
|
|
20
|
+
[](https://github.com/neverinfamous/postgres-mcp)
|
|
21
|
+
[](https://github.com/neverinfamous/postgres-mcp)
|
|
22
22
|
|
|
23
|
-
**[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/
|
|
23
|
+
**[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)**
|
|
24
24
|
|
|
25
25
|
## 🎯 What Sets Us Apart
|
|
26
26
|
|
|
27
|
-
| Feature
|
|
28
|
-
|
|
|
29
|
-
| **
|
|
30
|
-
| **20 Observability Resources**
|
|
31
|
-
| **19 AI-Powered Prompts**
|
|
32
|
-
| **Code Mode**
|
|
33
|
-
| **OAuth 2.1 + Access Control**
|
|
34
|
-
| **Smart Tool Filtering**
|
|
35
|
-
| **HTTP Streaming Transport**
|
|
36
|
-
| **High-Performance Pooling**
|
|
37
|
-
| **8 Extension Ecosystems**
|
|
38
|
-
| **
|
|
39
|
-
| **
|
|
40
|
-
| **
|
|
41
|
-
| **
|
|
27
|
+
| Feature | Description |
|
|
28
|
+
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
29
|
+
| **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 |
|
|
30
|
+
| **20 Observability Resources** | Real-time schema, performance metrics, connection pool status, replication lag, vacuum stats, lock contention, and extension diagnostics |
|
|
31
|
+
| **19 AI-Powered Prompts** | Guided workflows for query building, schema design, performance tuning, and extension setup |
|
|
32
|
+
| **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. |
|
|
33
|
+
| **OAuth 2.1 + Access Control** | Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (`read`, `write`, `admin`, `full`, `db:*`, `table:*:*`), and Keycloak integration |
|
|
34
|
+
| **Smart Tool Filtering** | 21 tool groups + 16 shortcuts let you stay within IDE limits while exposing exactly what you need |
|
|
35
|
+
| **HTTP Streaming Transport** | SSE-based streaming with `/mcp`, and `/health` endpoints for remote deployments |
|
|
36
|
+
| **High-Performance Pooling** | Built-in connection pooling with health checks for efficient, concurrent database access |
|
|
37
|
+
| **8 Extension Ecosystems** | First-class support for **pgvector**, **PostGIS**, **pg_cron**, **pg_partman**, **pg_stat_kcache**, **citext**, **ltree**, and **pgcrypto** |
|
|
38
|
+
| **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 |
|
|
39
|
+
| **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 |
|
|
40
|
+
| **Production-Ready Security** | SQL injection protection, parameterized queries, input validation, sandboxed code execution, SSL certificate verification by default, and HTTP body size enforcement |
|
|
41
|
+
| **Strict TypeScript** | 100% type-safe codebase with 3176 tests and 93.58% coverage |
|
|
42
|
+
| **MCP 2025-11-25 Compliant** | Full protocol support with tool safety hints, resource priorities, and progress notifications |
|
|
42
43
|
|
|
43
44
|
## 🚀 Quick Start
|
|
44
45
|
|
|
45
46
|
### Prerequisites
|
|
46
47
|
|
|
47
|
-
- Node.js 24+ (LTS)
|
|
48
48
|
- PostgreSQL 12-18 (tested with PostgreSQL 18.1)
|
|
49
|
-
-
|
|
49
|
+
- **Docker** (recommended) or Node.js 24+ (LTS)
|
|
50
50
|
|
|
51
|
-
###
|
|
51
|
+
### Docker (Recommended)
|
|
52
52
|
|
|
53
53
|
```bash
|
|
54
|
-
|
|
54
|
+
docker pull writenotenow/postgres-mcp:latest
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"mcpServers": {
|
|
60
|
+
"postgres-mcp": {
|
|
61
|
+
"command": "docker",
|
|
62
|
+
"args": [
|
|
63
|
+
"run",
|
|
64
|
+
"--rm",
|
|
65
|
+
"-i",
|
|
66
|
+
"-e",
|
|
67
|
+
"POSTGRES_HOST",
|
|
68
|
+
"-e",
|
|
69
|
+
"POSTGRES_PORT",
|
|
70
|
+
"-e",
|
|
71
|
+
"POSTGRES_USER",
|
|
72
|
+
"-e",
|
|
73
|
+
"POSTGRES_PASSWORD",
|
|
74
|
+
"-e",
|
|
75
|
+
"POSTGRES_DATABASE",
|
|
76
|
+
"writenotenow/postgres-mcp:latest",
|
|
77
|
+
"--tool-filter",
|
|
78
|
+
"starter"
|
|
79
|
+
],
|
|
80
|
+
"env": {
|
|
81
|
+
"POSTGRES_HOST": "host.docker.internal",
|
|
82
|
+
"POSTGRES_PORT": "5432",
|
|
83
|
+
"POSTGRES_USER": "your_username",
|
|
84
|
+
"POSTGRES_PASSWORD": "your_password",
|
|
85
|
+
"POSTGRES_DATABASE": "your_database"
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
> **Note for Docker**: Use `host.docker.internal` to connect to PostgreSQL running on your host machine.
|
|
93
|
+
|
|
94
|
+
📖 **Full Docker guide:** [DOCKER_README.md](DOCKER_README.md) · [Docker Hub](https://hub.docker.com/r/writenotenow/postgres-mcp)
|
|
95
|
+
|
|
96
|
+
### npm
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
npm install -g @neverinfamous/postgres-mcp
|
|
100
|
+
postgres-mcp --transport stdio --postgres postgres://user:password@localhost:5432/database
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### From Source
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
git clone https://github.com/neverinfamous/postgres-mcp.git
|
|
55
107
|
cd postgres-mcp
|
|
56
108
|
npm install
|
|
57
109
|
npm run build
|
|
@@ -64,12 +116,50 @@ node dist/cli.js --transport stdio --postgres postgres://user:password@localhost
|
|
|
64
116
|
|
|
65
117
|
Code Mode (`pg_execute_code`) dramatically reduces token usage (70–90%) and is included by default in all presets.
|
|
66
118
|
|
|
119
|
+
Code executes in a **sandboxed VM context** with multiple layers of security. All `pg.*` API calls execute against the database within the sandbox, providing:
|
|
120
|
+
|
|
121
|
+
- **Static code validation** — blocked patterns include `require()`, `process`, `eval()`, and filesystem access
|
|
122
|
+
- **Rate limiting** — 60 executions per minute per client
|
|
123
|
+
- **Hard timeouts** — configurable execution limit (default 30s)
|
|
124
|
+
- **Full API access** — all 20 tool groups are available via `pg.*` (e.g., `pg.core.readQuery()`, `pg.jsonb.extract()`, `pg.introspection.dependencyGraph()`)
|
|
125
|
+
- **Requires `admin` OAuth scope** — execution is logged for audit
|
|
126
|
+
|
|
127
|
+
### ⚡ Code Mode Only (Maximum Token Savings)
|
|
128
|
+
|
|
129
|
+
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:
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
{
|
|
133
|
+
"mcpServers": {
|
|
134
|
+
"postgres-mcp": {
|
|
135
|
+
"command": "node",
|
|
136
|
+
"args": [
|
|
137
|
+
"/path/to/postgres-mcp/dist/cli.js",
|
|
138
|
+
"--transport",
|
|
139
|
+
"stdio",
|
|
140
|
+
"--tool-filter",
|
|
141
|
+
"codemode"
|
|
142
|
+
],
|
|
143
|
+
"env": {
|
|
144
|
+
"POSTGRES_HOST": "localhost",
|
|
145
|
+
"POSTGRES_PORT": "5432",
|
|
146
|
+
"POSTGRES_USER": "your_user",
|
|
147
|
+
"POSTGRES_PASSWORD": "your_password",
|
|
148
|
+
"POSTGRES_DATABASE": "your_database"
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
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.
|
|
156
|
+
|
|
67
157
|
> [!TIP]
|
|
68
|
-
> **Maximize Token Savings:**
|
|
158
|
+
> **Maximize Token Savings:** Instruct your AI agent to prefer Code Mode over individual tool calls:
|
|
69
159
|
>
|
|
70
160
|
> _"When using postgres-mcp, prefer `pg_execute_code` (Code Mode) for multi-step database operations to minimize token usage."_
|
|
71
161
|
>
|
|
72
|
-
>
|
|
162
|
+
> 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.
|
|
73
163
|
|
|
74
164
|
> [!NOTE]
|
|
75
165
|
> **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.
|
|
@@ -84,53 +174,24 @@ If you don't have admin access or prefer individual tool calls, exclude codemode
|
|
|
84
174
|
}
|
|
85
175
|
```
|
|
86
176
|
|
|
87
|
-
### Isolation Modes
|
|
88
|
-
|
|
89
|
-
| Mode | Isolation | When to Use |
|
|
90
|
-
| -------- | ------------------ | ---------------------------- |
|
|
91
|
-
| `vm` | Same process | **Default, recommended** |
|
|
92
|
-
| `worker` | Separate V8 thread | Not recommended (incomplete) |
|
|
93
|
-
|
|
94
|
-
The `vm` mode is fully functional and is the default. No configuration needed.
|
|
95
|
-
|
|
96
|
-
### Security
|
|
97
|
-
|
|
98
|
-
- Requires `admin` OAuth scope
|
|
99
|
-
- Blocked: `require()`, `process`, `eval()`, filesystem
|
|
100
|
-
- Rate limited: 60 executions/minute
|
|
101
|
-
|
|
102
177
|
📖 **Full documentation:** [docs/CODE_MODE.md](docs/CODE_MODE.md)
|
|
103
178
|
|
|
104
179
|
---
|
|
105
180
|
|
|
106
181
|
## Development
|
|
107
182
|
|
|
108
|
-
**
|
|
183
|
+
See **[From Source](#from-source)** above for setup. After cloning:
|
|
109
184
|
|
|
110
185
|
```bash
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
**Build:**
|
|
117
|
-
|
|
118
|
-
```bash
|
|
119
|
-
npm run build
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
**Run checks:**
|
|
123
|
-
|
|
124
|
-
```bash
|
|
125
|
-
npm run lint && npm run typecheck
|
|
186
|
+
npm run lint && npm run typecheck # Run checks
|
|
187
|
+
npm run bench # Run performance benchmarks
|
|
188
|
+
node dist/cli.js info # Test CLI
|
|
189
|
+
node dist/cli.js list-tools # List available tools
|
|
126
190
|
```
|
|
127
191
|
|
|
128
|
-
|
|
192
|
+
### Benchmarks
|
|
129
193
|
|
|
130
|
-
|
|
131
|
-
node dist/cli.js info
|
|
132
|
-
node dist/cli.js list-tools
|
|
133
|
-
```
|
|
194
|
+
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.
|
|
134
195
|
|
|
135
196
|
---
|
|
136
197
|
|
|
@@ -205,7 +266,7 @@ node dist/cli.js list-tools
|
|
|
205
266
|
## 🛠️ Tool Filtering
|
|
206
267
|
|
|
207
268
|
> [!IMPORTANT]
|
|
208
|
-
> AI IDEs like Cursor have tool limits. With
|
|
269
|
+
> 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.
|
|
209
270
|
|
|
210
271
|
### What Can You Filter?
|
|
211
272
|
|
|
@@ -224,50 +285,52 @@ All shortcuts and tool groups include **Code Mode** (`pg_execute_code`) by defau
|
|
|
224
285
|
|
|
225
286
|
> Tool counts include Code Mode (`pg_execute_code`) which is included in all presets by default.
|
|
226
287
|
|
|
227
|
-
| Shortcut
|
|
228
|
-
|
|
|
229
|
-
| `starter`
|
|
230
|
-
| `essential`
|
|
231
|
-
| `dev-
|
|
232
|
-
| `
|
|
233
|
-
| `ai-
|
|
234
|
-
| `
|
|
235
|
-
| `dba-
|
|
236
|
-
| `dba-
|
|
237
|
-
| `
|
|
238
|
-
| `
|
|
239
|
-
| `
|
|
240
|
-
| `
|
|
241
|
-
| `ext-
|
|
242
|
-
| `ext-
|
|
243
|
-
| `ext-
|
|
244
|
-
|
|
245
|
-
|
|
288
|
+
| Shortcut | Tools | Use Case | What's Included |
|
|
289
|
+
| --------------- | ------ | ------------------------ | -------------------------------------------------------- |
|
|
290
|
+
| `starter` | **59** | 🌟 **Recommended** | Core, trans, JSONB, schema, codemode |
|
|
291
|
+
| `essential` | 47 | Minimal footprint | Core, trans, JSONB, codemode |
|
|
292
|
+
| `dev-schema` | 52 | Dev Schema & Migrations | Core, trans, schema, introspection, codemode |
|
|
293
|
+
| `dev-analytics` | 42 | Dev Analytics | Core, trans, stats, partitioning, codemode |
|
|
294
|
+
| `ai-data` | 60 | AI Data Analyst | Core, JSONB, text, trans, codemode |
|
|
295
|
+
| `ai-vector` | 50 | AI/ML with pgvector | Core, vector, trans, part, codemode |
|
|
296
|
+
| `dba-monitor` | 59 | DBA Monitoring | Core, monitoring, perf, trans, codemode |
|
|
297
|
+
| `dba-schema` | 45 | DBA Schema & Migrations | Core, schema, introspection, codemode |
|
|
298
|
+
| `dba-infra` | 46 | DBA Infrastructure | Core, admin, backup, partitioning, codemode |
|
|
299
|
+
| `dba-stats` | 57 | DBA Stats | Core, admin, monitoring, trans, stats, codemode |
|
|
300
|
+
| `geo` | 43 | Geospatial Workloads | Core, PostGIS, trans, codemode |
|
|
301
|
+
| `base-ops` | 51 | Operations Block | Admin, monitoring, backup, part, stats, citext, codemode |
|
|
302
|
+
| `ext-ai` | 26 | Extension: AI/Security | pgvector, pgcrypto, codemode |
|
|
303
|
+
| `ext-geo` | 24 | Extension: Spatial | PostGIS, ltree, codemode |
|
|
304
|
+
| `ext-schedule` | 19 | Extension: Scheduling | pg_cron, pg_partman, codemode |
|
|
305
|
+
| `ext-perf` | 28 | Extension: Perf/Analysis | pg_stat_kcache, performance, codemode |
|
|
306
|
+
|
|
307
|
+
### Tool Groups (21 Available)
|
|
246
308
|
|
|
247
309
|
> Tool counts include Code Mode (`pg_execute_code`) which is added to all groups by default.
|
|
248
310
|
|
|
249
|
-
| Group
|
|
250
|
-
|
|
|
251
|
-
| `
|
|
252
|
-
| `
|
|
253
|
-
| `
|
|
254
|
-
| `
|
|
255
|
-
| `
|
|
256
|
-
| `
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
259
|
-
| `
|
|
260
|
-
| `
|
|
261
|
-
| `
|
|
262
|
-
| `
|
|
263
|
-
| `
|
|
264
|
-
| `
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
311
|
+
| Group | Tools | Description |
|
|
312
|
+
| --------------- | ----- | ----------------------------------------------------------- |
|
|
313
|
+
| `codemode` | 1 | Code Mode (sandboxed code execution) |
|
|
314
|
+
| `core` | 21 | Read/write queries, tables, indexes, convenience/drop tools |
|
|
315
|
+
| `transactions` | 8 | BEGIN, COMMIT, ROLLBACK, savepoints |
|
|
316
|
+
| `jsonb` | 20 | JSONB manipulation and queries |
|
|
317
|
+
| `text` | 14 | Full-text search, fuzzy matching |
|
|
318
|
+
| `performance` | 21 | EXPLAIN, query analysis, optimization |
|
|
319
|
+
| `admin` | 11 | VACUUM, ANALYZE, REINDEX |
|
|
320
|
+
| `monitoring` | 12 | Database sizes, connections, status |
|
|
321
|
+
| `backup` | 10 | pg_dump, COPY, restore |
|
|
322
|
+
| `schema` | 13 | Schemas, views, sequences, functions, triggers |
|
|
323
|
+
| `introspection` | 13 | Dependency graphs, cascade simulation, migration tracking |
|
|
324
|
+
| `partitioning` | 7 | Native partition management |
|
|
325
|
+
| `stats` | 9 | Statistical analysis |
|
|
326
|
+
| `vector` | 17 | pgvector (AI/ML similarity search) |
|
|
327
|
+
| `postgis` | 16 | PostGIS (geospatial) |
|
|
328
|
+
| `cron` | 9 | pg_cron (job scheduling) |
|
|
329
|
+
| `partman` | 11 | pg_partman (auto-partitioning) |
|
|
330
|
+
| `kcache` | 8 | pg_stat_kcache (OS-level stats) |
|
|
331
|
+
| `citext` | 7 | citext (case-insensitive text) |
|
|
332
|
+
| `ltree` | 9 | ltree (hierarchical data) |
|
|
333
|
+
| `pgcrypto` | 10 | pgcrypto (encryption, UUIDs) |
|
|
271
334
|
|
|
272
335
|
---
|
|
273
336
|
|
|
@@ -417,6 +480,9 @@ The server exposes metadata at `/.well-known/oauth-protected-resource`.
|
|
|
417
480
|
|
|
418
481
|
> **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.
|
|
419
482
|
|
|
483
|
+
> [!NOTE]
|
|
484
|
+
> **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.
|
|
485
|
+
|
|
420
486
|
---
|
|
421
487
|
|
|
422
488
|
## ⚡ Performance Tuning
|
|
@@ -447,7 +513,7 @@ This server includes **19 intelligent prompts** for guided workflows:
|
|
|
447
513
|
| `pg_quick_query` | Quick SQL query guidance for common operations | core | `starter` |
|
|
448
514
|
| `pg_quick_schema` | Quick reference for exploring database schema | core | `starter` |
|
|
449
515
|
| `pg_database_health_check` | Comprehensive database health assessment | core, performance, monitoring | `dba-monitor` |
|
|
450
|
-
| `pg_backup_strategy` | Enterprise backup planning with RTO/RPO | core, monitoring, backup | `dba-
|
|
516
|
+
| `pg_backup_strategy` | Enterprise backup planning with RTO/RPO | core, monitoring, backup | `dba-infra` |
|
|
451
517
|
| `pg_index_tuning` | Index analysis and optimization workflow | core, performance | `dba-monitor` |
|
|
452
518
|
| `pg_extension_setup` | Extension installation and configuration guide | core | `starter` |
|
|
453
519
|
| `pg_setup_pgvector` | Complete pgvector setup for semantic search | core, vector | `ai-vector` |
|
|
@@ -509,25 +575,7 @@ This server provides **20 resources** for structured data access:
|
|
|
509
575
|
| `ltree` | Hierarchical tree labels | 8 ltree tools |
|
|
510
576
|
| `pgcrypto` | Hashing, encryption, UUIDs | 9 pgcrypto tools |
|
|
511
577
|
|
|
512
|
-
> Extension tools gracefully handle cases where extensions are not installed. Extension tool counts include `create_extension` helpers
|
|
513
|
-
|
|
514
|
-
---
|
|
515
|
-
|
|
516
|
-
## 🔥 Core Capabilities
|
|
517
|
-
|
|
518
|
-
- 📊 **Full SQL Support** - Execute any PostgreSQL query with parameter binding
|
|
519
|
-
- 🔍 **JSONB Operations** - Native JSONB functions and path queries
|
|
520
|
-
- 🔐 **Connection Pooling** - Efficient connection management with health checks
|
|
521
|
-
- 🎛️ **Tool Filtering** - Control which operations are exposed
|
|
522
|
-
- ⚡ **Performance Tools** - EXPLAIN ANALYZE, buffer analysis, index hints
|
|
523
|
-
- 🗺️ **PostGIS Support** - Geospatial queries and spatial indexes
|
|
524
|
-
- 🧠 **pgvector Support** - AI/ML vector similarity search
|
|
525
|
-
|
|
526
|
-
### 🏢 Enterprise Features
|
|
527
|
-
|
|
528
|
-
- 🔐 **OAuth 2.1 Authentication** - RFC 9728/8414 compliant
|
|
529
|
-
- 🛡️ **Tool Filtering** - Control which database operations are exposed
|
|
530
|
-
- 📈 **Monitoring** - Process lists, replication lag, cache hit ratios
|
|
578
|
+
> 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.
|
|
531
579
|
|
|
532
580
|
---
|
|
533
581
|
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* postgres-mcp - Code Mode Sandbox Performance Benchmarks
|
|
3
|
+
*
|
|
4
|
+
* Measures VM context creation, sandbox pool lifecycle, security
|
|
5
|
+
* validation, and execution overhead using vitest bench (tinybench).
|
|
6
|
+
*
|
|
7
|
+
* Run: npm run bench
|
|
8
|
+
*/
|
|
9
|
+
export {};
|
|
10
|
+
//# sourceMappingURL=codemode.bench.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"codemode.bench.d.ts","sourceRoot":"","sources":["../../../src/__tests__/benchmarks/codemode.bench.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* postgres-mcp - Code Mode Sandbox Performance Benchmarks
|
|
3
|
+
*
|
|
4
|
+
* Measures VM context creation, sandbox pool lifecycle, security
|
|
5
|
+
* validation, and execution overhead using vitest bench (tinybench).
|
|
6
|
+
*
|
|
7
|
+
* Run: npm run bench
|
|
8
|
+
*/
|
|
9
|
+
import { describe, bench, beforeEach, afterEach, vi } from "vitest";
|
|
10
|
+
import { CodeModeSandbox, SandboxPool } from "../../codemode/sandbox.js";
|
|
11
|
+
import { CodeModeSecurityManager } from "../../codemode/security.js";
|
|
12
|
+
// Suppress logger stderr output during benchmarks
|
|
13
|
+
vi.mock("../../utils/logger.js", () => ({
|
|
14
|
+
logger: {
|
|
15
|
+
debug: vi.fn(),
|
|
16
|
+
info: vi.fn(),
|
|
17
|
+
warn: vi.fn(),
|
|
18
|
+
warning: vi.fn(),
|
|
19
|
+
error: vi.fn(),
|
|
20
|
+
notice: vi.fn(),
|
|
21
|
+
critical: vi.fn(),
|
|
22
|
+
alert: vi.fn(),
|
|
23
|
+
emergency: vi.fn(),
|
|
24
|
+
setLevel: vi.fn(),
|
|
25
|
+
setMcpServer: vi.fn(),
|
|
26
|
+
},
|
|
27
|
+
}));
|
|
28
|
+
// ---------------------------------------------------------------------------
|
|
29
|
+
// 1. Sandbox Creation
|
|
30
|
+
// ---------------------------------------------------------------------------
|
|
31
|
+
describe("Sandbox Creation", () => {
|
|
32
|
+
bench("CodeModeSandbox.create() cold start", () => {
|
|
33
|
+
const sandbox = CodeModeSandbox.create();
|
|
34
|
+
sandbox.dispose();
|
|
35
|
+
}, { iterations: 200, warmupIterations: 5 });
|
|
36
|
+
bench("sandbox dispose() (idempotent)", () => {
|
|
37
|
+
const sandbox = CodeModeSandbox.create();
|
|
38
|
+
sandbox.dispose();
|
|
39
|
+
sandbox.dispose(); // Idempotent call
|
|
40
|
+
}, { iterations: 200, warmupIterations: 5 });
|
|
41
|
+
});
|
|
42
|
+
// ---------------------------------------------------------------------------
|
|
43
|
+
// 2. Sandbox Pool Lifecycle
|
|
44
|
+
// ---------------------------------------------------------------------------
|
|
45
|
+
describe("SandboxPool Lifecycle", () => {
|
|
46
|
+
bench("pool initialization (minInstances=2)", () => {
|
|
47
|
+
const pool = new SandboxPool({ minInstances: 2, maxInstances: 10, idleTimeoutMs: 60000 }, { timeoutMs: 30000, memoryLimitMb: 128, cpuLimitMs: 10000 });
|
|
48
|
+
pool.initialize();
|
|
49
|
+
pool.dispose();
|
|
50
|
+
}, { iterations: 100, warmupIterations: 3 });
|
|
51
|
+
let sandboxPool;
|
|
52
|
+
describe("pool operations", () => {
|
|
53
|
+
beforeEach(() => {
|
|
54
|
+
sandboxPool = new SandboxPool({ minInstances: 2, maxInstances: 10, idleTimeoutMs: 60000 }, { timeoutMs: 30000, memoryLimitMb: 128, cpuLimitMs: 10000 });
|
|
55
|
+
sandboxPool.initialize();
|
|
56
|
+
});
|
|
57
|
+
afterEach(() => {
|
|
58
|
+
sandboxPool?.dispose();
|
|
59
|
+
});
|
|
60
|
+
bench("acquire/release round trip", () => {
|
|
61
|
+
const sandbox = sandboxPool.acquire();
|
|
62
|
+
sandboxPool.release(sandbox);
|
|
63
|
+
}, { iterations: 1000, warmupIterations: 10 });
|
|
64
|
+
bench("getStats() overhead", () => {
|
|
65
|
+
sandboxPool.getStats();
|
|
66
|
+
}, { iterations: 5000, warmupIterations: 20 });
|
|
67
|
+
});
|
|
68
|
+
});
|
|
69
|
+
// ---------------------------------------------------------------------------
|
|
70
|
+
// 3. Sandbox Execution
|
|
71
|
+
// ---------------------------------------------------------------------------
|
|
72
|
+
describe("Sandbox Execution", () => {
|
|
73
|
+
let sandbox;
|
|
74
|
+
beforeEach(() => {
|
|
75
|
+
sandbox = CodeModeSandbox.create();
|
|
76
|
+
});
|
|
77
|
+
afterEach(() => {
|
|
78
|
+
sandbox?.dispose();
|
|
79
|
+
});
|
|
80
|
+
bench('trivial code execution ("return 42")', async () => {
|
|
81
|
+
await sandbox.execute("return 42;", {});
|
|
82
|
+
}, { iterations: 30, warmupIterations: 3, time: 5000 });
|
|
83
|
+
bench("execution with 20-group API bindings", async () => {
|
|
84
|
+
const apiBindings = {};
|
|
85
|
+
const groupNames = [
|
|
86
|
+
"core",
|
|
87
|
+
"transactions",
|
|
88
|
+
"jsonb",
|
|
89
|
+
"text",
|
|
90
|
+
"performance",
|
|
91
|
+
"admin",
|
|
92
|
+
"monitoring",
|
|
93
|
+
"backup",
|
|
94
|
+
"schema",
|
|
95
|
+
"partitioning",
|
|
96
|
+
"stats",
|
|
97
|
+
"vector",
|
|
98
|
+
"postgis",
|
|
99
|
+
"cron",
|
|
100
|
+
"partman",
|
|
101
|
+
"kcache",
|
|
102
|
+
"citext",
|
|
103
|
+
"ltree",
|
|
104
|
+
"pgcrypto",
|
|
105
|
+
"codemode",
|
|
106
|
+
];
|
|
107
|
+
for (const group of groupNames) {
|
|
108
|
+
apiBindings[group] = {
|
|
109
|
+
readQuery: () => ({ rows: [], rowCount: 0 }),
|
|
110
|
+
writeQuery: () => ({ rowsAffected: 0 }),
|
|
111
|
+
help: () => [],
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
await sandbox.execute("const result = pg.core.readQuery(); return result;", apiBindings);
|
|
115
|
+
}, { iterations: 20, warmupIterations: 3, time: 5000 });
|
|
116
|
+
bench("console output capture", async () => {
|
|
117
|
+
await sandbox.execute('console.log("test output"); console.warn("warning");', {});
|
|
118
|
+
sandbox.clearConsoleOutput();
|
|
119
|
+
}, { iterations: 30, warmupIterations: 3, time: 5000 });
|
|
120
|
+
});
|
|
121
|
+
// ---------------------------------------------------------------------------
|
|
122
|
+
// 4. Security Validation
|
|
123
|
+
// ---------------------------------------------------------------------------
|
|
124
|
+
describe("Security Validation", () => {
|
|
125
|
+
const security = new CodeModeSecurityManager();
|
|
126
|
+
bench("validateCode() safe short code (50 chars)", () => {
|
|
127
|
+
security.validateCode('const result = await pg.core.readQuery("SELECT 1");');
|
|
128
|
+
}, { iterations: 5000, warmupIterations: 50 });
|
|
129
|
+
bench("validateCode() safe large code (10KB)", () => {
|
|
130
|
+
const lines = [];
|
|
131
|
+
for (let i = 0; i < 200; i++) {
|
|
132
|
+
lines.push(`const result${String(i)} = await pg.core.readQuery("SELECT * FROM table${String(i)} LIMIT 10");`);
|
|
133
|
+
}
|
|
134
|
+
security.validateCode(lines.join("\n"));
|
|
135
|
+
}, { iterations: 1000, warmupIterations: 10 });
|
|
136
|
+
bench("validateCode() blocked code (early rejection)", () => {
|
|
137
|
+
security.validateCode('require("fs").readFileSync("/etc/passwd")');
|
|
138
|
+
}, { iterations: 5000, warmupIterations: 50 });
|
|
139
|
+
bench("checkRateLimit() throughput", () => {
|
|
140
|
+
const secManager = new CodeModeSecurityManager({
|
|
141
|
+
maxExecutionsPerMinute: 10000,
|
|
142
|
+
});
|
|
143
|
+
secManager.checkRateLimit("client-1");
|
|
144
|
+
}, { iterations: 5000, warmupIterations: 50 });
|
|
145
|
+
bench("sanitizeResult() small payload", () => {
|
|
146
|
+
security.sanitizeResult({ users: [{ id: 1, name: "test" }] });
|
|
147
|
+
}, { iterations: 3000, warmupIterations: 30 });
|
|
148
|
+
bench("sanitizeResult() medium payload (100 rows)", () => {
|
|
149
|
+
const medium = {
|
|
150
|
+
data: Array.from({ length: 100 }, (_, i) => ({
|
|
151
|
+
id: i,
|
|
152
|
+
name: `user_${String(i)}`,
|
|
153
|
+
email: `user${String(i)}@example.com`,
|
|
154
|
+
})),
|
|
155
|
+
};
|
|
156
|
+
security.sanitizeResult(medium);
|
|
157
|
+
}, { iterations: 1000, warmupIterations: 10 });
|
|
158
|
+
});
|
|
159
|
+
//# sourceMappingURL=codemode.bench.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"codemode.bench.js","sourceRoot":"","sources":["../../../src/__tests__/benchmarks/codemode.bench.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* postgres-mcp - Connection Pool Performance Benchmarks
|
|
3
|
+
*
|
|
4
|
+
* Measures overhead of pool operations using mocked pg internals
|
|
5
|
+
* to isolate framework cost from database latency.
|
|
6
|
+
*
|
|
7
|
+
* Run: npm run bench
|
|
8
|
+
*/
|
|
9
|
+
export {};
|
|
10
|
+
//# sourceMappingURL=connection-pool.bench.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"connection-pool.bench.d.ts","sourceRoot":"","sources":["../../../src/__tests__/benchmarks/connection-pool.bench.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
|