@flefebvre/prisma-test-helper 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Lefebvre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,297 @@
+# @flefebvre/prisma-test-helper
+
+An isolated, fast Postgres test database for Prisma + Vitest projects: one throwaway
+container per test run, migrations applied once to a Template Database, one Worker
+Database cloned per Vitest worker, and every test wrapped in a transaction that is rolled
+back.
+
+**Postgres-only.** The harness starts a real Postgres in Docker and relies on
+`CREATE DATABASE … TEMPLATE` for cloning; no other database is supported. Tested against
+**Prisma 7** and **Vitest 4** on **Node >= 20**.
+
+## What you get
+
+- **No cleanup code.** Each test runs inside a transaction that is rolled back when it
+  ends. The Worker Database never changes, so every test starts from the same pristine
+  clone — no truncation, no ordering constraints, no leftover rows.
+- **Real Postgres.** Not SQLite, not a mock. Your migrations, your constraints, your
+  triggers, your `citext` columns.
+- **Parallel by default.** One database per Vitest worker slot, so files running in
+  parallel cannot see each other's writes.
+- **Nothing to tear down.** The container is removed when the run ends, including after a
+  crash.
+
+## Requirements
+
+- Node >= 20, ESM project
+- Docker (or another container runtime Testcontainers can reach)
+- Peer dependencies: `vitest` ^4 and `prisma` ^7, with your migrations committed
+  (`prisma migrate deploy` is what the harness runs)
+
+## Install
+
+```sh
+pnpm add -D @flefebvre/prisma-test-helper
+# or: npm i -D / yarn add -D / bun add -d
+```
+
+## Wiring
+
+Five files. The blocks below are the wiring this repo's own test suite runs — see
+`prisma.config.ts`, `tests/global-setup.ts`, `tests/setup.ts`, `tests/db/client.ts`, and
+`vitest.config.ts`.
+
+### 1. Prisma config
+
+Prisma 7 reads the datasource URL from `prisma.config.ts`, not from the schema — and
+`prisma migrate deploy` **fails without it**. The harness runs your project's own
+`migrate deploy` with `DATABASE_URL` pointed at the throwaway container, so read it from
+the environment here. The placeholder keeps database-free commands (`prisma generate`)
+working.
+
+```ts
+// prisma.config.ts
+import { defineConfig } from "prisma/config";
+
+export default defineConfig({
+  schema: "prisma/schema.prisma",
+  migrations: { path: "prisma/migrations" },
+  datasource: {
+    url: process.env.DATABASE_URL ?? "postgresql://unset:unset@localhost:5432/unset",
+  },
+});
+```
+
+### 2. Your Prisma client module
+
+The harness assumes your app reaches the database through a single module it can
+intercept. If you already have one, use it as-is.
+
+```ts
+// src/db/client.ts
+import { PrismaPg } from "@prisma/adapter-pg";
+
+import { PrismaClient } from "../generated/prisma/client.js";
+
+const connectionString = process.env.DATABASE_URL;
+if (!connectionString) {
+  throw new Error("DATABASE_URL is not set");
+}
+
+export const db = new PrismaClient({ adapter: new PrismaPg({ connectionString }) });
+```
+
+The import path follows your own `generator client { output = … }` — adjust it to wherever
+your schema emits the client.
+
+Throwing when `DATABASE_URL` is unset is worth keeping. It is the tripwire for the
+ordering rule in step 4: if the setup file ever imports your app statically, this throw
+fires loudly instead of silently pointing the suite at your dev database.
+
+### 3. Global setup
+
+```ts
+// tests/global-setup.ts
+import { createGlobalSetup } from "@flefebvre/prisma-test-helper/global-setup";
+
+export default createGlobalSetup();
+```
+
+### 4. Per-worker setup
+
+```ts
+// tests/setup.ts
+import { vi } from "vitest";
+
+import { installTestTransaction } from "@flefebvre/prisma-test-helper";
+import { setupWorkerDatabase } from "@flefebvre/prisma-test-helper/setup";
+
+const { databaseUrl, databaseName } = setupWorkerDatabase();
+
+vi.mock("../src/db/client.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../src/db/client.js")>();
+  return { db: installTestTransaction(actual.db, databaseUrl, databaseName) };
+});
+```
+
+The factory returns `{ db }` because the client module above exports only `db`. If yours
+exports anything else — types, a re-exported `Prisma` namespace, helpers — spread the
+original too, or those exports become `undefined` at every call site:
+
+```ts
+return { ...actual, db: installTestTransaction(actual.db, databaseUrl, databaseName) };
+```
+
+> **This file must keep zero static imports of your app.** ES imports hoist above
+> statements, so a static `import { db } from "../src/db/client.js"` would build the
+> client _before_ `setupWorkerDatabase()` assigns `DATABASE_URL` — pointing your whole
+> suite at your dev database. Reach for app modules through the lazy `vi.mock` factory
+> (as above) or a dynamic `import()`. Library imports are safe: they read no environment
+> at import time.
+
+### 5. Vitest config
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globalSetup: ["tests/global-setup.ts"],
+    setupFiles: ["tests/setup.ts"],
+    // Both are Vitest defaults, set explicitly because the harness depends on them:
+    // together they re-run `setupFiles` in a fresh process per test file.
+    pool: "forks",
+    isolate: true,
+  },
+});
+```
+
+`pool: "forks"` and `isolate: true` are load-bearing. Under `isolate: false` module state
+leaks across files, and the `setupDatabase()` opt-in guard relies on its module
+re-instantiating per file.
+
+### Writing a test
+
+```ts
+// tests/author.test.ts
+import { expect, test } from "vitest";
+
+import { setupDatabase } from "@flefebvre/prisma-test-helper";
+import { db } from "../src/db/client.js";
+
+setupDatabase();
+
+test("persists an author", async () => {
+  await db.author.create({ data: { name: "Ada" } });
+  expect(await db.author.count()).toBe(1);
+});
+```
+
+`setupDatabase()` is the opt-in: call it once, at the top of any file that touches the
+database. Files that never call it are untouched by the harness.
+
+## What happens per run
+
+One tuned throwaway Postgres container starts (tmpfs data directory, `fsync=off`). Your
+project's `prisma migrate deploy` runs once against the **Template Database**. One
+**Worker Database** is cloned per Vitest worker slot (`<databaseName>_1..N`) before any
+worker forks. Each worker points `DATABASE_URL` at its own clone. Each test opens a
+transaction and rolls it back. The container is removed when the run ends.
+
+## API
+
+### `createGlobalSetup(options?)`
+
+| Option         | Default              | What it does                                                                                                                                       |
+| -------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `image`        | `postgres:17-alpine` | Postgres image to run. Pin it to the same major as your production database, so a test never runs against a different Postgres than you deploy on. |
+| `databaseName` | `prisma_test`        | Name of the Template Database: migrated once per run, then cloned into `<databaseName>_1..N`. It never hosts a test.                               |
+
+The Template Database connection URI is `provide`d to your tests, fully typed:
+
+```ts
+import { inject } from "vitest";
+
+const uri = inject("templateDatabaseUri");
+```
+
+Typing works only if your global-setup file is part of your TypeScript program — that
+file carries the module augmentation that declares these keys. If it sits outside
+`tsconfig.json`'s `include`, `inject("templateDatabaseUri")` will not typecheck.
+
+### `setupWorkerDatabase(): { databaseUrl, databaseName }`
+
+Points this worker at its own Worker Database. Call it at the top of your setup file,
+above the `vi.mock`. It reads what `createGlobalSetup` provided, rewrites the URI onto
+this worker's clone, sets `process.env.DATABASE_URL`, and returns both halves —
+`installTestTransaction` needs both.
+
+### `installTestTransaction(client, databaseUrl, databaseName): client`
+
+Wraps your real Prisma client and returns a routing proxy under the same type. Every
+importer of your client module receives it, so their queries land in whichever test
+transaction is live. Called once per worker, from the `vi.mock` factory.
+
+### `setupDatabase(): void`
+
+Opts a test file into the database. Wraps every test in its own transaction: a
+`beforeEach` opens it and runs the reset hooks, an `afterEach` rolls it back.
+
+### `isDatabaseSetUp(): boolean`
+
+Whether `setupDatabase()` has run in this file. Factories read it to fail loudly when a
+file forgot to opt in, rather than run outside any transaction — where their writes would
+commit.
+
+```ts
+if (!isDatabaseSetUp()) {
+  throw new Error("call setupDatabase() at the top of this test file");
+}
+```
+
+### `registerResetHook(hook): void`
+
+Register a callback to run in every `beforeEach`, after the transaction opens. This is the
+seam factories plug into. Hooks receive `{ testName, seed }`, where `seed` is a
+deterministic 32-bit hash (FNV-1a) of the test name alone — never the worker id, the file,
+or the run order. Rerunning one test with `-t` therefore hands it the same seed a
+full-suite run did.
+
+Faker is deliberately **not** a dependency of this package; the harness only hands you the
+seed.
+
+```ts
+// tests/factories.ts
+import { faker } from "@faker-js/faker";
+
+import { registerResetHook } from "@flefebvre/prisma-test-helper";
+import { db } from "../src/db/client.js";
+
+registerResetHook(({ seed }) => {
+  faker.seed(seed);
+});
+
+export function buildAuthor() {
+  return db.author.create({ data: { name: faker.person.fullName() } });
+}
+```
+
+Hooks are held in a `Set`, so registering the same function twice runs it once. They run
+sequentially, in registration order, and are awaited.
+
+## Rules and caveats
+
+**Per-test cleanup belongs in `afterEach`, registered after `setupDatabase()`.** Vitest
+runs `afterEach` hooks in reverse registration order, so one your file registers _after_
+that call still runs while the transaction is live. Cleanup registered with
+`onTestFinished` does **not**: the runner fires those after every `afterEach`, so they land
+past the rollback, where the database is out of reach.
+
+**Call `setupDatabase()` once per file.** A second call in the same file fails with
+`a test transaction is already live`, which does not point at the duplicate call.
+
+**Build test data inside tests, not in `beforeAll`.** `beforeAll` runs before any
+transaction is open, so writes there would commit to the Worker Database and leak into
+every later test. The harness throws rather than let that happen.
+
+## When something is mis-wired
+
+Every error below comes from this package. Find the one you got.
+
+| Error                                                                   | What is mis-wired                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `The test suite could not reach a container runtime.`                   | Docker is not running. Start it and run the tests again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ``Could not resolve the `prisma` CLI from <cwd>.``                      | The `prisma` peer dependency is not installed. The harness migrates with your project's own Prisma.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `` `prisma migrate deploy` failed: ``                                   | Your migrations failed to apply; Prisma's own output follows. If it reads `The datasource.url property is required in your Prisma config file`, you are missing the `prisma.config.ts` from step 1.                                                                                                                                                                                                                                                                                                                                    |
+| `cloning the Worker Databases from <name> failed:`                      | `CREATE DATABASE … TEMPLATE` failed — usually another connection to the template, or a Postgres image that does not support the clone.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `VITEST_POOL_ID is not set —`                                           | `setupWorkerDatabase()` ran outside a Vitest worker. It must run from a file listed in `setupFiles`, with `pool: "forks"` set.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `No Template Database was provided to this run —`                       | The global setup did not run. Register your global-setup file as `globalSetup: ["tests/global-setup.ts"]`.                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `refusing to open a test transaction on <name> — only Worker Databases` | Your client is pointed at something that is not a Worker Database — **check `<name>` in the message first**. If it is your dev database, the setup file's ordering broke: a static app import ran before `setupWorkerDatabase()` (see step 4). If it is the template, or a near-miss name, the `databaseName` passed to `installTestTransaction` does not match the one `createGlobalSetup` used — pass the value `setupWorkerDatabase()` returned. This guard is the last line stopping a suite from running against a real database. |
+| `no test transaction is installed —`                                    | Your client module was imported without going through the setup file's `vi.mock`. Check the mock path matches the import path your app uses.                                                                                                                                                                                                                                                                                                                                                                                           |
+| `a test transaction is already live —`                                  | `setupDatabase()` was called twice in one file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `the database was touched with no test transaction live —`              | The file never called `setupDatabase()`, or data was built in `beforeAll` instead of inside a test.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+
+## License
+
+MIT

package/dist/database.d.ts

@@ -0,0 +1,74 @@
+/** What every Reset Hook receives when it runs. */
+export interface ResetHookContext {
+    /** Vitest's name for the running test, describe blocks included. */
+    testName: string;
+    /**
+     * A deterministic 32-bit seed derived from `testName` alone — never from the worker
+     * id, the file, or the run order. Rerunning one test with `-t` therefore hands it the
+     * same seed the full-suite run did, so faker produces the same data both times.
+     */
+    seed: number;
+}
+/** A callback registered with {@link registerResetHook}. May be async; it is awaited. */
+export type ResetHook = (context: ResetHookContext) => void | Promise<void>;
+/**
+ * Whether {@link setupDatabase} has run in this test file.
+ *
+ * Factories read it to fail loudly when a file forgot to opt in, rather than run against
+ * an unseeded generator or — worse — outside any Test Transaction, where their writes
+ * would commit.
+ *
+ * @example
+ * if (!isDatabaseSetUp()) {
+ *   throw new Error("call setupDatabase() at the top of this test file");
+ * }
+ */
+export declare function isDatabaseSetUp(): boolean;
+/**
+ * Register a callback to run in every `beforeEach`, after the Test Transaction opens.
+ *
+ * This is the seam factories plug into: reset a per-test sequence counter, seed faker
+ * from `seed`, or anything else that must be fresh per test. Hooks are held in a Set, so
+ * registering the same function twice runs it once. The library itself never depends on
+ * faker — it only hands you the seed.
+ *
+ * @example
+ * registerResetHook(({ seed }) => {
+ *   faker.seed(seed);
+ *   nextId = 0;
+ * });
+ */
+export declare function registerResetHook(hook: ResetHook): void;
+/**
+ * Opt a test file into the database. Call it once, at the top of the file.
+ *
+ * Wraps every test in its own Test Transaction: a `beforeEach` opens it and runs the
+ * Reset Hooks; an `afterEach` rolls it back, discarding every write — the Worker
+ * Database itself never changes, so each test starts from the same pristine clone.
+ *
+ * Vitest runs `afterEach` hooks in reverse registration order (`sequence.hooks:
+ * "stack"`, the default), so an `afterEach` your file registers *after* this call — or
+ * one inside a nested `describe` — still runs while the transaction is live. Cleanup
+ * registered with `onTestFinished` does *not*: the runner fires those after every
+ * `afterEach`, so they land past the rollback, where the database is out of reach.
+ *
+ * @example
+ * import { setupDatabase } from "@flefebvre/prisma-test-helper";
+ * import { db } from "../src/db/client.js";
+ *
+ * setupDatabase();
+ *
+ * test("persists an author", async () => {
+ *   await db.author.create({ data: { name: "Ada" } });
+ *   expect(await db.author.count()).toBe(1);
+ * });
+ */
+export declare function setupDatabase(): void;
+/**
+ * FNV-1a, 32-bit — a small, fast, well-mixed string hash. Exported for its own unit
+ * test; consumers receive its result as `seed` rather than calling it.
+ *
+ * @example
+ * hashName("persists an author"); // → a stable uint32
+ */
+export declare function hashName(name: string): number;

package/dist/database.js

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, expect } from "vitest";
+import { testTransaction } from "./transaction.js";
+// Vitest isolates test files (`isolate: true`), so this module is re-instantiated per
+// file: the flag below resets for each, and hooks registered by one file's imports never
+// leak into another's.
+let databaseSetUp = false;
+/**
+ * Whether {@link setupDatabase} has run in this test file.
+ *
+ * Factories read it to fail loudly when a file forgot to opt in, rather than run against
+ * an unseeded generator or — worse — outside any Test Transaction, where their writes
+ * would commit.
+ *
+ * @example
+ * if (!isDatabaseSetUp()) {
+ *   throw new Error("call setupDatabase() at the top of this test file");
+ * }
+ */
+export function isDatabaseSetUp() {
+    return databaseSetUp;
+}
+const resetHooks = new Set();
+/**
+ * Register a callback to run in every `beforeEach`, after the Test Transaction opens.
+ *
+ * This is the seam factories plug into: reset a per-test sequence counter, seed faker
+ * from `seed`, or anything else that must be fresh per test. Hooks are held in a Set, so
+ * registering the same function twice runs it once. The library itself never depends on
+ * faker — it only hands you the seed.
+ *
+ * @example
+ * registerResetHook(({ seed }) => {
+ *   faker.seed(seed);
+ *   nextId = 0;
+ * });
+ */
+export function registerResetHook(hook) {
+    resetHooks.add(hook);
+}
+/**
+ * Opt a test file into the database. Call it once, at the top of the file.
+ *
+ * Wraps every test in its own Test Transaction: a `beforeEach` opens it and runs the
+ * Reset Hooks; an `afterEach` rolls it back, discarding every write — the Worker
+ * Database itself never changes, so each test starts from the same pristine clone.
+ *
+ * Vitest runs `afterEach` hooks in reverse registration order (`sequence.hooks:
+ * "stack"`, the default), so an `afterEach` your file registers *after* this call — or
+ * one inside a nested `describe` — still runs while the transaction is live. Cleanup
+ * registered with `onTestFinished` does *not*: the runner fires those after every
+ * `afterEach`, so they land past the rollback, where the database is out of reach.
+ *
+ * @example
+ * import { setupDatabase } from "@flefebvre/prisma-test-helper";
+ * import { db } from "../src/db/client.js";
+ *
+ * setupDatabase();
+ *
+ * test("persists an author", async () => {
+ *   await db.author.create({ data: { name: "Ada" } });
+ *   expect(await db.author.count()).toBe(1);
+ * });
+ */
+export function setupDatabase() {
+    databaseSetUp = true;
+    beforeEach(async () => {
+        await testTransaction().start();
+        const testName = expect.getState().currentTestName ?? "";
+        const seed = hashName(testName);
+        // Sequential, not Promise.all: hooks reset shared per-test state, and the order they
+        // were registered in is the order a consumer can reason about.
+        for (const hook of resetHooks)
+            await hook({ testName, seed });
+    });
+    afterEach(async () => {
+        await testTransaction().rollback();
+    });
+}
+/**
+ * FNV-1a, 32-bit — a small, fast, well-mixed string hash. Exported for its own unit
+ * test; consumers receive its result as `seed` rather than calling it.
+ *
+ * @example
+ * hashName("persists an author"); // → a stable uint32
+ */
+export function hashName(name) {
+    let hash = 2166136261;
+    for (let index = 0; index < name.length; index++) {
+        hash ^= name.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+}

package/dist/global-setup.d.ts

@@ -0,0 +1,78 @@
+import type { TestProject } from "vitest/node";
+declare module "vitest" {
+    interface ProvidedContext {
+        /** Connection URI of this run's container, pointing at the Template Database. */
+        templateDatabaseUri: string;
+        /**
+         * Name of the Template Database the Worker Databases were cloned from. Workers
+         * rewrite the URI path from it (`<databaseName>_<pool id>`) and the Test Transaction
+         * guard derives the shape it admits from it.
+         */
+        templateDatabaseName: string;
+    }
+}
+/** Options for {@link createGlobalSetup}. */
+export interface CreateGlobalSetupOptions {
+    /**
+     * Postgres image to run. Pin it to the same major as your production database, so a
+     * test never runs against a different Postgres than the one you deploy on.
+     * @default "postgres:17-alpine"
+     */
+    image?: string;
+    /**
+     * Name of the Template Database: migrated once per run, then cloned once per Vitest
+     * worker slot into the Worker Databases `<databaseName>_1..N`. It never hosts a test.
+     * @default "prisma_test"
+     */
+    databaseName?: string;
+}
+/**
+ * Build a Vitest `globalSetup` function: `export default createGlobalSetup()` from the
+ * file your `globalSetup` config points at.
+ *
+ * It runs once per test run, in the main process, before any worker is forked. It
+ * starts one throwaway Postgres on a random host port, migrates the Template Database
+ * with the consumer project's own `prisma migrate deploy`, and clones one Worker
+ * Database per worker slot: `<databaseName>_1..maxWorkers`. `VITEST_POOL_ID` is always
+ * within that range — the pool leases ids from a fixed `1..maxWorkers` map — so every
+ * fork finds its database already provisioned.
+ *
+ * The clones run here, in one psql invocation, while nothing else is connected to
+ * the template. `CREATE DATABASE … TEMPLATE` fails when the template has other
+ * connections (SQLSTATE 55006), which is why cloning from inside workers would
+ * need a lock; cloning before workers exist needs none.
+ */
+export declare function createGlobalSetup(options?: CreateGlobalSetupOptions): (project: TestProject) => Promise<() => Promise<void>>;
+/**
+ * How many Worker Databases to provision.
+ *
+ * `maxWorkers` is resolved lazily inside the pool, so at globalSetup time the config
+ * carries it only when set explicitly (config file or CLI). Without one, Vitest
+ * derives its worker count from `availableParallelism()` — minus one in run mode,
+ * halved in watch mode — so the undiminished value is an upper bound on every pool
+ * id in both modes, at the cost of spare clones: one in run mode, up to half the
+ * cores in watch mode. Vitest resolves `maxWorkers` with a truthy check — `0` means
+ * "unset", not "zero workers" — so this falls through on `0` the same way, or a
+ * `--maxWorkers=0` run would find no database provisioned. Exported for that test.
+ *
+ * @example
+ * workerCount(project); // 4 when maxWorkers is 4; availableParallelism() when unset or 0
+ */
+export declare function workerCount(project: TestProject): number;
+/**
+ * The psql argv that clones every Worker Database (`<databaseName>_1..workerCount`)
+ * from the template in a single invocation. Each clone is its own `--command` flag:
+ * psql runs a multi-statement `--command` in an implicit transaction, and
+ * `CREATE DATABASE` refuses to run inside one. `ON_ERROR_STOP` makes the first
+ * failed clone abort the invocation with a non-zero exit, since psql otherwise
+ * continues past errors and exits 0. Exported so the argv can be unit-tested
+ * without a container.
+ *
+ * @example
+ * cloneCommand("prisma_test", "postgres", 2)
+ * // → ["psql", "--username", "postgres", "--dbname", "postgres",
+ * //    "--set", "ON_ERROR_STOP=1",
+ * //    "--command", 'CREATE DATABASE "prisma_test_1" TEMPLATE "prisma_test"',
+ * //    "--command", 'CREATE DATABASE "prisma_test_2" TEMPLATE "prisma_test"']
+ */
+export declare function cloneCommand(databaseName: string, username: string, workerCount: number): string[];

package/dist/global-setup.js

@@ -0,0 +1,176 @@
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { PostgreSqlContainer } from "@testcontainers/postgresql";
+import { getContainerRuntimeClient } from "testcontainers";
+// initdb refuses a data directory it does not own, and a tmpfs mount is root-owned.
+// PGDATA must therefore be a subdirectory the container creates itself.
+const PGDATA_MOUNT = "/var/lib/postgresql/data";
+const PGDATA = `${PGDATA_MOUNT}/pgdata`;
+/**
+ * Build a Vitest `globalSetup` function: `export default createGlobalSetup()` from the
+ * file your `globalSetup` config points at.
+ *
+ * It runs once per test run, in the main process, before any worker is forked. It
+ * starts one throwaway Postgres on a random host port, migrates the Template Database
+ * with the consumer project's own `prisma migrate deploy`, and clones one Worker
+ * Database per worker slot: `<databaseName>_1..maxWorkers`. `VITEST_POOL_ID` is always
+ * within that range — the pool leases ids from a fixed `1..maxWorkers` map — so every
+ * fork finds its database already provisioned.
+ *
+ * The clones run here, in one psql invocation, while nothing else is connected to
+ * the template. `CREATE DATABASE … TEMPLATE` fails when the template has other
+ * connections (SQLSTATE 55006), which is why cloning from inside workers would
+ * need a lock; cloning before workers exist needs none.
+ */
+export function createGlobalSetup(options = {}) {
+    const { image = "postgres:17-alpine", databaseName = "prisma_test" } = options;
+    return async function setup(project) {
+        await assertDockerReachable();
+        const container = await new PostgreSqlContainer(image)
+            .withDatabase(databaseName)
+            .withEnvironment({ PGDATA })
+            .withTmpFs({ [PGDATA_MOUNT]: "rw,noexec,nosuid" })
+            .withCommand([
+            "postgres",
+            "-c",
+            "fsync=off",
+            "-c",
+            "synchronous_commit=off",
+            "-c",
+            "full_page_writes=off",
+        ])
+            .start();
+        try {
+            migrate(container.getConnectionUri());
+            await cloneWorkerDatabases(container, databaseName, workerCount(project));
+        }
+        catch (error) {
+            // A failed stop (e.g. the daemon died, failing migrate and stop alike) must not
+            // mask the diagnostic error being thrown; Ryuk reaps the container regardless.
+            await container.stop().catch(() => { });
+            throw error;
+        }
+        project.provide("templateDatabaseUri", container.getConnectionUri());
+        project.provide("templateDatabaseName", databaseName);
+        // Ryuk is the backstop: it removes the whole session even when Vitest is killed
+        // and this teardown never runs.
+        return async function teardown() {
+            await container.stop();
+        };
+    };
+}
+/**
+ * How many Worker Databases to provision.
+ *
+ * `maxWorkers` is resolved lazily inside the pool, so at globalSetup time the config
+ * carries it only when set explicitly (config file or CLI). Without one, Vitest
+ * derives its worker count from `availableParallelism()` — minus one in run mode,
+ * halved in watch mode — so the undiminished value is an upper bound on every pool
+ * id in both modes, at the cost of spare clones: one in run mode, up to half the
+ * cores in watch mode. Vitest resolves `maxWorkers` with a truthy check — `0` means
+ * "unset", not "zero workers" — so this falls through on `0` the same way, or a
+ * `--maxWorkers=0` run would find no database provisioned. Exported for that test.
+ *
+ * @example
+ * workerCount(project); // 4 when maxWorkers is 4; availableParallelism() when unset or 0
+ */
+export function workerCount(project) {
+    return project.config.maxWorkers || project.vitest.config.maxWorkers || os.availableParallelism();
+}
+/**
+ * Fail with an actionable message when no container runtime answers.
+ *
+ * Testcontainers tries each connection strategy in turn and reports only that they all
+ * failed, naming sockets rather than the missing dependency. Probing here separates
+ * "Docker is not running" — the one failure a reader is expected to hit and fix — from
+ * every other startup failure, which keeps its own error rather than being relabelled.
+ */
+async function assertDockerReachable() {
+    try {
+        await getContainerRuntimeClient();
+    }
+    catch (cause) {
+        throw new Error("The test suite could not reach a container runtime. " +
+            "@flefebvre/prisma-test-helper starts a Postgres container for the run, so " +
+            "Docker must be running — start Docker and run the tests again.", { cause });
+    }
+}
+/**
+ * Apply all migrations to this run's Template Database.
+ *
+ * Runs the consumer project's own `prisma` CLI — resolved from the working directory
+ * and executed with the current Node, so no package manager is involved — relying on
+ * Prisma's own schema discovery (`prisma.config.ts`, `./prisma/schema.prisma`, …).
+ * `DATABASE_URL` is pointed at the container for the child process only. Output is
+ * captured rather than inherited: a clean run should print nothing.
+ */
+function migrate(databaseUrl) {
+    const prismaBin = resolvePrismaBin();
+    try {
+        execFileSync(process.execPath, [prismaBin, "migrate", "deploy"], {
+            stdio: "pipe",
+            env: { ...process.env, DATABASE_URL: databaseUrl },
+        });
+    }
+    catch (cause) {
+        const output = cause && typeof cause === "object" && "stdout" in cause
+            ? String(cause.stdout ?? "") +
+                String(cause.stderr ?? "")
+            : "";
+        throw new Error(`\`prisma migrate deploy\` failed:\n${output}`, { cause });
+    }
+}
+/**
+ * Resolve the consumer's `prisma` CLI entry point (its published bin, exported as
+ * `prisma/build/index.js`), starting from the project that is running Vitest.
+ */
+function resolvePrismaBin() {
+    const require = createRequire(path.join(process.cwd(), "package.json"));
+    try {
+        return require.resolve("prisma/build/index.js");
+    }
+    catch (cause) {
+        throw new Error("Could not resolve the `prisma` CLI from " +
+            process.cwd() +
+            ". @flefebvre/prisma-test-helper migrates the Template Database with your " +
+            "project's own Prisma — install the `prisma` package (it is a peer " +
+            "dependency) and run the tests again.", { cause });
+    }
+}
+/**
+ * The psql argv that clones every Worker Database (`<databaseName>_1..workerCount`)
+ * from the template in a single invocation. Each clone is its own `--command` flag:
+ * psql runs a multi-statement `--command` in an implicit transaction, and
+ * `CREATE DATABASE` refuses to run inside one. `ON_ERROR_STOP` makes the first
+ * failed clone abort the invocation with a non-zero exit, since psql otherwise
+ * continues past errors and exits 0. Exported so the argv can be unit-tested
+ * without a container.
+ *
+ * @example
+ * cloneCommand("prisma_test", "postgres", 2)
+ * // → ["psql", "--username", "postgres", "--dbname", "postgres",
+ * //    "--set", "ON_ERROR_STOP=1",
+ * //    "--command", 'CREATE DATABASE "prisma_test_1" TEMPLATE "prisma_test"',
+ * //    "--command", 'CREATE DATABASE "prisma_test_2" TEMPLATE "prisma_test"']
+ */
+export function cloneCommand(databaseName, username, workerCount) {
+    const argv = ["psql", "--username", username, "--dbname", "postgres", "--set", "ON_ERROR_STOP=1"];
+    for (let workerId = 1; workerId <= workerCount; workerId++) {
+        argv.push("--command", `CREATE DATABASE "${databaseName}_${workerId}" TEMPLATE "${databaseName}"`);
+    }
+    return argv;
+}
+/**
+ * Clone the migrated template into the Worker Databases, via `psql` inside the
+ * container — over the local socket, which the official image trusts, so no
+ * client library or credentials are involved. One exec covers every clone: the
+ * exec round-trip costs more than the clone itself.
+ */
+async function cloneWorkerDatabases(postgres, databaseName, workerCount) {
+    const { exitCode, output } = await postgres.exec(cloneCommand(databaseName, postgres.getUsername(), workerCount));
+    if (exitCode !== 0) {
+        throw new Error(`cloning the Worker Databases from ${databaseName} failed:\n${output}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { installTestTransaction } from "./transaction.js";
+export type { MinimalClient, MinimalTransactionClient } from "./transaction.js";
+export { isDatabaseSetUp, registerResetHook, setupDatabase } from "./database.js";
+export type { ResetHook, ResetHookContext } from "./database.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// Main entry: what a consumer's test setup file and their test files import. The engine
+// internals (`TestTransaction`, `testTransaction`, `assertWorkerDatabase`, `hashName`)
+// stay off the public surface — the harness's own wiring drives them.
+export { installTestTransaction } from "./transaction.js";
+export { isDatabaseSetUp, registerResetHook, setupDatabase } from "./database.js";

package/dist/setup.d.ts

@@ -0,0 +1,43 @@
+/** What {@link setupWorkerDatabase} hands back: everything the Client Seam needs. */
+export interface WorkerDatabase {
+    /** Connection URL of this worker's Worker Database — also set as `DATABASE_URL`. */
+    databaseUrl: string;
+    /** The Template Database name it was cloned from, for the Test Transaction guard. */
+    databaseName: string;
+}
+/**
+ * Point this worker at its own Worker Database.
+ *
+ * Call it at the top of your Vitest setup file, above the `vi.mock` that installs the
+ * Client Seam. It reads what `createGlobalSetup` provided, rewrites the URI onto this
+ * worker's clone (`<databaseName>_<VITEST_POOL_ID>`), sets `process.env.DATABASE_URL`,
+ * and returns both halves — the URL and the template name — because
+ * `installTestTransaction` needs both.
+ *
+ * **Ordering matters.** The assignment below must happen before any module that reads
+ * `DATABASE_URL` at import time is loaded, and ES imports hoist above statements — so
+ * the setup file must keep *zero* static imports of your app, and reach for them with a
+ * dynamic `import()` (or a lazy `vi.mock` factory) instead. A single static app import
+ * would parse the environment against your dev `DATABASE_URL` and point the whole suite
+ * at your dev database.
+ *
+ * @example
+ * // test/setup.ts
+ * const { databaseUrl, databaseName } = setupWorkerDatabase();
+ *
+ * vi.mock("../src/db/client", async (importOriginal) => {
+ *   const actual = await importOriginal<typeof import("../src/db/client")>();
+ *   return { db: installTestTransaction(actual.db, databaseUrl, databaseName) };
+ * });
+ */
+export declare function setupWorkerDatabase(): WorkerDatabase;
+/**
+ * Swap the database in a connection URI for this worker's clone, keeping everything
+ * else — credentials, host, port, query parameters — untouched. Exported so the rewrite
+ * can be unit-tested without a container.
+ *
+ * @example
+ * workerDatabaseUrl("postgresql://u:p@host:5432/prisma_test", "prisma_test", "1");
+ * // → "postgresql://u:p@host:5432/prisma_test_1"
+ */
+export declare function workerDatabaseUrl(templateUri: string, databaseName: string, poolId: string): string;

package/dist/setup.js

@@ -0,0 +1,62 @@
+import { inject } from "vitest";
+/**
+ * Point this worker at its own Worker Database.
+ *
+ * Call it at the top of your Vitest setup file, above the `vi.mock` that installs the
+ * Client Seam. It reads what `createGlobalSetup` provided, rewrites the URI onto this
+ * worker's clone (`<databaseName>_<VITEST_POOL_ID>`), sets `process.env.DATABASE_URL`,
+ * and returns both halves — the URL and the template name — because
+ * `installTestTransaction` needs both.
+ *
+ * **Ordering matters.** The assignment below must happen before any module that reads
+ * `DATABASE_URL` at import time is loaded, and ES imports hoist above statements — so
+ * the setup file must keep *zero* static imports of your app, and reach for them with a
+ * dynamic `import()` (or a lazy `vi.mock` factory) instead. A single static app import
+ * would parse the environment against your dev `DATABASE_URL` and point the whole suite
+ * at your dev database.
+ *
+ * @example
+ * // test/setup.ts
+ * const { databaseUrl, databaseName } = setupWorkerDatabase();
+ *
+ * vi.mock("../src/db/client", async (importOriginal) => {
+ *   const actual = await importOriginal<typeof import("../src/db/client")>();
+ *   return { db: installTestTransaction(actual.db, databaseUrl, databaseName) };
+ * });
+ */
+export function setupWorkerDatabase() {
+    const poolId = process.env.VITEST_POOL_ID;
+    if (!poolId) {
+        throw new Error("VITEST_POOL_ID is not set — @flefebvre/prisma-test-helper could not tell which " +
+            "Worker Database belongs to this worker. `setupWorkerDatabase()` must run inside " +
+            'a Vitest worker, from a file listed in `setupFiles`, with `pool: "forks"` set ' +
+            "in your Vitest config.");
+    }
+    // Typed as `string`, but `inject` is a plain lookup in the context the main process
+    // provided: an unregistered globalSetup yields `undefined` at runtime, not an error.
+    const templateUri = inject("templateDatabaseUri");
+    const databaseName = inject("templateDatabaseName");
+    if (!templateUri || !databaseName) {
+        throw new Error("No Template Database was provided to this run — @flefebvre/prisma-test-helper's " +
+            "global setup did not run. Add a global-setup file exporting " +
+            "`createGlobalSetup()` and register it in your Vitest config as " +
+            '`globalSetup: ["test/global-setup.ts"]`.');
+    }
+    const databaseUrl = workerDatabaseUrl(templateUri, databaseName, poolId);
+    process.env.DATABASE_URL = databaseUrl;
+    return { databaseUrl, databaseName };
+}
+/**
+ * Swap the database in a connection URI for this worker's clone, keeping everything
+ * else — credentials, host, port, query parameters — untouched. Exported so the rewrite
+ * can be unit-tested without a container.
+ *
+ * @example
+ * workerDatabaseUrl("postgresql://u:p@host:5432/prisma_test", "prisma_test", "1");
+ * // → "postgresql://u:p@host:5432/prisma_test_1"
+ */
+export function workerDatabaseUrl(templateUri, databaseName, poolId) {
+    const url = new URL(templateUri);
+    url.pathname = `/${databaseName}_${poolId}`;
+    return url.toString();
+}

package/dist/transaction.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The transaction-side surface the engine drives directly: savepoints are raw SQL. Any
+ * interactive-transaction client exposing `$executeRawUnsafe` qualifies — a generated
+ * `Prisma.TransactionClient` does.
+ */
+export interface MinimalTransactionClient {
+    $executeRawUnsafe(query: string, ...values: unknown[]): Promise<unknown>;
+}
+/**
+ * The client-side surface the engine drives directly: opening the one interactive
+ * transaction it parks per test. Declared with method syntax so the check is bivariant —
+ * a generated `PrismaClient`, whose callback receives its own richer transaction client,
+ * is assignable.
+ */
+export interface MinimalClient {
+    $transaction(fn: (tx: MinimalTransactionClient) => Promise<unknown>, options?: {
+        maxWait?: number;
+        timeout?: number;
+    }): Promise<unknown>;
+}
+/**
+ * Guard the entry to every Test Transaction. A throwaway container is not enough: if the
+ * `DATABASE_URL` wiring in the consumer's setup file ever fails, a client still points at
+ * the dev database and every test would run its transaction there. Only Worker Databases
+ * — named `<databaseName>_<pool id>` after the Template Database they were cloned from —
+ * may host one: even a rolled-back transaction advances sequences and takes locks, so the
+ * template and the dev database are refused. The name is matched literally (no regex
+ * built from config). Exported so it can be unit-tested without a real connection to a
+ * wrongly-named database.
+ */
+export declare function assertWorkerDatabase(url: string, databaseName: string): void;
+/**
+ * Build the worker's engine around the real client and hand back its Routing Proxy —
+ * what every importer of the consumer's client module receives instead of the raw
+ * client, under the same type. Called once per worker, from the `vi.mock` block in the
+ * consumer's test setup file.
+ *
+ * `databaseName` is the Template Database name the Worker Database was cloned from
+ * (the `databaseName` given to `createGlobalSetup`, `"prisma_test"` by default); the
+ * guard derives the accepted `<databaseName>_<pool id>` shape from it.
+ */
+export declare function installTestTransaction<Client extends MinimalClient>(prisma: Client, databaseUrl: string, databaseName: string): Client;
+/** The engine `installTestTransaction` built for this worker. */
+export declare function testTransaction(): TestTransaction<MinimalClient>;
+/**
+ * One test's database transaction. `start()` opens an interactive transaction and parks
+ * it; `client` is a stand-in for the app's Prisma client that routes every query into
+ * the parked transaction *at call time* — so a delegate captured at import (a factory's
+ * `db.user`) still lands inside whichever transaction is live when the query actually
+ * runs; `rollback()` ends the transaction, discarding every write.
+ *
+ * @example
+ * const engine = new TestTransaction(prisma, databaseUrl, "prisma_test");
+ * await engine.start();
+ * await engine.client.user.create({ data: … }); // inside the transaction
+ * await engine.rollback(); // gone
+ */
+export declare class TestTransaction<Client extends MinimalClient> {
+    private readonly prisma;
+    private readonly databaseUrl;
+    private readonly databaseName;
+    private tx;
+    private release;
+    private running;
+    private savepointSeq;
+    private mutex;
+    private readonly inSavepoint;
+    constructor(prisma: Client, databaseUrl: string, databaseName: string);
+    /** Open the transaction and park it until `rollback()`. Refuses a non-worker database. */
+    start(): Promise<void>;
+    /**
+     * End the transaction, discarding its writes. A no-op when none is live. State resets
+     * before the transaction's own error (if any) surfaces, so a transaction that died
+     * mid-test fails that test alone instead of wedging the engine.
+     */
+    rollback(): Promise<void>;
+    private reset;
+    private proxy;
+    /**
+     * The Routing Proxy: a drop-in for the app's Prisma client. Model delegates and
+     * raw-query methods route into the live transaction at call time; everything else
+     * passes through to the underlying client. One stable object — consumers may capture
+     * it, or any of its delegates, once and forever.
+     */
+    get client(): Client;
+    private requireTx;
+    /**
+     * Run `op` inside its own savepoint on the live transaction: released on success,
+     * rolled back — restoring a healthy transaction — when `op` throws. Scopes queue on
+     * the mutex; a scope opened from *inside* another (nested `$transaction`) joins the
+     * outer scope's turn, since Postgres savepoints nest natively.
+     */
+    private withSavepoint;
+    private savepointScope;
+    /**
+     * A stand-in for one model delegate (`db.user`). Method calls resolve the live
+     * transaction when invoked, which is what makes eagerly captured delegates safe.
+     */
+    private routeDelegate;
+}

package/dist/transaction.js

@@ -0,0 +1,240 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * Guard the entry to every Test Transaction. A throwaway container is not enough: if the
+ * `DATABASE_URL` wiring in the consumer's setup file ever fails, a client still points at
+ * the dev database and every test would run its transaction there. Only Worker Databases
+ * — named `<databaseName>_<pool id>` after the Template Database they were cloned from —
+ * may host one: even a rolled-back transaction advances sequences and takes locks, so the
+ * template and the dev database are refused. The name is matched literally (no regex
+ * built from config). Exported so it can be unit-tested without a real connection to a
+ * wrongly-named database.
+ */
+export function assertWorkerDatabase(url, databaseName) {
+    const name = new URL(url).pathname.slice(1);
+    const prefix = `${databaseName}_`;
+    const workerId = name.startsWith(prefix) ? name.slice(prefix.length) : "";
+    if (!/^\d+$/.test(workerId)) {
+        throw new Error(`refusing to open a test transaction on ${name} — only Worker Databases ` +
+            `(${prefix}<pool id>) may host one`);
+    }
+}
+// The worker's one engine, installed by the consumer's module mock (the Client Seam)
+// when the first import of their client module resolves, and driven per-test by the
+// harness: `start()` before each test, `rollback()` after.
+let current = null;
+/**
+ * Build the worker's engine around the real client and hand back its Routing Proxy —
+ * what every importer of the consumer's client module receives instead of the raw
+ * client, under the same type. Called once per worker, from the `vi.mock` block in the
+ * consumer's test setup file.
+ *
+ * `databaseName` is the Template Database name the Worker Database was cloned from
+ * (the `databaseName` given to `createGlobalSetup`, `"prisma_test"` by default); the
+ * guard derives the accepted `<databaseName>_<pool id>` shape from it.
+ */
+export function installTestTransaction(prisma, databaseUrl, databaseName) {
+    const engine = new TestTransaction(prisma, databaseUrl, databaseName);
+    current = engine;
+    return engine.client;
+}
+/** The engine `installTestTransaction` built for this worker. */
+export function testTransaction() {
+    if (!current) {
+        throw new Error("no test transaction is installed — the app's Prisma client module was not " +
+            "imported through the test setup's module mock");
+    }
+    return current;
+}
+// Thrown into the parked transaction callback to end it; `start()` recognises it as the
+// one expected way the transaction ends, so real errors still surface.
+class Rollback extends Error {
+}
+// Raw-query methods route into the live transaction like model delegates do; the
+// remaining `$`-methods (`$connect`, `$disconnect`, `$on`, `$extends`, …) are
+// connection-level and pass through to the underlying client.
+const RAW_METHODS = new Set(["$queryRaw", "$queryRawUnsafe", "$executeRaw", "$executeRawUnsafe"]);
+/**
+ * One test's database transaction. `start()` opens an interactive transaction and parks
+ * it; `client` is a stand-in for the app's Prisma client that routes every query into
+ * the parked transaction *at call time* — so a delegate captured at import (a factory's
+ * `db.user`) still lands inside whichever transaction is live when the query actually
+ * runs; `rollback()` ends the transaction, discarding every write.
+ *
+ * @example
+ * const engine = new TestTransaction(prisma, databaseUrl, "prisma_test");
+ * await engine.start();
+ * await engine.client.user.create({ data: … }); // inside the transaction
+ * await engine.rollback(); // gone
+ */
+export class TestTransaction {
+    prisma;
+    databaseUrl;
+    databaseName;
+    tx = null;
+    release = null;
+    running = null;
+    savepointSeq = 0;
+    // Serializes savepoint scopes: they share one connection and Postgres savepoints are
+    // stack-like, so two interleaved scopes would corrupt each other's rollback.
+    mutex = Promise.resolve();
+    // Marks "inside a savepoint scope" across awaits, so a $transaction nested within
+    // another joins the outer scope's turn instead of deadlocking on the mutex.
+    inSavepoint = new AsyncLocalStorage();
+    constructor(prisma, databaseUrl, databaseName) {
+        this.prisma = prisma;
+        this.databaseUrl = databaseUrl;
+        this.databaseName = databaseName;
+    }
+    /** Open the transaction and park it until `rollback()`. Refuses a non-worker database. */
+    async start() {
+        assertWorkerDatabase(this.databaseUrl, this.databaseName);
+        if (this.running) {
+            throw new Error("a test transaction is already live — `start()` must be paired with a `rollback()`");
+        }
+        let ready;
+        const isReady = new Promise((resolve) => (ready = resolve));
+        this.running = this.prisma
+            .$transaction(async (tx) => {
+            this.tx = tx;
+            ready();
+            // Park until `rollback()` rejects with `Rollback`. The timeout only bounds a
+            // transaction whose `rollback()` never came — a leaked one — so it is far
+            // above any test's runtime.
+            await new Promise((_, reject) => {
+                this.release = () => reject(new Rollback());
+            });
+        }, { maxWait: 5_000, timeout: 3_600_000 })
+            .catch((error) => {
+            if (!(error instanceof Rollback))
+                throw error;
+        });
+        // `running` settles first only when the transaction failed to open (e.g. the pool
+        // handed out a dead connection); racing it turns that failure into a loud `start()`
+        // rejection instead of a hang on `isReady`. The reset keeps the failure to this one
+        // test — leaving state behind would make every later `start()` claim a transaction
+        // is live when none is.
+        try {
+            await Promise.race([isReady, this.running]);
+        }
+        catch (error) {
+            this.reset();
+            throw error;
+        }
+    }
+    /**
+     * End the transaction, discarding its writes. A no-op when none is live. State resets
+     * before the transaction's own error (if any) surfaces, so a transaction that died
+     * mid-test fails that test alone instead of wedging the engine.
+     */
+    async rollback() {
+        const running = this.running;
+        this.release?.();
+        this.reset();
+        if (running)
+            await running;
+    }
+    reset() {
+        this.tx = null;
+        this.release = null;
+        this.running = null;
+        this.savepointSeq = 0;
+        this.mutex = Promise.resolve();
+    }
+    proxy = null;
+    /**
+     * The Routing Proxy: a drop-in for the app's Prisma client. Model delegates and
+     * raw-query methods route into the live transaction at call time; everything else
+     * passes through to the underlying client. One stable object — consumers may capture
+     * it, or any of its delegates, once and forever.
+     */
+    get client() {
+        return (this.proxy ??= new Proxy(this.prisma, {
+            get: (target, prop) => {
+                if (prop === "$transaction") {
+                    return (arg) => {
+                        this.requireTx();
+                        if (typeof arg === "function") {
+                            return this.withSavepoint(() => arg(this.tx));
+                        }
+                        // The batch form: its operations were built through this client, so awaiting
+                        // them runs them on the live transaction; the savepoint makes the batch
+                        // atomic, and sequential awaiting keeps the order.
+                        return this.withSavepoint(async () => {
+                            const results = [];
+                            for (const operation of arg) {
+                                results.push(await operation);
+                            }
+                            return results;
+                        });
+                    };
+                }
+                if (typeof prop === "string" && RAW_METHODS.has(prop)) {
+                    return (...args) => {
+                        const tx = this.requireTx();
+                        return tx[prop](...args);
+                    };
+                }
+                if (typeof prop === "string" && !prop.startsWith("$")) {
+                    const value = Reflect.get(target, prop);
+                    if (value !== null && typeof value === "object") {
+                        return this.routeDelegate(prop);
+                    }
+                }
+                const value = Reflect.get(target, prop);
+                return typeof value === "function" ? value.bind(target) : value;
+            },
+        }));
+    }
+    requireTx() {
+        if (!this.tx) {
+            throw new Error("the database was touched with no test transaction live — call `setupDatabase()` " +
+                "at the top of the test file, and build test data inside tests, not in `beforeAll`");
+        }
+        return this.tx;
+    }
+    /**
+     * Run `op` inside its own savepoint on the live transaction: released on success,
+     * rolled back — restoring a healthy transaction — when `op` throws. Scopes queue on
+     * the mutex; a scope opened from *inside* another (nested `$transaction`) joins the
+     * outer scope's turn, since Postgres savepoints nest natively.
+     */
+    async withSavepoint(op) {
+        if (this.inSavepoint.getStore())
+            return this.savepointScope(op);
+        const run = this.mutex.then(() => this.inSavepoint.run(true, () => this.savepointScope(op)));
+        this.mutex = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async savepointScope(op) {
+        const tx = this.requireTx();
+        const name = `test_savepoint_${++this.savepointSeq}`;
+        await tx.$executeRawUnsafe(`SAVEPOINT ${name}`);
+        try {
+            const result = await op();
+            await tx.$executeRawUnsafe(`RELEASE SAVEPOINT ${name}`);
+            return result;
+        }
+        catch (error) {
+            await tx.$executeRawUnsafe(`ROLLBACK TO SAVEPOINT ${name}`);
+            throw error;
+        }
+    }
+    /**
+     * A stand-in for one model delegate (`db.user`). Method calls resolve the live
+     * transaction when invoked, which is what makes eagerly captured delegates safe.
+     */
+    routeDelegate(model) {
+        const source = this.prisma;
+        return new Proxy(source[model], {
+            get: (target, method) => {
+                const value = Reflect.get(target, method);
+                if (typeof value !== "function")
+                    return value;
+                return (...args) => {
+                    const delegate = this.requireTx();
+                    return delegate[model][method](...args);
+                };
+            },
+        });
+    }
+}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@flefebvre/prisma-test-helper",
+  "version": "0.1.0",
+  "description": "Throwaway-Postgres test harness for Prisma + Vitest: one container per run, one database per worker. Postgres-only.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Florian Lefebvre <florian.lefebvre.contact@gmail.com>",
+  "homepage": "https://github.com/flolefebvre/prisma-test-helper#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flolefebvre/prisma-test-helper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/flolefebvre/prisma-test-helper/issues"
+  },
+  "keywords": [
+    "prisma",
+    "vitest",
+    "postgres",
+    "testcontainers",
+    "testing",
+    "test-database",
+    "isolation"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./global-setup": {
+      "types": "./dist/global-setup.d.ts",
+      "default": "./dist/global-setup.js"
+    },
+    "./setup": {
+      "types": "./dist/setup.d.ts",
+      "default": "./dist/setup.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "generate": "prisma generate",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "lint": "eslint --max-warnings 0",
+    "duplicates": "jscpd",
+    "format": "prettier -w .",
+    "format:check": "prettier -c .",
+    "gate": "pnpm run typecheck && pnpm run lint && pnpm run duplicates && pnpm run test && pnpm run build",
+    "prepublishOnly": "pnpm run clean && pnpm run build"
+  },
+  "dependencies": {
+    "@testcontainers/postgresql": "^12.0.4",
+    "testcontainers": "^12.0.4"
+  },
+  "peerDependencies": {
+    "prisma": "^7.0.0",
+    "vitest": "^4.0.0"
+  },
+  "devDependencies": {
+    "@prisma/adapter-pg": "^7.8.0",
+    "@prisma/client": "^7.8.0",
+    "@types/node": "^20.19.43",
+    "eslint": "^10.6.0",
+    "jscpd": "^5.0.12",
+    "prettier": "^3.9.4",
+    "prisma": "^7.8.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.62.0",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}