pg-admin-mcp 0.0.0-stage → 0.1.0

package/dist/tools/copy.js

@@ -0,0 +1,355 @@
+import { createHash } from 'node:crypto';
+import process from 'node:process';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { from as copyFrom, to as copyTo } from 'pg-copy-streams';
+import { z } from 'zod';
+import { readInt } from '../config/env.js';
+import { loadProfiles } from '../config/profiles.js';
+import { toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { CONFIRM_PROTOCOL_DESCRIPTION, runGuardedMutation } from '../core/guards.js';
+import { columnIdentFromCatalog, resolveColumn, resolveRelation } from '../core/identifiers.js';
+import { fileTooLarge, renderHostPath, resolveWorkspaceFileForRead, resolveWorkspacePath, writeFileAtomic, } from '../core/paths.js';
+import { requireCapability } from '../core/policy.js';
+import { getColumns } from '../db/catalog.js';
+import { withSession, withTx } from '../db/session.js';
+import { confirmFragment, toExpectToken } from './_batch_shared.js';
+import { defineTool, profileParam } from './_shared.js';
+/**
+ * `postgres_copy` — a whole-table (or column-subset) transfer between a table
+ * and a file through PostgreSQL's own COPY protocol, in both directions:
+ * `direction: 'export'` (`COPY … TO STDOUT` -> file, the default) and
+ * `direction: 'import'` (file -> `COPY … FROM STDIN`).
+ *
+ * **Why this exists next to `postgres_export`.** `postgres_export` builds its
+ * own CSV/JSON/JSONL text in JS (`tools/_export_format.ts`) so it can serve an
+ * arbitrary `SELECT`. This tool instead hands the whole job to PostgreSQL's
+ * own COPY protocol — no per-cell JS formatting, no server-side cursor/FETCH
+ * loop, just a straight byte pipe from the server to disk. That is faster for
+ * the case it covers (a full or column-subset table dump) but it is also why
+ * this tool's `source` is deliberately narrower than `postgres_export`'s:
+ *
+ * - **No raw SQL source.** `pg-copy-streams`'s `CopyStreamQuery.submit`
+ *   issues `connection.query(this.text)` — PostgreSQL's *simple* query
+ *   protocol, which has no bound-parameter support at all (confirmed by
+ *   reading `copy-to.js`). A raw-SQL variant here would force either string-
+ *   interpolating caller-supplied values into the COPY statement (a real SQL
+ *   injection surface) or silently ignoring `params` — neither is acceptable,
+ *   so it is not offered. `schema`/`table`/`columns` are the only inputs, and
+ *   every one of them is resolved through `core/identifiers.ts` against
+ *   `pg_catalog` before it reaches SQL text, exactly like `postgres_select`.
+ * - **No `where`.** Same reasoning again: a filter predicate is a value, and
+ *   this statement text has nowhere safe to bind one.
+ *
+ * **Never `process.stdout.write`.** `core/stdout-guard.ts` patches
+ * `console.*` so an accidental log call cannot corrupt the JSON-RPC frame
+ * stream on stdout — but it does **not**, and cannot, patch
+ * `process.stdout.write` itself (that guard would also break the transport).
+ * A `COPY` stream piped to `process.stdout` would therefore be a real hazard,
+ * not a theoretical one. This tool's only destination is ever the file handle
+ * `core/paths.ts#writeFileAtomic` opens.
+ *
+ * **Backpressure.** `client.query(copyTo(sql))` returns a `Readable` driven
+ * directly off the wire protocol; `node:stream/promises#pipeline` connects it
+ * to the destination file with no manual `.on('data', …)` loop, so the server
+ * only sends more `CopyData` messages once the file write has drained —
+ * exactly the same discipline `postgres_export` gets from its cursor +
+ * `Readable.from` chain, here for free from the wire-level stream itself.
+ *
+ * **`timeoutMs`.** Same raise-then-clamp rule as `postgres_export`
+ * (`Profile.exportTimeoutMaxMs`), but with a different practical meaning: a
+ * `COPY … TO STDOUT` is one PostgreSQL statement start to finish, so
+ * `statement_timeout` here bounds the *entire* copy's wall-clock time — unlike
+ * `postgres_export`, where each `FETCH` is its own statement (see that file's
+ * doc comment).
+ *
+ * ## The import direction, and the one deliberate deviation
+ *
+ * `COPY … FROM` is the fastest way in this server to overwrite the contents of
+ * a table, so it gets the same two-call dry-run/confirm protocol as every other
+ * write — but it **cannot** get it the way the other write tools do.
+ * `core/guards.ts#runGuardedMutation` wraps the caller's statement as
+ * `WITH pg_admin_mcp_target AS (<sql> RETURNING pk…)`, and `COPY` is a
+ * wire-protocol command with no `RETURNING`: it cannot appear inside a CTE at
+ * all. `tools/insert_batch.ts` hit exactly this wall and answered it by not
+ * using COPY (it switches to `jsonb_to_recordset` above its bulk threshold).
+ *
+ * **That answer is not available here, and reusing it would delete the tool.**
+ * The whole reason `postgres_copy` exists next to `postgres_insert_batch` is
+ * that PostgreSQL parses the file: `format: text | csv | binary`, embedded
+ * newlines, quoting, encodings, `NULL` sentinels. Routing the import through
+ * `jsonb_to_recordset` would mean writing a COPY-format parser in JS — the one
+ * thing this tool exists to avoid — would break the byte-for-byte round trip
+ * with the export direction, would buffer the whole file as a JSON string, and
+ * is flatly impossible for `format: binary`.
+ *
+ * So this is the documented non-CTE path — **and it is still the same guard**,
+ * not a second one. It goes through `runGuardedMutation` via
+ * `core/guards.ts#GuardedExecutor`, which replaces only "how the statement is
+ * issued". Capability check, confirm policy, `sqlHash`, the comparison *inside
+ * the committing transaction*, and the `rollbackAlways` savepoint fence are all
+ * the shared implementation. Two consequences, both deliberate:
+ *
+ * - **`keyChecksum` is the SHA-256 of the input FILE**, computed while the
+ *   bytes stream past on both calls, not a checksum over affected primary keys.
+ *   For a bulk load that is the stronger of the two: a COPY has no `RETURNING`,
+ *   and a checksum over server-generated keys would differ on every confirm
+ *   anyway because a rolled-back dry run still advances the sequence
+ *   (`tools/insert_batch.ts`). It means a `GUARD_ROW_DRIFT` naming a key
+ *   checksum here reads "the file changed between the two calls".
+ * - **The file is streamed twice** — once for the dry run, once for the
+ *   confirm. That is the price of previewing a load without committing it.
+ *
+ * **Input size.** `PG_MCP_MAX_IMPORT_BYTES` (default 512 MiB) is checked with
+ * `stat()` *before* the file is opened, and re-counted as the bytes actually
+ * flow so a file that grows between the two cannot slip past. It is not a
+ * memory bound — nothing here buffers the file — it bounds how much
+ * operator-supplied input this server will feed a table in one call, and it is
+ * sized so a load can still finish twice inside `exportTimeoutMaxMs`.
+ *
+ * **Symlinked input.** `core/paths.ts#resolveWorkspacePath` realpaths the
+ * *parent* directory only, because an export destination need not exist yet.
+ * The export direction closes the remaining gap with `writeFileAtomic`'s `wx`
+ * flag; an import reads, so it realpaths the file itself and puts the result
+ * back through the allow-list. Without that, a symlink planted inside an
+ * allowed directory would read whatever it points at. And because every one of
+ * those checks is on a *name*, `resolveWorkspaceFileForRead` opens the file once and
+ * the COPY streams from that **file handle** — closing the window in which the
+ * final path component could be swapped for a symlink after the checks and
+ * before the read.
+ */
+const COPY_FORMATS = ['csv', 'text', 'binary'];
+const inputSchema = z.object({
+    ...profileParam,
+    direction: z
+        .enum(['export', 'import'])
+        .optional()
+        .describe('export (default) = table -> file via COPY … TO STDOUT. import = file -> table via COPY … FROM STDIN, which needs PG_<ALIAS>_ALLOW_WRITE and the confirm protocol below.'),
+    schema: z.string().min(1),
+    table: z.string().min(1),
+    columns: z.array(z.string().min(1)).min(1).optional().describe('Columns to copy, in this order. Omit for every column, in ordinal order.'),
+    path: z.string().min(1).describe('File path — destination when exporting, source when importing. Relative paths resolve against the profile\'s first allowed directory; absolute paths must still land inside an allowed directory.'),
+    format: z.enum(COPY_FORMATS).optional().describe('PostgreSQL COPY format — defaults to csv.'),
+    overwrite: z.boolean().optional().describe('Export only: required (true) to replace an existing file at path. Defaults to false.'),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Per-call statement timeout, bounding the whole COPY — may raise the profile\'s default, clamped to PG_<ALIAS>_EXPORT_TIMEOUT_MAX_MS.'),
+    csv: z
+        .object({
+        delimiter: z.string().length(1).optional(),
+        header: z.boolean().optional(),
+        nullValue: z.string().optional(),
+    })
+        .optional()
+        .describe('Only applies when format is csv (the default) — passed straight through to PostgreSQL\'s own COPY … WITH options. When importing, these must describe the file you are reading.'),
+    ...confirmFragment,
+});
+/** PostgreSQL string-literal quoting for a COPY `WITH (...)` option value — this statement has no bound parameters at all (see the file header), so every option value is embedded as SQL text and must be escaped here. */
+function sqlLiteral(text) {
+    return `'${text.replace(/'/g, "''")}'`;
+}
+function copyWithOptions(format, csv) {
+    const parts = [`FORMAT ${format}`];
+    if (format === 'csv') {
+        if (csv?.delimiter !== undefined)
+            parts.push(`DELIMITER ${sqlLiteral(csv.delimiter)}`);
+        if (csv?.header !== undefined)
+            parts.push(`HEADER ${csv.header ? 'true' : 'false'}`);
+        if (csv?.nullValue !== undefined)
+            parts.push(`NULL ${sqlLiteral(csv.nullValue)}`);
+    }
+    return `(${parts.join(', ')})`;
+}
+/**
+ * Sized so a load still finishes twice (dry run + confirm) inside the default
+ * `exportTimeoutMaxMs`, and small enough that a mistyped path cannot feed a
+ * multi-gigabyte blob into a table. **Not a memory bound** — nothing here
+ * buffers the file; it bounds blast radius and wall clock.
+ */
+const DEFAULT_MAX_IMPORT_BYTES = 512 * 1024 * 1024;
+function maxImportBytes() {
+    return readInt(process.env, 'PG_MCP_MAX_IMPORT_BYTES', { default: DEFAULT_MAX_IMPORT_BYTES, min: 1 });
+}
+/**
+ * The wording half of `core/paths.ts#resolveWorkspaceFileForRead`, which now
+ * owns the read-side path policy this file used to carry its own copy of: the
+ * double resolve that refuses a symlink escape, the open-once + `ino` check
+ * that refuses a post-check swap, and the size cap enforced from the fstat
+ * before a byte is read. Three copies of that policy existed before Phase 6
+ * (here, `tools/_snapshot_io.ts`, and `postgres_restore` would have been a
+ * fourth); one copy is the point, so only the sentences a human reads are
+ * still tool-specific.
+ */
+function importReadOptions(cap) {
+    return {
+        maxBytes: cap,
+        limitLabel: 'import',
+        limitHint: `split the file, or raise PG_MCP_MAX_IMPORT_BYTES (currently ${cap}) and restart the server`,
+        missingHint: 'an import reads an existing file — check the path, and that it is inside an allowed directory',
+        notFileHint: 'point path at a file produced by a COPY export (or any file in the same format), not a directory or device',
+    };
+}
+/**
+ * The `COPY … FROM STDIN` half of the guard, as a
+ * `core/guards.ts#GuardedExecutor` — everything else about the two-call
+ * protocol is `runGuardedMutation`'s.
+ */
+function importExecutor(sql, source, cap) {
+    return {
+        providesKeyChecksum: true,
+        run: async (client) => {
+            const digest = createHash('sha256');
+            let seen = 0;
+            // Hashes and meters in the same pass the bytes already make, so the
+            // content checksum costs no extra read — and a file that grew after
+            // `stat()` still cannot exceed the cap.
+            const meter = new Transform({
+                transform(chunk, _encoding, callback) {
+                    seen += chunk.length;
+                    if (seen > cap) {
+                        callback(fileTooLarge(source.path, seen, importReadOptions(cap)));
+                        return;
+                    }
+                    digest.update(chunk);
+                    callback(null, chunk);
+                },
+            });
+            const dest = client.query(copyFrom(sql));
+            // A mid-COPY failure reaches us through `pipeline`'s rejection. The copy
+            // stream can then emit a SECOND error while being destroyed — it drops
+            // its own connection reference when it handles the first — and with no
+            // listener Node turns that into an uncaughtException that kills the
+            // server. Same absorber, same reason, as `core/paths.ts#writeFileAtomic`.
+            dest.on('error', () => undefined);
+            // `pipeline`, never a manual 'data' loop: the file is only read as fast
+            // as the COPY stream drains it onto the wire. The stream comes off the fd
+            // `resolveWorkspaceFileForRead` already validated — not off the path again, which
+            // could by now be a symlink to something else entirely. `run` is called
+            // exactly once per tool call (a dry run OR a confirm), so reading the fd
+            // once is enough; the second stream of the file is the second MCP call,
+            // with its own fd and its own checks.
+            await pipeline(source.handle.createReadStream({ autoClose: false }), meter, dest);
+            // COPY's own `COPY n` command tag — PostgreSQL's count of the rows it
+            // actually wrote, not our count of the lines we sent.
+            return { rowCount: dest.rowCount, keyChecksum: digest.digest('hex') };
+        },
+    };
+}
+function importNote(bytes) {
+    return (`The row count above is PostgreSQL's own COPY command tag — the rows it really read from the file and wrote, ` +
+        'inside a transaction that was then rolled back. There is no key preview because COPY has no RETURNING. ' +
+        `expect.keyChecksum is the SHA-256 of the ${bytes}-byte input file, recomputed while the file streams again on ` +
+        'the confirming call and compared inside the committing transaction — so if the file changes between the two ' +
+        'calls the load is refused rather than applied. Confirming re-reads and re-streams the same file; COPY appends, ' +
+        'it does not replace, so run this once.');
+}
+async function runImport(profile, args, format, timeoutMs) {
+    // Cheapest refusal first, and the only one that must precede any file I/O: a
+    // profile that cannot write never gets this server to open its input.
+    requireCapability('write', profile);
+    const cap = maxImportBytes();
+    const source = await resolveWorkspaceFileForRead(args.path, profile.allowedDirs, importReadOptions(cap));
+    try {
+        return await runImportGuarded(profile, args, format, timeoutMs, source, cap);
+    }
+    finally {
+        // Opened by `resolveWorkspaceFileForRead`; closed on every path, including a refusal
+        // from the guard that never reached the executor.
+        await source.handle.close();
+    }
+}
+async function runImportGuarded(profile, args, format, timeoutMs, source, cap) {
+    // Resolved BEFORE runGuardedMutation opens its transaction. `resolveRelation`
+    // and `withSession` each take their own pool checkout, and a second checkout
+    // acquired while the first is held is the Phase 2 deadlock — see the export
+    // branch below for the full note.
+    const rel = await resolveRelation(profile, args.schema, args.table);
+    const columnIdents = args.columns === undefined
+        ? []
+        : await withSession(profile, async (client) => {
+            const knownColumns = (await getColumns(client, rel)).map((c) => c.name);
+            return (args.columns ?? []).map((name) => resolveColumn(args.schema, args.table, name, knownColumns));
+        }, { operation: 'copy_import' });
+    const columnList = columnIdents.length === 0 ? '' : ` (${columnIdents.join(', ')})`;
+    const sql = `COPY ${rel.schema}.${rel.name}${columnList} FROM STDIN WITH ${copyWithOptions(format, args.csv)}`;
+    const outcome = await runGuardedMutation({
+        profile,
+        capability: 'write',
+        operation: 'copy_import',
+        // Hashed, not executed — the executor issues the statement. `sqlHash` must
+        // therefore change when the statement, the target, the format options or
+        // the source path changes; the file's *contents* are pinned separately by
+        // keyChecksum, inside the committing transaction.
+        sql,
+        params: [source.path],
+        keyColumns: [],
+        executor: importExecutor(sql, source, cap),
+        confirm: args.confirm,
+        expect: toExpectToken(args.expect),
+        allowRowDrift: args.allowRowDrift,
+        statementTimeoutMs: timeoutMs,
+    });
+    if (outcome.kind !== 'dryRun')
+        return formatOutcome(outcome);
+    return formatOutcome({ ...outcome, note: importNote(source.bytes) });
+}
+export const copyTool = defineTool('postgres_copy', {
+    title: 'COPY a table to or from a file',
+    description: 'High-throughput whole-table (or column-subset) transfer through PostgreSQL\'s own COPY protocol, streamed ' +
+        'straight to or from a file — no where filter, no raw SQL source (see postgres_export for those). path ' +
+        'resolves against the profile\'s allowed directories. direction:"export" (default) writes COPY … TO STDOUT to ' +
+        'the file. direction:"import" reads the file into the table with COPY … FROM STDIN: it needs ' +
+        'PG_<ALIAS>_ALLOW_WRITE=true, refuses a source file larger than PG_MCP_MAX_IMPORT_BYTES (default 512 MiB) ' +
+        'before opening it, and goes through the dry-run/confirm protocol below. Two things are specific to import: ' +
+        'the row count is COPY\'s own command tag, and `expect.keyChecksum` is the SHA-256 of the INPUT FILE rather ' +
+        'than of affected primary keys (COPY has no RETURNING) — so a key-checksum mismatch on the confirming call ' +
+        'means the file changed between the two calls. The file is streamed once for the dry run and once for the ' +
+        `confirm. COPY appends rows; it never replaces them. ${CONFIRM_PROTOCOL_DESCRIPTION}`,
+    inputSchema,
+    // Same annotation as `postgres_export`, deliberately: both tools write a
+    // file and both replace an existing one under `overwrite: true`, so both
+    // are destructive and neither is idempotent (a second identical call either
+    // refuses, or replaces a file whose contents may differ because the table
+    // moved underneath it).
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        const timeoutMs = Math.min(args.timeoutMs ?? profile.statementTimeoutMs, profile.exportTimeoutMaxMs);
+        const format = args.format ?? 'csv';
+        if (args.direction === 'import')
+            return await runImport(profile, args, format, timeoutMs);
+        const resolvedPath = await resolveWorkspacePath(args.path, profile.allowedDirs);
+        // Resolved BEFORE withTx takes a client: resolveRelation opens its own
+        // withSession, and a second pool checkout acquired while the first is
+        // still held is a deadlock — at poolMax: 1 it can never be satisfied at
+        // all, and at any poolMax that many concurrent copies wedge the profile
+        // until PG_MCP_CONNECT_TIMEOUT_MS fires. getColumns takes a client as an
+        // argument, so it is the only catalog step that may stay inside.
+        // `tools/select.ts` resolves before its own withTx for the same reason.
+        const rel = await resolveRelation(profile, args.schema, args.table);
+        const bytes = await withTx(profile, async (client) => {
+            const columnInfos = await getColumns(client, rel);
+            const knownColumns = columnInfos.map((c) => c.name);
+            const selectIdents = args.columns === undefined
+                ? columnInfos.map((c) => columnIdentFromCatalog(c.name))
+                : args.columns.map((name) => resolveColumn(args.schema, args.table, name, knownColumns));
+            const sql = `COPY (SELECT ${selectIdents.join(', ')} FROM ${rel.schema}.${rel.name}) TO STDOUT WITH ${copyWithOptions(format, args.csv)}`;
+            return writeFileAtomic(resolvedPath, 
+            // Piped directly to the destination file handle — never to
+            // process.stdout. See the file header for why that guard matters here.
+            (dest) => pipeline(client.query(copyTo(sql)), dest), { overwrite: args.overwrite === true });
+        }, { readOnly: true, operation: 'copy', statementTimeoutMs: timeoutMs });
+        const hostPath = renderHostPath(resolvedPath, profile.allowedDirs);
+        return formatOutcome({ kind: 'file', path: resolvedPath, bytes, ...(hostPath === undefined ? {} : { hostPath }) });
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=copy.js.map

package/dist/tools/copy.js.map

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

package/dist/tools/delete_batch.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { loadProfiles } from '../config/profiles.js';
+import { toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { assertStructuredWhere, CONFIRM_PROTOCOL_DESCRIPTION, runGuardedMutation } from '../core/guards.js';
+import { resolveColumn, resolveRelation } from '../core/identifiers.js';
+import { getColumns, getPrimaryKey } from '../db/catalog.js';
+import { withSession } from '../db/session.js';
+import { buildWhereClause, confirmFragment, toExpectToken } from './_batch_shared.js';
+import { wherePredicate } from './select.js';
+import { defineTool, profileParam } from './_shared.js';
+/**
+ * `postgres_delete_batch` — filtered bulk DELETE through
+ * `core/guards.ts#runGuardedMutation`. `where` reuses `tools/select.ts`'s
+ * structured predicate shape and is mandatory: `assertStructuredWhere` runs
+ * BEFORE `resolveRelation`, so an empty/omitted filter is refused before any
+ * SQL — not even an identifier lookup — reaches the server. See
+ * `update_batch`'s header for why the WHERE guard is "cheap and easily
+ * fooled" and the dry run's row count is the real guard.
+ */
+const inputSchema = z.object({
+    ...profileParam,
+    schema: z.string().min(1).describe('Schema name, e.g. "app".'),
+    table: z.string().min(1).describe('Table name within the schema.'),
+    where: z
+        .array(wherePredicate)
+        .optional()
+        .describe('Filter predicates, ANDed together — required. Empty/omitted is refused before any SQL reaches the server.'),
+    ...confirmFragment,
+});
+export const deleteBatchTool = defineTool('postgres_delete_batch', {
+    title: 'Bulk DELETE rows from a PostgreSQL table',
+    description: 'Filtered bulk DELETE. `where` is a structured, parameterized filter (same shape as postgres_select) and is ' +
+        'mandatory — an empty filter is refused before any SQL reaches the server; to empty a table deliberately, use ' +
+        `postgres_execute_sql with TRUNCATE on a profile that allows DDL. ${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);
+        // Cheap guard first: fails before any identifier lookup, let alone any
+        // mutation SQL, reaches the server.
+        const ctx = { profile: profile.alias, operation: 'delete_batch', target: `${args.schema}.${args.table}` };
+        assertStructuredWhere((args.where ?? []).length, ctx);
+        const rel = await resolveRelation(profile, args.schema, args.table);
+        const { knownColumns, pkIdents } = await withSession(profile, async (client) => {
+            const columnInfos = await getColumns(client, rel);
+            const knownColumns = columnInfos.map((c) => c.name);
+            const primaryKey = await getPrimaryKey(client, rel);
+            const pkIdents = (primaryKey?.columns ?? []).map((name) => resolveColumn(args.schema, args.table, name, knownColumns));
+            return { knownColumns, pkIdents };
+        }, { operation: 'delete_batch' });
+        const whereResult = buildWhereClause(args.where ?? [], args.schema, args.table, knownColumns, 1);
+        const sql = `DELETE FROM ${rel.schema}.${rel.name} WHERE ${whereResult.clause}`;
+        const outcome = await runGuardedMutation({
+            profile,
+            capability: 'write',
+            operation: 'delete_batch',
+            sql,
+            params: whereResult.params,
+            keyColumns: pkIdents,
+            confirm: args.confirm,
+            expect: toExpectToken(args.expect),
+            allowRowDrift: args.allowRowDrift,
+        });
+        return formatOutcome(outcome);
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=delete_batch.js.map

package/dist/tools/delete_batch.js.map

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

package/dist/tools/describe_object.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { loadProfiles } from '../config/profiles.js';
+import { PgMcpError, toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { assertSchemaAllowed, resolveRelation } from '../core/identifiers.js';
+import { getEnumTypeDetail, getFunctionDetails, getSequenceDetail } from '../db/catalog.js';
+import { withSession } from '../db/session.js';
+import { buildRelationDetail } from './_relation_detail.js';
+import { defineTool, profileParam } from './_shared.js';
+/**
+ * `postgres_describe_object` — full detail for one object.
+ *
+ * `resolveRelation` only covers relkinds `r,p,v,m,f` (table/partitioned
+ * table/view/materialized view/foreign table) — sequences (relkind `S`),
+ * functions (`pg_proc`), and enum types (`pg_type`) are not relations at all,
+ * so there is nothing for it to resolve. The strategy: try `resolveRelation`
+ * first (it already does schema-scope enforcement, oid lookup, and near-miss
+ * suggestions); if it reports the object unknown, fall back to the three
+ * bound-parameter lookups for the other kinds `db/catalog.ts` exposes. If
+ * none of those match either, the original `resolveRelation` error — with its
+ * suggestions — is what the caller sees.
+ *
+ * `assertSchemaAllowed` runs explicitly up front rather than relying solely
+ * on `resolveRelation`'s own internal check: `resolveRelation` throws the
+ * *same* `IDENTIFIER_UNKNOWN` code for "schema not in scope" as it does for
+ * "relation not found in an in-scope schema", so without this explicit gate
+ * the sequence/function/enum fallback below would run on a schema the
+ * profile is not allowed to see.
+ */
+const inputSchema = z.object({
+    ...profileParam,
+    schema: z.string().min(1).describe('Schema name, e.g. "app".'),
+    name: z.string().min(1).describe('Object name within the schema — a table, view, materialized view, sequence, function, or enum type.'),
+});
+export const describeObjectTool = defineTool('postgres_describe_object', {
+    title: 'Describe a PostgreSQL object',
+    description: 'Full detail for one object. For a table/partitioned table: columns, primary key, foreign keys in both ' +
+        'directions (outbound and what references it), unique/check constraints, indexes (with partial-index ' +
+        'predicates), triggers, row-level security, permissions, and comments. A view/materialized view returns its ' +
+        'definition; a sequence its parameters and current value; a function its signature and body (all overloads); ' +
+        'an enum its labels. An unknown object returns IDENTIFIER_UNKNOWN with near-miss suggestions.',
+    inputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        assertSchemaAllowed(profile, args.schema);
+        let relationError;
+        try {
+            const rel = await resolveRelation(profile, args.schema, args.name);
+            const detail = await withSession(profile, (client) => buildRelationDetail(client, rel), { operation: 'describe_object' });
+            return formatOutcome({ kind: 'report', data: { schema: args.schema, name: args.name, kind: rel.kind, detail } });
+        }
+        catch (err) {
+            if (err instanceof PgMcpError && err.code === 'IDENTIFIER_UNKNOWN') {
+                relationError = err;
+            }
+            else {
+                throw err;
+            }
+        }
+        const fallback = await withSession(profile, async (client) => {
+            const sequence = await getSequenceDetail(client, args.schema, args.name);
+            if (sequence !== null)
+                return { kind: 'sequence', detail: sequence };
+            const functions = await getFunctionDetails(client, args.schema, args.name);
+            if (functions.length > 0)
+                return { kind: 'function', detail: functions };
+            const enumType = await getEnumTypeDetail(client, args.schema, args.name);
+            if (enumType !== null)
+                return { kind: 'enum', detail: enumType };
+            return null;
+        }, { operation: 'describe_object' });
+        if (fallback === null) {
+            // relationError is always set by this point: the only way past the
+            // try/catch above without an early return is the IDENTIFIER_UNKNOWN
+            // catch branch running and assigning it.
+            throw relationError ?? new Error(`"${args.schema}.${args.name}" could not be resolved`);
+        }
+        return formatOutcome({ kind: 'report', data: { schema: args.schema, name: args.name, kind: fallback.kind, detail: fallback.detail } });
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=describe_object.js.map

package/dist/tools/describe_object.js.map

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