@softure-ai/db 0.0.0-stage → 0.1.6

package/dist/testing.js

@@ -0,0 +1,62 @@
+// 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`). An app with its own migrations
+// passes the same `app` hooks (and baseline) as to `migrate`, so module tables can reference app
+// tables and a module the app's history already creates is adopted in the template.
+import { PGlite } from "@electric-sql/pglite";
+import { createPgliteHandle } from "./client.js";
+import { migrate } from "./migrations/migrator.js";
+import { describeProblem } from "./migrations/problems.js";
+const templates = new Map();
+const hookIds = new WeakMap();
+let nextHookId = 1;
+/**
+ * A fresh, migrated, in-memory database per call. List the module under test and the modules it
+ * depends on. Throws when a migration (a module file or an app hook) fails: that is a bug in the
+ * module package or the app's migrations.
+ */
+export async function createTestDatabase(modules = [], options = {}) {
+    const client = new PGlite({ loadDataDir: await getTemplate(modules, options.app ?? {}) });
+    const handle = await createPgliteHandle(client);
+    return { db: handle.db, client, close: handle.close };
+}
+function getTemplate(modules, app) {
+    const moduleKey = modules.map((module) => `${module.id}@${module.migrations?.dir.href ?? "-"}`).join("|");
+    const baselineKey = Object.entries(app.baseline ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([id, through]) => `${id}:${through}`).join(",");
+    const key = `${moduleKey}#before:${identifyHook(app.before)}#after:${identifyHook(app.after)}#baseline:${baselineKey}`;
+    let template = templates.get(key);
+    if (template === undefined) {
+        template = buildTemplate(modules, app);
+        templates.set(key, template);
+        // A failed build is not cached: the next call reports the problem again.
+        template.catch(() => templates.delete(key));
+    }
+    return template;
+}
+// Hooks are functions, so the key holds an id per hook object rather than its source text.
+function identifyHook(hook) {
+    if (hook === undefined) {
+        return "-";
+    }
+    let id = hookIds.get(hook);
+    if (id === undefined) {
+        id = nextHookId++;
+        hookIds.set(hook, id);
+    }
+    return String(id);
+}
+async function buildTemplate(modules, app) {
+    const handle = await createPgliteHandle(new PGlite());
+    try {
+        const result = await migrate(handle, { modules, app });
+        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();
+    }
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@softure-ai/db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.6",
+  "description": "SOFTURE AI database layer: pg/PGlite client, per-module migrator with plan and adopt, PGlite test databases.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SOFTURE/AI.git",
+    "directory": "foundation/db"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "softure": "./dist/cli/bin.js"
+  },
+  "exports": {
+    ".": {
+      "@softure-ai/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "@softure-ai/source": "./src/testing.ts",
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./cli": {
+      "@softure-ai/source": "./src/cli/index.ts",
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@softure-ai/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@electric-sql/pglite": "^0.5.0",
+    "@types/pg": "^8.11.0",
+    "drizzle-orm": "^0.45.2",
+    "pg": "^8.11.0"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "@types/pg": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "@types/pg": "^8.23.1",
+    "pg": "^8.23.1"
+  }
+}

package/src/cli/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `softure` executable. All logic lives in command.ts, which the tests call directly.
+import { runSoftureCommand } from "./command.js";
+
+process.exitCode = await runSoftureCommand({ argv: process.argv.slice(2), cwd: process.cwd() });

package/src/cli/command.ts

@@ -0,0 +1,47 @@
+// The `softure` bin: `softure migrate [--config <file>] [options]`. It loads the app's config through
+// `@softure-ai/core/cli`, so the file must be loadable by Node itself: `.js`/`.mjs`, or `.ts` where
+// Node strips types (Node >= 22.18; relative imports then need `.ts` extensions). Anything else
+// uses an app script with `runMigrateCli` instead (see run.ts).
+import { loadAppConfig, takeConfigOption } from "@softure-ai/core/cli";
+import { EXIT_FAILED, EXIT_OK, EXIT_USAGE, MIGRATE_USAGE, runMigrateCli, type CliOutput } from "./run.js";
+
+export interface RunSoftureCommandOptions {
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly output?: CliOutput;
+}
+
+const APP_SCRIPT = { runner: "runMigrateCli", packageName: "@softure-ai/db" };
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+export async function runSoftureCommand(options: RunSoftureCommandOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const [command, ...rest] = options.argv;
+  if (command !== "migrate") {
+    output.error(command === undefined ? "softure: missing command" : `softure: unknown command "${command}"`);
+    output.error("Commands: migrate");
+    output.error(MIGRATE_USAGE);
+    return EXIT_USAGE;
+  }
+
+  if (rest.includes("--help")) {
+    output.log(MIGRATE_USAGE);
+    return EXIT_OK;
+  }
+  const taken = takeConfigOption(rest);
+  if (!taken.ok) {
+    output.error(`softure migrate: ${taken.problem}`);
+    output.error(MIGRATE_USAGE);
+    return EXIT_USAGE;
+  }
+  const loaded = await loadAppConfig({ cwd: options.cwd, configPath: taken.configPath, appScript: APP_SCRIPT });
+  if (!loaded.ok) {
+    output.error(`softure: ${loaded.problem}`);
+    return EXIT_FAILED;
+  }
+  return runMigrateCli({ config: loaded.config, argv: taken.argv, cwd: options.cwd, output });
+}

package/src/cli/index.ts

@@ -0,0 +1,3 @@
+// `@softure-ai/db/cli`: the `softure migrate` command for app scripts and container bundles.
+export { runSoftureCommand, type RunSoftureCommandOptions } from "./command.js";
+export { EXIT_FAILED, EXIT_OK, EXIT_USAGE, MIGRATE_USAGE, runMigrateCli, type CliOutput, type RunMigrateCliOptions } from "./run.js";

package/src/cli/run.ts

@@ -0,0 +1,250 @@
+// `softure migrate` (docs/02-module-standard.md §4). The app passes its validated config, so the
+// same function serves the `softure` bin and an app script that esbuild bundles for a container:
+//
+//   // scripts/migrate.ts
+//   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 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, runAppMigrations, type AppMigrations, type MigrationStep } from "../migrations/migrator.js";
+import { describeProblem, type MigrationFailure } from "../migrations/problems.js";
+
+export interface CliOutput {
+  readonly log: (line: string) => void;
+  readonly error: (line: string) => void;
+}
+
+export interface RunMigrateCliOptions {
+  readonly config: Pick<SoftureConfig, "database" | "modules">;
+  /** The arguments after the command name, e.g. `["--plan"]`. */
+  readonly argv: readonly string[];
+  /** 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;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+
+export const MIGRATE_USAGE = `Usage: softure migrate [options]
+
+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;
+                                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`;
+
+const ADOPT_TARGET = /^([a-z][a-z0-9]*(?:-[a-z0-9]+)*)@(\d+\.\d+\.\d+)$/;
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+type Command =
+  | { kind: "help" }
+  | { kind: "export"; targetDir: string }
+  | { kind: "migrate"; plan: boolean; 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> {
+  const output = options.output ?? consoleOutput;
+  const cwd = options.cwd ?? process.cwd();
+  const command = parseCommand(options.argv);
+  if (typeof command === "string") {
+    output.error(`softure migrate: ${command}`);
+    output.error(MIGRATE_USAGE);
+    return EXIT_USAGE;
+  }
+  if (command.kind === "help") {
+    output.log(MIGRATE_USAGE);
+    return EXIT_OK;
+  }
+  if (command.kind === "export") {
+    const result = await exportMigrations(options.config.modules, resolve(cwd, command.targetDir));
+    if (!result.ok) return reportFailure(output, result);
+    result.value.forEach((step) => output.log(`exported ${formatStep(step)}`));
+    return EXIT_OK;
+  }
+
+  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 opened: CommandDatabase;
+  try {
+    // 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, 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 opened.close();
+  }
+}
+
+async function runDatabaseCommand(
+  handle: DatabaseHandle,
+  input: {
+    command: Extract<Command, { kind: "migrate" | "adopt" }>;
+    modules: RunMigrateCliOptions["config"]["modules"];
+    migrationsDir: URL | undefined;
+    output: CliOutput;
+    app: AppMigrations;
+  },
+): Promise<number> {
+  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") {
+    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, ...result.value.dependencies].forEach((step) => output.log(`${verb} apply ${formatStep(step)}`));
+    result.value.adopted.forEach((step) => output.log(`${verb} adopt ${formatStep(step)}`));
+    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, app });
+    if (!result.ok) return reportFailure(output, result);
+    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,
+    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(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; 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" },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (error) {
+    return describeError(error);
+  }
+
+  if (values.help === true) return { kind: "help" };
+  const exportDir = values["export-migrations"];
+  if (exportDir !== 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 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}"`;
+  }
+  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 {
+  failure.problems.forEach((problem) => output.error(describeProblem(problem)));
+  return EXIT_FAILED;
+}
+
+function formatStep(step: MigrationStep): string {
+  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 {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/client.ts

@@ -0,0 +1,151 @@
+// 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.
+// 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";
+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"]);
+
+/** 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<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()`.
+ */
+export type Queryable<TSchema extends DatabaseSchema = DatabaseSchema> =
+  | Database<TSchema>
+  | Parameters<Parameters<Database<TSchema>["transaction"]>[0]>[0];
+
+export type DatabaseHandle =
+  | {
+      readonly kind: "postgres";
+      readonly db: PostgresDatabase;
+      readonly pool: Pool;
+      readonly close: () => Promise<void>;
+    }
+  | {
+      readonly kind: "pglite";
+      readonly db: PgliteClientDatabase;
+      readonly client: PGlite;
+      readonly close: () => Promise<void>;
+    };
+
+export interface CreateDatabaseOptions {
+  /** Pool size for Postgres; ignored by PGlite, which has a single connection. Default 10. */
+  readonly max?: number;
+}
+
+/**
+ * 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 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 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 createPostgresHandle(pool);
+  }
+  throw new Error(
+    `createDatabase: unsupported database URL scheme ${describeScheme(url)}; use postgres://, postgresql:// or pglite://<dir>`,
+  );
+}
+
+/**
+ * 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 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}:"`;
+}