@conte777/db-view-mcp 1.2.0 → 1.3.0

package/README.md

@@ -1,23 +1,22 @@
 # db-view-mcp
 
-MCP server that gives AI assistants direct access to PostgreSQL and ClickHouse databases. Supports stdio and HTTP transports, allowing both local IDE integration and remote network access.
+An MCP server that gives AI assistants direct access to PostgreSQL and ClickHouse databases. It
+supports both stdio and HTTP transports, for local IDE integration and remote network access.
 
 ## Features
 
-- **Multi-database** — connect to any number of PostgreSQL and ClickHouse instances simultaneously
+- **Multi-database** — connect any number of PostgreSQL and ClickHouse instances at once
 - **Dual transport** — stdio for IDE integration (Cursor, Claude Code), HTTP for remote/multi-client access
-- **Read & write tools** — SELECT queries with row limits, INSERT/UPDATE/DELETE, DDL, transactions
+- **Read & write tools** — SELECT with row limits, INSERT/UPDATE/DELETE, DDL, transactions
 - **Schema introspection** — list tables, describe columns, export full DDL
-- **Query analysis** — EXPLAIN ANALYZE support, slow query tracking
-- **SQL safety** — read-only tools validate SQL to block accidental writes
-- **Flexible tool modes** — single tool with `database` parameter, or separate tool per database
+- **Query analysis** — EXPLAIN / EXPLAIN ANALYZE, slow-query tracking
+- **SQL safety** — read-only tools validate SQL and block accidental writes
+- **Flexible tool modes** — one tool with a `database` parameter, or a separate tool per database
 - **Lazy connections** — databases connect on first use by default
-- **Bearer auth** — optional token-based authentication for HTTP transport
+- **Bearer auth** — optional token authentication for the HTTP transport
 - **Session management** — stateful (per-session MCP server) or stateless HTTP mode
 
-## Quick start
-
-### Install
+## Install
 
 ```bash
 npm install @conte777/db-view-mcp
@@ -32,7 +31,9 @@ npm install
 npm run build
 ```
 
-### Configure
+## Quick start
+
+### 1. Configure
 
 Copy the example config and edit it:
 
@@ -40,7 +41,7 @@ Copy the example config and edit it:
 cp config.example.json config.json
 ```
 
-Minimal config (stdio, default):
+Minimal stdio config:
 
 ```json
 {
@@ -58,66 +59,25 @@ Minimal config (stdio, default):
 }
 ```
 
-HTTP transport config:
+Every field, default, and the full config reference (SSL/TLS, per-database overrides, environment
+substitution, HTTP transport) is in [docs/configuration.md](docs/configuration.md).
 
-```json
-{
-  "transport": {
-    "type": "http",
-    "port": 3000,
-    "host": "127.0.0.1",
-    "stateless": false,
-    "auth": {
-      "type": "bearer",
-      "token": "your-secret-token"
-    }
-  },
-  "databases": [
-    {
-      "id": "main_pg",
-      "type": "postgresql",
-      "host": "localhost",
-      "port": 5432,
-      "database": "myapp",
-      "user": "admin",
-      "password": "secret123"
-    }
-  ]
-}
-```
-
-### Run
+### 2. Run
 
 ```bash
 # Stdio (default)
 npm start -- --config config.json
 
-# HTTP via config (set transport.type to "http" in config.json)
-npm start -- --config config.json
-
-# HTTP via CLI flag (overrides config)
+# HTTP (set transport.type to "http" in config, or override on the CLI)
 npm start -- --config config.json --transport http
 
 # Development (no build needed)
 npm run dev -- --config config.json
 ```
 
-### Add to your MCP client
-
-**Claude Desktop** (`claude_desktop_config.json`) — stdio:
-
-```json
-{
-  "mcpServers": {
-    "database": {
-      "command": "npx",
-      "args": ["-y", "@conte777/db-view-mcp", "--config", "/path/to/config.json"]
-    }
-  }
-}
-```
+### 3. Add an MCP client
 
-**Claude Code** (`.mcp.json`) — stdio:
+**Claude Desktop** (`claude_desktop_config.json`) or **Claude Code** (`.mcp.json`), stdio:
 
 ```json
 {
@@ -130,211 +90,35 @@ npm run dev -- --config config.json
 }
 ```
 
-**Any MCP client** — HTTP:
+**Any MCP client**, HTTP:
 
 ```bash
-# Start the server
 node dist/index.js --config config.json --transport http
 # Server listens on http://127.0.0.1:3000/mcp
 ```
 
-## Transport modes
-
-### Stdio (default)
-
-Communication via stdin/stdout. Best for local IDE integrations where the MCP client spawns the server process.
-
-### HTTP
-
-Uses the MCP Streamable HTTP transport (`POST/GET/DELETE /mcp`). Best for:
-- Remote access over the network
-- Multiple clients connecting simultaneously
-- Web application integrations
-
-**Stateful mode** (default): each MCP session gets its own `McpServer` instance with a unique session ID. All sessions share database connection pools. Supports transactions across requests within the same session.
-
-**Stateless mode** (`"stateless": true`): no session management. Each request is independent. Suitable for simple query scenarios without transactions.
-
-#### HTTP endpoints
+See [docs/http-transport.md](docs/http-transport.md) for sessions, auth, and curl examples.
 
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/mcp` | Send JSON-RPC requests (initialize, tools/call, etc.) |
-| `GET` | `/mcp` | SSE stream for server-to-client notifications |
-| `DELETE` | `/mcp` | Close a session |
-| `GET` | `/health` | Health check — status, active sessions, database list |
+## Documentation
 
-#### Authentication
-
-Optional bearer token authentication:
-
-```json
-{
-  "transport": {
-    "type": "http",
-    "auth": {
-      "type": "bearer",
-      "token": "your-secret-token"
-    }
-  }
-}
-```
-
-Requests to `/mcp` must include `Authorization: Bearer your-secret-token`. Requests without a valid token receive `401 Unauthorized`. The `/health` endpoint is not protected.
-
-#### Example: initialize a session
-
-```bash
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -H "Authorization: Bearer your-secret-token" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "initialize",
-    "params": {
-      "protocolVersion": "2025-03-26",
-      "capabilities": {},
-      "clientInfo": { "name": "test", "version": "1.0" }
-    }
-  }'
-```
-
-The response includes a `Mcp-Session-Id` header. Use it in subsequent requests:
-
-```bash
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -H "Authorization: Bearer your-secret-token" \
-  -H "Mcp-Session-Id: <session-id-from-init>" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 2,
-    "method": "tools/list",
-    "params": {}
-  }'
-```
-
-## Tools
-
-### Read-only
-
-| Tool | Description |
-|------|-------------|
-| `query` | Execute a SELECT query with automatic row limit |
-| `list_databases` | List all configured database connections |
-| `list_tables` | List tables and views in a schema |
-| `describe_table` | Get column names, types, nullability, and primary keys |
-| `schema` | Export full DDL for a database |
-| `explain_query` | Run EXPLAIN ANALYZE (PostgreSQL) or EXPLAIN (ClickHouse) |
-| `performance` | Track and retrieve slow queries, set thresholds |
-
-### Write
-
-| Tool | Description |
-|------|-------------|
-| `execute` | Run INSERT, UPDATE, DELETE, or DDL statements |
-| `transaction` | Begin, execute within, commit, or rollback transactions (PostgreSQL only) |
-
-## Configuration
-
-### Transport
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `transport.type` | `"stdio"` \| `"http"` | `"stdio"` | Transport mode |
-| `transport.port` | number | `3000` | HTTP listen port |
-| `transport.host` | string | `"127.0.0.1"` | HTTP bind address |
-| `transport.stateless` | boolean | `false` | Disable session management |
-| `transport.auth.type` | `"bearer"` | — | Authentication type |
-| `transport.auth.token` | string | — | Bearer token value |
-
-The `transport` field is optional. When omitted, stdio is used. The `--transport` CLI flag overrides the config value.
-
-### Defaults
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `maxRows` | number | `100` | Maximum rows returned by `query` |
-| `lazyConnection` | boolean | `true` | Connect on first use instead of at startup |
-| `toolsPerDatabase` | boolean | `false` | Register separate tools per database (e.g. `query_main_pg`) |
-| `queryTimeout` | number | `30000` | Query timeout in milliseconds |
-
-### PostgreSQL database
-
-| Field | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `id` | yes | — | Unique identifier |
-| `type` | yes | — | Must be `"postgresql"` |
-| `host` | yes | — | Hostname |
-| `port` | no | `5432` | Port |
-| `database` | yes | — | Database name |
-| `user` | yes | — | Username |
-| `password` | no | `""` | Password |
-| `ssl` | no | — | Enable SSL |
-| `description` | no | — | Human-readable label |
-| `lazyConnection` | no | inherits | Override default |
-| `maxRows` | no | inherits | Override default |
-| `queryTimeout` | no | inherits | Override default |
-
-### ClickHouse database
-
-| Field | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `id` | yes | — | Unique identifier |
-| `type` | yes | — | Must be `"clickhouse"` |
-| `url` | yes | — | HTTP URL (e.g. `http://localhost:8123`) |
-| `database` | yes | — | Database name |
-| `user` | no | `"default"` | Username |
-| `password` | no | `""` | Password |
-| `description` | no | — | Human-readable label |
-| `lazyConnection` | no | inherits | Override default |
-| `maxRows` | no | inherits | Override default |
-| `queryTimeout` | no | inherits | Override default |
-
-### Per-database tool mode
-
-Set `"toolsPerDatabase": true` in defaults to register a separate tool for each database. Instead of a single `query` tool with a `database` parameter, you get `query_main_pg`, `query_analytics`, etc. Useful when connecting many databases to avoid parameter confusion.
-
-## Architecture
-
-```
-src/
-├── index.ts              Entry point: CLI args → config → transport routing
-├── server.ts             Creates McpServer + ConnectorManager, registers tools
-├── config/
-│   ├── types.ts          Zod schemas for config validation (transport, databases)
-│   └── loader.ts         Reads config file, parses CLI args (--config, --transport)
-├── connectors/
-│   ├── interface.ts      Connector interface and shared types
-│   ├── manager.ts        Connector lifecycle (lazy/eager, create, disconnect)
-│   ├── postgresql.ts     PostgreSQL implementation (pg)
-│   └── clickhouse.ts     ClickHouse implementation (@clickhouse/client)
-├── tools/
-│   ├── registry.ts       Registers tools in parameter or per-database mode
-│   ├── readonly/         query, list-tables, describe-table, schema, explain, performance
-│   └── write/            execute, transaction
-├── transport/
-│   └── http.ts           HTTP transport: Express app, session management, auth
-└── utils/
-    ├── response.ts       Standardized MCP response formatting
-    └── sql-validator.ts   Blocks write keywords in read-only queries
-```
+| Doc | Contents |
+|-----|----------|
+| [docs/configuration.md](docs/configuration.md) | Every config field, defaults, SSL/TLS, `rowFormat`, env substitution, hot reload |
+| [docs/tools.md](docs/tools.md) | The 9 tools: params, output, examples, error codes, per-database mode |
+| [docs/http-transport.md](docs/http-transport.md) | stdio vs HTTP, sessions, bearer auth, `/health`, curl |
+| [docs/security.md](docs/security.md) | Read-only SQL validator, deny-lists, response caps, network exposure |
+| [docs/architecture.md](docs/architecture.md) | Source tree, layers, connector model, lifecycle (hot reload, shutdown) |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Build, test, lint, hooks, CI |
 
 ## ClickHouse limitations
 
-- Transactions are not supported (throws an error)
-- Query parameters via `params` are ignored — use ClickHouse's native `{name:Type}` syntax in SQL
+- Transactions are not supported (`transaction begin` throws).
+- Query `params` are ignored — use ClickHouse's native `{name:Type}` syntax in the SQL.
 
 ## Development
 
-```bash
-npm run dev -- --config config.json   # Run with tsx, auto-reload
-npm run build                         # Compile TypeScript to dist/
-npm start -- --config config.json     # Run compiled output
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for build/test/lint commands, coverage thresholds, git
+hooks, and CI.
 
 ## License
 

package/config.example.json

@@ -4,6 +4,7 @@
     "port": 3000,
     "host": "127.0.0.1",
     "stateless": false,
+    "sessionTimeout": 1800000,
     "auth": {
       "type": "bearer",
       "token": "your-secret-token"
@@ -13,7 +14,8 @@
     "maxRows": 100,
     "lazyConnection": true,
     "toolsPerDatabase": false,
-    "queryTimeout": 30000
+    "queryTimeout": 30000,
+    "rowFormat": "json"
   },
   "databases": [
     {

package/dist/config/types.d.ts

@@ -70,10 +70,14 @@ declare const DefaultsSchema: z.ZodObject<{
     toolsPerDatabase: z.ZodDefault<z.ZodBoolean>;
     queryTimeout: z.ZodDefault<z.ZodNumber>;
     logLevel: z.ZodDefault<z.ZodEnum<{
+        error: "error";
         debug: "debug";
         info: "info";
         warn: "warn";
-        error: "error";
+    }>>;
+    rowFormat: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        table: "table";
     }>>;
 }, z.core.$strip>;
 declare const HttpTransportConfigSchema: z.ZodObject<{
@@ -120,23 +124,29 @@ export declare const AppConfigSchema: z.ZodObject<{
         toolsPerDatabase: z.ZodDefault<z.ZodBoolean>;
         queryTimeout: z.ZodDefault<z.ZodNumber>;
         logLevel: z.ZodDefault<z.ZodEnum<{
+            error: "error";
             debug: "debug";
             info: "info";
             warn: "warn";
-            error: "error";
+        }>>;
+        rowFormat: z.ZodDefault<z.ZodEnum<{
+            json: "json";
+            table: "table";
         }>>;
     }, z.core.$strip>>, z.ZodTransform<{
         maxRows: number;
         lazyConnection: boolean;
         toolsPerDatabase: boolean;
         queryTimeout: number;
-        logLevel: "debug" | "info" | "warn" | "error";
+        logLevel: "error" | "debug" | "info" | "warn";
+        rowFormat: "json" | "table";
     }, {
         maxRows: number;
         lazyConnection: boolean;
         toolsPerDatabase: boolean;
         queryTimeout: number;
-        logLevel: "debug" | "info" | "warn" | "error";
+        logLevel: "error" | "debug" | "info" | "warn";
+        rowFormat: "json" | "table";
     } | undefined>>;
     databases: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         id: z.ZodString;

package/dist/config/types.js

@@ -13,7 +13,7 @@ const PostgresConfigBaseSchema = z.object({
     sslCa: z.string().optional(),
     description: z.string().optional(),
     lazyConnection: z.boolean().optional(),
-    maxRows: z.number().optional(),
+    maxRows: z.number().int().positive().optional(),
     queryTimeout: z.number().optional(),
 });
 const PostgresConfigSchema = PostgresConfigBaseSchema.superRefine((data, ctx) => {
@@ -39,17 +39,18 @@ const ClickHouseConfigSchema = z.object({
         .optional(),
     description: z.string().optional(),
     lazyConnection: z.boolean().optional(),
-    maxRows: z.number().optional(),
+    maxRows: z.number().int().positive().optional(),
     queryTimeout: z.number().optional(),
 });
 const DatabaseConfigSchema = z.union([PostgresConfigSchema, ClickHouseConfigSchema]);
 const LogLevelSchema = z.enum(["debug", "info", "warn", "error"]);
 const DefaultsSchema = z.object({
-    maxRows: z.number().default(100),
+    maxRows: z.number().int().positive().default(100),
     lazyConnection: z.boolean().default(true),
     toolsPerDatabase: z.boolean().default(false),
     queryTimeout: z.number().default(30000),
     logLevel: LogLevelSchema.default("info"),
+    rowFormat: z.enum(["json", "table"]).default("json"),
 });
 const HttpTransportConfigSchema = z.object({
     type: z.literal("http"),
@@ -70,13 +71,7 @@ const StdioTransportConfigSchema = z.object({
 const TransportConfigSchema = z.discriminatedUnion("type", [StdioTransportConfigSchema, HttpTransportConfigSchema]);
 export const AppConfigSchema = z.object({
     transport: TransportConfigSchema.optional().default({ type: "stdio" }),
-    defaults: DefaultsSchema.optional().transform((v) => v ?? {
-        maxRows: 100,
-        lazyConnection: true,
-        toolsPerDatabase: false,
-        queryTimeout: 30000,
-        logLevel: "info",
-    }),
+    defaults: DefaultsSchema.optional().transform((v) => v ?? DefaultsSchema.parse({})),
     databases: z.array(DatabaseConfigSchema).min(1),
 });
 export function resolveDbConfig(db, defaults) {

package/dist/config/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IAC7B,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAC9B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAChC,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC3B,qBAAqB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAChD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACtC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC;AAEH,MAAM,oBAAoB,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;IAC9E,IAAI,CAAC,IAAI,CAAC,gBAAgB,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3E,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,4EAA4E;SACtF,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IAC7B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC;IACnC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAChC,GAAG,EAAE,CAAC;SACH,MAAM,CAAC;QACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACzB,kBAAkB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;KAC9C,CAAC;SACD,QAAQ,EAAE;IACb,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACtC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC;AAEH,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,oBAAoB,EAAE,sBAAsB,CAAC,CAAC,CAAC;AAErF,MAAM,cAAc,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAElE,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IAChC,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACzC,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC5C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACvC,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC;CACzC,CAAC,CAAC;AAEH,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACvB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAC9B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC;IACrC,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACrC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,aAAa;IACjE,IAAI,EAAE,CAAC;SACJ,MAAM,CAAC;QACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QACzB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;KAClB,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAEH,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,qBAAqB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE,CAAC,0BAA0B,EAAE,yBAAyB,CAAC,CAAC,CAAC;AAEpH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,SAAS,EAAE,qBAAqB,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACtE,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE,CAAC,SAAS,CAC3C,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,IAAI;QACH,OAAO,EAAE,GAAG;QACZ,cAAc,EAAE,IAAI;QACpB,gBAAgB,EAAE,KAAK;QACvB,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,MAAe;KAC1B,CACJ;IACD,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAChD,CAAC,CAAC;AAgBH,MAAM,UAAU,eAAe,CAAC,EAAkB,EAAE,QAAkB;IACpE,OAAO;QACL,GAAG,EAAE;QACL,cAAc,EAAE,EAAE,CAAC,cAAc,IAAI,QAAQ,CAAC,cAAc;QAC5D,OAAO,EAAE,EAAE,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;QACvC,YAAY,EAAE,EAAE,CAAC,YAAY,IAAI,QAAQ,CAAC,YAAY;KAC7B,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"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"}

package/dist/connectors/clickhouse.d.ts

@@ -1,5 +1,5 @@
-import type { Connector, QueryResult, TableInfo, ColumnInfo, ExplainResult, TransactionHandle } from "./interface.js";
 import type { ClickHouseConfig } from "../config/types.js";
+import type { ColumnInfo, Connector, ExplainResult, QueryResult, TableInfo, TransactionHandle } from "./interface.js";
 export declare class ClickHouseConnector implements Connector {
     readonly type: "clickhouse";
     private client;

package/dist/connectors/clickhouse.js

@@ -1,5 +1,6 @@
-import { createClient } from "@clickhouse/client";
 import { readFileSync } from "node:fs";
+import { createClient } from "@clickhouse/client";
+import { wrapReadonlyQuery } from "../utils/sql-validator.js";
 export class ClickHouseConnector {
     type = "clickhouse";
     client = null;
@@ -43,8 +44,15 @@ export class ClickHouseConnector {
     }
     async query(sql, _params, maxRows) {
         const limit = maxRows ?? this.maxRows;
-        const wrappedSql = `SELECT * FROM (${sql}) AS _q LIMIT ${limit}`;
-        const result = await this.getClient().query({ query: wrappedSql, format: "JSONEachRow" });
+        const wrappedSql = wrapReadonlyQuery(sql, limit, "clickhouse");
+        // The sql-validator deny-list is the primary guard against url()/file()/s3() SSRF; readonly:1
+        // is defense-in-depth (it reliably blocks writes and settings changes, not necessarily every
+        // read-side table function).
+        const result = await this.getClient().query({
+            query: wrappedSql,
+            format: "JSONEachRow",
+            clickhouse_settings: { readonly: "1" },
+        });
         const rows = (await result.json());
         return { rows, rowCount: rows.length };
     }

package/dist/connectors/clickhouse.js.map

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

package/dist/connectors/manager.d.ts

@@ -1,10 +1,11 @@
-import type { Connector } from "./interface.js";
 import type { ResolvedDatabaseConfig } from "../config/types.js";
 import { PerformanceTracker } from "../tools/readonly/performance.js";
+import type { Connector } from "./interface.js";
 export declare class ConnectorManager {
     private configs;
     private connectors;
     private rawConnectors;
+    private connecting;
     private tracker;
     constructor(databases: ResolvedDatabaseConfig[]);
     getDatabaseIds(): string[];
@@ -12,7 +13,11 @@ export declare class ConnectorManager {
     getAllConfigs(): ResolvedDatabaseConfig[];
     getPerformanceTracker(): PerformanceTracker;
     getConnector(dbId: string): Promise<Connector>;
-    withConnector<T>(dbId: string, fn: (connector: Connector) => Promise<T>): Promise<T>;
+    resolveId(input: string): string;
+    acquire(input: string): Promise<{
+        id: string;
+        connector: Connector;
+    }>;
     invalidateConnector(dbId: string): void;
     private createConnector;
     updateDatabases(newConfigs: ResolvedDatabaseConfig[]): {

package/dist/connectors/manager.js

@@ -1,25 +1,13 @@
-import { PostgresConnector } from "./postgresql.js";
+import { PerformanceTracker } from "../tools/readonly/performance.js";
+import { resolveDbId } from "../utils/resolve-db.js";
 import { ClickHouseConnector } from "./clickhouse.js";
 import { InstrumentedConnector } from "./instrumented.js";
-import { PerformanceTracker } from "../tools/readonly/performance.js";
-import { getLogger } from "../utils/logger.js";
-const CONNECTION_ERROR_CODES = new Set(["ECONNREFUSED", "ECONNRESET", "EPIPE", "ETIMEDOUT"]);
-function isConnectionError(err) {
-    if (err instanceof Error) {
-        const code = err.code;
-        if (code && CONNECTION_ERROR_CODES.has(code))
-            return true;
-        if (err.message.includes("Connection terminated"))
-            return true;
-        if (err.message.includes("connection refused"))
-            return true;
-    }
-    return false;
-}
+import { PostgresConnector } from "./postgresql.js";
 export class ConnectorManager {
     configs = new Map();
     connectors = new Map();
     rawConnectors = new Map();
+    connecting = new Map();
     tracker = new PerformanceTracker();
     constructor(databases) {
         for (const db of databases) {
@@ -42,32 +30,47 @@ export class ConnectorManager {
         const existing = this.connectors.get(dbId);
         if (existing)
             return existing;
+        const inFlight = this.connecting.get(dbId);
+        if (inFlight)
+            return inFlight;
         const config = this.configs.get(dbId);
         if (!config)
             throw new Error(`Unknown database: ${dbId}`);
-        const raw = this.createConnector(config);
-        await raw.connect();
-        this.rawConnectors.set(dbId, raw);
-        const instrumented = new InstrumentedConnector(raw, this.tracker, dbId);
-        this.connectors.set(dbId, instrumented);
-        return instrumented;
-    }
-    async withConnector(dbId, fn) {
-        const connector = await this.getConnector(dbId);
+        // Store the connect promise before awaiting so concurrent callers hitting
+        // the same miss join this one instead of each creating their own pool.
+        const connectPromise = (async () => {
+            const raw = this.createConnector(config);
+            await raw.connect();
+            // A concurrent updateDatabases()/invalidateConnector() may have replaced or removed this
+            // db's config while we were connecting. Storing the connector now would pin the manager to
+            // superseded (e.g. rotated/revoked) credentials, so discard it and let the caller retry.
+            if (this.configs.get(dbId) !== config) {
+                await raw.disconnect().catch(() => { });
+                throw new Error(`Database "${dbId}" was reconfigured during connection; please retry`);
+            }
+            this.rawConnectors.set(dbId, raw);
+            const instrumented = new InstrumentedConnector(raw, this.tracker, dbId);
+            this.connectors.set(dbId, instrumented);
+            return instrumented;
+        })();
+        this.connecting.set(dbId, connectPromise);
         try {
-            return await fn(connector);
+            return await connectPromise;
         }
-        catch (err) {
-            if (isConnectionError(err)) {
-                const logger = getLogger();
-                logger.warn("Connection error, retrying", { database: dbId, error: String(err) });
-                this.invalidateConnector(dbId);
-                const retryConnector = await this.getConnector(dbId);
-                return await fn(retryConnector);
-            }
-            throw err;
+        finally {
+            this.connecting.delete(dbId);
         }
     }
+    // Single source of truth for fuzzy id resolution. Handlers must go through this (or acquire())
+    // rather than calling resolveDbId directly, so id-resolution stays consistent everywhere.
+    resolveId(input) {
+        return resolveDbId(this.getDatabaseIds(), input);
+    }
+    async acquire(input) {
+        const id = this.resolveId(input);
+        const connector = await this.getConnector(id);
+        return { id, connector };
+    }
     invalidateConnector(dbId) {
         const raw = this.rawConnectors.get(dbId);
         if (raw) {