@softure-ai/db 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,26 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`db@x.y.z`).
 
+## 0.1.8
+
+- `createProcessDatabase(url, { globalKey })` keeps the open database on `globalThis`, so a module `next dev`
+  re-evaluates finds it; `closeProcessDatabases()` closes every process database, for tests (#404).
+- `@softure-ai/db/testing`: `expectEntriesOpenDatabase({ entries, clientModule, opens })` and
+  `findEntriesReachingDatabase(...)`, an entry-point guard over esbuild's import graph (`esbuild` is an optional
+  peer) (#404).
+- `drizzleAppMigrations(folder)`: an app migration hook running drizzle's migrator for the handle's driver (#404).
+- `queryDatabase(handle, text, values)` and `openRawDatabase(url)`: parameterized raw SQL for scripts on either
+  driver (#404).
+
+## 0.1.7
+
+- `createProcessDatabase(url, { schema, max })` returns `{ db, open, close, withDatabase, isOpen }`: a module-level,
+  synchronous `db` over the process-wide handle for the URL. A query before `open()` throws `Database is not open`;
+  `withDatabase(main)` opens, runs and closes for a script. `url` may be a function, read on `open()` (#313).
+- `findDriverError(error)` (`{ code, constraint, message }` of the Postgres error under drizzle's wrapper) and
+  `isConstraintViolation(error, { code, constraint })`, so apps and modules stop copying them (#313).
+- `closeSharedDatabase(url)` closes and forgets one shared handle.
+
 ## 0.1.6
 
 - One database handle per process: `getConfiguredDatabase` opens the config's `database.handle` or URL once, and modules, health route and commands share it.

package/README.md

@@ -7,7 +7,10 @@ The database layer every SOFTURE module stands on. Standard:
 
 A pg/PGlite client chosen by URL, a migrator that runs each module's SQL in the module's own
 Postgres schema (with a ledger, checksums, a lock, a dry run and adoption of existing tables),
-`createTestDatabase` for unit tests, and the `softure migrate` command.
+`createTestDatabase` for unit tests, the `softure migrate` command, a module-level process database
+(`createProcessDatabase`) with an entry-point guard for tests, `drizzleAppMigrations` for the app's own
+drizzle folder, raw parameterized queries for scripts (`queryDatabase`, `openRawDatabase`) and helpers that
+read the Postgres error behind a failed query (`findDriverError`, `isConstraintViolation`).
 
 ## 2. Installation
 
@@ -140,6 +143,100 @@ export async function getDb() {
 the modules use can call it too. A migration run on a PGlite handle the app shares keeps the app's
 session settings (`TimeZone`, `search_path`); only what the run changed is put back.
 
+### A module-level `db`
+
+An app whose code imports one `db` everywhere, instead of awaiting a handle in each function,
+creates it once with `createProcessDatabase`. `db` stands in for the shared handle's drizzle instance
+(the one `getSharedDatabase(url)` gives the modules, so there is still one pool); every entry point
+opens it first, and a query before that throws `Database is not open`:
+
+```ts
+// db/index.ts
+import { createProcessDatabase } from "@softure-ai/db";
+import * as schema from "./schema";
+
+// A function: read on open(), so a script may load its environment after importing this file.
+export const { db, open, close, withDatabase } = createProcessDatabase(() => process.env.DATABASE_URL ?? "", { schema });
+
+// instrumentation.ts (the server): open once at startup
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") await (await import("./db")).open();
+}
+
+// scripts/import.ts: opens, runs, closes (also when main throws)
+await withDatabase(async (db) => { /* … */ });
+```
+
+`open()` is idempotent; `close()` closes the shared handle for that URL, which the modules use too,
+so only a script's end calls it. With `schema`, `db.query.<table>` is typed and works.
+
+`next dev` re-evaluates `db/index.ts` on a change, and a new evaluation would refuse queries until
+something opens it again. `globalKey` keeps the open database on `globalThis`, so every evaluation
+finds it (the open `db` keeps the schema it was opened with until a restart):
+
+```ts
+export const { db, open, close, withDatabase } = createProcessDatabase(() => process.env.DATABASE_URL ?? "", {
+  schema,
+  globalKey: "app",
+});
+```
+
+In tests, `closeProcessDatabases()` in `afterEach` closes every process database the test opened.
+
+**Entry-point guard.** An entry that forgets `open()` fails only at its first query. A test in the app
+fails earlier: `expectEntriesOpenDatabase` (from `@softure-ai/db/testing`, needs `esbuild` as a dev
+dependency) follows each entry's imports and throws, naming them, when an entry reaches the database
+module without a call to `withDatabase(` or `open(` in its own source.
+`findEntriesReachingDatabase` returns `{ entry, opens }[]` for the same check by hand:
+
+```ts
+// tests/entry-points.test.ts
+import { expectEntriesOpenDatabase } from "@softure-ai/db/testing";
+
+it("opens the database at every entry", async () => {
+  await expectEntriesOpenDatabase({
+    entries: ["src/instrumentation.ts", "src/mcp/stdio.ts", "scripts/import.ts"],
+    clientModule: "src/db/index.ts",
+    // an app helper that opens it counts too
+    opens: [/\bwithDatabase\s*\(/, /\bopen\s*\(/, /\bopenConfiguredDatabase\s*\(/],
+  });
+});
+```
+
+### Raw queries for scripts
+
+An operator or report script that reads with plain SQL opens its own handle on the URL, whichever
+driver it names, and closes it at the end. Values bind to `$1`, `$2`, …; they never go into the text:
+
+```ts
+import { openRawDatabase } from "@softure-ai/db";
+
+const database = await openRawDatabase(process.env.DATABASE_URL ?? "");
+try {
+  const rows = await database.query<{ email: string }>("select email from users where created_at > $1", [since]);
+} finally {
+  await database.close();
+}
+```
+
+`queryDatabase(handle, text, values)` does the same over a handle the script already has.
+
+### Driver errors
+
+`findDriverError(error)` returns `{ code, constraint, message }` of the Postgres error behind a failed
+query (node-postgres and PGlite alike; drizzle wraps it as the `cause`), or `undefined`.
+`isConstraintViolation(error, { code, constraint })` answers whether it is that SQLSTATE on that
+constraint (any constraint when `constraint` is left out):
+
+```ts
+try {
+  await db.insert(articles).values(article);
+} catch (error) {
+  if (!isConstraintViolation(error, { code: "23505", constraint: "articles_slug_key" })) throw error;
+  return err("slug_taken");
+}
+```
+
 ## 4. Mounting
 
 Nothing to mount. Migrations run as a deploy step:
@@ -193,22 +290,12 @@ object to the migrate script and to `createTestDatabase`:
 
 ```ts
 // db/app-migrations.ts
-import type { AppMigrations, DatabaseHandle } from "@softure-ai/db";
-
-async function runDrizzle(handle: DatabaseHandle, migrationsFolder: string): Promise<void> {
-  if (handle.kind === "postgres") {
-    const { migrate } = await import("drizzle-orm/node-postgres/migrator");
-    await migrate(handle.db, { migrationsFolder });
-  } else {
-    const { migrate } = await import("drizzle-orm/pglite/migrator");
-    await migrate(handle.db, { migrationsFolder });
-  }
-}
+import { drizzleAppMigrations, type AppMigrations } from "@softure-ai/db";
 
 export const appMigrations: AppMigrations = {
-  before: (handle) => runDrizzle(handle, "./drizzle"),
+  before: drizzleAppMigrations("./drizzle"),
   // only when an app migration needs a module table: a second drizzle folder
-  // after: (handle) => runDrizzle(handle, "./drizzle-after"),
+  // after: drizzleAppMigrations("./drizzle-after"),
 };
 
 // scripts/migrate.ts
@@ -231,7 +318,7 @@ file the app's own history creates; `migrate` then adopts or migrates by itself,
 
 ```ts
 export const appMigrations: AppMigrations = {
-  before: (handle) => runDrizzle(handle, "./drizzle"),
+  before: drizzleAppMigrations("./drizzle"),
   // the app's history creates auth's 0001 (users, sessions); 0002.. are new to it
   baseline: { auth: 1 },
 };

package/dist/driver-errors.d.ts

@@ -0,0 +1,21 @@
+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 declare function findDriverError(error: unknown): DriverError | 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 declare function isConstraintViolation(error: unknown, violation: ConstraintViolation): boolean;
+//# sourceMappingURL=driver-errors.d.ts.map

package/dist/driver-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-errors.d.ts","sourceRoot":"","sources":["../src/driver-errors.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAMvE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAI7F"}

package/dist/driver-errors.js

@@ -0,0 +1,25 @@
+// 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;
+/** The driver error behind `error` (itself or one of its causes), or undefined when there is none. */
+export function findDriverError(error) {
+    for (let current = error, depth = 0; current instanceof Error && depth < MAX_CAUSE_DEPTH; current = current.cause, depth += 1) {
+        const { code, constraint } = current;
+        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, violation) {
+    const driverError = findDriverError(error);
+    if (driverError?.code !== violation.code)
+        return false;
+    return violation.constraint === undefined || driverError.constraint === violation.constraint;
+}
+//# sourceMappingURL=driver-errors.js.map

package/dist/driver-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-errors.js","sourceRoot":"","sources":["../src/driver-errors.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAC7G,8GAA8G;AAC9G,kHAAkH;AAElH,mGAAmG;AACnG,MAAM,eAAe,GAAG,CAAC,CAAC;AAiB1B,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,KAAK,IAAI,OAAO,GAAY,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,OAAO,YAAY,KAAK,IAAI,KAAK,GAAG,eAAe,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACvI,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,OAAmD,CAAC;QACjF,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/I,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,SAA8B;IAClF,MAAM,WAAW,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,WAAW,EAAE,IAAI,KAAK,SAAS,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACvD,OAAO,SAAS,CAAC,UAAU,KAAK,SAAS,IAAI,WAAW,CAAC,UAAU,KAAK,SAAS,CAAC,UAAU,CAAC;AAC/F,CAAC"}

package/dist/entry-guard.d.ts

@@ -0,0 +1,28 @@
+/** A call to `withDatabase(` or `open(` (`processDb.open(` too): what `createProcessDatabase` gives an entry. */
+export declare const DEFAULT_DATABASE_OPENERS: readonly RegExp[];
+export interface EntryGuardOptions {
+    /** The process entry points, as paths (relative to `workingDir`) or absolute paths. */
+    readonly entries: readonly string[];
+    /** The app's module that calls `createProcessDatabase` (e.g. `src/db/index.ts`). */
+    readonly clientModule: string;
+    /** Patterns an entry's own source must match to count as opening the database. Default: `DEFAULT_DATABASE_OPENERS`. */
+    readonly opens?: readonly RegExp[];
+    /** The directory paths and the app's tsconfig resolve from. Default: `process.cwd()`. */
+    readonly workingDir?: string;
+    /** Extra import paths esbuild leaves out of the graph (packages are always left out). */
+    readonly external?: readonly string[];
+}
+export interface EntryReach {
+    /** The entry as given in `entries`. */
+    readonly entry: string;
+    /** Whether the entry's own source opens the database. */
+    readonly opens: boolean;
+}
+/**
+ * The entries whose import graph (static and dynamic imports) reaches `clientModule`, in the order given, each
+ * with whether its own source opens the database. Entries that never reach it are left out.
+ */
+export declare function findEntriesReachingDatabase(options: EntryGuardOptions): Promise<EntryReach[]>;
+/** Throws, naming each one, when an entry reaches `clientModule` without opening the database. */
+export declare function expectEntriesOpenDatabase(options: EntryGuardOptions): Promise<void>;
+//# sourceMappingURL=entry-guard.d.ts.map

package/dist/entry-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-guard.d.ts","sourceRoot":"","sources":["../src/entry-guard.ts"],"names":[],"mappings":"AAQA,iHAAiH;AACjH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAA2C,CAAC;AAElG,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uHAAuH;IACvH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yFAAyF;IACzF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAID;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAenG;AAED,kGAAkG;AAClG,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzF"}

package/dist/entry-guard.js

@@ -0,0 +1,87 @@
+// The entry-point guard for an app on `createProcessDatabase`: `db` is synchronous but opening is not, so every
+// process entry (the server's instrumentation, an MCP stdio server, each script) must open the database before its
+// first query. esbuild resolves each entry's import graph (path aliases and re-exports included); an entry that
+// reaches the app's client module must call an opener in its own source. esbuild is an optional peer, loaded here.
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/** A call to `withDatabase(` or `open(` (`processDb.open(` too): what `createProcessDatabase` gives an entry. */
+export const DEFAULT_DATABASE_OPENERS = [/\bwithDatabase\s*\(/, /\bopen\s*\(/];
+const ASSET_EXTENSIONS = [".css", ".scss", ".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".woff", ".woff2"];
+/**
+ * The entries whose import graph (static and dynamic imports) reaches `clientModule`, in the order given, each
+ * with whether its own source opens the database. Entries that never reach it are left out.
+ */
+export async function findEntriesReachingDatabase(options) {
+    const workingDir = options.workingDir ?? process.cwd();
+    const clientPath = resolve(workingDir, options.clientModule);
+    if (!existsSync(clientPath)) {
+        throw new Error(`findEntriesReachingDatabase: the client module does not exist: ${options.clientModule}`);
+    }
+    const metafile = await buildMetafile(options.entries.map((entry) => resolve(workingDir, entry)), workingDir, options.external ?? []);
+    const opens = options.opens ?? DEFAULT_DATABASE_OPENERS;
+    return options.entries.flatMap((entry) => {
+        const entryPath = resolve(workingDir, entry);
+        if (!reaches(metafile, workingDir, entryPath, clientPath))
+            return [];
+        const source = readFileSync(entryPath, "utf8");
+        return [{ entry, opens: opens.some((pattern) => pattern.test(source)) }];
+    });
+}
+/** Throws, naming each one, when an entry reaches `clientModule` without opening the database. */
+export async function expectEntriesOpenDatabase(options) {
+    const missing = (await findEntriesReachingDatabase(options)).filter((reach) => !reach.opens);
+    if (missing.length === 0)
+        return;
+    throw new Error(`These entries reach the database client without opening it (call withDatabase() or open() at the entry):\n` +
+        missing.map((reach) => `  - ${reach.entry}`).join("\n"));
+}
+async function buildMetafile(entryPoints, workingDir, external) {
+    const { build } = await loadEsbuild();
+    const result = await build({
+        entryPoints: [...entryPoints],
+        absWorkingDir: workingDir,
+        // Never written (`write: false`); esbuild needs an output directory for several entries.
+        outdir: resolve(workingDir, ".entry-guard"),
+        bundle: true,
+        write: false,
+        metafile: true,
+        platform: "node",
+        format: "esm",
+        packages: "external",
+        external: [...external],
+        loader: Object.fromEntries(ASSET_EXTENSIONS.map((extension) => [extension, "empty"])),
+        logLevel: "silent",
+    }).catch((error) => {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`findEntriesReachingDatabase: esbuild could not follow the entries' imports: ${reason}`, { cause: error });
+    });
+    return result.metafile;
+}
+async function loadEsbuild() {
+    try {
+        return await import("esbuild");
+    }
+    catch (error) {
+        throw new Error("findEntriesReachingDatabase: needs the \"esbuild\" package; run `npm install --save-dev esbuild`", { cause: error });
+    }
+}
+function reaches(metafile, workingDir, entryPath, clientPath) {
+    const keyByPath = new Map(Object.keys(metafile.inputs).map((key) => [resolve(workingDir, key), key]));
+    const start = keyByPath.get(entryPath);
+    if (start === undefined)
+        return false;
+    const seen = new Set([start]);
+    const queue = [start];
+    for (let key = queue.shift(); key !== undefined; key = queue.shift()) {
+        if (resolve(workingDir, key) === clientPath)
+            return true;
+        for (const imported of metafile.inputs[key]?.imports ?? []) {
+            if (imported.external === true || seen.has(imported.path))
+                continue;
+            seen.add(imported.path);
+            queue.push(imported.path);
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=entry-guard.js.map

package/dist/entry-guard.js.map

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

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 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 { closeProcessDatabases, createProcessDatabase, type ProcessDatabase, type ProcessDatabaseOptions } from "./process.js";
+export { openRawDatabase, queryDatabase, type RawDatabase } from "./raw.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, type MigrationErrorCode, type MigrationFailure, type MigrationProblem, type MigrationResult, } from "./migrations/problems.js";
 export { migrate, planMigrations, runAppMigrations, type AppMigrationHook, type AppMigrationPhase, type AppMigrations, type MigrateOptions, type MigrationPlan, type MigrationReport, type MigrationStep, } from "./migrations/migrator.js";
+export { drizzleAppMigrations } from "./migrations/drizzle.js";
 export { adoptModule, type AdoptionReport, type AdoptOptions } from "./migrations/adopt.js";
 export { exportMigrations } from "./migrations/export.js";
 export { checkExportedMigrations, type ExportedMigration, type ExportedMigrationsCheck, } from "./migrations/exported.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC/H,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACxH,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,11 +1,15 @@
 // Public API of @softure-ai/db: the database client and the module migrator
 // (docs/02-module-standard.md §4). Test databases: `@softure-ai/db/testing`; CLI: `@softure-ai/db/cli`.
 export { createDatabase, createPgliteHandle, createPostgresHandle, isDatabaseHandle, } from "./client.js";
-export { closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { closeSharedDatabase, closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { closeProcessDatabases, createProcessDatabase } from "./process.js";
+export { openRawDatabase, queryDatabase } from "./raw.js";
+export { findDriverError, isConstraintViolation } from "./driver-errors.js";
 export { closeConfiguredDatabases, getConfiguredDatabase, openCommandDatabase } from "./configured.js";
 export { computeChecksum, readMigrationFiles } from "./migrations/files.js";
 export { describeProblem, } from "./migrations/problems.js";
 export { migrate, planMigrations, runAppMigrations, } from "./migrations/migrator.js";
+export { drizzleAppMigrations } from "./migrations/drizzle.js";
 export { adoptModule } from "./migrations/adopt.js";
 export { exportMigrations } from "./migrations/export.js";
 export { checkExportedMigrations, } from "./migrations/exported.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wGAAwG;AACxG,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,GAQjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAwB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAsB,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,GAKhB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,GAQjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAA0C,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,GAGxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAyC,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wGAAwG;AACxG,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,GAQjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAqD,MAAM,cAAc,CAAC;AAC/H,OAAO,EAAE,eAAe,EAAE,aAAa,EAAoB,MAAM,UAAU,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAA8C,MAAM,oBAAoB,CAAC;AACxH,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAwB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAsB,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,GAKhB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,GAQjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAA0C,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,GAGxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAyC,MAAM,wBAAwB,CAAC"}

package/dist/migrations/drizzle.d.ts

@@ -0,0 +1,8 @@
+import type { AppMigrationHook } from "./migrator.js";
+/**
+ * A hook for `app.before` (or `app.after`) that applies the drizzle-kit folder (`meta/_journal.json` and its SQL
+ * files) with drizzle's migrator. Drizzle skips what its ledger (`drizzle.__drizzle_migrations`) already holds, so
+ * the hook is safe on every `migrate` run. `folder` is a path (relative to the working directory) or a file URL.
+ */
+export declare function drizzleAppMigrations(folder: string | URL): AppMigrationHook;
+//# sourceMappingURL=drizzle.d.ts.map

package/dist/migrations/drizzle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../../src/migrations/drizzle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,GAAG,gBAAgB,CAW3E"}

package/dist/migrations/drizzle.js

@@ -0,0 +1,21 @@
+// The app's own drizzle-kit migrations as an app migration hook: drizzle's migrator for the handle's driver,
+// loaded only when the hook runs, so an app ships just its own driver.
+import { fileURLToPath } from "node:url";
+/**
+ * A hook for `app.before` (or `app.after`) that applies the drizzle-kit folder (`meta/_journal.json` and its SQL
+ * files) with drizzle's migrator. Drizzle skips what its ledger (`drizzle.__drizzle_migrations`) already holds, so
+ * the hook is safe on every `migrate` run. `folder` is a path (relative to the working directory) or a file URL.
+ */
+export function drizzleAppMigrations(folder) {
+    const migrationsFolder = typeof folder === "string" ? folder : fileURLToPath(folder);
+    return async (handle) => {
+        if (handle.kind === "postgres") {
+            const { migrate } = await import("drizzle-orm/node-postgres/migrator");
+            await migrate(handle.db, { migrationsFolder });
+            return;
+        }
+        const { migrate } = await import("drizzle-orm/pglite/migrator");
+        await migrate(handle.db, { migrationsFolder });
+    };
+}
+//# sourceMappingURL=drizzle.js.map

package/dist/migrations/drizzle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.js","sourceRoot":"","sources":["../../src/migrations/drizzle.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAC7G,uEAAuE;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAoB;IACvD,MAAM,gBAAgB,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACrF,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE;QACtB,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,oCAAoC,CAAC,CAAC;YACvE,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC;YAC/C,OAAO;QACT,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC;QAChE,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACjD,CAAC,CAAC;AACJ,CAAC"}

package/dist/process.d.ts

@@ -0,0 +1,34 @@
+import type { Database, DatabaseHandle, DatabaseSchema, CreateDatabaseOptions } from "./client.js";
+export interface ProcessDatabaseOptions<TSchema extends DatabaseSchema> extends CreateDatabaseOptions {
+    /** The app's drizzle schema: `db` is built with it, so `db.query.<table>` is typed and works. */
+    readonly schema?: TSchema;
+    /**
+     * Keeps the open database on `globalThis` under this key, so a module that `next dev` re-evaluates (HMR) finds the
+     * database its previous evaluation opened instead of refusing queries. One key per database in the process. The
+     * open `db` keeps the schema it was opened with; a changed schema takes effect after `close()` or a restart.
+     */
+    readonly globalKey?: string;
+}
+export interface ProcessDatabase<TSchema extends DatabaseSchema = DatabaseSchema> {
+    /** The open database. Usable from module scope; a query before `open()` resolves throws "Database is not open". */
+    readonly db: Database<TSchema>;
+    /** Opens the process-wide handle for the URL (`getSharedDatabase`), once; later calls return the same handle. */
+    readonly open: () => Promise<DatabaseHandle>;
+    /** Closes the handle and forgets it, so `db` refuses queries again. Does nothing when not open. */
+    readonly close: () => Promise<void>;
+    /** For a script: opens, runs `main` with `db`, and closes whether `main` resolves or throws. */
+    readonly withDatabase: <T>(main: (db: Database<TSchema>) => Promise<T>) => Promise<T>;
+    readonly isOpen: () => boolean;
+}
+/**
+ * A module-level database for the process. `url` may be a function, read on `open()`, so a script can load its
+ * environment after importing the module that creates it. The handle is the one `getSharedDatabase(url)` gives the
+ * modules, so the app and the modules share one pool (db README §3, "One handle per process").
+ */
+export declare function createProcessDatabase<TSchema extends DatabaseSchema = DatabaseSchema>(url: string | (() => string), options?: ProcessDatabaseOptions<TSchema>): ProcessDatabase<TSchema>;
+/**
+ * Closes every process database this process opened (with or without `globalKey`), so each `db` refuses queries
+ * until its `open()`. For tests' `afterEach`; a server's shutdown closes its own.
+ */
+export declare function closeProcessDatabases(): Promise<void>;
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../src/process.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAgBnG,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,cAAc,CAAE,SAAQ,qBAAqB;IACnG,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,cAAc,GAAG,cAAc;IAC9E,mHAAmH;IACnH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC/B,iHAAiH;IACjH,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7C,mGAAmG;IACnG,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACtF,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS,cAAc,GAAG,cAAc,EACnF,GAAG,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EAC5B,OAAO,GAAE,sBAAsB,CAAC,OAAO,CAAM,GAC5C,eAAe,CAAC,OAAO,CAAC,CAsC1B;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3D"}

package/dist/process.js

@@ -0,0 +1,116 @@
+import { closeSharedDatabase, getSharedDatabase } from "./shared.js";
+const NOT_OPEN_MESSAGE = "Database is not open: call open() or withDatabase() at the process entry before querying";
+const REGISTRY_KEY = Symbol.for("@softure-ai/db/process-databases");
+const host = globalThis;
+/**
+ * A module-level database for the process. `url` may be a function, read on `open()`, so a script can load its
+ * environment after importing the module that creates it. The handle is the one `getSharedDatabase(url)` gives the
+ * modules, so the app and the modules share one pool (db README §3, "One handle per process").
+ */
+export function createProcessDatabase(url, options = {}) {
+    const { schema, globalKey, ...databaseOptions } = options;
+    const state = getProcessState(globalKey);
+    const open = () => {
+        if (state.opening === undefined) {
+            getRegistry().add(state);
+            state.opening = openHandle().catch((error) => {
+                state.opening = undefined;
+                getRegistry().delete(state);
+                throw error;
+            });
+        }
+        return state.opening;
+    };
+    async function openHandle() {
+        const resolvedUrl = typeof url === "function" ? url() : url;
+        const handle = await getSharedDatabase(resolvedUrl, databaseOptions);
+        state.opened = { url: resolvedUrl, db: await buildDatabase(handle, schema) };
+        return handle;
+    }
+    const close = () => closeProcessState(state);
+    const withDatabase = async (main) => {
+        await open();
+        try {
+            return await main(db);
+        }
+        finally {
+            await close();
+        }
+    };
+    // The state holds whichever schema opened it; this instance's callers see it typed with their own.
+    const db = createDatabaseProxy(() => state.opened?.db);
+    return { db, open, close, withDatabase, isOpen: () => state.opened !== undefined };
+}
+/**
+ * Closes every process database this process opened (with or without `globalKey`), so each `db` refuses queries
+ * until its `open()`. For tests' `afterEach`; a server's shutdown closes its own.
+ */
+export async function closeProcessDatabases() {
+    await Promise.all([...getRegistry()].map(closeProcessState));
+}
+function getProcessState(globalKey) {
+    if (globalKey === undefined)
+        return { opening: undefined, opened: undefined };
+    const key = Symbol.for(`@softure-ai/db/process:${globalKey}`);
+    const existing = host[key];
+    if (existing !== undefined && !(existing instanceof Set))
+        return existing;
+    const created = { opening: undefined, opened: undefined };
+    host[key] = created;
+    return created;
+}
+function getRegistry() {
+    const existing = host[REGISTRY_KEY];
+    if (existing instanceof Set)
+        return existing;
+    const created = new Set();
+    host[REGISTRY_KEY] = created;
+    return created;
+}
+async function closeProcessState(state) {
+    getRegistry().delete(state);
+    if (state.opening === undefined)
+        return;
+    const pending = state.opening;
+    state.opening = undefined;
+    await pending.catch(() => undefined);
+    const current = state.opened;
+    state.opened = undefined;
+    if (current !== undefined)
+        await closeSharedDatabase(current.url);
+}
+/** The handle's drizzle instance, or a new one over the same pool or client when the app passes its schema. */
+async function buildDatabase(handle, schema) {
+    // The handle's own instance is typed with the default schema; without the app's schema the two types agree.
+    if (schema === undefined)
+        return handle.db;
+    if (handle.kind === "postgres") {
+        const { drizzle } = await import("drizzle-orm/node-postgres");
+        return drizzle({ client: handle.pool, schema });
+    }
+    const { drizzle } = await import("drizzle-orm/pglite");
+    return drizzle({ client: handle.client, schema });
+}
+/** A stand-in that forwards every property to the open database, or throws when none is open. */
+function createDatabaseProxy(getDatabase) {
+    return new Proxy({}, {
+        get(_target, property) {
+            const database = getDatabase();
+            if (database === undefined) {
+                // `await db` and `Promise.resolve(db)` look for `then`: a closed database is just not a thenable.
+                if (property === "then")
+                    return undefined;
+                throw new Error(NOT_OPEN_MESSAGE);
+            }
+            const value = Reflect.get(database, property, database);
+            return typeof value === "function" ? value.bind(database) : value;
+        },
+        has(_target, property) {
+            const database = getDatabase();
+            if (database === undefined)
+                throw new Error(NOT_OPEN_MESSAGE);
+            return Reflect.has(database, property);
+        },
+    });
+}
+//# sourceMappingURL=process.js.map

package/dist/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../src/process.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,gBAAgB,GAAG,0FAA0F,CAAC;AACpH,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;AAUpE,MAAM,IAAI,GAAG,UAAkC,CAAC;AAyBhD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAA4B,EAC5B,UAA2C,EAAE;IAE7C,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC;IAC1D,MAAM,KAAK,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAEzC,MAAM,IAAI,GAAG,GAA4B,EAAE;QACzC,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAChC,WAAW,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACzB,KAAK,CAAC,OAAO,GAAG,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBACpD,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;gBAC1B,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC5B,MAAM,KAAK,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC,CAAC;IAEF,KAAK,UAAU,UAAU;QACvB,MAAM,WAAW,GAAG,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAC5D,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;QACrE,KAAK,CAAC,MAAM,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;QAC7E,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,KAAK,GAAG,GAAkB,EAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAE5D,MAAM,YAAY,GAAG,KAAK,EAAK,IAA2C,EAAc,EAAE;QACxF,MAAM,IAAI,EAAE,CAAC;QACb,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,EAAE,CAAC,CAAC;QACxB,CAAC;gBAAS,CAAC;YACT,MAAM,KAAK,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;IAEF,mGAAmG;IACnG,MAAM,EAAE,GAAG,mBAAmB,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,EAAmC,CAAC,CAAC;IAExF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB;IACzC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,EAAE,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,SAAS,eAAe,CAAC,SAA6B;IACpD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC9E,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,SAAS,EAAE,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,YAAY,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC1E,MAAM,OAAO,GAAiB,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACxE,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;IACpB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,WAAW;IAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;IACpC,IAAI,QAAQ,YAAY,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAgB,CAAC;IACxC,IAAI,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC;IAC7B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,KAAmB;IAClD,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;IAC1B,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC;IAC7B,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,OAAO,KAAK,SAAS;QAAE,MAAM,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AACpE,CAAC;AAED,+GAA+G;AAC/G,KAAK,UAAU,aAAa,CAAiC,MAAsB,EAAE,MAA2B;IAC9G,4GAA4G;IAC5G,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,EAAkC,CAAC;IAC3E,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;QAC9D,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACvD,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,iGAAiG;AACjG,SAAS,mBAAmB,CAAiC,WAAgD;IAC3G,OAAO,IAAI,KAAK,CAAC,EAAuB,EAAE;QACxC,GAAG,CAAC,OAAO,EAAE,QAAQ;YACnB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;YAC/B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,kGAAkG;gBAClG,IAAI,QAAQ,KAAK,MAAM;oBAAE,OAAO,SAAS,CAAC;gBAC1C,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;YACpC,CAAC;YACD,MAAM,KAAK,GAAY,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;YACjE,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAE,KAAyC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QACzG,CAAC;QACD,GAAG,CAAC,OAAO,EAAE,QAAQ;YACnB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;YAC/B,IAAI,QAAQ,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;YAC9D,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/raw.d.ts

@@ -0,0 +1,16 @@
+import { type CreateDatabaseOptions, type DatabaseHandle } from "./client.js";
+export interface RawDatabase {
+    readonly kind: DatabaseHandle["kind"];
+    /** Runs `text` with `values` bound to `$1`, `$2`, … and returns the rows. */
+    readonly query: <TRow = Record<string, unknown>>(text: string, values?: readonly unknown[]) => Promise<TRow[]>;
+    /** Closes the handle this database opened; a `pglite://<dir>` database is written back only then. */
+    readonly close: () => Promise<void>;
+}
+/** Runs a parameterized query on the handle's pool (node-postgres) or client (PGlite) and returns its rows. */
+export declare function queryDatabase<TRow = Record<string, unknown>>(handle: DatabaseHandle, text: string, values?: readonly unknown[]): Promise<TRow[]>;
+/**
+ * Opens a new handle on `url` (not the process-wide one) for a script's raw queries. The script closes it at its
+ * end. Throws on an empty URL or an unsupported scheme, as `createDatabase` does.
+ */
+export declare function openRawDatabase(url: string, options?: CreateDatabaseOptions): Promise<RawDatabase>;
+//# sourceMappingURL=raw.d.ts.map

package/dist/raw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["../src/raw.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE9F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/G,qGAAqG;IACrG,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,+GAA+G;AAC/G,wBAAsB,aAAa,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,SAAS,OAAO,EAAO,GAC9B,OAAO,CAAC,IAAI,EAAE,CAAC,CAOjB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,WAAW,CAAC,CAO5G"}

package/dist/raw.js

@@ -0,0 +1,25 @@
+// Raw SQL over whichever driver a handle or URL uses, for operator and report scripts that read with plain SQL
+// instead of drizzle. Values are always passed separately ($1, $2, …), never spliced into the text.
+import { createDatabase } from "./client.js";
+/** Runs a parameterized query on the handle's pool (node-postgres) or client (PGlite) and returns its rows. */
+export async function queryDatabase(handle, text, values = []) {
+    if (handle.kind === "postgres") {
+        const result = await handle.pool.query(text, [...values]);
+        return result.rows;
+    }
+    const result = await handle.client.query(text, [...values]);
+    return result.rows;
+}
+/**
+ * Opens a new handle on `url` (not the process-wide one) for a script's raw queries. The script closes it at its
+ * end. Throws on an empty URL or an unsupported scheme, as `createDatabase` does.
+ */
+export async function openRawDatabase(url, options = {}) {
+    const handle = await createDatabase(url, options);
+    return {
+        kind: handle.kind,
+        query: (text, values) => queryDatabase(handle, text, values),
+        close: handle.close,
+    };
+}
+//# sourceMappingURL=raw.js.map

package/dist/raw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw.js","sourceRoot":"","sources":["../src/raw.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,oGAAoG;AACpG,OAAO,EAAE,cAAc,EAAmD,MAAM,aAAa,CAAC;AAU9F,+GAA+G;AAC/G,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAsB,EACtB,IAAY,EACZ,SAA6B,EAAE;IAE/B,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;QAC1D,OAAO,MAAM,CAAC,IAAc,CAAC;IAC/B,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAO,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAClE,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW,EAAE,UAAiC,EAAE;IACpF,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAClD,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC;QAC5D,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC;AACJ,CAAC"}

package/dist/shared.d.ts

@@ -4,6 +4,8 @@ import { type CreateDatabaseOptions, type DatabaseHandle } from "./client.js";
  * A failed open is not kept, so the next call tries again.
  */
 export declare function getSharedDatabase(url: string, options?: CreateDatabaseOptions): Promise<DatabaseHandle>;
+/** Closes and forgets the shared handle for `url`, if one is open. For a script's end. */
+export declare function closeSharedDatabase(url: string): Promise<void>;
 /** Closes and forgets every shared handle. For tests and graceful shutdown. */
 export declare function closeSharedDatabases(): Promise<void>;
 //# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ9F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,+EAA+E;AAC/E,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1D"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ9F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,0FAA0F;AAC1F,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpE;AAED,+EAA+E;AAC/E,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1D"}

package/dist/shared.js

@@ -19,6 +19,15 @@ export function getSharedDatabase(url, options = {}) {
     }
     return handle;
 }
+/** Closes and forgets the shared handle for `url`, if one is open. For a script's end. */
+export async function closeSharedDatabase(url) {
+    const handle = host[HANDLES_KEY]?.get(url);
+    if (handle === undefined)
+        return;
+    host[HANDLES_KEY]?.delete(url);
+    const opened = await handle.catch(() => undefined);
+    await opened?.close();
+}
 /** Closes and forgets every shared handle. For tests and graceful shutdown. */
 export async function closeSharedDatabases() {
     const handles = host[HANDLES_KEY];

package/dist/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,oGAAoG;AACpG,8FAA8F;AAC9F,sFAAsF;AACtF,OAAO,EAAE,cAAc,EAAmD,MAAM,aAAa,CAAC;AAE9F,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAIhE,MAAM,IAAI,GAAG,UAAmC,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,UAAiC,EAAE;IAChF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,GAAG,EAAmC,CAAC,CAAC;IACnF,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACzB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAClC,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAChH,CAAC"}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,oGAAoG;AACpG,8FAA8F;AAC9F,sFAAsF;AACtF,OAAO,EAAE,cAAc,EAAmD,MAAM,aAAa,CAAC;AAE9F,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAIhE,MAAM,IAAI,GAAG,UAAmC,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,UAAiC,EAAE;IAChF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,GAAG,EAAmC,CAAC,CAAC;IACnF,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACzB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAW;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO;IACjC,IAAI,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC;AACxB,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAClC,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAChH,CAAC"}

package/dist/testing.d.ts

@@ -2,6 +2,7 @@ import { PGlite } from "@electric-sql/pglite";
 import type { AnySoftureModule } from "@softure-ai/core";
 import { type PgliteClientDatabase } from "./client.js";
 import { type AppMigrations } from "./migrations/migrator.js";
+export { DEFAULT_DATABASE_OPENERS, expectEntriesOpenDatabase, findEntriesReachingDatabase, type EntryGuardOptions, type EntryReach, } from "./entry-guard.js";
 export interface TestDatabase {
     readonly db: PgliteClientDatabase;
     readonly client: PGlite;

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAkC,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG9F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,oBAAoB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;CAC9B;AAMD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,SAAS,gBAAgB,EAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,YAAY,CAAC,CAIlJ"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAkC,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG9F,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,KAAK,iBAAiB,EACtB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,oBAAoB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;CAC9B;AAMD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,SAAS,gBAAgB,EAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,YAAY,CAAC,CAIlJ"}

package/dist/testing.js

@@ -8,6 +8,7 @@ import { PGlite } from "@electric-sql/pglite";
 import { createPgliteHandle } from "./client.js";
 import { migrate } from "./migrations/migrator.js";
 import { describeProblem } from "./migrations/problems.js";
+export { DEFAULT_DATABASE_OPENERS, expectEntriesOpenDatabase, findEntriesReachingDatabase, } from "./entry-guard.js";
 const templates = new Map();
 const hookIds = new WeakMap();
 let nextHookId = 1;

package/dist/testing.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/db",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "SOFTURE AI database layer: pg/PGlite client, per-module migrator with plan and adopt, PGlite test databases.",
   "license": "MIT",
   "type": "module",
@@ -54,6 +54,7 @@
     "@electric-sql/pglite": "^0.5.0",
     "@types/pg": "^8.11.0",
     "drizzle-orm": "^0.45.2",
+    "esbuild": ">=0.25.0",
     "pg": "^8.11.0"
   },
   "peerDependenciesMeta": {
@@ -63,6 +64,9 @@
     "@types/pg": {
       "optional": true
     },
+    "esbuild": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     }

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/entry-guard.ts

@@ -0,0 +1,111 @@
+// The entry-point guard for an app on `createProcessDatabase`: `db` is synchronous but opening is not, so every
+// process entry (the server's instrumentation, an MCP stdio server, each script) must open the database before its
+// first query. esbuild resolves each entry's import graph (path aliases and re-exports included); an entry that
+// reaches the app's client module must call an opener in its own source. esbuild is an optional peer, loaded here.
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Metafile } from "esbuild";
+
+/** A call to `withDatabase(` or `open(` (`processDb.open(` too): what `createProcessDatabase` gives an entry. */
+export const DEFAULT_DATABASE_OPENERS: readonly RegExp[] = [/\bwithDatabase\s*\(/, /\bopen\s*\(/];
+
+export interface EntryGuardOptions {
+  /** The process entry points, as paths (relative to `workingDir`) or absolute paths. */
+  readonly entries: readonly string[];
+  /** The app's module that calls `createProcessDatabase` (e.g. `src/db/index.ts`). */
+  readonly clientModule: string;
+  /** Patterns an entry's own source must match to count as opening the database. Default: `DEFAULT_DATABASE_OPENERS`. */
+  readonly opens?: readonly RegExp[];
+  /** The directory paths and the app's tsconfig resolve from. Default: `process.cwd()`. */
+  readonly workingDir?: string;
+  /** Extra import paths esbuild leaves out of the graph (packages are always left out). */
+  readonly external?: readonly string[];
+}
+
+export interface EntryReach {
+  /** The entry as given in `entries`. */
+  readonly entry: string;
+  /** Whether the entry's own source opens the database. */
+  readonly opens: boolean;
+}
+
+const ASSET_EXTENSIONS = [".css", ".scss", ".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".woff", ".woff2"];
+
+/**
+ * The entries whose import graph (static and dynamic imports) reaches `clientModule`, in the order given, each
+ * with whether its own source opens the database. Entries that never reach it are left out.
+ */
+export async function findEntriesReachingDatabase(options: EntryGuardOptions): Promise<EntryReach[]> {
+  const workingDir = options.workingDir ?? process.cwd();
+  const clientPath = resolve(workingDir, options.clientModule);
+  if (!existsSync(clientPath)) {
+    throw new Error(`findEntriesReachingDatabase: the client module does not exist: ${options.clientModule}`);
+  }
+  const metafile = await buildMetafile(options.entries.map((entry) => resolve(workingDir, entry)), workingDir, options.external ?? []);
+  const opens = options.opens ?? DEFAULT_DATABASE_OPENERS;
+
+  return options.entries.flatMap((entry) => {
+    const entryPath = resolve(workingDir, entry);
+    if (!reaches(metafile, workingDir, entryPath, clientPath)) return [];
+    const source = readFileSync(entryPath, "utf8");
+    return [{ entry, opens: opens.some((pattern) => pattern.test(source)) }];
+  });
+}
+
+/** Throws, naming each one, when an entry reaches `clientModule` without opening the database. */
+export async function expectEntriesOpenDatabase(options: EntryGuardOptions): Promise<void> {
+  const missing = (await findEntriesReachingDatabase(options)).filter((reach) => !reach.opens);
+  if (missing.length === 0) return;
+  throw new Error(
+    `These entries reach the database client without opening it (call withDatabase() or open() at the entry):\n` +
+      missing.map((reach) => `  - ${reach.entry}`).join("\n"),
+  );
+}
+
+async function buildMetafile(entryPoints: readonly string[], workingDir: string, external: readonly string[]): Promise<Metafile> {
+  const { build } = await loadEsbuild();
+  const result = await build({
+    entryPoints: [...entryPoints],
+    absWorkingDir: workingDir,
+    // Never written (`write: false`); esbuild needs an output directory for several entries.
+    outdir: resolve(workingDir, ".entry-guard"),
+    bundle: true,
+    write: false,
+    metafile: true,
+    platform: "node",
+    format: "esm",
+    packages: "external",
+    external: [...external],
+    loader: Object.fromEntries(ASSET_EXTENSIONS.map((extension) => [extension, "empty" as const])),
+    logLevel: "silent",
+  }).catch((error: unknown) => {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`findEntriesReachingDatabase: esbuild could not follow the entries' imports: ${reason}`, { cause: error });
+  });
+  return result.metafile;
+}
+
+async function loadEsbuild(): Promise<typeof import("esbuild")> {
+  try {
+    return await import("esbuild");
+  } catch (error) {
+    throw new Error("findEntriesReachingDatabase: needs the \"esbuild\" package; run `npm install --save-dev esbuild`", { cause: error });
+  }
+}
+
+function reaches(metafile: Metafile, workingDir: string, entryPath: string, clientPath: string): boolean {
+  const keyByPath = new Map(Object.keys(metafile.inputs).map((key) => [resolve(workingDir, key), key]));
+  const start = keyByPath.get(entryPath);
+  if (start === undefined) return false;
+  const seen = new Set<string>([start]);
+  const queue = [start];
+  for (let key = queue.shift(); key !== undefined; key = queue.shift()) {
+    if (resolve(workingDir, key) === clientPath) return true;
+    for (const imported of metafile.inputs[key]?.imports ?? []) {
+      if (imported.external === true || seen.has(imported.path)) continue;
+      seen.add(imported.path);
+      queue.push(imported.path);
+    }
+  }
+  return false;
+}

package/src/index.ts

@@ -13,7 +13,10 @@ export {
   type PostgresDatabase,
   type Queryable,
 } from "./client.js";
-export { closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { closeSharedDatabase, closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { closeProcessDatabases, createProcessDatabase, type ProcessDatabase, type ProcessDatabaseOptions } from "./process.js";
+export { openRawDatabase, queryDatabase, type RawDatabase } from "./raw.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 {
@@ -35,6 +38,7 @@ export {
   type MigrationReport,
   type MigrationStep,
 } from "./migrations/migrator.js";
+export { drizzleAppMigrations } from "./migrations/drizzle.js";
 export { adoptModule, type AdoptionReport, type AdoptOptions } from "./migrations/adopt.js";
 export { exportMigrations } from "./migrations/export.js";
 export {

package/src/migrations/drizzle.ts

@@ -0,0 +1,22 @@
+// The app's own drizzle-kit migrations as an app migration hook: drizzle's migrator for the handle's driver,
+// loaded only when the hook runs, so an app ships just its own driver.
+import { fileURLToPath } from "node:url";
+import type { AppMigrationHook } from "./migrator.js";
+
+/**
+ * A hook for `app.before` (or `app.after`) that applies the drizzle-kit folder (`meta/_journal.json` and its SQL
+ * files) with drizzle's migrator. Drizzle skips what its ledger (`drizzle.__drizzle_migrations`) already holds, so
+ * the hook is safe on every `migrate` run. `folder` is a path (relative to the working directory) or a file URL.
+ */
+export function drizzleAppMigrations(folder: string | URL): AppMigrationHook {
+  const migrationsFolder = typeof folder === "string" ? folder : fileURLToPath(folder);
+  return async (handle) => {
+    if (handle.kind === "postgres") {
+      const { migrate } = await import("drizzle-orm/node-postgres/migrator");
+      await migrate(handle.db, { migrationsFolder });
+      return;
+    }
+    const { migrate } = await import("drizzle-orm/pglite/migrator");
+    await migrate(handle.db, { migrationsFolder });
+  };
+}

package/src/process.ts

@@ -0,0 +1,160 @@
+// A process-wide database for an app whose code imports one module-level `db` (drizzle queries everywhere)
+// instead of awaiting a handle in every function. `db` is a synchronous stand-in for the shared handle's
+// drizzle instance: each entry point (the server's startup, a script's main) opens it first, and a query
+// before that throws instead of silently opening a second pool.
+import type { Database, DatabaseHandle, DatabaseSchema, CreateDatabaseOptions } from "./client.js";
+import { closeSharedDatabase, getSharedDatabase } from "./shared.js";
+
+const NOT_OPEN_MESSAGE = "Database is not open: call open() or withDatabase() at the process entry before querying";
+const REGISTRY_KEY = Symbol.for("@softure-ai/db/process-databases");
+
+/** What one process database holds between `open()` and `close()`; on `globalThis` when it has a `globalKey`. */
+interface ProcessState {
+  opening: Promise<DatabaseHandle> | undefined;
+  opened: { readonly url: string; readonly db: Database<DatabaseSchema> } | undefined;
+}
+
+type StateHost = Record<symbol, ProcessState | Set<ProcessState> | undefined>;
+
+const host = globalThis as unknown as StateHost;
+
+export interface ProcessDatabaseOptions<TSchema extends DatabaseSchema> extends CreateDatabaseOptions {
+  /** The app's drizzle schema: `db` is built with it, so `db.query.<table>` is typed and works. */
+  readonly schema?: TSchema;
+  /**
+   * Keeps the open database on `globalThis` under this key, so a module that `next dev` re-evaluates (HMR) finds the
+   * database its previous evaluation opened instead of refusing queries. One key per database in the process. The
+   * open `db` keeps the schema it was opened with; a changed schema takes effect after `close()` or a restart.
+   */
+  readonly globalKey?: string;
+}
+
+export interface ProcessDatabase<TSchema extends DatabaseSchema = DatabaseSchema> {
+  /** The open database. Usable from module scope; a query before `open()` resolves throws "Database is not open". */
+  readonly db: Database<TSchema>;
+  /** Opens the process-wide handle for the URL (`getSharedDatabase`), once; later calls return the same handle. */
+  readonly open: () => Promise<DatabaseHandle>;
+  /** Closes the handle and forgets it, so `db` refuses queries again. Does nothing when not open. */
+  readonly close: () => Promise<void>;
+  /** For a script: opens, runs `main` with `db`, and closes whether `main` resolves or throws. */
+  readonly withDatabase: <T>(main: (db: Database<TSchema>) => Promise<T>) => Promise<T>;
+  readonly isOpen: () => boolean;
+}
+
+/**
+ * A module-level database for the process. `url` may be a function, read on `open()`, so a script can load its
+ * environment after importing the module that creates it. The handle is the one `getSharedDatabase(url)` gives the
+ * modules, so the app and the modules share one pool (db README §3, "One handle per process").
+ */
+export function createProcessDatabase<TSchema extends DatabaseSchema = DatabaseSchema>(
+  url: string | (() => string),
+  options: ProcessDatabaseOptions<TSchema> = {},
+): ProcessDatabase<TSchema> {
+  const { schema, globalKey, ...databaseOptions } = options;
+  const state = getProcessState(globalKey);
+
+  const open = (): Promise<DatabaseHandle> => {
+    if (state.opening === undefined) {
+      getRegistry().add(state);
+      state.opening = openHandle().catch((error: unknown) => {
+        state.opening = undefined;
+        getRegistry().delete(state);
+        throw error;
+      });
+    }
+    return state.opening;
+  };
+
+  async function openHandle(): Promise<DatabaseHandle> {
+    const resolvedUrl = typeof url === "function" ? url() : url;
+    const handle = await getSharedDatabase(resolvedUrl, databaseOptions);
+    state.opened = { url: resolvedUrl, db: await buildDatabase(handle, schema) };
+    return handle;
+  }
+
+  const close = (): Promise<void> => closeProcessState(state);
+
+  const withDatabase = async <T>(main: (db: Database<TSchema>) => Promise<T>): Promise<T> => {
+    await open();
+    try {
+      return await main(db);
+    } finally {
+      await close();
+    }
+  };
+
+  // The state holds whichever schema opened it; this instance's callers see it typed with their own.
+  const db = createDatabaseProxy(() => state.opened?.db as Database<TSchema> | undefined);
+
+  return { db, open, close, withDatabase, isOpen: () => state.opened !== undefined };
+}
+
+/**
+ * Closes every process database this process opened (with or without `globalKey`), so each `db` refuses queries
+ * until its `open()`. For tests' `afterEach`; a server's shutdown closes its own.
+ */
+export async function closeProcessDatabases(): Promise<void> {
+  await Promise.all([...getRegistry()].map(closeProcessState));
+}
+
+function getProcessState(globalKey: string | undefined): ProcessState {
+  if (globalKey === undefined) return { opening: undefined, opened: undefined };
+  const key = Symbol.for(`@softure-ai/db/process:${globalKey}`);
+  const existing = host[key];
+  if (existing !== undefined && !(existing instanceof Set)) return existing;
+  const created: ProcessState = { opening: undefined, opened: undefined };
+  host[key] = created;
+  return created;
+}
+
+function getRegistry(): Set<ProcessState> {
+  const existing = host[REGISTRY_KEY];
+  if (existing instanceof Set) return existing;
+  const created = new Set<ProcessState>();
+  host[REGISTRY_KEY] = created;
+  return created;
+}
+
+async function closeProcessState(state: ProcessState): Promise<void> {
+  getRegistry().delete(state);
+  if (state.opening === undefined) return;
+  const pending = state.opening;
+  state.opening = undefined;
+  await pending.catch(() => undefined);
+  const current = state.opened;
+  state.opened = undefined;
+  if (current !== undefined) await closeSharedDatabase(current.url);
+}
+
+/** The handle's drizzle instance, or a new one over the same pool or client when the app passes its schema. */
+async function buildDatabase<TSchema extends DatabaseSchema>(handle: DatabaseHandle, schema: TSchema | undefined): Promise<Database<TSchema>> {
+  // The handle's own instance is typed with the default schema; without the app's schema the two types agree.
+  if (schema === undefined) return handle.db as unknown as Database<TSchema>;
+  if (handle.kind === "postgres") {
+    const { drizzle } = await import("drizzle-orm/node-postgres");
+    return drizzle({ client: handle.pool, schema });
+  }
+  const { drizzle } = await import("drizzle-orm/pglite");
+  return drizzle({ client: handle.client, schema });
+}
+
+/** A stand-in that forwards every property to the open database, or throws when none is open. */
+function createDatabaseProxy<TSchema extends DatabaseSchema>(getDatabase: () => Database<TSchema> | undefined): Database<TSchema> {
+  return new Proxy({} as Database<TSchema>, {
+    get(_target, property) {
+      const database = getDatabase();
+      if (database === undefined) {
+        // `await db` and `Promise.resolve(db)` look for `then`: a closed database is just not a thenable.
+        if (property === "then") return undefined;
+        throw new Error(NOT_OPEN_MESSAGE);
+      }
+      const value: unknown = Reflect.get(database, property, database);
+      return typeof value === "function" ? (value as (...args: unknown[]) => unknown).bind(database) : value;
+    },
+    has(_target, property) {
+      const database = getDatabase();
+      if (database === undefined) throw new Error(NOT_OPEN_MESSAGE);
+      return Reflect.has(database, property);
+    },
+  });
+}

package/src/raw.ts

@@ -0,0 +1,38 @@
+// Raw SQL over whichever driver a handle or URL uses, for operator and report scripts that read with plain SQL
+// instead of drizzle. Values are always passed separately ($1, $2, …), never spliced into the text.
+import { createDatabase, type CreateDatabaseOptions, type DatabaseHandle } from "./client.js";
+
+export interface RawDatabase {
+  readonly kind: DatabaseHandle["kind"];
+  /** Runs `text` with `values` bound to `$1`, `$2`, … and returns the rows. */
+  readonly query: <TRow = Record<string, unknown>>(text: string, values?: readonly unknown[]) => Promise<TRow[]>;
+  /** Closes the handle this database opened; a `pglite://<dir>` database is written back only then. */
+  readonly close: () => Promise<void>;
+}
+
+/** Runs a parameterized query on the handle's pool (node-postgres) or client (PGlite) and returns its rows. */
+export async function queryDatabase<TRow = Record<string, unknown>>(
+  handle: DatabaseHandle,
+  text: string,
+  values: readonly unknown[] = [],
+): Promise<TRow[]> {
+  if (handle.kind === "postgres") {
+    const result = await handle.pool.query(text, [...values]);
+    return result.rows as TRow[];
+  }
+  const result = await handle.client.query<TRow>(text, [...values]);
+  return result.rows;
+}
+
+/**
+ * Opens a new handle on `url` (not the process-wide one) for a script's raw queries. The script closes it at its
+ * end. Throws on an empty URL or an unsupported scheme, as `createDatabase` does.
+ */
+export async function openRawDatabase(url: string, options: CreateDatabaseOptions = {}): Promise<RawDatabase> {
+  const handle = await createDatabase(url, options);
+  return {
+    kind: handle.kind,
+    query: (text, values) => queryDatabase(handle, text, values),
+    close: handle.close,
+  };
+}

package/src/shared.ts

@@ -25,6 +25,15 @@ export function getSharedDatabase(url: string, options: CreateDatabaseOptions =
   return handle;
 }
 
+/** Closes and forgets the shared handle for `url`, if one is open. For a script's end. */
+export async function closeSharedDatabase(url: string): Promise<void> {
+  const handle = host[HANDLES_KEY]?.get(url);
+  if (handle === undefined) return;
+  host[HANDLES_KEY]?.delete(url);
+  const opened = await handle.catch(() => undefined);
+  await opened?.close();
+}
+
 /** Closes and forgets every shared handle. For tests and graceful shutdown. */
 export async function closeSharedDatabases(): Promise<void> {
   const handles = host[HANDLES_KEY];

package/src/testing.ts

@@ -10,6 +10,14 @@ import { createPgliteHandle, type PgliteClientDatabase } from "./client.js";
 import { migrate, type AppMigrationHook, type AppMigrations } from "./migrations/migrator.js";
 import { describeProblem } from "./migrations/problems.js";
 
+export {
+  DEFAULT_DATABASE_OPENERS,
+  expectEntriesOpenDatabase,
+  findEntriesReachingDatabase,
+  type EntryGuardOptions,
+  type EntryReach,
+} from "./entry-guard.js";
+
 export interface TestDatabase {
   readonly db: PgliteClientDatabase;
   readonly client: PGlite;