@shibbirweb/mcp-db-read-only 0.1.0

package/dist/drivers/sql/MySqlDriver.js

@@ -0,0 +1,144 @@
+import { ObjectNotFoundError } from "../../errors/ObjectNotFoundError.js";
+import { BaseDriver } from "../BaseDriver.js";
+import { GlobPattern } from "../GlobPattern.js";
+import { LazyResource } from "../LazyResource.js";
+import { MySqlSessionInitializer } from "./MySqlSessionInitializer.js";
+import { SqlIdentifier } from "./SqlIdentifier.js";
+/**
+ * MySQL and MariaDB, through mysql2.
+ *
+ * Read-only layer two: every pooled connection is opened with
+ * `SET SESSION TRANSACTION READ ONLY` (see MySqlSessionInitializer), and
+ * multipleStatements is off, so the protocol cannot carry a second statement.
+ */
+export class MySqlDriver extends BaseDriver {
+    tuning;
+    logger;
+    family = "sql";
+    dialect = "mysql";
+    /**
+     * Hidden by default: noise in almost every session. `include_system` on
+     * list_databases exists because inspecting them is occasionally the task.
+     */
+    static SYSTEM_SCHEMAS = new Set([
+        "information_schema",
+        "performance_schema",
+        "mysql",
+        "sys",
+    ]);
+    static FOREIGN_KEYS = `SELECT COLUMN_NAME, REFERENCED_TABLE_SCHEMA, REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME, CONSTRAINT_NAME
+    FROM information_schema.KEY_COLUMN_USAGE
+    WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ? AND REFERENCED_TABLE_NAME IS NOT NULL`;
+    static NO_SUCH_TABLE = 1146;
+    pool;
+    constructor(target, tuning, logger) {
+        super(target);
+        this.tuning = tuning;
+        this.logger = logger;
+        this.pool = new LazyResource(() => this.createPool(), (pool) => pool.end());
+    }
+    async verify() {
+        await this.run("SELECT 1");
+    }
+    close() {
+        return this.pool.close();
+    }
+    async listDatabases() {
+        const rows = (await this.run("SHOW DATABASES"));
+        return rows.map((row) => {
+            const name = Object.values(row)[0];
+            return { name, system: MySqlDriver.SYSTEM_SCHEMAS.has(name) };
+        });
+    }
+    async listObjects(pattern, limit) {
+        this.requireDatabase();
+        const rows = (await this.run("SHOW TABLES"));
+        // SHOW TABLES returns single-key objects whose key name varies with the
+        // database (Tables_in_<name>). A plain list is far easier to read.
+        return new GlobPattern(pattern).apply(rows.map((row) => Object.values(row)[0]), limit);
+    }
+    async describeObject(name) {
+        return this.onTable(name, () => this.run(`SHOW COLUMNS FROM ${this.quote(name)}`));
+    }
+    async listIndexes(name) {
+        return this.onTable(name, () => this.run(`SHOW INDEX FROM ${this.quote(name)}`));
+    }
+    /** The foreign-key query answers a missing table with no rows, which reads as "no keys", so existence is checked first. */
+    async listForeignKeys(name) {
+        const qualified = SqlIdentifier.parse(name);
+        await this.onTable(name, () => this.run(`SELECT 1 FROM ${this.quote(name)} LIMIT 0`));
+        return this.run(MySqlDriver.FOREIGN_KEYS, [qualified.schema, qualified.name]);
+    }
+    async sample(name, limit) {
+        return this.onTable(name, () => this.run(`SELECT * FROM ${this.quote(name)} LIMIT ${limit}`));
+    }
+    query(sql) {
+        return this.run(sql);
+    }
+    /** Placeholders for values wherever the statement allows; identifiers are quoted. */
+    async run(sql, params) {
+        const pool = await this.pool.get();
+        const [rows] = await pool.query(sql, params);
+        return rows;
+    }
+    /**
+     * Runs work against one table, turning MySQL's "table doesn't exist" (error
+     * 1146) into the same ObjectNotFoundError every other engine raises, so a
+     * missing table reads the same whichever engine is behind the connection.
+     */
+    async onTable(name, work) {
+        try {
+            return await work();
+        }
+        catch (error) {
+            if (error.errno === MySqlDriver.NO_SUCH_TABLE) {
+                throw new ObjectNotFoundError(this.objectNoun, name);
+            }
+            throw error;
+        }
+    }
+    quote(name) {
+        return SqlIdentifier.quoteQualified(SqlIdentifier.parse(name), SqlIdentifier.backtick);
+    }
+    /**
+     * Imported on first use rather than at startup. Eight drivers loaded eagerly
+     * would put every one of them on the startup path of a server that will,
+     * in most sessions, only ever talk to one engine.
+     */
+    async createPool() {
+        const { default: mysql } = await import("mysql2/promise");
+        const pool = mysql.createPool({
+            host: this.target.host,
+            port: this.target.port,
+            user: this.target.user,
+            password: this.target.password,
+            database: this.target.database || undefined,
+            connectionLimit: this.tuning.connectionLimit,
+            waitForConnections: true,
+            // The single most important option here. With multiple statements
+            // enabled, the read-only guarantee would rest entirely on the validator
+            // finding every separator. Disabled, the protocol cannot carry a second
+            // statement at all, so a validator bug is not a dropped table.
+            multipleStatements: false,
+            connectTimeout: this.tuning.connectTimeoutMs,
+            // Without this, mysql2 returns Date objects that JSON.stringify converts
+            // to UTC ISO strings, silently shifting every timestamp by the server's
+            // offset. Strings come back exactly as the server stored them.
+            dateStrings: true,
+            ssl: this.sslOptions(),
+        });
+        new MySqlSessionInitializer(this.tuning.queryTimeoutMs, this.logger).attachTo(pool);
+        return pool;
+    }
+    /** `?ssl=true` requires TLS; `?ssl-mode=REQUIRED` is accepted as the MySQL spelling. */
+    sslOptions() {
+        const mode = (this.target.option("ssl-mode") ?? this.target.option("sslmode") ?? "").toUpperCase();
+        if (this.target.flag("ssl") || ["REQUIRED", "REQUIRE"].includes(mode)) {
+            return { rejectUnauthorized: false };
+        }
+        if (["VERIFY_CA", "VERIFY_IDENTITY", "VERIFY-CA", "VERIFY-FULL"].includes(mode)) {
+            return { rejectUnauthorized: true };
+        }
+        return undefined;
+    }
+}

package/dist/drivers/sql/MySqlSessionInitializer.js

@@ -0,0 +1,100 @@
+/**
+ * Applies the server-side half of the read-only guarantee to every connection
+ * a MySQL or MariaDB pool opens.
+ *
+ * Separated from the driver because it is the security-critical part and
+ * deserves to be findable on its own. The driver decides *when* connections
+ * exist; this decides *what they are allowed to do*.
+ *
+ * This is the layer that holds if the SQL validator is ever wrong. The two are
+ * independent by design: a parser bug should not automatically be a write.
+ */
+export class MySqlSessionInitializer {
+    queryTimeoutMs;
+    logger;
+    /**
+     * Removes the two sql_mode flags that change how quotes are read, so the
+     * server lexes a statement exactly as the validator did.
+     *
+     * With NO_BACKSLASH_ESCAPES, `'a\'` is a complete string to the server but
+     * an unfinished one to the validator. With ANSI_QUOTES, `"..."` is an
+     * identifier, which takes no backslash escapes. Either mismatch lets text
+     * the validator took for a literal run as SQL. ANSI and the old combination
+     * modes are removed too, because each re-enables ANSI_QUOTES.
+     *
+     * One statement, built from string functions, because the pool may hand the
+     * connection out as soon as this event returns; a read followed by a
+     * separate write would race the first query.
+     */
+    static ALIGN_SQL_MODE = `SET SESSION sql_mode = TRIM(BOTH ',' FROM ${[
+        "NO_BACKSLASH_ESCAPES",
+        "ANSI_QUOTES",
+        "ANSI",
+        "DB2",
+        "MAXDB",
+        "MSSQL",
+        "ORACLE",
+        "POSTGRESQL",
+    ].reduce((expression, mode) => `REPLACE(${expression}, ',${mode},', ',')`, "CONCAT(',', @@SESSION.sql_mode, ',')")})`;
+    /** MariaDB's name for the variable; MySQL rejects it with error 1193. */
+    static UNKNOWN_VARIABLE = 1193;
+    constructor(queryTimeoutMs, logger) {
+        this.queryTimeoutMs = queryTimeoutMs;
+        this.logger = logger;
+    }
+    /**
+     * Hooks the pool's `connection` event, which fires once per physical
+     * connection. Once per connection rather than once per query, and it also
+     * covers connections opened later as the pool grows.
+     */
+    attachTo(pool) {
+        pool.on("connection", (connection) => {
+            const coreConnection = connection;
+            // SET SESSION TRANSACTION READ ONLY sets the access mode for subsequent
+            // transactions. With autocommit on, every statement is its own
+            // transaction, so MySQL rejects any write with error 1792. It cannot be
+            // undone from a query: SET is not an allowed leading keyword, and
+            // statement stacking is impossible with multipleStatements disabled.
+            this.apply(coreConnection, "SET SESSION TRANSACTION READ ONLY", "set read-only session");
+            this.apply(coreConnection, MySqlSessionInitializer.ALIGN_SQL_MODE, "align sql_mode");
+            this.applyTimeout(coreConnection);
+        });
+    }
+    /**
+     * Caps SELECT execution server-side so a runaway query is killed by the
+     * server instead of hanging the conversation. MySQL calls it
+     * MAX_EXECUTION_TIME in milliseconds, MariaDB max_statement_time in seconds.
+     *
+     * On MariaDB the fallback is queued only after MySQL's name is refused, so
+     * the very first query on a new connection can run before it applies. That
+     * gap affects only the timeout, never the read-only mode set above.
+     */
+    applyTimeout(connection) {
+        connection.query(`SET SESSION MAX_EXECUTION_TIME = ${this.queryTimeoutMs}`, (error) => {
+            if (!error) {
+                return;
+            }
+            if (error.errno === MySqlSessionInitializer.UNKNOWN_VARIABLE) {
+                this.apply(connection, `SET SESSION max_statement_time = ${this.queryTimeoutMs / 1000}`, "set statement timeout");
+                return;
+            }
+            this.logger(`could not set statement timeout: ${String(error)}`);
+        });
+    }
+    /**
+     * Failures are logged, never thrown.
+     *
+     * A pool `connection` event handler has nowhere to propagate a rejection to,
+     * so an unhandled one would take the process down. A connection that could
+     * not be set read-only is still guarded by the validator, so continuing is
+     * correct; crashing on a server variant lacking one of these variables is
+     * not.
+     */
+    apply(connection, sql, description) {
+        connection.query(sql, (error) => {
+            if (error) {
+                this.logger(`could not ${description}: ${String(error)}`);
+            }
+        });
+    }
+}

package/dist/drivers/sql/PostgresDriver.js

@@ -0,0 +1,176 @@
+import { ObjectNotFoundError } from "../../errors/ObjectNotFoundError.js";
+import { BaseDriver } from "../BaseDriver.js";
+import { GlobPattern } from "../GlobPattern.js";
+import { LazyResource } from "../LazyResource.js";
+import { SqlIdentifier } from "./SqlIdentifier.js";
+/**
+ * PostgreSQL, and anything wire-compatible with it, through node-postgres.
+ *
+ * Read-only layer two: **every statement runs inside a transaction opened
+ * READ ONLY, and that transaction is always rolled back.** PostgreSQL refuses
+ * any write inside it, and whatever a statement manages to change without
+ * writing (a `set_config` smuggled through a function, say) is undone by the
+ * rollback before the connection returns to the pool.
+ *
+ * This is done per transaction rather than with connection startup options
+ * such as `-c default_transaction_read_only=on`, because PgBouncer and most
+ * managed poolers reject startup options, and a read-only guarantee that only
+ * works without a pooler is not one.
+ *
+ * The statement itself goes over the extended query protocol, which carries
+ * exactly one statement, so a second one cannot be stacked behind it whatever
+ * the validator concluded.
+ */
+export class PostgresDriver extends BaseDriver {
+    tuning;
+    family = "sql";
+    dialect = "postgres";
+    /**
+     * Date and time types come back as the text PostgreSQL sent. Parsed into
+     * Date objects they would be re-serialised as UTC ISO strings, silently
+     * shifting every value without a time zone by the host's offset.
+     */
+    static RAW_TEXT_TYPES = new Set([1082, 1083, 1114, 1184, 1266]);
+    pool;
+    constructor(target, tuning) {
+        super(target);
+        this.tuning = tuning;
+        this.pool = new LazyResource(() => this.createPool(), (pool) => pool.end());
+    }
+    async verify() {
+        await this.run("SELECT 1");
+    }
+    close() {
+        return this.pool.close();
+    }
+    /** Templates are system databases; connections are refused to some, so those are left out. */
+    async listDatabases() {
+        const rows = (await this.run("SELECT datname AS name, datistemplate AS system FROM pg_database WHERE datallowconn ORDER BY datname"));
+        return rows.map((row) => ({ name: row.name, system: row.system }));
+    }
+    /**
+     * Tables in `public` are listed bare and everything else schema-qualified,
+     * which is how they are then written in a query.
+     */
+    async listObjects(pattern, limit) {
+        const rows = (await this.run(`SELECT table_schema, table_name FROM information_schema.tables
+       WHERE table_schema NOT IN ('pg_catalog', 'information_schema') AND table_schema NOT LIKE 'pg_toast%'
+       ORDER BY table_schema, table_name`));
+        const names = rows.map((row) => row.table_schema === "public" ? row.table_name : `${row.table_schema}.${row.table_name}`);
+        return new GlobPattern(pattern).apply(names, limit);
+    }
+    async describeObject(name) {
+        const qualified = SqlIdentifier.parse(name);
+        const rows = await this.run(`SELECT column_name, data_type, is_nullable, column_default, character_maximum_length
+       FROM information_schema.columns
+       WHERE table_schema = COALESCE($1::text, current_schema()) AND table_name = $2
+       ORDER BY ordinal_position`, [qualified.schema, qualified.name]);
+        if (rows.length === 0) {
+            throw new ObjectNotFoundError(this.objectNoun, name);
+        }
+        return rows;
+    }
+    async listIndexes(name) {
+        const qualified = SqlIdentifier.parse(name);
+        await this.assertExists(name);
+        return this.run(`SELECT indexname, indexdef FROM pg_indexes
+       WHERE schemaname = COALESCE($1::text, current_schema()) AND tablename = $2
+       ORDER BY indexname`, [qualified.schema, qualified.name]);
+    }
+    async listForeignKeys(name) {
+        const qualified = SqlIdentifier.parse(name);
+        await this.assertExists(name);
+        return this.run(`SELECT c.conname AS constraint_name, pg_get_constraintdef(c.oid) AS definition
+       FROM pg_constraint c
+       JOIN pg_class t ON t.oid = c.conrelid
+       JOIN pg_namespace n ON n.oid = t.relnamespace
+       WHERE c.contype = 'f' AND n.nspname = COALESCE($1::text, current_schema()) AND t.relname = $2
+       ORDER BY c.conname`, [qualified.schema, qualified.name]);
+    }
+    async sample(name, limit) {
+        const table = SqlIdentifier.quoteQualified(SqlIdentifier.parse(name), SqlIdentifier.doubleQuote);
+        return this.run(`SELECT * FROM ${table} LIMIT $1`, [limit]);
+    }
+    query(sql) {
+        return this.run(sql);
+    }
+    /**
+     * One statement inside a read-only transaction that is always rolled back.
+     *
+     * The opening batch is a single round trip. standard_conforming_strings is
+     * pinned on because the SQL validator lexes plain strings without backslash
+     * escapes, and that is only how PostgreSQL reads them while it is on.
+     */
+    async run(text, values) {
+        const pool = await this.pool.get();
+        const client = await pool.connect();
+        let broken;
+        try {
+            await client.query(`BEGIN TRANSACTION READ ONLY; SET LOCAL statement_timeout = ${this.tuning.queryTimeoutMs}; SET LOCAL standard_conforming_strings = on`);
+            const config = { text, values, queryMode: "extended" };
+            const result = await client.query(config);
+            return result.rows;
+        }
+        finally {
+            broken = await this.rollback(client);
+            // A connection whose rollback failed is in an unknown state, so it is
+            // destroyed rather than handed to the next query.
+            client.release(broken);
+        }
+    }
+    async rollback(client) {
+        try {
+            await client.query("ROLLBACK");
+            return undefined;
+        }
+        catch (error) {
+            return error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    async assertExists(name) {
+        const qualified = SqlIdentifier.parse(name);
+        const rows = await this.run(`SELECT 1 FROM information_schema.tables
+       WHERE table_schema = COALESCE($1::text, current_schema()) AND table_name = $2`, [qualified.schema, qualified.name]);
+        if (rows.length === 0) {
+            throw new ObjectNotFoundError(this.objectNoun, name);
+        }
+    }
+    /** Imported on first use; see MySqlDriver.createPool. */
+    async createPool() {
+        const { default: pg } = await import("pg");
+        const pool = new pg.Pool({
+            host: this.target.host,
+            port: this.target.port,
+            user: this.target.user || undefined,
+            password: this.target.password || undefined,
+            database: this.target.database || undefined,
+            max: this.tuning.connectionLimit,
+            connectionTimeoutMillis: this.tuning.connectTimeoutMs,
+            application_name: "mcp-db-read-only",
+            ssl: this.sslOptions(),
+            types: {
+                getTypeParser: ((oid, format) => PostgresDriver.RAW_TEXT_TYPES.has(oid)
+                    ? (value) => value
+                    : pg.types.getTypeParser(oid, format)),
+            },
+        });
+        // An idle client that loses its connection emits on the pool; without a
+        // listener that is an unhandled error and the whole process exits.
+        pool.on("error", () => undefined);
+        return pool;
+    }
+    /**
+     * libpq's sslmode names. `require` encrypts without checking the
+     * certificate, as libpq does; the verify modes check it.
+     */
+    sslOptions() {
+        const mode = (this.target.option("sslmode") ?? "").toLowerCase();
+        if (mode === "verify-ca" || mode === "verify-full") {
+            return { rejectUnauthorized: true };
+        }
+        if (mode === "require" || this.target.flag("ssl")) {
+            return { rejectUnauthorized: false };
+        }
+        return false;
+    }
+}

package/dist/drivers/sql/SqlIdentifier.js

@@ -0,0 +1,36 @@
+/**
+ * Splits and quotes identifiers for interpolation into SQL.
+ *
+ * Names reach here already checked by SqlNamePolicy, whose allowlist cannot
+ * contain a quote character. The quoting below still escapes one properly, by
+ * doubling it, so safety does not rest on the allowlist alone: either
+ * protection is enough on its own.
+ */
+export class SqlIdentifier {
+    /** `schema.table` becomes both parts; `table` has no schema. */
+    static parse(value) {
+        const dot = value.indexOf(".");
+        if (dot === -1) {
+            return { schema: null, name: value };
+        }
+        return { schema: value.slice(0, dot), name: value.slice(dot + 1) };
+    }
+    /** `name` with backticks, for MySQL, SQLite and ClickHouse. */
+    static backtick(part) {
+        return `\`${part.replace(/`/g, "``")}\``;
+    }
+    /** `"name"`, standard SQL, for PostgreSQL and SQLite. */
+    static doubleQuote(part) {
+        return `"${part.replace(/"/g, '""')}"`;
+    }
+    /** `[name]`, for SQL Server. */
+    static bracket(part) {
+        return `[${part.replace(/]/g, "]]")}]`;
+    }
+    /** Quote each part of a possibly qualified name with the given style. */
+    static quoteQualified(qualified, quote) {
+        return qualified.schema
+            ? `${quote(qualified.schema)}.${quote(qualified.name)}`
+            : quote(qualified.name);
+    }
+}

package/dist/drivers/sql/SqliteDriver.js

@@ -0,0 +1,202 @@
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { ObjectNotFoundError } from "../../errors/ObjectNotFoundError.js";
+import { BaseDriver } from "../BaseDriver.js";
+import { GlobPattern } from "../GlobPattern.js";
+import { LazyResource } from "../LazyResource.js";
+import { SqlIdentifier } from "./SqlIdentifier.js";
+/**
+ * The server's side of one SQLite worker process: sends a statement, awaits
+ * the rows, and kills the process when a statement overruns.
+ */
+class SqliteWorkerHandle {
+    child;
+    static ENTRY = fileURLToPath(new URL("./SqliteWorker.js", import.meta.url));
+    nextId = 1;
+    pending = new Map();
+    deadReason = null;
+    constructor(child) {
+        this.child = child;
+        child.on("message", (response) => this.settle(response));
+        child.on("error", (error) => this.fail(error.message));
+        child.on("exit", () => this.fail("the SQLite worker exited"));
+    }
+    /**
+     * Resolves once the database is open, so a missing file or a permissions
+     * problem is reported by connect rather than by the first query.
+     */
+    static start(options, timeoutMs) {
+        const child = fork(SqliteWorkerHandle.ENTRY, [JSON.stringify(options)], {
+            // stdout is ignored, never inherited: this process's stdout is the
+            // JSON-RPC stream, and one stray byte from the child would corrupt it.
+            stdio: ["ignore", "ignore", "inherit", "ipc"],
+            // Structured clone rather than JSON, so blobs arrive as bytes rather
+            // than as an array of numbers.
+            serialization: "advanced",
+            // node:sqlite prints an ExperimentalWarning on first use. It is noise in
+            // a client's log, and it says nothing an operator can act on.
+            execArgv: ["--disable-warning=ExperimentalWarning"],
+        });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                reject(new Error(`Opening the SQLite database took longer than ${timeoutMs} ms.`));
+            }, timeoutMs);
+            child.once("message", (startup) => {
+                clearTimeout(timer);
+                if (startup.type === "ready") {
+                    resolve(new SqliteWorkerHandle(child));
+                    return;
+                }
+                child.kill("SIGKILL");
+                reject(new Error(`Could not open SQLite database: ${startup.error}`));
+            });
+            child.once("error", (error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    }
+    get dead() {
+        return this.deadReason !== null;
+    }
+    run(sql, params, timeoutMs) {
+        if (this.deadReason) {
+            return Promise.reject(new Error(this.deadReason));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                // The only way to stop a synchronous SQLite statement. The driver
+                // opens a fresh process for the next call.
+                this.fail(`Query exceeded ${timeoutMs} ms and was stopped.`);
+                this.child.kill("SIGKILL");
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (rows) => {
+                    clearTimeout(timer);
+                    resolve(rows);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    reject(error);
+                },
+            });
+            this.child.send({ id, sql, params });
+        });
+    }
+    /**
+     * Not awaited beyond the signal: SIGKILL cannot be refused, and waiting on
+     * the exit event is what hung the worker-thread version of this class.
+     */
+    async terminate() {
+        this.fail("the SQLite connection was closed");
+        this.child.kill("SIGKILL");
+    }
+    settle(response) {
+        const waiter = this.pending.get(response.id);
+        if (!waiter) {
+            return;
+        }
+        this.pending.delete(response.id);
+        if ("error" in response) {
+            waiter.reject(new Error(response.error));
+            return;
+        }
+        waiter.resolve(response.rows);
+    }
+    /** Every call in flight fails with the same reason, and so does every later one. */
+    fail(reason) {
+        if (!this.deadReason) {
+            this.deadReason = reason;
+        }
+        for (const waiter of this.pending.values()) {
+            waiter.reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+}
+/**
+ * SQLite, through the node:sqlite module built into Node 22.13 and later.
+ *
+ * Read-only layer two: the file is opened with SQLite's `readOnly` flag, so
+ * the library refuses to write to it at all, whatever the statement says.
+ * Extension loading is disabled.
+ *
+ * The database lives in a child process (see SqliteWorker), started on first
+ * use and replaced after a query is killed for overrunning.
+ *
+ * No dependency is needed, which is also why SQLite needs no native module
+ * build and works in the Alpine image on every architecture.
+ */
+export class SqliteDriver extends BaseDriver {
+    tuning;
+    family = "sql";
+    dialect = "sqlite";
+    worker;
+    constructor(target, tuning) {
+        super(target);
+        this.tuning = tuning;
+        this.worker = new LazyResource(() => SqliteWorkerHandle.start({ path: target.database, busyTimeoutMs: tuning.connectTimeoutMs }, tuning.connectTimeoutMs), (handle) => handle.terminate());
+    }
+    async verify() {
+        await this.run("SELECT 1");
+    }
+    close() {
+        return this.worker.close();
+    }
+    async listDatabases() {
+        const rows = (await this.run("SELECT name FROM pragma_database_list"));
+        return rows.map((row) => ({ name: row.name, system: row.name === "temp" }));
+    }
+    async listObjects(pattern, limit) {
+        const rows = (await this.run("SELECT name FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%' ORDER BY name"));
+        return new GlobPattern(pattern).apply(rows.map((row) => row.name), limit);
+    }
+    async describeObject(name) {
+        const rows = await this.pragma("table_info", name);
+        if (rows.length === 0) {
+            throw new ObjectNotFoundError(this.objectNoun, name);
+        }
+        return rows;
+    }
+    async listIndexes(name) {
+        await this.describeObject(name);
+        const qualified = SqlIdentifier.parse(name);
+        return this.run(`SELECT il.name AS index_name, il."unique" AS is_unique, il.origin, ii.seqno, ii.name AS column_name
+       FROM pragma_index_list(?, ?) il JOIN pragma_index_info(il.name, ?) ii
+       ORDER BY il.name, ii.seqno`, [qualified.name, qualified.schema ?? "main", qualified.schema ?? "main"]);
+    }
+    async listForeignKeys(name) {
+        await this.describeObject(name);
+        return this.pragma("foreign_key_list", name);
+    }
+    async sample(name, limit) {
+        const table = SqlIdentifier.quoteQualified(SqlIdentifier.parse(name), SqlIdentifier.doubleQuote);
+        return this.run(`SELECT * FROM ${table} LIMIT ?`, [limit]);
+    }
+    query(sql) {
+        return this.run(sql);
+    }
+    /** Table-valued pragma functions, so the table name is a bound value, not SQL. */
+    pragma(pragmaName, name) {
+        const qualified = SqlIdentifier.parse(name);
+        return this.run(`SELECT * FROM pragma_${pragmaName}(?, ?)`, [
+            qualified.name,
+            qualified.schema ?? "main",
+        ]);
+    }
+    /** A worker that died, including one stopped for overrunning, is replaced on the next call. */
+    async run(sql, params = []) {
+        const handle = await this.worker.get();
+        try {
+            return await handle.run(sql, params, this.tuning.queryTimeoutMs);
+        }
+        catch (error) {
+            if (handle.dead) {
+                await this.worker.reset();
+            }
+            throw error;
+        }
+    }
+}

package/dist/drivers/sql/SqliteProtocol.js

@@ -0,0 +1,7 @@
+/**
+ * Messages between SqliteDriver and the worker process that owns the database.
+ *
+ * Kept in their own module so both sides import one definition, rather than
+ * two files agreeing on a shape by coincidence.
+ */
+export {};