@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/explorer/dependents.js

@@ -0,0 +1,222 @@
+// Beyond this many steps out the chain is followed no further.
+const MAX_DEPTH = 8;
+const MAX_DEPENDENTS = 500;
+/** The catalog and oid of the object; null when there is no such object. */
+async function locate(session, target) {
+    if (target.kind === 'column') {
+        const [row] = await session.rows(`SELECT c.oid::text AS oid, a.attnum::text AS attnum FROM pg_catalog.pg_class c
+			JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+			JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid AND NOT a.attisdropped
+			WHERE n.nspname = $1 AND c.relname = $2 AND a.attname = $3`, [target.schema, target.table, target.name]);
+        return row?.oid
+            ? { classid: 'pg_catalog.pg_class', objid: row.oid, subid: Number(row.attnum) }
+            : null;
+    }
+    if (target.kind === 'constraint') {
+        // What points at a primary key or unique constraint points at the index behind it.
+        const [row] = await session.rows(`SELECT CASE WHEN k.contype IN ('p', 'u') THEN k.conindid ELSE k.oid END::text AS oid,
+				CASE WHEN k.contype IN ('p', 'u') THEN 'i' ELSE 'c' END AS kind
+			FROM pg_catalog.pg_constraint k
+			JOIN pg_catalog.pg_class c ON c.oid = k.conrelid
+			JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+			WHERE n.nspname = $1 AND c.relname = $2 AND k.conname = $3`, [target.schema, target.table, target.name]);
+        if (!row?.oid)
+            return null;
+        return {
+            classid: row.kind === 'i' ? 'pg_catalog.pg_class' : 'pg_catalog.pg_constraint',
+            objid: row.oid,
+            subid: 0,
+        };
+    }
+    if (target.kind === 'index') {
+        const [row] = await session.rows(`SELECT c.oid::text AS oid FROM pg_catalog.pg_class c
+			JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+			WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind IN ('i', 'I')`, [target.schema, target.name]);
+        return row?.oid ? { classid: 'pg_catalog.pg_class', objid: row.oid, subid: 0 } : null;
+    }
+    if (target.kind === 'function') {
+        const [row] = await session.rows(`SELECT p.oid::text AS oid FROM pg_catalog.pg_proc p
+			JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+			WHERE n.nspname = $1 AND p.proname = $2
+				AND pg_catalog.pg_get_function_identity_arguments(p.oid) = $3`, [target.schema, target.name, target.args]);
+        return row?.oid ? { classid: 'pg_catalog.pg_proc', objid: row.oid, subid: 0 } : null;
+    }
+    if (target.kind === 'type') {
+        const [row] = await session.rows(`SELECT t.oid::text AS oid FROM pg_catalog.pg_type t
+			JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+			WHERE n.nspname = $1 AND t.typname = $2`, [target.schema, target.name]);
+        return row?.oid ? { classid: 'pg_catalog.pg_type', objid: row.oid, subid: 0 } : null;
+    }
+    const [row] = await session.rows(`SELECT c.oid::text AS oid FROM pg_catalog.pg_class c
+		JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+		WHERE n.nspname = $1 AND c.relname = $2`, [target.schema, target.name]);
+    return row?.oid ? { classid: 'pg_catalog.pg_class', objid: row.oid, subid: 0 } : null;
+}
+/**
+ * Everything that depends on the object, directly or through something else that does, nearest
+ * first; null when there is no such object. A view's rule is reported as the view, and a column
+ * default as its table.
+ */
+export async function listDependents(session, target) {
+    const found = await locate(session, target);
+    if (!found)
+        return null;
+    const rows = await session.rows(`WITH RECURSIVE
+		-- A view's rule stands for the view; a column default for the table it belongs to.
+		edge AS (
+			SELECT d.refclassid, d.refobjid, d.refobjsubid, d.deptype,
+				CASE WHEN d.classid = 'pg_catalog.pg_rewrite'::regclass
+					OR d.classid = 'pg_catalog.pg_attrdef'::regclass
+					THEN 'pg_catalog.pg_class'::regclass::oid ELSE d.classid END AS classid,
+				coalesce(r.ev_class, ad.adrelid, d.objid) AS objid,
+				CASE WHEN d.classid = 'pg_catalog.pg_rewrite'::regclass
+					OR d.classid = 'pg_catalog.pg_attrdef'::regclass THEN 0 ELSE d.objsubid END AS objsubid
+			FROM pg_catalog.pg_depend d
+			LEFT JOIN pg_catalog.pg_rewrite r
+				ON d.classid = 'pg_catalog.pg_rewrite'::regclass AND r.oid = d.objid
+			LEFT JOIN pg_catalog.pg_attrdef ad
+				ON d.classid = 'pg_catalog.pg_attrdef'::regclass AND ad.oid = d.objid
+			-- Internal dependencies are parts of the object itself (its row type, TOAST table, a view's
+			-- rule), except the index behind a primary key or unique constraint, which is worth naming.
+			WHERE d.deptype IN ('n', 'a') OR (d.deptype = 'i'
+				AND d.classid = 'pg_catalog.pg_class'::regclass
+				AND d.refclassid = 'pg_catalog.pg_constraint'::regclass)
+		),
+		walk AS (
+			SELECT e.classid, e.objid, e.objsubid, 1 AS depth, e.deptype = 'n' AS blocking,
+				NULL::oid AS via_classid, NULL::oid AS via_objid,
+				ARRAY[$1::regclass::oid, $2::oid, e.classid, e.objid] AS path
+			FROM edge e
+			WHERE e.refclassid = $1::regclass::oid AND e.refobjid = $2::oid
+				-- For a column, only what depends on that column.
+				AND ($3::int = 0 OR e.refobjsubid = $3::int)
+				AND NOT (e.classid = $1::regclass::oid AND e.objid = $2::oid)
+			UNION ALL
+			SELECT e.classid, e.objid, e.objsubid, w.depth + 1, w.blocking OR e.deptype = 'n',
+				w.classid, w.objid, w.path || ARRAY[e.classid, e.objid]
+			FROM walk w
+			JOIN edge e ON e.refclassid = w.classid AND e.refobjid = w.objid
+			WHERE w.depth < ${MAX_DEPTH}
+				AND NOT (e.classid = $1::regclass::oid AND e.objid = $2::oid)
+				-- Not back to something already on this path, so a cycle ends.
+				AND NOT EXISTS (SELECT 1 FROM generate_subscripts(w.path, 1) s
+					WHERE s % 2 = 1 AND w.path[s] = e.classid AND w.path[s + 1] = e.objid)
+		),
+		-- Each object once: the nearest way to it, blocking if any way to it is.
+		nearest AS (
+			SELECT DISTINCT ON (classid, objid, objsubid) classid, objid, objsubid, depth,
+				via_classid, via_objid,
+				bool_or(blocking) OVER (PARTITION BY classid, objid, objsubid) AS blocking
+			FROM walk
+			ORDER BY classid, objid, objsubid, depth, blocking DESC
+			LIMIT ${MAX_DEPENDENTS}
+		)
+		SELECT o.type, o.identity, x.depth, x.blocking,
+			CASE WHEN x.via_classid IS NULL THEN NULL
+				ELSE (pg_catalog.pg_identify_object(x.via_classid, x.via_objid, 0)).identity END AS via,
+			link.kind AS link_kind, link.schema AS link_schema, link.name AS link_name,
+			link.args AS link_args
+		FROM nearest x
+		CROSS JOIN LATERAL pg_catalog.pg_identify_object(x.classid, x.objid, x.objsubid) o
+		LEFT JOIN LATERAL (
+			-- Relations open themselves; constraints, triggers, indexes, policies and rules their table.
+			SELECT CASE WHEN c.relkind = 'S' THEN 'sequence' ELSE 'table' END AS kind,
+				n.nspname AS schema, c.relname AS name, NULL AS args
+			FROM pg_catalog.pg_class c
+			JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+			WHERE c.relkind IN ('r', 'p', 'v', 'm', 'f', 'S') AND c.oid = CASE
+				WHEN x.classid = 'pg_catalog.pg_class'::regclass THEN
+					coalesce((SELECT i.indrelid FROM pg_catalog.pg_index i WHERE i.indexrelid = x.objid), x.objid)
+				WHEN x.classid = 'pg_catalog.pg_constraint'::regclass THEN
+					(SELECT k.conrelid FROM pg_catalog.pg_constraint k WHERE k.oid = x.objid)
+				WHEN x.classid = 'pg_catalog.pg_trigger'::regclass THEN
+					(SELECT t.tgrelid FROM pg_catalog.pg_trigger t WHERE t.oid = x.objid)
+				WHEN x.classid = 'pg_catalog.pg_policy'::regclass THEN
+					(SELECT p.polrelid FROM pg_catalog.pg_policy p WHERE p.oid = x.objid)
+				END
+			UNION ALL
+			SELECT 'function', n.nspname, p.proname, pg_catalog.pg_get_function_identity_arguments(p.oid)
+			FROM pg_catalog.pg_proc p
+			JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+			WHERE x.classid = 'pg_catalog.pg_proc'::regclass AND p.oid = x.objid
+			UNION ALL
+			SELECT 'type', n.nspname, t.typname, NULL
+			FROM pg_catalog.pg_type t
+			JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+			WHERE x.classid = 'pg_catalog.pg_type'::regclass AND t.oid = x.objid
+				AND t.typtype IN ('e', 'c', 'd', 'r', 'm')
+				AND (t.typtype <> 'c' OR EXISTS (SELECT 1 FROM pg_catalog.pg_class c
+					WHERE c.oid = t.typrelid AND c.relkind = 'c'))
+			LIMIT 1
+		) link ON true
+		ORDER BY x.blocking DESC, x.depth, o.type, o.identity`, [found.classid, found.objid, found.subid]);
+    const dependents = rows.map((row) => {
+        const link = row.link_kind === null || row.link_schema === null || row.link_name === null
+            ? null
+            : row.link_kind === 'function'
+                ? {
+                    kind: 'function',
+                    schema: row.link_schema,
+                    name: row.link_name,
+                    args: row.link_args ?? '',
+                }
+                : {
+                    kind: row.link_kind,
+                    schema: row.link_schema,
+                    name: row.link_name,
+                };
+        return {
+            type: row.type ?? '',
+            identity: row.identity ?? '',
+            depth: Number(row.depth),
+            // A table's own checks, indexes and triggers go with it (or with the column they use), whatever
+            // the path to them in pg_depend.
+            blocking: row.blocking === 't' &&
+                !((target.kind === 'table' || target.kind === 'column') &&
+                    link?.kind === 'table' &&
+                    link.schema === target.schema &&
+                    link.name === (target.kind === 'column' ? target.table : target.name) &&
+                    /constraint|index|trigger|policy/.test(row.type ?? '')),
+            via: row.via ?? null,
+            link,
+        };
+    });
+    if (target.kind === 'column' || target.kind === 'constraint' || target.kind === 'index') {
+        return { dependents, mentions: [] };
+    }
+    return { dependents, mentions: await listMentions(session, target, found.objid) };
+}
+/**
+ * Functions and procedures whose source names the object as a whole word: Postgres keeps no
+ * record of what a body refers to (except a SQL function written with BEGIN ATOMIC), so these are
+ * only found by reading the text, and some may be false alarms.
+ */
+async function listMentions(session, target, objid) {
+    const rows = await session.rows(`SELECT n.nspname AS schema, p.proname AS name,
+			pg_catalog.pg_get_function_identity_arguments(p.oid) AS args, l.lanname AS language
+		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 l.lanname NOT IN ('c', 'internal')
+			AND n.nspname !~ '^pg_' AND n.nspname <> 'information_schema'
+			-- What an extension brings is not the user's to change.
+			AND NOT EXISTS (SELECT 1 FROM pg_catalog.pg_depend e
+				WHERE e.classid = 'pg_catalog.pg_proc'::regclass AND e.objid = p.oid AND e.deptype = 'e')
+			AND NOT (p.oid = $2::oid AND $3)
+			AND p.prosrc ~* $1
+		ORDER BY n.nspname, p.proname, args
+		LIMIT 200`, [
+        // The name as a word of its own, so "users" does not find "users_archive"; a quoted name
+        // matches too, since the quote is not part of a word.
+        `(^|[^a-z0-9_$])${escapeRegex(target.name)}($|[^a-z0-9_$])`,
+        objid,
+        target.kind === 'function',
+    ]);
+    return rows.map((row) => ({
+        schema: row.schema ?? '',
+        name: row.name ?? '',
+        args: row.args ?? '',
+        language: row.language ?? '',
+    }));
+}
+const escapeRegex = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/dist/explorer/design-load.js

@@ -0,0 +1,254 @@
+// Reads an existing table back as a TableDesign, so the designer can edit it. What a design cannot
+// say (exclusion constraints, indexes with a custom operator class or null ordering) is listed as
+// `untouched`: the page shows it, and the diff never changes it.
+import { BUILTIN_TYPES, } from './ddl.js';
+// Catalog names of types that SQL spells another way.
+const BUILTIN_BY_CATALOG = {
+    int2: 'smallint',
+    int4: 'integer',
+    int8: 'bigint',
+    float4: 'real',
+    float8: 'double precision',
+    bool: 'boolean',
+    bpchar: 'char',
+    varbit: 'varbit',
+    timestamp: 'timestamp',
+    timestamptz: 'timestamptz',
+};
+const ACTIONS = {
+    a: 'no action',
+    r: 'restrict',
+    c: 'cascade',
+    n: 'set null',
+    d: 'set default',
+};
+const METHODS = ['btree', 'hash', 'gin', 'gist', 'brin'];
+/** A catalog type, its modifier and array dimensions as a design type. */
+export function columnType(schema, name, typmod, array) {
+    const sql = BUILTIN_BY_CATALOG[name] ?? name;
+    const builtin = schema === 'pg_catalog' || sql === 'citext' || sql === 'hstore' ? sql : null;
+    const dims = array > 0 ? { array } : {};
+    const known = builtin !== null && BUILTIN_TYPES.some((type) => type.name === builtin);
+    if (!known)
+        return { name, schema, ...dims };
+    const sized = BUILTIN_TYPES.find((type) => type.name === builtin)?.sized;
+    let size = {};
+    if (typmod >= 0) {
+        if (sized === 'length')
+            size = { length: builtin === 'bit' || builtin === 'varbit' ? typmod : typmod - 4 };
+        else if (sized === 'numeric') {
+            const packed = typmod - 4;
+            size = { precision: (packed >> 16) & 0xffff, scale: packed & 0xffff };
+        }
+        else if (sized === 'precision') {
+            // An interval keeps its precision in the low 16 bits, 0xFFFF meaning none.
+            const precision = builtin === 'interval' ? typmod & 0xffff : typmod;
+            if (precision !== 0xffff)
+                size = { length: precision };
+        }
+    }
+    return { name: builtin, ...size, ...dims };
+}
+/** `(id * 2)` as `id * 2`: Postgres brackets a stored expression, and the builder brackets it again. */
+function unwrap(sql) {
+    if (!sql.startsWith('(') || !sql.endsWith(')'))
+        return sql;
+    let depth = 0;
+    for (let at = 0; at < sql.length; at++) {
+        if (sql[at] === '(')
+            depth++;
+        else if (sql[at] === ')' && --depth === 0 && at < sql.length - 1)
+            return sql;
+    }
+    return sql.slice(1, -1).trim();
+}
+function stripCheck(definition) {
+    const match = /^CHECK \((.*)\)( NOT VALID)?$/s.exec(definition.trim());
+    return match ? match[1].trim() : null;
+}
+/** Loads the table; null when there is no such table (or it is not an ordinary or partitioned one). */
+export async function loadDesign(session, table) {
+    const [head] = await session.rows(`SELECT c.oid::text AS oid, c.relkind AS kind, c.relpersistence = 'u' AS unlogged,
+			pg_catalog.obj_description(c.oid, 'pg_class') AS comment, c.reltuples::bigint::text AS rows
+		FROM pg_catalog.pg_class c
+		JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+		WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind IN ('r', 'p')`, [table.schema, table.name]);
+    if (!head?.oid)
+        return null;
+    const oid = head.oid;
+    const [version] = await session.rows(`SELECT (current_setting('server_version_num')::int / 10000) AS major`);
+    const columnRows = await session.rows(`SELECT a.attname AS name,
+			coalesce(et.nspname, tn.nspname) AS type_schema, coalesce(e.typname, t.typname) AS type_name,
+			a.atttypmod AS typmod, a.attndims AS dims, (t.typcategory = 'A' AND t.typelem <> 0) AS is_array,
+			a.attnotnull AS not_null, pg_catalog.pg_get_expr(d.adbin, d.adrelid) AS default,
+			a.attidentity AS identity, a.attgenerated AS generated,
+			pg_catalog.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
+		JOIN pg_catalog.pg_namespace tn ON tn.oid = t.typnamespace
+		LEFT JOIN pg_catalog.pg_type e ON t.typcategory = 'A' AND e.oid = t.typelem
+		LEFT JOIN pg_catalog.pg_namespace et ON et.oid = e.typnamespace
+		LEFT JOIN pg_catalog.pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+		WHERE a.attrelid = $1::oid AND a.attnum > 0 AND NOT a.attisdropped
+		ORDER BY a.attnum`, [oid]);
+    const columns = columnRows.map((row) => {
+        const generated = row.generated === 's';
+        const identity = row.identity === 'a' ? 'always' : row.identity === 'd' ? 'by default' : null;
+        const array = row.is_array === 't' ? Math.max(Number(row.dims), 1) : 0;
+        return {
+            name: row.name ?? '',
+            type: columnType(row.type_schema ?? '', row.type_name ?? '', Number(row.typmod), array),
+            ...(row.not_null === 't' ? { notNull: true } : {}),
+            ...(generated && row.default ? { generated: unwrap(row.default) } : {}),
+            ...(!generated && !identity && row.default ? { default: row.default } : {}),
+            ...(identity ? { identity } : {}),
+            ...(row.comment ? { comment: row.comment } : {}),
+        };
+    });
+    const untouched = [];
+    const constraintRows = await session.rows(`SELECT c.conname AS name, c.contype AS kind, pg_catalog.pg_get_constraintdef(c.oid, true) AS definition,
+			(SELECT string_agg(a.attname, E'\\t' ORDER BY k.ord) FROM unnest(c.conkey) WITH ORDINALITY k(attnum, ord)
+				JOIN pg_catalog.pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum) AS columns,
+			rn.nspname AS ref_schema, rc.relname AS ref_table,
+			(SELECT string_agg(a.attname, E'\\t' ORDER BY k.ord) FROM unnest(c.confkey) WITH ORDINALITY k(attnum, ord)
+				JOIN pg_catalog.pg_attribute a ON a.attrelid = c.confrelid AND a.attnum = k.attnum) AS ref_columns,
+			c.confdeltype AS del, c.confupdtype AS upd, c.confmatchtype = 'f' AS full,
+			c.condeferrable AS deferrable, c.condeferred AS deferred, c.conparentid <> 0 AS inherited
+		FROM pg_catalog.pg_constraint c
+		LEFT JOIN pg_catalog.pg_class rc ON rc.oid = c.confrelid
+		LEFT JOIN pg_catalog.pg_namespace rn ON rn.oid = rc.relnamespace
+		WHERE c.conrelid = $1::oid AND c.contype IN ('p', 'u', 'c', 'f', 'x')
+		ORDER BY array_position(ARRAY['p', 'u', 'f', 'c', 'x']::"char"[], c.contype), c.conname`, [oid]);
+    const constraints = [];
+    for (const row of constraintRows) {
+        const name = row.name ?? '';
+        const own = (row.columns ?? '').split('\t').filter(Boolean);
+        if (row.inherited === 't') {
+            untouched.push({ name, reason: 'inherited from the partitioned table' });
+        }
+        else if (row.kind === 'p') {
+            constraints.push({ kind: 'primary', name, columns: own });
+        }
+        else if (row.kind === 'u') {
+            constraints.push({
+                kind: 'unique',
+                name,
+                columns: own,
+                ...(/NULLS NOT DISTINCT/.test(row.definition ?? '') ? { nullsNotDistinct: true } : {}),
+            });
+        }
+        else if (row.kind === 'c') {
+            const expression = stripCheck(row.definition ?? '');
+            if (expression === null)
+                untouched.push({ name, reason: 'a check the designer cannot read' });
+            else
+                constraints.push({ kind: 'check', name, expression });
+        }
+        else if (row.kind === 'f') {
+            const onDelete = ACTIONS[row.del ?? 'a'];
+            const onUpdate = ACTIONS[row.upd ?? 'a'];
+            constraints.push({
+                kind: 'foreign',
+                name,
+                columns: own,
+                references: {
+                    schema: row.ref_schema ?? '',
+                    table: row.ref_table ?? '',
+                    columns: (row.ref_columns ?? '').split('\t').filter(Boolean),
+                },
+                ...(onDelete && onDelete !== 'no action' ? { onDelete } : {}),
+                ...(onUpdate && onUpdate !== 'no action' ? { onUpdate } : {}),
+                ...(row.full === 't' ? { matchFull: true } : {}),
+                ...(row.deferrable === 't' ? { deferrable: true } : {}),
+                ...(row.deferred === 't' ? { initiallyDeferred: true } : {}),
+            });
+        }
+        else {
+            untouched.push({ name, reason: 'an exclusion constraint' });
+        }
+    }
+    const indexRows = await session.rows(`SELECT ic.relname AS name, i.indisunique AS unique, am.amname AS method,
+			(SELECT string_agg(
+				CASE WHEN i.indkey[k - 1] = 0 THEN 'e:' ELSE 'c:' END || pg_catalog.pg_get_indexdef(i.indexrelid, k, true),
+				E'\\t' ORDER BY k) FROM generate_series(1, i.indnkeyatts) k) AS keys,
+			(SELECT string_agg(pg_catalog.pg_get_indexdef(i.indexrelid, k, true), E'\\t' ORDER BY k)
+				FROM generate_series(i.indnkeyatts + 1, i.indnatts) k) AS include,
+			pg_catalog.pg_get_expr(i.indpred, i.indrelid) AS predicate,
+			i.indoption::text AS options,
+			(SELECT bool_or(NOT oc.opcdefault) FROM unnest(i.indclass::oid[]) o(oid)
+				JOIN pg_catalog.pg_opclass oc ON oc.oid = o.oid) AS custom,
+			pg_catalog.pg_get_indexdef(i.indexrelid) AS definition
+		FROM pg_catalog.pg_index i
+		JOIN pg_catalog.pg_class ic ON ic.oid = i.indexrelid
+		JOIN pg_catalog.pg_am am ON am.oid = ic.relam
+		WHERE i.indrelid = $1::oid AND NOT i.indisprimary
+			-- An index behind a unique or exclusion constraint belongs to that constraint.
+			AND NOT EXISTS (SELECT 1 FROM pg_catalog.pg_constraint k
+				WHERE k.conindid = i.indexrelid AND k.contype IN ('u', 'x', 'p'))
+		ORDER BY ic.relname`, [oid]);
+    const indexes = [];
+    for (const row of indexRows) {
+        const name = row.name ?? '';
+        // indoption: bit 1 is DESC, bit 2 NULLS FIRST. DESC with NULLS FIRST is the default for DESC.
+        const options = (row.options ?? '').split(' ').map(Number);
+        const odd = options.some((option) => option !== 0 && option !== 3);
+        if (!METHODS.includes(row.method ?? '')) {
+            untouched.push({ name, reason: `a ${row.method} index` });
+            continue;
+        }
+        if (row.custom === 't' || odd || /\bCOLLATE\b/.test(row.definition ?? '')) {
+            untouched.push({ name, reason: 'an index with an operator class, collation or null ordering' });
+            continue;
+        }
+        const items = (row.keys ?? '').split('\t').map((entry, at) => {
+            const descending = options[at] === 3;
+            const body = entry.slice(2);
+            return entry.startsWith('c:')
+                ? { column: body, ...(descending ? { descending } : {}) }
+                : { expression: body, ...(descending ? { descending } : {}) };
+        });
+        const include = (row.include ?? '').split('\t').filter(Boolean);
+        indexes.push({
+            name,
+            ...(row.unique === 't' ? { unique: true } : {}),
+            ...(row.method !== 'btree' ? { method: row.method } : {}),
+            items,
+            ...(include.length > 0 ? { include } : {}),
+            ...(row.predicate ? { where: unwrap(row.predicate) } : {}),
+        });
+    }
+    const [partition] = head.kind === 'p'
+        ? await session.rows(`SELECT p.partstrat AS strategy, a.attname AS column, p.partnatts = 1 AS simple
+					FROM pg_catalog.pg_partitioned_table p
+					LEFT JOIN pg_catalog.pg_attribute a ON a.attrelid = p.partrelid AND a.attnum = p.partattrs[0]
+					WHERE p.partrelid = $1::oid`, [oid])
+        : [];
+    const methods = {
+        r: 'range',
+        l: 'list',
+        h: 'hash',
+    };
+    const method = methods[partition?.strategy ?? ''];
+    if (partition && (!method || partition.simple !== 't' || !partition.column)) {
+        untouched.push({ name: table.name, reason: 'a partition key the designer cannot read' });
+    }
+    const design = {
+        schema: table.schema,
+        name: table.name,
+        columns,
+        constraints,
+        indexes,
+        ...(head.unlogged === 't' ? { unlogged: true } : {}),
+        ...(head.comment ? { comment: head.comment } : {}),
+        ...(partition && method && partition.column
+            ? { partition: { method, column: partition.column } }
+            : {}),
+    };
+    const rows = Number(head.rows);
+    return {
+        design,
+        estimatedRows: Number.isFinite(rows) && rows >= 0 ? rows : null,
+        serverMajor: Number(version?.major ?? 0),
+        untouched,
+    };
+}

package/dist/explorer/design.js

@@ -0,0 +1,45 @@
+export class DesignRunError extends Error {
+    statement;
+    cause;
+    constructor(message, 
+    // Which statement failed, counting from 0.
+    statement, cause) {
+        super(message);
+        this.statement = statement;
+        this.cause = cause;
+    }
+}
+/** Runs the statements in one transaction; rolls everything back if any of them fails. */
+export async function runStatements(session, statements, describe) {
+    const started = performance.now();
+    await session.run('BEGIN');
+    let at = 0;
+    try {
+        for (; at < statements.length; at++)
+            await session.run(statements[at]);
+        await session.run('COMMIT');
+    }
+    catch (error) {
+        await session.run('ROLLBACK').catch(() => undefined);
+        throw new DesignRunError(describe(error), at, error);
+    }
+    return { durationMs: performance.now() - started };
+}
+/**
+ * Runs a plan: the statements that can go in a transaction in one, and then those that cannot (an
+ * index built CONCURRENTLY), one by one. A failure of the second kind leaves the first committed.
+ */
+export async function runPlan(session, plan, describe) {
+    const started = performance.now();
+    if (plan.transactional.length > 0)
+        await runStatements(session, plan.transactional, describe);
+    for (const [at, sql] of plan.concurrent.entries()) {
+        try {
+            await session.run(sql);
+        }
+        catch (error) {
+            throw new DesignRunError(`${describe(error)}\nThe statements before this one were already committed.`, plan.transactional.length + at, error);
+        }
+    }
+    return { durationMs: performance.now() - started };
+}

package/dist/explorer/edit.js

@@ -0,0 +1,108 @@
+// Editing the rows of a table: the UPDATE, INSERT or DELETE for one row, shown before it is run,
+// and run in a transaction that only commits when exactly the intended row changed.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { qualified } from './catalog.js';
+export class EditError extends Error {
+}
+// A value longer than this is cut short where the statement is shown, not where it is run.
+const SHOWN_LENGTH = 200;
+const literal = (value) => {
+    if (value === null)
+        return 'NULL';
+    const shown = value.length > SHOWN_LENGTH
+        ? `${value.slice(0, SHOWN_LENGTH)}... (${value.length} characters)`
+        : value;
+    return `'${shown.replaceAll("'", "''")}'`;
+};
+/** Whether rows of a table can be told apart, which editing needs: the names of its primary key. */
+export const primaryKeyOf = (columns) => columns.filter((column) => column.primaryKey).map((column) => column.name);
+function knownColumns(columns, names) {
+    for (const name of names) {
+        if (!columns.some((column) => column.name === name))
+            throw new EditError(`no column "${name}"`);
+    }
+}
+/** `"a" = $1 AND "b" = $2`, numbered from `first`; the key must be exactly the primary key. */
+function keyClause(columns, key, first) {
+    const primary = primaryKeyOf(columns);
+    if (primary.length === 0)
+        throw new EditError('this table has no primary key, so its rows cannot be edited');
+    const given = Object.keys(key);
+    if (given.length !== primary.length || !primary.every((name) => given.includes(name))) {
+        throw new EditError(`the key must be the primary key (${primary.join(', ')})`);
+    }
+    const values = primary.map((name) => {
+        const value = key[name];
+        if (typeof value !== 'string')
+            throw new EditError(`the key needs a value for "${name}"`);
+        return value;
+    });
+    return {
+        sql: primary.map((name, i) => `${quoteIdentifier(name)} = $${first + i}`).join(' AND '),
+        display: primary
+            .map((name, i) => `${quoteIdentifier(name)} = ${literal(values[i])}`)
+            .join(' AND '),
+        values,
+    };
+}
+export function buildEdit(table, columns, request) {
+    const target = qualified(table);
+    if (request.action === 'delete') {
+        const where = keyClause(columns, request.key, 1);
+        return {
+            sql: `DELETE FROM ${target} WHERE ${where.sql}`,
+            params: where.values,
+            display: `DELETE FROM ${target} WHERE ${where.display}`,
+        };
+    }
+    const names = Object.keys(request.values);
+    knownColumns(columns, names);
+    if (request.action === 'insert') {
+        if (names.length === 0) {
+            return {
+                sql: `INSERT INTO ${target} DEFAULT VALUES`,
+                params: [],
+                display: `INSERT INTO ${target} DEFAULT VALUES`,
+            };
+        }
+        const list = names.map(quoteIdentifier).join(', ');
+        const values = names.map((name) => request.values[name]);
+        return {
+            sql: `INSERT INTO ${target} (${list}) VALUES (${names.map((_, i) => `$${i + 1}`).join(', ')})`,
+            params: values,
+            display: `INSERT INTO ${target} (${list}) VALUES (${values.map(literal).join(', ')})`,
+        };
+    }
+    if (names.length === 0)
+        throw new EditError('nothing was changed');
+    const where = keyClause(columns, request.key, names.length + 1);
+    const values = names.map((name) => request.values[name]);
+    const set = names.map((name, i) => `${quoteIdentifier(name)} = $${i + 1}`).join(', ');
+    const shown = names
+        .map((name, i) => `${quoteIdentifier(name)} = ${literal(values[i])}`)
+        .join(', ');
+    return {
+        sql: `UPDATE ${target} SET ${set} WHERE ${where.sql}`,
+        params: [...values, ...where.values],
+        display: `UPDATE ${target} SET ${shown} WHERE ${where.display}`,
+    };
+}
+/**
+ * Runs the edit inside BEGIN ... COMMIT. When it did not change exactly one row (the row is gone,
+ * or a key matched more than it should) it is rolled back and says so.
+ */
+export async function applyEdit(session, edit) {
+    await session.run('BEGIN');
+    try {
+        const result = await session.run(edit.sql, edit.params);
+        if (result.rowCount !== 1) {
+            throw new EditError(`the statement changed ${result.rowCount ?? 0} rows, not 1, so nothing was changed`);
+        }
+        await session.run('COMMIT');
+        return result;
+    }
+    catch (error) {
+        await session.run('ROLLBACK').catch(() => undefined);
+        throw error;
+    }
+}

package/dist/explorer/explain.js

@@ -0,0 +1,37 @@
+/**
+ * The plan for a statement, with schemas and qualified column names so that advice can name them.
+ * Without ANALYZE the statement is planned but never run, so explaining
+ * an UPDATE or DELETE changes nothing.
+ */
+export async function explainQuery(session, sql) {
+    const statement = sql.replace(/[\s;]+$/, '');
+    const [row] = await session.rows(`EXPLAIN (VERBOSE, FORMAT JSON) ${statement}`);
+    const plan = JSON.parse(row?.['QUERY PLAN'] ?? '[]');
+    if (!plan[0]?.Plan)
+        throw new Error('Postgres did not return a plan');
+    return plan[0].Plan;
+}
+/**
+ * Runs the statement to measure it (EXPLAIN ANALYZE), so every step of the plan has its actual
+ * time, rows and buffers next to the planner's estimates. It runs inside a transaction that is
+ * always rolled back, so rows it inserts, updates or deletes are not kept; what cannot be undone
+ * (a sequence's nextval, a NOTIFY sent by a trigger, ...) still happens.
+ */
+export async function explainAnalyze(session, sql) {
+    const statement = sql.replace(/[\s;]+$/, '');
+    await session.run('BEGIN');
+    try {
+        const [row] = await session.rows(`EXPLAIN (ANALYZE, BUFFERS, VERBOSE, FORMAT JSON) ${statement}`);
+        const plan = JSON.parse(row?.['QUERY PLAN'] ?? '[]');
+        if (!plan[0]?.Plan)
+            throw new Error('Postgres did not return a plan');
+        return {
+            plan: plan[0].Plan,
+            planningMs: plan[0]['Planning Time'] ?? null,
+            executionMs: plan[0]['Execution Time'] ?? null,
+        };
+    }
+    finally {
+        await session.run('ROLLBACK').catch(() => undefined);
+    }
+}