@softure-ai/db 0.1.11 → 0.1.13

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":"AA0CA,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;AAEtC,MAAM,cAAc,GAAG,mIAAmI,CAAC;AAE3J,wHAAwH;AACxH,MAAM,eAAe,GAAG;;;;;0EAKkD,cAAc;;;yEAGf,cAAc;;;iFAGN,cAAc;;;;;kHAKmB,cAAc;UACtH,CAAC;AAEX,MAAM,UAAU,GAAG;;;;;yCAKsB,cAAc;WAC5C,CAAC;AAEZ,MAAM,aAAa,GAAG;;+EAEyD,CAAC;AAEhF,MAAM,qBAAqB,GAAG,mIAAmI,CAAC;AAElK;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAW,EAAE,IAAmC;IAC1F,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,KAAK,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,KAAK,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QAC5E,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAClF,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,IAAI,CAAC,KAAK,KAAK,oBAAoB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAClD,MAAM,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACpB,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,oHAAoH;AACpH,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,OAAO;QAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,OAAO,CAAC,GAAW;IAC1B,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QACxD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,IAAI,CAAC,IAAU,EAAE,QAAwB;IAChD,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,UAAU,EAAE,CAAC;gBACf,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;YAC3B,CAAC;YACD,UAAU,GAAG,IAAI,CAAC;YAClB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;YAC1B,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAC,MAAc;IAChD,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,KAAK,CAA6E,UAAU,CAAC,CAAC;IAC7H,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,KAAK,MAAM,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;QACtC,IAAI,QAAQ,CAAC,IAAI,KAAK,GAAG,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YACvD,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,KAAK,CAAwB,gCAAgC,QAAQ,CAAC,IAAI,eAAe,CAAC,CAAC;QACxH,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,OAAO,kBAAkB,CAAC,CAAC;YAChG,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,oDAAoD,QAAQ,CAAC,IAAI,mBAAmB,CAAC,CAAC;YACxG,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,KAAK,CAAgB,aAAa,CAAC,CAAC;IACnE,OAAO;QACL,WAAW;QACX,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;QACnG,KAAK;QACL,SAAS,EAAE,SAAS,CAAC,IAAI;QACzB,iBAAiB,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,GAAG,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;KACrI,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,MAAc;IAC3C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAA0B,eAAe,CAAC,CAAC;IAC5E,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,UAAU,CAAC,MAAc,EAAE,KAAoB;IAC5D,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC;YAC1D,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YACpC,+EAA+E;YAC/E,MAAM,EAAE,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;YAC9D,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5B,MAAM,EAAE,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/D,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBAC/B,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,OAAO,oBAAoB,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YACnG,CAAC;YACD,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC/B,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAC3E,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;gBAC3C,MAAM,EAAE,CAAC,IAAI,CAAC,6BAA6B,IAAI,EAAE,CAAC,CAAC;YACrD,CAAC;QACH,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,kHAAkH;QAClH,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

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":"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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.11",
+  "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/index.ts

@@ -40,7 +40,7 @@ export {
   type MigrationReport,
   type MigrationStep,
 } from "./migrations/migrator.js";
-export { drizzleAppMigrations } from "./migrations/drizzle.js";
+export { drizzleAppMigrations, type DrizzleAppMigrationsOptions } 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

@@ -1,22 +1,61 @@
 // 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";
 
+export interface DrizzleAppMigrationsOptions {
+  /** drizzle's ledger table for this folder. Default: `__drizzle_migrations`. */
+  readonly migrationsTable?: string;
+  /** The schema of that table. Default: `drizzle`. */
+  readonly migrationsSchema?: string;
+}
+
+const DEFAULT_TABLE = "__drizzle_migrations";
+const DEFAULT_SCHEMA = "drizzle";
+
+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
- * 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.
+ * files) with drizzle's migrator. Drizzle skips what its ledger (`drizzle.__drizzle_migrations` unless `options`
+ * names another) already holds, so the hook is safe on every `migrate` run. Drizzle reads only the newest row of the
+ * ledger, so a second folder needs a ledger of its own. `folder` is a path (relative to the working directory) or a
+ * file URL.
  */
-export function drizzleAppMigrations(folder: string | URL): AppMigrationHook {
+export function drizzleAppMigrations(folder: string | URL, options: DrizzleAppMigrationsOptions = {}): AppMigrationHook {
   const migrationsFolder = typeof folder === "string" ? folder : fileURLToPath(folder);
-  return async (handle) => {
+  const config = {
+    migrationsFolder,
+    migrationsTable: options.migrationsTable ?? DEFAULT_TABLE,
+    migrationsSchema: options.migrationsSchema ?? DEFAULT_SCHEMA,
+  };
+  const hook: AppMigrationHook = async (handle) => {
     if (handle.kind === "postgres") {
       const { migrate } = await import("drizzle-orm/node-postgres/migrator");
-      await migrate(handle.db, { migrationsFolder });
+      await migrate(handle.db, config);
       return;
     }
     const { migrate } = await import("drizzle-orm/pglite/migrator");
-    await migrate(handle.db, { migrationsFolder });
+    await migrate(handle.db, config);
   };
+  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 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/migrations/migrator.ts

@@ -6,6 +6,7 @@
 // `app.baseline` names the module files the app's own history already creates (issue #152).
 import { ok, sortModulesByDependencies, type AnySoftureModule } from "@softure-ai/core";
 import type { DatabaseHandle } from "../client.js";
+import { getDrizzleLedger } from "./drizzle.js";
 import { applyFile, describeError, recordAdoption, withMigrationLock, type MigrationUnit } from "./apply.js";
 import { readMigrationFiles } from "./files.js";
 import { describeSchema, diffSchemas } from "./introspect.js";
@@ -98,7 +99,7 @@ export async function planMigrations(handle: DatabaseHandle, options: MigrateOpt
     return units;
   }
   const baseline = options.app?.baseline ?? {};
-  const baselineProblems = checkBaseline(options.modules, units.value, baseline);
+  const baselineProblems = [...checkAppHooks(options.app ?? {}), ...checkBaseline(options.modules, units.value, baseline)];
   if (baselineProblems.length > 0) {
     return failWith(baselineProblems);
   }
@@ -122,7 +123,7 @@ export async function migrate(handle: DatabaseHandle, options: MigrateOptions):
   }
   const app = options.app ?? {};
   const baseline = app.baseline ?? {};
-  const baselineProblems = checkBaseline(options.modules, units.value, baseline);
+  const baselineProblems = [...checkAppHooks(app), ...checkBaseline(options.modules, units.value, baseline)];
   if (baselineProblems.length > 0) {
     return failWith(baselineProblems);
   }
@@ -246,6 +247,16 @@ function checkBaseline(
   });
 }
 
+/**
+ * `before` and `after` must not be drizzle hooks on one ledger: drizzle applies only files newer than the ledger's
+ * newest row, so every `after` file older than the newest `before` file would be skipped silently (issue #534).
+ */
+function checkAppHooks(app: AppMigrations): MigrationProblem[] {
+  const before = app.before === undefined ? undefined : getDrizzleLedger(app.before);
+  const after = app.after === undefined ? undefined : getDrizzleLedger(app.after);
+  return before !== undefined && before === after ? [{ code: "db.app_migrations_shared_ledger", ledger: before }] : [];
+}
+
 /** `through` must be a whole number from 1 to the unit's file count. */
 export function checkThrough(unit: MigrationUnit, through: number): MigrationProblem[] {
   const files = unit.files.length;

package/src/migrations/problems.ts

@@ -11,6 +11,7 @@ export type MigrationProblem =
   | { readonly code: "db.migration_out_of_order"; readonly module: string; readonly version: number; readonly appliedVersion: number }
   | { readonly code: "db.migration_failed"; readonly module: string; readonly version: number; readonly name: string; readonly reason: string }
   | { readonly code: "db.app_migration_failed"; readonly phase: "before" | "after"; readonly reason: string }
+  | { readonly code: "db.app_migrations_shared_ledger"; readonly ledger: string }
   | { readonly code: "db.reserved_module"; readonly module: string }
   | { readonly code: "db.migrations_without_schema"; readonly module: string }
   | { readonly code: "db.dependency_cycle"; readonly modules: readonly string[] }
@@ -60,6 +61,12 @@ export function describeProblem(problem: MigrationProblem): string {
       return problem.phase === "before"
         ? `app: the before migrations failed: ${problem.reason}; no module migration ran`
         : `app: the after migrations failed: ${problem.reason}; the module migrations before it stay applied`;
+    case "db.app_migrations_shared_ledger":
+      return (
+        `app: the before and after drizzle migrations share the ledger ${problem.ledger}, so drizzle would skip every ` +
+        "after file older than the newest before file; give the after folder its own ledger " +
+        '(drizzleAppMigrations(folder, { migrationsTable: "__drizzle_migrations_after" }))'
+      );
     case "db.reserved_module":
       return `${problem.module}: uses a reserved id or schema (the id "softure"; the schemas softure, public, information_schema, drizzle, pg_* and names over 63 bytes)`;
     case "db.migrations_without_schema":

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 });
+  };
+}