@rvoh/dream 2.13.0 → 2.14.0-beta.1

package/dist/esm/src/db/testDatabasePool.js

@@ -0,0 +1,182 @@
+/**
+ * Per-live-worker test-database pool. Each worker claims a free database from a
+ * pre-created pool by holding a process-lifetime, auto-releasing lock; the
+ * adapter-specific lock primitive lives behind the query-driver seam
+ * ({@link TestDatabaseLockSession}), so this module stays driver-agnostic.
+ *
+ * ## Why this exists
+ *
+ * Under vitest (`pool: 'forks'`, `isolate: true`) `VITEST_POOL_ID` is a
+ * *reusable slot id* (1..maxWorkers) that vitest frees and reassigns across
+ * worker processes. vitest does not await `runner.stop()` before reusing a
+ * slot, so a retired-but-still-terminating worker overlaps the new worker that
+ * reused its slot. When the test database is keyed off that reusable slot
+ * (`<base>_<VITEST_POOL_ID>`), the two overlapping processes share one
+ * database, and the newcomer's `beforeEach(truncate)` wipes the other's
+ * in-flight rows -> records vanish mid-test -> intermittent failures.
+ *
+ * ## The fix
+ *
+ * Tie database ownership to *process liveness* instead of vitest's slot
+ * accounting. Each live worker claims a free database from a pre-created pool
+ * by taking a lock on a dedicated, long-lived connection (the
+ * {@link TestDatabaseLockSession}, supplied by the default connection's query
+ * driver). The lock auto-releases the instant the worker's connection drops on
+ * process exit, so a reused vitest slot can never collide: the new worker
+ * probes for and claims a *different* free database, and only ever reuses an
+ * index whose previous owner has genuinely exited.
+ *
+ * The pool is `<base>` (index 1, unsuffixed) plus `<base>_2 .. <base>_K`,
+ * pre-created at `db:migrate` / `db:reset` time as `TEMPLATE <base>` clones.
+ * Pool size `K = 2 * max(1, parallelTests) + margin` covers N active workers
+ * plus up to N still-terminating workers, with margin for transient overlap.
+ *
+ * The lock primitive itself — and its key derivation — is the driver's
+ * concern: Postgres maps `(namespace, index)` to a two-`int4` advisory lock,
+ * MySQL to a `GET_LOCK` name. This orchestrator only ever speaks the neutral
+ * `(namespace, index)` contract.
+ */
+// Extra databases beyond `2 * max(1, parallelTests)` to absorb transient
+// overlap (e.g. several workers terminating at once on a slow machine).
+const POOL_MARGIN = 2;
+// How long to keep re-probing for a free database when every pool index is
+// momentarily claimed, before failing loud. A lingering worker's lock frees
+// within milliseconds of its process exiting, so this only ever waits out a
+// brief handoff window.
+const WAIT_FOR_FREE_TIMEOUT_MS = 5_000;
+const WAIT_FOR_FREE_POLL_INTERVAL_MS = 50;
+// Module-level singleton: one per Node process === one per vitest worker. A
+// fresh worker process starts with a clean slate and claims its own index.
+const state = {
+    index: null,
+    claimPromise: null,
+    lockSession: null,
+};
+/**
+ * The number of databases in the pre-created pool (including the unsuffixed
+ * base at index 1). Shared by the CLI pool-creation / drop loops and the claim
+ * probe so they always agree on the index range.
+ */
+export function testDatabasePoolSize(parallelTests) {
+    const n = typeof parallelTests === 'number' && Number.isFinite(parallelTests) && parallelTests > 0
+        ? Math.floor(parallelTests)
+        : 1;
+    return 2 * Math.max(1, n) + POOL_MARGIN;
+}
+/**
+ * The database name for a pool index given the un-suffixed base name. Index 1
+ * is the base itself (no suffix); higher indexes are `<base>_<index>`. This is
+ * the single naming rule, used by both the claim path and the CLI loops.
+ */
+export function testDatabaseNameForIndex(baseName, index) {
+    return index <= 1 ? baseName : `${baseName}_${index}`;
+}
+/**
+ * Sync read of the already-claimed pool index, or null if no claim has
+ * completed yet in this process. `DreamApp.dbName()` (synchronous, called when
+ * Kysely builds a pool) relies on the claim having been awaited earlier in the
+ * worker — `DreamApp.init()` awaits {@link claimTestDatabase} before the first
+ * connection is built, and `truncate` awaits it too — so by the time any
+ * connection resolves its database name the index is populated.
+ */
+export function claimedTestDatabaseIndexOrNull() {
+    return state.index;
+}
+function delay(ms) {
+    return new Promise(resolve => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+/**
+ * Claim a free pool database for this worker (idempotent). On first call it
+ * opens the default driver's dedicated lock session, probes
+ * {@link TestDatabaseLockSession.tryAcquire} across the pool indexes until one
+ * succeeds, and caches the claimed index for the rest of the process.
+ * Subsequent calls (and concurrent callers) return the same index.
+ *
+ * Throws a loud, actionable error if the pool is genuinely exhausted after the
+ * wait-for-free window — telling the reader to recreate the pool with
+ * `<packageManager> psy db:reset`.
+ */
+export async function claimTestDatabase(dreamApp) {
+    if (state.index !== null)
+        return state.index;
+    if (state.claimPromise)
+        return state.claimPromise;
+    state.claimPromise = performClaim(dreamApp);
+    try {
+        state.index = await state.claimPromise;
+        return state.index;
+    }
+    finally {
+        state.claimPromise = null;
+    }
+}
+async function performClaim(dreamApp) {
+    const creds = dreamApp.dbCredentialsFor('default')?.primary ?? dreamApp.dbCredentialsFor('default')?.replica;
+    if (!creds?.name)
+        throw new Error('[dream] cannot claim a test database: the "default" connection has no resolvable primary db name');
+    // The base db name doubles as the lock namespace: the driver hashes it into
+    // its own lock key so two apps sharing one server reserve disjoint indexes.
+    const baseName = creds.name;
+    const poolSize = testDatabasePoolSize(dreamApp.parallelTests);
+    const driver = dreamApp.dbConnectionQueryDriverClass('default');
+    const session = await driver.openTestDatabaseLockSession('default');
+    state.lockSession = session;
+    const deadline = nowMs() + WAIT_FOR_FREE_TIMEOUT_MS;
+    for (;;) {
+        for (let index = 1; index <= poolSize; index++) {
+            if (await session.tryAcquire(baseName, index))
+                return index;
+        }
+        if (nowMs() >= deadline)
+            break;
+        await delay(WAIT_FOR_FREE_POLL_INTERVAL_MS);
+    }
+    // Genuine exhaustion: every pool index is held and none freed within the
+    // wait window. Fail loud with concrete remediation rather than hanging or
+    // silently sharing a database.
+    await session.release().catch(() => undefined);
+    state.lockSession = null;
+    throw new Error(`[dream] test-database pool exhausted: all ${poolSize} databases in the "${baseName}" ` +
+        `pool are claimed by live workers and none freed within ${WAIT_FOR_FREE_TIMEOUT_MS}ms. ` +
+        `This usually means the pool is undersized for the current parallelism, or stale locks are ` +
+        `lingering. Recreate the pool with:\n\n    ${dbResetCommand(dreamApp)}\n\n` +
+        `If it recurs under heavy parallelism, raise DREAM_PARALLEL_TESTS (which widens the pool).`);
+}
+function dbResetCommand(dreamApp) {
+    switch (dreamApp.packageManager) {
+        case 'npm':
+            return 'npm run psy db:reset';
+        case 'yarn':
+            return 'yarn psy db:reset';
+        case 'bun':
+            return 'bun run psy db:reset';
+        case 'deno':
+            return 'deno task psy db:reset';
+        case 'pnpm':
+        default:
+            return 'pnpm psy db:reset';
+    }
+}
+function nowMs() {
+    // Date.now() rather than performance.now(); we only need coarse wall-clock
+    // for the wait-for-free deadline.
+    return Date.now();
+}
+/**
+ * Test-only escape hatch for dream's own spec suite: release the claim and
+ * close the lock session so a test can exercise the claim machinery in
+ * isolation. Not part of the public API.
+ *
+ * @internal
+ */
+export async function __resetTestDatabaseClaimForSpec() {
+    const session = state.lockSession;
+    state.index = null;
+    state.claimPromise = null;
+    state.lockSession = null;
+    if (session)
+        await session.release().catch(() => undefined);
+}

package/dist/esm/src/dream/QueryDriver/Base.js

@@ -164,6 +164,35 @@ export default class QueryDriverBase {
     static async setDatabaseTypeParsers(connectionName) { }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     static async duplicateDatabase(connectionName) { }
+    /**
+     * @internal
+     *
+     * Whether this driver implements the per-worker test-database claim seam
+     * ({@link openTestDatabaseLockSession}). Adapters that can hold a
+     * process-lifetime, auto-releasing lock to reserve one database from the
+     * test pool override this to `true`. It defaults to `false` so that a new
+     * adapter fails loud under vitest rather than silently sharing a single
+     * database across overlapping workers — see `src/db/testDatabasePool.ts`.
+     */
+    static supportsParallelTestDatabases = false;
+    /**
+     * @internal
+     *
+     * Open a dedicated, process-lifetime lock session used to claim one database
+     * from the per-worker test pool. Only ever called when
+     * {@link supportsParallelTestDatabases} is `true`; the base default throws.
+     *
+     * The returned session wraps a single dedicated connection: the orchestrator
+     * (`src/db/testDatabasePool.ts`) probes many pool indexes on the one session
+     * via `tryAcquire` and keeps whichever it acquires, holding it for the
+     * worker's lifetime.
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    static async openTestDatabaseLockSession(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    connectionName) {
+        throw new Error('override openTestDatabaseLockSession in child class');
+    }
     // eslint-disable-next-line @typescript-eslint/require-await
     static async getColumnData(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars

package/dist/esm/src/dream/QueryDriver/Kysely.js

@@ -1007,7 +1007,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 joinAndStatements: query['innerJoinAndStatements'],
                 dreamClass: query['dreamClass'],
                 // As recursivelyJoin progresses through the chain of associations that
-                // the developer has inclued in a join statement (e.g. `leftJoinPreload('hello as ho', 'world as wd')`),
+                // the developer has included in a join statement (e.g. `leftJoinPreload('hello as ho', 'world as wd')`),
                 // previousTableAlias will be modified so that the join statement can properly reference
                 // what we are joining on. When an `associationQuery` is the start of a join, then `baseSqlAlias` is set,
                 // this is passed into the very beginning of recursivelyJoin.
@@ -1022,7 +1022,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 joinAndStatements: query['leftJoinAndStatements'],
                 dreamClass: query['dreamClass'],
                 // As recursivelyJoin progresses through the chain of associations that
-                // the developer has inclued in a join statement (e.g. `leftJoinPreload('hello as ho', 'world as wd')`),
+                // the developer has included in a join statement (e.g. `leftJoinPreload('hello as ho', 'world as wd')`),
                 // previousTableAlias will be modified so that the join statement can properly reference
                 // what we are joining on. When an `associationQuery` is the start of a join, then `baseSqlAlias` is set,
                 // this is passed into the very beginning of recursivelyJoin.
@@ -1367,6 +1367,19 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     namespaceColumn(column, alias = this.query['baseSqlAlias']) {
         return namespaceColumn(column, alias);
     }
+    /**
+     * @internal
+     *
+     * Builds the table expression passed to Kysely's `innerJoin`/`leftJoin` for an
+     * association. When the alias already snakeifies to the table name, Kysely's
+     * CamelCasePlugin emits the correct identifier from the alias alone, so no
+     * explicit `as` clause is needed; otherwise we join the table aliased as `alias`.
+     *
+     * @returns A table expression string, e.g. `"beautiful_balloons as balloon"`
+     */
+    aliasedJoinTableExpression(tableName, alias) {
+        return snakeify(alias) === tableName ? alias : `${tableName} as ${alias}`;
+    }
     checkForQueryViolations() {
         const invalidWhereNotClauses = this.similarityStatementBuilder().whereNotStatementsWithSimilarityClauses();
         if (invalidWhereNotClauses.length) {
@@ -1502,12 +1515,19 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      */
     joinsBridgeThroughAssociations({ query, dreamClassTheAssociationIsDefinedOn, throughAssociation, 
     /**
-     * If the join statement includes an explicit alias, e.g.,
-     * `leftJoinPreload('hello as ho', 'world as wd')`
-     * then explicitAlias is set (e.g., to 'ho' the first time that `recursivelyJoin`
-     * calls this method and to 'ho' the second time `recursivelyJoin` is called)
-     * If only implicit aliasing happens (based on association name)
-     * (e.g. `leftJoinPreload('hello', 'world')`), then explicitAlias is null
+     * The table alias to use for the association being joined.
+     *
+     * When the join statement includes an explicit alias, e.g.
+     * `leftJoinPreload('hello as ho', 'world as wd')`, explicitAlias is that
+     * alias ('ho' for `hello`, 'wd' for `world`).
+     *
+     * When no explicit alias is given (e.g. `leftJoinPreload('hello', 'world')`),
+     * `recursivelyJoin` passes the association name itself ('hello', 'world') as
+     * the alias, so explicitAlias is still defined.
+     *
+     * explicitAlias is only `undefined` for the intermediate join tables that
+     * `joinsBridgeThroughAssociations` synthesizes while bridging a `through`
+     * association — those tables are never aliased by the developer.
      */
     explicitAlias, 
     /**
@@ -1628,12 +1648,19 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     }
     applyOneJoin({ query, dreamClass, association, 
     /**
-     * If the join statement includes an explicit alias, e.g.,
-     * `leftJoinPreload('hello as ho', 'world as wd')`
-     * then explicitAlias is set (e.g., to 'ho' the first time that `recursivelyJoin`
-     * calls this method and to 'ho' the second time `recursivelyJoin` is called)
-     * If only implicit aliasing happens (based on association name)
-     * (e.g. `leftJoinPreload('hello', 'world')`), then explicitAlias is null
+     * The table alias to use for the association being joined.
+     *
+     * When the join statement includes an explicit alias, e.g.
+     * `leftJoinPreload('hello as ho', 'world as wd')`, explicitAlias is that
+     * alias ('ho' for `hello`, 'wd' for `world`).
+     *
+     * When no explicit alias is given (e.g. `leftJoinPreload('hello', 'world')`),
+     * `recursivelyJoin` passes the association name itself ('hello', 'world') as
+     * the alias, so explicitAlias is still defined.
+     *
+     * explicitAlias is only `undefined` for the intermediate join tables that
+     * `joinsBridgeThroughAssociations` synthesizes while bridging a `through`
+     * association — those tables are never aliased by the developer.
      */
     explicitAlias, 
     /**
@@ -1672,12 +1699,19 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     }
     addAssociationJoinStatementToQuery({ query, dreamClass, association, 
     /**
-     * If the join statement includes an explicit alias, e.g.,
-     * `leftJoinPreload('hello as ho', 'world as wd')`
-     * then explicitAlias is set (e.g., to 'ho' the first time that `recursivelyJoin`
-     * calls this method and to 'ho' the second time `recursivelyJoin` is called)
-     * If only implicit aliasing happens (based on association name)
-     * (e.g. `leftJoinPreload('hello', 'world')`), then explicitAlias is null
+     * The table alias to use for the association being joined.
+     *
+     * When the join statement includes an explicit alias, e.g.
+     * `leftJoinPreload('hello as ho', 'world as wd')`, explicitAlias is that
+     * alias ('ho' for `hello`, 'wd' for `world`).
+     *
+     * When no explicit alias is given (e.g. `leftJoinPreload('hello', 'world')`),
+     * `recursivelyJoin` passes the association name itself ('hello', 'world') as
+     * the alias, so explicitAlias is still defined.
+     *
+     * explicitAlias is only `undefined` for the intermediate join tables that
+     * `joinsBridgeThroughAssociations` synthesizes while bridging a `through`
+     * association — those tables are never aliased by the developer.
      */
     explicitAlias, 
     /**
@@ -1714,7 +1748,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     leftJoinStatements: this.query['leftJoinStatements'],
                 });
             const to = (dreamClassThroughAssociationWantsToHydrate ?? association.modelCB()).table;
-            const joinTableExpression = snakeify(currentTableAlias) === to ? currentTableAlias : `${to} as ${currentTableAlias}`;
+            const joinTableExpression = this.aliasedJoinTableExpression(to, currentTableAlias);
             query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
                 join = join.onRef(this.namespaceColumn(association.foreignKey(), previousTableAlias), '=', this.namespaceColumn(association.primaryKey(undefined, {
                     associatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
@@ -1747,7 +1781,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         }
         else {
             const to = association.modelCB().table;
-            const joinTableExpression = snakeify(currentTableAlias) === to ? currentTableAlias : `${to} as ${currentTableAlias}`;
+            const joinTableExpression = this.aliasedJoinTableExpression(to, currentTableAlias);
             query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
                 join = join.onRef(this.namespaceColumn(association.primaryKey(), previousTableAlias), '=', this.namespaceColumn(association.foreignKey(), currentTableAlias));
                 if (association.polymorphic) {

package/dist/esm/src/dream/QueryDriver/Postgres.js

@@ -13,12 +13,35 @@ import { isPrimitiveDataType } from '../../db/dataTypes.js';
 import DreamApp from '../../dream-app/index.js';
 import camelize from '../../helpers/camelize.js';
 import { findCitextArrayOid, findCorrespondingArrayOid, findEnumArrayOids, parsePostgresBigint, parsePostgresDate, parsePostgresDatetime, parsePostgresDatetimeTz, parsePostgresDecimal, parsePostgresTime, parsePostgresTimeTz, } from '../../helpers/customPgParsers.js';
+import { testDatabasePoolSize } from '../../db/testDatabasePool.js';
 import EnvInternal from '../../helpers/EnvInternal.js';
 import createDb from './helpers/pg/createDb.js';
 import _dropDb from './helpers/pg/dropDb.js';
 import loadPgClient from './helpers/pg/loadPgClient.js';
 import KyselyQueryDriver from './Kysely.js';
 const pgTypes = pg.types;
+// Fixed dream-pool namespace constant for the advisory-lock `key1`. Chosen to
+// sit high in the int4 range and be recognizable in `pg_locks` (classid/objid)
+// when debugging. XORed with a per-namespace hash below so two apps sharing one
+// Postgres cluster reserve disjoint index spaces.
+const DREAM_TEST_POOL_LOCK_NAMESPACE = 0x44_52_4d_00 | 0; // "DRM\0"
+// Aggressive TCP keepalive on the dedicated lock-holding connection. Insurance
+// for remote / CI Postgres and abrupt kills where a FIN might be lost: it lets
+// Postgres reap the dead backend (and release the lock) even when the OS never
+// delivered a clean socket close. For a local kill the lock releases on EOF
+// regardless of this.
+const LOCK_CONNECTION_KEEPALIVE_INITIAL_DELAY_MS = 1_000;
+function int32Hash(value) {
+    let hash = 0;
+    for (let i = 0; i < value.length; i++) {
+        hash = (Math.imul(hash, 31) + value.charCodeAt(i)) | 0;
+    }
+    return hash;
+}
+function advisoryLockKey1(namespace) {
+    // Stays within int4 via the `| 0` coercions.
+    return (DREAM_TEST_POOL_LOCK_NAMESPACE ^ int32Hash(namespace)) | 0;
+}
 export default class PostgresQueryDriver extends KyselyQueryDriver {
     /**
      * create the database. Must respond to the NODE_ENV value.
@@ -161,7 +184,12 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
             await client.query(`DROP DATABASE IF EXISTS ${replicaTestWorkerDatabaseName};`);
             await client.query(`CREATE DATABASE ${replicaTestWorkerDatabaseName} TEMPLATE ${dbConf.name};`);
         }
-        for (let i = 2; i <= parallelTests; i++) {
+        // The pool spans `<base>` (the migration template, also claimable) plus
+        // `<base>_2 .. <base>_K`. Each live test worker claims one member for its
+        // lifetime via an advisory lock, so the pool must be wide enough to cover
+        // active + still-terminating workers — see src/db/testDatabasePool.ts.
+        const poolSize = testDatabasePoolSize(parallelTests);
+        for (let i = 2; i <= poolSize; i++) {
             const workerDatabaseName = `${dbConf.name}_${i}`;
             DreamCLI.logger.logContinueProgress(`creating duplicate test database ${workerDatabaseName} for concurrent tests...`, { logPrefix: '  ├ [db]', logPrefixColor: 'greenBright' });
             await client.query(`DROP DATABASE IF EXISTS ${workerDatabaseName};`);
@@ -170,4 +198,51 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
         await client.end();
         DreamCLI.logger.logEndProgress();
     }
+    static supportsParallelTestDatabases = true;
+    /**
+     * @internal
+     *
+     * Postgres implementation of the per-worker test-database claim seam (see
+     * {@link TestDatabaseLockSession} and `src/db/testDatabasePool.ts`).
+     *
+     * Postgres advisory locks are global to the cluster (not scoped to a single
+     * database), so one dedicated connection — to the `postgres` maintenance
+     * database — can reserve a pool index for the whole cluster. We use the
+     * two-`int4` form `pg_try_advisory_lock(key1, key2)`, whose lock space is
+     * distinct from the single-`bigint` form `pg_advisory_lock(bigint)` that
+     * application code typically uses, so a claim can never clash with an
+     * app-level advisory lock. `key1` folds a hash of the lock namespace (the
+     * base database name) into a fixed dream-pool constant; `key2` is the pool
+     * index. The lock auto-releases when the connection drops on process exit.
+     */
+    static async openTestDatabaseLockSession(connectionName) {
+        const dreamApp = DreamApp.getOrFail();
+        const creds = dreamApp.dbCredentialsFor(connectionName)?.primary ?? dreamApp.dbCredentialsFor(connectionName)?.replica;
+        if (!creds?.name)
+            throw new Error(`[dream] cannot open a test-database lock session: the "${connectionName}" connection has no resolvable primary db name`);
+        const client = new pg.Client({
+            host: creds.host || 'localhost',
+            port: creds.port,
+            // The maintenance database always exists and we never lock it —
+            // advisory locks are cluster-wide.
+            database: 'postgres',
+            user: creds.user,
+            password: creds.password,
+            keepAlive: true,
+            keepAliveInitialDelayMillis: LOCK_CONNECTION_KEEPALIVE_INITIAL_DELAY_MS,
+        });
+        await client.connect();
+        return {
+            async tryAcquire(namespace, index) {
+                const result = await client.query('SELECT pg_try_advisory_lock($1::int4, $2::int4) AS locked', [
+                    advisoryLockKey1(namespace),
+                    index,
+                ]);
+                return result.rows[0]?.locked === true;
+            },
+            async release() {
+                await client.end().catch(() => undefined);
+            },
+        };
+    }
 }

package/dist/esm/src/dream/QueryDriver/helpers/pg/dropDb.js

@@ -1,4 +1,5 @@
 import DreamCLI from '../../../../cli/index.js';
+import { testDatabasePoolSize } from '../../../../db/testDatabasePool.js';
 import DreamApp from '../../../../dream-app/index.js';
 import EnvInternal from '../../../../helpers/EnvInternal.js';
 import loadPgClient from './loadPgClient.js';
@@ -25,7 +26,8 @@ async function maybeDropDuplicateDatabases(client, dbName) {
         DreamCLI.logger.logContinueProgress(`dropping fake replica test database ${replicaTestWorkerDatabaseName}`, { logPrefix: '  ├ [db]', logPrefixColor: 'greenBright' });
         await client.query(`DROP DATABASE IF EXISTS ${replicaTestWorkerDatabaseName};`);
     }
-    for (let i = 2; i <= parallelTests; i++) {
+    const poolSize = testDatabasePoolSize(parallelTests);
+    for (let i = 2; i <= poolSize; i++) {
         const workerDatabaseName = `${dbName}_${i}`;
         DreamCLI.logger.logContinueProgress(`dropping duplicate test database ${workerDatabaseName}`, {
             logPrefix: '  ├ [db]',

package/dist/esm/src/dream-app/index.js

@@ -1,4 +1,5 @@
 import * as util from 'node:util';
+import { claimedTestDatabaseIndexOrNull, claimTestDatabase, testDatabaseNameForIndex, } from '../db/testDatabasePool.js';
 import validateTable from '../db/validators/validateTable.js';
 import Query from '../dream/Query.js';
 import PostgresQueryDriver from '../dream/QueryDriver/Postgres.js';
@@ -47,8 +48,12 @@ export default class DreamApp {
         if (!dreamApp.serializers)
             setCachedSerializers({});
         cacheDreamApp(dreamApp);
-        if (!opts.bypassDbConnectionsDuringInit)
+        if (!opts.bypassDbConnectionsDuringInit) {
+            // Claim this worker's pool database before any connection is built, so
+            // the synchronous dbName() always resolves to the claimed database.
+            await dreamApp.ensureTestDatabaseClaimed();
             await this.setDatabaseTypeParsers(dreamApp);
+        }
         await deferCb?.(dreamApp);
         for (const plugin of dreamApp.plugins) {
             await plugin(dreamApp);
@@ -289,9 +294,56 @@ A new key can also be generated from the CLI:
     get serializers() {
         return getSerializersOrFail();
     }
+    /**
+     * The database name to connect to for a given connection. In dev/prod this is
+     * simply the configured name. Under vitest (test env) it is the per-worker
+     * database claimed from the pool — see {@link testDatabaseClaimEnabled} and
+     * `src/db/testDatabasePool.ts`.
+     *
+     * This is synchronous because Kysely builds its `pg.Pool` synchronously. It
+     * reads the already-claimed pool index; the claim is awaited earlier in the
+     * worker — `DreamApp.init()` calls {@link claimTestDatabase} before the first
+     * connection is built, and `dream-spec-helpers`' `truncate` awaits
+     * {@link testDatabaseName} — so the index is always populated by the time any
+     * connection resolves its name.
+     */
     dbName(connectionName, connection) {
         const conf = this.dbConnectionConfig(connectionName, connection);
-        return this.parallelDatabasesEnabled ? `${conf.name}_${process.env.VITEST_POOL_ID}` : conf.name;
+        if (!this.runtimeNeedsTestDatabaseClaim)
+            return conf.name;
+        this.requireTestDatabaseClaimSupport();
+        const index = claimedTestDatabaseIndexOrNull();
+        if (index === null)
+            throw new Error(`[dream] dbName("${connectionName}", "${connection}") was resolved before this worker claimed ` +
+                `a test database. The pool claim must be awaited first (DreamApp.init / truncate do this). ` +
+                `This indicates a database connection was opened before app initialization completed.`);
+        return testDatabaseNameForIndex(conf.name, index);
+    }
+    /**
+     * Single source of truth for the claimed test-database name, used both by
+     * dream's connection resolution and by `dream-spec-helpers`' `truncate`
+     * (which opens its own `pg.Client` and so must read — not recompute — the
+     * claim). Awaits the pool claim if it has not happened yet in this worker.
+     */
+    async testDatabaseName(connectionName, connection) {
+        const conf = this.dbConnectionConfig(connectionName, connection);
+        if (!this.runtimeNeedsTestDatabaseClaim)
+            return conf.name;
+        this.requireTestDatabaseClaimSupport();
+        const index = await claimTestDatabase(this);
+        return testDatabaseNameForIndex(conf.name, index);
+    }
+    /**
+     * Claim this worker's pool database if it hasn't been claimed yet. Idempotent
+     * and a no-op outside the test-under-vitest path. Called by `DreamApp.init()`
+     * before any connection is built so the synchronous {@link dbName} always
+     * sees a populated index.
+     */
+    async ensureTestDatabaseClaimed() {
+        if (!this.runtimeNeedsTestDatabaseClaim)
+            return;
+        this.requireTestDatabaseClaimSupport();
+        await claimTestDatabase(this);
     }
     dbConnectionConfig(connectionName, connection) {
         const conf = this.dbCredentialsFor(connectionName)?.[connection] || this.dbCredentialsFor(connectionName)?.primary;
@@ -322,10 +374,57 @@ A new key can also be generated from the CLI:
     hasReplicaConfig(connectionName) {
         return !!this.dbCredentials[connectionName]?.replica;
     }
-    get parallelDatabasesEnabled() {
-        return (!!this.parallelTests &&
-            !Number.isNaN(Number(process.env.VITEST_POOL_ID)) &&
-            Number(process.env.VITEST_POOL_ID) > 1);
+    /**
+     * Whether the runtime *requires* a per-worker test-database claim. Gated on
+     * test env *under vitest* (not on `parallelTests > 1`): the slot-reuse
+     * collision reproduces even serially, because vitest respawns a process per
+     * file and the lingering process overlaps the new one on the same database.
+     * CLI db tasks (`db:migrate`, `db:reset`, …) do not run under vitest, so they
+     * keep the unsuffixed name and operate on the whole pool explicitly.
+     *
+     * This is independent of whether the default driver can actually claim — when
+     * the need is present but the capability is absent, the claim path fails loud
+     * (see {@link requireTestDatabaseClaimSupport}) rather than silently sharing
+     * one database.
+     */
+    get runtimeNeedsTestDatabaseClaim() {
+        return EnvInternal.isTest && runningUnderVitest();
+    }
+    /**
+     * Whether the default connection's query driver implements the per-worker
+     * test-database claim seam (`openTestDatabaseLockSession`). The claim is keyed
+     * off the **default** connection's capability so a Postgres-default app with a
+     * MySQL secondary keeps working (the secondary borrows the Postgres-claimed
+     * index for its database name).
+     */
+    get defaultConnectionSupportsParallelTestDatabases() {
+        return this.dbConnectionQueryDriverClass('default').supportsParallelTestDatabases;
+    }
+    /**
+     * Whether the per-worker test-database pool claim is active: needed by the
+     * runtime *and* supported by the default connection's driver. Consumers that
+     * key behavior off the claimed index (connection-cache suffixing) use this;
+     * the claim entry points additionally fail loud when the need is present but
+     * support is absent.
+     */
+    get testDatabaseClaimEnabled() {
+        return this.runtimeNeedsTestDatabaseClaim && this.defaultConnectionSupportsParallelTestDatabases;
+    }
+    /**
+     * Throw an actionable error when the runtime needs a per-worker test-database
+     * claim but the default connection's driver cannot provide one — rather than
+     * silently sharing a single database across overlapping vitest workers (which
+     * reintroduces the flake this whole mechanism exists to fix).
+     */
+    requireTestDatabaseClaimSupport() {
+        if (this.defaultConnectionSupportsParallelTestDatabases)
+            return;
+        const driverName = this.dbConnectionQueryDriverClass('default').name;
+        throw new Error(`[dream] running under vitest requires a per-worker test database, but the "default" connection's ` +
+            `query driver (${driverName}) does not support parallel test databases. Implement the claim seam ` +
+            `on that driver — set \`supportsParallelTestDatabases = true\` and override ` +
+            `\`openTestDatabaseLockSession\` (see PostgresQueryDriver / the test-app MysqlQueryDriver for ` +
+            `reference) — or do not run this adapter under vitest.`);
     }
     async load(resourceType, resourcePath, importCb) {
         switch (resourceType) {
@@ -436,6 +535,14 @@ function loggerArgToString(arg) {
     }
     return JSON.stringify(util.inspect(arg, { depth: 6 }));
 }
+/**
+ * Whether the current process is a vitest worker. vitest sets `VITEST=true` in
+ * every worker, and also exposes the per-worker `VITEST_POOL_ID` /
+ * `VITEST_WORKER_ID`. CLI db tasks run outside vitest, so this is false there.
+ */
+function runningUnderVitest() {
+    return process.env.VITEST === 'true' || process.env.VITEST_POOL_ID != null;
+}
 export const DreamAppAllowedPackageManagersEnumValues = ['pnpm', 'yarn', 'npm', 'bun', 'deno'];
 // GeneratorImportStyles are used by CLI generators to determine how
 // to style import suffixes. When integrating with other apps, this

package/dist/esm/src/helpers/areEqual.js

@@ -4,7 +4,7 @@ import CalendarDate from '../utils/datetime/CalendarDate.js';
 import { DateTime } from '../utils/datetime/DateTime.js';
 /**
  * Performs a deep equality check between two values, supporting primitives, arrays,
- * Dream instances, CalendarDate, DateTime, and objects.
+ * Dream instances, CalendarDate, DateTime, ClockTime, ClockTimeTz, and objects.
  *
  * Examples:
  *   areEqual(undefined, undefined) // true

package/dist/esm/src/helpers/loadRepl.js

@@ -2,6 +2,8 @@ import DreamApp from '../dream-app/index.js';
 import Encrypt from '../encrypt/index.js';
 import ops from '../ops/index.js';
 import CalendarDate from '../utils/datetime/CalendarDate.js';
+import ClockTime from '../utils/datetime/ClockTime.js';
+import ClockTimeTz from '../utils/datetime/ClockTimeTz.js';
 import { DateTime } from '../utils/datetime/DateTime.js';
 import camelize from './camelize.js';
 import capitalize from './capitalize.js';
@@ -19,6 +21,8 @@ import uniq from './uniq.js';
 export default async function loadRepl(context) {
     const dreamApp = DreamApp.getOrFail();
     context.CalendarDate = CalendarDate;
+    context.ClockTime = ClockTime;
+    context.ClockTimeTz = ClockTimeTz;
     context.DateTime = DateTime;
     context.Encrypt = Encrypt;
     context.camelize = camelize;