@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.
Files changed (226) hide show
  1. package/README.md +177 -129
  2. package/dist/__tests__/benchmarks/codemode.bench.d.ts +10 -0
  3. package/dist/__tests__/benchmarks/codemode.bench.d.ts.map +1 -0
  4. package/dist/__tests__/benchmarks/codemode.bench.js +159 -0
  5. package/dist/__tests__/benchmarks/codemode.bench.js.map +1 -0
  6. package/dist/__tests__/benchmarks/connection-pool.bench.d.ts +10 -0
  7. package/dist/__tests__/benchmarks/connection-pool.bench.d.ts.map +1 -0
  8. package/dist/__tests__/benchmarks/connection-pool.bench.js +123 -0
  9. package/dist/__tests__/benchmarks/connection-pool.bench.js.map +1 -0
  10. package/dist/__tests__/benchmarks/handler-dispatch.bench.d.ts +11 -0
  11. package/dist/__tests__/benchmarks/handler-dispatch.bench.d.ts.map +1 -0
  12. package/dist/__tests__/benchmarks/handler-dispatch.bench.js +199 -0
  13. package/dist/__tests__/benchmarks/handler-dispatch.bench.js.map +1 -0
  14. package/dist/__tests__/benchmarks/logger-sanitization.bench.d.ts +15 -0
  15. package/dist/__tests__/benchmarks/logger-sanitization.bench.d.ts.map +1 -0
  16. package/dist/__tests__/benchmarks/logger-sanitization.bench.js +155 -0
  17. package/dist/__tests__/benchmarks/logger-sanitization.bench.js.map +1 -0
  18. package/dist/__tests__/benchmarks/resource-prompts.bench.d.ts +10 -0
  19. package/dist/__tests__/benchmarks/resource-prompts.bench.d.ts.map +1 -0
  20. package/dist/__tests__/benchmarks/resource-prompts.bench.js +181 -0
  21. package/dist/__tests__/benchmarks/resource-prompts.bench.js.map +1 -0
  22. package/dist/__tests__/benchmarks/schema-parsing.bench.d.ts +11 -0
  23. package/dist/__tests__/benchmarks/schema-parsing.bench.d.ts.map +1 -0
  24. package/dist/__tests__/benchmarks/schema-parsing.bench.js +209 -0
  25. package/dist/__tests__/benchmarks/schema-parsing.bench.js.map +1 -0
  26. package/dist/__tests__/benchmarks/tool-filtering.bench.d.ts +9 -0
  27. package/dist/__tests__/benchmarks/tool-filtering.bench.d.ts.map +1 -0
  28. package/dist/__tests__/benchmarks/tool-filtering.bench.js +83 -0
  29. package/dist/__tests__/benchmarks/tool-filtering.bench.js.map +1 -0
  30. package/dist/__tests__/benchmarks/transport-auth.bench.d.ts +10 -0
  31. package/dist/__tests__/benchmarks/transport-auth.bench.d.ts.map +1 -0
  32. package/dist/__tests__/benchmarks/transport-auth.bench.js +128 -0
  33. package/dist/__tests__/benchmarks/transport-auth.bench.js.map +1 -0
  34. package/dist/__tests__/benchmarks/utilities.bench.d.ts +10 -0
  35. package/dist/__tests__/benchmarks/utilities.bench.d.ts.map +1 -0
  36. package/dist/__tests__/benchmarks/utilities.bench.js +164 -0
  37. package/dist/__tests__/benchmarks/utilities.bench.js.map +1 -0
  38. package/dist/adapters/DatabaseAdapter.d.ts.map +1 -1
  39. package/dist/adapters/DatabaseAdapter.js +12 -0
  40. package/dist/adapters/DatabaseAdapter.js.map +1 -1
  41. package/dist/adapters/postgresql/PostgresAdapter.d.ts.map +1 -1
  42. package/dist/adapters/postgresql/PostgresAdapter.js +3 -0
  43. package/dist/adapters/postgresql/PostgresAdapter.js.map +1 -1
  44. package/dist/adapters/postgresql/schemas/backup.d.ts +37 -23
  45. package/dist/adapters/postgresql/schemas/backup.d.ts.map +1 -1
  46. package/dist/adapters/postgresql/schemas/backup.js +53 -22
  47. package/dist/adapters/postgresql/schemas/backup.js.map +1 -1
  48. package/dist/adapters/postgresql/schemas/extensions.d.ts +56 -37
  49. package/dist/adapters/postgresql/schemas/extensions.d.ts.map +1 -1
  50. package/dist/adapters/postgresql/schemas/extensions.js +68 -36
  51. package/dist/adapters/postgresql/schemas/extensions.js.map +1 -1
  52. package/dist/adapters/postgresql/schemas/index.d.ts +3 -2
  53. package/dist/adapters/postgresql/schemas/index.d.ts.map +1 -1
  54. package/dist/adapters/postgresql/schemas/index.js +8 -2
  55. package/dist/adapters/postgresql/schemas/index.js.map +1 -1
  56. package/dist/adapters/postgresql/schemas/introspection.d.ts +445 -0
  57. package/dist/adapters/postgresql/schemas/introspection.d.ts.map +1 -0
  58. package/dist/adapters/postgresql/schemas/introspection.js +478 -0
  59. package/dist/adapters/postgresql/schemas/introspection.js.map +1 -0
  60. package/dist/adapters/postgresql/schemas/jsonb.d.ts +8 -0
  61. package/dist/adapters/postgresql/schemas/jsonb.d.ts.map +1 -1
  62. package/dist/adapters/postgresql/schemas/jsonb.js +26 -2
  63. package/dist/adapters/postgresql/schemas/jsonb.js.map +1 -1
  64. package/dist/adapters/postgresql/schemas/monitoring.d.ts +41 -25
  65. package/dist/adapters/postgresql/schemas/monitoring.d.ts.map +1 -1
  66. package/dist/adapters/postgresql/schemas/monitoring.js +49 -16
  67. package/dist/adapters/postgresql/schemas/monitoring.js.map +1 -1
  68. package/dist/adapters/postgresql/schemas/partitioning.d.ts +16 -20
  69. package/dist/adapters/postgresql/schemas/partitioning.d.ts.map +1 -1
  70. package/dist/adapters/postgresql/schemas/partitioning.js +21 -10
  71. package/dist/adapters/postgresql/schemas/partitioning.js.map +1 -1
  72. package/dist/adapters/postgresql/schemas/partman.d.ts +69 -0
  73. package/dist/adapters/postgresql/schemas/partman.d.ts.map +1 -1
  74. package/dist/adapters/postgresql/schemas/partman.js +46 -33
  75. package/dist/adapters/postgresql/schemas/partman.js.map +1 -1
  76. package/dist/adapters/postgresql/schemas/performance.d.ts +37 -19
  77. package/dist/adapters/postgresql/schemas/performance.d.ts.map +1 -1
  78. package/dist/adapters/postgresql/schemas/performance.js +54 -12
  79. package/dist/adapters/postgresql/schemas/performance.js.map +1 -1
  80. package/dist/adapters/postgresql/schemas/postgis.d.ts.map +1 -1
  81. package/dist/adapters/postgresql/schemas/postgis.js +20 -0
  82. package/dist/adapters/postgresql/schemas/postgis.js.map +1 -1
  83. package/dist/adapters/postgresql/schemas/schema-mgmt.d.ts +15 -7
  84. package/dist/adapters/postgresql/schemas/schema-mgmt.d.ts.map +1 -1
  85. package/dist/adapters/postgresql/schemas/schema-mgmt.js +36 -7
  86. package/dist/adapters/postgresql/schemas/schema-mgmt.js.map +1 -1
  87. package/dist/adapters/postgresql/schemas/text-search.d.ts +26 -14
  88. package/dist/adapters/postgresql/schemas/text-search.d.ts.map +1 -1
  89. package/dist/adapters/postgresql/schemas/text-search.js +41 -9
  90. package/dist/adapters/postgresql/schemas/text-search.js.map +1 -1
  91. package/dist/adapters/postgresql/tools/admin.d.ts.map +1 -1
  92. package/dist/adapters/postgresql/tools/admin.js +82 -67
  93. package/dist/adapters/postgresql/tools/admin.js.map +1 -1
  94. package/dist/adapters/postgresql/tools/backup/dump.d.ts.map +1 -1
  95. package/dist/adapters/postgresql/tools/backup/dump.js +27 -24
  96. package/dist/adapters/postgresql/tools/backup/dump.js.map +1 -1
  97. package/dist/adapters/postgresql/tools/citext.js +114 -82
  98. package/dist/adapters/postgresql/tools/citext.js.map +1 -1
  99. package/dist/adapters/postgresql/tools/codemode/index.d.ts.map +1 -1
  100. package/dist/adapters/postgresql/tools/codemode/index.js +2 -11
  101. package/dist/adapters/postgresql/tools/codemode/index.js.map +1 -1
  102. package/dist/adapters/postgresql/tools/core/convenience.d.ts.map +1 -1
  103. package/dist/adapters/postgresql/tools/core/convenience.js +23 -8
  104. package/dist/adapters/postgresql/tools/core/convenience.js.map +1 -1
  105. package/dist/adapters/postgresql/tools/core/indexes.d.ts.map +1 -1
  106. package/dist/adapters/postgresql/tools/core/indexes.js +3 -2
  107. package/dist/adapters/postgresql/tools/core/indexes.js.map +1 -1
  108. package/dist/adapters/postgresql/tools/core/tables.d.ts.map +1 -1
  109. package/dist/adapters/postgresql/tools/core/tables.js +4 -4
  110. package/dist/adapters/postgresql/tools/core/tables.js.map +1 -1
  111. package/dist/adapters/postgresql/tools/cron.js +59 -27
  112. package/dist/adapters/postgresql/tools/cron.js.map +1 -1
  113. package/dist/adapters/postgresql/tools/introspection.d.ts +15 -0
  114. package/dist/adapters/postgresql/tools/introspection.d.ts.map +1 -0
  115. package/dist/adapters/postgresql/tools/introspection.js +1682 -0
  116. package/dist/adapters/postgresql/tools/introspection.js.map +1 -0
  117. package/dist/adapters/postgresql/tools/jsonb/advanced.d.ts.map +1 -1
  118. package/dist/adapters/postgresql/tools/jsonb/advanced.js +26 -17
  119. package/dist/adapters/postgresql/tools/jsonb/advanced.js.map +1 -1
  120. package/dist/adapters/postgresql/tools/jsonb/basic.d.ts.map +1 -1
  121. package/dist/adapters/postgresql/tools/jsonb/basic.js +92 -23
  122. package/dist/adapters/postgresql/tools/jsonb/basic.js.map +1 -1
  123. package/dist/adapters/postgresql/tools/ltree.d.ts.map +1 -1
  124. package/dist/adapters/postgresql/tools/ltree.js +17 -4
  125. package/dist/adapters/postgresql/tools/ltree.js.map +1 -1
  126. package/dist/adapters/postgresql/tools/monitoring.js +32 -21
  127. package/dist/adapters/postgresql/tools/monitoring.js.map +1 -1
  128. package/dist/adapters/postgresql/tools/partman/management.d.ts.map +1 -1
  129. package/dist/adapters/postgresql/tools/partman/management.js +32 -52
  130. package/dist/adapters/postgresql/tools/partman/management.js.map +1 -1
  131. package/dist/adapters/postgresql/tools/partman/operations.d.ts.map +1 -1
  132. package/dist/adapters/postgresql/tools/partman/operations.js +5 -5
  133. package/dist/adapters/postgresql/tools/partman/operations.js.map +1 -1
  134. package/dist/adapters/postgresql/tools/performance/analysis.d.ts.map +1 -1
  135. package/dist/adapters/postgresql/tools/performance/analysis.js +15 -8
  136. package/dist/adapters/postgresql/tools/performance/analysis.js.map +1 -1
  137. package/dist/adapters/postgresql/tools/performance/monitoring.d.ts.map +1 -1
  138. package/dist/adapters/postgresql/tools/performance/monitoring.js +10 -7
  139. package/dist/adapters/postgresql/tools/performance/monitoring.js.map +1 -1
  140. package/dist/adapters/postgresql/tools/performance/stats.d.ts.map +1 -1
  141. package/dist/adapters/postgresql/tools/performance/stats.js +62 -28
  142. package/dist/adapters/postgresql/tools/performance/stats.js.map +1 -1
  143. package/dist/adapters/postgresql/tools/pgcrypto.js +31 -11
  144. package/dist/adapters/postgresql/tools/pgcrypto.js.map +1 -1
  145. package/dist/adapters/postgresql/tools/postgis/advanced.d.ts.map +1 -1
  146. package/dist/adapters/postgresql/tools/postgis/advanced.js +30 -25
  147. package/dist/adapters/postgresql/tools/postgis/advanced.js.map +1 -1
  148. package/dist/adapters/postgresql/tools/postgis/basic.d.ts.map +1 -1
  149. package/dist/adapters/postgresql/tools/postgis/basic.js +24 -15
  150. package/dist/adapters/postgresql/tools/postgis/basic.js.map +1 -1
  151. package/dist/adapters/postgresql/tools/schema.js +79 -5
  152. package/dist/adapters/postgresql/tools/schema.js.map +1 -1
  153. package/dist/adapters/postgresql/tools/stats/advanced.d.ts.map +1 -1
  154. package/dist/adapters/postgresql/tools/stats/advanced.js +61 -39
  155. package/dist/adapters/postgresql/tools/stats/advanced.js.map +1 -1
  156. package/dist/adapters/postgresql/tools/stats/basic.d.ts.map +1 -1
  157. package/dist/adapters/postgresql/tools/stats/basic.js +45 -30
  158. package/dist/adapters/postgresql/tools/stats/basic.js.map +1 -1
  159. package/dist/adapters/postgresql/tools/text.js +327 -148
  160. package/dist/adapters/postgresql/tools/text.js.map +1 -1
  161. package/dist/auth/auth-context.d.ts +28 -0
  162. package/dist/auth/auth-context.d.ts.map +1 -0
  163. package/dist/auth/auth-context.js +37 -0
  164. package/dist/auth/auth-context.js.map +1 -0
  165. package/dist/auth/scope-map.d.ts +20 -0
  166. package/dist/auth/scope-map.d.ts.map +1 -0
  167. package/dist/auth/scope-map.js +40 -0
  168. package/dist/auth/scope-map.js.map +1 -0
  169. package/dist/auth/scopes.d.ts.map +1 -1
  170. package/dist/auth/scopes.js +2 -0
  171. package/dist/auth/scopes.js.map +1 -1
  172. package/dist/cli.js +1 -1
  173. package/dist/cli.js.map +1 -1
  174. package/dist/codemode/api.d.ts +1 -0
  175. package/dist/codemode/api.d.ts.map +1 -1
  176. package/dist/codemode/api.js +34 -0
  177. package/dist/codemode/api.js.map +1 -1
  178. package/dist/codemode/index.d.ts +0 -2
  179. package/dist/codemode/index.d.ts.map +1 -1
  180. package/dist/codemode/index.js +0 -4
  181. package/dist/codemode/index.js.map +1 -1
  182. package/dist/codemode/sandbox.d.ts +14 -1
  183. package/dist/codemode/sandbox.d.ts.map +1 -1
  184. package/dist/codemode/sandbox.js +58 -19
  185. package/dist/codemode/sandbox.js.map +1 -1
  186. package/dist/codemode/types.d.ts.map +1 -1
  187. package/dist/codemode/types.js +3 -0
  188. package/dist/codemode/types.js.map +1 -1
  189. package/dist/constants/ServerInstructions.d.ts +5 -1
  190. package/dist/constants/ServerInstructions.d.ts.map +1 -1
  191. package/dist/constants/ServerInstructions.js +91 -43
  192. package/dist/constants/ServerInstructions.js.map +1 -1
  193. package/dist/filtering/ToolConstants.d.ts +22 -19
  194. package/dist/filtering/ToolConstants.d.ts.map +1 -1
  195. package/dist/filtering/ToolConstants.js +48 -37
  196. package/dist/filtering/ToolConstants.js.map +1 -1
  197. package/dist/filtering/ToolFilter.d.ts.map +1 -1
  198. package/dist/filtering/ToolFilter.js +10 -13
  199. package/dist/filtering/ToolFilter.js.map +1 -1
  200. package/dist/pool/ConnectionPool.js +1 -1
  201. package/dist/pool/ConnectionPool.js.map +1 -1
  202. package/dist/transports/http.d.ts +1 -0
  203. package/dist/transports/http.d.ts.map +1 -1
  204. package/dist/transports/http.js +75 -21
  205. package/dist/transports/http.js.map +1 -1
  206. package/dist/types/filtering.d.ts +2 -2
  207. package/dist/types/filtering.d.ts.map +1 -1
  208. package/dist/utils/icons.d.ts.map +1 -1
  209. package/dist/utils/icons.js +5 -0
  210. package/dist/utils/icons.js.map +1 -1
  211. package/dist/utils/where-clause.d.ts.map +1 -1
  212. package/dist/utils/where-clause.js +24 -0
  213. package/dist/utils/where-clause.js.map +1 -1
  214. package/package.json +15 -12
  215. package/dist/codemode/sandbox-factory.d.ts +0 -72
  216. package/dist/codemode/sandbox-factory.d.ts.map +0 -1
  217. package/dist/codemode/sandbox-factory.js +0 -88
  218. package/dist/codemode/sandbox-factory.js.map +0 -1
  219. package/dist/codemode/worker-sandbox.d.ts +0 -82
  220. package/dist/codemode/worker-sandbox.d.ts.map +0 -1
  221. package/dist/codemode/worker-sandbox.js +0 -244
  222. package/dist/codemode/worker-sandbox.js.map +0 -1
  223. package/dist/codemode/worker-script.d.ts +0 -8
  224. package/dist/codemode/worker-script.d.ts.map +0 -1
  225. package/dist/codemode/worker-script.js +0 -113
  226. 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 February 22, 2026**
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, Code Mode, tool filtering, and extension support for citext, ltree, pgcrypto, pg_cron, pg_stat_kcache, pgvector, PostGIS, and HypoPG.
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
- **206 specialized tools** · **20 resources** · **19 AI-powered prompts**
9
+ **227 Specialized Tools** · **20 Resources** · **19 AI-Powered Prompts**
10
10
 
11
- [![GitHub](https://img.shields.io/badge/GitHub-neverinfamous/postgres--mcp-blue?logo=github)](https://github.com/neverinfamous/postgresql-mcp)
12
- ![GitHub Release](https://img.shields.io/github/v/release/neverinfamous/postgresql-mcp)
11
+ [![GitHub](https://img.shields.io/badge/GitHub-neverinfamous/postgres--mcp-blue?logo=github)](https://github.com/neverinfamous/postgres-mcp)
12
+ ![GitHub Release](https://img.shields.io/github/v/release/neverinfamous/postgres-mcp)
13
13
  [![Docker Pulls](https://img.shields.io/docker/pulls/writenotenow/postgres-mcp)](https://hub.docker.com/r/writenotenow/postgres-mcp)
14
14
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
15
15
  [![MCP](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/postgres-mcp)
16
16
  [![npm](https://img.shields.io/npm/v/@neverinfamous/postgres-mcp)](https://www.npmjs.com/package/@neverinfamous/postgres-mcp)
17
- [![Security](https://img.shields.io/badge/Security-Enhanced-green.svg)](https://github.com/neverinfamous/postgresql-mcp/blob/master/SECURITY.md)
17
+ [![Security](https://img.shields.io/badge/Security-Enhanced-green.svg)](https://github.com/neverinfamous/postgres-mcp/blob/main/SECURITY.md)
18
18
  ![Status](https://img.shields.io/badge/status-Production%2FStable-brightgreen)
19
- [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://github.com/neverinfamous/postgresql-mcp)
20
- [![Tests](https://img.shields.io/badge/Tests-2920_passed-success.svg)](https://github.com/neverinfamous/postgresql-mcp)
21
- [![Coverage](https://img.shields.io/badge/Coverage-92.05%25-brightgreen.svg)](https://github.com/neverinfamous/postgresql-mcp)
19
+ [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://github.com/neverinfamous/postgres-mcp)
20
+ [![Tests](https://img.shields.io/badge/Tests-3176_passed-success.svg)](https://github.com/neverinfamous/postgres-mcp)
21
+ [![Coverage](https://img.shields.io/badge/Coverage-93.58%25-brightgreen.svg)](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/postgresql-mcp/wiki)** • **[Changelog](https://github.com/neverinfamous/postgresql-mcp/blob/master/CHANGELOG.md)**
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 | Description |
28
- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29
- | **206 Specialized Tools** | The largest PostgreSQL tool collection for MCP — from core CRUD and native JSONB to pgvector, PostGIS, pg_cron, ltree, pgcrypto, 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** | Sandboxed JavaScript execution with 70-90% token reduction for multi-step operations |
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** | 20 tool groups + 15 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
- | **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 |
39
- | **Production-Ready Security** | SQL injection protection, parameterized queries, input validation, and sandboxed code execution |
40
- | **Strict TypeScript** | 100% type-safe codebase with 2376 tests and 85.37% coverage |
41
- | **MCP 2025-11-25 Compliant** | Full protocol support with tool safety hints, resource priorities, and progress notifications |
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
- - npm or yarn
49
+ - **Docker** (recommended) or Node.js 24+ (LTS)
50
50
 
51
- ### Installation
51
+ ### Docker (Recommended)
52
52
 
53
53
  ```bash
54
- git clone https://github.com/neverinfamous/postgresql-mcp.git
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:** 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:
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
- > 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.
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
- **Clone and install:**
183
+ See **[From Source](#from-source)** above for setup. After cloning:
109
184
 
110
185
  ```bash
111
- git clone https://github.com/neverinfamous/postgresql-mcp.git
112
- cd postgres-mcp
113
- npm install
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
- **Test CLI:**
192
+ ### Benchmarks
129
193
 
130
- ```bash
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 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.
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 | Tools | Use Case | What's Included |
228
- | -------------- | ------ | ------------------------ | -------------------------------------------------------- |
229
- | `starter` | **59** | 🌟 **Recommended** | Core, trans, JSONB, schema, codemode |
230
- | `essential` | 47 | Minimal footprint | Core, trans, JSONB, codemode |
231
- | `dev-power` | 54 | Power Developer | Core, trans, schema, stats, part, codemode |
232
- | `ai-data` | 60 | AI Data Analyst | Core, JSONB, text, trans, codemode |
233
- | `ai-vector` | 50 | AI/ML with pgvector | Core, vector, trans, part, codemode |
234
- | `dba-monitor` | 59 | DBA Monitoring | Core, monitoring, perf, trans, codemode |
235
- | `dba-manage` | 58 | DBA Management | Core, admin, backup, part, schema, codemode |
236
- | `dba-stats` | 57 | DBA Stats/Security | Core, admin, monitoring, trans, stats, codemode |
237
- | `geo` | 43 | Geospatial Workloads | Core, PostGIS, trans, codemode |
238
- | `base-core` | 59 | Base Building Block | Core, JSONB, trans, schema, codemode |
239
- | `base-ops` | 51 | Operations Block | Admin, monitoring, backup, part, stats, citext, codemode |
240
- | `ext-ai` | 26 | Extension: AI/Security | pgvector, pgcrypto, codemode |
241
- | `ext-geo` | 24 | Extension: Spatial | PostGIS, ltree, codemode |
242
- | `ext-schedule` | 19 | Extension: Scheduling | pg_cron, pg_partman, codemode |
243
- | `ext-perf` | 28 | Extension: Perf/Analysis | pg_stat_kcache, performance, codemode |
244
-
245
- ### Tool Groups (20 Available)
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 | Tools | Description |
250
- | -------------- | ----- | ----------------------------------------------------------- |
251
- | `core` | 21 | Read/write queries, tables, indexes, convenience/drop tools |
252
- | `transactions` | 8 | BEGIN, COMMIT, ROLLBACK, savepoints |
253
- | `jsonb` | 20 | JSONB manipulation and queries |
254
- | `text` | 14 | Full-text search, fuzzy matching |
255
- | `performance` | 21 | EXPLAIN, query analysis, optimization |
256
- | `admin` | 11 | VACUUM, ANALYZE, REINDEX |
257
- | `monitoring` | 12 | Database sizes, connections, status |
258
- | `backup` | 10 | pg_dump, COPY, restore |
259
- | `schema` | 13 | Schemas, views, sequences, functions, triggers |
260
- | `partitioning` | 7 | Native partition management |
261
- | `stats` | 9 | Statistical analysis |
262
- | `vector` | 17 | pgvector (AI/ML similarity search) |
263
- | `postgis` | 16 | PostGIS (geospatial) |
264
- | `cron` | 9 | pg_cron (job scheduling) |
265
- | `partman` | 11 | pg_partman (auto-partitioning) |
266
- | `kcache` | 8 | pg_stat_kcache (OS-level stats) |
267
- | `citext` | 7 | citext (case-insensitive text) |
268
- | `ltree` | 9 | ltree (hierarchical data) |
269
- | `pgcrypto` | 10 | pgcrypto (encryption, UUIDs) |
270
- | `codemode` | 1 | Code Mode (sandboxed code execution) |
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-manage` |
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, which are utility tools excluded from the published 206 count.
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":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAErE,kDAAkD;AAClD,EAAE,CAAC,IAAI,CAAC,uBAAuB,EAAE,GAAG,EAAE,CAAC,CAAC;IACtC,MAAM,EAAE;QACN,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE;QACd,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE;QACb,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE;QACb,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE;QAChB,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE;QACd,MAAM,EAAE,EAAE,CAAC,EAAE,EAAE;QACf,QAAQ,EAAE,EAAE,CAAC,EAAE,EAAE;QACjB,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE;QACd,SAAS,EAAE,EAAE,CAAC,EAAE,EAAE;QAClB,QAAQ,EAAE,EAAE,CAAC,EAAE,EAAE;QACjB,YAAY,EAAE,EAAE,CAAC,EAAE,EAAE;KACtB;CACF,CAAC,CAAC,CAAC;AAEJ,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAC9E,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,KAAK,CACH,qCAAqC,EACrC,GAAG,EAAE;QACH,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;QACzC,OAAO,CAAC,OAAO,EAAE,CAAC;IACpB,CAAC,EACD,EAAE,UAAU,EAAE,GAAG,EAAE,gBAAgB,EAAE,CAAC,EAAE,CACzC,CAAC;IAEF,KAAK,CACH,gCAAgC,EAChC,GAAG,EAAE;QACH,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;QACzC,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,kBAAkB;IACvC,CAAC,EACD,EAAE,UAAU,EAAE,GAAG,EAAE,gBAAgB,EAAE,CAAC,EAAE,CACzC,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAC9E,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,KAAK,CACH,sCAAsC,EACtC,GAAG,EAAE;QACH,MAAM,IAAI,GAAG,IAAI,WAAW,CAC1B,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,EAC3D,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,CAC5D,CAAC;QACF,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC,EACD,EAAE,UAAU,EAAE,GAAG,EAAE,gBAAgB,EAAE,CAAC,EAAE,CACzC,CAAC;IAEF,IAAI,WAAwB,CAAC;IAE7B,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;QAC/B,UAAU,CAAC,GAAG,EAAE;YACd,WAAW,GAAG,IAAI,WAAW,CAC3B,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,EAC3D,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,CAC5D,CAAC;YACF,WAAW,CAAC,UAAU,EAAE,CAAC;QAC3B,CAAC,CAAC,CAAC;QAEH,SAAS,CAAC,GAAG,EAAE;YACb,WAAW,EAAE,OAAO,EAAE,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,KAAK,CACH,4BAA4B,EAC5B,GAAG,EAAE;YACH,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC;YACtC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC,EACD,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAC3C,CAAC;QAEF,KAAK,CACH,qBAAqB,EACrB,GAAG,EAAE;YACH,WAAW,CAAC,QAAQ,EAAE,CAAC;QACzB,CAAC,EACD,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAC3C,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAC9E,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,IAAI,OAAwB,CAAC;IAE7B,UAAU,CAAC,GAAG,EAAE;QACd,OAAO,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,KAAK,CACH,sCAAsC,EACtC,KAAK,IAAI,EAAE;QACT,MAAM,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC,EACD,EAAE,UAAU,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CACpD,CAAC;IAEF,KAAK,CACH,sCAAsC,EACtC,KAAK,IAAI,EAAE;QACT,MAAM,WAAW,GAAkD,EAAE,CAAC;QACtE,MAAM,UAAU,GAAG;YACjB,MAAM;YACN,cAAc;YACd,OAAO;YACP,MAAM;YACN,aAAa;YACb,OAAO;YACP,YAAY;YACZ,QAAQ;YACR,QAAQ;YACR,cAAc;YACd,OAAO;YACP,QAAQ;YACR,SAAS;YACT,MAAM;YACN,SAAS;YACT,QAAQ;YACR,QAAQ;YACR,OAAO;YACP,UAAU;YACV,UAAU;SACX,CAAC;QACF,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;YAC/B,WAAW,CAAC,KAAK,CAAC,GAAG;gBACnB,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;gBAC5C,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;gBACvC,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE;aACf,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,CAAC,OAAO,CACnB,oDAAoD,EACpD,WAAW,CACZ,CAAC;IACJ,CAAC,EACD,EAAE,UAAU,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CACpD,CAAC;IAEF,KAAK,CACH,wBAAwB,EACxB,KAAK,IAAI,EAAE;QACT,MAAM,OAAO,CAAC,OAAO,CACnB,sDAAsD,EACtD,EAAE,CACH,CAAC;QACF,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAC/B,CAAC,EACD,EAAE,UAAU,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CACpD,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAC9E,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,MAAM,QAAQ,GAAG,IAAI,uBAAuB,EAAE,CAAC;IAE/C,KAAK,CACH,2CAA2C,EAC3C,GAAG,EAAE;QACH,QAAQ,CAAC,YAAY,CACnB,qDAAqD,CACtD,CAAC;IACJ,CAAC,EACD,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAC3C,CAAC;IAEF,KAAK,CACH,uCAAuC,EACvC,GAAG,EAAE;QACH,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CACR,eAAe,MAAM,CAAC,CAAC,CAAC,kDAAkD,MAAM,CAAC,CAAC,CAAC,cAAc,CAClG,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1C,CAAC,EACD,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAC3C,CAAC;IAEF,KAAK,CACH,+CAA+C,EAC/C,GAAG,EAAE;QACH,QAAQ,CAAC,YAAY,CAAC,2CAA2C,CAAC,CAAC;IACrE,CAAC,EACD,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAC3C,CAAC;IAEF,KAAK,CACH,6BAA6B,EAC7B,GAAG,EAAE;QACH,MAAM,UAAU,GAAG,IAAI,uBAAuB,CAAC;YAC7C,sBAAsB,EAAE,KAAK;SAC9B,CAAC,CAAC;QACH,UAAU,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC,EACD,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAC3C,CAAC;IAEF,KAAK,CACH,gCAAgC,EAChC,GAAG,EAAE;QACH,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAChE,CAAC,EACD,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAC3C,CAAC;IAEF,KAAK,CACH,4CAA4C,EAC5C,GAAG,EAAE;QACH,MAAM,MAAM,GAAG;YACb,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3C,EAAE,EAAE,CAAC;gBACL,IAAI,EAAE,QAAQ,MAAM,CAAC,CAAC,CAAC,EAAE;gBACzB,KAAK,EAAE,OAAO,MAAM,CAAC,CAAC,CAAC,cAAc;aACtC,CAAC,CAAC;SACJ,CAAC;QACF,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC,EACD,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAC3C,CAAC;AACJ,CAAC,CAAC,CAAC"}
@@ -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"}