pg-admin-mcp 0.0.0-stage → 0.1.0

package/dist/tools/restore.js

@@ -0,0 +1,301 @@
+import process from 'node:process';
+import { z } from 'zod';
+import { readInt } from '../config/env.js';
+import { loadProfiles } from '../config/profiles.js';
+import { PgMcpError, toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { resolveWorkspaceFileForRead } from '../core/paths.js';
+import { capabilityEnvVar, requireCapability } from '../core/policy.js';
+import { assertArchiveReadable, assertClientCoversServer, connectionArgs, parseMajor, requireBinary, runBinary, } from '../runtime/binaries.js';
+import { readSidecar, serverVersionOf, sidecarPathFor } from './_archive_meta.js';
+import { defineTool, profileParam } from './_shared.js';
+/**
+ * `postgres_restore` — **the most destructive tool in this server.**
+ * `pg_restore` can drop and recreate every object in the target database, and
+ * with `clean: true` it does exactly that. There is no undo.
+ *
+ * ## It does NOT compose `runGuardedMutation`, and here is why
+ *
+ * Stated plainly because the alternative — a tool that *looks* guarded and is
+ * not — is worse than an unguarded one. Every other mutating tool in this
+ * server goes through `core/guards.ts#runGuardedMutation`, which previews a
+ * change by running it inside a transaction this server opened and then rolling
+ * back, and confirms it by re-running it and comparing a row count and a key
+ * checksum *inside the committing transaction*. Not one part of that is
+ * available here:
+ *
+ * - **There is no transaction we control.** `pg_restore` is a separate process
+ *   that opens its own connections. `withTx`'s `BEGIN`/`ROLLBACK` are on a
+ *   different backend entirely and could not roll back a single thing the child
+ *   did. `pg_restore --single-transaction` is the child's own transaction,
+ *   committed by the child before it exits — we cannot inspect it, let alone
+ *   abort it.
+ * - **There is no row count.** `pg_restore` reports nothing comparable; a
+ *   restore is a stream of DDL and COPY, not one statement with a result.
+ * - **There is no `sqlHash`.** The unit of work is an archive file, not SQL we
+ *   authored, so there is no normalized statement to hash and nothing for
+ *   `expect` to pin.
+ *
+ * So: same shape as `tools/admin/maintenance.ts`'s VACUUM — outside the guard,
+ * because the guard is *not possible* here, not because it was inconvenient.
+ * What replaces it, and what the tool actually enforces:
+ *
+ * 1. **`mode: "inspect"` is the dry run.** `pg_restore --list` reads the
+ *    archive's table of contents and touches no database at all — it is not a
+ *    weakened preview, it is a complete and truthful account of what the
+ *    archive contains. It is also the default: an omitted `mode` inspects.
+ * 2. **`mode: "restore"` requires `confirm: true`**, in every environment
+ *    class, with no `expect` token — because there is no honest token to
+ *    issue. A restore without `confirm` changes nothing and returns the
+ *    inspection instead.
+ * 3. **The `restore` capability** (`PG_<ALIAS>_ALLOW_RESTORE`) is off by
+ *    default, like every other write capability.
+ *
+ * ## The archive is untrusted operator input
+ *
+ * It is a file path handed in by whoever is driving the agent, so it goes
+ * through `core/paths.ts#resolveWorkspaceFileForRead` — the same one policy
+ * `postgres_copy`'s import direction and the snapshot reader use: allow-list
+ * containment, a second resolve after `realpath` so a symlink cannot lead out
+ * of the workspace, open-once plus an `ino` check so the file cannot be swapped
+ * after it was approved, and a size cap (`PG_MCP_MAX_ARCHIVE_BYTES`) enforced
+ * from the open handle's `fstat`.
+ *
+ * *Documented residual gap:* `pg_restore` takes a **path**, not a file
+ * descriptor, so it re-opens the file by name. This module holds its own handle
+ * open for the whole restore, which keeps the approved inode alive, but a
+ * rename of the path between the check and the child's open would still send
+ * `pg_restore` at a different file. Closing that completely would mean piping
+ * the archive to the child's stdin, which `pg_restore` supports only for
+ * single-file custom archives and only without parallelism. The exposure is an
+ * operator racing their own workspace; the containment check is what stops a
+ * *planted* symlink, and that one is closed.
+ *
+ * ## Forward-only archives (design.md risk 10)
+ *
+ * `pg_dump 17` dumps a 16 server fine, but a custom-format archive written by
+ * 17 can never be read by `pg_restore 16`. The archive major comes from the
+ * sidecar `postgres_backup` wrote (checked before anything is spawned) or, for
+ * a hand-made archive, from the `Dumped by pg_dump version:` line in
+ * `pg_restore --list`'s own header. Either way the refusal names the image tag
+ * that *can* read it, instead of surfacing `unsupported version (1.16) in file
+ * header`.
+ */
+/**
+ * 20 GiB. Unlike `PG_MCP_MAX_IMPORT_BYTES` this is not a throughput bound —
+ * nothing here reads the archive into this process at all, `pg_restore` does —
+ * it is a sanity bound on what an operator can point this tool at, and archives
+ * are legitimately much larger than a CSV import.
+ */
+const DEFAULT_MAX_ARCHIVE_BYTES = 20 * 1024 * 1024 * 1024;
+function maxArchiveBytes() {
+    return readInt(process.env, 'PG_MCP_MAX_ARCHIVE_BYTES', { default: DEFAULT_MAX_ARCHIVE_BYTES, min: 1 });
+}
+const inputSchema = z.object({
+    ...profileParam,
+    path: z
+        .string()
+        .min(1)
+        .describe('Archive written by pg_dump in custom or tar format. Relative paths resolve against the profile\'s first allowed directory; absolute paths must still land inside one.'),
+    mode: z
+        .enum(['inspect', 'restore'])
+        .optional()
+        .describe('inspect (default) — list the archive contents, touching no database. restore — apply it. THIS OVERWRITES DATA.'),
+    confirm: z
+        .boolean()
+        .optional()
+        .describe('Required (true) for mode:"restore". There is no dry-run/expect token here: pg_restore is a separate process with no transaction this server can roll back. Use mode:"inspect" to see what the archive holds first.'),
+    clean: z
+        .boolean()
+        .optional()
+        .describe('pg_restore --clean: DROP every object before recreating it. THE MOST DESTRUCTIVE OPTION IN THIS SERVER — existing data in the target objects is gone.'),
+    noOwner: z.boolean().optional().describe('Ignore ownership commands in the archive; objects end up owned by the connecting role.'),
+    singleTransaction: z
+        .boolean()
+        .optional()
+        .describe('pg_restore --single-transaction: all-or-nothing inside the CHILD process\'s own transaction. It reduces the blast radius of a partial failure; it is not a dry run and this server cannot roll it back.'),
+    schemas: z.array(z.string().min(1)).optional().describe('Restore only these schemas from the archive (pg_restore --schema).'),
+    tables: z.array(z.string().min(1)).optional().describe('Restore only these tables from the archive (pg_restore --table).'),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Wall-clock ceiling for the pg_restore child, clamped to PG_<ALIAS>_BACKUP_TIMEOUT_MAX_MS (1 h by default).'),
+});
+/** `;     Dumped by pg_dump version: 17.5` — the archive's own header, the fallback when there is no sidecar. */
+export function archiveMajorFromListing(listing) {
+    const line = /Dumped by pg_dump version:\s*(\S+)/.exec(listing);
+    return line?.[1] === undefined ? undefined : parseMajor(line[1]);
+}
+/**
+ * `pg_restore`'s own refusal when the archive is too new for it. Recognized so
+ * the operator gets the image-tag remedy even for a hand-made archive with no
+ * sidecar, where the major could not be read up front — the failure is the
+ * only place the truth surfaces.
+ */
+function isUnsupportedVersion(err) {
+    return err instanceof PgMcpError && /unsupported version|not supported by this version/i.test(err.message);
+}
+function tooNewForLocalRestore(archivePath, restore, cause) {
+    return new PgMcpError({
+        code: 'BINARY_MISSING',
+        message: `"${archivePath}" was written by a newer pg_dump than the local pg_restore (${restore.major}), which cannot read it`,
+        hint: 'archives are forward-only: run the pg-admin-mcp image tag matching the pg_dump major that wrote this archive ' +
+            '(pg-admin-mcp:pg<N>), or point PG_MCP_PG_BIN_DIR at that postgresql-client version',
+        details: { archivePath, restoreMajor: restore.major },
+        cause,
+    });
+}
+function listArgs(archivePath) {
+    return ['--list', archivePath];
+}
+export function restoreArgs(profile, args, archivePath) {
+    return [
+        ...connectionArgs(profile),
+        `--dbname=${profile.database}`,
+        ...(args.clean === true ? ['--clean', '--if-exists'] : []),
+        ...(args.noOwner === true ? ['--no-owner'] : []),
+        ...(args.singleTransaction === true ? ['--single-transaction'] : []),
+        ...(args.schemas ?? []).map((s) => `--schema=${s}`),
+        ...(args.tables ?? []).map((t) => `--table=${t}`),
+        // Last, and always an absolute resolved path, so it can never be read as a flag.
+        archivePath,
+    ];
+}
+/** The archive's TOC, as `pg_restore --list` prints it. Touches no database. */
+async function inspect(archivePath, restore, timeoutMs) {
+    try {
+        const { stdout } = await runBinary('pg_restore', restore.command, listArgs(archivePath), {
+            timeoutMs,
+            operation: 'restore inspect',
+            stdoutMaxBytes: 4 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (err) {
+        if (isUnsupportedVersion(err))
+            throw tooNewForLocalRestore(archivePath, restore, err);
+        throw err;
+    }
+}
+function confirmRequired(profile, archivePath, clean) {
+    return new PgMcpError({
+        code: 'GUARD_CONFIRM_REQUIRED',
+        message: `restoring "${archivePath}" into profile "${profile.alias}" (${profile.database} on ${profile.host}) would ` +
+            `${clean ? 'DROP and recreate every object in the archive' : 'overwrite the objects in the archive'}, and nothing was changed`,
+        hint: 'run this again with mode:"inspect" to see exactly what the archive contains, then re-run with confirm:true to ' +
+            'apply it. There is no expect token for a restore: pg_restore runs in a separate process with no transaction ' +
+            'this server can preview or roll back',
+        details: { profile: profile.alias, database: profile.database, archivePath, clean },
+    });
+}
+export const restoreTool = defineTool('postgres_restore', {
+    title: 'Inspect or restore a pg_dump archive (DESTRUCTIVE)',
+    description: 'THE MOST DESTRUCTIVE TOOL IN THIS SERVER. mode:"restore" runs pg_restore against the profile\'s database and can ' +
+        'overwrite or, with clean:true, DROP AND RECREATE every object in the archive. There is no undo and no rollback: ' +
+        'pg_restore is a separate process, so this tool is NOT wrapped in the dry-run/confirm transaction guard the other ' +
+        'mutating tools use — there is no transaction this server can roll back, no row count to compare and no expect ' +
+        'token to issue. What it has instead: mode:"inspect" (the default) lists the archive contents with ' +
+        'pg_restore --list and touches no database, and mode:"restore" refuses without an explicit confirm:true. ' +
+        'Requires PG_<ALIAS>_ALLOW_RESTORE=true. The archive must be inside an allowed directory, is size-capped by ' +
+        'PG_MCP_MAX_ARCHIVE_BYTES, and is refused when it was written by a NEWER pg_dump than the local pg_restore ' +
+        '(archives are forward-only) with the image tag that can read it. Plain-format (SQL text) dumps are not ' +
+        'pg_restore archives — feed those to psql.',
+    inputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+}, async (args) => {
+    try {
+        const profile = loadProfiles().get(args.profile);
+        // Even inspect needs the capability: reading an archive's table of
+        // contents is the first step of a restore, and a profile that may never
+        // restore has no business being handed one.
+        requireCapability('restore', profile);
+        const cap = maxArchiveBytes();
+        const source = await resolveWorkspaceFileForRead(args.path, profile.allowedDirs, {
+            maxBytes: cap,
+            limitLabel: 'archive read',
+            limitHint: `raise PG_MCP_MAX_ARCHIVE_BYTES (currently ${cap}) and restart the server, or restore from a smaller archive`,
+            missingHint: 'a restore reads an existing archive — check the path, and that it is inside an allowed directory',
+            notFileHint: 'point path at a single-file archive (pg_dump --format=custom or tar). Directory-format archives are not supported here: ' +
+                'they cannot be identity-checked as one file, so re-dump with --format=custom',
+        });
+        try {
+            const pgRestore = await requireBinary('pg_restore');
+            const timeoutMs = Math.min(args.timeoutMs ?? profile.backupTimeoutMaxMs, profile.backupTimeoutMaxMs);
+            // Before anything is spawned, when the sidecar is there to say so.
+            const sidecar = await readSidecar(source.path, profile.allowedDirs);
+            if (sidecar !== undefined)
+                assertArchiveReadable(sidecar.clientMajor, pgRestore, source.path);
+            const listing = await inspect(source.path, pgRestore, timeoutMs);
+            // Fallback for an archive with no sidecar: the TOC header carries the
+            // version that wrote it. Only reachable when --list itself succeeded,
+            // i.e. when the archive is readable but may still be too new to apply.
+            const listedMajor = archiveMajorFromListing(listing);
+            if (sidecar === undefined && listedMajor !== undefined) {
+                assertArchiveReadable(listedMajor, pgRestore, source.path);
+            }
+            const entries = listing.split('\n').filter((line) => line.trim() !== '' && !line.startsWith(';'));
+            if (args.mode !== 'restore') {
+                return formatOutcome({
+                    kind: 'report',
+                    data: {
+                        mode: 'inspect',
+                        path: source.path,
+                        bytes: source.bytes,
+                        archiveMajor: sidecar?.clientMajor ?? listedMajor ?? null,
+                        sidecar: sidecar ?? null,
+                        sidecarPath: sidecarPathFor(source.path),
+                        entryCount: entries.length,
+                        entries,
+                        note: 'Nothing was changed — this is pg_restore --list, which reads the archive only. Re-run with ' +
+                            'mode:"restore" and confirm:true to apply it.',
+                    },
+                });
+            }
+            if (args.confirm !== true)
+                throw confirmRequired(profile, source.path, args.clean === true);
+            // design.md risk 2, on the restoring side: a pg_restore older than the
+            // target server refuses to run, and the raw stderr says nothing useful.
+            const server = await serverVersionOf(profile, 'restore');
+            assertClientCoversServer(pgRestore, server.num, server.version, profile.alias);
+            const result = await runBinary('pg_restore', pgRestore.command, restoreArgs(profile, args, source.path), {
+                timeoutMs,
+                password: profile.password(),
+                operation: 'restore',
+            });
+            return formatOutcome({
+                kind: 'report',
+                data: {
+                    mode: 'restore',
+                    restored: true,
+                    path: source.path,
+                    database: profile.database,
+                    host: `${profile.host}:${profile.port}`,
+                    archiveMajor: sidecar?.clientMajor ?? listedMajor ?? null,
+                    restoreMajor: pgRestore.major,
+                    serverVersion: server.version,
+                    entryCount: entries.length,
+                    clean: args.clean === true,
+                    singleTransaction: args.singleTransaction === true,
+                    // pg_restore writes warnings here even on success (missing roles,
+                    // already-existing objects under --clean --if-exists). Surfaced
+                    // rather than swallowed: they are the only account of what did not
+                    // apply cleanly.
+                    warnings: result.stderr.trim() === '' ? [] : result.stderr.trim().split('\n').slice(-40),
+                    capability: capabilityEnvVar('restore', profile.alias),
+                },
+            });
+        }
+        finally {
+            // Held open for the whole restore so the approved inode stays alive
+            // while pg_restore reads it — see the file header's note on the
+            // residual path-vs-fd gap.
+            await source.handle.close();
+        }
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=restore.js.map

package/dist/tools/restore.js.map

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

package/dist/tools/schema_diff.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { loadProfiles } from '../config/profiles.js';
+import { toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { resolveLimits, truncateRows } from '../core/limits.js';
+import { diffSnapshots } from '../snapshot/diff.js';
+import { defineTool, profileParam } from './_shared.js';
+import { resolveSnapshotSource, snapshotSourceSchema } from './_snapshot_io.js';
+/**
+ * `postgres_schema_diff` — structural diff between two normalized schema
+ * snapshots (`snapshot/diff.ts#diffSnapshots`). Each side (`before`/`after`)
+ * is independently either a live database capture or a snapshot file written
+ * by `postgres_schema_snapshot` (`_snapshot_io.ts#resolveSnapshotSource`), so
+ * this covers all three shapes the phase asked for: two files, a file vs. a
+ * live database, or two live databases.
+ *
+ * A snapshot file is untrusted input — `_snapshot_io.ts#parseSnapshotFile`
+ * validates it against a `.strict()` zod mirror of `snapshot/model.ts` before
+ * it ever reaches `diffSnapshots`, and `diffSnapshots` itself refuses two
+ * snapshots of different `formatVersion`s (`SNAPSHOT_VERSION_MISMATCH`) rather
+ * than reporting every object as changed.
+ *
+ * Output is bounded the same way `postgres_get_schema` bounds its object
+ * list: `core/limits.ts#truncateRows` over the flat change list, byte-capped
+ * by the real serialized size of each entry, with an explicit count of what
+ * was kept vs. cut and how to narrow (`before`/`after` `schemas` scope).
+ */
+const inputSchema = z.object({
+    ...profileParam,
+    before: snapshotSourceSchema.describe('The baseline side of the comparison.'),
+    after: snapshotSourceSchema.describe('The changed side of the comparison — the diff reads as "before -> after".'),
+    maxChanges: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Caps the number of changes included before truncation. Defaults to the profile row limit.'),
+});
+/** An explicit, actionable truncation message: what was kept, what was cut, how to narrow. */
+function truncationHint(kept, total, cutAt) {
+    const at = cutAt === undefined ? 'the cap' : `${cutAt.path} (${cutAt.objectType} ${cutAt.kind})`;
+    return `showing ${kept} of ${total} changes; truncated at ${at} — narrow before/after with a schemas scope, or raise maxChanges`;
+}
+export const schemaDiffTool = defineTool('postgres_schema_diff', {
+    title: 'Diff two PostgreSQL schema snapshots',
+    description: 'Structural diff between two schema snapshots. Each of before/after is independently either kind:"live" (a ' +
+        'fresh capture) or kind:"file" (a file written earlier by postgres_schema_snapshot) — so this compares two ' +
+        'files, a file against a live database, or two live databases. Read-only: never modifies either side. An ' +
+        'oversized result is truncated with an explicit count and a hint for narrowing scope, never silently cut.',
+    inputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        const [before, after] = await Promise.all([
+            resolveSnapshotSource(args.before, args.profile),
+            resolveSnapshotSource(args.after, args.profile),
+        ]);
+        const changes = diffSnapshots(before, after);
+        const limits = resolveLimits(profile.maxRows, args.maxChanges === undefined ? {} : { maxRows: args.maxChanges }, process.env);
+        const { rows: kept, truncation } = truncateRows(changes, limits, (c) => JSON.stringify(c));
+        const truncated = truncation.reason !== null;
+        const data = {
+            before: { database: before.database },
+            after: { database: after.database },
+            changeCount: kept.length,
+            totalChanges: changes.length,
+            changes: kept,
+            truncated,
+            ...(truncated ? { truncationMessage: truncationHint(kept.length, changes.length, changes[kept.length]) } : {}),
+        };
+        return formatOutcome({ kind: 'report', data });
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=schema_diff.js.map

package/dist/tools/schema_diff.js.map

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

package/dist/tools/schema_snapshot.js

@@ -0,0 +1,57 @@
+import { finished } from 'node:stream/promises';
+import { z } from 'zod';
+import { loadProfiles } from '../config/profiles.js';
+import { toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { renderHostPath, resolveWorkspacePath, writeFileAtomic } from '../core/paths.js';
+import { captureSnapshot } from '../snapshot/capture.js';
+import { defineTool, profileParam } from './_shared.js';
+/**
+ * `postgres_schema_snapshot` — captures a normalized schema snapshot
+ * (`snapshot/capture.ts`) and persists it to a workspace file, so it can
+ * later be compared with `postgres_schema_diff` / `postgres_prepare_migration`
+ * without holding the source database open.
+ *
+ * Same path policy as `postgres_export`: `resolveWorkspacePath` (never a
+ * directory as the destination) then `writeFileAtomic` (a `.partial` file
+ * published only on success, refuses to clobber an existing file unless
+ * `overwrite: true`). The file is one `JSON.stringify` of the snapshot —
+ * `model.ts`'s own byte-stability guarantee means two captures of an
+ * unchanged database produce the identical file.
+ */
+const inputSchema = z.object({
+    ...profileParam,
+    schemas: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Restrict the capture to these schemas. Omit for every schema in scope (Profile.schemas, or every non-system schema).'),
+    path: z.string().min(1).describe('Destination file path. Relative paths resolve against the profile\'s first allowed directory; absolute paths must still land inside an allowed directory.'),
+    overwrite: z.boolean().optional().describe('Required (true) to replace an existing file at path. Defaults to false.'),
+});
+export const schemaSnapshotTool = defineTool('postgres_schema_snapshot', {
+    title: 'Capture a normalized schema snapshot to a file',
+    description: 'Captures a normalized, byte-stable schema snapshot (tables, views, sequences, functions, enums, extensions ' +
+        '— see postgres_get_schema for a live equivalent) and writes it to a workspace file as JSON. Use the result ' +
+        'with postgres_schema_diff or postgres_prepare_migration to compare it against another snapshot or a live ' +
+        'database. Refuses to overwrite an existing file unless overwrite:true.',
+    inputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        const resolvedPath = await resolveWorkspacePath(args.path, profile.allowedDirs);
+        const snapshot = await captureSnapshot(profile, args.schemas === undefined ? {} : { schemas: args.schemas });
+        const json = JSON.stringify(snapshot);
+        const bytes = await writeFileAtomic(resolvedPath, async (dest) => {
+            dest.end(json);
+            await finished(dest);
+        }, { overwrite: args.overwrite === true });
+        const hostPath = renderHostPath(resolvedPath, profile.allowedDirs);
+        return formatOutcome({ kind: 'file', path: resolvedPath, bytes, ...(hostPath === undefined ? {} : { hostPath }) });
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=schema_snapshot.js.map

package/dist/tools/schema_snapshot.js.map

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

package/dist/tools/select.js

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+import { loadProfiles } from '../config/profiles.js';
+import { toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { columnIdentFromCatalog, resolveColumn, resolveRelation } from '../core/identifiers.js';
+import { resolveLimits } from '../core/limits.js';
+import { buildKeysetWhere, computeShapeHash, cursorValuesFromRow, decodeCursor, encodeCursor, orderByClause, withTiebreaker, } from '../core/paginate.js';
+import { getColumns, getPrimaryKey } from '../db/catalog.js';
+import { withTx } from '../db/session.js';
+import { defineTool, profileParam } from './_shared.js';
+/**
+ * `postgres_select` — structured, parameterized, paginated reads. Deliberately
+ * NOT an arbitrary-SQL escape hatch (that is `postgres_execute_sql`, Phase 2):
+ * every identifier (`columns`, `where[].column`, `orderBy[].column`) is
+ * validated against the relation's real columns via `core/identifiers.ts#resolveColumn`
+ * before it ever reaches SQL text, and every value is a bound `$N` parameter —
+ * never string-concatenated.
+ *
+ * Runs inside `withTx({ readOnly: true })`: PostgreSQL's own `READ ONLY`
+ * transaction (SQLSTATE 25006 -> `POLICY_READ_ONLY`) is the enforcement
+ * mechanism, not a lexical check — so a `where` value that calls a volatile
+ * writing function is rejected by PostgreSQL itself, not by this tool trying
+ * to parse SQL.
+ *
+ * Pagination is real SQL keyset pagination (unlike `list_objects`'s in-memory
+ * one): `core/paginate.ts#SortColumn`/`buildKeysetWhere`/`orderByClause` all
+ * resolve NULLS FIRST/LAST placement through the same `effectiveNulls`
+ * default, which is the entire mechanism that keeps the emitted `ORDER BY`
+ * and the keyset `WHERE` predicate from disagreeing on a nullable sort
+ * column — see that module's doc comment for the four-case breakdown.
+ */
+const DEFAULT_PAGE_SIZE = 200;
+const MAX_PAGE_SIZE = 2000;
+/** Exported so `tools/export.ts`, `update_batch` and `delete_batch` reuse the exact same scalar shape instead of a second, later-diverging copy. */
+export const scalarValue = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+/** Exported so `tools/export.ts`, `update_batch` and `delete_batch` reuse the exact same predicate shape and validation instead of a second, later-diverging copy. */
+export const wherePredicate = z.discriminatedUnion('op', [
+    z.object({ column: z.string().min(1), op: z.literal('IS NULL') }),
+    z.object({ column: z.string().min(1), op: z.literal('IS NOT NULL') }),
+    z.object({
+        column: z.string().min(1),
+        op: z.enum(['=', '!=', '<', '<=', '>', '>=', 'LIKE', 'ILIKE']),
+        value: scalarValue,
+    }),
+    z.object({ column: z.string().min(1), op: z.enum(['IN', 'NOT IN']), value: z.array(scalarValue).min(1) }),
+]);
+const orderByColumn = z.object({
+    column: z.string().min(1),
+    direction: z.enum(['ASC', 'DESC']).optional().describe('Defaults to ASC.'),
+    nulls: z.enum(['FIRST', 'LAST']).optional().describe('Defaults to the direction\'s own PostgreSQL default (ASC -> LAST, DESC -> FIRST).'),
+});
+const inputSchema = z.object({
+    ...profileParam,
+    schema: z.string().min(1).describe('Schema name, e.g. "app".'),
+    table: z.string().min(1).describe('Table/view name within the schema.'),
+    columns: z.array(z.string().min(1)).min(1).optional().describe('Columns to select, in this order. Omit for every column, in ordinal order.'),
+    where: z
+        .array(wherePredicate)
+        .optional()
+        .describe('Filter predicates, ANDed together. Every value is a bound parameter — never interpolated into SQL text.'),
+    orderBy: z
+        .array(orderByColumn)
+        .optional()
+        .describe('Sort columns in priority order. A unique tiebreaker (primary key, or ctid) is appended automatically.'),
+    limit: z.number().int().min(1).max(MAX_PAGE_SIZE).optional().describe(`Rows per page (max ${MAX_PAGE_SIZE}), further capped by the profile row limit.`),
+    cursor: z.string().optional().describe('Opaque pagination cursor — pass back the previous call\'s nextCursor verbatim to fetch the next page.'),
+});
+export const selectTool = defineTool('postgres_select', {
+    title: 'Select rows from a PostgreSQL table',
+    description: 'Structured, parameterized, paginated read of one table or view — the primary way to fetch actual row data. ' +
+        'Filter with a structured `where` (=, !=, <, <=, >, >=, LIKE, ILIKE, IN, NOT IN, IS NULL, IS NOT NULL); sort ' +
+        'with `orderBy` (direction and NULLS FIRST/LAST); page with `limit`/`cursor`. Every identifier is validated ' +
+        'against the table\'s real columns (unknown column -> IDENTIFIER_UNKNOWN with suggestions); every value is a ' +
+        'bound parameter. Runs inside a read-only transaction. Not an arbitrary-SQL tool.',
+    inputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        const rel = await resolveRelation(profile, args.schema, args.table);
+        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 shapeHash = computeShapeHash({
+            profile: profile.alias,
+            schema: args.schema,
+            table: args.table,
+            columns: args.columns ?? null,
+            where: args.where ?? null,
+            orderBy: args.orderBy ?? null,
+        });
+        const result = await withTx(profile, async (client) => {
+            const columnInfos = await getColumns(client, rel);
+            const knownColumns = columnInfos.map((c) => c.name);
+            const selectColumns = args.columns === undefined
+                ? columnInfos.map((c) => ({ name: c.name, ident: columnIdentFromCatalog(c.name) }))
+                : args.columns.map((name) => ({ name, ident: resolveColumn(args.schema, args.table, name, knownColumns) }));
+            const primaryKey = await getPrimaryKey(client, rel);
+            const pkIdents = (primaryKey?.columns ?? []).map((name) => resolveColumn(args.schema, args.table, name, knownColumns));
+            const userSort = (args.orderBy ?? []).map((o) => ({
+                name: o.column,
+                ident: resolveColumn(args.schema, args.table, o.column, knownColumns),
+                direction: o.direction ?? 'ASC',
+                ...(o.nulls === undefined ? {} : { nulls: o.nulls }),
+            }));
+            const sortColumns = withTiebreaker(userSort, pkIdents);
+            let paramIndex = 1;
+            const whereParts = [];
+            const params = [];
+            for (const pred of args.where ?? []) {
+                const ident = resolveColumn(args.schema, args.table, pred.column, knownColumns);
+                if (pred.op === 'IS NULL' || pred.op === 'IS NOT NULL') {
+                    whereParts.push(`${ident} ${pred.op}`);
+                }
+                else if (pred.op === 'IN' || pred.op === 'NOT IN') {
+                    const placeholders = pred.value.map(() => `$${paramIndex++}`).join(', ');
+                    whereParts.push(`${ident} ${pred.op} (${placeholders})`);
+                    params.push(...pred.value);
+                }
+                else {
+                    whereParts.push(`${ident} ${pred.op} $${paramIndex++}`);
+                    params.push(pred.value);
+                }
+            }
+            const userWhere = whereParts.length === 0 ? 'TRUE' : whereParts.join(' AND ');
+            const cursorValues = args.cursor === undefined ? [] : decodeCursor(args.cursor, shapeHash);
+            const keyset = buildKeysetWhere(sortColumns, cursorValues, paramIndex);
+            const limitParamIndex = paramIndex + keyset.params.length;
+            const sql = `SELECT ${selectColumns.map((c) => c.ident).join(', ')} FROM ${rel.schema}.${rel.name} ` +
+                `WHERE (${userWhere}) AND (${keyset.clause}) ORDER BY ${orderByClause(sortColumns)} LIMIT $${limitParamIndex}`;
+            // `queryMode: 'extended'` explicitly, never "there are params so it
+            // must be extended": `pg` decides that from `values.length > 0`, which
+            // is a property of this statement today and not an invariant. Every
+            // identifier above is a catalog-resolved `SafeIdent`, so this is
+            // defence in depth rather than the fence — but it is the same one
+            // line every other call site in this server carries.
+            const queryResult = await client.query({
+                text: sql,
+                values: [...params, ...keyset.params, pageLimit + 1],
+                queryMode: 'extended',
+            });
+            const columns = queryResult.fields.map((f) => ({ name: f.name, dataTypeId: f.dataTypeID }));
+            const hasMore = queryResult.rows.length > pageLimit;
+            const rows = (hasMore ? queryResult.rows.slice(0, pageLimit) : queryResult.rows);
+            const last = rows[rows.length - 1];
+            const nextCursor = hasMore && last !== undefined ? encodeCursor(cursorValuesFromRow(last, sortColumns), shapeHash) : undefined;
+            return { columns, rows, hasMore, nextCursor };
+        }, { readOnly: true, operation: 'select' });
+        return formatOutcome({
+            kind: 'rows',
+            columns: result.columns,
+            rows: result.rows,
+            rowCount: result.rows.length,
+            truncated: result.hasMore,
+            ...(result.nextCursor === undefined ? {} : { nextCursor: result.nextCursor }),
+        }, { limits });
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=select.js.map