@shibbirweb/mcp-db-read-only 0.1.0

package/dist/drivers/keyvalue/RedisDriver.js

@@ -0,0 +1,224 @@
+import { EngineCatalog } from "../../domain/Engine.js";
+import { ObjectNotFoundError } from "../../errors/ObjectNotFoundError.js";
+import { BaseDriver } from "../BaseDriver.js";
+import { LazyResource } from "../LazyResource.js";
+import { RedisCommandFlagsGuard } from "./RedisCommandFlagsGuard.js";
+/**
+ * Redis, and anything speaking its protocol (Valkey, KeyDB, Dragonfly),
+ * through ioredis.
+ *
+ * Keys stand in for tables: list_tables scans keys, describe_table reports a
+ * key's type, TTL and size, and get_table_sample reads a bounded slice of its
+ * value. Every one of those uses a fixed read command chosen here.
+ *
+ * Read-only layer two applies to redis_command, the only path where the
+ * caller chooses the command: RedisCommandFlagsGuard asks the server to
+ * confirm the command is flagged read-only before it is sent.
+ */
+export class RedisDriver extends BaseDriver {
+    tuning;
+    logger;
+    guard;
+    family = "keyvalue";
+    /** How many keys one SCAN step asks for. A hint to Redis, not a limit. */
+    static SCAN_BATCH = 500;
+    /** Long strings are cut in samples; the length is reported so nothing is hidden silently. */
+    static MAX_STRING_PREVIEW = 4096;
+    client;
+    constructor(target, tuning, logger, guard = new RedisCommandFlagsGuard()) {
+        super(target);
+        this.tuning = tuning;
+        this.logger = logger;
+        this.guard = guard;
+        this.client = new LazyResource(() => this.open(), async (client) => {
+            client.disconnect();
+        });
+    }
+    async verify() {
+        await this.call("PING");
+    }
+    close() {
+        return this.client.close();
+    }
+    /**
+     * INFO keyspace lists only databases holding keys, which is what someone
+     * browsing wants; the active one is always included even when empty.
+     */
+    async listDatabases() {
+        const info = String(await this.call("INFO", "keyspace"));
+        const names = new Set();
+        for (const match of info.matchAll(/^db(\d+):/gm)) {
+            names.add(match[1]);
+        }
+        names.add(this.databaseIndex().toString());
+        return Array.from(names)
+            .sort((a, b) => Number(a) - Number(b))
+            .map((name) => ({ name, system: false }));
+    }
+    /**
+     * SCAN, never KEYS: KEYS blocks the whole server while it walks every key,
+     * which on a production instance is an outage.
+     */
+    async listObjects(pattern, limit) {
+        const found = [];
+        let cursor = "0";
+        do {
+            const [next, keys] = (await this.call("SCAN", cursor, "MATCH", pattern || "*", "COUNT", String(RedisDriver.SCAN_BATCH)));
+            cursor = next;
+            found.push(...keys);
+        } while (cursor !== "0" && found.length <= limit);
+        const unique = Array.from(new Set(found)).sort();
+        return { names: unique.slice(0, limit), truncated: unique.length > limit || cursor !== "0" };
+    }
+    async describeObject(name) {
+        const type = await this.typeOf(name);
+        const [ttl, length, encoding, memory] = await Promise.all([
+            this.call("TTL", name),
+            this.lengthOf(name, type),
+            this.optional(() => this.call("OBJECT", "ENCODING", name)),
+            this.optional(() => this.call("MEMORY", "USAGE", name)),
+        ]);
+        return {
+            key: name,
+            type,
+            // -1 means the key never expires, which reads better said than shown.
+            ttl_seconds: ttl === -1 ? "no expiry" : ttl,
+            length,
+            encoding,
+            memory_bytes: memory,
+        };
+    }
+    /** A bounded slice of the value, read with the command that fits its type. */
+    async sample(name, limit) {
+        const type = await this.typeOf(name);
+        const last = String(limit - 1);
+        switch (type) {
+            case "string":
+                return this.previewString(String(await this.call("GET", name)));
+            case "hash":
+                return this.pairs((await this.call("HSCAN", name, "0", "COUNT", String(limit))), limit);
+            case "list":
+                return this.call("LRANGE", name, "0", last);
+            case "set":
+                return (await this.call("SSCAN", name, "0", "COUNT", String(limit)))[1].slice(0, limit);
+            case "zset":
+                return this.scored((await this.call("ZRANGE", name, "0", last, "WITHSCORES")));
+            case "stream":
+                return this.call("XRANGE", name, "-", "+", "COUNT", String(limit));
+            case "ReJSON-RL":
+                return JSON.parse(String(await this.call("JSON.GET", name)));
+            default:
+                return { key: name, type, note: "No sample reader for this type; use redis_command." };
+        }
+    }
+    async command(name, args) {
+        const client = await this.client.get();
+        const call = (command, ...rest) => client.call(command, ...rest);
+        const subcommand = this.isContainer(name) ? args[0]?.toUpperCase() : undefined;
+        await this.guard.assertReadOnly(call, name, subcommand);
+        return call(name, ...args);
+    }
+    async typeOf(name) {
+        const type = String(await this.call("TYPE", name));
+        if (type === "none") {
+            throw new ObjectNotFoundError(this.objectNoun, name);
+        }
+        return type;
+    }
+    async lengthOf(name, type) {
+        const command = {
+            string: "STRLEN",
+            hash: "HLEN",
+            list: "LLEN",
+            set: "SCARD",
+            zset: "ZCARD",
+            stream: "XLEN",
+        };
+        return command[type] ? this.call(command[type], name) : null;
+    }
+    /** OBJECT and MEMORY are often denied by ACLs or missing on compatible servers. */
+    async optional(read) {
+        try {
+            return await read();
+        }
+        catch {
+            return null;
+        }
+    }
+    previewString(value) {
+        if (value.length <= RedisDriver.MAX_STRING_PREVIEW) {
+            return value;
+        }
+        return {
+            preview: value.slice(0, RedisDriver.MAX_STRING_PREVIEW),
+            total_length: value.length,
+        };
+    }
+    pairs(reply, limit) {
+        const flat = reply[1];
+        const out = {};
+        for (let index = 0; index + 1 < flat.length && Object.keys(out).length < limit; index += 2) {
+            out[flat[index]] = flat[index + 1];
+        }
+        return out;
+    }
+    scored(flat) {
+        const out = [];
+        for (let index = 0; index + 1 < flat.length; index += 2) {
+            out.push({ member: flat[index], score: Number(flat[index + 1]) });
+        }
+        return out;
+    }
+    isContainer(name) {
+        return ["OBJECT", "MEMORY", "XINFO"].includes(name);
+    }
+    async call(command, ...args) {
+        const client = await this.client.get();
+        return client.call(command, ...args);
+    }
+    databaseIndex() {
+        const parsed = Number.parseInt(this.target.database, 10);
+        return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+    }
+    /** Imported on first use; see MySqlDriver.createPool. */
+    async open() {
+        const { Redis: RedisClient } = await import("ioredis");
+        const secure = EngineCatalog.scheme(this.target.scheme).secure;
+        // Reconnect only once a connection has worked. With lazyConnect, ioredis
+        // retries a refused first connection forever and connect() never settles,
+        // so connecting to a Redis that is down hung the tool call instead of
+        // failing it. Found when the integration probe hung on a missing server.
+        let everConnected = false;
+        const client = new RedisClient({
+            host: this.target.host,
+            port: this.target.port,
+            username: this.target.user || undefined,
+            password: this.target.password || undefined,
+            db: this.databaseIndex(),
+            tls: secure ? {} : undefined,
+            connectTimeout: this.tuning.connectTimeoutMs,
+            commandTimeout: this.tuning.queryTimeoutMs,
+            lazyConnect: true,
+            // Fail a command promptly while disconnected rather than queueing it
+            // until the server returns, which from a conversation looks like a hang.
+            maxRetriesPerRequest: 1,
+            retryStrategy: (attempt) => (everConnected ? Math.min(attempt * 200, 2000) : null),
+            connectionName: "mcp-db-read-only",
+        });
+        client.once("ready", () => {
+            everConnected = true;
+        });
+        // ioredis emits connection errors as events; unlistened, they are printed
+        // by the library itself. Routed through the logger they stay on stderr
+        // and carry this server's prefix.
+        client.on("error", (error) => this.logger(`redis: ${error.message}`));
+        try {
+            await client.connect();
+        }
+        catch (error) {
+            client.disconnect();
+            throw error;
+        }
+        return client;
+    }
+}

package/dist/drivers/search/ElasticsearchDriver.js

@@ -0,0 +1,159 @@
+import { EngineCatalog } from "../../domain/Engine.js";
+import { ObjectNotFoundError } from "../../errors/ObjectNotFoundError.js";
+import { UnsupportedOperationError } from "../../errors/UnsupportedOperationError.js";
+import { BaseDriver } from "../BaseDriver.js";
+/**
+ * Elasticsearch and OpenSearch, over their REST API with Node's own fetch.
+ *
+ * No client library, for two reasons. The official Elasticsearch client
+ * refuses to talk to OpenSearch, and the OpenSearch client to Elasticsearch,
+ * so supporting both would take two dependencies. And the five read calls
+ * needed here are simple enough that a client would add weight without
+ * adding safety; the closed ReadRequest union is the safety.
+ *
+ * Authentication is basic auth from the URL's user and password, or an API
+ * key from `?api_key=`, which is kept out of every displayed string.
+ */
+export class ElasticsearchDriver extends BaseDriver {
+    tuning;
+    fetcher;
+    family = "search";
+    constructor(target, tuning, 
+    // Wrapped so fetch is never invoked with this driver as its receiver.
+    fetcher = (input, init) => fetch(input, init)) {
+        super(target);
+        this.tuning = tuning;
+        this.fetcher = fetcher;
+    }
+    async verify() {
+        const cluster = (await this.send({ kind: "cluster" }, this.tuning.connectTimeoutMs));
+        if (!cluster.version?.number) {
+            throw new Error("The server answered, but not as Elasticsearch or OpenSearch.");
+        }
+    }
+    /** Nothing to release: fetch holds no connection between calls that we own. */
+    async close() {
+        return;
+    }
+    async listDatabases() {
+        throw new UnsupportedOperationError(this.label, "databases", "Its indices are listed by list_tables.");
+    }
+    /**
+     * Indices whose names start with `.` are internal (security, Kibana,
+     * ingest state) and are hidden unless the pattern asks for them.
+     */
+    async listObjects(pattern, limit) {
+        const rows = (await this.send({ kind: "indices", pattern: pattern || "*" }));
+        const showHidden = (pattern ?? "").startsWith(".");
+        const names = rows
+            .map((row) => row.index)
+            .filter((name) => showHidden || !name.startsWith("."))
+            .sort();
+        return { names: names.slice(0, limit), truncated: names.length > limit };
+    }
+    async describeObject(name) {
+        return this.send({ kind: "mapping", index: name });
+    }
+    async sample(name, limit) {
+        const result = (await this.search(name, { size: limit }));
+        return result.hits;
+    }
+    /** Hits trimmed to what a reader needs, with the total reported alongside. */
+    async search(index, body) {
+        const result = (await this.send({ kind: "search", index, body }));
+        return {
+            took_ms: result.took,
+            timed_out: result.timed_out,
+            total: result.hits?.total,
+            hits: (result.hits?.hits ?? []).map((hit) => ({
+                _index: hit._index,
+                _id: hit._id,
+                _score: hit._score,
+                _source: hit._source,
+                fields: hit.fields,
+                highlight: hit.highlight,
+                sort: hit.sort,
+            })),
+            aggregations: result.aggregations,
+            suggest: result.suggest,
+        };
+    }
+    async send(request, timeoutMs = this.tuning.queryTimeoutMs) {
+        const { method, path, body } = this.route(request);
+        const response = await this.fetcher(`${this.baseUrl()}${path}`, {
+            method,
+            headers: this.headers(),
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const text = await response.text();
+        const parsed = text ? this.parse(text) : null;
+        if (response.status === 404 && request.kind !== "cluster" && request.kind !== "indices") {
+            throw new ObjectNotFoundError(this.objectNoun, request.index);
+        }
+        if (!response.ok) {
+            throw new Error(`${this.label} answered ${response.status}: ${this.reason(parsed, text)}`);
+        }
+        return parsed;
+    }
+    /**
+     * The only place a path is built. Index names are percent-encoded on top of
+     * having passed the name policy, which already refused `.`, `..` and a
+     * leading `_`.
+     */
+    route(request) {
+        switch (request.kind) {
+            case "cluster":
+                return { method: "GET", path: "/" };
+            case "indices":
+                return {
+                    method: "GET",
+                    path: `/_cat/indices/${this.segment(request.pattern)}?format=json&h=index&expand_wildcards=open`,
+                };
+            case "mapping":
+                return { method: "GET", path: `/${this.segment(request.index)}/_mapping` };
+            case "search":
+                return { method: "POST", path: `/${this.segment(request.index)}/_search`, body: request.body };
+        }
+    }
+    /** Commas and wildcards are meaningful in an index expression, so they are kept. */
+    segment(value) {
+        return encodeURIComponent(value).replace(/%2C/gi, ",").replace(/%2A/gi, "*");
+    }
+    baseUrl() {
+        const secure = EngineCatalog.scheme(this.target.scheme).secure;
+        const host = this.target.host.includes(":") ? `[${this.target.host}]` : this.target.host;
+        return `${secure ? "https" : "http"}://${host}:${this.target.port}`;
+    }
+    headers() {
+        const headers = { "content-type": "application/json", accept: "application/json" };
+        const apiKey = this.target.secretOption("api_key") ?? this.target.secretOption("apikey");
+        if (apiKey) {
+            headers.authorization = `ApiKey ${apiKey}`;
+        }
+        else if (this.target.user) {
+            const credentials = Buffer.from(`${this.target.user}:${this.target.password}`).toString("base64");
+            headers.authorization = `Basic ${credentials}`;
+        }
+        return headers;
+    }
+    parse(text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    /** Elasticsearch errors carry `error.root_cause[0].reason`; the first useful one wins. */
+    reason(parsed, text) {
+        const error = parsed?.error;
+        if (typeof error === "string") {
+            return error;
+        }
+        if (error?.reason) {
+            return error.type ? `${error.type}: ${error.reason}` : error.reason;
+        }
+        return text.slice(0, 500);
+    }
+}

package/dist/drivers/sql/ClickHouseDriver.js

@@ -0,0 +1,156 @@
+import { EngineCatalog } from "../../domain/Engine.js";
+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";
+/**
+ * ClickHouse, through the official client over the HTTP interface.
+ *
+ * Read-only layer two is ClickHouse's own `readonly` setting, sent with every
+ * query. `readonly=2` refuses every write and DDL statement while still
+ * allowing the timeout and result caps below to be set, and it cannot itself
+ * be lowered from inside a query.
+ *
+ * An account that is already read-only on the server (a user profile with
+ * `readonly=1`) refuses any setting at all, the read-only one included. So the
+ * driver asks first and only sends what the account permits: a server that
+ * already enforces read-only needs nothing from us to do so.
+ */
+export class ClickHouseDriver extends BaseDriver {
+    tuning;
+    family = "sql";
+    dialect = "clickhouse";
+    static SYSTEM_DATABASES = new Set(["system", "INFORMATION_SCHEMA", "information_schema"]);
+    /**
+     * An analytics table can hold billions of rows, and the formatter shows only
+     * a hundred. Capping on the server stops a careless SELECT * from pulling a
+     * table into this process's memory before any of it is thrown away.
+     */
+    static MAX_RESULT_ROWS = 10000;
+    client;
+    constructor(target, tuning) {
+        super(target);
+        this.tuning = tuning;
+        this.client = new LazyResource(() => this.open(), (opened) => opened.client.close());
+    }
+    async verify() {
+        await this.run("SELECT 1 AS ok");
+    }
+    close() {
+        return this.client.close();
+    }
+    async listDatabases() {
+        const rows = (await this.run("SELECT name FROM system.databases ORDER BY name"));
+        return rows.map((row) => ({ name: row.name, system: ClickHouseDriver.SYSTEM_DATABASES.has(row.name) }));
+    }
+    async listObjects(pattern, limit) {
+        const rows = (await this.run("SELECT name FROM system.tables WHERE database = {database:String} ORDER BY name", { database: this.databaseName() }));
+        return new GlobPattern(pattern).apply(rows.map((row) => row.name), limit);
+    }
+    /** Identifier parameters: ClickHouse binds the table name itself, so nothing is interpolated. */
+    async describeObject(name) {
+        const { database, table } = this.locate(name);
+        await this.assertExists(database, table);
+        return this.run("DESCRIBE TABLE {database:Identifier}.{table:Identifier}", { database, table });
+    }
+    /** ClickHouse has sorting and primary keys plus skipping indices, rather than B-tree indexes. */
+    async listIndexes(name) {
+        const { database, table } = this.locate(name);
+        await this.assertExists(database, table);
+        const keys = await this.run(`SELECT partition_key, sorting_key, primary_key, sampling_key
+       FROM system.tables WHERE database = {database:String} AND name = {table:String}`, { database, table });
+        const skipping = await this.run(`SELECT name, type, expr, granularity
+       FROM system.data_skipping_indices WHERE database = {database:String} AND table = {table:String}`, { database, table });
+        return { keys: keys[0] ?? {}, data_skipping_indices: skipping };
+    }
+    async sample(name, limit) {
+        const { database, table } = this.locate(name);
+        return this.run("SELECT * FROM {database:Identifier}.{table:Identifier} LIMIT {limit:UInt32}", {
+            database,
+            table,
+            limit,
+        });
+    }
+    query(sql) {
+        return this.run(sql);
+    }
+    async run(sql, params) {
+        const { client, settings } = await this.client.get();
+        const result = await client.query({
+            query: sql,
+            format: "JSONEachRow",
+            query_params: params,
+            clickhouse_settings: settings,
+        });
+        return (await result.json());
+    }
+    async assertExists(database, table) {
+        const rows = await this.run("SELECT 1 AS found FROM system.tables WHERE database = {database:String} AND name = {table:String}", { database, table });
+        if (rows.length === 0) {
+            throw new ObjectNotFoundError(this.objectNoun, table);
+        }
+    }
+    /** `db.table` names a table in another database; a bare name means the connection's own. */
+    locate(name) {
+        const qualified = SqlIdentifier.parse(name);
+        return { database: qualified.schema ?? this.databaseName(), table: qualified.name };
+    }
+    databaseName() {
+        return this.target.database || EngineCatalog.describe("clickhouse").defaultDatabase;
+    }
+    /** Imported on first use; see MySqlDriver.createPool. */
+    async open() {
+        const { createClient, ClickHouseLogLevel } = await import("@clickhouse/client");
+        const secure = EngineCatalog.scheme(this.target.scheme).secure;
+        const client = createClient({
+            url: `${secure ? "https" : "http"}://${this.target.host}:${this.target.port}`,
+            username: this.target.user || "default",
+            password: this.target.password,
+            database: this.databaseName(),
+            application: "mcp-db-read-only",
+            max_open_connections: this.tuning.connectionLimit,
+            // Client-side, a little beyond the server-side limit, so the server's
+            // own timeout error is what the user sees.
+            request_timeout: this.tuning.queryTimeoutMs + 5000,
+            // The client's own logger writes debug and info through console.debug
+            // and console.info, which go to stdout, the JSON-RPC stream; one level
+            // change would corrupt the protocol. Its error lines also carry query
+            // context, which PRIVACY.md says is never logged. Every failure already
+            // reaches the caller as a thrown error, so nothing is lost.
+            log: { level: ClickHouseLogLevel.OFF },
+        });
+        try {
+            return { client, settings: await this.negotiateSettings(client) };
+        }
+        catch (error) {
+            await client.close();
+            throw error;
+        }
+    }
+    /**
+     * Reads the account's own `readonly` level with no settings attached, since
+     * attaching any is exactly what a read-only account refuses.
+     */
+    async negotiateSettings(client) {
+        const result = await client.query({
+            query: "SELECT toUInt8(getSetting('readonly')) AS readonly",
+            format: "JSONEachRow",
+        });
+        const rows = (await result.json());
+        const level = Number(rows[0]?.readonly ?? 0);
+        const limits = {
+            max_execution_time: Math.max(1, Math.ceil(this.tuning.queryTimeoutMs / 1000)),
+            max_result_rows: String(ClickHouseDriver.MAX_RESULT_ROWS),
+            result_overflow_mode: "break",
+        };
+        if (level === 0) {
+            return { ...limits, readonly: "2" };
+        }
+        if (level === 2) {
+            return limits;
+        }
+        // readonly=1: the server already refuses writes, and refuses any setting.
+        return {};
+    }
+}

package/dist/drivers/sql/MsSqlDriver.js

@@ -0,0 +1,147 @@
+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";
+/**
+ * SQL Server and Azure SQL, through the `mssql` package (tedious underneath).
+ *
+ * Read-only layer two: SQL Server has no read-only session mode, so **every
+ * batch runs inside a transaction that is always rolled back**. A write that
+ * got past the validator is undone before the connection is reused, and
+ * statements that refuse to run inside a transaction (BACKUP, ALTER DATABASE)
+ * fail outright. The validator separately refuses COMMIT, so the batch cannot
+ * end the transaction early.
+ *
+ * `?applicationIntent=ReadOnly` routes to a readable secondary in an
+ * availability group. It is opt-in: against a primary that disallows
+ * read-intent connections, forcing it would make every connection fail.
+ */
+export class MsSqlDriver extends BaseDriver {
+    tuning;
+    family = "sql";
+    dialect = "mssql";
+    static SYSTEM_DATABASES = new Set(["master", "tempdb", "model", "msdb"]);
+    pool;
+    constructor(target, tuning) {
+        super(target);
+        this.tuning = tuning;
+        this.pool = new LazyResource(() => this.createPool(), (opened) => opened.pool.close());
+    }
+    async verify() {
+        await this.run("SELECT 1 AS ok");
+    }
+    close() {
+        return this.pool.close();
+    }
+    async listDatabases() {
+        const rows = (await this.run("SELECT name FROM sys.databases WHERE state = 0 ORDER BY name"));
+        return rows.map((row) => ({ name: row.name, system: MsSqlDriver.SYSTEM_DATABASES.has(row.name) }));
+    }
+    /** `dbo` tables are listed bare and everything else schema-qualified. */
+    async listObjects(pattern, limit) {
+        const rows = (await this.run("SELECT TABLE_SCHEMA AS table_schema, TABLE_NAME AS table_name FROM INFORMATION_SCHEMA.TABLES ORDER BY TABLE_SCHEMA, TABLE_NAME"));
+        const names = rows.map((row) => row.table_schema === "dbo" ? 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(@schema, SCHEMA_NAME()) AND TABLE_NAME = @table
+       ORDER BY ORDINAL_POSITION`, { schema: qualified.schema, table: qualified.name });
+        if (rows.length === 0) {
+            throw new ObjectNotFoundError(this.objectNoun, name);
+        }
+        return rows;
+    }
+    async listIndexes(name) {
+        await this.assertExists(name);
+        return this.run(`SELECT i.name AS index_name, i.type_desc, i.is_unique, i.is_primary_key, c.name AS column_name,
+              ic.key_ordinal, ic.is_included_column
+       FROM sys.indexes i
+       JOIN sys.index_columns ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
+       JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
+       WHERE i.object_id = OBJECT_ID(@object)
+       ORDER BY i.name, ic.key_ordinal`, { object: this.quote(name) });
+    }
+    async listForeignKeys(name) {
+        await this.assertExists(name);
+        return this.run(`SELECT fk.name AS constraint_name, pc.name AS column_name,
+              OBJECT_SCHEMA_NAME(fk.referenced_object_id) AS referenced_schema,
+              OBJECT_NAME(fk.referenced_object_id) AS referenced_table,
+              rc.name AS referenced_column
+       FROM sys.foreign_keys fk
+       JOIN sys.foreign_key_columns fkc ON fkc.constraint_object_id = fk.object_id
+       JOIN sys.columns pc ON pc.object_id = fkc.parent_object_id AND pc.column_id = fkc.parent_column_id
+       JOIN sys.columns rc ON rc.object_id = fkc.referenced_object_id AND rc.column_id = fkc.referenced_column_id
+       WHERE fk.parent_object_id = OBJECT_ID(@object)
+       ORDER BY fk.name`, { object: this.quote(name) });
+    }
+    async sample(name, limit) {
+        return this.run(`SELECT TOP (@limit) * FROM ${this.quote(name)}`, { limit });
+    }
+    query(sql) {
+        return this.run(sql);
+    }
+    /**
+     * One batch inside a transaction that is always rolled back.
+     *
+     * If the batch itself fails, SQL Server may already have aborted the
+     * transaction, and the rollback then fails too. That second failure is
+     * swallowed: the batch's own error is the one worth reporting, and an
+     * aborted transaction has nothing left to undo.
+     */
+    async run(text, inputs = {}) {
+        const { pool, sql } = await this.pool.get();
+        const transaction = new sql.Transaction(pool);
+        await transaction.begin();
+        try {
+            const request = new sql.Request(transaction);
+            for (const [name, value] of Object.entries(inputs)) {
+                request.input(name, value);
+            }
+            const result = await request.query(text);
+            return (result.recordset ?? []);
+        }
+        finally {
+            await transaction.rollback().catch(() => undefined);
+        }
+    }
+    async assertExists(name) {
+        const rows = await this.run("SELECT OBJECT_ID(@object) AS id", { object: this.quote(name) });
+        if (rows[0]?.id == null) {
+            throw new ObjectNotFoundError(this.objectNoun, name);
+        }
+    }
+    quote(name) {
+        return SqlIdentifier.quoteQualified(SqlIdentifier.parse(name), SqlIdentifier.bracket);
+    }
+    /** Imported on first use; see MySqlDriver.createPool. */
+    async createPool() {
+        const { default: sql } = (await import("mssql"));
+        const pool = new sql.ConnectionPool({
+            server: this.target.host,
+            port: this.target.port,
+            user: this.target.user,
+            password: this.target.password,
+            database: this.target.database || undefined,
+            connectionTimeout: this.tuning.connectTimeoutMs,
+            requestTimeout: this.tuning.queryTimeoutMs,
+            pool: { max: this.tuning.connectionLimit, min: 0 },
+            options: {
+                // Encrypted unless the URL says otherwise, which is also tedious's
+                // default. A self-signed development server needs
+                // trustServerCertificate=true.
+                encrypt: this.target.flag("encrypt") ?? true,
+                trustServerCertificate: this.target.flag("trustServerCertificate") ?? false,
+                readOnlyIntent: (this.target.option("applicationIntent") ?? "").toLowerCase() === "readonly",
+                appName: "mcp-db-read-only",
+            },
+        });
+        // Without a listener a dropped idle connection is an unhandled error.
+        pool.on("error", () => undefined);
+        await pool.connect();
+        return { pool, sql };
+    }
+}