@kazurolabs/psql-explorer 0.1.0 → 0.3.0

package/dist/explorer/gucs.js

@@ -0,0 +1,31 @@
+export class GucError extends Error {
+}
+// Plain (work_mem) or custom (app.tenant_id): words joined by dots.
+const validName = /^[a-z_][a-z0-9_$]*(?:\.[a-z_][a-z0-9_$]*)*$/i;
+// These would lift the read only protection of the environment.
+const readOnlySettings = new Set(['default_transaction_read_only', 'transaction_read_only']);
+/** The settings a request asked for, from `[{name, value}]`; throws a GucError for anything else. */
+export function parseGucs(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new GucError('settings is a list of {name, value}');
+    return raw.map((item) => {
+        if (typeof item?.name !== 'string' || typeof item.value !== 'string') {
+            throw new GucError('settings is a list of {name, value}');
+        }
+        const name = item.name.trim().toLowerCase();
+        if (!validName.test(name))
+            throw new GucError(`"${item.name}" is not a setting name`);
+        return { name, value: item.value };
+    });
+}
+/** Sets each setting for the rest of the session; the Postgres error says if one is unknown or refused. */
+export async function applyGucs(session, gucs) {
+    for (const { name, value } of gucs) {
+        if (session.readOnly && readOnlySettings.has(name)) {
+            throw new GucError(`${name} cannot be changed: this environment is read only`);
+        }
+        await session.rows('SELECT pg_catalog.set_config($1, $2, false)', [name, value]);
+    }
+}

package/dist/explorer/profile.js

@@ -0,0 +1,102 @@
+// What a column holds, worked out from a sample so it stays fast on big tables.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { qualified } from './catalog.js';
+import { withStatementTimeout } from './timeout.js';
+export const SAMPLE_ROWS = 10_000;
+export const PROFILE_TIMEOUT_MS = 8000;
+export const HISTOGRAM_BUCKETS = 10;
+const numberType = /^(smallint|integer|bigint|numeric|decimal|real|double precision)\b/;
+const dateType = /^(date|timestamp)\b/;
+const errorCode = (error) => error?.code ?? '';
+/** The size of a sample that holds about SAMPLE_ROWS rows of a table of `estimated` rows, in percent. */
+export const samplePercent = (estimated) => Math.min(100, Math.max(0.0001, (SAMPLE_ROWS / estimated) * 100));
+const parse = (text) => (text === null ? [] : (JSON.parse(text) ?? []));
+/** Counts by bucket number (from 1), with the empty buckets filled in. */
+const bucketsOf = (found) => {
+    const counts = Array.from({ length: HISTOGRAM_BUCKETS }, () => 0);
+    for (const { bucket, count } of found)
+        counts[Number(bucket) - 1] = Number(count);
+    return counts;
+};
+/** Profiles one column of a table or view. Throws if the column does not exist. */
+export async function profileColumn(session, table, column) {
+    const [info] = await session.rows(`SELECT pg_catalog.format_type(a.atttypid, a.atttypmod) AS type, c.relkind AS kind,
+			c.reltuples::float8 AS tuples
+		FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
+		WHERE a.attrelid = $1::regclass AND a.attname = $2 AND a.attnum > 0 AND NOT a.attisdropped`, [qualified(table), column]);
+    if (!info)
+        throw new Error(`no column "${column}" in ${table.schema}.${table.name}`);
+    const type = info.type ?? '';
+    const tuples = Number(info.tuples ?? -1);
+    const estimatedRows = tuples >= 0 ? Math.round(tuples) : null;
+    // A table sampled by pages is random; a view, or a table nobody has analyzed, gives its first rows.
+    const sampleable = info.kind === 'r' || info.kind === 'm';
+    let source;
+    let from;
+    if (estimatedRows !== null && estimatedRows <= SAMPLE_ROWS * 2) {
+        source = 'all';
+        from = qualified(table);
+    }
+    else if (sampleable && estimatedRows !== null) {
+        source = 'sample';
+        from = `${qualified(table)} TABLESAMPLE SYSTEM (${samplePercent(estimatedRows).toFixed(4)})`;
+    }
+    else {
+        source = 'first';
+        from = `(SELECT * FROM ${qualified(table)} LIMIT ${SAMPLE_ROWS}) AS head`;
+    }
+    const name = quoteIdentifier(column);
+    // The first try compares the values themselves; types that cannot be compared (json, xml,
+    // point...) are compared as text instead, without min, max and a histogram.
+    const query = (orderable) => {
+        const value = orderable ? 'v' : 'v::text';
+        const number = numberType.test(type)
+            ? 'v::numeric'
+            : dateType.test(type)
+                ? 'extract(epoch from v)::numeric'
+                : null;
+        const histogram = orderable && number
+            ? `(SELECT json_agg(json_build_object('bucket', h.bucket, 'count', h.count)) FROM (
+					SELECT LEAST(width_bucket(${number}, r.lo, r.hi, ${HISTOGRAM_BUCKETS}), ${HISTOGRAM_BUCKETS}) AS bucket,
+						count(*) AS count
+					FROM s, (SELECT min(${number}) AS lo, max(${number}) AS hi FROM s WHERE v IS NOT NULL) r
+					WHERE v IS NOT NULL AND r.hi > r.lo GROUP BY 1) h)`
+            : 'NULL';
+        return `WITH s AS MATERIALIZED (SELECT ${name} AS v FROM ${from})
+			SELECT (SELECT count(*) FROM s) AS total,
+				(SELECT count(*) FROM s WHERE v IS NULL) AS nulls,
+				(SELECT count(DISTINCT ${value}) FROM s) AS distinct,
+				(SELECT json_agg(t) FROM (
+					SELECT ${value}::text AS value, count(*) AS count FROM s WHERE v IS NOT NULL
+					GROUP BY ${value} ORDER BY 2 DESC, 1 LIMIT 10) t) AS top,
+				${orderable ? '(SELECT min(v)::text FROM s)' : 'NULL'} AS min,
+				${orderable ? '(SELECT max(v)::text FROM s)' : 'NULL'} AS max,
+				${histogram} AS histogram`;
+    };
+    const [row] = await withStatementTimeout(session, PROFILE_TIMEOUT_MS, async () => {
+        try {
+            return await session.rows(query(true));
+        }
+        catch (error) {
+            // 42883: no operator or function for the type; 42804: the types do not match.
+            if (!['42883', '42804', '22003', '22P02'].includes(errorCode(error)))
+                throw error;
+            return session.rows(query(false));
+        }
+    });
+    const total = Number(row?.total ?? 0);
+    return {
+        source,
+        sampleRows: total,
+        estimatedRows,
+        nullFraction: total === 0 ? 0 : Number(row?.nulls ?? 0) / total,
+        distinct: Number(row?.distinct ?? 0),
+        top: parse(row?.top ?? null).map((entry) => ({
+            value: entry.value,
+            count: Number(entry.count),
+        })),
+        min: row?.min ?? null,
+        max: row?.max ?? null,
+        histogram: row?.histogram ? bucketsOf(parse(row.histogram)) : null,
+    };
+}

package/dist/explorer/references.js

@@ -0,0 +1,95 @@
+// Foreign keys between tables: where a row points, and which rows point at it.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { qualified } from './catalog.js';
+import { withStatementTimeout } from './timeout.js';
+const KEY_COLUMNS = `c.conname AS name, fn.nspname AS from_schema, fc.relname AS from_table,
+			tn.nspname AS to_schema, tc.relname AS to_table,
+			(SELECT json_agg(a.attname ORDER BY k.ord)
+				FROM unnest(c.conkey) WITH ORDINALITY AS k(attnum, ord)
+				JOIN pg_catalog.pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum) AS from_columns,
+			(SELECT json_agg(a.attname ORDER BY k.ord)
+				FROM unnest(c.confkey) WITH ORDINALITY AS k(attnum, ord)
+				JOIN pg_catalog.pg_attribute a ON a.attrelid = c.confrelid AND a.attnum = k.attnum) AS to_columns`;
+const KEY_FROM = `FROM pg_catalog.pg_constraint c
+		JOIN pg_catalog.pg_class fc ON fc.oid = c.conrelid
+		JOIN pg_catalog.pg_namespace fn ON fn.oid = fc.relnamespace
+		JOIN pg_catalog.pg_class tc ON tc.oid = c.confrelid
+		JOIN pg_catalog.pg_namespace tn ON tn.oid = tc.relnamespace`;
+const keyOf = (row) => ({
+    name: row.name ?? '',
+    from: { schema: row.from_schema ?? '', name: row.from_table ?? '' },
+    to: { schema: row.to_schema ?? '', name: row.to_table ?? '' },
+    fromColumns: JSON.parse(row.from_columns ?? '[]'),
+    toColumns: JSON.parse(row.to_columns ?? '[]'),
+});
+/** Names a foreign key across the database (constraint names are only unique within a table). */
+export const foreignKeyId = (key) => JSON.stringify([key.from.schema, key.from.name, key.name]);
+/** Foreign keys of the table, and those of other tables that point at it. */
+export async function listForeignKeys(session, table) {
+    const rows = await session.rows(`SELECT ${KEY_COLUMNS}, c.conrelid = $1::regclass AS outgoing
+		${KEY_FROM}
+		WHERE c.contype = 'f' AND (c.conrelid = $1::regclass OR c.confrelid = $1::regclass)
+		ORDER BY fn.nspname, fc.relname, c.conname`, [qualified(table)]);
+    const outgoing = [];
+    const incoming = [];
+    for (const row of rows) {
+        const key = keyOf(row);
+        // A table that points at itself is both.
+        if (row.outgoing === 't' || row.outgoing === 'true')
+            outgoing.push(key);
+        if (key.to.schema === table.schema && key.to.name === table.name)
+            incoming.push(key);
+    }
+    return { outgoing, incoming };
+}
+/** Every foreign key that starts or ends in the schema. */
+export async function listSchemaForeignKeys(session, schema) {
+    const rows = await session.rows(`SELECT ${KEY_COLUMNS}
+		${KEY_FROM}
+		WHERE c.contype = 'f' AND (fn.nspname = $1 OR tn.nspname = $1)
+		ORDER BY fn.nspname, fc.relname, c.conname`, [schema]);
+    return rows.map(keyOf);
+}
+export const DEFAULT_COUNT_CAP = 1000;
+export const COUNT_TIMEOUT_MS = 3000;
+const timedOut = (error) => error?.code === '57014';
+/**
+ * How many rows of each referencing table point at the row of `table` with these values (by
+ * column name). Counting stops at `cap` per table, and a count that takes longer than
+ * COUNT_TIMEOUT_MS is given up, so a row in a huge child table cannot hang the page.
+ */
+export async function countReferences(session, table, values, { cap = DEFAULT_COUNT_CAP } = {}) {
+    const { incoming } = await listForeignKeys(session, table);
+    return withStatementTimeout(session, COUNT_TIMEOUT_MS, async () => {
+        const counts = [];
+        for (const key of incoming) {
+            const parameters = key.toColumns.map((column) => values[column]);
+            // A null never matches a foreign key, so a row without the value has no children.
+            if (parameters.some((value) => value === undefined || value === null)) {
+                counts.push({ key, count: 0, more: false });
+                continue;
+            }
+            const where = key.fromColumns
+                .map((column, i) => `${quoteIdentifier(column)} = $${i + 1}`)
+                .join(' AND ');
+            try {
+                const [row] = await session.rows(`SELECT count(*) AS n FROM (SELECT 1 FROM ${qualified(key.from)} WHERE ${where} LIMIT ${cap + 1}) AS limited`, parameters);
+                const n = Number(row?.n ?? 0);
+                counts.push({ key, count: Math.min(n, cap), more: n > cap });
+            }
+            catch (error) {
+                counts.push({
+                    key,
+                    count: null,
+                    more: false,
+                    error: timedOut(error)
+                        ? `took longer than ${COUNT_TIMEOUT_MS / 1000}s`
+                        : error instanceof Error
+                            ? error.message
+                            : String(error),
+                });
+            }
+        }
+        return counts;
+    });
+}

package/dist/explorer/rows.js

@@ -2,17 +2,18 @@
 import { quoteIdentifier } from '../db/identifiers.js';
 import { qualified } from './catalog.js';
 export const DEFAULT_PAGE_SIZE = 100;
-export function browseSql(table, { orderBy = [] }) {
+export function browseSql(table, { orderBy = [], where }) {
     const order = orderBy
         .map(({ column, descending }) => `${quoteIdentifier(column)} ${descending ? 'DESC NULLS LAST' : 'ASC NULLS FIRST'}`)
         .join(', ');
-    return `SELECT * FROM ${qualified(table)}${order ? ` ORDER BY ${order}` : ''} LIMIT $1 OFFSET $2`;
+    const n = where?.params.length ?? 0;
+    return `SELECT * FROM ${qualified(table)}${where?.sql ?? ''}${order ? ` ORDER BY ${order}` : ''} LIMIT $${n + 1} OFFSET $${n + 2}`;
 }
 /** One page of a table's rows. */
 export function browseRows(session, table, options) {
-    return session.run(browseSql(table, options), [options.limit, options.offset ?? 0], {
-        maxRows: options.limit,
-    });
+    return session.run(browseSql(table, options), 
+    // One more row than wanted, which says whether there is a next page.
+    [...(options.where?.params ?? []), options.limit + 1, options.offset ?? 0], { maxRows: options.limit });
 }
 /** The exact number of rows; this reads the whole table, so the statement timeout bounds it. */
 export async function countRows(session, table) {
@@ -24,9 +25,7 @@ const readsRows = /^(?:select|with|values|table)\b/i;
 // SQLSTATE 42601 (syntax error) and 0A000 (not supported): the statement cannot be wrapped.
 const cannotWrap = (error) => ['42601', '0A000'].includes(error?.code ?? '');
 /** The statement without its leading comments and trailing semicolons. */
-const trimStatement = (sql) => sql
-    .replace(/^(?:\s+|--[^\n]*\n?|\/\*[\s\S]*?\*\/)+/, '')
-    .replace(/[\s;]+$/, '');
+const trimStatement = (sql) => sql.replace(/^(?:\s+|--[^\n]*\n?|\/\*[\s\S]*?\*\/)+/, '').replace(/[\s;]+$/, '');
 /**
  * One page of any statement's rows, without the statement needing a LIMIT of its own. A query is
  * wrapped in `SELECT * FROM (...) LIMIT OFFSET`, so the planner knows that few rows are wanted and
@@ -48,3 +47,18 @@ export async function runPage(session, sql, { limit, offset = 0 }) {
         return session.run(sql, [], { maxRows: limit });
     }
 }
+/** The most rows an export reads; more than this is cut off and says so. */
+export const EXPORT_MAX_ROWS = 100_000;
+/** Whether a statement is one that `exportRows` can read all of. */
+export const canExport = (sql) => readsRows.test(trimStatement(sql));
+/**
+ * Up to EXPORT_MAX_ROWS rows of a query, from its first. The statement is always wrapped, so an
+ * export can never run anything that is not a query, and never falls back to running it as it is.
+ */
+export function exportRows(session, sql) {
+    const statement = trimStatement(sql);
+    if (!readsRows.test(statement)) {
+        throw new Error('Only a query that returns rows can be exported');
+    }
+    return session.run(`SELECT * FROM (\n${statement}\n) AS export LIMIT ${EXPORT_MAX_ROWS + 1}`, [], { maxRows: EXPORT_MAX_ROWS });
+}

package/dist/explorer/schema-diff.js

@@ -0,0 +1,360 @@
+const relationKinds = {
+    r: 'table',
+    p: 'table',
+    v: 'view',
+    m: 'materialized view',
+    f: 'foreign table',
+};
+// The order kinds are listed in: what holds other things first.
+const kindOrder = [
+    'extension',
+    'schema',
+    'type',
+    'sequence',
+    'table',
+    'foreign table',
+    'view',
+    'materialized view',
+    'function',
+];
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * The text without its own schema's name in front of the names in it, so that "app.users" and
+ * "app_copy.users" read the same when one schema is compared with another. Names in other schemas
+ * keep theirs.
+ */
+export function unqualify(text, schema) {
+    const quoted = `"${schema.replaceAll('"', '""')}".`;
+    let out = text.split(quoted).join('');
+    if (/^[a-z_][a-z0-9_$]*$/.test(schema)) {
+        out = out.replace(new RegExp(`(?<![\\w$".])${escapeRegExp(schema)}\\.(?=[\\w"])`, 'g'), '');
+    }
+    return out;
+}
+// Excludes what an extension created, which its own version already accounts for.
+const notInExtension = (catalog, oid) => `NOT EXISTS (SELECT 1 FROM pg_catalog.pg_depend e
+		WHERE e.classid = '${catalog}'::regclass AND e.objid = ${oid} AND e.deptype = 'e')`;
+const userSchema = (column) => `${column} !~ '^pg_' AND ${column} <> 'information_schema' AND ($1::text IS NULL OR ${column} = $1)`;
+/** The structure of a database (or one schema of it) as text, for comparing with another. */
+export async function snapshotSchema(session, options = {}) {
+    const filter = [options.schema ?? null];
+    // With an empty search path Postgres writes every name with its schema, the same way on both
+    // sides, whatever each environment's search path is. Put back afterwards for the next statement.
+    const [saved] = await session.rows(`SELECT current_setting('search_path') AS path, pg_catalog.set_config('search_path', '', false)`);
+    try {
+        return { objects: await readObjects(session, filter) };
+    }
+    finally {
+        await session.rows(`SELECT pg_catalog.set_config('search_path', $1, false)`, [
+            saved?.path ?? '',
+        ]);
+    }
+}
+async function readObjects(session, filter) {
+    const objects = new Map();
+    const add = (kind, schema, name) => {
+        const key = objectKey({ kind, schema, name });
+        let object = objects.get(key);
+        if (!object) {
+            object = { kind, schema, name, parts: {} };
+            objects.set(key, object);
+        }
+        return object;
+    };
+    // Parts of a table, view, ... by its schema and name, whose kind is already known.
+    const relations = new Map();
+    const partsOf = (schema, name) => relations.get(`${schema}\0${name}`);
+    const set = (parts, part, value, schema) => {
+        if (parts)
+            parts[part] = unqualify(value, schema ?? '');
+    };
+    for (const row of await session.rows(`SELECT n.nspname AS name FROM pg_catalog.pg_namespace n
+		WHERE ${userSchema('n.nspname')} AND ${notInExtension('pg_catalog.pg_namespace', 'n.oid')}`, filter)) {
+        add('schema', row.name ?? '', row.name ?? '');
+    }
+    for (const row of await session.rows(`SELECT x.extname AS name, x.extversion AS version, n.nspname AS schema
+		FROM pg_catalog.pg_extension x JOIN pg_catalog.pg_namespace n ON n.oid = x.extnamespace`)) {
+        const parts = add('extension', '', row.name ?? '').parts;
+        parts.version = row.version ?? '';
+        parts.schema = row.schema ?? '';
+    }
+    for (const row of await session.rows(`SELECT n.nspname AS schema, c.relname AS name, c.relkind AS kind,
+			CASE WHEN c.relkind IN ('v', 'm') THEN pg_catalog.pg_get_viewdef(c.oid, true) END AS definition,
+			CASE WHEN c.relkind = 'p' THEN pg_catalog.pg_get_partkeydef(c.oid) END AS partition_key,
+			(SELECT pg_catalog.format('%I.%I', pn.nspname, pc.relname)
+				FROM pg_catalog.pg_inherits i
+				JOIN pg_catalog.pg_class pc ON pc.oid = i.inhparent
+				JOIN pg_catalog.pg_namespace pn ON pn.oid = pc.relnamespace
+				WHERE i.inhrelid = c.oid AND c.relispartition) AS parent,
+			CASE WHEN c.relispartition THEN pg_catalog.pg_get_expr(c.relpartbound, c.oid) END AS bound,
+			c.relrowsecurity AS rls
+		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') AND ${userSchema('n.nspname')}
+			AND ${notInExtension('pg_catalog.pg_class', 'c.oid')}`, filter)) {
+        const parts = add(relationKinds[row.kind ?? ''] ?? 'table', row.schema ?? '', row.name ?? '').parts;
+        relations.set(`${row.schema}\0${row.name}`, parts);
+        if (row.definition !== null)
+            set(parts, 'definition', row.definition.trim(), row.schema);
+        if (row.partition_key !== null)
+            set(parts, 'partitioned by', row.partition_key, row.schema);
+        if (row.parent !== null)
+            set(parts, 'partition of', `${row.parent} ${row.bound ?? ''}`.trim(), row.schema);
+        if (row.rls === 't')
+            parts['row level security'] = 'enabled';
+    }
+    // Columns of tables and foreign tables; a view's follow from its definition.
+    for (const row of await session.rows(`SELECT n.nspname AS schema, c.relname AS table, a.attname AS name,
+			pg_catalog.format_type(a.atttypid, a.atttypmod) AS type, a.attnotnull AS not_null,
+			pg_catalog.pg_get_expr(d.adbin, d.adrelid) AS default, a.attidentity AS identity,
+			a.attgenerated AS generated,
+			CASE WHEN a.attcollation <> t.typcollation THEN
+				(SELECT pg_catalog.format('%I.%I', cn.nspname, co.collname) FROM pg_catalog.pg_collation co
+					JOIN pg_catalog.pg_namespace cn ON cn.oid = co.collnamespace WHERE co.oid = a.attcollation)
+			END AS collation
+		FROM pg_catalog.pg_attribute a
+		JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
+		JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+		JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
+		LEFT JOIN pg_catalog.pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+		WHERE c.relkind IN ('r', 'p', 'f') AND a.attnum > 0 AND NOT a.attisdropped
+			AND ${userSchema('n.nspname')}
+		ORDER BY a.attnum`, filter)) {
+        const words = [row.type ?? ''];
+        if (row.collation)
+            words.push(`COLLATE ${row.collation}`);
+        if (row.not_null === 't')
+            words.push('NOT NULL');
+        if (row.identity === 'a')
+            words.push('GENERATED ALWAYS AS IDENTITY');
+        else if (row.identity === 'd')
+            words.push('GENERATED BY DEFAULT AS IDENTITY');
+        else if (row.generated === 's')
+            words.push(`GENERATED ALWAYS AS (${row.default}) STORED`);
+        else if (row.generated === 'v')
+            words.push(`GENERATED ALWAYS AS (${row.default}) VIRTUAL`);
+        else if (row.default !== null)
+            words.push(`DEFAULT ${row.default}`);
+        set(partsOf(row.schema, row.table), `column ${row.name}`, words.join(' '), row.schema);
+    }
+    for (const row of await session.rows(`SELECT n.nspname AS schema, c.relname AS table, i.relname AS name,
+			pg_catalog.pg_get_indexdef(x.indexrelid) AS definition
+		FROM pg_catalog.pg_index x
+		JOIN pg_catalog.pg_class i ON i.oid = x.indexrelid
+		JOIN pg_catalog.pg_class c ON c.oid = x.indrelid
+		JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+		WHERE ${userSchema('n.nspname')}
+		ORDER BY x.indisprimary DESC, i.relname`, filter)) {
+        set(partsOf(row.schema, row.table), `index ${row.name}`, row.definition ?? '', row.schema);
+    }
+    // Not-null constraints (Postgres 18) are left out: the column already says NOT NULL.
+    for (const row of await session.rows(`SELECT n.nspname AS schema, c.relname AS table, k.conname AS name,
+			pg_catalog.pg_get_constraintdef(k.oid, true) AS definition
+		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 k.contype <> 'n' AND ${userSchema('n.nspname')}
+		ORDER BY array_position(ARRAY['p', 'u', 'f', 'c', 'x', 't']::"char"[], k.contype), k.conname`, filter)) {
+        set(partsOf(row.schema, row.table), `constraint ${row.name}`, row.definition ?? '', row.schema);
+    }
+    for (const row of await session.rows(`SELECT n.nspname AS schema, c.relname AS table, t.tgname AS name,
+			pg_catalog.pg_get_triggerdef(t.oid, true) AS definition, t.tgenabled AS enabled
+		FROM pg_catalog.pg_trigger t
+		JOIN pg_catalog.pg_class c ON c.oid = t.tgrelid
+		JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+		WHERE NOT t.tgisinternal AND ${userSchema('n.nspname')}
+		ORDER BY t.tgname`, filter)) {
+        const disabled = row.enabled === 'D' ? ' (disabled)' : '';
+        set(partsOf(row.schema, row.table), `trigger ${row.name}`, `${row.definition}${disabled}`, row.schema);
+    }
+    for (const row of await session.rows(`SELECT schemaname AS schema, tablename AS table, policyname AS name, permissive,
+			array_to_string(roles, ', ') AS roles, cmd AS command, qual, with_check
+		FROM pg_catalog.pg_policies
+		WHERE ${userSchema('schemaname')}
+		ORDER BY policyname`, filter)) {
+        const words = [`AS ${row.permissive} FOR ${row.command} TO ${row.roles}`];
+        if (row.qual !== null)
+            words.push(`USING (${row.qual})`);
+        if (row.with_check !== null)
+            words.push(`WITH CHECK (${row.with_check})`);
+        set(partsOf(row.schema, row.table), `policy ${row.name}`, words.join(' '), row.schema);
+    }
+    for (const row of await session.rows(`SELECT n.nspname AS schema, p.proname AS name, pg_catalog.oidvectortypes(p.proargtypes) AS args,
+			p.prokind AS kind,
+			CASE WHEN p.prokind <> 'a' THEN pg_catalog.pg_get_functiondef(p.oid) END AS definition,
+			pg_catalog.pg_get_function_result(p.oid) AS returns
+		FROM pg_catalog.pg_proc p
+		JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+		WHERE ${userSchema('n.nspname')} AND ${notInExtension('pg_catalog.pg_proc', 'p.oid')}`, filter)) {
+        const schema = row.schema ?? '';
+        const name = `${row.name}(${unqualify(row.args ?? '', schema)})`;
+        const parts = add('function', schema, name).parts;
+        if (row.definition !== null)
+            set(parts, 'definition', row.definition.trim(), schema);
+        else
+            set(parts, 'aggregate returning', row.returns ?? '', schema);
+    }
+    for (const row of await session.rows(`SELECT s.schemaname AS schema, s.sequencename AS name, s.data_type::text AS type,
+			s.start_value::text AS start, s.increment_by::text AS increment, s.min_value::text AS min,
+			s.max_value::text AS max, s.cache_size::text AS cache, s.cycle,
+			(SELECT pg_catalog.format('%I.%I.%I', rn.nspname, r.relname, a.attname)
+				FROM pg_catalog.pg_depend d
+				JOIN pg_catalog.pg_class r ON r.oid = d.refobjid
+				JOIN pg_catalog.pg_namespace rn ON rn.oid = r.relnamespace
+				JOIN pg_catalog.pg_attribute a ON a.attrelid = d.refobjid AND a.attnum = d.refobjsubid
+				WHERE d.objid = c.oid AND d.classid = 'pg_catalog.pg_class'::regclass
+					AND d.refclassid = 'pg_catalog.pg_class'::regclass AND d.deptype IN ('a', 'i')
+				LIMIT 1) AS owned_by
+		FROM pg_catalog.pg_sequences s
+		JOIN pg_catalog.pg_namespace n ON n.nspname = s.schemaname
+		JOIN pg_catalog.pg_class c ON c.relname = s.sequencename AND c.relnamespace = n.oid
+		WHERE ${userSchema('s.schemaname')} AND ${notInExtension('pg_catalog.pg_class', 'c.oid')}`, filter)) {
+        const schema = row.schema ?? '';
+        const parts = add('sequence', schema, row.name ?? '').parts;
+        for (const field of ['type', 'start', 'increment', 'min', 'max', 'cache']) {
+            parts[field] = row[field] ?? '';
+        }
+        parts.cycle = row.cycle === 't' ? 'yes' : 'no';
+        if (row.owned_by !== null)
+            set(parts, 'owned by', row.owned_by ?? '', schema);
+    }
+    for (const row of await session.rows(`SELECT n.nspname AS schema, t.typname AS name, t.typtype AS kind,
+			(SELECT string_agg(pg_catalog.quote_literal(e.enumlabel), ', ' ORDER BY e.enumsortorder)
+				FROM pg_catalog.pg_enum e WHERE e.enumtypid = t.oid) AS labels,
+			CASE t.typtype
+				WHEN 'd' THEN pg_catalog.format_type(t.typbasetype, t.typtypmod)
+				WHEN 'r' THEN (SELECT pg_catalog.format_type(r.rngsubtype, NULL)
+					FROM pg_catalog.pg_range r WHERE r.rngtypid = t.oid)
+			END AS base,
+			t.typdefault AS default, t.typnotnull AS not_null
+		FROM pg_catalog.pg_type t
+		JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+		WHERE t.typtype IN ('e', 'c', 'd', 'r') AND ${userSchema('n.nspname')}
+			AND (t.typtype <> 'c' OR EXISTS (
+				SELECT 1 FROM pg_catalog.pg_class c WHERE c.oid = t.typrelid AND c.relkind = 'c'))
+			AND ${notInExtension('pg_catalog.pg_type', 't.oid')}`, filter)) {
+        const schema = row.schema ?? '';
+        const parts = add('type', schema, row.name ?? '').parts;
+        if (row.kind === 'e')
+            parts['enum labels'] = row.labels ?? '';
+        if (row.kind === 'd') {
+            set(parts, 'domain of', row.base ?? '', schema);
+            if (row.default !== null)
+                set(parts, 'default', row.default, schema);
+            if (row.not_null === 't')
+                parts['not null'] = 'yes';
+        }
+        if (row.kind === 'r')
+            set(parts, 'range of', row.base ?? '', schema);
+    }
+    // The attributes of composite types and the constraints of domains.
+    for (const row of await session.rows(`SELECT n.nspname AS schema, t.typname AS type, a.attname AS name,
+			pg_catalog.format_type(a.atttypid, a.atttypmod) AS type_of
+		FROM pg_catalog.pg_type t
+		JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+		JOIN pg_catalog.pg_class c ON c.oid = t.typrelid AND c.relkind = 'c'
+		JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+		WHERE ${userSchema('n.nspname')}
+		ORDER BY a.attnum`, filter)) {
+        const object = objects.get(objectKey({ kind: 'type', schema: row.schema ?? '', name: row.type ?? '' }));
+        if (object)
+            set(object.parts, `attribute ${row.name}`, row.type_of ?? '', row.schema);
+    }
+    for (const row of await session.rows(`SELECT n.nspname AS schema, t.typname AS type, k.conname AS name,
+			pg_catalog.pg_get_constraintdef(k.oid, true) AS definition
+		FROM pg_catalog.pg_constraint k
+		JOIN pg_catalog.pg_type t ON t.oid = k.contypid
+		JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+		WHERE ${userSchema('n.nspname')}
+		ORDER BY k.conname`, filter)) {
+        const object = objects.get(objectKey({ kind: 'type', schema: row.schema ?? '', name: row.type ?? '' }));
+        if (object)
+            set(object.parts, `constraint ${row.name}`, row.definition ?? '', row.schema);
+    }
+    return [...objects.values()];
+}
+const objectKey = (object) => `${object.kind}\0${object.schema}\0${object.name}`;
+// Beyond this many lines a side the comparison is not worth its time: all of a, then all of b.
+const MAX_DIFF_LINES = 3000;
+/** The lines of a and b in order, those they share once, by the longest common subsequence. */
+export function diffLines(a, b) {
+    const left = a.split('\n');
+    const right = b.split('\n');
+    if (left.length > MAX_DIFF_LINES || right.length > MAX_DIFF_LINES) {
+        return [
+            ...left.map((text) => ({ side: 'a', text })),
+            ...right.map((text) => ({ side: 'b', text })),
+        ];
+    }
+    // common[i][j]: how many lines left[i..] and right[j..] have in common.
+    const common = Array.from({ length: left.length + 1 }, () => new Uint32Array(right.length + 1));
+    for (let i = left.length - 1; i >= 0; i--) {
+        for (let j = right.length - 1; j >= 0; j--) {
+            common[i][j] =
+                left[i] === right[j]
+                    ? common[i + 1][j + 1] + 1
+                    : Math.max(common[i + 1][j], common[i][j + 1]);
+        }
+    }
+    const lines = [];
+    let i = 0;
+    let j = 0;
+    while (i < left.length || j < right.length) {
+        if (i < left.length && j < right.length && left[i] === right[j]) {
+            lines.push({ side: 'both', text: left[i] });
+            i++;
+            j++;
+        }
+        else if (j >= right.length || (i < left.length && common[i + 1][j] >= common[i][j + 1])) {
+            lines.push({ side: 'a', text: left[i++] });
+        }
+        else {
+            lines.push({ side: 'b', text: right[j++] });
+        }
+    }
+    return lines;
+}
+const partChange = (part, a, b) => a !== null && b !== null && (a.includes('\n') || b.includes('\n'))
+    ? { part, a, b, lines: diffLines(a, b) }
+    : { part, a, b };
+const sortKey = (object) => `${object.schema}\0${String(kindOrder.indexOf(object.kind)).padStart(2, '0')}\0${object.name}`;
+/** The objects and parts that differ between two snapshots, by schema, kind and name. */
+export function diffSnapshots(a, b, options = {}) {
+    const { schemas } = options;
+    // Side b's objects named as though in side a's schema, so the two line up.
+    const rename = (object) => schemas && object.schema === schemas.b
+        ? { ...object, schema: schemas.a, name: object.kind === 'schema' ? schemas.a : object.name }
+        : object;
+    const left = new Map(a.objects.map((object) => [objectKey(object), object]));
+    const right = new Map(b.objects.map(rename).map((object) => [objectKey(object), object]));
+    const changes = [];
+    let same = 0;
+    for (const key of new Set([...left.keys(), ...right.keys()])) {
+        const one = left.get(key);
+        const other = right.get(key);
+        const object = (one ?? other);
+        const names = [
+            ...new Set([...Object.keys(one?.parts ?? {}), ...Object.keys(other?.parts ?? {})]),
+        ];
+        const parts = names
+            .filter((part) => !one || !other || one.parts[part] !== other.parts[part])
+            .map((part) => partChange(part, one?.parts[part] ?? null, other?.parts[part] ?? null));
+        const status = !other ? 'only-a' : !one ? 'only-b' : parts.length > 0 ? 'changed' : null;
+        if (status)
+            changes.push({ kind: object.kind, schema: object.schema, name: object.name, status, parts });
+        else
+            same++;
+    }
+    changes.sort((x, y) => sortKey(x).localeCompare(sortKey(y)));
+    return { changes, same };
+}
+/** Reads both sides at once (one after the other on the same session) and compares them. */
+export async function compareSchemas(a, b, options = {}) {
+    const { schema } = options;
+    const withSchema = options.withSchema ?? schema;
+    const readA = () => snapshotSchema(a, schema ? { schema } : {});
+    const readB = () => snapshotSchema(b, withSchema ? { schema: withSchema } : {});
+    // One connection runs one statement at a time, and each read changes its search path meanwhile.
+    const [left, right] = a === b ? [await readA(), await readB()] : await Promise.all([readA(), readB()]);
+    return diffSnapshots(left, right, schema && withSchema && schema !== withSchema ? { schemas: { a: schema, b: withSchema } } : {});
+}