pg-admin-mcp 0.0.0-stage → 0.1.0

package/dist/tools/execute_sql.js

@@ -0,0 +1,395 @@
+import { z } from 'zod';
+import { loadProfiles } from '../config/profiles.js';
+import { leadingKeyword, obviousWriteKeyword, planStatements } from '../core/classifier.js';
+import { PgMcpError, envPrefix, toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { assertRawWhere, CONFIRM_PROTOCOL_DESCRIPTION, runGuardedMutation } from '../core/guards.js';
+import { resolveLimits } from '../core/limits.js';
+import { requireCapability } from '../core/policy.js';
+import { withTx } from '../db/session.js';
+import { confirmFragment, toExpectToken } from './_batch_shared.js';
+import { defineTool, profileParam } from './_shared.js';
+/**
+ * `postgres_execute_sql` — the arbitrary-SQL escape hatch.
+ *
+ * This is the one tool where the project's usual discipline (`SafeIdent`
+ * identifiers resolved through the catalog, values only ever bound as `$N`)
+ * does not apply, because the caller supplies the SQL text. Its safety story
+ * therefore comes from somewhere else entirely:
+ *
+ * 1. **PostgreSQL's own read-only transaction.** Every statement that is not
+ *    routed to the write path runs inside `withTx({ readOnly: true })`, so the
+ *    server itself rejects any write with SQLSTATE `25006`, which
+ *    `core/errors.ts#fromPgError` maps to `POLICY_READ_ONLY` with a hint naming
+ *    `PG_<ALIAS>_ALLOW_WRITE`. That, not the lexical pre-check below, is what
+ *    catches `WITH x AS (INSERT … RETURNING) SELECT * FROM x`,
+ *    `SELECT nextval('s')`, and a VOLATILE function that writes. See
+ *    `core/classifier.ts`.
+ *
+ *    **This still holds on a write-capable profile**, and it is the single most
+ *    important consequence of the routing rule below: the write path is entered
+ *    only by a statement whose *leading keyword* says it writes. A statement
+ *    that hides its write (`WITH … INSERT … RETURNING`, `SELECT nextval()`) is
+ *    therefore still run read-only and still refused with 25006 — even when the
+ *    profile has `ALLOW_WRITE`. Rewrite it as a plain `INSERT`/`UPDATE`/`DELETE`
+ *    to get the dry-run/confirm protocol. Refusing is the safe direction: the
+ *    alternative is a statement that writes without ever being previewed.
+ * 2. **Multi-statement rejection** (design.md risk 7), via the scanner in
+ *    `core/classifier.ts#splitStatements`. `pg` runs a multi-statement string
+ *    in simple-query mode as one implicit transaction *and silently ignores
+ *    parameters*; both halves of that are refused here.
+ * 3. **The extended query protocol, forced explicitly.** Every query this tool
+ *    issues goes through `{ text, values, queryMode: 'extended' }`, where
+ *    PostgreSQL accepts exactly one statement per Parse and answers a second
+ *    one with `42601 cannot insert multiple commands into a prepared
+ *    statement`. That makes the scanner in (2) a fast, readable first refusal
+ *    rather than the sole fence.
+ *
+ *    **`queryMode` is not decoration.** The previous version of this comment
+ *    claimed an always-present `params` array was enough — it is not.
+ *    `pg@8.22`'s `Query.requiresPreparation()` ends `return this.values.length
+ *    > 0`, so on the common no-params call `client.query(sql, [])` runs in
+ *    *simple* mode and `SELECT 1; INSERT …` executes both commands. Measured,
+ *    not assumed. Do not remove `queryMode` from any call site in this file.
+ *
+ *    **Since the write path shipped, `queryMode` is the ONLY structural
+ *    multi-statement fence left on this tool.** The read-only transaction used
+ *    to be a blanket second answer to `SELECT 1; INSERT …` — a write-capable
+ *    profile no longer has it. `core/guards.ts#runMutation` sets `queryMode`
+ *    for the same reason, so both paths keep the fence. There is an integration
+ *    test that submits exactly that string to a write-capable profile and
+ *    asserts `42601`; if it ever goes green for the wrong reason, this is why
+ *    it exists.
+ *
+ * ## Routing: which statements take the write path
+ *
+ * One table, {@link WRITE_PATH_CAPABILITY}, keyed by the statement's leading
+ * keyword (`core/classifier.ts#leadingKeyword`), mapping to the capability that
+ * statement needs. Absent from the table means the read path.
+ *
+ * - DML (`INSERT`/`UPDATE`/`DELETE`/`MERGE`) needs `write`.
+ * - DDL (`CREATE`/`ALTER`/`DROP`/`TRUNCATE`) needs `ddl` **on top of** `write`.
+ *   `ALLOW_WRITE` is the master switch for this tool's write path; `ALLOW_DDL`
+ *   is the second key for the statements that can destroy a schema rather than
+ *   rows.
+ * - `GRANT`/`REVOKE` need `admin`, again on top of `write`. Changing who may
+ *   read a table is not DDL and is not an ordinary write.
+ * - **Transaction control** (`BEGIN`, `COMMIT`, `ROLLBACK`, `END`, `ABORT`,
+ *   `SAVEPOINT`, `RELEASE`, `START`) is routed to the write path deliberately,
+ *   even though it writes nothing. It is what *attacks* the guard: a bare
+ *   `COMMIT` ends the transaction `withTx` owns, and on the write path the
+ *   `rollbackAlways` savepoint fence detects that and raises
+ *   `GUARD_DRY_RUN_ESCAPED` with a human-readable hint. Routed to the read path
+ *   it would instead succeed silently as a no-op. Nothing is lost by refusing
+ *   it — this server always owns the transaction.
+ *
+ * **Bounded fetch, not just a bounded response.** The page is read through a
+ * server-side `DECLARE … NO SCROLL CURSOR` + one `FETCH FORWARD n+1` inside
+ * the same transaction, so `limit: 1` against a 400k-row table transfers one
+ * row instead of buffering all 400k in the driver and slicing in JS (measured:
+ * a 168.9 MB heap delta to return a single row). Statements that cannot back a
+ * cursor at all — `EXPLAIN`, `SHOW`, … — fall back to a direct query; those
+ * return a handful of rows, which is not the failure mode this guards.
+ *
+ * **No cursor is handed out.** design.md §`core/paginate.ts` is explicit:
+ * **keyset cursors only**, because successive calls land on different pooled
+ * backends (risk 4). Offset-into-a-re-run is not keyset — a plan change
+ * between pages overlaps or skips rows — so this tool caps the page and tells
+ * the caller to put `LIMIT`/`OFFSET` (or a keyset predicate) in their own SQL,
+ * where they can see it. `postgres_select` is the tool with real pagination.
+ *
+ * Read-only is not a sandbox (design.md risk 8): it does not stop
+ * `COPY … TO PROGRAM`, `lo_export()`, or advisory locks. The documented
+ * production posture is a PostgreSQL role that is itself read-only.
+ *
+ * ## What the write path cannot offer, and why
+ *
+ * - **No `keyChecksum`, no preview.** The guard's key preview comes from
+ *   catalog-resolved primary key columns wrapped around the statement as
+ *   `WITH … RETURNING pk`. Raw SQL has no catalog-resolved target relation —
+ *   deriving one would mean parsing the statement, which this project
+ *   deliberately refuses to do (`core/classifier.ts`). So `keyColumns` is empty
+ *   here and `rowCount` is the whole receipt.
+ * - **Therefore raw SQL cannot write on a `production` profile at all.**
+ *   `core/policy.ts` makes `expect.keyChecksum` mandatory there, and
+ *   `runGuardedMutation` refuses up front rather than after a dry run nobody
+ *   could confirm. That is the right outcome, not a gap: on production, use
+ *   `postgres_update_batch`/`postgres_delete_batch`/`postgres_insert_batch`,
+ *   which resolve a real primary key and can pin *which* rows they touch.
+ * - **No `allowMultiple`.** Refused outright on the write path. N statements in
+ *   one transaction have no per-statement dry run, no `rowCount` worth hashing
+ *   and no `expect` token that could mean anything about the middle of the list.
+ * - **No rows come back.** A confirmed write reports a row count; a `RETURNING`
+ *   list is executed but not rendered. `limit` applies to the read path only.
+ */
+const DEFAULT_PAGE_SIZE = 200;
+const MAX_PAGE_SIZE = 2000;
+/** Named rather than random so it is greppable in a server log; closed before the transaction ends, so it never outlives the checkout. */
+const CURSOR_NAME = 'pg_admin_mcp_exec_cursor';
+/** Fences the `DECLARE` attempt: a statement a cursor cannot wrap aborts the transaction, and this is what lets the direct-query fallback run anyway. */
+const CURSOR_SAVEPOINT = 'pg_admin_mcp_exec_probe';
+const inputSchema = z.object({
+    ...profileParam,
+    sql: z.string().min(1).describe('The SQL to run. One statement unless allowMultiple is set. Never string-interpolate values into this — use params.'),
+    params: z
+        .array(z.unknown())
+        .optional()
+        .describe('Bound parameters for $1, $2, … — always sent over the extended query protocol, so a value is data, never SQL.'),
+    allowMultiple: z
+        .boolean()
+        .optional()
+        .describe('Permit several ;-separated statements. Refused by default; impossible together with params.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PAGE_SIZE)
+        .optional()
+        .describe(`Rows fetched (max ${MAX_PAGE_SIZE}), further capped by the profile row limit. Bounds the fetch, not just the response — put LIMIT/OFFSET in your own SQL to read past it.`),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Per-call statement timeout. Can only tighten the profile\'s PG_<ALIAS>_STATEMENT_TIMEOUT_MS, never loosen it.'),
+    ...confirmFragment,
+});
+/**
+ * The cheap fast-fail for a profile that cannot write at all. Never the
+ * guarantee — see `core/classifier.ts`. Exported so `tools/export.ts` reuses it
+ * for its `sql`-source path (always read-only) instead of a second copy.
+ *
+ * Still here, and still branched on `profile.capabilities.write` rather than
+ * deleted, because on a read-only profile it is the fastest and most readable
+ * refusal there is: it names the keyword and the env var without a round trip.
+ */
+export function assertNoObviousWrite(statements, alias) {
+    for (const statement of statements) {
+        const keyword = obviousWriteKeyword(statement);
+        if (keyword === undefined)
+            continue;
+        throw new PgMcpError({
+            code: 'POLICY_READ_ONLY',
+            message: `this statement starts with ${keyword}, and this profile runs every statement inside a read-only transaction`,
+            hint: `set ${envPrefix(alias)}_ALLOW_WRITE=true on this profile and restart the server to unlock ` +
+                'postgres_execute_sql\'s write path (a two-call dry run + confirm); DDL additionally needs ' +
+                `${envPrefix(alias)}_ALLOW_DDL=true`,
+            details: { profile: alias, keyword },
+        });
+    }
+}
+/** Every spelling PostgreSQL accepts for "end or fence the transaction". See the file header for why they take the write path. */
+const TX_CONTROL_KEYWORDS = ['BEGIN', 'START', 'COMMIT', 'END', 'ROLLBACK', 'ABORT', 'SAVEPOINT', 'RELEASE'];
+const TX_CONTROL = new Set(TX_CONTROL_KEYWORDS);
+/** The keywords whose dry run genuinely reports a row count. */
+const DML_KEYWORDS = new Set(['INSERT', 'UPDATE', 'DELETE', 'MERGE']);
+/** Leading keyword -> the capability that statement needs. Absent = read path. */
+const WRITE_PATH_CAPABILITY = {
+    INSERT: 'write',
+    UPDATE: 'write',
+    DELETE: 'write',
+    MERGE: 'write',
+    CREATE: 'ddl',
+    ALTER: 'ddl',
+    DROP: 'ddl',
+    TRUNCATE: 'ddl',
+    GRANT: 'admin',
+    REVOKE: 'admin',
+    ...Object.fromEntries(TX_CONTROL_KEYWORDS.map((keyword) => [keyword, 'write'])),
+};
+/** The first statement that would take the write path, or `undefined` for a pure read. */
+function planWrite(statements) {
+    for (const statement of statements) {
+        const keyword = leadingKeyword(statement);
+        const capability = keyword === undefined ? undefined : WRITE_PATH_CAPABILITY[keyword];
+        if (keyword !== undefined && capability !== undefined)
+            return { keyword, capability, statement };
+    }
+    return undefined;
+}
+/**
+ * What a DDL dry run actually establishes, stated so that nobody reads
+ * "0 row(s) would be affected" as "nothing will happen".
+ *
+ * PostgreSQL returns no row count for a utility statement, so the 0 is the
+ * absence of a number, not a measurement. The dry run really did run the
+ * statement against the real catalog inside a transaction that was rolled back
+ * — which proves parse, resolution and privilege, and proves nothing at all
+ * about blast radius.
+ */
+function ddlNote(keyword) {
+    return (`DDL — READ THIS BEFORE CONFIRMING. PostgreSQL reports no row count for ${keyword}, so the 0 above means ` +
+        '"not applicable", NOT "nothing will happen". What this dry run DID prove: the statement parsed, ran to ' +
+        'completion against the real catalog inside a transaction that was rolled back, and your role holds the ' +
+        'privileges for it. What it CANNOT tell you: how many rows a DROP or TRUNCATE will destroy, which views, ' +
+        'foreign keys, sequences or functions depend on the object, or how long an ALTER that rewrites the table will ' +
+        `hold its lock. Confirming runs the same ${keyword} for real. Call postgres_describe_object on the target first.`);
+}
+/** The other half of the honesty: raw DML has a real row count but no key identity behind it. */
+const RAW_DML_NOTE = 'The row count above is real — it is what the statement actually affected inside the rolled-back transaction. ' +
+    'There is no key preview and no keyChecksum: raw SQL has no catalog-resolved primary key, so the confirming call ' +
+    'can only re-verify the COUNT, not that the same rows are still the ones being hit. If the identity of the rows ' +
+    'matters, use postgres_update_batch / postgres_delete_batch instead.';
+/** Only reachable for BEGIN/START/SAVEPOINT — the rest end the transaction and are caught by the dry-run fence first. */
+const TX_CONTROL_NOTE = 'This statement only manipulates the transaction that this server owns and opens for you. It changed no data, and ' +
+    'confirming it would change none either. Delete it from your SQL: use confirm:true to commit a write, not COMMIT.';
+/** `runGuardedMutation` opens the transaction, so this refusal has to happen before it — and before any round trip. */
+function refuseMultiStatementWrite(keyword, alias) {
+    throw new PgMcpError({
+        code: 'PG_ERROR',
+        message: `allowMultiple cannot be combined with a write (this call starts with ${keyword}) — a list of statements has ` +
+            'no per-statement dry run, no row count worth hashing, and no expect token that would mean anything about the ' +
+            'middle of the list',
+        hint: 'send one write per call so each gets its own dry run and its own expect token, and re-run',
+        details: { profile: alias, keyword },
+    });
+}
+/**
+ * The guarded write path. Split out of the handler so the read path above stays
+ * exactly as it was — the two share only `planStatements` and the profile.
+ */
+async function runWrite(profile, write, args, params, timeoutMs) {
+    if (!profile.capabilities.write) {
+        // The fast, readable refusal, kept and branched rather than deleted.
+        assertNoObviousWrite([write.statement], profile.alias);
+        // Transaction control is not an "obvious write", so it reaches here instead.
+        requireCapability('write', profile);
+    }
+    if (args.allowMultiple === true)
+        refuseMultiStatementWrite(write.keyword, profile.alias);
+    if (write.keyword === 'UPDATE' || write.keyword === 'DELETE') {
+        // The WHERE guard for raw SQL. Cheap and easily fooled — the row count the
+        // dry run reports is the guard that matters. See `core/guards.ts`.
+        assertRawWhere(write.statement, { profile: profile.alias, operation: 'postgres_execute_sql' });
+    }
+    const outcome = await runGuardedMutation({
+        profile,
+        // `write` was verified above; this is the SECOND key for DDL/GRANT.
+        capability: write.capability,
+        operation: 'execute_sql',
+        sql: write.statement,
+        params,
+        // Raw SQL has no catalog-resolved relation, so there is no primary key to
+        // preview or checksum — and nothing here computes a checksum over
+        // server-generated keys, which a rolled-back dry run would invalidate
+        // anyway (sequences are not transactional; see `tools/insert_batch.ts`).
+        keyColumns: [],
+        confirm: args.confirm,
+        expect: toExpectToken(args.expect),
+        allowRowDrift: args.allowRowDrift,
+        ...(timeoutMs === undefined ? {} : { statementTimeoutMs: timeoutMs }),
+    });
+    if (outcome.kind !== 'dryRun')
+        return formatOutcome(outcome);
+    const note = DML_KEYWORDS.has(write.keyword)
+        ? RAW_DML_NOTE
+        : TX_CONTROL.has(write.keyword)
+            ? TX_CONTROL_NOTE
+            : ddlNote(write.keyword);
+    return formatOutcome({ ...outcome, note });
+}
+/**
+ * The only way caller-supplied SQL reaches PostgreSQL in this file.
+ * `queryMode: 'extended'` is the whole point — see the file header.
+ */
+async function runExtended(client, text, values) {
+    return client.query({ text, values: [...values], queryMode: 'extended' });
+}
+/**
+ * Fetches at most `pageLimit + 1` rows (the extra row is what proves there are
+ * more) without ever materializing the full result in the driver.
+ */
+async function fetchBounded(client, sql, params, pageLimit) {
+    await client.query(`SAVEPOINT ${CURSOR_SAVEPOINT}`);
+    try {
+        await runExtended(client, `DECLARE ${CURSOR_NAME} NO SCROLL CURSOR FOR ${sql}`, params);
+    }
+    catch (err) {
+        // `DECLARE … CURSOR FOR` only accepts a SELECT/VALUES/TABLE/WITH query, so
+        // `EXPLAIN`, `SHOW`, `TABLE`-adjacent utility statements and friends land
+        // here. The failed DECLARE aborted the transaction; rewind and run the
+        // statement directly — still extended-mode, still one command, just
+        // unbounded, which is fine for statements that return a handful of rows.
+        // A genuine error in the caller's SQL surfaces identically from the direct
+        // run, so nothing is swallowed.
+        await client.query(`ROLLBACK TO SAVEPOINT ${CURSOR_SAVEPOINT}`);
+        void err;
+        return runExtended(client, sql, params);
+    }
+    const page = await client.query(`FETCH FORWARD ${pageLimit + 1} FROM ${CURSOR_NAME}`);
+    await client.query(`CLOSE ${CURSOR_NAME}`);
+    return page;
+}
+export const executeSqlTool = defineTool('postgres_execute_sql', {
+    title: 'Run arbitrary SQL (reads, and guarded writes)',
+    description: 'The arbitrary-SQL escape hatch — for anything postgres_select cannot express (joins, CTEs, window functions, ' +
+        'set operations, catalog queries). Values belong in params ($1, $2, …), which are always bound, never ' +
+        'interpolated. Multi-statement strings are refused unless allowMultiple is set, and are impossible when params ' +
+        'are supplied. READS run inside a PostgreSQL READ ONLY transaction and return up to `limit` rows; this tool ' +
+        'hands out no cursor, so put LIMIT/OFFSET (with an ORDER BY) in your own SQL to read past the cap. WRITES: a ' +
+        'statement whose leading keyword is INSERT/UPDATE/DELETE/MERGE takes the guarded write path when the profile ' +
+        'sets PG_<ALIAS>_ALLOW_WRITE=true; UPDATE and DELETE must carry a WHERE clause that references a real column. ' +
+        'CREATE/ALTER/DROP/TRUNCATE additionally need PG_<ALIAS>_ALLOW_DDL=true, and GRANT/REVOKE need ' +
+        'PG_<ALIAS>_ALLOW_ADMIN=true. A DDL DRY RUN CANNOT REPORT A ROW COUNT — PostgreSQL returns none for DDL, so a ' +
+        'dry-run "0 rows" on a DROP TABLE means "not applicable", never "nothing will happen"; the dry run proves only ' +
+        'that the statement parses, resolves and is permitted, and says nothing about how many rows it destroys or ' +
+        'what depends on the object. allowMultiple is refused on the write path. No rows are returned by a write, and ' +
+        'raw SQL has no catalog-resolved primary key, so there is no key preview and no keyChecksum — which means a ' +
+        'production profile refuses raw-SQL writes outright (use postgres_update_batch / postgres_delete_batch / ' +
+        'postgres_insert_batch there). A write that no keyword check can see (WITH … INSERT … RETURNING, nextval()) ' +
+        `still runs read-only and is still refused by the server; rewrite it as a plain INSERT. ${CONFIRM_PROTOCOL_DESCRIPTION}`,
+    inputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        const params = args.params ?? [];
+        const statements = planStatements(args.sql, {
+            allowMultiple: args.allowMultiple === true,
+            hasParams: params.length > 0,
+        });
+        // Only tighten: a timeoutMs above the profile's ceiling is capped, never applied.
+        const timeoutMs = args.timeoutMs === undefined ? undefined : Math.min(args.timeoutMs, profile.statementTimeoutMs);
+        const write = planWrite(statements);
+        if (write !== undefined)
+            return await runWrite(profile, write, args, params, timeoutMs);
+        const limits = resolveLimits(profile.maxRows, args.limit === undefined ? {} : { maxRows: args.limit }, process.env);
+        const pageLimit = Math.min(args.limit ?? DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, limits.maxRows);
+        const result = await withTx(profile, async (client) => {
+            // Under `allowMultiple` only the last statement's rows come back, so
+            // the leading ones are run for their effect and only the last one is
+            // worth bounding. Each is its own round trip — never one
+            // simple-query batch.
+            for (const statement of statements.slice(0, -1))
+                await runExtended(client, statement, []);
+            const last = statements[statements.length - 1] ?? '';
+            return fetchBounded(client, last, params, pageLimit);
+        }, {
+            readOnly: true,
+            operation: 'execute_sql',
+            ...(timeoutMs === undefined ? {} : { statementTimeoutMs: timeoutMs }),
+        });
+        const columns = result.fields.map((f) => ({ name: f.name, dataTypeId: f.dataTypeID }));
+        const fetched = result.rows;
+        const hasMore = fetched.length > pageLimit;
+        const rows = hasMore ? fetched.slice(0, pageLimit) : fetched;
+        return formatOutcome({
+            kind: 'rows',
+            columns,
+            rows,
+            rowCount: rows.length,
+            truncated: hasMore,
+            ...(hasMore
+                ? {
+                    rowCapLabel: `row cap ${pageLimit}; this tool hands out no cursor (offset paging over a re-run query can ` +
+                        'overlap or skip rows) — add ORDER BY plus LIMIT/OFFSET to the statement to read the rest',
+                }
+                : {}),
+        }, { limits });
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=execute_sql.js.map

package/dist/tools/execute_sql.js.map

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

package/dist/tools/explain.js

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import { loadProfiles } from '../config/profiles.js';
+import { planStatements } from '../core/classifier.js';
+import { envPrefix, PgMcpError, toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { withTx } from '../db/session.js';
+import { defineTool, profileParam } from './_shared.js';
+/**
+ * `postgres_explain` — EXPLAIN a statement, with format/flag options.
+ *
+ * Unlike `postgres_select`, this takes a raw `statement: string` — a
+ * deliberate, scoped exception to "no arbitrary SQL in Phase 1": EXPLAIN
+ * itself never executes anything (ANALYZE is the one thing that does), and
+ * the phase brief specifically requires explaining an INSERT/UPDATE/DELETE
+ * under ANALYZE, which a structured shape like `postgres_select`'s cannot
+ * express.
+ *
+ * **Multi-statement rejection, the same two layers every other tool has.**
+ * `statement` goes through `core/classifier.ts#planStatements` (one statement,
+ * `;`-lists refused) and the EXPLAIN is issued with an explicit
+ * `queryMode: 'extended'`. Both are load-bearing. The original version of this
+ * comment claimed "a (possibly empty) params array forces the extended query
+ * protocol" — it does not: `pg@8.22`'s `Query.requiresPreparation()` ends
+ * `return this.values.length > 0`, so on the common no-params call this ran in
+ * *simple* mode, where `EXPLAIN … SELECT 1; DROP TABLE t; COMMIT` executed all
+ * three commands — the trailing `COMMIT` escaping both `rollbackAlways` and the
+ * savepoint fence — on a profile holding neither `write` nor `ddl`, and came
+ * back as a `TypeError` about `result.fields` so the damage was invisible in
+ * the response. Measured, not assumed. Do not remove either layer.
+ *
+ * `analyze: true` actually executes `statement` (design.md risk 3), so it is
+ * gated twice:
+ *   1. the profile's `explainAnalyze` capability must be on (env var named in
+ *      the `POLICY_ANALYZE_DENIED` hint) — checked before anything runs;
+ *   2. even when permitted, the whole EXPLAIN runs inside
+ *      `withTx({ rollbackAlways: !confirm })` — a real transaction that is
+ *      rolled back unless the caller passes `confirm: true`, fenced by a
+ *      SAVEPOINT (`db/session.ts#fenceDryRun`) that raises
+ *      `GUARD_DRY_RUN_ESCAPED` if `statement` ends the transaction itself.
+ *
+ * Plain EXPLAIN (no ANALYZE) never executes `statement`, so it just runs
+ * inside `withTx({ readOnly: true })` like every other Phase 1 tool.
+ */
+const FORMATS = ['TEXT', 'JSON', 'XML', 'YAML'];
+const inputSchema = z.object({
+    ...profileParam,
+    statement: z.string().min(1).describe('The SQL statement to explain — SELECT, INSERT, UPDATE, DELETE, etc. Exactly one statement.'),
+    params: z.array(z.unknown()).optional().describe('Bound parameters ($1, $2, ...) referenced by statement.'),
+    analyze: z
+        .boolean()
+        .optional()
+        .describe('EXPLAIN ANALYZE actually executes statement. Requires the profile\'s explainAnalyze capability.'),
+    format: z.enum(FORMATS).optional().describe('Plan output format. Defaults to TEXT.'),
+    costs: z.boolean().optional(),
+    buffers: z.boolean().optional(),
+    verbose: z.boolean().optional(),
+    settings: z.boolean().optional(),
+    confirm: z
+        .boolean()
+        .optional()
+        .describe('Only meaningful with analyze:true. Without it the transaction is always rolled back (dry run) even though ' +
+        'ANALYZE really executed statement. With it, the transaction commits normally.'),
+});
+function explainOptionsClause(args) {
+    const parts = [`ANALYZE ${args.analyze === true}`, `FORMAT ${args.format ?? 'TEXT'}`];
+    if (args.costs !== undefined)
+        parts.push(`COSTS ${args.costs}`);
+    if (args.buffers !== undefined)
+        parts.push(`BUFFERS ${args.buffers}`);
+    if (args.verbose !== undefined)
+        parts.push(`VERBOSE ${args.verbose}`);
+    if (args.settings !== undefined)
+        parts.push(`SETTINGS ${args.settings}`);
+    return parts.join(', ');
+}
+export const explainTool = defineTool('postgres_explain', {
+    title: 'Explain a PostgreSQL statement',
+    description: 'EXPLAIN a statement (any SQL — SELECT/INSERT/UPDATE/DELETE/etc.) with format (TEXT/JSON/XML/YAML) and flag ' +
+        '(costs, buffers, verbose, settings) options. analyze:true actually executes the statement to get real ' +
+        'timings — requires the profile\'s explainAnalyze capability, and is rolled back unless confirm:true is also ' +
+        'passed. Without analyze, nothing is ever executed.',
+    inputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        const analyze = args.analyze === true;
+        if (analyze && !profile.capabilities.explainAnalyze) {
+            throw new PgMcpError({
+                code: 'POLICY_ANALYZE_DENIED',
+                message: `profile "${profile.alias}" does not allow EXPLAIN ANALYZE`,
+                hint: `set ${envPrefix(profile.alias)}_ALLOW_EXPLAIN_ANALYZE=true for this profile and re-run`,
+                details: { profile: profile.alias },
+            });
+        }
+        const params = args.params ?? [];
+        // Exactly one statement, refused before any round trip. `allowMultiple` is
+        // not offered here at all: an EXPLAIN of a `;`-list is meaningless, and it
+        // was the way a `COMMIT` got past the dry-run fence.
+        const [statement = ''] = planStatements(args.statement, {
+            allowMultiple: false,
+            hasParams: params.length > 0,
+        });
+        const sql = `EXPLAIN (${explainOptionsClause(args)}) ${statement}`;
+        const format = args.format ?? 'TEXT';
+        const plan = await withTx(profile, async (client) => {
+            const result = await client.query({ text: sql, values: [...params], queryMode: 'extended' });
+            // `result.fields?.` and not `result.fields[0]?.`: a shape surprise
+            // (an array of results, which is what a multi-statement string used to
+            // produce here) must not surface as a TypeError blamed on the caller.
+            const col = result.fields?.[0]?.name;
+            if (col === undefined)
+                return null;
+            if (format === 'JSON')
+                return result.rows[0]?.[col] ?? null;
+            return result.rows.map((r) => String(r[col])).join('\n');
+        }, analyze ? { rollbackAlways: args.confirm !== true, operation: 'explain' } : { readOnly: true, operation: 'explain' });
+        return formatOutcome({
+            kind: 'report',
+            data: {
+                profile: profile.alias,
+                analyze,
+                format,
+                rolledBack: analyze ? args.confirm !== true : true,
+                plan,
+            },
+        });
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=explain.js.map

package/dist/tools/explain.js.map

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