pg-admin-mcp 0.0.0-stage → 0.1.0

package/dist/db/catalog.js

@@ -0,0 +1,1006 @@
+/**
+ * The one place all `pg_catalog` SQL lives. `list_objects`, `describe_object`,
+ * `get_schema`, and later resources call these instead of writing their own
+ * queries — this is where the "never `information_schema`" rule (design.md
+ * risk 5) is actually enforced: every query below reads `pg_catalog` directly,
+ * which is the only place partial-index predicates (`pg_index.indpred`) and
+ * row-level-security policies (`pg_policy`) are visible at all.
+ *
+ * Every function takes an already-checked-out `client: PoolClient` — this
+ * module never acquires one itself (`db/session.ts` is the only acquirer), so
+ * a caller that needs several of these under one consistent snapshot (e.g.
+ * `describe_object` pulling columns + indexes + triggers together) runs them
+ * all inside a single `withSession`/`withTx` callback.
+ *
+ * All queries are parameterized. Listing-level functions take a plain
+ * `readonly string[]` of schema names because that list is always either
+ * profile config (`Profile.schemas`, trusted, never interpolated — only ever
+ * bound) or the output of {@link listSchemas} itself; only bound parameters
+ * touch SQL text, so no `SafeIdent` is needed there. Per-relation functions
+ * take a {@link RelationRef} (an oid plus catalog-verified `SafeIdent`s)
+ * because those are always called after `core/identifiers.ts#resolveRelation`.
+ */
+async function rows(client, text, params) {
+    const result = await client.query(text, params);
+    return result.rows;
+}
+// pg_class.relkind for every relation kind this server exposes. Kept local
+// (rather than re-exported from core/identifiers.ts) since it is a tiny,
+// stable table duplicated in exactly one other place for a different purpose.
+const RELKIND_TO_KIND = {
+    r: 'table',
+    p: 'partitioned_table',
+    v: 'view',
+    m: 'materialized_view',
+    f: 'foreign_table',
+};
+const RELATION_RELKINDS = Object.keys(RELKIND_TO_KIND);
+// ---------------------------------------------------------------------------
+// Database-wide listings
+// ---------------------------------------------------------------------------
+/**
+ * `schemas` unset lists every non-system schema; system schemas (`pg_%`, `information_schema`) are always excluded.
+ * `namePattern` (a SQL `LIKE`/`ILIKE` pattern, `%`/`_` wildcards) is bound as `$N` and evaluated by PostgreSQL itself
+ * — never matched in JS. PostgreSQL's `LIKE` engine is linear in input length; a naive `pattern -> RegExp` translation
+ * (the historical approach here, `tools/_object_kinds.ts#patternToRegExp`) is not, and a caller-supplied pattern like
+ * `%%%%%%%%z` turns that into catastrophic backtracking — the whole server would hang evaluating one pattern against
+ * one name. Binding as a value into `ILIKE` sidesteps the vulnerability class entirely instead of trying to detect it.
+ */
+export async function listSchemas(client, schemas, namePattern) {
+    const result = await rows(client, `SELECT n.oid::int AS oid, n.nspname AS name, pg_get_userbyid(n.nspowner) AS owner
+       FROM pg_catalog.pg_namespace n
+      WHERE n.nspname !~ '^pg_' AND n.nspname <> 'information_schema'
+        AND ($1::text[] IS NULL OR n.nspname = ANY($1))
+        AND ($2::text IS NULL OR n.nspname ILIKE $2)
+      ORDER BY n.nspname`, [schemas ?? null, namePattern ?? null]);
+    return result;
+}
+export async function listRelations(client, schemas, opts = {}) {
+    if (schemas.length === 0)
+        return [];
+    const relkinds = opts.kinds === undefined
+        ? RELATION_RELKINDS
+        : Object.entries(RELKIND_TO_KIND)
+            .filter(([, kind]) => opts.kinds?.includes(kind))
+            .map(([relkind]) => relkind);
+    if (relkinds.length === 0)
+        return [];
+    const result = await rows(client, `SELECT c.oid::int AS oid, n.nspname AS schema, c.relname AS name, c.relkind AS relkind,
+            pg_get_userbyid(c.relowner) AS owner, obj_description(c.oid, 'pg_class') AS comment,
+            NULLIF(c.reltuples, -1) AS estimated_rows
+       FROM pg_catalog.pg_class c
+       JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = ANY($1) AND c.relkind = ANY($2::"char"[])
+        AND ($3::text IS NULL OR c.relname ILIKE $3)
+      ORDER BY n.nspname, c.relname`, [schemas, relkinds, opts.namePattern ?? null]);
+    return result.map((r) => ({
+        oid: r.oid,
+        schema: r.schema,
+        name: r.name,
+        kind: RELKIND_TO_KIND[r.relkind] ?? 'table',
+        owner: r.owner,
+        comment: r.comment,
+        estimatedRows: r.estimated_rows === null ? null : Math.round(r.estimated_rows),
+    }));
+}
+export async function listSequences(client, schemas, namePattern) {
+    if (schemas.length === 0)
+        return [];
+    const result = await rows(client, `SELECT c.oid::int AS oid, n.nspname AS schema, c.relname AS name,
+            pg_get_userbyid(c.relowner) AS owner, obj_description(c.oid, 'pg_class') AS comment
+       FROM pg_catalog.pg_class c
+       JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = ANY($1) AND c.relkind = 'S'
+        AND ($2::text IS NULL OR c.relname ILIKE $2)
+      ORDER BY n.nspname, c.relname`, [schemas, namePattern ?? null]);
+    return result;
+}
+export async function listFunctions(client, schemas, namePattern) {
+    if (schemas.length === 0)
+        return [];
+    const result = await rows(client, `SELECT p.oid::int AS oid, n.nspname AS schema, p.proname AS name,
+            pg_get_function_identity_arguments(p.oid) AS arg_types,
+            pg_get_function_result(p.oid) AS return_type,
+            l.lanname AS language, p.prokind AS kind,
+            obj_description(p.oid, 'pg_proc') AS comment
+       FROM pg_catalog.pg_proc p
+       JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+       JOIN pg_catalog.pg_language l ON l.oid = p.prolang
+      WHERE n.nspname = ANY($1)
+        AND ($2::text IS NULL OR p.proname ILIKE $2)
+      ORDER BY n.nspname, p.proname`, [schemas, namePattern ?? null]);
+    return result.map((r) => ({
+        oid: r.oid,
+        schema: r.schema,
+        name: r.name,
+        argTypes: r.arg_types,
+        returnType: r.return_type,
+        language: r.language,
+        kind: r.kind,
+        comment: r.comment,
+    }));
+}
+export async function listEnumTypes(client, schemas, namePattern) {
+    if (schemas.length === 0)
+        return [];
+    const result = await rows(client, `SELECT t.oid::int AS oid, n.nspname AS schema, t.typname AS name,
+            ARRAY(SELECT e.enumlabel FROM pg_catalog.pg_enum e
+                   WHERE e.enumtypid = t.oid ORDER BY e.enumsortorder)::text[] AS labels,
+            obj_description(t.oid, 'pg_type') AS comment
+       FROM pg_catalog.pg_type t
+       JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+      WHERE t.typtype = 'e' AND n.nspname = ANY($1)
+        AND ($2::text IS NULL OR t.typname ILIKE $2)
+      ORDER BY n.nspname, t.typname`, [schemas, namePattern ?? null]);
+    return result;
+}
+/** `namePattern` filters extension names; schema scoping is applied by the caller (`tools/_object_kinds.ts`) since an extension's schema is not part of this query's own `WHERE`. */
+export async function listExtensions(client, namePattern) {
+    return rows(client, `SELECT e.extname AS name, e.extversion AS version, n.nspname AS schema,
+            obj_description(e.oid, 'pg_extension') AS comment
+       FROM pg_catalog.pg_extension e
+       JOIN pg_catalog.pg_namespace n ON n.oid = e.extnamespace
+      WHERE ($1::text IS NULL OR e.extname ILIKE $1)
+      ORDER BY e.extname`, [namePattern ?? null]);
+}
+/**
+ * Server version and `current_user`'s privileges — `postgres_connection_status`'s
+ * probe. Lives here (not inlined in `tools/connection_status.ts`) per this
+ * module's own rule: `catalog.ts` is the one place `pg_catalog` SQL lives.
+ * `null` only if the server returns neither row, which should never happen on
+ * a reachable connection.
+ */
+export async function getCurrentRoleInfo(client) {
+    const versionRows = await rows(client, `SELECT current_setting('server_version') AS version`, []);
+    const roleRows = await rows(client, `SELECT rolname, rolsuper, rolcreaterole, rolcreatedb, rolreplication, rolbypassrls
+       FROM pg_catalog.pg_roles WHERE rolname = current_user`, []);
+    const version = versionRows[0]?.version;
+    const role = roleRows[0];
+    if (version === undefined || role === undefined)
+        return null;
+    return {
+        serverVersion: version,
+        role: role.rolname,
+        isSuperuser: role.rolsuper,
+        canCreateRole: role.rolcreaterole,
+        canCreateDb: role.rolcreatedb,
+        canReplicate: role.rolreplication,
+        bypassRls: role.rolbypassrls,
+    };
+}
+// ---------------------------------------------------------------------------
+// Per-relation detail — every function below takes a resolved RelationRef.
+// ---------------------------------------------------------------------------
+export async function getColumns(client, rel) {
+    const result = await rows(client, `SELECT a.attname AS name, a.attnum AS ordinal,
+            format_type(a.atttypid, a.atttypmod) AS data_type,
+            a.attnotnull AS not_null,
+            pg_get_expr(ad.adbin, ad.adrelid) AS default_expr,
+            a.attgenerated <> '' AS is_generated,
+            col_description(a.attrelid, a.attnum) AS comment
+       FROM pg_catalog.pg_attribute a
+       LEFT JOIN pg_catalog.pg_attrdef ad ON ad.adrelid = a.attrelid AND ad.adnum = a.attnum
+      WHERE a.attrelid = $1 AND a.attnum > 0 AND NOT a.attisdropped
+      ORDER BY a.attnum`, [rel.oid]);
+    return result.map((r) => ({
+        name: r.name,
+        ordinal: r.ordinal,
+        dataType: r.data_type,
+        notNull: r.not_null,
+        defaultExpr: r.default_expr,
+        isGenerated: r.is_generated,
+        comment: r.comment,
+    }));
+}
+/**
+ * Column list for a `conkey`/`confkey` array, in index/constraint-defined order (not `attnum` order).
+ *
+ * Cast to `text[]` (OID 1009): `attname` is Postgres type `name`, so an uncast
+ * `ARRAY(...)` here comes back as `name[]` (OID 1003) — a type `pg-types` has
+ * no built-in array parser for, unlike `text[]`. Without the cast, `pg` hands
+ * back the raw `'{a,b,c}'` wire literal instead of a real JS array.
+ */
+const ORDERED_COLUMNS_SUBQUERY = (keyExpr, relidExpr) => `
+  ARRAY(
+    SELECT a.attname
+      FROM unnest(${keyExpr}) WITH ORDINALITY AS k(attnum, ord)
+      JOIN pg_catalog.pg_attribute a ON a.attrelid = ${relidExpr} AND a.attnum = k.attnum
+     ORDER BY k.ord
+  )::text[]`;
+export async function getPrimaryKey(client, rel) {
+    const result = await rows(client, `SELECT con.conname AS name, ${ORDERED_COLUMNS_SUBQUERY('con.conkey', 'con.conrelid')} AS columns
+       FROM pg_catalog.pg_constraint con
+      WHERE con.conrelid = $1 AND con.contype = 'p'`, [rel.oid]);
+    return result[0] ?? null;
+}
+export async function getForeignKeys(client, rel) {
+    const ACTION = { a: 'NO ACTION', r: 'RESTRICT', c: 'CASCADE', n: 'SET NULL', d: 'SET DEFAULT' };
+    const result = await rows(client, `SELECT con.conname AS name,
+            ${ORDERED_COLUMNS_SUBQUERY('con.conkey', 'con.conrelid')} AS columns,
+            rn.nspname AS ref_schema, rc.relname AS ref_table,
+            ${ORDERED_COLUMNS_SUBQUERY('con.confkey', 'con.confrelid')} AS ref_columns,
+            con.confupdtype AS on_update_code, con.confdeltype AS on_delete_code,
+            pg_get_constraintdef(con.oid) AS definition
+       FROM pg_catalog.pg_constraint con
+       JOIN pg_catalog.pg_class rc ON rc.oid = con.confrelid
+       JOIN pg_catalog.pg_namespace rn ON rn.oid = rc.relnamespace
+      WHERE con.conrelid = $1 AND con.contype = 'f'
+      ORDER BY con.conname`, [rel.oid]);
+    return result.map((r) => ({
+        name: r.name,
+        columns: r.columns,
+        refSchema: r.ref_schema,
+        refTable: r.ref_table,
+        refColumns: r.ref_columns,
+        onUpdate: ACTION[r.on_update_code] ?? r.on_update_code,
+        onDelete: ACTION[r.on_delete_code] ?? r.on_delete_code,
+        definition: r.definition,
+    }));
+}
+export async function getUniqueConstraints(client, rel) {
+    return rows(client, `SELECT con.conname AS name, ${ORDERED_COLUMNS_SUBQUERY('con.conkey', 'con.conrelid')} AS columns
+       FROM pg_catalog.pg_constraint con
+      WHERE con.conrelid = $1 AND con.contype = 'u'
+      ORDER BY con.conname`, [rel.oid]);
+}
+export async function getCheckConstraints(client, rel) {
+    return rows(client, `SELECT con.conname AS name, pg_get_constraintdef(con.oid) AS definition
+       FROM pg_catalog.pg_constraint con
+      WHERE con.conrelid = $1 AND con.contype = 'c'
+      ORDER BY con.conname`, [rel.oid]);
+}
+export async function getIndexes(client, rel) {
+    const result = await rows(client, `SELECT ic.relname AS name,
+            pg_get_indexdef(i.indexrelid) AS definition,
+            i.indisunique AS is_unique,
+            i.indisprimary AS is_primary,
+            pg_get_expr(i.indpred, i.indrelid) AS predicate,
+            (SELECT array_agg(COALESCE(a.attname, '(expression)') ORDER BY k.ord)::text[]
+               FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
+               LEFT JOIN pg_catalog.pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
+            ) AS columns
+       FROM pg_catalog.pg_index i
+       JOIN pg_catalog.pg_class ic ON ic.oid = i.indexrelid
+      WHERE i.indrelid = $1
+      ORDER BY ic.relname`, [rel.oid]);
+    return result.map((r) => ({
+        name: r.name,
+        definition: r.definition,
+        isUnique: r.is_unique,
+        isPrimary: r.is_primary,
+        columns: r.columns ?? [],
+        predicate: r.predicate,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Batched per-relation detail — one round trip for N relations instead of N.
+// `get_schema`'s `detail: "full"` used to call the four single-relation
+// functions above once per relation (`Promise.all` over the same client, no
+// less — see `tools/_relation_detail.ts`'s module doc for why that alone was
+// a bug): 4 catalog round trips per relation, so 40 objects meant ~160
+// queries and the profile's default `maxRows` (500) meant up to ~2000
+// sequential round trips on one connection. These four take `oid = ANY($1)`
+// instead of `oid = $1` and return a `Map<oid, T[]>` (or `Map<oid, T>` for the
+// at-most-one-per-relation primary key) so the caller pays 4 queries total,
+// not 4 per relation. Not part of the single-relation `describe_object` path
+// — that already runs exactly 1 relation through the unbatched functions
+// above, where batching would add overhead for no benefit.
+// ---------------------------------------------------------------------------
+export async function getColumnsBatch(client, oids) {
+    const out = new Map();
+    if (oids.length === 0)
+        return out;
+    const result = await rows(client, `SELECT a.attrelid::int AS relid, a.attname AS name, a.attnum AS ordinal,
+            format_type(a.atttypid, a.atttypmod) AS data_type,
+            a.attnotnull AS not_null,
+            pg_get_expr(ad.adbin, ad.adrelid) AS default_expr,
+            a.attgenerated <> '' AS is_generated,
+            col_description(a.attrelid, a.attnum) AS comment
+       FROM pg_catalog.pg_attribute a
+       LEFT JOIN pg_catalog.pg_attrdef ad ON ad.adrelid = a.attrelid AND ad.adnum = a.attnum
+      WHERE a.attrelid = ANY($1) AND a.attnum > 0 AND NOT a.attisdropped
+      ORDER BY a.attrelid, a.attnum`, [oids]);
+    for (const r of result) {
+        const list = out.get(r.relid) ?? [];
+        list.push({
+            name: r.name,
+            ordinal: r.ordinal,
+            dataType: r.data_type,
+            notNull: r.not_null,
+            defaultExpr: r.default_expr,
+            isGenerated: r.is_generated,
+            comment: r.comment,
+        });
+        out.set(r.relid, list);
+    }
+    return out;
+}
+export async function getPrimaryKeysBatch(client, oids) {
+    const out = new Map();
+    if (oids.length === 0)
+        return out;
+    const result = await rows(client, `SELECT con.conrelid::int AS relid, con.conname AS name, ${ORDERED_COLUMNS_SUBQUERY('con.conkey', 'con.conrelid')} AS columns
+       FROM pg_catalog.pg_constraint con
+      WHERE con.conrelid = ANY($1) AND con.contype = 'p'`, [oids]);
+    for (const r of result)
+        out.set(r.relid, { name: r.name, columns: r.columns });
+    return out;
+}
+export async function getForeignKeysBatch(client, oids) {
+    const out = new Map();
+    if (oids.length === 0)
+        return out;
+    const ACTION = { a: 'NO ACTION', r: 'RESTRICT', c: 'CASCADE', n: 'SET NULL', d: 'SET DEFAULT' };
+    const result = await rows(client, `SELECT con.conrelid::int AS relid, con.conname AS name,
+            ${ORDERED_COLUMNS_SUBQUERY('con.conkey', 'con.conrelid')} AS columns,
+            rn.nspname AS ref_schema, rc.relname AS ref_table,
+            ${ORDERED_COLUMNS_SUBQUERY('con.confkey', 'con.confrelid')} AS ref_columns,
+            con.confupdtype AS on_update_code, con.confdeltype AS on_delete_code,
+            pg_get_constraintdef(con.oid) AS definition
+       FROM pg_catalog.pg_constraint con
+       JOIN pg_catalog.pg_class rc ON rc.oid = con.confrelid
+       JOIN pg_catalog.pg_namespace rn ON rn.oid = rc.relnamespace
+      WHERE con.conrelid = ANY($1) AND con.contype = 'f'
+      ORDER BY con.conrelid, con.conname`, [oids]);
+    for (const r of result) {
+        const list = out.get(r.relid) ?? [];
+        list.push({
+            name: r.name,
+            columns: r.columns,
+            refSchema: r.ref_schema,
+            refTable: r.ref_table,
+            refColumns: r.ref_columns,
+            onUpdate: ACTION[r.on_update_code] ?? r.on_update_code,
+            onDelete: ACTION[r.on_delete_code] ?? r.on_delete_code,
+            definition: r.definition,
+        });
+        out.set(r.relid, list);
+    }
+    return out;
+}
+export async function getIndexesBatch(client, oids, opts = {}) {
+    const out = new Map();
+    if (oids.length === 0)
+        return out;
+    const result = await rows(client, `SELECT i.indrelid::int AS relid, ic.relname AS name,
+            pg_get_indexdef(i.indexrelid) AS definition,
+            i.indisunique AS is_unique,
+            i.indisprimary AS is_primary,
+            pg_get_expr(i.indpred, i.indrelid) AS predicate,
+            (SELECT array_agg(COALESCE(a.attname, '(expression)') ORDER BY k.ord)::text[]
+               FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
+               LEFT JOIN pg_catalog.pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
+            ) AS columns
+       FROM pg_catalog.pg_index i
+       JOIN pg_catalog.pg_class ic ON ic.oid = i.indexrelid
+      WHERE i.indrelid = ANY($1)
+        AND ($2::bool IS NOT TRUE
+             OR NOT EXISTS (SELECT 1 FROM pg_catalog.pg_constraint con WHERE con.conindid = i.indexrelid))
+      ORDER BY i.indrelid, ic.relname`, [oids, opts.excludeConstraintBacked ?? false]);
+    for (const r of result) {
+        const list = out.get(r.relid) ?? [];
+        list.push({ name: r.name, definition: r.definition, isUnique: r.is_unique, isPrimary: r.is_primary, columns: r.columns ?? [], predicate: r.predicate });
+        out.set(r.relid, list);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Snapshot capture support — everything below is batched (`= ANY($1)`) or
+// schema-scoped (`= ANY($1)` over schema names), because `snapshot/capture.ts`
+// must cost a fixed number of round trips for a whole schema, not a number
+// that grows with the relation count (see `_relation_detail.ts`'s module doc
+// for the 166-queries-for-40-objects regression these shapes exist to avoid).
+// ---------------------------------------------------------------------------
+/** `SELECT current_database()` — cast to `text`, since `name` is not a type any caller should be handed raw. */
+export async function getCurrentDatabase(client) {
+    const result = await rows(client, `SELECT current_database()::text AS name`, []);
+    return result[0]?.name ?? '';
+}
+/**
+ * Columns with everything a schema *snapshot* needs and `describe_object` does
+ * not: identity kind, generation kind, and a non-default collation. Kept
+ * separate from {@link getColumnsBatch} rather than widening `ColumnInfo`,
+ * because widening it would silently change the JSON `postgres_describe_object`
+ * and `postgres_get_schema` have been returning since Phase 1.
+ *
+ * `attcollation <> typcollation` is the whole point of the collation column:
+ * every collatable column has *a* collation, and reporting the type's own
+ * default on every one of them would bury the handful that actually override it.
+ */
+export async function getSnapshotColumnsBatch(client, oids) {
+    const out = new Map();
+    if (oids.length === 0)
+        return out;
+    const result = await rows(client, `SELECT a.attrelid::int AS relid, a.attname AS name, a.attnum AS ordinal,
+            format_type(a.atttypid, a.atttypmod) AS data_type,
+            a.attnotnull AS not_null,
+            pg_get_expr(ad.adbin, ad.adrelid) AS default_expr,
+            CASE a.attidentity WHEN 'a' THEN 'always' WHEN 'd' THEN 'by default' ELSE NULL END AS identity,
+            CASE a.attgenerated WHEN 's' THEN 'stored' ELSE NULL END AS generated,
+            (SELECT co.collname::text FROM pg_catalog.pg_collation co
+              WHERE co.oid = a.attcollation AND a.attcollation <> t.typcollation) AS collation,
+            col_description(a.attrelid, a.attnum) AS comment
+       FROM pg_catalog.pg_attribute a
+       JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
+       LEFT JOIN pg_catalog.pg_attrdef ad ON ad.adrelid = a.attrelid AND ad.adnum = a.attnum
+      WHERE a.attrelid = ANY($1) AND a.attnum > 0 AND NOT a.attisdropped
+      ORDER BY a.attrelid, a.attnum`, [oids]);
+    for (const r of result) {
+        const list = out.get(r.relid) ?? [];
+        list.push({
+            name: r.name,
+            ordinal: r.ordinal,
+            dataType: r.data_type,
+            notNull: r.not_null,
+            defaultExpr: r.default_expr,
+            identity: r.identity === 'always' || r.identity === 'by default' ? r.identity : null,
+            generated: r.generated === 'stored' ? 'stored' : null,
+            collation: r.collation,
+            comment: r.comment,
+        });
+        out.set(r.relid, list);
+    }
+    return out;
+}
+/**
+ * Every constraint of the requested `contype`s for many relations in **one**
+ * query, as `pg_get_constraintdef` text.
+ *
+ * The definition text is the normalization: it is the server's own canonical
+ * rendering, so it already carries the constraint's column order, `MATCH`,
+ * `ON DELETE`, `DEFERRABLE`, `NOT VALID`, `NULLS NOT DISTINCT` and the
+ * reformatted check expression — all the things a hand-assembled structural
+ * comparison gets subtly wrong and then reports as a phantom change.
+ */
+export async function getConstraintDefsBatch(client, oids, contypes) {
+    const out = new Map();
+    if (oids.length === 0 || contypes.length === 0)
+        return out;
+    const result = await rows(client, `SELECT con.conrelid::int AS relid, con.conname AS name, con.contype::text AS contype,
+            pg_get_constraintdef(con.oid) AS definition,
+            rn.nspname AS ref_schema, rc.relname AS ref_table
+       FROM pg_catalog.pg_constraint con
+       LEFT JOIN pg_catalog.pg_class rc ON rc.oid = con.confrelid
+       LEFT JOIN pg_catalog.pg_namespace rn ON rn.oid = rc.relnamespace
+      WHERE con.conrelid = ANY($1) AND con.contype = ANY($2::"char"[])
+      ORDER BY con.conrelid, con.contype, con.conname`, [oids, contypes]);
+    for (const r of result) {
+        const list = out.get(r.relid) ?? [];
+        list.push({ name: r.name, type: r.contype, definition: r.definition, refSchema: r.ref_schema, refTable: r.ref_table });
+        out.set(r.relid, list);
+    }
+    return out;
+}
+/**
+ * `relrowsecurity`/`relforcerowsecurity`, the view definition, and the
+ * inheritance/partition attachment for many relations — one `pg_class` pass
+ * instead of one query per concern. `inherits` is the parent list for both
+ * classical inheritance and partitioning (a partition has exactly one);
+ * `partitionBound` is `null` for anything that is not a partition.
+ */
+export async function getRelationExtrasBatch(client, oids) {
+    const out = new Map();
+    if (oids.length === 0)
+        return out;
+    const result = await rows(client, `SELECT c.oid::int AS relid,
+            c.relrowsecurity AS rls_enabled,
+            c.relforcerowsecurity AS rls_forced,
+            CASE WHEN c.relkind IN ('v', 'm') THEN pg_get_viewdef(c.oid, true) END AS view_definition,
+            ARRAY(SELECT pn.nspname || '.' || pc.relname
+                    FROM pg_catalog.pg_inherits inh
+                    JOIN pg_catalog.pg_class pc ON pc.oid = inh.inhparent
+                    JOIN pg_catalog.pg_namespace pn ON pn.oid = pc.relnamespace
+                   WHERE inh.inhrelid = c.oid
+                   ORDER BY inh.inhseqno)::text[] AS inherits,
+            pg_get_expr(c.relpartbound, c.oid) AS partition_bound
+       FROM pg_catalog.pg_class c
+      WHERE c.oid = ANY($1)`, [oids]);
+    for (const r of result) {
+        out.set(r.relid, {
+            rowSecurityEnabled: r.rls_enabled,
+            rowSecurityForced: r.rls_forced,
+            viewDefinition: r.view_definition,
+            inherits: r.inherits ?? [],
+            partitionBound: r.partition_bound,
+        });
+    }
+    return out;
+}
+/** Row-level-security policies for many relations. Roles are `ORDER BY`ed — `oid = ANY(...)` alone returns them in physical catalog order, which is not stable. */
+export async function getPoliciesBatch(client, oids) {
+    const out = new Map();
+    if (oids.length === 0)
+        return out;
+    const COMMAND = { r: 'SELECT', a: 'INSERT', w: 'UPDATE', d: 'DELETE', '*': 'ALL' };
+    const result = await rows(client, `SELECT pol.polrelid::int AS relid, pol.polname AS name, pol.polcmd::text AS polcmd, pol.polpermissive AS permissive,
+            CASE WHEN pol.polroles = '{0}' THEN ARRAY['public']::text[]
+                 ELSE ARRAY(SELECT rolname FROM pg_catalog.pg_roles WHERE oid = ANY(pol.polroles) ORDER BY rolname)::text[] END AS roles,
+            pg_get_expr(pol.polqual, pol.polrelid) AS using_expr,
+            pg_get_expr(pol.polwithcheck, pol.polrelid) AS with_check_expr
+       FROM pg_catalog.pg_policy pol
+      WHERE pol.polrelid = ANY($1)
+      ORDER BY pol.polrelid, pol.polname`, [oids]);
+    for (const r of result) {
+        const list = out.get(r.relid) ?? [];
+        list.push({
+            name: r.name,
+            command: COMMAND[r.polcmd] ?? 'ALL',
+            permissive: r.permissive,
+            roles: r.roles,
+            using: r.using_expr,
+            withCheck: r.with_check_expr,
+        });
+        out.set(r.relid, list);
+    }
+    return out;
+}
+/** Sequence parameters for every sequence in `schemas` — the batched counterpart of {@link getSequenceDetail}. */
+export async function listSequenceDetails(client, schemas) {
+    if (schemas.length === 0)
+        return [];
+    const result = await rows(client, `SELECT c.oid::int AS oid, n.nspname AS schema, c.relname AS name,
+            pg_get_userbyid(c.relowner) AS owner, obj_description(c.oid, 'pg_class') AS comment,
+            s.data_type::text AS data_type, s.start_value::text AS start_value, s.min_value::text AS min_value,
+            s.max_value::text AS max_value, s.increment_by::text AS increment_by, s.cycle,
+            s.cache_size::text AS cache_size, s.last_value::text AS last_value
+       FROM pg_catalog.pg_class c
+       JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+       JOIN pg_catalog.pg_sequences s ON s.schemaname = n.nspname AND s.sequencename = c.relname
+      WHERE n.nspname = ANY($1) AND c.relkind = 'S'
+      ORDER BY n.nspname, c.relname`, [schemas]);
+    return result.map((r) => ({
+        oid: r.oid,
+        schema: r.schema,
+        name: r.name,
+        owner: r.owner,
+        comment: r.comment,
+        dataType: r.data_type,
+        startValue: r.start_value,
+        minValue: r.min_value,
+        maxValue: r.max_value,
+        incrementBy: r.increment_by,
+        cycle: r.cycle,
+        cacheSize: r.cache_size,
+        lastValue: r.last_value,
+    }));
+}
+/**
+ * {@link listFunctions} plus `pg_proc.prosrc`, so a changed function *body* is
+ * a visible schema change rather than a silent one. Deliberately not
+ * `pg_get_functiondef`, which {@link getFunctionDetails} uses: that function
+ * raises `ERROR: "…" is an aggregate function` for `prokind = 'a'`, and one
+ * aggregate anywhere in scope would fail a whole snapshot.
+ */
+export async function listFunctionSources(client, schemas) {
+    if (schemas.length === 0)
+        return [];
+    const result = await rows(client, `SELECT p.oid::int AS oid, n.nspname AS schema, p.proname AS name,
+            pg_get_function_identity_arguments(p.oid) AS arg_types,
+            pg_get_function_result(p.oid) AS return_type,
+            l.lanname AS language, p.prokind AS kind,
+            obj_description(p.oid, 'pg_proc') AS comment,
+            p.prosrc AS body
+       FROM pg_catalog.pg_proc p
+       JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+       JOIN pg_catalog.pg_language l ON l.oid = p.prolang
+      WHERE n.nspname = ANY($1)
+      ORDER BY n.nspname, p.proname, p.oid`, [schemas]);
+    return result.map((r) => ({
+        oid: r.oid,
+        schema: r.schema,
+        name: r.name,
+        argTypes: r.arg_types,
+        returnType: r.return_type,
+        language: r.language,
+        kind: r.kind,
+        comment: r.comment,
+        body: r.body,
+    }));
+}
+const TG_BEFORE = 1 << 1; // 2
+const TG_INSTEAD = 1 << 6; // 64
+const TG_INSERT = 1 << 2; // 4
+const TG_DELETE = 1 << 3; // 8
+const TG_UPDATE = 1 << 4; // 16
+const TG_TRUNCATE = 1 << 5; // 32
+function decodeTriggerTiming(tgtype) {
+    if ((tgtype & TG_INSTEAD) !== 0)
+        return 'INSTEAD OF';
+    if ((tgtype & TG_BEFORE) !== 0)
+        return 'BEFORE';
+    return 'AFTER';
+}
+function decodeTriggerEvents(tgtype) {
+    const events = [];
+    if ((tgtype & TG_INSERT) !== 0)
+        events.push('INSERT');
+    if ((tgtype & TG_DELETE) !== 0)
+        events.push('DELETE');
+    if ((tgtype & TG_UPDATE) !== 0)
+        events.push('UPDATE');
+    if ((tgtype & TG_TRUNCATE) !== 0)
+        events.push('TRUNCATE');
+    return events;
+}
+export async function getTriggers(client, rel) {
+    const result = await rows(client, `SELECT t.tgname AS name, t.tgtype::int2 AS tgtype, pg_get_triggerdef(t.oid) AS definition
+       FROM pg_catalog.pg_trigger t
+      WHERE t.tgrelid = $1 AND NOT t.tgisinternal
+      ORDER BY t.tgname`, [rel.oid]);
+    return result.map((r) => ({
+        name: r.name,
+        timing: decodeTriggerTiming(r.tgtype),
+        events: decodeTriggerEvents(r.tgtype),
+        definition: r.definition,
+    }));
+}
+/** Non-internal triggers for many relations — the batched counterpart of {@link getTriggers}, for `snapshot/capture.ts`. */
+export async function getTriggersBatch(client, oids) {
+    const out = new Map();
+    if (oids.length === 0)
+        return out;
+    const result = await rows(client, `SELECT t.tgrelid::int AS relid, t.tgname AS name, t.tgtype::int2 AS tgtype, pg_get_triggerdef(t.oid) AS definition
+       FROM pg_catalog.pg_trigger t
+      WHERE t.tgrelid = ANY($1) AND NOT t.tgisinternal
+      ORDER BY t.tgrelid, t.tgname`, [oids]);
+    for (const r of result) {
+        const list = out.get(r.relid) ?? [];
+        list.push({ name: r.name, timing: decodeTriggerTiming(r.tgtype), events: decodeTriggerEvents(r.tgtype), definition: r.definition });
+        out.set(r.relid, list);
+    }
+    return out;
+}
+export async function getRowSecurity(client, rel) {
+    const [flags] = await rows(client, `SELECT relrowsecurity AS enabled, relforcerowsecurity AS forced
+       FROM pg_catalog.pg_class WHERE oid = $1`, [rel.oid]);
+    const COMMAND = { r: 'SELECT', a: 'INSERT', w: 'UPDATE', d: 'DELETE', '*': 'ALL' };
+    const policyRows = await rows(client, `SELECT pol.polname AS name, pol.polcmd::text AS polcmd, pol.polpermissive AS permissive,
+            CASE WHEN pol.polroles = '{0}' THEN ARRAY['public']::text[]
+                 ELSE ARRAY(SELECT rolname FROM pg_catalog.pg_roles WHERE oid = ANY(pol.polroles) ORDER BY rolname)::text[] END AS roles,
+            pg_get_expr(pol.polqual, pol.polrelid) AS using_expr,
+            pg_get_expr(pol.polwithcheck, pol.polrelid) AS with_check_expr
+       FROM pg_catalog.pg_policy pol
+      WHERE pol.polrelid = $1
+      ORDER BY pol.polname`, [rel.oid]);
+    return {
+        enabled: flags?.enabled ?? false,
+        forced: flags?.forced ?? false,
+        policies: policyRows.map((r) => ({
+            name: r.name,
+            command: COMMAND[r.polcmd] ?? 'ALL',
+            permissive: r.permissive,
+            roles: r.roles,
+            using: r.using_expr,
+            withCheck: r.with_check_expr,
+        })),
+    };
+}
+/** Table/view permissions — a thin `'table'`-kind wrapper over {@link getPermissionsByKind}, which is the fix for this function's former hardcoded `acldefault('r', …)` (only ever correct for tables/views; see that function's doc for the other four object kinds). */
+export async function getPermissions(client, rel) {
+    return getPermissionsByKind(client, 'table', rel.oid);
+}
+// ---------------------------------------------------------------------------
+// describe_object / get_schema composition helpers — inbound FKs, view
+// definitions, and the non-relation kinds resolveRelation does not cover
+// (sequences, functions, enum types). The latter three take plain bound
+// schema/name params, never a RelationRef: they are not relations
+// (relkind 'S'/pg_proc/pg_type), so there is nothing for resolveRelation to
+// resolve and no SafeIdent is needed — see core/identifiers.ts's module doc.
+// ---------------------------------------------------------------------------
+/** Owner/comment/estimated-row-count for one already-resolved relation, by oid — the single-object counterpart of {@link listRelations}. */
+export async function getRelationMeta(client, rel) {
+    const result = await rows(client, `SELECT pg_get_userbyid(c.relowner) AS owner, obj_description(c.oid, 'pg_class') AS comment,
+            NULLIF(c.reltuples, -1) AS estimated_rows
+       FROM pg_catalog.pg_class c
+      WHERE c.oid = $1`, [rel.oid]);
+    const r = result[0];
+    if (r === undefined)
+        return null;
+    return { owner: r.owner, comment: r.comment, estimatedRows: r.estimated_rows === null ? null : Math.round(r.estimated_rows) };
+}
+/** `pg_get_viewdef` — the reconstructed `SELECT` behind a view or materialized view. */
+export async function getViewDefinition(client, rel) {
+    const result = await rows(client, `SELECT pg_get_viewdef($1::oid, true) AS definition`, [rel.oid]);
+    return result[0]?.definition ?? null;
+}
+/**
+ * Foreign keys pointing AT `rel` from other tables — the mirror of
+ * {@link getForeignKeys}. An agent planning a delete needs these: they are
+ * what would block or cascade, not the FKs `rel` itself declares.
+ */
+export async function getInboundForeignKeys(client, rel) {
+    const ACTION = { a: 'NO ACTION', r: 'RESTRICT', c: 'CASCADE', n: 'SET NULL', d: 'SET DEFAULT' };
+    const result = await rows(client, `SELECT con.conname AS name, cn.nspname AS schema, cc.relname AS table,
+            ${ORDERED_COLUMNS_SUBQUERY('con.conkey', 'con.conrelid')} AS columns,
+            ${ORDERED_COLUMNS_SUBQUERY('con.confkey', 'con.confrelid')} AS ref_columns,
+            con.confupdtype AS on_update_code, con.confdeltype AS on_delete_code,
+            pg_get_constraintdef(con.oid) AS definition
+       FROM pg_catalog.pg_constraint con
+       JOIN pg_catalog.pg_class cc ON cc.oid = con.conrelid
+       JOIN pg_catalog.pg_namespace cn ON cn.oid = cc.relnamespace
+      WHERE con.confrelid = $1 AND con.contype = 'f'
+      ORDER BY cn.nspname, cc.relname, con.conname`, [rel.oid]);
+    return result.map((r) => ({
+        name: r.name,
+        schema: r.schema,
+        table: r.table,
+        columns: r.columns,
+        refColumns: r.ref_columns,
+        onUpdate: ACTION[r.on_update_code] ?? r.on_update_code,
+        onDelete: ACTION[r.on_delete_code] ?? r.on_delete_code,
+        definition: r.definition,
+    }));
+}
+/**
+ * Sequence parameters and current value by schema/name. `pg_sequences` is a
+ * `pg_catalog` system view (not `information_schema`), so this still honors
+ * design.md risk 5. Returns `null` when no such sequence exists.
+ */
+export async function getSequenceDetail(client, schema, name) {
+    const result = await rows(client, `SELECT c.oid::int AS oid, n.nspname AS schema, c.relname AS name,
+            pg_get_userbyid(c.relowner) AS owner, obj_description(c.oid, 'pg_class') AS comment,
+            s.data_type::text AS data_type, s.start_value::text AS start_value, s.min_value::text AS min_value,
+            s.max_value::text AS max_value, s.increment_by::text AS increment_by, s.cycle,
+            s.cache_size::text AS cache_size, s.last_value::text AS last_value
+       FROM pg_catalog.pg_class c
+       JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+       JOIN pg_catalog.pg_sequences s ON s.schemaname = n.nspname AND s.sequencename = c.relname
+      WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind = 'S'`, [schema, name]);
+    const r = result[0];
+    if (r === undefined)
+        return null;
+    return {
+        oid: r.oid,
+        schema: r.schema,
+        name: r.name,
+        owner: r.owner,
+        comment: r.comment,
+        dataType: r.data_type,
+        startValue: r.start_value,
+        minValue: r.min_value,
+        maxValue: r.max_value,
+        incrementBy: r.increment_by,
+        cycle: r.cycle,
+        cacheSize: r.cache_size,
+        lastValue: r.last_value,
+    };
+}
+/**
+ * Every overload named `schema.name`, each with its full `CREATE FUNCTION`
+ * body via `pg_get_functiondef`. Functions can be overloaded, so this always
+ * returns an array — never assume a single match.
+ */
+export async function getFunctionDetails(client, schema, name) {
+    const result = await rows(client, `SELECT p.oid::int AS oid, n.nspname AS schema, p.proname AS name,
+            pg_get_function_identity_arguments(p.oid) AS arg_types,
+            pg_get_function_result(p.oid) AS return_type,
+            l.lanname AS language, p.prokind AS kind,
+            obj_description(p.oid, 'pg_proc') AS comment,
+            pg_get_functiondef(p.oid) AS definition
+       FROM pg_catalog.pg_proc p
+       JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+       JOIN pg_catalog.pg_language l ON l.oid = p.prolang
+      WHERE n.nspname = $1 AND p.proname = $2
+      ORDER BY p.oid`, [schema, name]);
+    return result.map((r) => ({
+        oid: r.oid,
+        schema: r.schema,
+        name: r.name,
+        argTypes: r.arg_types,
+        returnType: r.return_type,
+        language: r.language,
+        kind: r.kind,
+        comment: r.comment,
+        definition: r.definition,
+    }));
+}
+export async function listRoles(client, namePattern) {
+    const result = await rows(client, `SELECT r.oid::int AS oid, r.rolname AS name, r.rolsuper AS superuser, r.rolinherit AS inherit,
+            r.rolcreaterole AS create_role, r.rolcreatedb AS create_db, r.rolcanlogin AS can_login,
+            r.rolreplication AS replication, r.rolbypassrls AS bypass_rls, r.rolconnlimit AS connection_limit,
+            r.rolvaliduntil::text AS valid_until,
+            ARRAY(SELECT m.rolname FROM pg_catalog.pg_auth_members am
+                    JOIN pg_catalog.pg_roles m ON m.oid = am.roleid
+                   WHERE am.member = r.oid ORDER BY m.rolname)::text[] AS member_of
+       FROM pg_catalog.pg_roles r
+      WHERE ($1::text IS NULL OR r.rolname ILIKE $1)
+      ORDER BY r.rolname`, [namePattern ?? null]);
+    return result.map((r) => ({
+        oid: r.oid,
+        name: r.name,
+        superuser: r.superuser,
+        inherit: r.inherit,
+        createRole: r.create_role,
+        createDb: r.create_db,
+        canLogin: r.can_login,
+        replication: r.replication,
+        bypassRls: r.bypass_rls,
+        connectionLimit: r.connection_limit,
+        validUntil: r.valid_until,
+        memberOf: r.member_of ?? [],
+    }));
+}
+/**
+ * Objects a role owns or otherwise blocks `DROP ROLE` on, rendered via
+ * `pg_describe_object` — the precondition `postgres_admin`'s `roles_drop`
+ * checks BEFORE attempting the drop, so the failure surfaces as a readable
+ * list with a next action instead of PostgreSQL's raw
+ * `2BP01 role "x" cannot be dropped because some objects depend on it`.
+ */
+export async function getRoleDependencies(client, roleOid) {
+    const result = await rows(client, `SELECT DISTINCT pg_catalog.pg_describe_object(dep.classid, dep.objid, dep.objsubid) AS object
+       FROM pg_catalog.pg_shdepend dep
+      WHERE dep.refobjid = $1 AND dep.refclassid = 'pg_catalog.pg_authid'::regclass
+      ORDER BY 1`, [roleOid]);
+    return result.map((r) => r.object);
+}
+/** `pg_available_extensions` — every extension whose control file is on this server, installed or not. Complements {@link listExtensions}, which is installed-only. */
+export async function listAvailableExtensions(client, namePattern) {
+    const result = await rows(client, `SELECT name, default_version, installed_version, comment
+       FROM pg_catalog.pg_available_extensions
+      WHERE ($1::text IS NULL OR name ILIKE $1)
+      ORDER BY name`, [namePattern ?? null]);
+    return result.map((r) => ({ name: r.name, defaultVersion: r.default_version, installedVersion: r.installed_version, comment: r.comment }));
+}
+/** Exported for `test/unit/admin.test.ts` — the fixed table {@link getPermissionsByKind} splices `typeCode` from; asserting the five mappings directly is cheaper than mocking a `PoolClient` to exercise it indirectly. */
+export const ACL_SOURCE = {
+    table: { table: 'pg_catalog.pg_class', aclCol: 'relacl', ownerCol: 'relowner', typeCode: 'r' },
+    sequence: { table: 'pg_catalog.pg_class', aclCol: 'relacl', ownerCol: 'relowner', typeCode: 'S' },
+    function: { table: 'pg_catalog.pg_proc', aclCol: 'proacl', ownerCol: 'proowner', typeCode: 'f' },
+    database: { table: 'pg_catalog.pg_database', aclCol: 'datacl', ownerCol: 'datdba', typeCode: 'd' },
+    schema: { table: 'pg_catalog.pg_namespace', aclCol: 'nspacl', ownerCol: 'nspowner', typeCode: 'n' },
+};
+/** The generalized form of {@link getPermissions} — correct for any of the five ACL-bearing catalogs, keyed by {@link AclObjectKind}. */
+export async function getPermissionsByKind(client, kind, oid) {
+    const src = ACL_SOURCE[kind];
+    return rows(client, `SELECT CASE WHEN a.grantee = 0 THEN 'public' ELSE a.grantee::regrole::text END AS grantee,
+            a.privilege_type AS privilege, a.is_grantable AS grantable
+       FROM ${src.table} t,
+            LATERAL aclexplode(COALESCE(t.${src.aclCol}, acldefault('${src.typeCode}', t.${src.ownerCol}))) AS a
+      WHERE t.oid = $1
+      ORDER BY 1, 2`, [oid]);
+}
+/** `pg_stat_activity`, this database only by default (`datname = current_database()`) — set `allDatabases` to see the whole cluster. */
+export async function listSessions(client, allDatabases = false) {
+    const result = await rows(client, `SELECT pid, usename, datname, client_addr::text AS client_addr, application_name,
+            backend_start::text AS backend_start, query_start::text AS query_start,
+            state, wait_event_type, wait_event, backend_type, query
+       FROM pg_catalog.pg_stat_activity
+      WHERE $1::bool OR datname = current_database()
+      ORDER BY pid`, [allDatabases]);
+    return result.map((r) => ({
+        pid: r.pid,
+        usename: r.usename,
+        datname: r.datname,
+        clientAddr: r.client_addr,
+        applicationName: r.application_name,
+        backendStart: r.backend_start,
+        queryStart: r.query_start,
+        state: r.state,
+        waitEventType: r.wait_event_type,
+        waitEvent: r.wait_event,
+        backendType: r.backend_type,
+        query: r.query,
+    }));
+}
+export async function getBackendPid(client) {
+    const result = await rows(client, `SELECT pg_backend_pid() AS pid`, []);
+    return result[0]?.pid ?? -1;
+}
+/** `backend_type`/`usename` for one pid — lets `sessions_terminate` refuse a system process (`backend_type <> 'client backend'`) by kind, not merely by pid. `null` when the pid is gone. */
+export async function getBackendInfo(client, pid) {
+    const result = await rows(client, `SELECT backend_type, usename FROM pg_catalog.pg_stat_activity WHERE pid = $1`, [pid]);
+    const r = result[0];
+    return r === undefined ? null : { backendType: r.backend_type, usename: r.usename };
+}
+/** `pg_stat_user_tables` joined to `pg_statio_user_tables` by `relid` (not by name — see `_relation_detail.ts`'s module doc for why a name join is the wrong shape) plus `pg_total_relation_size`. `deadTuples`/`liveTuples` is the bloat *estimate* this server offers: a true bloat number needs `pgstattuple`, which is not assumed installed. */
+export async function getTableStats(client, schemas, namePattern) {
+    if (schemas.length === 0)
+        return [];
+    const result = await rows(client, `SELECT s.schemaname AS schema, s.relname AS name,
+            s.seq_scan::text AS seq_scan, s.idx_scan::text AS idx_scan,
+            s.n_tup_ins::text AS rows_inserted, s.n_tup_upd::text AS rows_updated, s.n_tup_del::text AS rows_deleted,
+            s.n_live_tup::text AS live_tuples, s.n_dead_tup::text AS dead_tuples,
+            s.last_vacuum::text AS last_vacuum, s.last_autovacuum::text AS last_autovacuum,
+            s.last_analyze::text AS last_analyze, s.last_autoanalyze::text AS last_autoanalyze,
+            io.heap_blks_read::text AS heap_blks_read, io.heap_blks_hit::text AS heap_blks_hit,
+            pg_total_relation_size(s.relid)::text AS total_bytes
+       FROM pg_catalog.pg_stat_user_tables s
+       LEFT JOIN pg_catalog.pg_statio_user_tables io ON io.relid = s.relid
+      WHERE s.schemaname = ANY($1) AND ($2::text IS NULL OR s.relname ILIKE $2)
+      ORDER BY s.schemaname, s.relname`, [schemas, namePattern ?? null]);
+    return result.map((r) => ({
+        schema: r.schema,
+        name: r.name,
+        seqScan: r.seq_scan,
+        idxScan: r.idx_scan,
+        rowsInserted: r.rows_inserted,
+        rowsUpdated: r.rows_updated,
+        rowsDeleted: r.rows_deleted,
+        liveTuples: r.live_tuples,
+        deadTuples: r.dead_tuples,
+        lastVacuum: r.last_vacuum,
+        lastAutovacuum: r.last_autovacuum,
+        lastAnalyze: r.last_analyze,
+        lastAutoanalyze: r.last_autoanalyze,
+        heapBlksRead: r.heap_blks_read,
+        heapBlksHit: r.heap_blks_hit,
+        totalBytes: r.total_bytes,
+    }));
+}
+export async function getIndexStats(client, schemas, namePattern) {
+    if (schemas.length === 0)
+        return [];
+    const result = await rows(client, `SELECT s.schemaname AS schema, s.relname AS table, s.indexrelname AS index,
+            s.idx_scan::text AS idx_scan, s.idx_tup_read::text AS idx_tup_read, s.idx_tup_fetch::text AS idx_tup_fetch,
+            io.idx_blks_read::text AS idx_blks_read, io.idx_blks_hit::text AS idx_blks_hit,
+            pg_relation_size(s.indexrelid)::text AS size_bytes
+       FROM pg_catalog.pg_stat_user_indexes s
+       LEFT JOIN pg_catalog.pg_statio_user_indexes io ON io.indexrelid = s.indexrelid
+      WHERE s.schemaname = ANY($1) AND ($2::text IS NULL OR s.relname ILIKE $2)
+      ORDER BY s.schemaname, s.relname, s.indexrelname`, [schemas, namePattern ?? null]);
+    return result.map((r) => ({
+        schema: r.schema,
+        table: r.table,
+        index: r.index,
+        idxScan: r.idx_scan,
+        idxTupRead: r.idx_tup_read,
+        idxTupFetch: r.idx_tup_fetch,
+        idxBlksRead: r.idx_blks_read,
+        idxBlksHit: r.idx_blks_hit,
+        sizeBytes: r.size_bytes,
+    }));
+}
+/** `state <> 'idle'` and running longer than `thresholdMs` — `query_start` is null for a backend between statements, hence the extra guard. */
+export async function getLongRunningQueries(client, thresholdMs) {
+    const result = await rows(client, `SELECT pid, usename, datname, state,
+            extract(epoch FROM (now() - query_start))::float8 * 1000 AS duration_ms_raw,
+            (extract(epoch FROM (now() - query_start)) * 1000)::bigint::text AS duration_ms,
+            query
+       FROM pg_catalog.pg_stat_activity
+      WHERE state IS DISTINCT FROM 'idle' AND query_start IS NOT NULL
+        AND extract(epoch FROM (now() - query_start)) * 1000 >= $1
+      ORDER BY query_start ASC`, [thresholdMs]);
+    return result.map((r) => ({ pid: r.pid, usename: r.usename, datname: r.datname, state: r.state, durationMs: r.duration_ms, query: r.query }));
+}
+/** The canonical `pg_locks` self-join for "who is blocking whom" — every lock field that matters for `NOT DISTINCT FROM` equality, per the PostgreSQL wiki's own reference query. */
+export async function getBlockedQueries(client) {
+    const result = await rows(client, `SELECT blocked.pid AS blocked_pid, blocked.usename AS blocked_user, blocked.query AS blocked_query,
+            blocking.pid AS blocking_pid, blocking.usename AS blocking_user, blocking.query AS blocking_query
+       FROM pg_catalog.pg_locks blocked_locks
+       JOIN pg_catalog.pg_stat_activity blocked ON blocked.pid = blocked_locks.pid
+       JOIN pg_catalog.pg_locks blocking_locks
+         ON blocking_locks.locktype = blocked_locks.locktype
+        AND blocking_locks.database IS NOT DISTINCT FROM blocked_locks.database
+        AND blocking_locks.relation IS NOT DISTINCT FROM blocked_locks.relation
+        AND blocking_locks.page IS NOT DISTINCT FROM blocked_locks.page
+        AND blocking_locks.tuple IS NOT DISTINCT FROM blocked_locks.tuple
+        AND blocking_locks.virtualxid IS NOT DISTINCT FROM blocked_locks.virtualxid
+        AND blocking_locks.transactionid IS NOT DISTINCT FROM blocked_locks.transactionid
+        AND blocking_locks.classid IS NOT DISTINCT FROM blocked_locks.classid
+        AND blocking_locks.objid IS NOT DISTINCT FROM blocked_locks.objid
+        AND blocking_locks.objsubid IS NOT DISTINCT FROM blocked_locks.objsubid
+        AND blocking_locks.pid <> blocked_locks.pid
+       JOIN pg_catalog.pg_stat_activity blocking ON blocking.pid = blocking_locks.pid
+      WHERE NOT blocked_locks.granted`, []);
+    return result.map((r) => ({
+        blockedPid: r.blocked_pid,
+        blockedUser: r.blocked_user,
+        blockedQuery: r.blocked_query,
+        blockingPid: r.blocking_pid,
+        blockingUser: r.blocking_user,
+        blockingQuery: r.blocking_query,
+    }));
+}
+/** One enum type by schema/name — the single-object counterpart of {@link listEnumTypes}. `null` when no such enum exists. */
+export async function getEnumTypeDetail(client, schema, name) {
+    const result = await rows(client, `SELECT t.oid::int AS oid, n.nspname AS schema, t.typname AS name,
+            ARRAY(SELECT e.enumlabel FROM pg_catalog.pg_enum e
+                   WHERE e.enumtypid = t.oid ORDER BY e.enumsortorder)::text[] AS labels,
+            obj_description(t.oid, 'pg_type') AS comment
+       FROM pg_catalog.pg_type t
+       JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+      WHERE t.typtype = 'e' AND n.nspname = $1 AND t.typname = $2`, [schema, name]);
+    return result[0] ?? null;
+}
+//# sourceMappingURL=catalog.js.map