@softure-ai/db 0.0.0-stage → 0.1.5

package/src/migrations/ledger.ts

@@ -0,0 +1,75 @@
+// The migration ledger `softure.migrations` (docs/02-module-standard.md §4). It is owned by the
+// pseudo-module `softure` and created by its own migration, which ships as code so a bundled
+// runner needs no file for it. While the table does not exist the journal reads as empty, so the
+// first run bootstraps through the normal path.
+//
+// NEVER edit LEDGER_MIGRATION: deployed databases hold its checksum (a test pins it). A change to
+// the ledger is a new file, `0002_…`, appended to LEDGER_FILES.
+import { createMigrationFile, type MigrationFile } from "./files.js";
+import type { MigrationSession } from "./session.js";
+
+export const LEDGER_MODULE_ID = "softure";
+export const LEDGER_SCHEMA = "softure";
+/** The ledger's own format version, recorded as `module_version` of its rows. */
+export const LEDGER_VERSION = "1.0.0";
+
+const LEDGER_MIGRATION = `-- Rollback: DROP SCHEMA softure CASCADE; this forgets which module migrations ran, the module schemas and their data stay.
+CREATE TABLE softure.migrations (
+  id bigint GENERATED ALWAYS AS IDENTITY UNIQUE,
+  module text NOT NULL CHECK (module ~ '^[a-z][a-z0-9]*(-[a-z0-9]+)*$'),
+  version integer NOT NULL CHECK (version > 0),
+  name text NOT NULL CHECK (name ~ '^[a-z0-9]+(_[a-z0-9]+)*$'),
+  checksum text NOT NULL CHECK (checksum ~ '^[0-9a-f]{64}$'),
+  module_version text NOT NULL,
+  method text NOT NULL CHECK (method IN ('applied', 'adopted')),
+  applied_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (module, version)
+);
+`;
+
+function createLedgerFiles(): MigrationFile[] {
+  const file = createMigrationFile("0001_ledger.sql", LEDGER_MIGRATION);
+  if (typeof file === "string") {
+    throw new Error(`ledger: the built-in migration is invalid: ${file}`);
+  }
+  return [file];
+}
+
+export const LEDGER_FILES: readonly MigrationFile[] = createLedgerFiles();
+
+export type MigrationMethod = "applied" | "adopted";
+
+export interface JournalRow {
+  readonly module: string;
+  readonly version: number;
+  readonly name: string;
+  readonly checksum: string;
+  readonly method: MigrationMethod;
+}
+
+export interface LedgerEntry {
+  readonly module: string;
+  readonly version: number;
+  readonly name: string;
+  readonly checksum: string;
+  readonly moduleVersion: string;
+  readonly method: MigrationMethod;
+}
+
+/** Every ledger row, or none while the ledger table does not exist yet. */
+export async function readJournal(session: MigrationSession): Promise<JournalRow[]> {
+  const [table] = await session.query<{ exists: boolean }>("SELECT to_regclass('softure.migrations') IS NOT NULL AS exists");
+  if (table?.exists !== true) {
+    return [];
+  }
+  return session.query<JournalRow>(
+    "SELECT module, version, name, checksum, method FROM softure.migrations ORDER BY id",
+  );
+}
+
+export async function recordMigration(session: MigrationSession, entry: LedgerEntry): Promise<void> {
+  await session.query(
+    "INSERT INTO softure.migrations (module, version, name, checksum, module_version, method) VALUES ($1, $2, $3, $4, $5, $6)",
+    [entry.module, entry.version, entry.name, entry.checksum, entry.moduleVersion, entry.method],
+  );
+}

package/src/migrations/migrator.ts

@@ -0,0 +1,285 @@
+// The module migrator (docs/02-module-standard.md §4). Every enabled module's SQL files run in the
+// module's own schema, dependencies first, one transaction per file together with its ledger row.
+// Everything that can be checked (names, numbering, checksums, order) is checked for all modules
+// before the first file runs, so a problem in one module never leaves another half-migrated.
+import { ok, sortModulesByDependencies, type AnySoftureModule } from "@softure-ai/core";
+import type { DatabaseHandle } from "../client.js";
+import { readMigrationFiles, type MigrationFile } from "./files.js";
+import {
+  LEDGER_FILES,
+  LEDGER_MODULE_ID,
+  LEDGER_SCHEMA,
+  LEDGER_VERSION,
+  readJournal,
+  recordMigration,
+  type JournalRow,
+  type MigrationMethod,
+} from "./ledger.js";
+import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+import { withSession, type MigrationSession } from "./session.js";
+
+export interface MigrateOptions {
+  /** The enabled modules, in any order; dependencies are applied first. */
+  readonly modules: readonly AnySoftureModule[];
+  /**
+   * Read each module's files from `<migrationsDir>/<module id>/` instead of the module's own
+   * folder: the container path, where a bundle cannot locate package folders.
+   */
+  readonly migrationsDir?: URL;
+  /** Called after each file is committed, e.g. to print progress. */
+  readonly onApplied?: (step: MigrationStep) => void;
+}
+
+export interface MigrationStep {
+  readonly module: string;
+  readonly schema: string;
+  readonly version: number;
+  readonly name: string;
+  readonly checksum: string;
+}
+
+export interface MigrationPlan {
+  /** What `migrate` would apply, in order. */
+  readonly pending: readonly MigrationStep[];
+}
+
+export interface MigrationReport {
+  readonly applied: readonly MigrationStep[];
+}
+
+/** One migration owner: the ledger itself or an enabled module with a schema. */
+export interface MigrationUnit {
+  readonly module: string;
+  readonly schema: string;
+  readonly moduleVersion: string;
+  readonly files: readonly MigrationFile[];
+}
+
+// Any constant works; it only has to be the same for every runner of every app.
+const MIGRATION_LOCK_KEY = "73012026";
+const RESERVED_SCHEMAS = new Set([LEDGER_SCHEMA, "public", "information_schema"]);
+const MAX_IDENTIFIER_BYTES = 63;
+
+/** The dry run: what `migrate` would apply. Takes no lock and writes nothing. */
+export async function planMigrations(handle: DatabaseHandle, options: MigrateOptions): Promise<MigrationResult<MigrationPlan>> {
+  const units = await prepareUnits(options.modules, options.migrationsDir);
+  if (!units.ok) {
+    return units;
+  }
+  const journal = await withSession(handle, readJournal);
+  const comparison = compareJournal(units.value, journal);
+  return comparison.problems.length > 0 ? failWith(comparison.problems) : ok({ pending: comparison.pending });
+}
+
+/** Applies every pending migration under the advisory lock. */
+export async function migrate(handle: DatabaseHandle, options: MigrateOptions): Promise<MigrationResult<MigrationReport>> {
+  const units = await prepareUnits(options.modules, options.migrationsDir);
+  if (!units.ok) {
+    return units;
+  }
+  return withSession(handle, (session) =>
+    withMigrationLock(session, async () => {
+      // Read after the lock: a runner that waited sees what the first one applied.
+      const comparison = compareJournal(units.value, await readJournal(session));
+      if (comparison.problems.length > 0) {
+        return failWith(comparison.problems);
+      }
+      const applied: MigrationStep[] = [];
+      for (const step of comparison.pending) {
+        const unit = units.value.find((candidate) => candidate.module === step.module);
+        const file = unit?.files.find((candidate) => candidate.version === step.version);
+        if (unit === undefined || file === undefined) {
+          throw new Error(`migrate: step ${step.module} ${step.version} has no file; compareJournal is broken`);
+        }
+        const failure = await applyFile(session, { unit, file, method: "applied" });
+        if (failure !== null) {
+          return failWith([failure]);
+        }
+        applied.push(step);
+        options.onApplied?.(step);
+      }
+      return ok({ applied });
+    }),
+  );
+}
+
+/**
+ * Validates the module list and reads every file: the ledger first, then the modules with a
+ * schema in dependency order. Fails with every problem found.
+ */
+export async function prepareUnits(
+  modules: readonly AnySoftureModule[],
+  migrationsDir: URL | undefined,
+): Promise<MigrationResult<MigrationUnit[]>> {
+  const problems = modules.flatMap(checkModule);
+  const sorted = sortModulesByDependencies(modules);
+  if (!sorted.ok) {
+    problems.push({ code: "db.dependency_cycle", modules: modules.map((module) => module.id) });
+  }
+  if (problems.length > 0 || !sorted.ok) {
+    return failWith(problems);
+  }
+
+  const units: MigrationUnit[] = [
+    { module: LEDGER_MODULE_ID, schema: LEDGER_SCHEMA, moduleVersion: LEDGER_VERSION, files: LEDGER_FILES },
+  ];
+  for (const module of sorted.value) {
+    const schema = module.manifest.dbSchema;
+    if (schema === null || module.migrations === null) {
+      continue;
+    }
+    const dir = migrationsDir === undefined ? module.migrations.dir : new URL(`${module.id}/`, ensureFolderUrl(migrationsDir));
+    const files = await readMigrationFiles(module.id, dir);
+    if (files.ok) {
+      units.push({ module: module.id, schema, moduleVersion: module.manifest.version, files: files.value });
+    } else {
+      problems.push(...files.problems);
+    }
+  }
+  return problems.length > 0 ? failWith(problems) : ok(units);
+}
+
+/** Checks applied files against the folder and lists the pending ones in run order. */
+export function compareJournal(
+  units: readonly MigrationUnit[],
+  journal: readonly JournalRow[],
+): { problems: MigrationProblem[]; pending: MigrationStep[] } {
+  const problems: MigrationProblem[] = [];
+  const pending: MigrationStep[] = [];
+  for (const unit of units) {
+    const rows = journal.filter((row) => row.module === unit.module);
+    const appliedVersions = new Set(rows.map((row) => row.version));
+    const lastApplied = Math.max(0, ...rows.map((row) => row.version));
+
+    for (const row of rows) {
+      const file = unit.files.find((candidate) => candidate.version === row.version);
+      if (file === undefined) {
+        problems.push({ code: "db.migration_missing", module: unit.module, version: row.version, name: row.name });
+      } else if (file.checksum !== row.checksum || file.name !== row.name) {
+        problems.push({ code: "db.migration_changed", module: unit.module, version: row.version, name: row.name });
+      }
+    }
+    for (const file of unit.files) {
+      if (appliedVersions.has(file.version)) {
+        continue;
+      }
+      if (file.version < lastApplied) {
+        problems.push({ code: "db.migration_out_of_order", module: unit.module, version: file.version, appliedVersion: lastApplied });
+      } else {
+        pending.push({ module: unit.module, schema: unit.schema, version: file.version, name: file.name, checksum: file.checksum });
+      }
+    }
+  }
+  return { problems, pending };
+}
+
+/**
+ * Runs one file and its ledger row in one transaction, inside the unit's schema. Returns the
+ * problem when the SQL fails; the transaction is rolled back first.
+ */
+export async function applyFile(
+  session: MigrationSession,
+  input: { unit: MigrationUnit; file: MigrationFile; method: MigrationMethod },
+): Promise<MigrationProblem | null> {
+  const { unit, file, method } = input;
+  // The schema passed the manifest's lower_snake_case rule and checkModule; quoting is a second line.
+  const schema = quoteIdentifier(unit.schema);
+  try {
+    await session.exec(`BEGIN; CREATE SCHEMA IF NOT EXISTS ${schema}; SET LOCAL search_path TO ${schema}, public;`);
+    const transactionId = await readTransactionId(session);
+    if (method === "applied") {
+      await session.exec(file.sql);
+    }
+    // Second line behind findTransactionControl: a file that still ended the transaction left
+    // part of itself committed, so it must not be reported as cleanly rolled back.
+    if ((await readTransactionId(session)) !== transactionId) {
+      throw new TransactionEndedError();
+    }
+    await recordMigration(session, {
+      module: unit.module,
+      version: file.version,
+      name: file.name,
+      checksum: file.checksum,
+      moduleVersion: unit.moduleVersion,
+      method,
+    });
+    await session.exec("COMMIT");
+    return null;
+  } catch (error) {
+    const reason = await rollBack(session, error);
+    return { code: "db.migration_failed", module: unit.module, version: file.version, name: file.name, reason };
+  }
+}
+
+class TransactionEndedError extends Error {
+  constructor() {
+    super("the file ended the migrator's transaction, so the statements before that point may be committed; check the schema by hand");
+  }
+}
+
+// The transaction id, not now(): two transactions can share a start time (PGlite's clock ticks in
+// milliseconds), but never an id.
+async function readTransactionId(session: MigrationSession): Promise<string> {
+  const [row] = await session.query<{ id: string }>("SELECT pg_current_xact_id()::text AS id");
+  return row?.id ?? "";
+}
+
+/**
+ * Rolls the open transaction back and returns the reason to report. A failing ROLLBACK (a lost
+ * connection) is added to the reason instead of hiding the original error.
+ */
+export async function rollBack(session: MigrationSession, error: unknown): Promise<string> {
+  const reason = describeError(error);
+  try {
+    await session.exec("ROLLBACK");
+    return reason;
+  } catch (rollbackError) {
+    return `${reason} (and ROLLBACK failed: ${describeError(rollbackError)})`;
+  }
+}
+
+/** Holds the session-level advisory lock while `run` runs; a second runner waits for it. */
+export async function withMigrationLock<T>(session: MigrationSession, run: () => Promise<T>): Promise<T> {
+  await session.query("SELECT pg_advisory_lock($1)", [MIGRATION_LOCK_KEY]);
+  let result: T;
+  try {
+    result = await run();
+  } catch (error) {
+    // The run's own error wins; an unlock failure here is secondary (the session is discarded).
+    await session.query("SELECT pg_advisory_unlock($1)", [MIGRATION_LOCK_KEY]).catch((unlockError: unknown) => {
+      throw new Error(`migration run failed (${describeError(error)}) and releasing the lock failed: ${describeError(unlockError)}`, {
+        cause: error,
+      });
+    });
+    throw error;
+  }
+  await session.query("SELECT pg_advisory_unlock($1)", [MIGRATION_LOCK_KEY]);
+  return result;
+}
+
+function checkModule(module: AnySoftureModule): MigrationProblem[] {
+  const schema = module.manifest.dbSchema;
+  if (module.id === LEDGER_MODULE_ID || (schema !== null && isReservedSchema(schema))) {
+    return [{ code: "db.reserved_module", module: module.id }];
+  }
+  if (schema === null && module.migrations !== null) {
+    return [{ code: "db.migrations_without_schema", module: module.id }];
+  }
+  return [];
+}
+
+function isReservedSchema(schema: string): boolean {
+  return RESERVED_SCHEMAS.has(schema) || schema.startsWith("pg_") || Buffer.byteLength(schema, "utf8") > MAX_IDENTIFIER_BYTES;
+}
+
+function quoteIdentifier(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+function ensureFolderUrl(url: URL): URL {
+  return url.href.endsWith("/") ? url : new URL(`${url.href}/`);
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/migrations/problems.ts

@@ -0,0 +1,91 @@
+// Every expected migration failure, as a value (AGENTS.md: expected failures are results). Each
+// problem names the module and file it is about; `describeProblem` turns it into the English line
+// the CLI prints and `createTestDatabase` throws.
+import type { Err, Ok } from "@softure-ai/core";
+
+export type MigrationProblem =
+  | { readonly code: "db.invalid_migration_file"; readonly module: string; readonly file: string; readonly reason: string }
+  | { readonly code: "db.migrations_unreadable"; readonly module: string; readonly dir: string; readonly reason: string }
+  | { readonly code: "db.migration_changed"; readonly module: string; readonly version: number; readonly name: string }
+  | { readonly code: "db.migration_missing"; readonly module: string; readonly version: number; readonly name: string }
+  | { readonly code: "db.migration_out_of_order"; readonly module: string; readonly version: number; readonly appliedVersion: number }
+  | { readonly code: "db.migration_failed"; readonly module: string; readonly version: number; readonly name: string; readonly reason: string }
+  | { readonly code: "db.reserved_module"; readonly module: string }
+  | { readonly code: "db.migrations_without_schema"; readonly module: string }
+  | { readonly code: "db.dependency_cycle"; readonly modules: readonly string[] }
+  | { readonly code: "db.adopt_unknown_module"; readonly module: string }
+  | { readonly code: "db.adopt_version_mismatch"; readonly module: string; readonly requested: string; readonly enabled: string }
+  | { readonly code: "db.adopt_already_applied"; readonly module: string }
+  | { readonly code: "db.adopt_dependency_pending"; readonly module: string; readonly dependency: string }
+  | { readonly code: "db.adopt_no_schema"; readonly module: string }
+  | { readonly code: "db.adopt_reference_failed"; readonly module: string; readonly reason: string }
+  | { readonly code: "db.export_target_not_empty"; readonly module: string; readonly dir: string; readonly entries: readonly string[] }
+  | { readonly code: "db.schema_mismatch"; readonly module: string; readonly schema: string; readonly differences: readonly string[] };
+
+export type MigrationErrorCode = MigrationProblem["code"];
+
+/** A failed migration operation: the code of its first problem, and every problem found. */
+export interface MigrationFailure extends Err<MigrationErrorCode> {
+  readonly problems: readonly MigrationProblem[];
+}
+
+export type MigrationResult<T> = Ok<T> | MigrationFailure;
+
+export function failWith(problems: readonly MigrationProblem[]): MigrationFailure {
+  const [first] = problems;
+  if (first === undefined) {
+    throw new Error("failWith: a migration failure needs at least one problem");
+  }
+  return { ok: false, error: first.code, problems };
+}
+
+/** One English line per problem, naming the module and the file or object involved. */
+export function describeProblem(problem: MigrationProblem): string {
+  switch (problem.code) {
+    case "db.invalid_migration_file":
+      return `${problem.module}: migration file ${problem.file} is invalid: ${problem.reason}`;
+    case "db.migrations_unreadable":
+      return `${problem.module}: cannot read the migrations folder ${problem.dir}: ${problem.reason}`;
+    case "db.migration_changed":
+      return `${problem.module}: applied migration ${formatFile(problem.version, problem.name)} was edited (checksum differs); add a new migration instead`;
+    case "db.migration_missing":
+      return `${problem.module}: applied migration ${formatFile(problem.version, problem.name)} is missing from the module`;
+    case "db.migration_out_of_order":
+      return `${problem.module}: migration ${formatVersion(problem.version)} is pending but ${formatVersion(problem.appliedVersion)} is already applied`;
+    case "db.migration_failed":
+      return `${problem.module}: migration ${formatFile(problem.version, problem.name)} failed and was rolled back: ${problem.reason}`;
+    case "db.reserved_module":
+      return `${problem.module}: uses a reserved id or schema (the id "softure"; the schemas softure, public, information_schema, pg_* and names over 63 bytes)`;
+    case "db.migrations_without_schema":
+      return `${problem.module}: has migrations but no dbSchema in its manifest`;
+    case "db.dependency_cycle":
+      return `modules ${problem.modules.join(", ")} depend on each other in a cycle`;
+    case "db.adopt_unknown_module":
+      return `${problem.module}: cannot adopt a module that is not enabled in the config`;
+    case "db.adopt_version_mismatch":
+      return `${problem.module}: --adopt asks for ${problem.requested} but ${problem.enabled} is enabled`;
+    case "db.adopt_already_applied":
+      return `${problem.module}: already has migrations in the ledger; adopt only works on a module the ledger has never seen`;
+    case "db.adopt_dependency_pending":
+      return `${problem.module}: depends on ${problem.dependency}, which has migrations still pending; migrate or adopt ${problem.dependency} first`;
+    case "db.adopt_no_schema":
+      return `${problem.module}: has no dbSchema, so there is nothing to adopt`;
+    case "db.adopt_reference_failed":
+      return `${problem.module}: could not build the reference schema: ${problem.reason}`;
+    case "db.export_target_not_empty":
+      return `${problem.module}: ${problem.dir} holds other files (${problem.entries.join(", ")}); export into an empty folder`;
+    case "db.schema_mismatch":
+      return [
+        `${problem.module}: schema "${problem.schema}" differs from what its migrations create:`,
+        ...problem.differences.map((difference) => `  ${difference}`),
+      ].join("\n");
+  }
+}
+
+function formatVersion(version: number): string {
+  return String(version).padStart(4, "0");
+}
+
+function formatFile(version: number, name: string): string {
+  return `${formatVersion(version)}_${name}.sql`;
+}

package/src/migrations/session.ts

@@ -0,0 +1,48 @@
+// One raw connection for a migration run. The advisory lock is session-level, so the lock, every
+// transaction and every statement of a run must share this connection (never `pool.query`).
+import type { DatabaseHandle } from "../client.js";
+
+export interface MigrationSession {
+  /** A parameterised statement; returns its rows. */
+  readonly query: <T>(text: string, params?: readonly unknown[]) => Promise<T[]>;
+  /** One or more statements without parameters (a migration file). */
+  readonly exec: (sql: string) => Promise<void>;
+}
+
+/**
+ * Runs `run` on one dedicated connection. A pg client is destroyed afterwards instead of going
+ * back to the pool, so a `SET` inside a migration file or a lock that failed to release cannot
+ * leak into the app's queries. PGlite has one connection, so its settings are reset instead.
+ */
+export async function withSession<T>(handle: DatabaseHandle, run: (session: MigrationSession) => Promise<T>): Promise<T> {
+  if (handle.kind === "pglite") {
+    const { client } = handle;
+    try {
+      return await run({
+        query: async <R>(text: string, params?: readonly unknown[]) => (await client.query<R>(text, params ? [...params] : undefined)).rows,
+        exec: async (sql) => {
+          await client.exec(sql);
+        },
+      });
+    } finally {
+      await client.exec("RESET ALL");
+    }
+  }
+
+  const client = await handle.pool.connect();
+  // A dropped connection makes pg emit 'error' on the client; without a listener Node crashes the
+  // process. The pending query rejects on its own, so the listener only has to exist.
+  const ignoreClientError = (): void => undefined;
+  client.on("error", ignoreClientError);
+  try {
+    return await run({
+      query: async <R>(text: string, params?: readonly unknown[]) => (await client.query(text, params ? [...params] : undefined)).rows as R[],
+      exec: async (sql) => {
+        await client.query(sql);
+      },
+    });
+  } finally {
+    client.release(true);
+    client.off("error", ignoreClientError);
+  }
+}

package/src/shared.ts

@@ -0,0 +1,36 @@
+// One database handle per URL for the whole server process, shared by every module's Next.js
+// adapter and the app. Package code cannot import the app's own handle, and `next dev` re-evaluates
+// modules on every change, so the handles live on `globalThis` under a `Symbol.for` key: each
+// reload, and each copy of this file in separate server bundles, finds the same pool.
+import { createDatabase, type CreateDatabaseOptions, type DatabaseHandle } from "./client.js";
+
+const HANDLES_KEY = Symbol.for("@softure-ai/db/shared-handles");
+
+type HandleHost = Record<typeof HANDLES_KEY, Map<string, Promise<DatabaseHandle>> | undefined>;
+
+const host = globalThis as unknown as HandleHost;
+
+/**
+ * The process-wide handle for `url`, opened on first use. `options` apply only to that first call.
+ * A failed open is not kept, so the next call tries again.
+ */
+export function getSharedDatabase(url: string, options: CreateDatabaseOptions = {}): Promise<DatabaseHandle> {
+  const handles = (host[HANDLES_KEY] ??= new Map<string, Promise<DatabaseHandle>>());
+  let handle = handles.get(url);
+  if (handle === undefined) {
+    handle = createDatabase(url, options);
+    handles.set(url, handle);
+    handle.catch(() => handles.delete(url));
+  }
+  return handle;
+}
+
+/** Closes and forgets every shared handle. For tests and graceful shutdown. */
+export async function closeSharedDatabases(): Promise<void> {
+  const handles = host[HANDLES_KEY];
+  if (handles === undefined) return;
+  const opened = [...handles.values()];
+  handles.clear();
+  const results = await Promise.allSettled(opened);
+  await Promise.all(results.flatMap((result) => (result.status === "fulfilled" ? [result.value.close()] : [])));
+}

package/src/testing.ts

@@ -0,0 +1,52 @@
+// Test databases for module unit tests (docs/02-module-standard.md §10): a real Postgres (PGlite)
+// with the real migrations of the given modules. Migrating costs about two seconds, so each
+// module set is migrated once per test worker into a template, and every call starts from a copy
+// of the template's data folder (FIRE_TRACKER `src/db/test-db.ts`).
+import { PGlite } from "@electric-sql/pglite";
+import type { AnySoftureModule } from "@softure-ai/core";
+import { createPgliteHandle, type PgliteClientDatabase } from "./client.js";
+import { migrate } from "./migrations/migrator.js";
+import { describeProblem } from "./migrations/problems.js";
+
+export interface TestDatabase {
+  readonly db: PgliteClientDatabase;
+  readonly client: PGlite;
+  readonly close: () => Promise<void>;
+}
+
+const templates = new Map<string, Promise<Blob | File>>();
+
+/**
+ * A fresh, migrated, in-memory database per call. List the module under test and the modules it
+ * depends on. Throws when a migration is invalid or fails: that is a bug in the module package.
+ */
+export async function createTestDatabase(modules: readonly AnySoftureModule[] = []): Promise<TestDatabase> {
+  const client = new PGlite({ loadDataDir: await getTemplate(modules) });
+  const handle = await createPgliteHandle(client);
+  return { db: handle.db, client, close: handle.close };
+}
+
+function getTemplate(modules: readonly AnySoftureModule[]): Promise<Blob | File> {
+  const key = modules.map((module) => `${module.id}@${module.migrations?.dir.href ?? "-"}`).join("|");
+  let template = templates.get(key);
+  if (template === undefined) {
+    template = buildTemplate(modules);
+    templates.set(key, template);
+    // A failed build is not cached: the next call reports the problem again.
+    template.catch(() => templates.delete(key));
+  }
+  return template;
+}
+
+async function buildTemplate(modules: readonly AnySoftureModule[]): Promise<Blob | File> {
+  const handle = await createPgliteHandle(new PGlite());
+  try {
+    const result = await migrate(handle, { modules });
+    if (!result.ok) {
+      throw new Error(`createTestDatabase: migrations failed:\n${result.problems.map(describeProblem).join("\n")}`);
+    }
+    return await handle.client.dumpDataDir("none");
+  } finally {
+    await handle.close();
+  }
+}