@fabrika/db 0.0.0-stage → 0.4.0

package/package.json

@@ -1,6 +1,70 @@
 {
-  "name": "@fabrika/db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@fabrika/db",
+	"version": "0.4.0",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/db"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./capability": {
+			"bun": "./src/capability.ts",
+			"types": "./src/capability.ts",
+			"default": "./src/capability.ts"
+		},
+		"./tables": {
+			"bun": "./src/tables.ts",
+			"types": "./src/tables.ts",
+			"default": "./src/tables.ts"
+		},
+		"./framework": {
+			"bun": "./src/framework.ts",
+			"types": "./src/framework.ts",
+			"default": "./src/framework.ts"
+		},
+		"./migrations": {
+			"bun": "./src/migrations.ts",
+			"types": "./src/migrations.ts",
+			"default": "./src/migrations.ts"
+		},
+		"./production": {
+			"bun": "./src/production.ts",
+			"types": "./src/production.ts",
+			"default": "./src/production.ts"
+		},
+		"./codegen": {
+			"bun": "./src/codegen.ts",
+			"types": "./src/codegen.ts",
+			"default": "./src/codegen.ts"
+		},
+		"./testing": {
+			"bun": "./src/testing.ts",
+			"types": "./src/testing.ts",
+			"default": "./src/testing.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@fabrika/auth-core": "^0.4.0",
+		"@fabrika/platform-node": "^0.4.0",
+		"kysely": "0.29.6",
+		"kysely-postgres-js": "5.0.1",
+		"zod": "^3.25.76"
+	}
+}

package/src/builtins.ts

@@ -0,0 +1,94 @@
+// Captured when the module loads, before application code: a later patch to Object, Array, Map or their prototypes
+// does not change what these references do. Every policy and allowlist check goes through them and index loops,
+// never through an iterator, a spread or a method the checked value (or a mutable prototype) supplies.
+
+export const ownKeys = Object.keys
+export const ownDescriptor = Object.getOwnPropertyDescriptor
+export const hasOwn = Object.hasOwn
+export const isArray = Array.isArray
+export const freeze = Object.freeze
+export const prototypeOf = Object.getPrototypeOf
+export const isSafeInteger = Number.isSafeInteger
+export const OBJECT_PROTOTYPE: unknown = Object.prototype
+const define = Object.defineProperty
+export const ownNames = Object.getOwnPropertyNames
+export const ownSymbols = Object.getOwnPropertySymbols
+const apply = Reflect.apply
+const ARRAY_PROTOTYPE: unknown = Array.prototype
+const mapForEach: (this: ReadonlyMap<string, string>, callback: (value: string, key: string) => void) => void = Map.prototype.forEach
+
+/**
+ * A frozen set of names, read through the captured `Object.hasOwn` only. Entries are defined, not assigned, so
+ * `__proto__` or an inherited setter cannot drop one.
+ */
+export type NameSet = Readonly<Record<string, true>>
+
+export function nameSet(names: readonly string[]): NameSet {
+	const set: Record<string, true> = {}
+	for (let index = 0; index < names.length; index++) {
+		const name = names[index]
+		if (name !== undefined) {
+			define(set, name, { value: true, enumerable: true })
+		}
+	}
+	return freeze(set)
+}
+
+export function inSet(set: NameSet, name: unknown): name is string {
+	return typeof name === 'string' && hasOwn(set, name)
+}
+
+/** The names in the order they were added. */
+export function namesOf(set: NameSet): readonly string[] {
+	return ownKeys(set)
+}
+
+/**
+ * The elements of a plain array, each passed through `parse` before it is copied; undefined for anything else: a
+ * subclass, an array with an own property besides its indexes and `length` (an own `map` or `Symbol.iterator`),
+ * a hole, or an accessor element. The input's own methods never run.
+ */
+export function parseList<T>(value: unknown, parse: (item: unknown) => T): T[] | undefined {
+	if (!isArray(value) || prototypeOf(value) !== ARRAY_PROTOTYPE || ownSymbols(value).length !== 0) {
+		return undefined
+	}
+	const length = value.length
+	if (ownNames(value).length !== length + 1) {
+		return undefined
+	}
+	const items: T[] = []
+	for (let index = 0; index < length; index++) {
+		const descriptor = ownDescriptor(value, index)
+		if (descriptor === undefined || !hasOwn(descriptor, 'value')) {
+			return undefined
+		}
+		items[index] = parse(descriptor.value)
+	}
+	return items
+}
+
+/** A frozen copy of a string map, read through the captured `Map.prototype.forEach`. */
+export function recordOf(map: ReadonlyMap<string, string>): Readonly<Record<string, string>> {
+	const record: Record<string, string> = {}
+	apply(mapForEach, map, [
+		(value: string, key: string) => {
+			setOwn(record, key, value)
+		},
+	])
+	return freeze(record)
+}
+
+/** Defines an own property: unlike an assignment, it cannot hit `__proto__` or an inherited setter. */
+export function setOwn<V>(record: Record<string, V>, key: string, value: V): void {
+	define(record, key, { value, enumerable: true, writable: true, configurable: true })
+}
+
+/** Redefines an own data property of any object, as `setOwn` does for a record. */
+export function defineValue(target: object, key: string, value: unknown): void {
+	define(target, key, { value, enumerable: true, writable: true, configurable: true })
+}
+
+/** An own property of a record, or undefined: an inherited one is never read. */
+export function ownEntry<V>(record: Readonly<Record<string, V>>, key: string): V | undefined {
+	return hasOwn(record, key) ? record[key] : undefined
+}

package/src/capability.ts

@@ -0,0 +1,93 @@
+/**
+ * One authorized object, for one action. The framework mints the class that implements it; this package never
+ * constructs one. The `~capability` member is type-only: the implementing class declares it so that
+ * `Ref<'note', 'notes.read'>` and `Ref<'note', 'notes.delete'>` stay distinct types, and nothing reads it at runtime.
+ */
+export interface Ref<Dim extends string, Action extends string> {
+	readonly '~capability': { readonly kind: 'ref'; readonly dimension: Dim; readonly action: Action }
+}
+
+/** The scope values of one dimension in which the caller holds one action. */
+export interface Within<Dim extends string, Action extends string> {
+	readonly '~capability': { readonly kind: 'within'; readonly dimension: Dim; readonly action: Action }
+}
+
+/**
+ * One action held as a global grant: the capability of an `app` endpoint, for data of the whole application. Like a
+ * `Ref`, the member is type-only.
+ */
+export interface AppCapability<Action extends string> {
+	readonly '~capability': { readonly kind: 'app'; readonly action: Action }
+}
+
+export interface RefGrant {
+	readonly kind: 'ref'
+	readonly dimension: string
+	readonly action: string
+	readonly principal: string
+	readonly id: string
+	/** The values of the containers this object lies in, by dimension (`workspace → w1` for a note). */
+	readonly chain: ReadonlyMap<string, string>
+}
+
+/** The values of one container dimension in which the caller holds the action: `organization → [o1]`. */
+export interface ContainerGrant {
+	readonly dimension: string
+	readonly values: readonly string[]
+}
+
+/**
+ * The most scope values one `Within` carries, its own and its containers' together. Each becomes one bound
+ * parameter of every statement the `Within` scopes; Postgres binds at most 65535.
+ */
+export const MAX_WITHIN_VALUES = 1000
+
+export interface WithinGrant {
+	readonly kind: 'within'
+	readonly dimension: string
+	readonly action: string
+	readonly principal: string
+	/** The values of `dimension` itself; `all` comes from a grant that is not limited to scope values. */
+	readonly values: readonly string[] | 'all'
+	/**
+	 * The containers of `dimension` whose grants also authorise this `Within`. They stay separate from `values`, so
+	 * every statement judges a row by the chain columns it carries now: a scope moved out of a container is out.
+	 */
+	readonly containers: readonly ContainerGrant[]
+}
+
+/** An `app` endpoint's grant: the action everywhere in the application, which the proxy checked was held globally. */
+export interface AppGrant {
+	readonly kind: 'app'
+	readonly action: string
+	readonly principal: string
+}
+
+export type CapabilityGrant = RefGrant | WithinGrant | AppGrant
+
+/** How a refusal names a capability: `a Ref of note`, `a Within of workspace`, `an app capability`. */
+export function describeGrant(grant: CapabilityGrant): string {
+	return grant.kind === 'app' ? 'an app capability' : `a ${grant.kind === 'ref' ? 'Ref' : 'Within'} of ${grant.dimension}`
+}
+
+/** One generation of a job's lease, held by one attempt. A write of the attempt commits only while it still holds it. */
+export interface LeaseFence {
+	readonly job: string
+	/** The attempt holding the lease. */
+	readonly holder: string
+	readonly generation: number
+}
+
+/**
+ * The framework side of a capability. `resolve` returns what an authentic capability of the current request grants,
+ * or throws when the value is not one, is forged, or belongs to a request that has ended or is not the current one.
+ * The data layer checks the kind, the dimension and the action itself, on every operation.
+ */
+export interface CapabilityAuthority {
+	resolve(capability: unknown): CapabilityGrant
+	/**
+	 * The lease the work running now must still hold for a write to commit: the job attempt's, or `null` in a
+	 * request. Every mutation checks it inside its own transaction.
+	 */
+	fence(): LeaseFence | null
+}

package/src/codegen.ts

@@ -0,0 +1,302 @@
+import { databaseCodeQuery, type DatabaseObject } from '@fabrika/platform-node'
+import { SQL } from 'bun'
+import { z } from 'zod/v4'
+import { isPlainIdentifier } from './identifier'
+
+/** Where an application keeps the generated types and column list; committed, never hand-edited. */
+export const SCHEMA_FILE = 'src/db/schema.generated.ts'
+
+/** Framework tables (the migration ledger, and later files, job leases, webhook deliveries) are not application tables. */
+const FRAMEWORK_TABLE_PREFIX = 'fabrika_'
+
+const HEADER = '// @generated by fabrika db codegen from the migrated database. Do not edit: write a migration, then run fabrika db codegen.'
+
+/** A column's TypeScript types: what a read returns, and what an insert or update may bind when that differs. */
+interface ScalarType {
+	readonly select: string
+	readonly write?: string
+}
+
+const STRING: ScalarType = { select: 'string' }
+const NUMBER: ScalarType = { select: 'number' }
+/** Bun decodes `int8` and `numeric` to strings, by column type; a bound number or bigint is accepted. */
+const DECIMAL_STRING: ScalarType = { select: 'string', write: 'bigint | number | string' }
+/** A calendar day: the layer answers `YYYY-MM-DD` text for the `Date` Bun decodes, and binds the same text. */
+const DAY: ScalarType = { select: 'string' }
+/** A point in time: Bun decodes a `Date`; a write binds a `Date` or its ISO 8601 text. */
+const TIMESTAMP: ScalarType = { select: 'Date', write: 'Date | string' }
+
+/** Exactly the types whose decoding by `Bun.SQL` the codegen test pins; anything else is refused, not guessed. */
+const SCALAR_TYPES: ReadonlyMap<string, ScalarType> = new Map([
+	['text', STRING],
+	['varchar', STRING],
+	['bpchar', STRING],
+	['uuid', STRING],
+	['time', STRING],
+	['timetz', STRING],
+	['interval', STRING],
+	['int2', NUMBER],
+	['int4', NUMBER],
+	['float4', NUMBER],
+	['float8', NUMBER],
+	['int8', DECIMAL_STRING],
+	['numeric', DECIMAL_STRING],
+	['bool', { select: 'boolean' }],
+	['date', DAY],
+	['timestamp', TIMESTAMP],
+	['timestamptz', TIMESTAMP],
+])
+
+export class CodegenError extends Error {
+	override name = 'CodegenError'
+}
+
+const catalogColumnSchema = z.object({
+	table_name: z.string(),
+	column_name: z.string(),
+	type_name: z.string(),
+	/** `pg_type.typtype`: `b` base, `e` enum, `d` domain, … */
+	type_type: z.string(),
+	/** `pg_type.typcategory`: `A` for an array. */
+	type_category: z.string(),
+	nullable: z.boolean(),
+	generated: z.enum(['no', 'default', 'always']),
+	enum_labels: z.array(z.string()),
+})
+
+export type CatalogColumn = z.infer<typeof catalogColumnSchema>
+
+const catalogForeignKeySchema = z.object({
+	table_name: z.string(),
+	constraint_name: z.string(),
+	columns: z.array(z.string()),
+	referenced_table: z.string(),
+	referenced_columns: z.array(z.string()),
+})
+
+export type CatalogForeignKey = z.infer<typeof catalogForeignKeySchema>
+
+/** What codegen reads of the schema: every column, and every foreign key between its tables. */
+export interface Catalog {
+	readonly columns: readonly CatalogColumn[]
+	readonly foreignKeys: readonly CatalogForeignKey[]
+}
+
+/** One row per column of every ordinary or partitioned table in the schema, in table then column order. */
+const CATALOG_QUERY = `
+SELECT
+	c.relname::text AS table_name,
+	a.attname::text AS column_name,
+	t.typname::text AS type_name,
+	t.typtype::text AS type_type,
+	t.typcategory::text AS type_category,
+	NOT a.attnotnull AS nullable,
+	CASE
+		WHEN a.attgenerated <> '' OR a.attidentity = 'a' THEN 'always'
+		WHEN a.atthasdef OR a.attidentity = 'd' THEN 'default'
+		ELSE 'no'
+	END AS generated,
+	ARRAY(SELECT e.enumlabel::text FROM pg_enum e WHERE e.enumtypid = t.oid ORDER BY e.enumsortorder) AS enum_labels
+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
+WHERE n.nspname = $1 AND c.relkind IN ('r', 'p') AND NOT c.relispartition AND a.attnum > 0 AND NOT a.attisdropped
+ORDER BY c.relname, a.attnum
+`
+
+/** One row per foreign key between two tables of the schema, its columns in key order, by table then constraint name. */
+const FOREIGN_KEY_QUERY = `
+SELECT
+	c.relname::text AS table_name,
+	k.conname::text AS constraint_name,
+	ARRAY(
+		SELECT a.attname::text FROM unnest(k.conkey) WITH ORDINALITY AS u(attnum, position)
+		JOIN pg_attribute a ON a.attrelid = k.conrelid AND a.attnum = u.attnum ORDER BY u.position
+	) AS columns,
+	r.relname::text AS referenced_table,
+	ARRAY(
+		SELECT a.attname::text FROM unnest(k.confkey) WITH ORDINALITY AS u(attnum, position)
+		JOIN pg_attribute a ON a.attrelid = k.confrelid AND a.attnum = u.attnum ORDER BY u.position
+	) AS referenced_columns
+FROM pg_constraint k
+JOIN pg_class c ON c.oid = k.conrelid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+JOIN pg_class r ON r.oid = k.confrelid
+JOIN pg_namespace rn ON rn.oid = r.relnamespace
+WHERE k.contype = 'f' AND n.nspname = $1 AND rn.nspname = $1
+ORDER BY c.relname, k.conname
+`
+
+/**
+ * Reads the columns of the application's schema, refusing one that escapes it or holds a database object that
+ * `objects`, the migrations' manifest (`PostgresApplicationMigrations.objects`), does not name. The URL is a
+ * credential: no message here contains it.
+ */
+export async function introspectSchema(url: string, schema: string, objects: readonly DatabaseObject[]): Promise<readonly CatalogColumn[]> {
+	return (await introspectCatalog(url, schema, objects)).columns
+}
+
+/** `introspectSchema`, with the foreign keys between the schema's tables. */
+export async function introspectCatalog(url: string, schema: string, objects: readonly DatabaseObject[]): Promise<Catalog> {
+	if (!isPlainIdentifier(schema)) throw new CodegenError(`the schema must match ^[a-z_][a-z0-9_]*$: ${schema}`)
+	const sql = new SQL({ url, adapter: 'postgres', max: 1, prepare: false })
+	try {
+		return await sql.begin('read only', async (tx) => {
+			// The role or the database may set either for its sessions; the catalog query must not depend on them.
+			await tx.unsafe('SET LOCAL search_path TO pg_catalog, pg_temp')
+			await tx.unsafe('SET LOCAL standard_conforming_strings = on')
+			const namespaces: unknown = await tx.unsafe('SELECT 1 FROM pg_namespace WHERE nspname = $1', [schema])
+			if (!Array.isArray(namespaces) || namespaces.length === 0) {
+				throw new CodegenError(`schema ${schema} does not exist; run fabrika db migrate first`)
+			}
+			// The migration runner's own pre-commit check, so an object created outside a migration fails every start.
+			const code = z.array(z.object({ violation: z.string() })).parse(await tx.unsafe(databaseCodeQuery(schema, objects)))
+			if (code.length > 0) {
+				throw new CodegenError(
+					`schema ${schema} holds database code that escapes it or that no migration declares: ${
+						code.map((row) => row.violation).join(', ')
+					}; declare it in a migration or drop it in a new one`,
+				)
+			}
+			return {
+				columns: z.array(catalogColumnSchema).parse(await tx.unsafe(CATALOG_QUERY, [schema])),
+				foreignKeys: z.array(catalogForeignKeySchema).parse(await tx.unsafe(FOREIGN_KEY_QUERY, [schema])),
+			}
+		})
+	} finally {
+		await sql.close()
+	}
+}
+
+/**
+ * `note_comments` → `NoteCommentsTable`; the suffix keeps every name clear of `DB` and the imported type names. A
+ * name that would not start with a letter (`_123`) gets a `T` prefix, so it stays a TypeScript identifier.
+ */
+function interfaceName(table: string): string {
+	const words = table.split('_').filter((word) => word !== '')
+	const pascal = words.map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join('')
+	return `${/^[A-Z]/.test(pascal) ? pascal : `T${pascal}`}Table`
+}
+
+/** As keys of the generated object literal these would set or shadow the prototype instead of naming a table. */
+const RESERVED_TABLE_NAMES: ReadonlySet<string> = new Set(['__proto__', 'constructor', 'prototype'])
+
+function quote(value: string): string {
+	return `'${JSON.stringify(value).slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`
+}
+
+function scalarType(column: CatalogColumn): ScalarType {
+	const where = `${column.table_name}.${column.column_name}`
+	if (column.type_type === 'e') {
+		if (column.enum_labels.length === 0) throw new CodegenError(`${where}: enum ${column.type_name} has no labels`)
+		return { select: column.enum_labels.map(quote).join(' | ') }
+	}
+	const scalar = column.type_category === 'A' || column.type_type !== 'b' ? undefined : SCALAR_TYPES.get(column.type_name)
+	if (scalar === undefined) {
+		throw new CodegenError(
+			`${where} has type ${column.type_name}, which the data layer does not read or bind (supported: ${[...SCALAR_TYPES.keys()].join(', ')}, enums)`,
+		)
+	}
+	return scalar
+}
+
+interface Rendered {
+	readonly type: string
+	readonly uses: 'ColumnType' | 'Generated' | 'GeneratedAlways' | undefined
+}
+
+function columnType(column: CatalogColumn): Rendered {
+	const scalar = scalarType(column)
+	const nullable = column.nullable ? ' | null' : ''
+	const select = `${scalar.select}${nullable}`
+	const write = scalar.write === undefined ? select : `${scalar.write}${nullable}`
+	if (column.generated === 'always') return { type: `GeneratedAlways<${select}>`, uses: 'GeneratedAlways' }
+	if (column.generated === 'default') {
+		return write === select
+			? { type: `Generated<${select}>`, uses: 'Generated' }
+			: { type: `ColumnType<${select}, ${write} | undefined, ${write}>`, uses: 'ColumnType' }
+	}
+	return write === select ? { type: select, uses: undefined } : { type: `ColumnType<${select}, ${write}, ${write}>`, uses: 'ColumnType' }
+}
+
+/**
+ * The generated module: one interface per application table, the `DB` map Kysely and `defineTables` take, and the
+ * runtime column list with each table's foreign keys to application tables. Deterministic for a given catalog, so
+ * `fabrika db codegen --verify` can compare text.
+ */
+export function renderSchema(catalog: readonly CatalogColumn[], foreignKeys: readonly CatalogForeignKey[] = []): string {
+	const tables = new Map<string, CatalogColumn[]>()
+	for (const column of catalog) {
+		if (column.table_name.startsWith(FRAMEWORK_TABLE_PREFIX)) continue
+		for (const name of [column.table_name, column.column_name]) {
+			if (!isPlainIdentifier(name)) throw new CodegenError(`${name} is not a plain identifier (^[a-z_][a-z0-9_]*$), which the data layer requires`)
+		}
+		if (RESERVED_TABLE_NAMES.has(column.table_name)) {
+			throw new CodegenError(`table ${column.table_name} has a reserved JavaScript name; rename it in a migration`)
+		}
+		const columns = tables.get(column.table_name) ?? []
+		columns.push(column)
+		tables.set(column.table_name, columns)
+	}
+	const names = [...tables.keys()].sort()
+	const owners = new Map<string, string>()
+	const used = new Set<string>()
+	const interfaces: string[] = []
+	for (const table of names) {
+		const name = interfaceName(table)
+		const owner = owners.get(name)
+		if (owner !== undefined) throw new CodegenError(`tables ${owner} and ${table} would both generate ${name}; rename one in a migration`)
+		owners.set(name, table)
+		const fields = (tables.get(table) ?? []).map((column) => {
+			const rendered = columnType(column)
+			if (rendered.uses !== undefined) used.add(rendered.uses)
+			return `\t${column.column_name}: ${rendered.type}\n`
+		})
+		interfaces.push(`export interface ${name} {\n${fields.join('')}}\n`)
+	}
+	const kyselyNames = ['ColumnType', 'Generated', 'GeneratedAlways'].filter((name) => used.has(name))
+	const imports = [
+		"import type { TypedColumnList } from '@fabrika/db'\n",
+		...(kyselyNames.length === 0 ? [] : [`import type { ${kyselyNames.join(', ')} } from 'kysely'\n`]),
+	]
+	const db = names.map((table) => `\t${table}: ${interfaceName(table)}\n`).join('')
+	const keysOf = (table: string): string => {
+		const keys = foreignKeys.filter((key) => key.table_name === table && tables.has(key.referenced_table))
+		if (keys.length === 0) return '\t\tforeignKeys: [],\n'
+		const rendered = keys.map((key) =>
+			`\t\t\t{\n\t\t\t\tcolumns: [${key.columns.map(quote).join(', ')}],\n\t\t\t\ttable: ${quote(key.referenced_table)},\n`
+			+ `\t\t\t\treferences: [${key.referenced_columns.map(quote).join(', ')}],\n\t\t\t},\n`
+		)
+		return `\t\tforeignKeys: [\n${rendered.join('')}\t\t],\n`
+	}
+	/**
+	 * A table's columns of `types` as the list field `field`: the `date` columns, which the layer answers as `YYYY-MM-DD`,
+	 * and the timestamps, whose written text it checks. A table without one has no such field.
+	 */
+	const listOf = (table: string, field: string, types: readonly string[]): string => {
+		const listed = (tables.get(table) ?? []).filter((column) => column.type_type === 'b' && types.includes(column.type_name))
+		return listed.length === 0 ? '' : `\t\t${field}: [${listed.map((column) => quote(column.column_name)).join(', ')}],\n`
+	}
+	const datesOf = (table: string): string => `${listOf(table, 'dates', ['date'])}${listOf(table, 'timestamps', ['timestamp', 'timestamptz'])}`
+	const columns = names
+		.map((table) =>
+			`\t'${table}': {\n\t\tcolumns: [\n${(tables.get(table) ?? []).map((column) => `\t\t\t'${column.column_name}',\n`).join('')}\t\t],\n${
+				keysOf(table)
+			}${datesOf(table)}\t},\n`
+		)
+		.join('')
+	return [
+		`${HEADER}\n`,
+		imports.join(''),
+		...interfaces,
+		`export interface DB {\n${db}}\n`,
+		`export const columns: TypedColumnList<DB> = {\n${columns}}\n`,
+	].join('\n')
+}
+
+/** Introspects the migrated schema, checked against the migrations' manifest, and renders the module for `SCHEMA_FILE`. */
+export async function generateSchema(url: string, schema: string, objects: readonly DatabaseObject[]): Promise<string> {
+	const catalog = await introspectCatalog(url, schema, objects)
+	return renderSchema(catalog.columns, catalog.foreignKeys)
+}