@softure-ai/db 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.13
+
+- `@softure-ai/db/testing/global-setup`, a Vitest `globalSetup` module: each module set is migrated once per run
+  instead of once per test file (#641). The template is written to a folder the setup creates and removes
+  (`SOFTURE_DB_TEST_TEMPLATES`), named by a hash of the module migration files, the drizzle folders' files and the
+  baseline; every other file and worker loads it from disk. An app hook other than `drizzleAppMigrations` needs the
+  new `templateKey` option to be shared; without it, its template stays per file as before.
+- `createTestDatabase(modules, { reuse: true })`: `close()` returns the database to a pool and the next call gets it
+  back reset to the template (rows, seed rows and ledgers, sequences, session state) in milliseconds instead of a new
+  copy (~0.5 s). A database whose schema a test changed is replaced by a fresh copy.
+- Without the setup and without `reuse`, nothing changes.
+
 ## 0.1.12
 
 - `drizzleAppMigrations(folder, { migrationsTable, migrationsSchema })` names the drizzle ledger the folder uses

package/README.md

@@ -427,7 +427,7 @@ For fresh databases of an app that adopted a module, declare a baseline (section
 
 **Tests:** `createTestDatabase(modules)` from `@softure-ai/db/testing` returns `{ db, client, close }`:
 an in-memory PGlite with the ledger and the listed modules migrated (list the module and the
-modules it depends on). Each module set is migrated once per test worker and copied per call; a
+modules it depends on). Each module set is migrated once into a template and copied per call; a
 broken migration throws naming the file. An app with its own migrations passes the same hooks,
 `createTestDatabase(modules, { app: appMigrations })`, so module tables can reference app tables; the
 template is cached per hook object, so import the shared object rather than writing hooks inline.
@@ -439,6 +439,53 @@ const database = await createTestDatabase([notes()]);
 afterEach(() => database.close());
 ```
 
+**A template per run, not per file.** The template cache is module state, and Vitest isolates modules
+per test file, so without more each test file migrates again (seconds per file). Add the global setup,
+and every module set is migrated once per run and loaded from disk by every other file and worker:
+
+```ts
+// vitest.config.ts
+export default defineConfig({ test: { globalSetup: ["@softure-ai/db/testing/global-setup"] } });
+```
+
+- The setup creates a temporary folder, names it in `SOFTURE_DB_TEST_TEMPLATES` for the workers, and
+  removes it when the run ends. An app that sets the variable itself keeps its folder; that folder must
+  not outlive a dependency upgrade, since the file names do not cover the PGlite or package version.
+- A template on disk is named by a hash of what it is built from: the module ids and every file in their
+  migration folders, each `drizzleAppMigrations` folder's files and ledger, `templateKey`, the baseline.
+  Editing a migration gives a new template.
+- An app hook other than `drizzleAppMigrations` is a function nothing can identify in another process: give
+  it `templateKey` (change the key when its migrations change), or its template stays per file:
+  `createTestDatabase(modules, { app: appMigrations, templateKey: "app-v12" })`.
+- Two workers that need the same template at once may both build it; the file is written under a
+  temporary name and renamed, so a reader sees the whole file or none.
+
+**Reuse: a reset instead of a new copy.** A copy of the template costs ~0.4-0.6 s per call; most tests
+only need empty tables. With `reuse: true`, `close()` returns the database to a pool, and the next call
+gets it back reset to the template (a few milliseconds):
+
+```ts
+let database: TestDatabase;
+beforeEach(async () => {
+  database = await createTestDatabase([notes()], { reuse: true });
+});
+afterEach(() => database.close());
+afterAll(() => closeReusedTestDatabases());
+```
+
+- Reset: session state discarded (`DISCARD ALL`: settings, temporary tables, prepared statements,
+  listeners, advisory locks), every table emptied and the template's rows copied back (seed rows and the
+  migration ledgers included), sequences set to the template's values, populated materialized views
+  refreshed.
+- A test that changed the schema (a table, column, index, constraint, function, trigger or enum value)
+  or left a transaction open hands back a database that cannot be reset; the next call closes it and
+  gets a fresh copy. Two databases open at the same time are never the same instance.
+- The pool is module state: one per test file under Vitest's default isolation.
+  `closeReusedTestDatabases()` in `afterAll` closes its idle databases.
+- Seed rows, identity values and sequences come back exactly as a fresh copy has them. A test that
+  counts on an exact id after inserts should read it, not assume it: PGlite's sequences resume past
+  their logged values in every copy, with or without reuse.
+
 ## 6. Environment variables
 
 None read by the package. The app passes `DATABASE_URL` (or any variable) through

package/dist/migrations/drizzle.d.ts

@@ -15,4 +15,6 @@ export interface DrizzleAppMigrationsOptions {
 export declare function drizzleAppMigrations(folder: string | URL, options?: DrizzleAppMigrationsOptions): AppMigrationHook;
 /** The ledger (`schema.table`) a `drizzleAppMigrations` hook writes to; `undefined` for any other hook. */
 export declare function getDrizzleLedger(hook: AppMigrationHook): string | undefined;
+/** The absolute folder a `drizzleAppMigrations` hook applies; `undefined` for any other hook. */
+export declare function getDrizzleFolder(hook: AppMigrationHook): string | undefined;
 //# sourceMappingURL=drizzle.d.ts.map

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

@@ -1 +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,MAAM,WAAW,2BAA2B;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,oDAAoD;IACpD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAQD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,GAAE,2BAAgC,GAAG,gBAAgB,CAkBtH;AAED,2GAA2G;AAC3G,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAE3E"}
+{"version":3,"file":"drizzle.d.ts","sourceRoot":"","sources":["../../src/migrations/drizzle.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,2BAA2B;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,oDAAoD;IACpD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAcD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,GAAE,2BAAgC,GAAG,gBAAgB,CAkBtH;AAED,2GAA2G;AAC3G,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAE3E;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAE3E"}

package/dist/migrations/drizzle.js

@@ -1,10 +1,10 @@
 // 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 { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const DEFAULT_TABLE = "__drizzle_migrations";
 const DEFAULT_SCHEMA = "drizzle";
-// The ledger each hook writes to, so `migrate` can refuse a `before` and an `after` sharing one (issue #534).
-const ledgers = new WeakMap();
+const sources = new WeakMap();
 /**
  * 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` unless `options`
@@ -28,11 +28,15 @@ export function drizzleAppMigrations(folder, options = {}) {
         const { migrate } = await import("drizzle-orm/pglite/migrator");
         await migrate(handle.db, config);
     };
-    ledgers.set(hook, `${config.migrationsSchema}.${config.migrationsTable}`);
+    sources.set(hook, { ledger: `${config.migrationsSchema}.${config.migrationsTable}`, folder: resolve(migrationsFolder) });
     return hook;
 }
 /** The ledger (`schema.table`) a `drizzleAppMigrations` hook writes to; `undefined` for any other hook. */
 export function getDrizzleLedger(hook) {
-    return ledgers.get(hook);
+    return sources.get(hook)?.ledger;
+}
+/** The absolute folder a `drizzleAppMigrations` hook applies; `undefined` for any other hook. */
+export function getDrizzleFolder(hook) {
+    return sources.get(hook)?.folder;
 }
 //# sourceMappingURL=drizzle.js.map

package/dist/migrations/drizzle.js.map

@@ -1 +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;AAUzC,MAAM,aAAa,GAAG,sBAAsB,CAAC;AAC7C,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC,8GAA8G;AAC9G,MAAM,OAAO,GAAG,IAAI,OAAO,EAA4B,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAoB,EAAE,UAAuC,EAAE;IAClG,MAAM,gBAAgB,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACrF,MAAM,MAAM,GAAG;QACb,gBAAgB;QAChB,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,aAAa;QACzD,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,cAAc;KAC7D,CAAC;IACF,MAAM,IAAI,GAAqB,KAAK,EAAE,MAAM,EAAE,EAAE;QAC9C,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,MAAM,CAAC,CAAC;YACjC,OAAO;QACT,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC;QAChE,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,gBAAgB,CAAC,IAAsB;IACrD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"drizzle.js","sourceRoot":"","sources":["../../src/migrations/drizzle.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAC7G,uEAAuE;AACvE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAUzC,MAAM,aAAa,GAAG,sBAAsB,CAAC;AAC7C,MAAM,cAAc,GAAG,SAAS,CAAC;AASjC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAuC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAoB,EAAE,UAAuC,EAAE;IAClG,MAAM,gBAAgB,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACrF,MAAM,MAAM,GAAG;QACb,gBAAgB;QAChB,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,aAAa;QACzD,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,cAAc;KAC7D,CAAC;IACF,MAAM,IAAI,GAAqB,KAAK,EAAE,MAAM,EAAE,EAAE;QAC9C,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,MAAM,CAAC,CAAC;YACjC,OAAO;QACT,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC;QAChE,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,eAAe,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;IACzH,OAAO,IAAI,CAAC;AACd,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,gBAAgB,CAAC,IAAsB;IACrD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;AACnC,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,gBAAgB,CAAC,IAAsB;IACrD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;AACnC,CAAC"}

package/dist/testing/global-setup.d.ts

@@ -0,0 +1,2 @@
+export default function setup(): Promise<() => Promise<void>>;
+//# sourceMappingURL=global-setup.d.ts.map

package/dist/testing/global-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-setup.d.ts","sourceRoot":"","sources":["../../src/testing/global-setup.ts"],"names":[],"mappings":"AASA,wBAA8B,KAAK,IAAI,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAWlE"}

package/dist/testing/global-setup.js

@@ -0,0 +1,21 @@
+// A Vitest `globalSetup` module (issue #641): `test: { globalSetup: ["@softure-ai/db/testing/global-setup"] }`.
+// It runs once in the main process before any worker starts and gives the run a template folder; workers inherit the
+// variable, so `createTestDatabase` migrates each module set once per run instead of once per test file. The folder
+// is removed when the run ends. A folder the app named itself (the variable already set) is kept.
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { TEMPLATE_DIR_VARIABLE } from "./template-store.js";
+export default async function setup() {
+    const given = process.env[TEMPLATE_DIR_VARIABLE];
+    if (given !== undefined && given !== "") {
+        return () => Promise.resolve();
+    }
+    const dir = await mkdtemp(join(tmpdir(), "softure-db-templates-"));
+    process.env[TEMPLATE_DIR_VARIABLE] = dir;
+    return async () => {
+        delete process.env[TEMPLATE_DIR_VARIABLE];
+        await rm(dir, { recursive: true, force: true });
+    };
+}
+//# sourceMappingURL=global-setup.js.map

package/dist/testing/global-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-setup.js","sourceRoot":"","sources":["../../src/testing/global-setup.ts"],"names":[],"mappings":"AAAA,gHAAgH;AAChH,qHAAqH;AACrH,oHAAoH;AACpH,kGAAkG;AAClG,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,KAAK;IACjC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACxC,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACjC,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,uBAAuB,CAAC,CAAC,CAAC;IACnE,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG,GAAG,CAAC;IACzC,OAAO,KAAK,IAAI,EAAE;QAChB,OAAO,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QAC1C,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

package/dist/testing/reuse.d.ts

@@ -0,0 +1,15 @@
+import type { PGlite } from "@electric-sql/pglite";
+import type { PgliteClientDatabase } from "../client.js";
+export interface PooledDatabase {
+    readonly db: PgliteClientDatabase;
+    readonly client: PGlite;
+    readonly close: () => Promise<void>;
+}
+/**
+ * A database from the pool of `key`, reset to the template's state, or a fresh copy from `open` when none is idle.
+ * Its `close` puts it back; a second `close` does nothing.
+ */
+export declare function acquirePooledDatabase(key: string, open: () => Promise<PooledDatabase>): Promise<PooledDatabase>;
+/** Closes every idle database of every pool; for `afterAll`. A database still held is closed when it comes back. */
+export declare function closePooledDatabases(): Promise<void>;
+//# sourceMappingURL=reuse.d.ts.map

package/dist/testing/reuse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reuse.d.ts","sourceRoot":"","sources":["../../src/testing/reuse.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B,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;AAkED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAkBrH;AAED,oHAAoH;AACpH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAM1D"}

package/dist/testing/reuse.js

@@ -0,0 +1,155 @@
+const pools = new Map();
+const USER_NAMESPACE = "n.nspname not in ('pg_catalog', 'information_schema') and n.nspname not like 'pg\\_toast%' and n.nspname not like 'pg\\_temp\\_%'";
+// What a reset cannot undo. Indexes, constraints and triggers are listed with their table, enum labels with their type.
+const FINGERPRINT_SQL = `
+select coalesce(string_agg(entry, E'\\n' order by entry), '') as fingerprint from (
+  select format('rel %s %I.%I %s', c.relkind, n.nspname, c.relname,
+    (select string_agg(format('%I:%s', a.attname, format_type(a.atttypid, a.atttypmod)), ',' order by a.attnum)
+      from pg_attribute a where a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped)) as entry
+    from pg_class c join pg_namespace n on n.oid = c.relnamespace where ${USER_NAMESPACE}
+  union all
+  select format('fn %I.%I(%s)', n.nspname, p.proname, pg_get_function_identity_arguments(p.oid))
+    from pg_proc p join pg_namespace n on n.oid = p.pronamespace where ${USER_NAMESPACE}
+  union all
+  select format('con %s %s %s', co.conrelid::regclass, co.conname, co.contype)
+    from pg_constraint co join pg_namespace n on n.oid = co.connamespace where ${USER_NAMESPACE}
+  union all
+  select format('trg %s %s %s', t.tgrelid::regclass, t.tgname, t.tgenabled) from pg_trigger t where not t.tgisinternal
+  union all
+  select format('enum %s %s', e.enumtypid::regtype, e.enumlabel)
+    from pg_enum e join pg_type ty on ty.oid = e.enumtypid join pg_namespace n on n.oid = ty.typnamespace where ${USER_NAMESPACE}
+) entries`;
+const TABLES_SQL = `
+select format('%I.%I', n.nspname, c.relname) as name, c.relkind::text as kind, c.relispopulated as populated,
+  (select string_agg(format('%I', a.attname), ', ' order by a.attnum) from pg_attribute a
+    where a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped and a.attgenerated = '') as columns
+from pg_class c join pg_namespace n on n.oid = c.relnamespace
+where c.relkind in ('r', 'p', 'm') and ${USER_NAMESPACE}
+order by 1`;
+const SEQUENCES_SQL = `
+select format('%I.%I', schemaname, sequencename) as name, coalesce(last_value, start_value)::text as value, last_value is not null as called
+from pg_sequences where schemaname not in ('pg_catalog', 'information_schema')`;
+const RESTORE_SEQUENCES_SQL = "select setval(s.name::regclass, s.value, s.called) from json_to_recordset($1::json) as s(name text, value bigint, called boolean)";
+/**
+ * A database from the pool of `key`, reset to the template's state, or a fresh copy from `open` when none is idle.
+ * Its `close` puts it back; a second `close` does nothing.
+ */
+export async function acquirePooledDatabase(key, open) {
+    const pool = getPool(key);
+    for (let idle = pool.idle.pop(); idle !== undefined; idle = pool.idle.pop()) {
+        if (pool.state !== undefined && (await tryRestore(idle.client, await pool.state))) {
+            return lend(pool, idle);
+        }
+        await idle.close();
+    }
+    const fresh = await open();
+    try {
+        pool.state ??= captureTemplateState(fresh.client);
+        await pool.state;
+    }
+    catch (error) {
+        pool.state = undefined;
+        await fresh.close();
+        throw error;
+    }
+    return lend(pool, fresh);
+}
+/** Closes every idle database of every pool; for `afterAll`. A database still held is closed when it comes back. */
+export async function closePooledDatabases() {
+    const retired = [...pools.values()];
+    pools.clear();
+    for (const pool of retired)
+        pool.isRetired = true;
+    const idle = retired.flatMap((pool) => pool.idle.splice(0));
+    await Promise.all(idle.map((database) => database.close()));
+}
+function getPool(key) {
+    let pool = pools.get(key);
+    if (pool === undefined) {
+        pool = { idle: [], state: undefined, isRetired: false };
+        pools.set(key, pool);
+    }
+    return pool;
+}
+function lend(pool, database) {
+    let isReturned = false;
+    return {
+        db: database.db,
+        client: database.client,
+        close: () => {
+            if (isReturned) {
+                return Promise.resolve();
+            }
+            isReturned = true;
+            if (pool.isRetired) {
+                return database.close();
+            }
+            pool.idle.push(database);
+            return Promise.resolve();
+        },
+    };
+}
+async function captureTemplateState(client) {
+    const fingerprint = await readFingerprint(client);
+    const relations = await client.query(TABLES_SQL);
+    const seeds = [];
+    for (const relation of relations.rows) {
+        if (relation.kind !== "r" || relation.columns === null) {
+            continue;
+        }
+        const hasRows = await client.query(`select exists (select 1 from ${relation.name}) as has_rows`);
+        if (hasRows.rows[0]?.has_rows === true) {
+            const copied = await client.query(`copy ${relation.name} (${relation.columns}) to '/dev/blob'`);
+            if (copied.blob === undefined) {
+                throw new Error(`createTestDatabase: copying the template rows of ${relation.name} returned no data`);
+            }
+            seeds.push({ table: relation.name, columns: relation.columns, rows: copied.blob });
+        }
+    }
+    const sequences = await client.query(SEQUENCES_SQL);
+    return {
+        fingerprint,
+        tables: relations.rows.filter((relation) => relation.kind !== "m").map((relation) => relation.name),
+        seeds,
+        sequences: sequences.rows,
+        materializedViews: relations.rows.filter((relation) => relation.kind === "m" && relation.populated).map((relation) => relation.name),
+    };
+}
+async function readFingerprint(client) {
+    const result = await client.query(FINGERPRINT_SQL);
+    return result.rows[0]?.fingerprint ?? "";
+}
+/**
+ * Restores the template's rows and session state. `false` when the database cannot be reset (its schema changed, or
+ * the test left it in a state a reset fails on, such as an open transaction): the caller replaces it.
+ */
+async function tryRestore(client, state) {
+    try {
+        await client.exec("DISCARD ALL");
+        if ((await readFingerprint(client)) !== state.fingerprint) {
+            return false;
+        }
+        await client.transaction(async (tx) => {
+            // Rows go back as they were, so foreign keys and triggers stay out of the way.
+            await tx.exec("SET LOCAL session_replication_role = replica");
+            if (state.tables.length > 0) {
+                await tx.exec(`TRUNCATE ${state.tables.join(", ")} CASCADE`);
+            }
+            for (const seed of state.seeds) {
+                await tx.query(`copy ${seed.table} (${seed.columns}) from '/dev/blob'`, [], { blob: seed.rows });
+            }
+            if (state.sequences.length > 0) {
+                await tx.query(RESTORE_SEQUENCES_SQL, [JSON.stringify(state.sequences)]);
+            }
+            for (const view of state.materializedViews) {
+                await tx.exec(`REFRESH MATERIALIZED VIEW ${view}`);
+            }
+        });
+        return true;
+    }
+    catch {
+        // Deliberately not reported: a database a test broke is replaced by a fresh copy, which is what the test expects.
+        return false;
+    }
+}
+//# sourceMappingURL=reuse.js.map

package/dist/testing/reuse.js.map

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

package/dist/testing/template-store.d.ts

@@ -0,0 +1,23 @@
+import type { AnySoftureModule } from "@softure-ai/core";
+import type { AppMigrations } from "../migrations/migrator.js";
+/** The variable naming the run's template folder. Set by the global setup; an app may set it itself. */
+export declare const TEMPLATE_DIR_VARIABLE = "SOFTURE_DB_TEST_TEMPLATES";
+export interface TemplateSource {
+    readonly modules: readonly AnySoftureModule[];
+    readonly app: AppMigrations;
+    readonly templateKey: string | undefined;
+}
+export declare function getTemplateDir(): string | null;
+/**
+ * The name of a template on disk, or `null` when it cannot be identified across processes: an app hook other than
+ * `drizzleAppMigrations` without a `templateKey`.
+ */
+export declare function computeTemplateName(source: TemplateSource): Promise<string | null>;
+/** The stored template, or `null` when this run has not written it yet. */
+export declare function readStoredTemplate(dir: string, name: string): Promise<Blob | null>;
+/**
+ * Writes the template under a temporary name and renames it, so a worker reading at the same time sees the whole
+ * file or none. Two workers building the same template both write it; the second rename wins with identical bytes.
+ */
+export declare function storeTemplate(dir: string, name: string, template: Blob): Promise<void>;
+//# sourceMappingURL=template-store.d.ts.map

package/dist/testing/template-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-store.d.ts","sourceRoot":"","sources":["../../src/testing/template-store.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAoB,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAEjF,wGAAwG;AACxG,eAAO,MAAM,qBAAqB,8BAA8B,CAAC;AAKjE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAG9C;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxF;AAED,2EAA2E;AAC3E,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CASxF;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAS5F"}

package/dist/testing/template-store.js

@@ -0,0 +1,103 @@
+// Migrated test templates on disk, shared by every test file and worker of one run (issue #641). The global setup
+// (`@softure-ai/db/testing/global-setup`) gives the run a folder through an environment variable; without it nothing
+// is written and each file migrates its own template, as before. A template is named by a hash of what it is built
+// from (the module and drizzle files, the hooks' `templateKey`, the baseline), never by object identity, which means
+// nothing in another process.
+import { createHash, randomUUID } from "node:crypto";
+import { readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getDrizzleFolder, getDrizzleLedger } from "../migrations/drizzle.js";
+/** The variable naming the run's template folder. Set by the global setup; an app may set it itself. */
+export const TEMPLATE_DIR_VARIABLE = "SOFTURE_DB_TEST_TEMPLATES";
+// Bumped when the stored format or the key changes, so a folder an app keeps across runs is not misread.
+const STORE_VERSION = "1";
+export function getTemplateDir() {
+    const dir = process.env[TEMPLATE_DIR_VARIABLE];
+    return dir === undefined || dir === "" ? null : dir;
+}
+/**
+ * The name of a template on disk, or `null` when it cannot be identified across processes: an app hook other than
+ * `drizzleAppMigrations` without a `templateKey`.
+ */
+export async function computeTemplateName(source) {
+    const parts = [`store:${STORE_VERSION}`];
+    for (const module of source.modules) {
+        const dir = module.migrations === null || module.migrations === undefined ? "-" : await hashFolder(fileURLToPath(module.migrations.dir));
+        parts.push(`module:${module.id}:${dir}`);
+    }
+    for (const [phase, hook] of [["before", source.app.before], ["after", source.app.after]]) {
+        const identity = await identifyHook(hook, source.templateKey);
+        if (identity === null) {
+            return null;
+        }
+        parts.push(`${phase}:${identity}`);
+    }
+    parts.push(`templateKey:${source.templateKey ?? "-"}`);
+    const baseline = Object.entries(source.app.baseline ?? {}).sort(([left], [right]) => left.localeCompare(right));
+    parts.push(`baseline:${baseline.map(([id, through]) => `${id}=${through}`).join(",")}`);
+    return createHash("sha256").update(parts.join("\n")).digest("hex");
+}
+/** The stored template, or `null` when this run has not written it yet. */
+export async function readStoredTemplate(dir, name) {
+    try {
+        return new Blob([await readFile(join(dir, `${name}.tar`))]);
+    }
+    catch (error) {
+        if (isMissingFile(error)) {
+            return null;
+        }
+        throw new Error(`createTestDatabase: reading the stored template ${name} in ${dir} failed`, { cause: error });
+    }
+}
+/**
+ * Writes the template under a temporary name and renames it, so a worker reading at the same time sees the whole
+ * file or none. Two workers building the same template both write it; the second rename wins with identical bytes.
+ */
+export async function storeTemplate(dir, name, template) {
+    const path = join(dir, `${name}.tar`);
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, new Uint8Array(await template.arrayBuffer()));
+        await rename(temporary, path);
+    }
+    catch (error) {
+        throw new Error(`createTestDatabase: storing the template ${name} in ${dir} failed`, { cause: error });
+    }
+}
+async function identifyHook(hook, templateKey) {
+    if (hook === undefined) {
+        return "-";
+    }
+    const folder = getDrizzleFolder(hook);
+    if (folder !== undefined) {
+        return `drizzle:${getDrizzleLedger(hook) ?? "-"}:${await hashFolder(folder)}`;
+    }
+    // A custom hook is a function: only the app can say which migrations it runs.
+    return templateKey === undefined ? null : "custom";
+}
+// Every file under the folder, by relative path and content. A missing folder hashes as such: `migrate` reports it.
+async function hashFolder(folder) {
+    const hash = createHash("sha256");
+    let entries;
+    try {
+        entries = await readdir(folder, { recursive: true, withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingFile(error)) {
+            return "missing";
+        }
+        throw new Error(`createTestDatabase: reading the migrations folder ${folder} failed`, { cause: error });
+    }
+    const files = entries.filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name)).sort();
+    for (const file of files) {
+        hash.update(`${relative(folder, file)}\0`);
+        hash.update(await readFile(file));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+//# sourceMappingURL=template-store.js.map

package/dist/testing/template-store.js.map

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

package/dist/testing.d.ts

@@ -3,6 +3,7 @@ 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 { TEMPLATE_DIR_VARIABLE } from "./testing/template-store.js";
 export interface TestDatabase {
     readonly db: PgliteClientDatabase;
     readonly client: PGlite;
@@ -14,6 +15,18 @@ export interface CreateTestDatabaseOptions {
      * cached per hook object: define the hooks once, at module level, not inline per call.
      */
     readonly app?: AppMigrations;
+    /**
+     * Names what the app hooks migrate, for the run-wide template folder of the global setup. Needed only for a hook
+     * other than `drizzleAppMigrations` (whose files are read); without it such a template is kept per test file.
+     * Change it when those migrations change, e.g. include a version.
+     */
+    readonly templateKey?: string;
+    /**
+     * `true`: a database a test closed is reset to the template and handed out again (a few milliseconds instead of a
+     * new copy). Rows, sequences and session state are reset; a test that changes the schema gets a fresh copy next
+     * time. Two open databases never share an instance.
+     */
+    readonly reuse?: boolean;
 }
 /**
  * A fresh, migrated, in-memory database per call. List the module under test and the modules it
@@ -21,4 +34,6 @@ export interface CreateTestDatabaseOptions {
  * module package or the app's migrations.
  */
 export declare function createTestDatabase(modules?: readonly AnySoftureModule[], options?: CreateTestDatabaseOptions): Promise<TestDatabase>;
+/** Closes the idle databases `reuse` keeps, so a test file can free them in `afterAll`. */
+export declare function closeReusedTestDatabases(): Promise<void>;
 //# sourceMappingURL=testing.d.ts.map

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,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"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAQA,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;AAK9F,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,EAC3B,KAAK,iBAAiB,EACtB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,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;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAMD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,SAAS,gBAAgB,EAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,YAAY,CAAC,CASlJ;AAED,2FAA2F;AAC3F,wBAAgB,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,CAExD"}

package/dist/testing.js

@@ -1,14 +1,19 @@
 // Test databases for module unit tests (docs/02-module-standard.md §10): a real Postgres (PGlite)
-// with the real migrations of the given modules. Migrating costs about two seconds, so each
-// module set is migrated once per test worker into a template, and every call starts from a copy
-// of the template's data folder (FIRE_TRACKER `src/db/test-db.ts`). An app with its own migrations
-// passes the same `app` hooks (and baseline) as to `migrate`, so module tables can reference app
-// tables and a module the app's history already creates is adopted in the template.
+// with the real migrations of the given modules. Migrating costs seconds, so each module set is
+// migrated once into a template, and every call starts from a copy of the template's data folder
+// (FIRE_TRACKER `src/db/test-db.ts`). The template is kept per test file, and per run when the
+// global setup gives the run a folder (testing/template-store.ts). `reuse` hands back a used
+// database reset to the template instead of a new copy (testing/reuse.ts). An app with its own
+// migrations passes the same `app` hooks (and baseline) as to `migrate`, so module tables can
+// reference app tables and a module the app's history already creates is adopted in the template.
 import { PGlite } from "@electric-sql/pglite";
 import { createPgliteHandle } from "./client.js";
 import { migrate } from "./migrations/migrator.js";
 import { describeProblem } from "./migrations/problems.js";
+import { acquirePooledDatabase, closePooledDatabases } from "./testing/reuse.js";
+import { computeTemplateName, getTemplateDir, readStoredTemplate, storeTemplate } from "./testing/template-store.js";
 export { DEFAULT_DATABASE_OPENERS, expectEntriesOpenDatabase, findEntriesReachingDatabase, } from "./entry-guard.js";
+export { TEMPLATE_DIR_VARIABLE } from "./testing/template-store.js";
 const templates = new Map();
 const hookIds = new WeakMap();
 let nextHookId = 1;
@@ -18,17 +23,28 @@ let nextHookId = 1;
  * module package or the app's migrations.
  */
 export async function createTestDatabase(modules = [], options = {}) {
-    const client = new PGlite({ loadDataDir: await getTemplate(modules, options.app ?? {}) });
-    const handle = await createPgliteHandle(client);
-    return { db: handle.db, client, close: handle.close };
+    const app = options.app ?? {};
+    const key = computeTemplateKey(modules, app, options.templateKey);
+    const openCopy = async () => {
+        const client = new PGlite({ loadDataDir: await getTemplate(key, modules, app, options.templateKey) });
+        const handle = await createPgliteHandle(client);
+        return { db: handle.db, client, close: handle.close };
+    };
+    return options.reuse === true ? acquirePooledDatabase(key, openCopy) : openCopy();
 }
-function getTemplate(modules, app) {
+/** Closes the idle databases `reuse` keeps, so a test file can free them in `afterAll`. */
+export function closeReusedTestDatabases() {
+    return closePooledDatabases();
+}
+function computeTemplateKey(modules, app, templateKey) {
     const moduleKey = modules.map((module) => `${module.id}@${module.migrations?.dir.href ?? "-"}`).join("|");
     const baselineKey = Object.entries(app.baseline ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([id, through]) => `${id}:${through}`).join(",");
-    const key = `${moduleKey}#before:${identifyHook(app.before)}#after:${identifyHook(app.after)}#baseline:${baselineKey}`;
+    return `${moduleKey}#before:${identifyHook(app.before)}#after:${identifyHook(app.after)}#baseline:${baselineKey}#key:${templateKey ?? "-"}`;
+}
+function getTemplate(key, modules, app, templateKey) {
     let template = templates.get(key);
     if (template === undefined) {
-        template = buildTemplate(modules, app);
+        template = loadOrBuildTemplate(modules, app, templateKey);
         templates.set(key, template);
         // A failed build is not cached: the next call reports the problem again.
         template.catch(() => templates.delete(key));
@@ -47,6 +63,21 @@ function identifyHook(hook) {
     }
     return String(id);
 }
+// From the run's folder when another file already built it; otherwise built here and stored for the others.
+async function loadOrBuildTemplate(modules, app, templateKey) {
+    const dir = getTemplateDir();
+    const name = dir === null ? null : await computeTemplateName({ modules, app, templateKey });
+    if (dir === null || name === null) {
+        return buildTemplate(modules, app);
+    }
+    const stored = await readStoredTemplate(dir, name);
+    if (stored !== null) {
+        return stored;
+    }
+    const built = await buildTemplate(modules, app);
+    await storeTemplate(dir, name, built);
+    return built;
+}
 async function buildTemplate(modules, app) {
     const handle = await createPgliteHandle(new PGlite());
     try {

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,4FAA4F;AAC5F,iGAAiG;AACjG,mGAAmG;AACnG,iGAAiG;AACjG,oFAAoF;AACpF,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAA6B,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,OAAO,EAA6C,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,GAG5B,MAAM,kBAAkB,CAAC;AAgB1B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAgC,CAAC;AAC1D,MAAM,OAAO,GAAG,IAAI,OAAO,EAA4B,CAAC;AACxD,IAAI,UAAU,GAAG,CAAC,CAAC;AAEnB;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,UAAuC,EAAE,EAAE,UAAqC,EAAE;IACzH,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1F,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAChD,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,WAAW,CAAC,OAAoC,EAAE,GAAkB;IAC3E,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1G,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,IAAI,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjK,MAAM,GAAG,GAAG,GAAG,SAAS,WAAW,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,WAAW,EAAE,CAAC;IACvH,IAAI,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,QAAQ,GAAG,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACvC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC7B,yEAAyE;QACzE,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,2FAA2F;AAC3F,SAAS,YAAY,CAAC,IAAkC;IACtD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,EAAE,GAAG,UAAU,EAAE,CAAC;QAClB,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC;AACpB,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,OAAoC,EAAE,GAAkB;IACnF,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,2CAA2C,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChH,CAAC;QACD,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACjD,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,gGAAgG;AAChG,iGAAiG;AACjG,+FAA+F;AAC/F,6FAA6F;AAC7F,+FAA+F;AAC/F,8FAA8F;AAC9F,kGAAkG;AAClG,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAA6B,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,OAAO,EAA6C,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAErH,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,2BAA2B,GAG5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AA4BpE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAgC,CAAC;AAC1D,MAAM,OAAO,GAAG,IAAI,OAAO,EAA4B,CAAC;AACxD,IAAI,UAAU,GAAG,CAAC,CAAC;AAEnB;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,UAAuC,EAAE,EAAE,UAAqC,EAAE;IACzH,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;IAC9B,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,KAAK,IAA2B,EAAE;QACjD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACtG,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAChD,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;IACxD,CAAC,CAAC;IACF,OAAO,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,qBAAqB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AACpF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,wBAAwB;IACtC,OAAO,oBAAoB,EAAE,CAAC;AAChC,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAoC,EAAE,GAAkB,EAAE,WAA+B;IACnH,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1G,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,IAAI,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjK,OAAO,GAAG,SAAS,WAAW,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,WAAW,QAAQ,WAAW,IAAI,GAAG,EAAE,CAAC;AAC9I,CAAC;AAED,SAAS,WAAW,CAAC,GAAW,EAAE,OAAoC,EAAE,GAAkB,EAAE,WAA+B;IACzH,IAAI,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,QAAQ,GAAG,mBAAmB,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;QAC1D,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC7B,yEAAyE;QACzE,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,2FAA2F;AAC3F,SAAS,YAAY,CAAC,IAAkC;IACtD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,EAAE,GAAG,UAAU,EAAE,CAAC;QAClB,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC;AACpB,CAAC;AAED,4GAA4G;AAC5G,KAAK,UAAU,mBAAmB,CAAC,OAAoC,EAAE,GAAkB,EAAE,WAA+B;IAC1H,MAAM,GAAG,GAAG,cAAc,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,mBAAmB,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,CAAC;IAC5F,IAAI,GAAG,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACnD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAChD,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,OAAoC,EAAE,GAAkB;IACnF,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,2CAA2C,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChH,CAAC;QACD,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACjD,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/db",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "SOFTURE AI database layer: pg/PGlite client, per-module migrator with plan and adopt, PGlite test databases.",
   "license": "MIT",
   "type": "module",
@@ -38,6 +38,11 @@
       "types": "./dist/testing.d.ts",
       "default": "./dist/testing.js"
     },
+    "./testing/global-setup": {
+      "@softure-ai/source": "./src/testing/global-setup.ts",
+      "types": "./dist/testing/global-setup.d.ts",
+      "default": "./dist/testing/global-setup.js"
+    },
     "./cli": {
       "@softure-ai/source": "./src/cli/index.ts",
       "types": "./dist/cli/index.d.ts",

package/src/migrations/drizzle.ts

@@ -1,5 +1,6 @@
 // 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 { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AppMigrationHook } from "./migrator.js";
 
@@ -13,8 +14,14 @@ export interface DrizzleAppMigrationsOptions {
 const DEFAULT_TABLE = "__drizzle_migrations";
 const DEFAULT_SCHEMA = "drizzle";
 
-// The ledger each hook writes to, so `migrate` can refuse a `before` and an `after` sharing one (issue #534).
-const ledgers = new WeakMap<AppMigrationHook, string>();
+interface DrizzleHookSource {
+  /** `schema.table`, so `migrate` can refuse a `before` and an `after` sharing one (issue #534). */
+  readonly ledger: string;
+  /** The absolute folder, so a test template can be identified by its files across processes (issue #641). */
+  readonly folder: string;
+}
+
+const sources = new WeakMap<AppMigrationHook, DrizzleHookSource>();
 
 /**
  * A hook for `app.before` (or `app.after`) that applies the drizzle-kit folder (`meta/_journal.json` and its SQL
@@ -39,11 +46,16 @@ export function drizzleAppMigrations(folder: string | URL, options: DrizzleAppMi
     const { migrate } = await import("drizzle-orm/pglite/migrator");
     await migrate(handle.db, config);
   };
-  ledgers.set(hook, `${config.migrationsSchema}.${config.migrationsTable}`);
+  sources.set(hook, { ledger: `${config.migrationsSchema}.${config.migrationsTable}`, folder: resolve(migrationsFolder) });
   return hook;
 }
 
 /** The ledger (`schema.table`) a `drizzleAppMigrations` hook writes to; `undefined` for any other hook. */
 export function getDrizzleLedger(hook: AppMigrationHook): string | undefined {
-  return ledgers.get(hook);
+  return sources.get(hook)?.ledger;
+}
+
+/** The absolute folder a `drizzleAppMigrations` hook applies; `undefined` for any other hook. */
+export function getDrizzleFolder(hook: AppMigrationHook): string | undefined {
+  return sources.get(hook)?.folder;
 }

package/src/testing/global-setup.ts

@@ -0,0 +1,21 @@
+// A Vitest `globalSetup` module (issue #641): `test: { globalSetup: ["@softure-ai/db/testing/global-setup"] }`.
+// It runs once in the main process before any worker starts and gives the run a template folder; workers inherit the
+// variable, so `createTestDatabase` migrates each module set once per run instead of once per test file. The folder
+// is removed when the run ends. A folder the app named itself (the variable already set) is kept.
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { TEMPLATE_DIR_VARIABLE } from "./template-store.js";
+
+export default async function setup(): Promise<() => Promise<void>> {
+  const given = process.env[TEMPLATE_DIR_VARIABLE];
+  if (given !== undefined && given !== "") {
+    return () => Promise.resolve();
+  }
+  const dir = await mkdtemp(join(tmpdir(), "softure-db-templates-"));
+  process.env[TEMPLATE_DIR_VARIABLE] = dir;
+  return async () => {
+    delete process.env[TEMPLATE_DIR_VARIABLE];
+    await rm(dir, { recursive: true, force: true });
+  };
+}

package/src/testing/reuse.ts

@@ -0,0 +1,205 @@
+// Reusable test databases (`createTestDatabase(modules, { reuse: true })`, issue #641). Booting a PGlite from the
+// template costs ~0.6 s; putting a used one back costs a few milliseconds. A database closed by a test goes back to a
+// pool per template; the next call takes it and restores the template's state: every table emptied and its template
+// rows copied back (migration ledgers and seed rows included), sequences set to the template's values, materialized
+// views refreshed, session state discarded. A database whose schema the test changed (a table, column, function,
+// trigger, constraint or enum value) is closed and replaced by a fresh copy, since rows are all a reset can undo.
+// The pool is module state: one test file under Vitest's default isolation; `closeReusedTestDatabases` empties it.
+import type { PGlite } from "@electric-sql/pglite";
+import type { PgliteClientDatabase } from "../client.js";
+
+export interface PooledDatabase {
+  readonly db: PgliteClientDatabase;
+  readonly client: PGlite;
+  readonly close: () => Promise<void>;
+}
+
+interface SeedTable {
+  readonly table: string;
+  readonly columns: string;
+  readonly rows: Blob;
+}
+
+interface SequenceValue {
+  readonly name: string;
+  readonly value: string;
+  readonly called: boolean;
+}
+
+interface TemplateState {
+  readonly fingerprint: string;
+  readonly tables: readonly string[];
+  readonly seeds: readonly SeedTable[];
+  readonly sequences: readonly SequenceValue[];
+  readonly materializedViews: readonly string[];
+}
+
+interface Pool {
+  readonly idle: PooledDatabase[];
+  state: Promise<TemplateState> | undefined;
+  isRetired: boolean;
+}
+
+const pools = new Map<string, Pool>();
+
+const USER_NAMESPACE = "n.nspname not in ('pg_catalog', 'information_schema') and n.nspname not like 'pg\\_toast%' and n.nspname not like 'pg\\_temp\\_%'";
+
+// What a reset cannot undo. Indexes, constraints and triggers are listed with their table, enum labels with their type.
+const FINGERPRINT_SQL = `
+select coalesce(string_agg(entry, E'\\n' order by entry), '') as fingerprint from (
+  select format('rel %s %I.%I %s', c.relkind, n.nspname, c.relname,
+    (select string_agg(format('%I:%s', a.attname, format_type(a.atttypid, a.atttypmod)), ',' order by a.attnum)
+      from pg_attribute a where a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped)) as entry
+    from pg_class c join pg_namespace n on n.oid = c.relnamespace where ${USER_NAMESPACE}
+  union all
+  select format('fn %I.%I(%s)', n.nspname, p.proname, pg_get_function_identity_arguments(p.oid))
+    from pg_proc p join pg_namespace n on n.oid = p.pronamespace where ${USER_NAMESPACE}
+  union all
+  select format('con %s %s %s', co.conrelid::regclass, co.conname, co.contype)
+    from pg_constraint co join pg_namespace n on n.oid = co.connamespace where ${USER_NAMESPACE}
+  union all
+  select format('trg %s %s %s', t.tgrelid::regclass, t.tgname, t.tgenabled) from pg_trigger t where not t.tgisinternal
+  union all
+  select format('enum %s %s', e.enumtypid::regtype, e.enumlabel)
+    from pg_enum e join pg_type ty on ty.oid = e.enumtypid join pg_namespace n on n.oid = ty.typnamespace where ${USER_NAMESPACE}
+) entries`;
+
+const TABLES_SQL = `
+select format('%I.%I', n.nspname, c.relname) as name, c.relkind::text as kind, c.relispopulated as populated,
+  (select string_agg(format('%I', a.attname), ', ' order by a.attnum) from pg_attribute a
+    where a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped and a.attgenerated = '') as columns
+from pg_class c join pg_namespace n on n.oid = c.relnamespace
+where c.relkind in ('r', 'p', 'm') and ${USER_NAMESPACE}
+order by 1`;
+
+const SEQUENCES_SQL = `
+select format('%I.%I', schemaname, sequencename) as name, coalesce(last_value, start_value)::text as value, last_value is not null as called
+from pg_sequences where schemaname not in ('pg_catalog', 'information_schema')`;
+
+const RESTORE_SEQUENCES_SQL = "select setval(s.name::regclass, s.value, s.called) from json_to_recordset($1::json) as s(name text, value bigint, called boolean)";
+
+/**
+ * A database from the pool of `key`, reset to the template's state, or a fresh copy from `open` when none is idle.
+ * Its `close` puts it back; a second `close` does nothing.
+ */
+export async function acquirePooledDatabase(key: string, open: () => Promise<PooledDatabase>): Promise<PooledDatabase> {
+  const pool = getPool(key);
+  for (let idle = pool.idle.pop(); idle !== undefined; idle = pool.idle.pop()) {
+    if (pool.state !== undefined && (await tryRestore(idle.client, await pool.state))) {
+      return lend(pool, idle);
+    }
+    await idle.close();
+  }
+  const fresh = await open();
+  try {
+    pool.state ??= captureTemplateState(fresh.client);
+    await pool.state;
+  } catch (error) {
+    pool.state = undefined;
+    await fresh.close();
+    throw error;
+  }
+  return lend(pool, fresh);
+}
+
+/** Closes every idle database of every pool; for `afterAll`. A database still held is closed when it comes back. */
+export async function closePooledDatabases(): Promise<void> {
+  const retired = [...pools.values()];
+  pools.clear();
+  for (const pool of retired) pool.isRetired = true;
+  const idle = retired.flatMap((pool) => pool.idle.splice(0));
+  await Promise.all(idle.map((database) => database.close()));
+}
+
+function getPool(key: string): Pool {
+  let pool = pools.get(key);
+  if (pool === undefined) {
+    pool = { idle: [], state: undefined, isRetired: false };
+    pools.set(key, pool);
+  }
+  return pool;
+}
+
+function lend(pool: Pool, database: PooledDatabase): PooledDatabase {
+  let isReturned = false;
+  return {
+    db: database.db,
+    client: database.client,
+    close: () => {
+      if (isReturned) {
+        return Promise.resolve();
+      }
+      isReturned = true;
+      if (pool.isRetired) {
+        return database.close();
+      }
+      pool.idle.push(database);
+      return Promise.resolve();
+    },
+  };
+}
+
+async function captureTemplateState(client: PGlite): Promise<TemplateState> {
+  const fingerprint = await readFingerprint(client);
+  const relations = await client.query<{ name: string; kind: string; populated: boolean; columns: string | null }>(TABLES_SQL);
+  const seeds: SeedTable[] = [];
+  for (const relation of relations.rows) {
+    if (relation.kind !== "r" || relation.columns === null) {
+      continue;
+    }
+    const hasRows = await client.query<{ has_rows: boolean }>(`select exists (select 1 from ${relation.name}) as has_rows`);
+    if (hasRows.rows[0]?.has_rows === true) {
+      const copied = await client.query(`copy ${relation.name} (${relation.columns}) to '/dev/blob'`);
+      if (copied.blob === undefined) {
+        throw new Error(`createTestDatabase: copying the template rows of ${relation.name} returned no data`);
+      }
+      seeds.push({ table: relation.name, columns: relation.columns, rows: copied.blob });
+    }
+  }
+  const sequences = await client.query<SequenceValue>(SEQUENCES_SQL);
+  return {
+    fingerprint,
+    tables: relations.rows.filter((relation) => relation.kind !== "m").map((relation) => relation.name),
+    seeds,
+    sequences: sequences.rows,
+    materializedViews: relations.rows.filter((relation) => relation.kind === "m" && relation.populated).map((relation) => relation.name),
+  };
+}
+
+async function readFingerprint(client: PGlite): Promise<string> {
+  const result = await client.query<{ fingerprint: string }>(FINGERPRINT_SQL);
+  return result.rows[0]?.fingerprint ?? "";
+}
+
+/**
+ * Restores the template's rows and session state. `false` when the database cannot be reset (its schema changed, or
+ * the test left it in a state a reset fails on, such as an open transaction): the caller replaces it.
+ */
+async function tryRestore(client: PGlite, state: TemplateState): Promise<boolean> {
+  try {
+    await client.exec("DISCARD ALL");
+    if ((await readFingerprint(client)) !== state.fingerprint) {
+      return false;
+    }
+    await client.transaction(async (tx) => {
+      // Rows go back as they were, so foreign keys and triggers stay out of the way.
+      await tx.exec("SET LOCAL session_replication_role = replica");
+      if (state.tables.length > 0) {
+        await tx.exec(`TRUNCATE ${state.tables.join(", ")} CASCADE`);
+      }
+      for (const seed of state.seeds) {
+        await tx.query(`copy ${seed.table} (${seed.columns}) from '/dev/blob'`, [], { blob: seed.rows });
+      }
+      if (state.sequences.length > 0) {
+        await tx.query(RESTORE_SEQUENCES_SQL, [JSON.stringify(state.sequences)]);
+      }
+      for (const view of state.materializedViews) {
+        await tx.exec(`REFRESH MATERIALIZED VIEW ${view}`);
+      }
+    });
+    return true;
+  } catch {
+    // Deliberately not reported: a database a test broke is replaced by a fresh copy, which is what the test expects.
+    return false;
+  }
+}

package/src/testing/template-store.ts

@@ -0,0 +1,116 @@
+// Migrated test templates on disk, shared by every test file and worker of one run (issue #641). The global setup
+// (`@softure-ai/db/testing/global-setup`) gives the run a folder through an environment variable; without it nothing
+// is written and each file migrates its own template, as before. A template is named by a hash of what it is built
+// from (the module and drizzle files, the hooks' `templateKey`, the baseline), never by object identity, which means
+// nothing in another process.
+import { createHash, randomUUID } from "node:crypto";
+import { readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AnySoftureModule } from "@softure-ai/core";
+import { getDrizzleFolder, getDrizzleLedger } from "../migrations/drizzle.js";
+import type { AppMigrationHook, AppMigrations } from "../migrations/migrator.js";
+
+/** The variable naming the run's template folder. Set by the global setup; an app may set it itself. */
+export const TEMPLATE_DIR_VARIABLE = "SOFTURE_DB_TEST_TEMPLATES";
+
+// Bumped when the stored format or the key changes, so a folder an app keeps across runs is not misread.
+const STORE_VERSION = "1";
+
+export interface TemplateSource {
+  readonly modules: readonly AnySoftureModule[];
+  readonly app: AppMigrations;
+  readonly templateKey: string | undefined;
+}
+
+export function getTemplateDir(): string | null {
+  const dir = process.env[TEMPLATE_DIR_VARIABLE];
+  return dir === undefined || dir === "" ? null : dir;
+}
+
+/**
+ * The name of a template on disk, or `null` when it cannot be identified across processes: an app hook other than
+ * `drizzleAppMigrations` without a `templateKey`.
+ */
+export async function computeTemplateName(source: TemplateSource): Promise<string | null> {
+  const parts = [`store:${STORE_VERSION}`];
+  for (const module of source.modules) {
+    const dir = module.migrations === null || module.migrations === undefined ? "-" : await hashFolder(fileURLToPath(module.migrations.dir));
+    parts.push(`module:${module.id}:${dir}`);
+  }
+  for (const [phase, hook] of [["before", source.app.before], ["after", source.app.after]] as const) {
+    const identity = await identifyHook(hook, source.templateKey);
+    if (identity === null) {
+      return null;
+    }
+    parts.push(`${phase}:${identity}`);
+  }
+  parts.push(`templateKey:${source.templateKey ?? "-"}`);
+  const baseline = Object.entries(source.app.baseline ?? {}).sort(([left], [right]) => left.localeCompare(right));
+  parts.push(`baseline:${baseline.map(([id, through]) => `${id}=${through}`).join(",")}`);
+  return createHash("sha256").update(parts.join("\n")).digest("hex");
+}
+
+/** The stored template, or `null` when this run has not written it yet. */
+export async function readStoredTemplate(dir: string, name: string): Promise<Blob | null> {
+  try {
+    return new Blob([await readFile(join(dir, `${name}.tar`))]);
+  } catch (error) {
+    if (isMissingFile(error)) {
+      return null;
+    }
+    throw new Error(`createTestDatabase: reading the stored template ${name} in ${dir} failed`, { cause: error });
+  }
+}
+
+/**
+ * Writes the template under a temporary name and renames it, so a worker reading at the same time sees the whole
+ * file or none. Two workers building the same template both write it; the second rename wins with identical bytes.
+ */
+export async function storeTemplate(dir: string, name: string, template: Blob): Promise<void> {
+  const path = join(dir, `${name}.tar`);
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, new Uint8Array(await template.arrayBuffer()));
+    await rename(temporary, path);
+  } catch (error) {
+    throw new Error(`createTestDatabase: storing the template ${name} in ${dir} failed`, { cause: error });
+  }
+}
+
+async function identifyHook(hook: AppMigrationHook | undefined, templateKey: string | undefined): Promise<string | null> {
+  if (hook === undefined) {
+    return "-";
+  }
+  const folder = getDrizzleFolder(hook);
+  if (folder !== undefined) {
+    return `drizzle:${getDrizzleLedger(hook) ?? "-"}:${await hashFolder(folder)}`;
+  }
+  // A custom hook is a function: only the app can say which migrations it runs.
+  return templateKey === undefined ? null : "custom";
+}
+
+// Every file under the folder, by relative path and content. A missing folder hashes as such: `migrate` reports it.
+async function hashFolder(folder: string): Promise<string> {
+  const hash = createHash("sha256");
+  let entries;
+  try {
+    entries = await readdir(folder, { recursive: true, withFileTypes: true });
+  } catch (error) {
+    if (isMissingFile(error)) {
+      return "missing";
+    }
+    throw new Error(`createTestDatabase: reading the migrations folder ${folder} failed`, { cause: error });
+  }
+  const files = entries.filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name)).sort();
+  for (const file of files) {
+    hash.update(`${relative(folder, file)}\0`);
+    hash.update(await readFile(file));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/src/testing.ts

@@ -1,14 +1,18 @@
 // Test databases for module unit tests (docs/02-module-standard.md §10): a real Postgres (PGlite)
-// with the real migrations of the given modules. Migrating costs about two seconds, so each
-// module set is migrated once per test worker into a template, and every call starts from a copy
-// of the template's data folder (FIRE_TRACKER `src/db/test-db.ts`). An app with its own migrations
-// passes the same `app` hooks (and baseline) as to `migrate`, so module tables can reference app
-// tables and a module the app's history already creates is adopted in the template.
+// with the real migrations of the given modules. Migrating costs seconds, so each module set is
+// migrated once into a template, and every call starts from a copy of the template's data folder
+// (FIRE_TRACKER `src/db/test-db.ts`). The template is kept per test file, and per run when the
+// global setup gives the run a folder (testing/template-store.ts). `reuse` hands back a used
+// database reset to the template instead of a new copy (testing/reuse.ts). An app with its own
+// migrations passes the same `app` hooks (and baseline) as to `migrate`, so module tables can
+// reference app tables and a module the app's history already creates is adopted in the template.
 import { PGlite } from "@electric-sql/pglite";
 import type { AnySoftureModule } from "@softure-ai/core";
 import { createPgliteHandle, type PgliteClientDatabase } from "./client.js";
 import { migrate, type AppMigrationHook, type AppMigrations } from "./migrations/migrator.js";
 import { describeProblem } from "./migrations/problems.js";
+import { acquirePooledDatabase, closePooledDatabases } from "./testing/reuse.js";
+import { computeTemplateName, getTemplateDir, readStoredTemplate, storeTemplate } from "./testing/template-store.js";
 
 export {
   DEFAULT_DATABASE_OPENERS,
@@ -17,6 +21,7 @@ export {
   type EntryGuardOptions,
   type EntryReach,
 } from "./entry-guard.js";
+export { TEMPLATE_DIR_VARIABLE } from "./testing/template-store.js";
 
 export interface TestDatabase {
   readonly db: PgliteClientDatabase;
@@ -30,6 +35,18 @@ export interface CreateTestDatabaseOptions {
    * cached per hook object: define the hooks once, at module level, not inline per call.
    */
   readonly app?: AppMigrations;
+  /**
+   * Names what the app hooks migrate, for the run-wide template folder of the global setup. Needed only for a hook
+   * other than `drizzleAppMigrations` (whose files are read); without it such a template is kept per test file.
+   * Change it when those migrations change, e.g. include a version.
+   */
+  readonly templateKey?: string;
+  /**
+   * `true`: a database a test closed is reset to the template and handed out again (a few milliseconds instead of a
+   * new copy). Rows, sequences and session state are reset; a test that changes the schema gets a fresh copy next
+   * time. Two open databases never share an instance.
+   */
+  readonly reuse?: boolean;
 }
 
 const templates = new Map<string, Promise<Blob | File>>();
@@ -42,18 +59,31 @@ let nextHookId = 1;
  * module package or the app's migrations.
  */
 export async function createTestDatabase(modules: readonly AnySoftureModule[] = [], options: CreateTestDatabaseOptions = {}): Promise<TestDatabase> {
-  const client = new PGlite({ loadDataDir: await getTemplate(modules, options.app ?? {}) });
-  const handle = await createPgliteHandle(client);
-  return { db: handle.db, client, close: handle.close };
+  const app = options.app ?? {};
+  const key = computeTemplateKey(modules, app, options.templateKey);
+  const openCopy = async (): Promise<TestDatabase> => {
+    const client = new PGlite({ loadDataDir: await getTemplate(key, modules, app, options.templateKey) });
+    const handle = await createPgliteHandle(client);
+    return { db: handle.db, client, close: handle.close };
+  };
+  return options.reuse === true ? acquirePooledDatabase(key, openCopy) : openCopy();
+}
+
+/** Closes the idle databases `reuse` keeps, so a test file can free them in `afterAll`. */
+export function closeReusedTestDatabases(): Promise<void> {
+  return closePooledDatabases();
 }
 
-function getTemplate(modules: readonly AnySoftureModule[], app: AppMigrations): Promise<Blob | File> {
+function computeTemplateKey(modules: readonly AnySoftureModule[], app: AppMigrations, templateKey: string | undefined): string {
   const moduleKey = modules.map((module) => `${module.id}@${module.migrations?.dir.href ?? "-"}`).join("|");
   const baselineKey = Object.entries(app.baseline ?? {}).sort(([left], [right]) => left.localeCompare(right)).map(([id, through]) => `${id}:${through}`).join(",");
-  const key = `${moduleKey}#before:${identifyHook(app.before)}#after:${identifyHook(app.after)}#baseline:${baselineKey}`;
+  return `${moduleKey}#before:${identifyHook(app.before)}#after:${identifyHook(app.after)}#baseline:${baselineKey}#key:${templateKey ?? "-"}`;
+}
+
+function getTemplate(key: string, modules: readonly AnySoftureModule[], app: AppMigrations, templateKey: string | undefined): Promise<Blob | File> {
   let template = templates.get(key);
   if (template === undefined) {
-    template = buildTemplate(modules, app);
+    template = loadOrBuildTemplate(modules, app, templateKey);
     templates.set(key, template);
     // A failed build is not cached: the next call reports the problem again.
     template.catch(() => templates.delete(key));
@@ -74,6 +104,22 @@ function identifyHook(hook: AppMigrationHook | undefined): string {
   return String(id);
 }
 
+// From the run's folder when another file already built it; otherwise built here and stored for the others.
+async function loadOrBuildTemplate(modules: readonly AnySoftureModule[], app: AppMigrations, templateKey: string | undefined): Promise<Blob | File> {
+  const dir = getTemplateDir();
+  const name = dir === null ? null : await computeTemplateName({ modules, app, templateKey });
+  if (dir === null || name === null) {
+    return buildTemplate(modules, app);
+  }
+  const stored = await readStoredTemplate(dir, name);
+  if (stored !== null) {
+    return stored;
+  }
+  const built = await buildTemplate(modules, app);
+  await storeTemplate(dir, name, built);
+  return built;
+}
+
 async function buildTemplate(modules: readonly AnySoftureModule[], app: AppMigrations): Promise<Blob | File> {
   const handle = await createPgliteHandle(new PGlite());
   try {