@softure-ai/db 0.0.0-stage → 0.1.5

package/src/migrations/adopt.ts

@@ -0,0 +1,171 @@
+// Adoption (docs/02-module-standard.md §4, docs/05-adoption-playbook.md step 3): an existing app
+// has moved its own tables into a module's schema with its own migration. `adoptModule` checks
+// that the schema now equals what the module's migrations would create, then records those
+// migrations as `adopted` without running them. Any difference refuses: marking a schema as
+// migrated when it is not is the one mistake a later migration cannot recover from.
+import { ok, type AnySoftureModule } from "@softure-ai/core";
+import { createDatabase, type DatabaseHandle } from "../client.js";
+import { describeSchema, diffSchemas } from "./introspect.js";
+import { LEDGER_MODULE_ID, readJournal, recordMigration, type JournalRow } from "./ledger.js";
+import {
+  applyFile,
+  compareJournal,
+  migrate,
+  prepareUnits,
+  rollBack,
+  withMigrationLock,
+  type MigrationStep,
+  type MigrationUnit,
+} from "./migrator.js";
+import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+import { withSession, type MigrationSession } from "./session.js";
+
+export interface AdoptOptions {
+  /** The enabled modules, as for `migrate`. */
+  readonly modules: readonly AnySoftureModule[];
+  /** The id of the module to adopt. */
+  readonly module: string;
+  /** Its version; must equal the enabled module's manifest version. */
+  readonly version: string;
+  /** Compare and report only; write nothing (also no ledger). */
+  readonly dryRun?: boolean;
+  readonly migrationsDir?: URL;
+}
+
+export interface AdoptionReport {
+  readonly module: string;
+  readonly version: string;
+  readonly dryRun: boolean;
+  /** Ledger migrations applied first (or that would be, on a dry run). */
+  readonly ledger: readonly MigrationStep[];
+  /** The module's migrations recorded as adopted (or that would be). */
+  readonly adopted: readonly MigrationStep[];
+}
+
+export async function adoptModule(handle: DatabaseHandle, options: AdoptOptions): Promise<MigrationResult<AdoptionReport>> {
+  const target = options.modules.find((module) => module.id === options.module);
+  if (target === undefined) {
+    return failWith([{ code: "db.adopt_unknown_module", module: options.module }]);
+  }
+  if (target.manifest.version !== options.version) {
+    return failWith([{ code: "db.adopt_version_mismatch", module: target.id, requested: options.version, enabled: target.manifest.version }]);
+  }
+  const units = await prepareUnits(options.modules, options.migrationsDir);
+  if (!units.ok) {
+    return units;
+  }
+  const unit = units.value.find((candidate) => candidate.module === target.id);
+  if (unit === undefined) {
+    return failWith([{ code: "db.adopt_no_schema", module: target.id }]);
+  }
+
+  const reference = await describeReference(options, target);
+  if (!reference.ok) {
+    return reference;
+  }
+
+  return withSession(handle, (session) =>
+    withMigrationLock(session, async () => {
+      const journal = await readJournal(session);
+      const comparison = compareJournal(units.value, journal);
+      const problems = [...comparison.problems, ...checkAdoptable(target, unit, journal, comparison.pending)];
+      if (problems.length > 0) {
+        return failWith(problems);
+      }
+      const differences = diffSchemas(reference.value, await describeSchema(session, unit.schema));
+      if (differences.length > 0) {
+        return failWith([{ code: "db.schema_mismatch", module: unit.module, schema: unit.schema, differences }]);
+      }
+
+      const ledger = comparison.pending.filter((step) => step.module === LEDGER_MODULE_ID);
+      const adopted = unit.files.map((file) => ({ module: unit.module, schema: unit.schema, version: file.version, name: file.name, checksum: file.checksum }));
+      const report = { module: unit.module, version: options.version, dryRun: options.dryRun === true, ledger, adopted };
+      if (options.dryRun === true) {
+        return ok(report);
+      }
+      const failure = await writeAdoption(session, units.value, unit);
+      return failure === null ? ok(report) : failWith([failure]);
+    }),
+  );
+}
+
+/** The adopted module must be new to the ledger, and everything it depends on fully migrated. */
+function checkAdoptable(
+  target: AnySoftureModule,
+  unit: MigrationUnit,
+  journal: readonly JournalRow[],
+  pending: readonly MigrationStep[],
+): MigrationProblem[] {
+  if (journal.some((row) => row.module === unit.module)) {
+    return [{ code: "db.adopt_already_applied", module: unit.module }];
+  }
+  return Object.keys(target.manifest.dependsOn)
+    .filter((dependency) => pending.some((step) => step.module === dependency))
+    .map((dependency) => ({ code: "db.adopt_dependency_pending", module: unit.module, dependency }));
+}
+
+/**
+ * The schema the module's migrations create: they run on a scratch PGlite together with the
+ * enabled modules the target depends on (directly or not), because its SQL may reference them.
+ */
+async function describeReference(options: AdoptOptions, target: AnySoftureModule): Promise<MigrationResult<string[]>> {
+  const modules = collectWithDependencies(options.modules, target);
+  const scratch = await createDatabase("pglite://");
+  try {
+    const result = await migrate(scratch, { modules, ...(options.migrationsDir ? { migrationsDir: options.migrationsDir } : {}) });
+    if (!result.ok) {
+      const reason = result.problems.map((problem) => problem.code === "db.migration_failed" ? `${problem.module} ${problem.name}: ${problem.reason}` : problem.code).join("; ");
+      return failWith([{ code: "db.adopt_reference_failed", module: target.id, reason }]);
+    }
+    const schema = target.manifest.dbSchema ?? "";
+    return ok(await withSession(scratch, (session) => describeSchema(session, schema)));
+  } finally {
+    await scratch.close();
+  }
+}
+
+function collectWithDependencies(modules: readonly AnySoftureModule[], target: AnySoftureModule): AnySoftureModule[] {
+  const byId = new Map(modules.map((module) => [module.id, module]));
+  const collected = new Map<string, AnySoftureModule>();
+  const visit = (module: AnySoftureModule): void => {
+    if (collected.has(module.id)) return;
+    collected.set(module.id, module);
+    for (const dependency of Object.keys(module.manifest.dependsOn)) {
+      const listed = byId.get(dependency);
+      if (listed !== undefined) visit(listed);
+    }
+  };
+  visit(target);
+  return [...collected.values()];
+}
+
+/** Applies a pending ledger migration, then records every module file as adopted in one transaction. */
+async function writeAdoption(session: MigrationSession, units: readonly MigrationUnit[], unit: MigrationUnit): Promise<MigrationProblem | null> {
+  const ledger = units.find((candidate) => candidate.module === LEDGER_MODULE_ID);
+  const journal = await readJournal(session);
+  for (const file of ledger?.files ?? []) {
+    if (ledger !== undefined && !journal.some((row) => row.module === LEDGER_MODULE_ID && row.version === file.version)) {
+      const failure = await applyFile(session, { unit: ledger, file, method: "applied" });
+      if (failure !== null) return failure;
+    }
+  }
+  try {
+    await session.exec("BEGIN");
+    for (const file of unit.files) {
+      await recordMigration(session, {
+        module: unit.module,
+        version: file.version,
+        name: file.name,
+        checksum: file.checksum,
+        moduleVersion: unit.moduleVersion,
+        method: "adopted",
+      });
+    }
+    await session.exec("COMMIT");
+    return null;
+  } catch (error) {
+    const reason = await rollBack(session, error);
+    const first = unit.files[0];
+    return { code: "db.migration_failed", module: unit.module, version: first?.version ?? 0, name: first?.name ?? "", reason };
+  }
+}

package/src/migrations/export.ts

@@ -0,0 +1,66 @@
+// The container path: a bundled runner cannot find package folders (`import.meta.url` points at
+// the bundle), so the build stage copies every enabled module's files to `<dir>/<module id>/` and
+// the bundled runner reads them with `migrationsDir`. The ledger migration ships as code.
+import type { Dirent } from "node:fs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ok, type AnySoftureModule } from "@softure-ai/core";
+import { LEDGER_MODULE_ID } from "./ledger.js";
+import { prepareUnits, type MigrationStep } from "./migrator.js";
+import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+
+/**
+ * Copies each module's migration files to `<targetDir>/<module id>/`, replacing older `.sql`
+ * copies. A module folder holding anything but `.sql` files is refused, never emptied: it is
+ * not an earlier export (e.g. `softure migrate --export-migrations .` in an app with an `auth/`).
+ */
+export async function exportMigrations(
+  modules: readonly AnySoftureModule[],
+  targetDir: string,
+): Promise<MigrationResult<MigrationStep[]>> {
+  const units = await prepareUnits(modules, undefined);
+  if (!units.ok) {
+    return units;
+  }
+  const moduleUnits = units.value.filter((candidate) => candidate.module !== LEDGER_MODULE_ID);
+  const problems: MigrationProblem[] = [];
+  for (const unit of moduleUnits) {
+    const foreign = (await listEntries(join(targetDir, unit.module))).filter((entry) => !entry.isFile() || !entry.name.endsWith(".sql"));
+    if (foreign.length > 0) {
+      problems.push({
+        code: "db.export_target_not_empty",
+        module: unit.module,
+        dir: join(targetDir, unit.module),
+        entries: foreign.map((entry) => entry.name).sort(),
+      });
+    }
+  }
+  if (problems.length > 0) {
+    return failWith(problems);
+  }
+
+  const exported: MigrationStep[] = [];
+  for (const unit of moduleUnits) {
+    const moduleDir = join(targetDir, unit.module);
+    for (const entry of await listEntries(moduleDir)) {
+      await rm(join(moduleDir, entry.name));
+    }
+    await mkdir(moduleDir, { recursive: true });
+    for (const file of unit.files) {
+      await writeFile(join(moduleDir, file.fileName), file.sql, "utf8");
+      exported.push({ module: unit.module, schema: unit.schema, version: file.version, name: file.name, checksum: file.checksum });
+    }
+  }
+  return ok(exported);
+}
+
+async function listEntries(dir: string): Promise<Dirent[]> {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}

package/src/migrations/exported.ts

@@ -0,0 +1,82 @@
+// The deploy-time check of an exported migrations folder (the new image's, written by
+// `softure migrate --export-migrations`) against a database's ledger, without the app config. It runs
+// the migrator's own comparison, so a deploy never accepts what `softure migrate` would refuse.
+import type { Dirent } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { ok } from "@softure-ai/core";
+import { readMigrationFiles } from "./files.js";
+import { LEDGER_FILES, LEDGER_MODULE_ID, LEDGER_SCHEMA, LEDGER_VERSION, type JournalRow } from "./ledger.js";
+import { compareJournal, type MigrationUnit } from "./migrator.js";
+import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+
+export interface ExportedMigration {
+  readonly module: string;
+  readonly version: number;
+  readonly name: string;
+  readonly checksum: string;
+}
+
+export interface ExportedMigrationsCheck {
+  /** Files the database has not applied yet, per module in folder order; `softure migrate` applies them. */
+  readonly pending: readonly ExportedMigration[];
+  /** Modules the ledger knows but the folder does not hold: not enabled in the image, so the migrator ignores them. */
+  readonly absent: readonly string[];
+}
+
+/**
+ * Compares `<migrationsDir>/<module id>/*.sql` and the built-in ledger migration with the journal. Fails with every
+ * problem: an applied file edited or missing, a pending file numbered below an applied one, an invalid folder.
+ */
+export async function checkExportedMigrations(
+  migrationsDir: URL,
+  journal: readonly JournalRow[],
+): Promise<MigrationResult<ExportedMigrationsCheck>> {
+  const folders = await listModuleFolders(migrationsDir);
+  if (!folders.ok) {
+    return folders;
+  }
+  const problems: MigrationProblem[] = [];
+  const units: MigrationUnit[] = [
+    { module: LEDGER_MODULE_ID, schema: LEDGER_SCHEMA, moduleVersion: LEDGER_VERSION, files: LEDGER_FILES },
+  ];
+  for (const module of folders.value) {
+    if (module === LEDGER_MODULE_ID) {
+      problems.push({ code: "db.reserved_module", module });
+      continue;
+    }
+    const files = await readMigrationFiles(module, new URL(`${encodeURIComponent(module)}/`, ensureFolderUrl(migrationsDir)));
+    if (files.ok) {
+      // The schema is not part of the export; the comparison does not read it.
+      units.push({ module, schema: "", moduleVersion: "", files: files.value });
+    } else {
+      problems.push(...files.problems);
+    }
+  }
+  const comparison = compareJournal(units, journal);
+  problems.push(...comparison.problems);
+  if (problems.length > 0) {
+    return failWith(problems);
+  }
+  const known = new Set(units.map((unit) => unit.module));
+  const absent = [...new Set(journal.map((row) => row.module))].filter((module) => !known.has(module)).sort();
+  const pending = comparison.pending.map(({ module, version, name, checksum }) => ({ module, version, name, checksum }));
+  return ok({ pending, absent });
+}
+
+/** The module folders, sorted; files beside them (a README) are ignored. */
+async function listModuleFolders(dir: URL): Promise<MigrationResult<string[]>> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(fileURLToPath(dir), { withFileTypes: true });
+  } catch (error) {
+    const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : "unknown error";
+    const reason = code === "ENOENT" ? "the folder does not exist" : code;
+    return failWith([{ code: "db.migrations_unreadable", module: "(export)", dir: fileURLToPath(dir), reason }]);
+  }
+  return ok(entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort());
+}
+
+function ensureFolderUrl(url: URL): URL {
+  return url.href.endsWith("/") ? url : new URL(`${url.href}/`);
+}

package/src/migrations/files.ts

@@ -0,0 +1,129 @@
+// Reading a module's migration folder (docs/02-module-standard.md §4): plain SQL files named
+// `NNNN_<description>.sql`, numbered 1..n without gaps, each opening with a comment that states
+// the rollback plan. Other files (a README) are ignored.
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { ok } from "@softure-ai/core";
+import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+
+export interface MigrationFile {
+  /** The number in the file name: 1 for `0001_create_notes.sql`. */
+  readonly version: number;
+  /** The description in the file name: `create_notes`. */
+  readonly name: string;
+  readonly fileName: string;
+  /** The file content with a BOM removed and CRLF line ends turned into LF. */
+  readonly sql: string;
+  /** sha256 of `sql`, hex. */
+  readonly checksum: string;
+}
+
+const FILE_NAME = /^(\d{4})_([a-z0-9]+(?:_[a-z0-9]+)*)\.sql$/;
+const ROLLBACK_NOTE = /rollback:/i;
+// Statements that end or open a transaction would split the per-file transaction (a top-level
+// `END;` commits). Bodies in quotes or dollar quotes (PL/pgSQL `BEGIN … END;`) are not statements.
+const TRANSACTION_KEYWORDS = new Set(["begin", "commit", "rollback", "end", "abort"]);
+const TRANSACTION_PHRASES = [["start", "transaction"], ["prepare", "transaction"]];
+// Comments, quoted strings, quoted identifiers and dollar-quoted bodies, in that order of match.
+const NON_CODE = /--[^\n]*|\/\*[\s\S]*?\*\/|'(?:[^']|'')*'|"(?:[^"]|"")*"|(\$[A-Za-z_]*\$)[\s\S]*?\1/g;
+
+/** Normalises line ends so a Windows checkout does not look like an edited migration. */
+export function normalizeSql(text: string): string {
+  return text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+}
+
+export function computeChecksum(sql: string): string {
+  return createHash("sha256").update(normalizeSql(sql), "utf8").digest("hex");
+}
+
+export function createMigrationFile(fileName: string, text: string): MigrationFile | string {
+  const match = FILE_NAME.exec(fileName);
+  if (match === null) {
+    return "the name must look like 0001_create_table.sql (four digits, then lower_snake_case)";
+  }
+  const version = Number(match[1]);
+  if (version === 0) {
+    return "numbering starts at 0001";
+  }
+  const sql = normalizeSql(text);
+  if (!hasRollbackNote(sql)) {
+    return 'the file must open with a comment stating the rollback plan, e.g. "-- Rollback: DROP TABLE notes;"';
+  }
+  const control = findTransactionControl(sql);
+  if (control !== null) {
+    return `the file must not control transactions ("${control}"): the migrator runs each file in its own transaction`;
+  }
+  return { version, name: match[2] ?? "", fileName, sql, checksum: computeChecksum(sql) };
+}
+
+/** The module's migration files sorted by number, or every problem found in the folder. */
+export async function readMigrationFiles(moduleId: string, dir: URL): Promise<MigrationResult<MigrationFile[]>> {
+  const dirPath = fileURLToPath(dir);
+  let fileNames: string[];
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    fileNames = entries.filter((entry) => entry.isFile() && entry.name.endsWith(".sql")).map((entry) => entry.name);
+  } catch (error) {
+    return failWith([{ code: "db.migrations_unreadable", module: moduleId, dir: dirPath, reason: describeFsError(error) }]);
+  }
+
+  const problems: MigrationProblem[] = [];
+  const files: MigrationFile[] = [];
+  for (const fileName of fileNames.sort()) {
+    const file = createMigrationFile(fileName, await readFile(`${dirPath}/${fileName}`, "utf8"));
+    if (typeof file === "string") {
+      problems.push({ code: "db.invalid_migration_file", module: moduleId, file: fileName, reason: file });
+    } else {
+      files.push(file);
+    }
+  }
+  problems.push(...checkNumbering(moduleId, files));
+  return problems.length > 0 ? failWith(problems) : ok(files);
+}
+
+/** Numbers must run 1, 2, 3 …: a repeat is ambiguous and a gap usually means a deleted file. */
+function checkNumbering(moduleId: string, files: readonly MigrationFile[]): MigrationProblem[] {
+  const problems: MigrationProblem[] = [];
+  files.forEach((file, index) => {
+    const previous = files[index - 1];
+    if (previous !== undefined && previous.version === file.version) {
+      problems.push({ code: "db.invalid_migration_file", module: moduleId, file: file.fileName, reason: `repeats number ${previous.fileName.slice(0, 4)}` });
+    } else if (file.version !== (previous?.version ?? 0) + 1) {
+      problems.push({ code: "db.invalid_migration_file", module: moduleId, file: file.fileName, reason: `breaks the sequence: expected number ${String((previous?.version ?? 0) + 1).padStart(4, "0")}` });
+    }
+  });
+  return problems;
+}
+
+/** The first top-level statement that begins, ends or aborts a transaction, or null. */
+export function findTransactionControl(sql: string): string | null {
+  const statements = sql.replace(NON_CODE, " ").split(";");
+  for (const statement of statements) {
+    const words = statement.trim().toLowerCase().split(/\s+/);
+    const [first = "", second = ""] = words;
+    if (TRANSACTION_KEYWORDS.has(first) || TRANSACTION_PHRASES.some(([verb, noun]) => first === verb && second === noun)) {
+      return words.slice(0, 3).join(" ");
+    }
+  }
+  return null;
+}
+
+/** The leading `--` comment block (after blank lines) must mention "Rollback:". */
+function hasRollbackNote(sql: string): boolean {
+  const lines = sql.split("\n").map((line) => line.trim());
+  const firstContent = lines.findIndex((line) => line !== "");
+  const leading: string[] = [];
+  for (const line of lines.slice(Math.max(firstContent, 0))) {
+    if (!line.startsWith("--")) break;
+    leading.push(line);
+  }
+  return leading.some((line) => ROLLBACK_NOTE.test(line));
+}
+
+function describeFsError(error: unknown): string {
+  if (error instanceof Error && "code" in error && typeof error.code === "string") {
+    return error.code === "ENOENT" ? "the folder does not exist" : error.code;
+  }
+  return "unknown error";
+}

package/src/migrations/introspect.ts

@@ -0,0 +1,165 @@
+// A comparable description of one schema, for `adoptModule`: one line per object, sorted. Read
+// from pg_catalog with `search_path = pg_catalog`, so every name in a definition is printed
+// schema-qualified and two databases print the same object the same way.
+//
+// Left out on purpose: dropped columns (`attisdropped`), objects that belong to an extension
+// (`pg_depend.deptype = 'e'`), NOT NULL rows of pg_constraint (PG 18 has them, PG 16 does not;
+// nullability is compared through `attnotnull`), grants, comments, column order, row-level
+// security policies and view bodies. Composite types appear as their type line plus one column
+// line per attribute.
+import type { MigrationSession } from "./session.js";
+
+const NOT_IN_EXTENSION = (catalog: string, alias: string): string =>
+  `NOT EXISTS (SELECT 1 FROM pg_depend dep WHERE dep.classid = '${catalog}'::regclass AND dep.objid = ${alias}.oid AND dep.deptype = 'e')`;
+
+const RELATION_KINDS: Readonly<Record<string, string>> = {
+  r: "table",
+  p: "partitioned table",
+  v: "view",
+  m: "materialized view",
+  S: "sequence",
+  f: "foreign table",
+};
+
+const QUERIES = {
+  relations: `
+    SELECT c.relname, c.relkind, c.relpersistence
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = $1 AND c.relkind IN ('r', 'p', 'v', 'm', 'S', 'f') AND ${NOT_IN_EXTENSION("pg_class", "c")}`,
+  columns: `
+    SELECT c.relname, a.attname, format_type(a.atttypid, a.atttypmod) AS type, a.attnotnull AS not_null,
+      CASE WHEN a.attcollation <> 0 AND a.attcollation <> t.typcollation THEN quote_ident(coll.collname) END AS collation,
+      pg_get_expr(d.adbin, d.adrelid) AS default_expr, a.attidentity AS identity, a.attgenerated AS generated
+    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_collation coll ON coll.oid = a.attcollation
+      LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+    WHERE n.nspname = $1 AND c.relkind IN ('r', 'p', 'v', 'm', 'f', 'c') AND a.attnum > 0 AND NOT a.attisdropped
+      AND ${NOT_IN_EXTENSION("pg_class", "c")}`,
+  constraints: `
+    SELECT c.relname, con.conname, pg_get_constraintdef(con.oid, true) AS definition
+    FROM pg_constraint con
+      JOIN pg_class c ON c.oid = con.conrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = $1 AND con.contype IN ('p', 'u', 'f', 'c', 'x')`,
+  indexes: `
+    SELECT i.relname, pg_get_indexdef(i.oid) AS definition
+    FROM pg_index x
+      JOIN pg_class i ON i.oid = x.indexrelid
+      JOIN pg_namespace n ON n.oid = i.relnamespace
+    WHERE n.nspname = $1 AND ${NOT_IN_EXTENSION("pg_class", "i")}`,
+  sequences: `
+    SELECT c.relname, format_type(s.seqtypid, NULL) AS type, s.seqstart::text AS start, s.seqincrement::text AS increment,
+      s.seqmin::text AS min, s.seqmax::text AS max, s.seqcache::text AS cache, s.seqcycle AS cycle
+    FROM pg_sequence s
+      JOIN pg_class c ON c.oid = s.seqrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = $1 AND ${NOT_IN_EXTENSION("pg_class", "c")}`,
+  triggers: `
+    SELECT c.relname, t.tgname, pg_get_triggerdef(t.oid, true) AS definition
+    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 = $1 AND NOT t.tgisinternal`,
+  functions: `
+    SELECT p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')' AS signature,
+      md5(pg_get_functiondef(p.oid)) AS definition_hash
+    FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+    WHERE n.nspname = $1 AND p.prokind IN ('f', 'p') AND ${NOT_IN_EXTENSION("pg_proc", "p")}`,
+  types: `
+    SELECT t.typname, t.typtype,
+      CASE t.typtype
+        WHEN 'r' THEN (SELECT format_type(r.rngsubtype, NULL) FROM pg_range r WHERE r.rngtypid = t.oid)
+        WHEN 'e' THEN (SELECT string_agg(e.enumlabel, ', ' ORDER BY e.enumsortorder) FROM pg_enum e WHERE e.enumtypid = t.oid)
+        WHEN 'd' THEN format_type(t.typbasetype, t.typtypmod)
+      END AS definition
+    FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace
+    WHERE n.nspname = $1 AND ${NOT_IN_EXTENSION("pg_type", "t")}
+      AND (t.typtype IN ('e', 'd', 'r')
+        OR (t.typtype = 'c' AND (SELECT c.relkind FROM pg_class c WHERE c.oid = t.typrelid) = 'c'))`,
+} as const;
+
+const TYPE_KINDS: Readonly<Record<string, string>> = { e: "enum", d: "domain", r: "range", c: "composite type" };
+
+interface SequenceRow {
+  relname: string;
+  type: string;
+  start: string;
+  increment: string;
+  min: string;
+  max: string;
+  cache: string;
+  cycle: boolean;
+}
+
+interface ColumnRow {
+  relname: string;
+  attname: string;
+  type: string;
+  not_null: boolean;
+  collation: string | null;
+  default_expr: string | null;
+  identity: string;
+  generated: string;
+}
+
+/** Every object of `schema` as one sorted line each. Runs in its own read-only transaction. */
+export async function describeSchema(session: MigrationSession, schema: string): Promise<string[]> {
+  await session.exec("BEGIN READ ONLY; SET LOCAL search_path = pg_catalog;");
+  try {
+    const lines = [
+      ...(await session.query<{ relname: string; relkind: string; relpersistence: string }>(QUERIES.relations, [schema])).map(
+        (row) => `${row.relpersistence === "u" ? "unlogged " : ""}${RELATION_KINDS[row.relkind] ?? row.relkind} ${schema}.${row.relname}`,
+      ),
+      ...(await session.query<SequenceRow>(QUERIES.sequences, [schema])).map(
+        (row) =>
+          `sequence ${schema}.${row.relname}: ${row.type} start ${row.start} increment ${row.increment} min ${row.min} max ${row.max} cache ${row.cache}${row.cycle ? " cycle" : ""}`,
+      ),
+      ...(await session.query<ColumnRow>(QUERIES.columns, [schema])).map((row) => describeColumn(schema, row)),
+      ...(await session.query<{ relname: string; conname: string; definition: string }>(QUERIES.constraints, [schema])).map(
+        (row) => `constraint ${schema}.${row.relname}.${row.conname}: ${row.definition}`,
+      ),
+      ...(await session.query<{ relname: string; definition: string }>(QUERIES.indexes, [schema])).map(
+        (row) => `index ${schema}.${row.relname}: ${row.definition}`,
+      ),
+      ...(await session.query<{ relname: string; tgname: string; definition: string }>(QUERIES.triggers, [schema])).map(
+        (row) => `trigger ${schema}.${row.relname}.${row.tgname}: ${row.definition}`,
+      ),
+      ...(await session.query<{ signature: string; definition_hash: string }>(QUERIES.functions, [schema])).map(
+        (row) => `function ${schema}.${row.signature}: body ${row.definition_hash}`,
+      ),
+      ...(await session.query<{ typname: string; typtype: string; definition: string | null }>(QUERIES.types, [schema])).map(
+        (row) => `${TYPE_KINDS[row.typtype] ?? row.typtype} ${schema}.${row.typname}${row.definition === null ? "" : `: ${row.definition}`}`,
+      ),
+    ];
+    return lines.sort();
+  } finally {
+    await session.exec("ROLLBACK");
+  }
+}
+
+/** What is in `expected` and not in `actual`, and the other way round, as readable lines. */
+export function diffSchemas(expected: readonly string[], actual: readonly string[]): string[] {
+  const actualSet = new Set(actual);
+  const expectedSet = new Set(expected);
+  return [
+    ...expected.filter((line) => !actualSet.has(line)).map((line) => `missing in database: ${line}`),
+    ...actual.filter((line) => !expectedSet.has(line)).map((line) => `unexpected in database: ${line}`),
+  ];
+}
+
+function describeColumn(schema: string, row: ColumnRow): string {
+  const parts = [`column ${schema}.${row.relname}.${row.attname} ${row.type}`];
+  if (row.collation !== null) parts.push(`collate ${row.collation}`);
+  if (row.not_null) parts.push("not null");
+  if (row.generated === "s" || row.generated === "v") {
+    parts.push(`generated as ${row.default_expr ?? ""}${row.generated === "s" ? " stored" : " virtual"}`);
+  } else if (row.default_expr !== null) {
+    parts.push(`default ${row.default_expr}`);
+  }
+  if (row.identity === "a") parts.push("identity always");
+  if (row.identity === "d") parts.push("identity by default");
+  return parts.join(" ");
+}