@softure-ai/db 0.1.5 → 0.1.7

package/src/cli/run.ts

@@ -5,14 +5,17 @@
 //   import { runMigrateCli } from "@softure-ai/db/cli";
 //   import config from "../softure.config";
 //   process.exitCode = await runMigrateCli({ config, argv: process.argv.slice(2) });
+//
+// An app with its own migrations passes them as `app: { before, after }` (see MigrateOptions.app).
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { pathToFileURL } from "node:url";
 import type { SoftureConfig } from "@softure-ai/core";
-import { createDatabase, type DatabaseHandle } from "../client.js";
+import type { DatabaseHandle } from "../client.js";
+import { openCommandDatabase, type CommandDatabase } from "../configured.js";
 import { adoptModule } from "../migrations/adopt.js";
 import { exportMigrations } from "../migrations/export.js";
-import { migrate, planMigrations, type MigrationStep } from "../migrations/migrator.js";
+import { migrate, planMigrations, runAppMigrations, type AppMigrations, type MigrationStep } from "../migrations/migrator.js";
 import { describeProblem, type MigrationFailure } from "../migrations/problems.js";
 
 export interface CliOutput {
@@ -27,6 +30,12 @@ export interface RunMigrateCliOptions {
   /** Relative paths resolve against it. Default: `process.cwd()`. */
   readonly cwd?: string;
   readonly output?: CliOutput;
+  /**
+   * The app's own migrations: migrate runs `before`, the module files (adopting `baseline` where
+   * it applies), then `after`; `--adopt` (without `--plan`) runs `before` first; `--plan` runs no
+   * hook and marks the files a baseline may adopt.
+   */
+  readonly app?: AppMigrations;
 }
 
 export const EXIT_OK = 0;
@@ -39,7 +48,9 @@ Applies the SQL migrations of every enabled module, each in its own schema.
 
 Options:
   --plan                        show what would be applied (or adopted) and change nothing
-  --adopt <module>@<version>    record an existing schema as migrated, after comparing it
+  --adopt <module>@<version>    record an existing schema as migrated, after comparing it;
+                                applies the pending migrations of its dependencies first
+  --through <n>                 with --adopt: adopt files 1..n only, leave the rest to migrate
   --migrations-dir <dir>        read module files from <dir>/<module id>/ (bundled runners)
   --export-migrations <dir>     copy module files to <dir>/<module id>/ and exit (build stage)
   --help                        show this help`;
@@ -55,7 +66,7 @@ type Command =
   | { kind: "help" }
   | { kind: "export"; targetDir: string }
   | { kind: "migrate"; plan: boolean; migrationsDir: string | undefined }
-  | { kind: "adopt"; plan: boolean; module: string; version: string; migrationsDir: string | undefined };
+  | { kind: "adopt"; plan: boolean; module: string; version: string; through: number | undefined; migrationsDir: string | undefined };
 
 /** Runs the command and returns the process exit code: 0 done, 1 failed, 2 usage error. */
 export async function runMigrateCli(options: RunMigrateCliOptions): Promise<number> {
@@ -78,27 +89,29 @@ export async function runMigrateCli(options: RunMigrateCliOptions): Promise<numb
     return EXIT_OK;
   }
 
-  const url = options.config.database?.url;
-  if (url === undefined) {
+  const database = options.config.database;
+  if (database === null) {
     output.error("softure migrate: the config has no database; set database.url in softure.config");
     return EXIT_FAILED;
   }
-  let handle: DatabaseHandle;
+  let opened: CommandDatabase;
   try {
-    handle = await createDatabase(url);
+    // The app's configured handle when it set one, so the app's hooks and the run share one instance.
+    opened = await openCommandDatabase(database);
   } catch (error) {
     output.error(`softure migrate: ${describeError(error)}`);
     return EXIT_FAILED;
   }
+  const { handle } = opened;
   try {
     const migrationsDir = command.migrationsDir === undefined ? undefined : pathToFileURL(`${resolve(cwd, command.migrationsDir)}/`);
-    return await runDatabaseCommand(handle, { command, modules: options.config.modules, migrationsDir, output });
+    return await runDatabaseCommand(handle, { command, modules: options.config.modules, migrationsDir, output, app: options.app ?? {} });
   } catch (error) {
     // Connection and driver errors: the message only, never a stack or the database URL.
     output.error(`softure migrate: ${describeError(error)}`);
     return EXIT_FAILED;
   } finally {
-    await handle.close();
+    await opened.close();
   }
 }
 
@@ -109,43 +122,73 @@ async function runDatabaseCommand(
     modules: RunMigrateCliOptions["config"]["modules"];
     migrationsDir: URL | undefined;
     output: CliOutput;
+    app: AppMigrations;
   },
 ): Promise<number> {
-  const { command, modules, output } = input;
+  const { command, modules, output, app } = input;
   const dirOption = input.migrationsDir === undefined ? {} : { migrationsDir: input.migrationsDir };
 
+  const hasAppMigrations = app.before !== undefined || app.after !== undefined;
+  if (command.plan && hasAppMigrations) {
+    output.log("app migrations: not planned; the app runs them itself on migrate");
+  }
+
   if (command.kind === "adopt") {
-    const result = await adoptModule(handle, { modules, module: command.module, version: command.version, dryRun: command.plan, ...dirOption });
+    if (!command.plan) {
+      const before = await runAppMigrations(handle, app, "before");
+      if (!before.ok) return reportFailure(output, before);
+      if (before.value.ran) output.log("applied app migrations (before)");
+    }
+    const result = await adoptModule(handle, {
+      modules,
+      module: command.module,
+      version: command.version,
+      dryRun: command.plan,
+      ...(command.through === undefined ? {} : { through: command.through }),
+      ...dirOption,
+    });
     if (!result.ok) return reportFailure(output, result);
     const verb = command.plan ? "would" : "did";
-    result.value.ledger.forEach((step) => output.log(`${verb} apply ${formatStep(step)}`));
+    [...result.value.ledger, ...result.value.dependencies].forEach((step) => output.log(`${verb} apply ${formatStep(step)}`));
     result.value.adopted.forEach((step) => output.log(`${verb} adopt ${formatStep(step)}`));
-    output.log(`${command.module}@${command.version}: the schema matches its migrations${command.plan ? " (plan only, nothing written)" : "; adopted"}`);
+    const scope = command.through === undefined ? "" : ` through ${formatVersion(command.through)}`;
+    output.log(`${command.module}@${command.version}: the schema matches its migrations${scope}${command.plan ? " (plan only, nothing written)" : "; adopted"}`);
     return EXIT_OK;
   }
 
   if (command.plan) {
-    const result = await planMigrations(handle, { modules, ...dirOption });
+    const result = await planMigrations(handle, { modules, ...dirOption, app });
     if (!result.ok) return reportFailure(output, result);
-    result.value.pending.forEach((step) => output.log(`pending ${formatStep(step)}`));
+    const baseline = new Set(result.value.baseline);
+    result.value.pending.forEach((step) =>
+      output.log(`pending ${formatStep(step)}${baseline.has(step) ? " (adopted if its schema already holds objects)" : ""}`),
+    );
     output.log(result.value.pending.length === 0 ? "nothing to apply" : `${result.value.pending.length} migration(s) to apply`);
     return EXIT_OK;
   }
 
-  const result = await migrate(handle, { modules, ...dirOption, onApplied: (step) => output.log(`applied ${formatStep(step)}`) });
+  const result = await migrate(handle, {
+    modules,
+    ...dirOption,
+    app,
+    onApplied: (step) => output.log(`applied ${formatStep(step)}`),
+    onAdopted: (step) => output.log(`adopted ${formatStep(step)}`),
+    onAppMigrated: (phase) => output.log(`applied app migrations (${phase})`),
+  });
   if (!result.ok) return reportFailure(output, result);
-  output.log(result.value.applied.length === 0 ? "nothing to apply" : `${result.value.applied.length} migration(s) applied`);
+  output.log(formatSummary(result.value.applied.length, result.value.adopted.length));
   return EXIT_OK;
 }
 
 function parseCommand(argv: readonly string[]): Command | string {
-  let values: { plan?: boolean; adopt?: string; "migrations-dir"?: string; "export-migrations"?: string; help?: boolean };
+  let values: { plan?: boolean; adopt?: string; through?: string; "migrations-dir"?: string; "export-migrations"?: string; help?: boolean };
   try {
     ({ values } = parseArgs({
       args: [...argv],
       options: {
         plan: { type: "boolean" },
         adopt: { type: "string" },
+        through: { type: "string" },
         "migrations-dir": { type: "string" },
         "export-migrations": { type: "string" },
         help: { type: "boolean" },
@@ -160,19 +203,28 @@ function parseCommand(argv: readonly string[]): Command | string {
   if (values.help === true) return { kind: "help" };
   const exportDir = values["export-migrations"];
   if (exportDir !== undefined) {
-    const others = (["plan", "adopt", "migrations-dir"] as const).filter((name) => values[name] !== undefined);
+    const others = (["plan", "adopt", "through", "migrations-dir"] as const).filter((name) => values[name] !== undefined);
     return others.length > 0 ? `--export-migrations cannot be combined with --${others.join(", --")}` : { kind: "export", targetDir: exportDir };
   }
   const plan = values.plan === true;
   const migrationsDir = values["migrations-dir"];
   if (values.adopt === undefined) {
-    return { kind: "migrate", plan, migrationsDir };
+    return values.through === undefined ? { kind: "migrate", plan, migrationsDir } : "--through needs --adopt <module>@<version>";
   }
   const match = ADOPT_TARGET.exec(values.adopt);
   if (match?.[1] === undefined || match[2] === undefined) {
     return `--adopt expects <module>@<x.y.z>, e.g. auth@0.1.0, got "${values.adopt}"`;
   }
-  return { kind: "adopt", plan, module: match[1], version: match[2], migrationsDir };
+  const through = values.through === undefined ? undefined : parseThrough(values.through);
+  if (through === null) {
+    return `--through expects a positive whole number, got "${values.through ?? ""}"`;
+  }
+  return { kind: "adopt", plan, module: match[1], version: match[2], through, migrationsDir };
+}
+
+/** A positive whole number written in digits, or null. */
+function parseThrough(text: string): number | null {
+  return /^[1-9]\d*$/.test(text) ? Number(text) : null;
 }
 
 function reportFailure(output: CliOutput, failure: MigrationFailure): number {
@@ -181,7 +233,16 @@ function reportFailure(output: CliOutput, failure: MigrationFailure): number {
 }
 
 function formatStep(step: MigrationStep): string {
-  return `${step.module} ${String(step.version).padStart(4, "0")}_${step.name}.sql`;
+  return `${step.module} ${formatVersion(step.version)}_${step.name}.sql`;
+}
+
+function formatVersion(version: number): string {
+  return String(version).padStart(4, "0");
+}
+
+function formatSummary(applied: number, adopted: number): string {
+  if (applied === 0 && adopted === 0) return "nothing to apply";
+  return adopted === 0 ? `${applied} migration(s) applied` : `${applied} migration(s) applied, ${adopted} adopted`;
 }
 
 function describeError(error: unknown): string {

package/src/client.ts

@@ -1,8 +1,9 @@
-// The database client (FIRE_TRACKER `src/db/client.ts`, generalised). The driver follows the URL:
+// The database client. The driver follows the URL:
 // `postgres://` or `postgresql://` → node-postgres (production), `pglite://<dir>` → PGlite, a
 // real Postgres in-process (dev without a server); `pglite://` alone is an in-memory database.
-// Drivers load through dynamic `import()`, so a bundle can keep both external and an app pays
-// only for the one it uses.
+// Both drivers are optional peers and load through dynamic `import()` only when a URL needs one, so an app
+// installs and ships just its own. The specifiers stay literal: a Next.js app lists this package in
+// `serverExternalPackages`, and output tracing follows these imports to copy the installed driver.
 import type { PGlite } from "@electric-sql/pglite";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { PgliteDatabase } from "drizzle-orm/pglite";
@@ -10,18 +11,37 @@ import type { Pool } from "pg";
 
 const PGLITE_PREFIX = "pglite://";
 const POSTGRES_PREFIXES = ["postgres://", "postgresql://"];
+const MODULE_NOT_FOUND_CODES = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"]);
 
-export type PostgresDatabase = NodePgDatabase & { $client: Pool };
-export type PgliteClientDatabase = PgliteDatabase & { $client: PGlite };
+/** The optional peer a URL scheme needs, named in the error when it is not installed. */
+export interface DriverRequirement {
+  readonly packageName: string;
+  readonly scheme: string;
+}
+
+const POSTGRES_DRIVER: DriverRequirement = { packageName: "pg", scheme: "postgres://" };
+const PGLITE_DRIVER: DriverRequirement = { packageName: "@electric-sql/pglite", scheme: "pglite://" };
+
+/**
+ * The drizzle schema a database is typed with. The default accepts any schema, so an app database made with
+ * `drizzle({ client, schema })` (and its transactions) can be passed wherever a module takes `Database` or
+ * `Queryable`; pass the app's schema to keep its relational `db.query` API typed.
+ */
+export type DatabaseSchema = Record<string, unknown>;
+
+export type PostgresDatabase<TSchema extends DatabaseSchema = DatabaseSchema> = NodePgDatabase<TSchema> & { $client: Pool };
+export type PgliteClientDatabase<TSchema extends DatabaseSchema = DatabaseSchema> = PgliteDatabase<TSchema> & { $client: PGlite };
 
 /** The drizzle database modules and the app query through. */
-export type Database = PostgresDatabase | PgliteClientDatabase;
+export type Database<TSchema extends DatabaseSchema = DatabaseSchema> = PostgresDatabase<TSchema> | PgliteClientDatabase<TSchema>;
 
 /**
  * A connection *or* an open transaction. Query helpers take this, so one function serves a
- * plain read and a step inside `db.transaction()` (FIRE `client.ts`).
+ * plain read and a step inside `db.transaction()`.
  */
-export type Queryable = Database | Parameters<Parameters<Database["transaction"]>[0]>[0];
+export type Queryable<TSchema extends DatabaseSchema = DatabaseSchema> =
+  | Database<TSchema>
+  | Parameters<Parameters<Database<TSchema>["transaction"]>[0]>[0];
 
 export type DatabaseHandle =
   | {
@@ -43,36 +63,88 @@ export interface CreateDatabaseOptions {
 }
 
 /**
- * Opens the database a URL points at. Throws when the scheme is not supported: that is a
- * deployment bug. The message names the scheme only, never the URL, which holds a password.
+ * Opens the database a URL points at. Throws when the URL is empty or its scheme is not supported:
+ * that is a deployment bug. The message names the scheme only, never the URL, which holds a password.
+ * The config accepts an empty URL (a build has no DATABASE_URL), so this is where it is refused.
  */
 export async function createDatabase(url: string, options: CreateDatabaseOptions = {}): Promise<DatabaseHandle> {
+  if (url === "") {
+    throw new Error("createDatabase: the database URL is empty; set database.url in softure.config (usually from DATABASE_URL)");
+  }
   if (url.startsWith(PGLITE_PREFIX)) {
     const dataDir = url.slice(PGLITE_PREFIX.length);
-    const { PGlite } = await import("@electric-sql/pglite");
+    const { PGlite } = await importDriver(PGLITE_DRIVER, () => import("@electric-sql/pglite"));
     const client = dataDir === "" ? new PGlite() : new PGlite(dataDir);
     return createPgliteHandle(client);
   }
   if (POSTGRES_PREFIXES.some((prefix) => url.startsWith(prefix))) {
-    const { default: pg } = await import("pg");
-    const { drizzle } = await import("drizzle-orm/node-postgres");
+    const { default: pg } = await importDriver(POSTGRES_DRIVER, () => import("pg"));
     const pool = new pg.Pool({ connectionString: url, max: options.max ?? 10 });
     // An idle client that loses its connection emits 'error' on the pool; unhandled, it would
     // crash the process. The pool drops that client and the next query opens a new one.
     pool.on("error", () => undefined);
-    return { kind: "postgres", db: drizzle({ client: pool }), pool, close: () => pool.end() };
+    return createPostgresHandle(pool);
   }
   throw new Error(
     `createDatabase: unsupported database URL scheme ${describeScheme(url)}; use postgres://, postgresql:// or pglite://<dir>`,
   );
 }
 
-/** Wraps an open PGlite instance (used by `createTestDatabase`). */
+/**
+ * Wraps an open PGlite instance, e.g. the app's own, for `database.handle` in softure.config. `close` closes the
+ * instance, which writes a `pglite://<dir>` database back to its directory.
+ */
 export async function createPgliteHandle(client: PGlite): Promise<DatabaseHandle & { kind: "pglite" }> {
-  const { drizzle } = await import("drizzle-orm/pglite");
+  const { drizzle } = await importDriver(PGLITE_DRIVER, () => import("drizzle-orm/pglite"));
   return { kind: "pglite", db: drizzle({ client }), client, close: () => client.close() };
 }
 
+/**
+ * Wraps an open node-postgres pool, e.g. the app's own, for `database.handle` in softure.config. `close` ends
+ * the pool. The pool's `error` listener stays the app's: add one, or an idle client's lost connection crashes
+ * the process.
+ */
+export async function createPostgresHandle(pool: Pool): Promise<DatabaseHandle & { kind: "postgres" }> {
+  const { drizzle } = await importDriver(POSTGRES_DRIVER, () => import("drizzle-orm/node-postgres"));
+  return { kind: "postgres", db: drizzle({ client: pool }), pool, close: () => pool.end() };
+}
+
+/** Whether `value` has the shape of a `DatabaseHandle` (what `database.handle` must return). */
+export function isDatabaseHandle(value: unknown): value is DatabaseHandle {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate.db !== "object" || candidate.db === null || typeof candidate.close !== "function") return false;
+  if (candidate.kind === "postgres") return typeof candidate.pool === "object" && candidate.pool !== null;
+  if (candidate.kind === "pglite") return typeof candidate.client === "object" && candidate.client !== null;
+  return false;
+}
+
+/**
+ * Turns Node's "Cannot find package" for a driver (from the driver import or from drizzle's adapter, which imports
+ * it statically) into an error that says what to install. Anything else, including a missing package other than
+ * the driver, is returned unchanged.
+ */
+export function explainMissingDriver(error: unknown, driver: DriverRequirement): unknown {
+  if (!(error instanceof Error)) return error;
+  const code = (error as Error & { code?: unknown }).code;
+  if (typeof code !== "string" || !MODULE_NOT_FOUND_CODES.has(code)) return error;
+  if (!error.message.includes(`'${driver.packageName}'`)) return error;
+  return new Error(
+    `createDatabase: ${driver.scheme} URLs need the "${driver.packageName}" package, which is not installed; run ` +
+      `\`npm install ${driver.packageName}\` and, in a Next.js app, list "@softure-ai/db" and "${driver.packageName}" ` +
+      "in serverExternalPackages (db README §2)",
+    { cause: error },
+  );
+}
+
+async function importDriver<T>(driver: DriverRequirement, load: () => Promise<T>): Promise<T> {
+  try {
+    return await load();
+  } catch (error) {
+    throw explainMissingDriver(error, driver);
+  }
+}
+
 function describeScheme(url: string): string {
   const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(url)?.[1];
   return scheme === undefined ? "(none)" : `"${scheme}:"`;

package/src/configured.ts

@@ -0,0 +1,109 @@
+// The handle a config's database resolves to: the app's own (`database.handle`) when it set one, so one
+// process never holds two handles on one database (with `pglite://`, two PGlite instances on one directory
+// corrupt it), otherwise the process-wide handle for `database.url`. Module adapters, the health route and the
+// package commands all resolve through here.
+import type { SoftureDatabaseConfig } from "@softure-ai/core";
+import { createDatabase, isDatabaseHandle, type CreateDatabaseOptions, type DatabaseHandle } from "./client.js";
+import { getSharedDatabase } from "./shared.js";
+
+declare module "@softure-ai/core" {
+  interface SoftureDatabaseHandleTypes {
+    readonly handle: DatabaseHandle;
+  }
+}
+
+type HandleSource = NonNullable<SoftureDatabaseConfig["handle"]>;
+
+const CONFIGURED_KEY = Symbol.for("@softure-ai/db/configured-handles");
+
+interface ConfiguredHandles {
+  /** Keyed by the app's function: `next dev` re-evaluates the config, and a new function is a new entry. */
+  readonly byFunction: WeakMap<HandleSource, Promise<DatabaseHandle>>;
+  /** The same promises, so `closeConfiguredDatabases` can reach them. */
+  readonly open: Set<Promise<DatabaseHandle>>;
+}
+
+type HandleHost = Record<typeof CONFIGURED_KEY, ConfiguredHandles | undefined>;
+
+const host = globalThis as unknown as HandleHost;
+
+function getConfiguredHandles(): ConfiguredHandles {
+  return (host[CONFIGURED_KEY] ??= { byFunction: new WeakMap(), open: new Set() });
+}
+
+/**
+ * The handle for the config's database: the app's `database.handle`, called once per function and checked, or
+ * else `getSharedDatabase(database.url)`. Never closes anything; for a server's whole life. A failed or invalid
+ * `handle` call is not kept, so the next call tries again.
+ */
+export function getConfiguredDatabase(database: SoftureDatabaseConfig): Promise<DatabaseHandle> {
+  const source = database.handle;
+  if (source === undefined) return getSharedDatabase(database.url);
+
+  const handles = getConfiguredHandles();
+  let handle = handles.byFunction.get(source);
+  if (handle === undefined) {
+    handle = resolveHandle(source);
+    const opened = handle;
+    handles.byFunction.set(source, opened);
+    handles.open.add(opened);
+    opened.catch(() => {
+      handles.byFunction.delete(source);
+      handles.open.delete(opened);
+    });
+  }
+  return handle;
+}
+
+async function resolveHandle(source: HandleSource): Promise<DatabaseHandle> {
+  const value: unknown = await source();
+  if (!isDatabaseHandle(value)) {
+    throw new Error(
+      "database.handle: the function must return a database handle; wrap the app's client with createPostgresHandle(pool) or createPgliteHandle(client) from @softure-ai/db",
+    );
+  }
+  return value;
+}
+
+export interface CommandDatabase {
+  readonly handle: DatabaseHandle;
+  /** Closes what the command opened: its own handle, or the app's configured one (and forgets it). */
+  readonly close: () => Promise<void>;
+}
+
+/**
+ * The database for a command's own process (`softure migrate`, a module CLI, an ops script): the app's
+ * configured handle when `database.handle` is set, so the app's hooks and the command share one instance,
+ * otherwise a new handle on `database.url` with `options`. `close` closes either one; a `pglite://` directory is
+ * written back only then. Not for a running server: closing would close the app's handle under it.
+ */
+export async function openCommandDatabase(database: SoftureDatabaseConfig, options: CreateDatabaseOptions = {}): Promise<CommandDatabase> {
+  const source = database.handle;
+  if (source === undefined) {
+    const handle = await createDatabase(database.url, options);
+    return { handle, close: handle.close };
+  }
+  const opened = getConfiguredDatabase(database);
+  const handle = await opened;
+  return {
+    handle,
+    close: async () => {
+      const handles = getConfiguredHandles();
+      handles.byFunction.delete(source);
+      handles.open.delete(opened);
+      await handle.close();
+    },
+  };
+}
+
+/**
+ * Closes and forgets every configured handle this process resolved. For tests; at shutdown the app closes its own
+ * handle, which it owns (`closeSharedDatabases` leaves configured handles alone for that reason).
+ */
+export async function closeConfiguredDatabases(): Promise<void> {
+  const handles = host[CONFIGURED_KEY];
+  if (handles === undefined) return;
+  host[CONFIGURED_KEY] = undefined;
+  const results = await Promise.allSettled([...handles.open]);
+  await Promise.all(results.flatMap((result) => (result.status === "fulfilled" ? [result.value.close()] : [])));
+}

package/src/driver-errors.ts

@@ -0,0 +1,40 @@
+// The Postgres error behind a failed query. node-postgres and PGlite both put the SQLSTATE in `code` and the
+// violated constraint's name in `constraint`; drizzle wraps that error as the `cause` of its own query error.
+// App and module code that turns a known violation into a result (a taken slug, a conflicting row) reads it here.
+
+/** How many `cause` links are followed: drizzle adds one, an app's own wrapper may add another. */
+const MAX_CAUSE_DEPTH = 5;
+
+export interface DriverError {
+  /** The SQLSTATE, e.g. `23505` (unique violation) or `23P01` (exclusion violation). */
+  readonly code: string;
+  /** The violated constraint's name, when the error is about one. */
+  readonly constraint: string | undefined;
+  readonly message: string;
+}
+
+export interface ConstraintViolation {
+  /** The SQLSTATE to match, e.g. `23505`. */
+  readonly code: string;
+  /** The constraint's name; when left out, any constraint (or none) matches. */
+  readonly constraint?: string;
+}
+
+/** The driver error behind `error` (itself or one of its causes), or undefined when there is none. */
+export function findDriverError(error: unknown): DriverError | undefined {
+  for (let current: unknown = error, depth = 0; current instanceof Error && depth < MAX_CAUSE_DEPTH; current = current.cause, depth += 1) {
+    const { code, constraint } = current as { code?: unknown; constraint?: unknown };
+    if (typeof code === "string") return { code, constraint: typeof constraint === "string" ? constraint : undefined, message: current.message };
+  }
+  return undefined;
+}
+
+/**
+ * Whether `error` is the driver's `violation.code`, on `violation.constraint` when given:
+ * `isConstraintViolation(error, { code: "23505", constraint: "articles_slug_key" })` for a taken slug.
+ */
+export function isConstraintViolation(error: unknown, violation: ConstraintViolation): boolean {
+  const driverError = findDriverError(error);
+  if (driverError?.code !== violation.code) return false;
+  return violation.constraint === undefined || driverError.constraint === violation.constraint;
+}

package/src/index.ts

@@ -2,14 +2,21 @@
 // (docs/02-module-standard.md §4). Test databases: `@softure-ai/db/testing`; CLI: `@softure-ai/db/cli`.
 export {
   createDatabase,
+  createPgliteHandle,
+  createPostgresHandle,
+  isDatabaseHandle,
   type CreateDatabaseOptions,
   type Database,
   type DatabaseHandle,
+  type DatabaseSchema,
   type PgliteClientDatabase,
   type PostgresDatabase,
   type Queryable,
 } from "./client.js";
-export { closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { closeSharedDatabase, closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { createProcessDatabase, type ProcessDatabase, type ProcessDatabaseOptions } from "./process.js";
+export { findDriverError, isConstraintViolation, type ConstraintViolation, type DriverError } from "./driver-errors.js";
+export { closeConfiguredDatabases, getConfiguredDatabase, openCommandDatabase, type CommandDatabase } from "./configured.js";
 export { computeChecksum, readMigrationFiles, type MigrationFile } from "./migrations/files.js";
 export {
   describeProblem,
@@ -21,6 +28,10 @@ export {
 export {
   migrate,
   planMigrations,
+  runAppMigrations,
+  type AppMigrationHook,
+  type AppMigrationPhase,
+  type AppMigrations,
   type MigrateOptions,
   type MigrationPlan,
   type MigrationReport,