@pvidaal07/heydb 0.0.0-stage → 2.0.0-beta.0

package/lib/engines/postgres/catalog.ts

@@ -0,0 +1,390 @@
+import { formatName } from "../../model/names.ts";
+import { sortSnapshot } from "../../model/order.ts";
+import type {
+	Column,
+	ForeignKey,
+	Index,
+	ReferentialAction,
+	Routine,
+	Schema,
+	Snapshot,
+	Table,
+	Trigger,
+	Warning,
+} from "../../model/snapshot.ts";
+
+// Pure translation from PostgreSQL catalog rows to a Snapshot, like
+// lib/engines/mysql/catalog.ts: introspect.ts runs the queries and hands the
+// rows here, so every rule below is tested with hand-written rows.
+//
+// PostgreSQL has three levels, database → schema → table, and a connection
+// only ever reaches the database it was opened on. So a PostgreSQL snapshot
+// has exactly one Database (the connected one) with one Schema per captured
+// schema, and every foreign key points inside that same database.
+//
+// Row field names match the aliases used in introspect.ts queries.
+
+export interface PostgresCatalog {
+	/** Result of SHOW server_version, e.g. "16.4 (Debian 16.4-1.pgdg120+1)". */
+	readonly version: string;
+	readonly capturedAt: string;
+	/** The database the connection is on: the only one a snapshot can describe. */
+	readonly database: string;
+	/** Schemas the caller asked for; null means "every non-system schema". */
+	readonly requestedSchemas: readonly string[] | null;
+	/** Every schema of the database, system ones included. */
+	readonly schemas: readonly SchemaRow[];
+	readonly tables: readonly TableRow[];
+	readonly columns: readonly ColumnRow[];
+	readonly indexColumns: readonly IndexColumnRow[];
+	readonly foreignKeyColumns: readonly ForeignKeyColumnRow[];
+	readonly triggers: readonly TriggerRow[];
+	readonly routines: readonly RoutineRow[];
+}
+
+export interface SchemaRow {
+	readonly schemaName: string;
+	/** has_schema_privilege(..., 'USAGE'): without it no table of the schema can be queried. */
+	readonly usable: boolean;
+}
+
+export interface TableRow {
+	readonly schemaName: string;
+	readonly tableName: string;
+	/** pg_class.relkind: r table, p partitioned table, f foreign table, v view, m materialized view. */
+	readonly relkind: string;
+	/** pg_class.reltuples: an estimate, -1 when the table was never analyzed (PostgreSQL 14+). */
+	readonly reltuples: number | string;
+	/** Sum of the known estimates of a partitioned table's partitions; null when none is known. */
+	readonly partitionRows: number | string | null;
+	readonly comment: string | null;
+	/** pg_get_viewdef for views and materialized views; null for anything else. */
+	readonly viewDefinition: string | null;
+}
+
+export interface ColumnRow {
+	readonly schemaName: string;
+	readonly tableName: string;
+	readonly columnName: string;
+	readonly position: number;
+	/** format_type(): schema-qualified when the type is not in pg_catalog, e.g. "public.order_status". */
+	readonly dataType: string;
+	readonly notNull: boolean;
+	/** pg_get_expr of the default, or of the expression of a generated column. */
+	readonly defaultExpression: string | null;
+	/** pg_attribute.attidentity: "a" ALWAYS, "d" BY DEFAULT, "" not an identity column. */
+	readonly identity: string;
+	/** pg_attribute.attgenerated: "s" stored, "v" virtual (PostgreSQL 18), "" not generated. */
+	readonly generated: string;
+	readonly comment: string | null;
+	/** Only when it differs from the type's default collation, i.e. set explicitly. */
+	readonly collation: string | null;
+	/** Labels of an enum type in their declared order; null for any other type. */
+	readonly enumLabels: readonly string[] | null;
+}
+
+export interface IndexColumnRow {
+	readonly schemaName: string;
+	readonly tableName: string;
+	readonly indexName: string;
+	readonly primary: boolean;
+	readonly unique: boolean;
+	/** Access method from pg_am: btree, hash, gin, gist… */
+	readonly method: string;
+	/** 1-based position in the index key (INCLUDE columns are not part of the key). */
+	readonly position: number;
+	/** The column name, or the expression text for an expression index part. */
+	readonly columnName: string;
+}
+
+export interface ForeignKeyColumnRow {
+	readonly schemaName: string;
+	readonly tableName: string;
+	readonly constraintName: string;
+	readonly position: number;
+	readonly columnName: string;
+	readonly referencedSchema: string;
+	readonly referencedTable: string;
+	readonly referencedColumn: string;
+	/** pg_constraint.confupdtype / confdeltype: one letter, see FOREIGN_KEY_ACTIONS. */
+	readonly updateRule: string;
+	readonly deleteRule: string;
+}
+
+export interface TriggerRow {
+	readonly schemaName: string;
+	readonly tableName: string;
+	readonly triggerName: string;
+	/** pg_trigger.tgtype: a bit set, see TRIGGER_TYPE. */
+	readonly type: number;
+}
+
+export interface RoutineRow {
+	readonly schemaName: string;
+	readonly routineName: string;
+	/** pg_proc.prokind: f function, p procedure, a aggregate, w window function. */
+	readonly kind: string;
+}
+
+const SYSTEM_SCHEMAS = ["pg_catalog", "information_schema", "pg_toast"];
+// Every session gets its own pg_temp_N and pg_toast_temp_N for temporary tables.
+const TEMPORARY_SCHEMA = /^pg_(toast_)?temp_\d+$/;
+
+const FOREIGN_KEY_ACTIONS: Readonly<Record<string, ReferentialAction>> = {
+	a: "NO ACTION",
+	r: "RESTRICT",
+	c: "CASCADE",
+	n: "SET NULL",
+	d: "SET DEFAULT",
+};
+
+// The bits of pg_trigger.tgtype (src/include/catalog/pg_trigger.h). ROW (1)
+// says row or statement level, which the model does not record.
+const TRIGGER_TYPE = { before: 2, insert: 4, delete: 8, update: 16, truncate: 32, instead: 64 } as const;
+
+// Aggregates and window functions live in pg_proc too, but they are not
+// something a person calls like a function or a procedure, so they are left out.
+const ROUTINE_KINDS: Readonly<Record<string, Routine["kind"]>> = { f: "function", p: "procedure" };
+
+/**
+ * The schemas to capture, sorted: the requested ones that exist (names match
+ * exactly, as PostgreSQL identifiers are case-sensitive), or every schema but
+ * the system ones when none was requested.
+ */
+export function capturedSchemas(schemas: readonly SchemaRow[], requested: readonly string[] | null): string[] {
+	const names = schemas.map((row) => row.schemaName);
+	const chosen = requested === null ? names.filter((name) => !isSystemSchema(name)) : names.filter((name) => requested.includes(name));
+	return [...new Set(chosen)].sort(compareText);
+}
+
+export function buildSnapshot(catalog: PostgresCatalog): Snapshot {
+	const { database } = catalog;
+	const captured = capturedSchemas(catalog.schemas, catalog.requestedSchemas);
+	const capturedSet = new Set(captured);
+	const inCapturedSchema = (row: { schemaName: string }) => capturedSet.has(row.schemaName);
+
+	// Group every kind of row by its table once, so building each table is a lookup.
+	const columnsByTable = groupBy(catalog.columns.filter(inCapturedSchema), tableKey);
+	const indexesByTable = groupBy(catalog.indexColumns.filter(inCapturedSchema), tableKey);
+	const foreignKeysByTable = groupBy(catalog.foreignKeyColumns.filter(inCapturedSchema), tableKey);
+	const triggersByTable = groupBy(catalog.triggers.filter(inCapturedSchema), tableKey);
+	const tablesBySchema = groupBy(catalog.tables.filter(inCapturedSchema), (row) => row.schemaName);
+	const routinesBySchema = groupBy(catalog.routines.filter(inCapturedSchema), (row) => row.schemaName);
+
+	const schemas: Schema[] = captured.map((name) => ({
+		name,
+		tables: (tablesBySchema.get(name) ?? []).map((row) => {
+			const key = tableKey(row);
+			return buildTable(
+				database,
+				row,
+				columnsByTable.get(key) ?? [],
+				indexesByTable.get(key) ?? [],
+				foreignKeysByTable.get(key) ?? [],
+				triggersByTable.get(key) ?? [],
+			);
+		}),
+		routines: buildRoutines(routinesBySchema.get(name) ?? []),
+	}));
+
+	// Return the canonical order so every consumer sees the same snapshot,
+	// whatever order the server returned the rows in.
+	return sortSnapshot({
+		formatVersion: 1,
+		engine: { kind: "postgresql", version: catalog.version },
+		capturedAt: catalog.capturedAt,
+		databases: [{ name: database, schemas }],
+		warnings: [
+			...missingSchemaWarnings(database, catalog.requestedSchemas, catalog.schemas),
+			...unusableSchemaWarnings(database, catalog.schemas, capturedSet),
+			...hiddenViewDefinitionWarnings(database, schemas),
+		],
+	});
+}
+
+function buildTable(
+	database: string,
+	row: TableRow,
+	columnRows: readonly ColumnRow[],
+	indexRows: readonly IndexColumnRow[],
+	foreignKeyRows: readonly ForeignKeyColumnRow[],
+	triggerRows: readonly TriggerRow[],
+): Table {
+	// A materialized view is stored like a table (it has rows and indexes) but
+	// is defined by a SELECT, which is what a reader needs to know: the model
+	// has no separate kind for it, so it is a view with its definition.
+	const isView = row.relkind === "v" || row.relkind === "m";
+	return {
+		name: row.tableName,
+		kind: isView ? "view" : "table",
+		comment: row.comment ?? "",
+		storageEngine: null,
+		rowEstimate: rowEstimate(row),
+		columns: [...columnRows].sort((a, b) => a.position - b.position).map(buildColumn),
+		primaryKey: indexColumns(indexRows.filter((r) => r.primary)),
+		indexes: buildIndexes(indexRows.filter((r) => !r.primary)),
+		foreignKeys: buildForeignKeys(database, foreignKeyRows),
+		triggers: triggerRows.map(buildTrigger),
+		viewDefinition: isView ? row.viewDefinition : null,
+	};
+}
+
+function rowEstimate(row: TableRow): number | null {
+	if (row.relkind === "v") return null;
+	const estimate = Number(row.reltuples);
+	if (estimate >= 0) return Math.round(estimate);
+	// A partitioned table holds no rows itself; until it is analyzed, the sum of
+	// its partitions is the best estimate there is.
+	if (row.relkind === "p" && row.partitionRows !== null) return Math.round(Number(row.partitionRows));
+	return null;
+}
+
+function buildColumn(row: ColumnRow): Column {
+	const generated = row.generated === "s" || row.generated === "v";
+	const identity = row.identity === "a" ? "ALWAYS" : row.identity === "d" ? "BY DEFAULT" : null;
+	return {
+		name: row.columnName,
+		position: row.position,
+		type: row.enumLabels === null ? row.dataType : `${row.dataType} enum(${row.enumLabels.map(sqlText).join(",")})`,
+		nullable: !row.notNull,
+		// An identity column has no pg_attrdef row; its default is the identity
+		// itself, written as the DDL says it, so ALWAYS and BY DEFAULT differ.
+		default: generated ? null : identity !== null ? `GENERATED ${identity} AS IDENTITY` : row.defaultExpression,
+		comment: row.comment ?? "",
+		// serial and bigserial are a sequence default, the pre-identity idiom.
+		autoIncrement: identity !== null || (row.defaultExpression?.startsWith("nextval(") ?? false),
+		generated: generated ? { expression: row.defaultExpression ?? "", stored: row.generated === "s" } : null,
+		collation: row.collation,
+	};
+}
+
+function buildIndexes(rows: readonly IndexColumnRow[]): Index[] {
+	return [...groupBy(rows, (r) => r.indexName)].map(([name, parts]) => {
+		const first = parts[0]!; // groupBy never creates empty groups
+		return { name, columns: indexColumns(parts), unique: first.unique, method: first.method };
+	});
+}
+
+function indexColumns(rows: readonly IndexColumnRow[]): string[] {
+	return [...rows].sort((a, b) => Number(a.position) - Number(b.position)).map((r) => r.columnName);
+}
+
+function buildForeignKeys(database: string, rows: readonly ForeignKeyColumnRow[]): ForeignKey[] {
+	return [...groupBy(rows, (r) => r.constraintName)].map(([name, parts]) => {
+		const sorted = [...parts].sort((a, b) => Number(a.position) - Number(b.position));
+		const first = sorted[0]!;
+		const where = `${database}.${first.schemaName}.${first.tableName}.${name}`;
+		return {
+			name,
+			columns: sorted.map((r) => r.columnName),
+			references: {
+				database,
+				schema: first.referencedSchema,
+				table: first.referencedTable,
+				columns: sorted.map((r) => r.referencedColumn),
+			},
+			onDelete: foreignKeyAction(first.deleteRule, where),
+			onUpdate: foreignKeyAction(first.updateRule, where),
+		};
+	});
+}
+
+function foreignKeyAction(code: string, where: string): ReferentialAction {
+	const action = FOREIGN_KEY_ACTIONS[code];
+	if (action === undefined) throw new Error(`unknown foreign key action "${code}" on ${where}`);
+	return action;
+}
+
+function buildTrigger(row: TriggerRow): Trigger {
+	const type = Number(row.type);
+	const has = (bit: number) => (type & bit) !== 0;
+	const events: Trigger["events"][number][] = [];
+	if (has(TRIGGER_TYPE.insert)) events.push("INSERT");
+	if (has(TRIGGER_TYPE.update)) events.push("UPDATE");
+	if (has(TRIGGER_TYPE.delete)) events.push("DELETE");
+	if (has(TRIGGER_TYPE.truncate)) events.push("TRUNCATE");
+	return {
+		name: row.triggerName,
+		timing: has(TRIGGER_TYPE.instead) ? "INSTEAD OF" : has(TRIGGER_TYPE.before) ? "BEFORE" : "AFTER",
+		events,
+	};
+}
+
+// Overloads share a name (add_item(int), add_item(text)): the model lists
+// routines by name, so each name appears once per kind.
+function buildRoutines(rows: readonly RoutineRow[]): Routine[] {
+	const routines = new Map<string, Routine>();
+	for (const row of rows) {
+		const kind = ROUTINE_KINDS[row.kind];
+		if (kind !== undefined) routines.set(`${kind}\u0000${row.routineName}`, { name: row.routineName, kind });
+	}
+	return [...routines.values()];
+}
+
+function missingSchemaWarnings(database: string, requested: readonly string[] | null, schemas: readonly SchemaRow[]): Warning[] {
+	const existing = new Set(schemas.map((row) => row.schemaName));
+	return [...new Set(requested ?? [])]
+		.filter((name) => !existing.has(name))
+		.map((name) => ({
+			code: "schema_not_visible",
+			message: `schema "${name}" does not exist in database "${database}"`,
+			target: formatName({ database, schema: name }),
+		}));
+}
+
+// pg_catalog lists every object of the database to every user, privileges or
+// not, so nothing is hidden from the snapshot. But without USAGE on a schema
+// no query can reach its tables, which an agent writing SQL must know.
+function unusableSchemaWarnings(database: string, schemas: readonly SchemaRow[], captured: ReadonlySet<string>): Warning[] {
+	return schemas
+		.filter((row) => captured.has(row.schemaName) && !row.usable)
+		.map((row) => ({
+			code: "schema_not_usable",
+			message: `the user has no USAGE privilege on schema "${row.schemaName}": its structure is listed, but its tables cannot be queried with this user`,
+			target: formatName({ database, schema: row.schemaName }),
+		}));
+}
+
+// pg_get_viewdef does not check privileges, so a definition is only missing
+// when the server returned none; still, null is never presented as a SELECT.
+function hiddenViewDefinitionWarnings(database: string, schemas: readonly Schema[]): Warning[] {
+	return schemas.flatMap((schema) =>
+		schema.tables
+			.filter((table) => table.kind === "view" && table.viewDefinition === null)
+			.map((view) => ({
+				code: "view_definition_hidden",
+				message: `definition of view "${schema.name}.${view.name}" could not be read`,
+				target: formatName({ database, schema: schema.name, table: view.name }),
+			})),
+	);
+}
+
+function isSystemSchema(name: string): boolean {
+	return SYSTEM_SCHEMAS.includes(name) || TEMPORARY_SCHEMA.test(name);
+}
+
+/** A SQL string literal: 'it''s', the way enum labels are written in DDL. */
+function sqlText(text: string): string {
+	return `'${text.replaceAll("'", "''")}'`;
+}
+
+function tableKey(row: { schemaName: string; tableName: string }): string {
+	// \u0000 cannot appear in identifiers, so the key is unambiguous.
+	return `${row.schemaName}\u0000${row.tableName}`;
+}
+
+function groupBy<T>(items: readonly T[], keyOf: (item: T) => string): Map<string, T[]> {
+	const groups = new Map<string, T[]>();
+	for (const item of items) {
+		const key = keyOf(item);
+		const group = groups.get(key);
+		if (group === undefined) groups.set(key, [item]);
+		else group.push(item);
+	}
+	return groups;
+}
+
+// Plain code-unit comparison, like byName: the order never depends on the locale.
+function compareText(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0;
+}

package/lib/engines/postgres/introspect.ts

@@ -0,0 +1,240 @@
+import { Client } from "pg";
+
+import type { Snapshot } from "../../model/snapshot.ts";
+import {
+	buildSnapshot,
+	capturedSchemas,
+	type ColumnRow,
+	type ForeignKeyColumnRow,
+	type IndexColumnRow,
+	type RoutineRow,
+	type SchemaRow,
+	type TableRow,
+	type TriggerRow,
+} from "./catalog.ts";
+
+// Reads the structure of one PostgreSQL 14+ database through pg_catalog.
+// information_schema is not enough: it hides every object the user has no
+// privilege on, and lacks enum labels, index methods, expression indexes and
+// materialized views. pg_catalog lists everything to everyone.
+//
+// One query per kind of object for ALL captured schemas at once (= ANY($1)),
+// never one per table, like the MySQL engine. The rows go to catalog.ts,
+// which builds the snapshot without touching the server.
+
+export interface PostgresConnectionOptions {
+	readonly host: string;
+	readonly port: number;
+	readonly user: string;
+	/** The resolved password. Callers resolve secret references before this point. */
+	readonly password: string;
+	/** The one database to connect to: a PostgreSQL connection never reaches another. */
+	readonly database: string;
+	/** Schemas to capture; null or omitted captures every non-system schema. */
+	readonly schemas?: readonly string[] | null;
+	readonly connectTimeoutMs?: number;
+	readonly statementTimeoutMs?: number;
+}
+
+// Every setting that changes how pg_catalog functions print text the hash
+// depends on. A role or a database can set any of them (ALTER ROLE ... SET),
+// so heydb pins its own values instead of inheriting them:
+// - search_path empty: format_type, pg_get_expr and pg_get_viewdef qualify
+//   every name with its schema ("public.orders"), whatever the user's path.
+//   pg_catalog is still searched first, so the queries below need no prefix.
+// - DateStyle, TimeZone, IntervalStyle, extra_float_digits: how date, time,
+//   interval and float constants in defaults and view definitions are printed.
+// - default_transaction_read_only: the session cannot write (see connectReadOnly).
+const SESSION_SETTINGS: readonly (readonly [string, string])[] = [
+	["search_path", ""],
+	["DateStyle", "ISO, MDY"],
+	["TimeZone", "UTC"],
+	["IntervalStyle", "postgres"],
+	["extra_float_digits", "1"],
+	["default_transaction_read_only", "on"],
+];
+
+const RELATION_KINDS = ["r", "p", "f", "v", "m"];
+
+export async function introspectPostgres(options: PostgresConnectionOptions): Promise<Snapshot> {
+	const client = await connectReadOnly(options);
+	try {
+		const capturedAt = new Date().toISOString();
+		// One read-only REPEATABLE READ transaction: every query below sees the
+		// same moment, so a table created halfway through cannot appear in one
+		// list and be missing from another.
+		await client.query("BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY");
+		const version = String((await client.query("SHOW server_version")).rows[0]?.server_version ?? "");
+		const database = String((await client.query("SELECT current_database() AS name")).rows[0]?.name ?? "");
+
+		const requestedSchemas = options.schemas ?? null;
+		const schemas = (
+			await client.query<SchemaRow>(
+				`SELECT nspname AS "schemaName", has_schema_privilege(oid, 'USAGE') AS usable FROM pg_namespace`,
+			)
+		).rows;
+		const captured = capturedSchemas(schemas, requestedSchemas);
+		const empty = { tables: [], columns: [], indexColumns: [], foreignKeyColumns: [], triggers: [], routines: [] };
+		const rows = captured.length === 0 ? empty : await readCatalog(client, captured);
+		await client.query("COMMIT");
+
+		return buildSnapshot({ version, capturedAt, database, requestedSchemas, schemas, ...rows });
+	} finally {
+		await client.end();
+	}
+}
+
+/**
+ * Opens a connection whose session is read-only: INSERT, UPDATE, DDL and
+ * CALL of a writing procedure all fail, even for a superuser. A superuser
+ * could switch it off again with SET; heydb only ever sends fixed SELECT
+ * statements. Defense in depth on top of recommending a read-only role.
+ */
+export async function connectReadOnly(options: PostgresConnectionOptions): Promise<Client> {
+	const client = new Client({
+		host: options.host,
+		port: options.port,
+		user: options.user,
+		password: options.password,
+		database: options.database,
+		connectionTimeoutMillis: options.connectTimeoutMs ?? 10_000,
+		application_name: "heydb",
+	});
+	try {
+		await client.connect();
+	} catch (error) {
+		// A failed connect may still hold a socket; ending it lets the process exit.
+		await client.end().catch(() => {});
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(
+			`postgresql: cannot connect to ${options.host}:${options.port} as ${options.user} (database "${options.database}"): ${reason}`,
+			{ cause: error },
+		);
+	}
+	try {
+		const settings = [...SESSION_SETTINGS, ["statement_timeout", String(options.statementTimeoutMs ?? 60_000)] as const];
+		// set_config(name, value, false) is SET for the whole session, with the values bound as parameters.
+		// Qualified, because this one statement still runs under the role's own search_path.
+		const calls = settings.map((_, index) => `pg_catalog.set_config($${index * 2 + 1}, $${index * 2 + 2}, false)`);
+		await client.query(`SELECT ${calls.join(", ")}`, settings.flat());
+	} catch (error) {
+		// Never leave a half-configured connection open: it would keep the process alive.
+		await client.end().catch(() => {});
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`postgresql: cannot open a read-only session on ${options.host}:${options.port}: ${reason}`, {
+			cause: error,
+		});
+	}
+	return client;
+}
+
+async function readCatalog(client: Client, schemas: readonly string[]) {
+	// Every query takes the captured schemas as $1 (a text[]) and, where it
+	// needs them, the relation kinds heydb lists as $2; nothing is interpolated.
+	const select = async <T>(sql: string, ...more: unknown[]): Promise<T[]> =>
+		(await client.query(sql, [schemas, ...more])).rows as T[];
+
+	// One after another, never with Promise.all: a pg client runs one query at
+	// a time anyway, and queueing a second one while the first runs is
+	// deprecated (pg 8 warns; pg 9 will refuse it).
+	//
+	// Partitions are left out (NOT relispartition): the partitioned table is
+	// the object people query, and listing each partition would repeat it.
+	const tables = await select<TableRow>(
+		`
+		SELECT n.nspname AS "schemaName", c.relname AS "tableName", c.relkind::text AS relkind,
+		       c.reltuples AS reltuples,
+		       CASE WHEN c.relkind = 'p' THEN (
+		         SELECT sum(part.reltuples) FROM pg_partition_tree(c.oid) tree
+		         JOIN pg_class part ON part.oid = tree.relid
+		         WHERE tree.isleaf AND part.reltuples >= 0
+		       ) END AS "partitionRows",
+		       obj_description(c.oid, 'pg_class') AS comment,
+		       CASE WHEN c.relkind IN ('v', 'm') THEN pg_get_viewdef(c.oid, true) END AS "viewDefinition"
+		FROM pg_class c
+		JOIN pg_namespace n ON n.oid = c.relnamespace
+		WHERE n.nspname = ANY($1) AND c.relkind = ANY($2) AND NOT c.relispartition`,
+		RELATION_KINDS,
+	);
+
+	// The collation is reported only when it differs from the type's own,
+	// i.e. when the column sets one explicitly.
+	const columns = await select<ColumnRow>(
+		`
+		SELECT n.nspname AS "schemaName", c.relname AS "tableName", a.attname AS "columnName",
+		       a.attnum AS position, format_type(a.atttypid, a.atttypmod) AS "dataType",
+		       a.attnotnull AS "notNull", pg_get_expr(d.adbin, d.adrelid) AS "defaultExpression",
+		       a.attidentity::text AS identity, a.attgenerated::text AS generated,
+		       col_description(c.oid, a.attnum) AS comment,
+		       CASE WHEN a.attcollation <> t.typcollation THEN co.collname::text END AS collation,
+		       CASE WHEN t.typtype = 'e' THEN ARRAY(
+		         SELECT e.enumlabel::text FROM pg_enum e WHERE e.enumtypid = t.oid ORDER BY e.enumsortorder
+		       ) END AS "enumLabels"
+		FROM pg_attribute a
+		JOIN pg_class c ON c.oid = a.attrelid
+		JOIN pg_namespace n ON n.oid = c.relnamespace
+		JOIN pg_type t ON t.oid = a.atttypid
+		LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+		LEFT JOIN pg_collation co ON co.oid = a.attcollation
+		WHERE n.nspname = ANY($1) AND c.relkind = ANY($2) AND NOT c.relispartition
+		  AND a.attnum > 0 AND NOT a.attisdropped`,
+		RELATION_KINDS,
+	);
+
+	// indkey is 0-based and holds 0 for an expression part, whose text
+	// pg_get_indexdef prints. Only key columns, not INCLUDE ones.
+	const indexColumns = await select<IndexColumnRow>(`
+		SELECT n.nspname AS "schemaName", c.relname AS "tableName", ic.relname AS "indexName",
+		       x.indisprimary AS "primary", x.indisunique AS "unique", am.amname AS method,
+		       k.ord::int AS position,
+		       CASE WHEN x.indkey[k.ord - 1] = 0 THEN pg_get_indexdef(x.indexrelid, k.ord::int, true)
+		            ELSE a.attname::text END AS "columnName"
+		FROM pg_index x
+		JOIN pg_class c ON c.oid = x.indrelid
+		JOIN pg_namespace n ON n.oid = c.relnamespace
+		JOIN pg_class ic ON ic.oid = x.indexrelid
+		JOIN pg_am am ON am.oid = ic.relam
+		CROSS JOIN LATERAL generate_series(1, x.indnkeyatts) AS k(ord)
+		LEFT JOIN pg_attribute a ON a.attrelid = x.indrelid AND a.attnum = x.indkey[k.ord - 1]
+		WHERE n.nspname = ANY($1) AND NOT c.relispartition`);
+
+	// conkey and confkey pair up position by position. A foreign key to a
+	// partitioned table also gets one clone per partition (conparentid <> 0).
+	const foreignKeyColumns = await select<ForeignKeyColumnRow>(`
+		SELECT n.nspname AS "schemaName", c.relname AS "tableName", con.conname AS "constraintName",
+		       k.ord::int AS position, a.attname AS "columnName",
+		       rn.nspname AS "referencedSchema", rc.relname AS "referencedTable", ra.attname AS "referencedColumn",
+		       con.confupdtype::text AS "updateRule", con.confdeltype::text AS "deleteRule"
+		FROM pg_constraint con
+		JOIN pg_class c ON c.oid = con.conrelid
+		JOIN pg_namespace n ON n.oid = c.relnamespace
+		JOIN pg_class rc ON rc.oid = con.confrelid
+		JOIN pg_namespace rn ON rn.oid = rc.relnamespace
+		CROSS JOIN LATERAL unnest(con.conkey, con.confkey) WITH ORDINALITY AS k(attnum, refattnum, ord)
+		JOIN pg_attribute a ON a.attrelid = con.conrelid AND a.attnum = k.attnum
+		JOIN pg_attribute ra ON ra.attrelid = con.confrelid AND ra.attnum = k.refattnum
+		WHERE n.nspname = ANY($1) AND con.contype = 'f' AND con.conparentid = 0 AND NOT c.relispartition`);
+
+	// Internal triggers are the ones PostgreSQL creates to enforce foreign keys.
+	const triggers = await select<TriggerRow>(`
+		SELECT n.nspname AS "schemaName", c.relname AS "tableName", t.tgname AS "triggerName", t.tgtype AS type
+		FROM pg_trigger t
+		JOIN pg_class c ON c.oid = t.tgrelid
+		JOIN pg_namespace n ON n.oid = c.relnamespace
+		WHERE n.nspname = ANY($1) AND NOT t.tgisinternal AND NOT c.relispartition`);
+
+	// Functions that belong to an extension (citext, PostGIS…) are part of
+	// that extension, not of the application's schema: PostGIS alone adds
+	// hundreds. pg_depend records them with deptype 'e'.
+	const routines = await select<RoutineRow>(`
+		SELECT n.nspname AS "schemaName", p.proname AS "routineName", p.prokind::text AS kind
+		FROM pg_proc p
+		JOIN pg_namespace n ON n.oid = p.pronamespace
+		WHERE n.nspname = ANY($1)
+		  AND NOT EXISTS (
+		    SELECT 1 FROM pg_depend dep
+		    WHERE dep.classid = 'pg_proc'::regclass AND dep.objid = p.oid AND dep.deptype = 'e'
+		  )`);
+
+	return { tables, columns, indexColumns, foreignKeyColumns, triggers, routines };
+}