schema-navigator-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EcoPanel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# schema-navigator-mcp
+
+[![npm version](https://img.shields.io/npm/v/schema-navigator-mcp.svg)](https://www.npmjs.com/package/schema-navigator-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+**MCP server for PostgreSQL schema introspection.** Gives Claude live access to your database structure — columns, types, constraints, foreign keys, RLS policies, functions, and more.
+
+Works with any PostgreSQL-compatible database: **Supabase**, **Neon**, **Railway**, **CockroachDB**, **AWS Aurora**, **local Postgres**.
+
+## Why
+
+The most common bugs when working with databases:
+
+1. **Wrong column names** — `total_price` doesn't exist, it's `total_amount`
+2. **Invalid constraint values** — `'complete'` is not an allowed status
+3. **RLS client mismatch** — browser client blocked by row-level security
+4. **Blind migrations** — dropping a column referenced by 5 foreign keys
+
+This server eliminates all four by giving your AI assistant live schema access.
+
+## Quick Start
+
+### Option 1: Supabase (no password needed)
+
+The easiest setup for Supabase projects. Uses the [Management API](https://supabase.com/docs/reference/api/introduction) — no database password or connection string required.
+
+1. Get a Personal Access Token from [supabase.com/dashboard/account/tokens](https://supabase.com/dashboard/account/tokens)
+2. Find your project ref in your dashboard URL: `supabase.com/dashboard/project/<project-ref>`
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "db": {
+      "command": "npx",
+      "args": ["-y", "schema-navigator-mcp@latest"],
+      "env": {
+        "SUPABASE_ACCESS_TOKEN": "sbp_...",
+        "SUPABASE_PROJECT_REF": "your-project-ref"
+      }
+    }
+  }
+}
+```
+
+Or if you already have `SUPABASE_URL` or `NEXT_PUBLIC_SUPABASE_URL` set, the project ref is extracted automatically:
+
+```json
+{
+  "mcpServers": {
+    "db": {
+      "command": "npx",
+      "args": ["-y", "schema-navigator-mcp@latest"],
+      "env": {
+        "SUPABASE_ACCESS_TOKEN": "sbp_...",
+        "SUPABASE_URL": "${SUPABASE_URL}"
+      }
+    }
+  }
+}
+```
+
+### Option 2: Direct connection (any PostgreSQL)
+
+Works with any PostgreSQL-compatible database — Supabase, Neon, Railway, CockroachDB, AWS Aurora, local Postgres.
+
+```json
+{
+  "mcpServers": {
+    "db": {
+      "command": "npx",
+      "args": ["-y", "schema-navigator-mcp@latest"],
+      "env": { "DATABASE_URL": "${DATABASE_URL}" }
+    }
+  }
+}
+```
+
+Set `DATABASE_URL` in your environment (e.g. `.env.local`) and restart Claude Code.
+
+### Priority
+
+If both are set, `DATABASE_URL` takes priority (direct connection is faster and has no rate limits).
+
+### With the schema-nav Plugin
+
+For slash commands (`/db:table`, `/db:find`, etc.) and auto-activated validation skills, install the companion [schema-nav](https://github.com/ivnv00/schema-nav) plugin.
+
+## Tools
+
+7 read-only tools, each under 200 chars description (~4.9K total context cost):
+
+| Tool | What it does |
+|------|-------------|
+| `schema_overview` | Database dashboard — all tables with row counts and sizes, views, enums, extensions, health warnings |
+| `schema_table` | Complete profile of a table/view/matview — columns, types, defaults, constraints, FKs, indexes, RLS, grants |
+| `schema_find` | Cross-schema search across tables, columns, functions, views, policies, enums, comments |
+| `schema_relations` | FK relationship graph — outbound and inbound references with cascade actions |
+| `schema_functions` | Function inspector — arguments, return type, language, volatility, security definer, source code |
+| `schema_constraints` | Value extractor — allowed values from CHECK constraints and ENUM types, merged |
+| `schema_policies` | RLS analyzer — enabled status, policy expressions, role-by-operation access matrix |
+
+### Example: `schema_table`
+
+```
+schema_table("orders") →
+{
+  "object_type": "table",
+  "columns": [
+    { "name": "id", "type": "uuid", "nullable": false, "default": "gen_random_uuid()" },
+    { "name": "status", "type": "text", "nullable": false, "comment": "Order lifecycle state" },
+    { "name": "total_amount", "type": "numeric", "nullable": false },
+    ...
+  ],
+  "constraints": [
+    { "type": "CHECK", "column": "status", "allowed_values": ["pending", "processing", "shipped", ...] }
+  ],
+  "fks_in": [
+    { "from_table": "order_items", "from_column": "order_id", "on_delete": "CASCADE" }
+  ],
+  "rls_enabled": true,
+  "row_count": 51200,
+  "total_size": "32.1 MB"
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  schema-navigator-mcp                                   │
+│                                                         │
+│  ┌─ DATABASE_URL ──► PgAdapter (pg.Pool)                │
+│  │                    ├── BEGIN TRANSACTION READ ONLY    │
+│  │                    ├── query (15s timeout)            │
+│  │                    └── COMMIT                         │
+│  │                                                      │
+│  └─ SUPABASE_ACCESS_TOKEN ──► SupabaseAdapter           │
+│                                ├── Management API       │
+│                                ├── batch N queries → 1  │
+│                                └── 30s timeout          │
+│                                                         │
+│  7 tools registered via MCP SDK                         │
+│  stdio transport (JSON-RPC)                             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Direct connection (PgAdapter)
+
+- **Read-only transactions** — every query wrapped in `BEGIN TRANSACTION READ ONLY`. Cannot modify data.
+- **Connection pooling** — `pg.Pool` with max 5 connections, 5s connect timeout, 30s idle timeout.
+- **Query timeout** — 15s `statement_timeout` prevents hanging queries.
+- **Graceful shutdown** — SIGINT/SIGTERM handlers close pool connections cleanly.
+
+### Supabase Management API (SupabaseAdapter)
+
+- **Zero-password** — authenticates via Personal Access Token, no database credentials needed.
+- **Batch queries** — multiple queries batched into a single API call using `json_build_array`, staying within the 10 req/min rate limit.
+- **Parameter inlining** — `$1`, `$2` placeholders safely inlined with SQL escaping (all params are Zod-validated schema/table names).
+- **30s timeout** — per-request timeout with `AbortController`.
+
+## Universality
+
+The server uses two query layers with automatic detection:
+
+**Universal** (`information_schema` — SQL standard):
+- Tables, columns, data types, defaults, nullability
+- Foreign keys, CHECK constraints, UNIQUE constraints
+- Views, routines, triggers
+
+**PostgreSQL-specific** (`pg_catalog` — graceful degradation):
+- RLS policies → returns `[]` + note on non-Postgres
+- ENUM types → returns `[]`
+- Function source code → signature-only fallback
+- Table sizes, row estimates → `null`
+- Column comments → `null`
+
+Detection runs once at startup via `SELECT version()`.
+
+## Programmatic API
+
+```typescript
+import { createSchemaNavigator } from "schema-navigator-mcp";
+
+// Direct PostgreSQL connection
+const server = await createSchemaNavigator("postgresql://...");
+
+// Supabase Management API
+const server = await createSchemaNavigator({
+  accessToken: "sbp_...",
+  projectRef: "your-project-ref",
+});
+
+// server is an McpServer instance — connect your own transport
+```
+
+## Security
+
+- **Read-only** — direct connections use read-only transactions; Management API queries are all SELECT statements
+- **No credentials stored** — `DATABASE_URL` / `SUPABASE_ACCESS_TOKEN` from environment only
+- **No data access** — introspects schema metadata, never reads table data
+- **Parameterized queries** — direct connections use native `$1` parameters; Management API inlines with SQL escaping (all inputs are Zod-validated)
+
+## Requirements
+
+- Node.js >= 18
+- One of:
+  - `DATABASE_URL` — any PostgreSQL-compatible connection string
+  - `SUPABASE_ACCESS_TOKEN` + `SUPABASE_PROJECT_REF` (or `SUPABASE_URL` / `NEXT_PUBLIC_SUPABASE_URL`)
+
+## License
+
+MIT

package/dist/db/pg-adapter.d.ts

@@ -0,0 +1,17 @@
+import type { QueryAdapter, QueryResult } from "./types.js";
+export declare class PgAdapter implements QueryAdapter {
+    private pool;
+    private _isPostgres;
+    private _version;
+    constructor(connectionString: string);
+    get isPostgres(): boolean;
+    get version(): string | null;
+    /** Must be called once after construction, before any tool queries. */
+    detectVersion(): Promise<void>;
+    query<T = any>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    multiQuery(queries: Array<{
+        sql: string;
+        params?: unknown[];
+    }>): Promise<QueryResult[]>;
+    shutdown(): Promise<void>;
+}

package/dist/db/pg-adapter.js

@@ -0,0 +1,74 @@
+import pg from "pg";
+const { Pool } = pg;
+const QUERY_TIMEOUT_MS = 15000;
+export class PgAdapter {
+    pool;
+    _isPostgres = false;
+    _version = null;
+    constructor(connectionString) {
+        this.pool = new Pool({
+            connectionString,
+            max: 5,
+            connectionTimeoutMillis: 5000,
+            idleTimeoutMillis: 30000,
+            statement_timeout: QUERY_TIMEOUT_MS,
+        });
+        this.pool.on("error", (err) => {
+            console.error("Unexpected pool error:", err.message);
+        });
+    }
+    get isPostgres() {
+        return this._isPostgres;
+    }
+    get version() {
+        return this._version;
+    }
+    /** Must be called once after construction, before any tool queries. */
+    async detectVersion() {
+        const result = await this.pool.query("SELECT version()");
+        const version = result.rows[0]?.version;
+        this._isPostgres = /postgresql/i.test(version);
+        this._version = version;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async query(sql, params) {
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN TRANSACTION READ ONLY");
+            const result = await client.query(sql, params);
+            await client.query("COMMIT");
+            return { rows: result.rows, rowCount: result.rowCount ?? 0 };
+        }
+        catch (err) {
+            await client.query("ROLLBACK").catch(() => { });
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async multiQuery(queries) {
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN TRANSACTION READ ONLY");
+            const results = [];
+            for (const q of queries) {
+                const r = await client.query(q.sql, q.params);
+                results.push({ rows: r.rows, rowCount: r.rowCount ?? 0 });
+            }
+            await client.query("COMMIT");
+            return results;
+        }
+        catch (err) {
+            await client.query("ROLLBACK").catch(() => { });
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async shutdown() {
+        await this.pool.end();
+    }
+}
+//# sourceMappingURL=pg-adapter.js.map

package/dist/db/pg-adapter.js.map

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

package/dist/db/postgres.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Thin facade over the active QueryAdapter.
+ *
+ * Tools import readOnlyQuery / readOnlyMultiQuery / getIsPostgres from here.
+ * The actual backend (pg.Pool or Supabase Management API) is set once at
+ * startup via setAdapter().
+ */
+import type { QueryAdapter, QueryResult } from "./types.js";
+export declare function setAdapter(a: QueryAdapter): void;
+export declare function getAdapter(): QueryAdapter | null;
+export type { QueryResult };
+export declare function getIsPostgres(): boolean;
+export declare function getPostgresVersion(): string | null;
+export declare function readOnlyQuery<T = any>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+export declare function readOnlyMultiQuery(queries: Array<{
+    sql: string;
+    params?: unknown[];
+}>): Promise<QueryResult[]>;
+export declare function shutdownPool(): Promise<void>;

package/dist/db/postgres.js

@@ -0,0 +1,34 @@
+let adapter = null;
+export function setAdapter(a) {
+    adapter = a;
+}
+export function getAdapter() {
+    return adapter;
+}
+// ── Existing exports preserved for tool compatibility ──
+export function getIsPostgres() {
+    if (!adapter)
+        throw new Error("Adapter not initialized");
+    return adapter.isPostgres;
+}
+export function getPostgresVersion() {
+    return adapter?.version ?? null;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function readOnlyQuery(sql, params) {
+    if (!adapter)
+        throw new Error("Adapter not initialized");
+    return adapter.query(sql, params);
+}
+export async function readOnlyMultiQuery(queries) {
+    if (!adapter)
+        throw new Error("Adapter not initialized");
+    return adapter.multiQuery(queries);
+}
+export async function shutdownPool() {
+    if (adapter) {
+        await adapter.shutdown();
+        adapter = null;
+    }
+}
+//# sourceMappingURL=postgres.js.map

package/dist/db/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../../src/db/postgres.ts"],"names":[],"mappings":"AASA,IAAI,OAAO,GAAwB,IAAI,CAAC;AAExC,MAAM,UAAU,UAAU,CAAC,CAAe;IACxC,OAAO,GAAG,CAAC,CAAC;AACd,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC;AACjB,CAAC;AAMD,0DAA0D;AAE1D,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC,UAAU,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC;AAClC,CAAC;AAED,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAW,EACX,MAAkB;IAElB,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC,KAAK,CAAI,GAAG,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAmD;IAEnD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzB,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/db/supabase-adapter.d.ts

@@ -0,0 +1,45 @@
+import type { QueryAdapter, QueryResult } from "./types.js";
+/**
+ * Extract project ref from a Supabase URL.
+ * Handles: https://abc123.supabase.co, https://abc123.supabase.co/rest/v1/...
+ */
+export declare function extractRefFromUrl(url: string): string | null;
+export interface SupabaseAdapterConfig {
+    accessToken: string;
+    projectRef: string;
+}
+export declare class SupabaseAdapter implements QueryAdapter {
+    private accessToken;
+    private projectRef;
+    readonly isPostgres = true;
+    readonly version: string | null;
+    constructor(config: SupabaseAdapterConfig);
+    query<T = any>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    multiQuery(queries: Array<{
+        sql: string;
+        params?: unknown[];
+    }>): Promise<QueryResult[]>;
+    shutdown(): Promise<void>;
+    private executeApi;
+}
+/**
+ * Inline $1, $2, ... placeholders with SQL-safe literal values.
+ *
+ * Safe because all parameters are Zod-validated strings (schema/table/function
+ * names) or computed integers, and the API is called with read_only: true.
+ */
+export declare function inlineParams(sql: string, params: unknown[]): string;
+/**
+ * Escape a value as a PostgreSQL literal.
+ */
+export declare function escapeLiteral(value: unknown): string;
+/**
+ * Batch N queries into 1 SQL statement using json_build_array.
+ *
+ * Each sub-query's result set becomes one element in a JSON array,
+ * turning N round-trips into 1 API call.
+ */
+export declare function buildBatchQuery(queries: Array<{
+    sql: string;
+    params?: unknown[];
+}>): string;

package/dist/db/supabase-adapter.js

@@ -0,0 +1,148 @@
+/**
+ * Extract project ref from a Supabase URL.
+ * Handles: https://abc123.supabase.co, https://abc123.supabase.co/rest/v1/...
+ */
+export function extractRefFromUrl(url) {
+    try {
+        const hostname = new URL(url).hostname;
+        const match = hostname.match(/^([a-z0-9]+)\.supabase\.co$/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+const API_BASE = "https://api.supabase.com";
+const FETCH_TIMEOUT_MS = 30_000;
+export class SupabaseAdapter {
+    accessToken;
+    projectRef;
+    isPostgres = true; // Supabase is always PostgreSQL
+    version = "PostgreSQL (Supabase Management API)";
+    constructor(config) {
+        this.accessToken = config.accessToken;
+        this.projectRef = config.projectRef;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async query(sql, params) {
+        const finalSql = params?.length ? inlineParams(sql, params) : sql;
+        const rows = await this.executeApi(finalSql);
+        return { rows: rows, rowCount: rows.length };
+    }
+    async multiQuery(queries) {
+        if (queries.length === 0)
+            return [];
+        if (queries.length === 1) {
+            return [await this.query(queries[0].sql, queries[0].params)];
+        }
+        // Batch all queries into a single API call using json_build_array
+        const batchSql = buildBatchQuery(queries);
+        const batchRows = await this.executeApi(batchSql);
+        const resultsArray = batchRows[0]?.results;
+        if (!Array.isArray(resultsArray)) {
+            throw new Error("Unexpected batch query response format from Supabase Management API");
+        }
+        return resultsArray.map((rows) => {
+            const rowArray = Array.isArray(rows) ? rows : [];
+            return {
+                rows: rowArray,
+                rowCount: rowArray.length,
+            };
+        });
+    }
+    async shutdown() {
+        // No persistent connections to close
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async executeApi(sql) {
+        const url = `${API_BASE}/v1/projects/${this.projectRef}/database/query`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.accessToken}`,
+                },
+                // Note: read_only is intentionally omitted. The Management API's
+                // read_only mode uses a restricted role that blocks visibility into
+                // information_schema views needed for schema introspection
+                // (table_constraints, check_constraints, referential_constraints,
+                // constraint_column_usage, role_table_grants, triggers).
+                // All queries in this tool are hardcoded SELECT statements.
+                body: JSON.stringify({ query: sql }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => "");
+                if (response.status === 401) {
+                    throw new Error("Supabase Management API: unauthorized. Check that SUPABASE_ACCESS_TOKEN is a valid Personal Access Token.");
+                }
+                if (response.status === 429) {
+                    throw new Error("Supabase Management API: rate limit exceeded (10 req/min). Wait a moment and retry.");
+                }
+                throw new Error(`Supabase Management API error ${response.status}: ${body.slice(0, 500)}`);
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return (await response.json());
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === "AbortError") {
+                throw new Error(`Supabase Management API: request timed out after ${FETCH_TIMEOUT_MS / 1000}s`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+// ── Parameter inlining (exported for testing) ──
+/**
+ * Inline $1, $2, ... placeholders with SQL-safe literal values.
+ *
+ * Safe because all parameters are Zod-validated strings (schema/table/function
+ * names) or computed integers, and the API is called with read_only: true.
+ */
+export function inlineParams(sql, params) {
+    return sql.replace(/\$(\d+)/g, (match, indexStr) => {
+        const index = parseInt(indexStr, 10) - 1;
+        if (index < 0 || index >= params.length)
+            return match;
+        return escapeLiteral(params[index]);
+    });
+}
+/**
+ * Escape a value as a PostgreSQL literal.
+ */
+export function escapeLiteral(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    if (typeof value === "boolean")
+        return value ? "TRUE" : "FALSE";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`Cannot inline non-finite number: ${value}`);
+        return String(value);
+    }
+    if (typeof value === "string") {
+        return `'${value.replace(/'/g, "''")}'`;
+    }
+    throw new Error(`Cannot inline parameter of type ${typeof value}: ${String(value)}`);
+}
+/**
+ * Batch N queries into 1 SQL statement using json_build_array.
+ *
+ * Each sub-query's result set becomes one element in a JSON array,
+ * turning N round-trips into 1 API call.
+ */
+export function buildBatchQuery(queries) {
+    const subQueries = queries.map((q, i) => {
+        const sql = q.params?.length ? inlineParams(q.sql, q.params) : q.sql;
+        const cleaned = sql.replace(/;\s*$/, "").trim();
+        return `(SELECT COALESCE(json_agg(row_to_json(q${i})), '[]'::json) FROM (${cleaned}) q${i})`;
+    });
+    return `SELECT json_build_array(\n  ${subQueries.join(",\n  ")}\n) AS results;`;
+}
+//# sourceMappingURL=supabase-adapter.js.map

package/dist/db/supabase-adapter.js.map

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

package/dist/db/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Backend-agnostic query result.
+ * Matches the subset of pg.QueryResult that tools actually use (.rows, .rowCount).
+ *
+ * Default generic is `any` to match pg.QueryResult behavior — tools rely on
+ * implicit any when accessing row properties without explicit typing.
+ */
+export interface QueryResult<T = any> {
+    rows: T[];
+    rowCount: number;
+}
+/**
+ * Contract that both pg.Pool and Supabase Management API adapters implement.
+ * Tools never import this directly — they use the facade exports from postgres.ts.
+ */
+export interface QueryAdapter {
+    query<T = any>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    multiQuery(queries: Array<{
+        sql: string;
+        params?: unknown[];
+    }>): Promise<QueryResult[]>;
+    readonly isPostgres: boolean;
+    readonly version: string | null;
+    shutdown(): Promise<void>;
+}

package/dist/db/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/db/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/db/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};