@softure-ai/db 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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,

package/README.md

@@ -8,8 +8,9 @@ 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, the `softure migrate` command, a module-level process database
-(`createProcessDatabase`) and helpers that read the Postgres error behind a failed query
-(`findDriverError`, `isConstraintViolation`).
+(`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
 
@@ -169,6 +170,57 @@ 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
@@ -238,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
@@ -276,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/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":"AAAA,gHAAgH;AAChH,mHAAmH;AACnH,gHAAgH;AAChH,mHAAmH;AACnH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,iHAAiH;AACjH,MAAM,CAAC,MAAM,wBAAwB,GAAsB,CAAC,qBAAqB,EAAE,aAAa,CAAC,CAAC;AAsBlG,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AAEhH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,OAA0B;IAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACvD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7D,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,kEAAkE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5G,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IACrI,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,wBAAwB,CAAC;IAExD,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QACvC,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC;YAAE,OAAO,EAAE,CAAC;QACrE,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC/C,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,kGAAkG;AAClG,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,OAA0B;IACxE,MAAM,OAAO,GAAG,CAAC,MAAM,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7F,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACjC,MAAM,IAAI,KAAK,CACb,4GAA4G;QAC1G,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAC1D,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,WAA8B,EAAE,UAAkB,EAAE,QAA2B;IAC1G,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC;QACzB,WAAW,EAAE,CAAC,GAAG,WAAW,CAAC;QAC7B,aAAa,EAAE,UAAU;QACzB,yFAAyF;QACzF,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,cAAc,CAAC;QAC3C,MAAM,EAAE,IAAI;QACZ,KAAK,EAAE,KAAK;QACZ,QAAQ,EAAE,IAAI;QACd,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,KAAK;QACb,QAAQ,EAAE,UAAU;QACpB,QAAQ,EAAE,CAAC,GAAG,QAAQ,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,OAAgB,CAAC,CAAC,CAAC;QAC9F,QAAQ,EAAE,QAAQ;KACnB,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC1B,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,+EAA+E,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7H,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,QAAQ,CAAC;AACzB,CAAC;AAED,KAAK,UAAU,WAAW;IACxB,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,kGAAkG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACxI,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,QAAkB,EAAE,UAAkB,EAAE,SAAiB,EAAE,UAAkB;IAC5F,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACtG,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC;IACtB,KAAK,IAAI,GAAG,GAAG,KAAK,CAAC,KAAK,EAAE,EAAE,GAAG,KAAK,SAAS,EAAE,GAAG,GAAG,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QACrE,IAAI,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,KAAK,UAAU;YAAE,OAAO,IAAI,CAAC;QACzD,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,IAAI,EAAE,EAAE,CAAC;YAC3D,IAAI,QAAQ,CAAC,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,SAAS;YACpE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -1,11 +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 { closeSharedDatabase, closeSharedDatabases, getSharedDatabase } from "./shared.js";
-export { createProcessDatabase, type ProcessDatabase, type ProcessDatabaseOptions } from "./process.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,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACxG,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,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

@@ -2,12 +2,14 @@
 // (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 { closeSharedDatabase, closeSharedDatabases, getSharedDatabase } from "./shared.js";
-export { createProcessDatabase } from "./process.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,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,qBAAqB,EAAqD,MAAM,cAAc,CAAC;AACxG,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,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

@@ -2,6 +2,12 @@ import type { Database, DatabaseHandle, DatabaseSchema, CreateDatabaseOptions }
 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". */
@@ -20,4 +26,9 @@ export interface ProcessDatabase<TSchema extends DatabaseSchema = DatabaseSchema
  * 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

@@ -1 +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;AAKnG,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,cAAc,CAAE,SAAQ,qBAAqB;IACnG,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;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,CA0C1B"}
+{"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

@@ -1,38 +1,33 @@
 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, ...databaseOptions } = options;
-    let opening;
-    let opened;
+    const { schema, globalKey, ...databaseOptions } = options;
+    const state = getProcessState(globalKey);
     const open = () => {
-        opening ??= openHandle().catch((error) => {
-            opening = undefined;
-            throw error;
-        });
-        return opening;
+        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);
-        opened = { url: resolvedUrl, db: await buildDatabase(handle, schema) };
+        state.opened = { url: resolvedUrl, db: await buildDatabase(handle, schema) };
         return handle;
     }
-    const close = async () => {
-        if (opening === undefined)
-            return;
-        const pending = opening;
-        opening = undefined;
-        await pending.catch(() => undefined);
-        const current = opened;
-        opened = undefined;
-        if (current !== undefined)
-            await closeSharedDatabase(current.url);
-    };
+    const close = () => closeProcessState(state);
     const withDatabase = async (main) => {
         await open();
         try {
@@ -42,8 +37,47 @@ export function createProcessDatabase(url, options = {}) {
             await close();
         }
     };
-    const db = createDatabaseProxy(() => opened?.db);
-    return { db, open, close, withDatabase, isOpen: () => opened !== undefined };
+    // 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) {

package/dist/process.js.map

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

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/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.7",
+  "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/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

@@ -14,7 +14,8 @@ export {
   type Queryable,
 } from "./client.js";
 export { closeSharedDatabase, closeSharedDatabases, getSharedDatabase } from "./shared.js";
-export { createProcessDatabase, type ProcessDatabase, type ProcessDatabaseOptions } from "./process.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";
@@ -37,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

@@ -6,10 +6,27 @@ import type { Database, DatabaseHandle, DatabaseSchema, CreateDatabaseOptions }
 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> {
@@ -33,34 +50,29 @@ export function createProcessDatabase<TSchema extends DatabaseSchema = DatabaseS
   url: string | (() => string),
   options: ProcessDatabaseOptions<TSchema> = {},
 ): ProcessDatabase<TSchema> {
-  const { schema, ...databaseOptions } = options;
-  let opening: Promise<DatabaseHandle> | undefined;
-  let opened: { readonly url: string; readonly db: Database<TSchema> } | undefined;
+  const { schema, globalKey, ...databaseOptions } = options;
+  const state = getProcessState(globalKey);
 
   const open = (): Promise<DatabaseHandle> => {
-    opening ??= openHandle().catch((error: unknown) => {
-      opening = undefined;
-      throw error;
-    });
-    return opening;
+    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);
-    opened = { url: resolvedUrl, db: await buildDatabase(handle, schema) };
+    state.opened = { url: resolvedUrl, db: await buildDatabase(handle, schema) };
     return handle;
   }
 
-  const close = async (): Promise<void> => {
-    if (opening === undefined) return;
-    const pending = opening;
-    opening = undefined;
-    await pending.catch(() => undefined);
-    const current = opened;
-    opened = undefined;
-    if (current !== undefined) await closeSharedDatabase(current.url);
-  };
+  const close = (): Promise<void> => closeProcessState(state);
 
   const withDatabase = async <T>(main: (db: Database<TSchema>) => Promise<T>): Promise<T> => {
     await open();
@@ -71,9 +83,47 @@ export function createProcessDatabase<TSchema extends DatabaseSchema = DatabaseS
     }
   };
 
-  const db = createDatabaseProxy(() => opened?.db);
+  // 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;
+}
 
-  return { db, open, close, withDatabase, isOpen: () => opened !== undefined };
+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. */

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/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;