@nifrajs/mcp-db 3.3.0 → 4.0.0

package/dist/internal/sqlite-session.js

@@ -0,0 +1,254 @@
+/**
+ * The execution lanes `run_query` uses: a reusable read-only worker for a file-backed database, and an
+ * in-process lane for one that cannot be reopened. Not part of the public engine - the CLI's database
+ * tool runs each query in its own subprocess instead, which bounds the work by killing the process.
+ */
+export class QueryTimeoutError extends Error {
+    constructor() {
+        super("query exceeded the time limit");
+        this.name = "QueryTimeoutError";
+    }
+}
+/**
+ * The isolated lane. The worker reopens the SAME database FILE read-only and answers one statement
+ * at a time; it is spawned once and reused for the life of the server. It deliberately does not
+ * take a `serialize()` snapshot - that copies the whole database into memory on EVERY call, which
+ * is a larger availability problem than the slow query the deadline exists to bound.
+ */
+const SQLITE_WORKER_SOURCE = `
+const { Database } = require("bun:sqlite")
+let db
+self.onmessage = (event) => {
+  const { id, filename, sql, type } = event.data
+  if (type === "close") {
+    let response
+    try {
+      // prepare().all() leaves a statement alive until it is finalized or collected. Bun's
+      // default close(false) preserves those statements and can keep the database file locked;
+      // close(true) finalizes every outstanding statement before the worker exits.
+      db?.close(true)
+      db = undefined
+      response = { id, closed: true, ok: true }
+    } catch (error) {
+      response = { id, closed: true, ok: false, error: String(error) }
+    }
+    // A forced parent-side terminate can leave native SQLite handles locked on Windows even after
+    // close() returns. Let the worker exit its own event turn so the runtime can finish releasing
+    // those handles before the parent considers graceful cleanup complete.
+    self.postMessage(response)
+    self.close()
+    return
+  }
+  try {
+    if (db === undefined) {
+      db = new Database(filename, { readonly: true })
+      db.run("PRAGMA query_only = ON")
+    }
+    self.postMessage({ id, ok: true, rows: db.prepare(sql).all() })
+  } catch (error) {
+    self.postMessage({ id, ok: false, error: String(error) })
+  }
+}
+`;
+function isWorkerAvailable() {
+    return typeof Worker !== "undefined" && typeof Blob !== "undefined" && typeof URL !== "undefined";
+}
+/** Only a file-backed database can be reopened in a worker. `:memory:` and the anonymous temp
+ * database live in this process alone, so they take the in-process lane instead. */
+function reopenableFilename(db) {
+    const filename = db.filename;
+    if (typeof filename !== "string" || filename === "" || filename === ":memory:")
+        return undefined;
+    return filename.startsWith("file::memory:") ? undefined : filename;
+}
+const WORKER_CLOSE_TIMEOUT_MS = 1_000;
+function workerSession(filename) {
+    let worker;
+    let sourceUrl;
+    let nextId = 0;
+    const pending = new Map();
+    let lane = Promise.resolve();
+    let closed = false;
+    let closePromise;
+    let pendingClose;
+    const detachWorker = (active = worker) => {
+        if (active === undefined)
+            return;
+        if (worker !== active)
+            return;
+        worker = undefined;
+        if (sourceUrl !== undefined)
+            URL.revokeObjectURL(sourceUrl);
+        sourceUrl = undefined;
+    };
+    const releaseWorker = (active = worker) => {
+        if (active === undefined)
+            return;
+        active.terminate();
+        detachWorker(active);
+    };
+    const rejectPending = (error) => {
+        const waiters = [...pending.values()];
+        pending.clear();
+        for (const waiter of waiters)
+            waiter.reject(error);
+    };
+    /** Drop the worker and fail everything riding on it. The only bound this side can enforce over a
+     * statement already running inside native SQLite is to stop owning the connection it runs on. */
+    const discard = (error) => {
+        const closing = pendingClose;
+        pendingClose = undefined;
+        releaseWorker();
+        rejectPending(error);
+        closing?.resolve();
+    };
+    const ensureWorker = () => {
+        if (worker !== undefined)
+            return worker;
+        sourceUrl = URL.createObjectURL(new Blob([SQLITE_WORKER_SOURCE], { type: "text/javascript" }));
+        const spawned = new Worker(sourceUrl);
+        spawned.onmessage = (event) => {
+            const { id, ok, rows, error } = event.data;
+            if (typeof id !== "number")
+                return;
+            if (event.data.closed === true) {
+                const closing = pendingClose;
+                if (closing?.id !== id)
+                    return;
+                pendingClose = undefined;
+                closing.resolve(event.data.ok === true);
+                return;
+            }
+            const waiter = pending.get(id);
+            if (waiter === undefined)
+                return;
+            if (Date.now() >= waiter.deadline) {
+                discard(new QueryTimeoutError());
+                return;
+            }
+            pending.delete(id);
+            if (ok === true)
+                waiter.resolve(rows ?? []);
+            else
+                waiter.reject(new Error(error ?? "query failed in worker"));
+        };
+        spawned.onerror = () => discard(new Error("query failed in worker"));
+        spawned.unref?.();
+        worker = spawned;
+        return spawned;
+    };
+    const dispatch = (sql, deadline) => {
+        if (closed)
+            return Promise.reject(new Error("query session is closed"));
+        const active = ensureWorker();
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            discard(new QueryTimeoutError());
+            return Promise.reject(new QueryTimeoutError());
+        }
+        const id = ++nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => discard(new QueryTimeoutError()), remaining);
+            pending.set(id, {
+                deadline,
+                resolve: (rows) => {
+                    clearTimeout(timer);
+                    resolve(rows);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    reject(error);
+                },
+            });
+            try {
+                active.postMessage({ id, filename, sql });
+            }
+            catch (error) {
+                pending.delete(id);
+                clearTimeout(timer);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    };
+    return {
+        run(sql, deadline) {
+            // One worker owns the connection, so overlapping calls queue behind each other rather than
+            // interleaving statements on it.
+            const result = lane.then(() => dispatch(sql, deadline));
+            lane = result.catch(() => undefined);
+            return result;
+        },
+        close() {
+            if (closePromise !== undefined)
+                return closePromise;
+            closed = true;
+            closePromise = (async () => {
+                const active = worker;
+                if (active !== undefined) {
+                    await new Promise((resolve) => {
+                        const id = ++nextId;
+                        let settled = false;
+                        const finish = (error, graceful = false) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            clearTimeout(timer);
+                            if (pendingClose?.id === id)
+                                pendingClose = undefined;
+                            if (error !== undefined)
+                                rejectPending(error);
+                            if (graceful)
+                                detachWorker(active);
+                            else
+                                releaseWorker(active);
+                            resolve();
+                        };
+                        const timer = setTimeout(() => {
+                            finish(new Error("query session is closed"));
+                        }, WORKER_CLOSE_TIMEOUT_MS);
+                        pendingClose = { id, resolve: (graceful) => finish(undefined, graceful) };
+                        try {
+                            active.postMessage({ id, type: "close" });
+                        }
+                        catch {
+                            finish(new Error("query session is closed"));
+                        }
+                    });
+                }
+                await lane;
+            })();
+            return closePromise;
+        },
+    };
+}
+/**
+ * The in-process lane, used when the database cannot be reopened elsewhere. The deadline is checked
+ * around the statement and nothing more: `prepare().all()` is synchronous, so it holds the only
+ * thread there is and no timer of ours can fire while it runs. That makes this lane BEST EFFORT -
+ * it reports an overrun, it does not cut one short.
+ */
+function inProcessSession(db) {
+    return {
+        async run(sql, deadline) {
+            if (Date.now() >= deadline)
+                throw new QueryTimeoutError();
+            const rows = db.prepare(sql).all();
+            if (Date.now() > deadline)
+                throw new QueryTimeoutError();
+            return rows;
+        },
+        async close() { },
+    };
+}
+/**
+ * Pick the lane once, at construction. A file-backed database is isolated in a reusable read-only
+ * worker, which is the only arrangement that can actually stop a running statement. Anything else
+ * runs in process - every database keeps working, none is refused.
+ */
+export function openQuerySession(db) {
+    const filename = reopenableFilename(db);
+    if (filename !== undefined && isWorkerAvailable())
+        return workerSession(filename);
+    return inProcessSession(db);
+}
+//# sourceMappingURL=sqlite-session.js.map

package/dist/internal/sqlite-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-session.js","sourceRoot":"","sources":["../../src/internal/sqlite-session.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C;QACE,KAAK,CAAC,+BAA+B,CAAC,CAAA;QACtC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF;AAQD;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkC5B,CAAA;AAED,SAAS,iBAAiB;IACxB,OAAO,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,IAAI,KAAK,WAAW,IAAI,OAAO,GAAG,KAAK,WAAW,CAAA;AACnG,CAAC;AAED;oFACoF;AACpF,SAAS,kBAAkB,CAAC,EAAsB;IAChD,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAA;IAC5B,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,EAAE,IAAI,QAAQ,KAAK,UAAU;QAAE,OAAO,SAAS,CAAA;IAChG,OAAO,QAAQ,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAA;AACpE,CAAC;AAaD,MAAM,uBAAuB,GAAG,KAAK,CAAA;AAErC,SAAS,aAAa,CAAC,QAAgB;IACrC,IAAI,MAA0B,CAAA;IAC9B,IAAI,SAA6B,CAAA;IACjC,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,MAAM,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAA;IAC/C,IAAI,IAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAA;IAC9C,IAAI,MAAM,GAAG,KAAK,CAAA;IAClB,IAAI,YAAuC,CAAA;IAC3C,IAAI,YAAsC,CAAA;IAE1C,MAAM,YAAY,GAAG,CAAC,SAA6B,MAAM,EAAQ,EAAE;QACjE,IAAI,MAAM,KAAK,SAAS;YAAE,OAAM;QAChC,IAAI,MAAM,KAAK,MAAM;YAAE,OAAM;QAC7B,MAAM,GAAG,SAAS,CAAA;QAClB,IAAI,SAAS,KAAK,SAAS;YAAE,GAAG,CAAC,eAAe,CAAC,SAAS,CAAC,CAAA;QAC3D,SAAS,GAAG,SAAS,CAAA;IACvB,CAAC,CAAA;IAED,MAAM,aAAa,GAAG,CAAC,SAA6B,MAAM,EAAQ,EAAE;QAClE,IAAI,MAAM,KAAK,SAAS;YAAE,OAAM;QAChC,MAAM,CAAC,SAAS,EAAE,CAAA;QAClB,YAAY,CAAC,MAAM,CAAC,CAAA;IACtB,CAAC,CAAA;IAED,MAAM,aAAa,GAAG,CAAC,KAAY,EAAQ,EAAE;QAC3C,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QACrC,OAAO,CAAC,KAAK,EAAE,CAAA;QACf,KAAK,MAAM,MAAM,IAAI,OAAO;YAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACpD,CAAC,CAAA;IAED;qGACiG;IACjG,MAAM,OAAO,GAAG,CAAC,KAAY,EAAQ,EAAE;QACrC,MAAM,OAAO,GAAG,YAAY,CAAA;QAC5B,YAAY,GAAG,SAAS,CAAA;QACxB,aAAa,EAAE,CAAA;QACf,aAAa,CAAC,KAAK,CAAC,CAAA;QACpB,OAAO,EAAE,OAAO,EAAE,CAAA;IACpB,CAAC,CAAA;IAED,MAAM,YAAY,GAAG,GAAW,EAAE;QAChC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAA;QACvC,SAAS,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,CAAC,oBAAoB,CAAC,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAA;QAC9F,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC,CAAA;QACrC,OAAO,CAAC,SAAS,GAAG,CAClB,KAME,EACF,EAAE;YACF,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,IAAI,CAAA;YAC1C,IAAI,OAAO,EAAE,KAAK,QAAQ;gBAAE,OAAM;YAClC,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC/B,MAAM,OAAO,GAAG,YAAY,CAAA;gBAC5B,IAAI,OAAO,EAAE,EAAE,KAAK,EAAE;oBAAE,OAAM;gBAC9B,YAAY,GAAG,SAAS,CAAA;gBACxB,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,CAAA;gBACvC,OAAM;YACR,CAAC;YACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YAC9B,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAM;YAChC,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBAClC,OAAO,CAAC,IAAI,iBAAiB,EAAE,CAAC,CAAA;gBAChC,OAAM;YACR,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YAClB,IAAI,EAAE,KAAK,IAAI;gBAAE,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAA;;gBACtC,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,IAAI,wBAAwB,CAAC,CAAC,CAAA;QAClE,CAAC,CAAA;QACD,OAAO,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC,CAGnE;QAAC,OAAkC,CAAC,KAAK,EAAE,EAAE,CAAA;QAC9C,MAAM,GAAG,OAAO,CAAA;QAChB,OAAO,OAAO,CAAA;IAChB,CAAC,CAAA;IAED,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAE,QAAgB,EAAsB,EAAE;QACrE,IAAI,MAAM;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAA;QACvE,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;QAC7B,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACvC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,iBAAiB,EAAE,CAAC,CAAA;YAChC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,iBAAiB,EAAE,CAAC,CAAA;QAChD,CAAC;QACD,MAAM,EAAE,GAAG,EAAE,MAAM,CAAA;QACnB,OAAO,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAChD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,iBAAiB,EAAE,CAAC,EAAE,SAAS,CAAC,CAAA;YAC3E,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE;gBACd,QAAQ;gBACR,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;oBAChB,YAAY,CAAC,KAAK,CAAC,CAAA;oBACnB,OAAO,CAAC,IAAI,CAAC,CAAA;gBACf,CAAC;gBACD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;oBAChB,YAAY,CAAC,KAAK,CAAC,CAAA;oBACnB,MAAM,CAAC,KAAK,CAAC,CAAA;gBACf,CAAC;aACF,CAAC,CAAA;YACF,IAAI,CAAC;gBACH,MAAM,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAA;YAC3C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;gBAClB,YAAY,CAAC,KAAK,CAAC,CAAA;gBACnB,MAAM,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YACnE,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,OAAO;QACL,GAAG,CAAC,GAAG,EAAE,QAAQ;YACf,2FAA2F;YAC3F,iCAAiC;YACjC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAA;YACvD,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;YACpC,OAAO,MAAM,CAAA;QACf,CAAC;QACD,KAAK;YACH,IAAI,YAAY,KAAK,SAAS;gBAAE,OAAO,YAAY,CAAA;YACnD,MAAM,GAAG,IAAI,CAAA;YACb,YAAY,GAAG,CAAC,KAAK,IAAI,EAAE;gBACzB,MAAM,MAAM,GAAG,MAAM,CAAA;gBACrB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;wBAClC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAA;wBACnB,IAAI,OAAO,GAAG,KAAK,CAAA;wBACnB,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,QAAQ,GAAG,KAAK,EAAQ,EAAE;4BACvD,IAAI,OAAO;gCAAE,OAAM;4BACnB,OAAO,GAAG,IAAI,CAAA;4BACd,YAAY,CAAC,KAAK,CAAC,CAAA;4BACnB,IAAI,YAAY,EAAE,EAAE,KAAK,EAAE;gCAAE,YAAY,GAAG,SAAS,CAAA;4BACrD,IAAI,KAAK,KAAK,SAAS;gCAAE,aAAa,CAAC,KAAK,CAAC,CAAA;4BAC7C,IAAI,QAAQ;gCAAE,YAAY,CAAC,MAAM,CAAC,CAAA;;gCAC7B,aAAa,CAAC,MAAM,CAAC,CAAA;4BAC1B,OAAO,EAAE,CAAA;wBACX,CAAC,CAAA;wBACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;4BAC5B,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAA;wBAC9C,CAAC,EAAE,uBAAuB,CAAC,CAAA;wBAC3B,YAAY,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAA;wBACzE,IAAI,CAAC;4BACH,MAAM,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;wBAC3C,CAAC;wBAAC,MAAM,CAAC;4BACP,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAA;wBAC9C,CAAC;oBACH,CAAC,CAAC,CAAA;gBACJ,CAAC;gBACD,MAAM,IAAI,CAAA;YACZ,CAAC,CAAC,EAAE,CAAA;YACJ,OAAO,YAAY,CAAA;QACrB,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,EAAsB;IAC9C,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ;YACrB,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;gBAAE,MAAM,IAAI,iBAAiB,EAAE,CAAA;YACzD,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAA;YAClC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ;gBAAE,MAAM,IAAI,iBAAiB,EAAE,CAAA;YACxD,OAAO,IAAI,CAAA;QACb,CAAC;QACD,KAAK,CAAC,KAAK,KAAI,CAAC;KACjB,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAsB;IACrD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAA;IACvC,IAAI,QAAQ,KAAK,SAAS,IAAI,iBAAiB,EAAE;QAAE,OAAO,aAAa,CAAC,QAAQ,CAAC,CAAA;IACjF,OAAO,gBAAgB,CAAC,EAAE,CAAC,CAAA;AAC7B,CAAC"}

package/dist/postgres.d.ts

@@ -0,0 +1,148 @@
+/**
+ * `@nifrajs/mcp-db/postgres` - a read-only Postgres engine for a development database, on Bun's
+ * built-in `Bun.SQL` (no npm driver). Every layer below is enforced on each call, in this order:
+ *
+ *  1. Host gate ({@link connectPostgres}): loopback, `*.localhost` or a unix socket, else only a host
+ *     named in `allowHosts`. Connection fields are passed explicitly, so `DATABASE_URL`/`PG*` in the
+ *     environment can never redirect the connection.
+ *  2. Role gate: a superuser, a member of a superuser role or of `pg_execute_server_program` /
+ *     `pg_read_server_files` / `pg_write_server_files`, or a role that may execute the server-file
+ *     functions is refused - a read-only transaction does not stop `COPY ... TO PROGRAM` or
+ *     `pg_read_file`. {@link postgresRoleSql} prints the role to use instead.
+ *  3. Extension gate: `dblink`, `postgres_fdw`, `file_fdw` or an untrusted language the role can use
+ *     is refused unless `allowExtensions` names it - `dblink_exec` writes to another database from a
+ *     read-only transaction.
+ *  4. Transaction: every connection starts with `default_transaction_read_only=on`; each call runs in
+ *     `BEGIN READ ONLY` with `statement_timeout`, `lock_timeout` and
+ *     `idle_in_transaction_session_timeout` set locally, and always rolls back.
+ *  5. Statement gate: the query goes over the extended protocol (the server refuses a second
+ *     statement) as `DECLARE ... NO SCROLL CURSOR` (the server accepts only a query there), and at most
+ *     `maxRows + 1` rows are fetched. A tokenizer in front refuses side-effect functions.
+ *  6. Table scope: the plan's relations (and every table they inherit from) must sit in the allowed
+ *     schemas and outside `exclude`. A function can still read a table internally; hard isolation
+ *     comes from the role's grants, which {@link postgresRoleSql} writes with a REVOKE per exclusion.
+ *
+ *   const target = parsePostgresUrl("postgres://nifra_dev_reader@localhost:5432/app")
+ *   const client = connectPostgres(target, { timeoutMs: 5000 })
+ *   const rows = await queryPostgres(client, "SELECT status, count(*) FROM orders GROUP BY 1", {
+ *     timeoutMs: 5000, maxRows: 100, maxResultBytes: 100 * 1024,
+ *   })
+ */
+import { type PostgresClient } from "./internal/pg-exec.js";
+import { type DbPlan, type DbRedaction, type DbRefusal, type DbRows, type DbSchemaReport, type ShapeRowsOptions } from "./internal/shared.js";
+export type { PgConnection, PgQuery, PostgresClient } from "./internal/pg-exec.js";
+/** Where to connect, parsed from a `postgres://` URL. */
+export interface PostgresTarget {
+    /** TCP host; absent for a unix socket. */
+    readonly host?: string;
+    /** Unix socket file path. */
+    readonly socket?: string;
+    readonly port: number;
+    readonly username: string;
+    readonly password?: string;
+    readonly database: string;
+    readonly tls?: "disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full";
+}
+/**
+ * Parse a `postgres://` (or `postgresql://`) URL. Only the host, port, user, password, database and
+ * `sslmode` are read - any other parameter (`options=-c ...` included) is ignored, so a URL cannot
+ * switch off the read-only session settings.
+ */
+export declare function parsePostgresUrl(url: string): PostgresTarget | DbRefusal;
+/** True for `localhost`, `*.localhost`, 127.0.0.0/8 and `::1` (also as an IPv4-mapped address). */
+export declare function isLocalPostgresHost(host: string): boolean;
+/** Refuse a TCP host that is neither local nor named in `allowHosts`. */
+export declare function postgresHostRefusal(target: PostgresTarget, allowHosts?: readonly string[]): DbRefusal | undefined;
+/** Options for {@link connectPostgres}. */
+export interface ConnectPostgresOptions {
+    readonly timeoutMs: number;
+    readonly allowHosts?: readonly string[];
+}
+/**
+ * Open a one-connection `Bun.SQL` client for `target` after the host gate. Every session starts
+ * read-only with `standard_conforming_strings` on (the statement tokenizer reads strings that way).
+ */
+export declare function connectPostgres(target: PostgresTarget, options: ConnectPostgresOptions): PostgresClient | DbRefusal;
+/** What the role gate and extension gate read about the connected role. */
+export interface PostgresRoleReport {
+    readonly role: string;
+    readonly superuser: boolean;
+    readonly serverVersionNum: number;
+    /** Superuser roles the role is a member of. */
+    readonly superuserRoles: readonly string[];
+    /** Server-file and server-program roles the role is a member of. */
+    readonly serverRoles: readonly string[];
+    /** Server-file functions the role may execute. */
+    readonly fileFunctions: readonly string[];
+    /** `dblink`, `postgres_fdw`, `file_fdw`: installed and usable by the role. */
+    readonly extensions: readonly string[];
+    /** Untrusted procedural languages the role can use or call functions in. */
+    readonly languages: readonly string[];
+}
+/** Read the connected role's privileges, in a read-only transaction. */
+export declare function inspectPostgresRole(client: PostgresClient, options: {
+    readonly timeoutMs: number;
+}): Promise<PostgresRoleReport | DbRefusal>;
+/** The role gate and the extension gate, as one decision over a {@link PostgresRoleReport}. */
+export declare function postgresRoleRefusal(report: PostgresRoleReport, options?: {
+    readonly allowExtensions?: readonly string[];
+}): DbRefusal | undefined;
+/** Refuse what the tokenizer layer refuses: a non-query, several statements, a denied function. */
+export declare function lintPostgresStatement(sql: string): DbRefusal | undefined;
+/** Which relations a query may read. */
+export interface PostgresScope {
+    /** Schemas a query may read (default `["public"]`). */
+    readonly schemas?: readonly string[];
+    /** Tables a query may not read: `name` in any allowed schema, or `schema.name`. */
+    readonly exclude?: readonly string[];
+}
+/** Options for {@link queryPostgres}. */
+export interface PostgresQueryOptions extends ShapeRowsOptions, PostgresScope {
+    readonly timeoutMs: number;
+    /** Extensions or untrusted languages to accept although the role can use them. */
+    readonly allowExtensions?: readonly string[];
+}
+/**
+ * Run one read-only query through every layer and return capped rows. A column `redaction.column`
+ * masks is refused wherever the plan uses it (selected under any alias, inside an expression, in a
+ * filter, or within a whole row); a matching result name is masked as well.
+ */
+export declare function queryPostgres(client: PostgresClient, sql: string, options: PostgresQueryOptions): Promise<DbRows | DbRefusal>;
+/** `EXPLAIN (FORMAT JSON)` for one query, after the same layers as {@link queryPostgres}. */
+export declare function explainPostgres(client: PostgresClient, sql: string, options: PostgresQueryOptions & {
+    readonly analyze?: boolean;
+}): Promise<DbPlan | DbRefusal>;
+/** Options for {@link readPostgresSchema}. */
+export interface PostgresSchemaOptions extends PostgresScope {
+    readonly timeoutMs: number;
+    /** Describe only this table (`name` or `schema.name`). */
+    readonly table?: string | undefined;
+    readonly redaction?: DbRedaction;
+}
+/**
+ * Describe the readable tables and views in the allowed schemas from `pg_catalog`, with queries this
+ * module writes (no caller SQL runs), so it works on any role: columns, primary keys, foreign keys,
+ * indexes and the planner's row estimate.
+ */
+export declare function readPostgresSchema(client: PostgresClient, options: PostgresSchemaOptions): Promise<DbSchemaReport | DbRefusal>;
+/** Options for {@link postgresRoleSql}. */
+export interface PostgresRoleSqlOptions extends PostgresScope {
+    readonly timeoutMs: number;
+    /** The role to create (default `nifra_dev_reader`). */
+    readonly role?: string;
+}
+/** The SQL that creates a read-only role for this database, for the developer to run themselves. */
+export interface PostgresRoleSql {
+    readonly role: string;
+    readonly database: string;
+    readonly serverVersionNum: number;
+    readonly statements: readonly string[];
+}
+/**
+ * Write the SQL for a login role that can read the allowed schemas and nothing else: `pg_read_all_data`
+ * on Postgres 14+ when nothing is excluded; otherwise `GRANT SELECT` per schema plus default
+ * privileges, and a `REVOKE` for each excluded table and its partitions (`pg_read_all_data` would
+ * override a REVOKE, so it is not used then). Nothing is executed.
+ */
+export declare function postgresRoleSql(client: PostgresClient, options: PostgresRoleSqlOptions): Promise<PostgresRoleSql | DbRefusal>;
+//# sourceMappingURL=postgres.d.ts.map

package/dist/postgres.d.ts.map

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