velocious 1.0.631 → 1.0.633

package/src/database/drivers/base.js

@@ -170,7 +170,7 @@ import TableData from "../table-data/index.js"
 import TableColumn from "../table-data/table-column.js"
 import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/build/wait.js"
-import { optionalPositiveInteger } from "typanic"
+import { ensureError, optionalPositiveInteger } from "typanic"
 import {coordinateSharedTransactionConnection, runWithoutSharedTransactionCoordinatorOwner} from "../../testing/shared-transaction-connection-coordinator.js"
 import { currentTestProfileContext } from "../../testing/test-profile-context.js"
 import sha256Hex from "../../utils/sha256-hex.js"
@@ -1376,63 +1376,65 @@ export default class VelociousDatabaseDriversBase {
   async transaction(callback, options = {}) {
     await this._waitForOperationLease(options.operationOwner)
 
-    if (this._transactionsCount > 0) {
-      return await this._runTransactionAttempt(callback, options)
-    }
-
-    const args = this.getArgs()
-    const maxAttempts = optionalPositiveInteger(args.deadlockMaxRetries, "deadlockMaxRetries") ?? 8
-    const configuredBaseWaitMs = optionalPositiveInteger(args.deadlockBaseWaitMs, "deadlockBaseWaitMs")
-    const deadlockMaxWaitMs = optionalPositiveInteger(args.deadlockMaxWaitMs, "deadlockMaxWaitMs") ?? 1000
-    let attempt = 0
+    return await coordinateSharedTransactionConnection(this, async () => {
+      if (this._transactionsCount > 0) {
+        return await this._runTransactionAttempt(callback, options)
+      }
 
-    while (true) {
-      attempt++
-      const attemptStartedAtMs = this._nowMs()
+      const args = this.getArgs()
+      const maxAttempts = optionalPositiveInteger(args.deadlockMaxRetries, "deadlockMaxRetries") ?? 8
+      const configuredBaseWaitMs = optionalPositiveInteger(args.deadlockBaseWaitMs, "deadlockBaseWaitMs")
+      const deadlockMaxWaitMs = optionalPositiveInteger(args.deadlockMaxWaitMs, "deadlockMaxWaitMs") ?? 1000
+      let attempt = 0
 
-      try {
-        return await this._runTransactionAttempt(callback, options)
-      } catch (error) {
-        if (error instanceof VelociousDatabaseAfterCommitCallbackError) throw error.callbackError
-        if (!(error instanceof Error)) throw error
+      while (true) {
+        attempt++
+        const attemptStartedAtMs = this._nowMs()
 
-        const retryInfo = this.retryableDatabaseError(error)
-        const willRetry = Boolean(retryInfo.deadlock && attempt < maxAttempts && this._transactionsCount == 0)
-
-        if (willRetry) {
-          this._reportDeadlockRetryDiagnostic({
-            attempt,
-            contentionKind: retryInfo.contentionKind || "deadlock",
-            error,
-            maxAttempts,
-            transactionAttemptDurationMs: Math.max(0, this._nowMs() - attemptStartedAtMs),
-            willRetry
-          })
+        try {
+          return await this._runTransactionAttempt(callback, options)
+        } catch (error) {
+          if (error instanceof VelociousDatabaseAfterCommitCallbackError) throw error.callbackError
+          if (!(error instanceof Error)) throw error
+
+          const retryInfo = this.retryableDatabaseError(error)
+          const willRetry = Boolean(retryInfo.deadlock && attempt < maxAttempts && this._transactionsCount == 0)
+
+          if (willRetry) {
+            this._reportDeadlockRetryDiagnostic({
+              attempt,
+              contentionKind: retryInfo.contentionKind || "deadlock",
+              error,
+              maxAttempts,
+              transactionAttemptDurationMs: Math.max(0, this._nowMs() - attemptStartedAtMs),
+              willRetry
+            })
+
+            // An explicitly-configured base wins so the tuning knob is effective even on drivers
+            // whose classifier supplies its own `waitMs` (MySQL/MariaDB return a fixed 50ms for
+            // deadlocks); otherwise honor that classifier hint, then fall back to 50ms.
+            const baseWaitMs = configuredBaseWaitMs ?? (typeof retryInfo.waitMs == "number" && retryInfo.waitMs > 0 ? retryInfo.waitMs : 50)
+
+            // Full-jitter exponential backoff: wait a uniform-random duration in
+            // [0, min(base * 2^(attempt-1), cap)]. The doubling ceiling spreads retries out as
+            // contention persists, and the jitter de-correlates transactions that deadlocked in
+            // lockstep so they stop re-colliding on the same wait (the linear `base * attempt`
+            // this replaces had every victim retry after an identical delay). `attempt` is
+            // 1-based here, so 2^(attempt-1) is 1, 2, 4, ... The cap keeps the tail sub-second.
+            const ceilingWaitMs = Math.min(baseWaitMs * (2 ** (attempt - 1)), deadlockMaxWaitMs)
+            const jitteredWaitMs = Math.floor(Math.random() * (ceilingWaitMs + 1))
+
+            const loggedContentionKind = retryInfo.contentionKind || "transaction contention"
+
+            this.logger.warn(`Retrying transaction after ${loggedContentionKind} (attempt ${attempt}/${maxAttempts})`)
+            await this._waitMs(jitteredWaitMs)
+            continue
+          }
 
-          // An explicitly-configured base wins so the tuning knob is effective even on drivers
-          // whose classifier supplies its own `waitMs` (MySQL/MariaDB return a fixed 50ms for
-          // deadlocks); otherwise honor that classifier hint, then fall back to 50ms.
-          const baseWaitMs = configuredBaseWaitMs ?? (typeof retryInfo.waitMs == "number" && retryInfo.waitMs > 0 ? retryInfo.waitMs : 50)
-
-          // Full-jitter exponential backoff: wait a uniform-random duration in
-          // [0, min(base * 2^(attempt-1), cap)]. The doubling ceiling spreads retries out as
-          // contention persists, and the jitter de-correlates transactions that deadlocked in
-          // lockstep so they stop re-colliding on the same wait (the linear `base * attempt`
-          // this replaces had every victim retry after an identical delay). `attempt` is
-          // 1-based here, so 2^(attempt-1) is 1, 2, 4, ... The cap keeps the tail sub-second.
-          const ceilingWaitMs = Math.min(baseWaitMs * (2 ** (attempt - 1)), deadlockMaxWaitMs)
-          const jitteredWaitMs = Math.floor(Math.random() * (ceilingWaitMs + 1))
-
-          const loggedContentionKind = retryInfo.contentionKind || "transaction contention"
-
-          this.logger.warn(`Retrying transaction after ${loggedContentionKind} (attempt ${attempt}/${maxAttempts})`)
-          await this._waitMs(jitteredWaitMs)
-          continue
+          throw error
         }
-
-        throw error
       }
-    }
+    }, options.operationOwner)
   }
 
   /**
@@ -1769,34 +1771,36 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async startTransaction(options = {}) {
-    while (true) {
-      /** @type {import("../operation-lease.js").default | undefined} */
-      let blockingOperationLease
-
-      await this._transactionsActionsMutex.sync(async () => {
-        const operationLease = this._operationLease
+    await coordinateSharedTransactionConnection(this, async () => {
+      while (true) {
+        /** @type {import("../operation-lease.js").default | undefined} */
+        let blockingOperationLease
 
-        if (operationLease && options.operationOwner !== operationLease.owner) {
-          blockingOperationLease = operationLease
-          return
-        }
+        await this._transactionsActionsMutex.sync(async () => {
+          const operationLease = this._operationLease
 
-        await this._runProfiledTransactionAction("start", async () => {
-          await this._startTransactionAction(options)
-        })
-        this._transactionsCount++
+          if (operationLease && options.operationOwner !== operationLease.owner) {
+            blockingOperationLease = operationLease
+            return
+          }
 
-        if (this._transactionsCount === 1) {
-          this._transactionCompletionPromise = new Promise((resolve) => {
-            this._resolveTransactionCompletion = resolve
+          await this._runProfiledTransactionAction("start", async () => {
+            await this._startTransactionAction(options)
           })
-        }
-      })
+          this._transactionsCount++
 
-      if (!blockingOperationLease) return
+          if (this._transactionsCount === 1) {
+            this._transactionCompletionPromise = new Promise((resolve) => {
+              this._resolveTransactionCompletion = resolve
+            })
+          }
+        })
 
-      await blockingOperationLease.wait(options.operationOwner)
-    }
+        if (!blockingOperationLease) return
+
+        await blockingOperationLease.wait(options.operationOwner)
+      }
+    }, options.operationOwner)
   }
 
   /**
@@ -1814,13 +1818,15 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async commitTransaction(options = {}) {
-    await this._transactionsActionsMutex.sync(async () => {
-      await this._runProfiledTransactionAction("commit", async () => {
-        await this._commitTransactionAction(options)
+    await coordinateSharedTransactionConnection(this, async () => {
+      await this._transactionsActionsMutex.sync(async () => {
+        await this._runProfiledTransactionAction("commit", async () => {
+          await this._commitTransactionAction(options)
+        })
+        this._transactionsCount--
+        this._resolveCompletedTransaction()
       })
-      this._transactionsCount--
-      this._resolveCompletedTransaction()
-    })
+    }, options.operationOwner)
   }
 
   /** Resolves the current outer transaction completion when it has finished. */
@@ -1998,7 +2004,10 @@ export default class VelociousDatabaseDriversBase {
           const waitMs = typeof retryInfo.waitMs === "number" && Number.isFinite(retryInfo.waitMs) ? retryInfo.waitMs : 100
 
           if (waitMs > 0) await wait(waitMs)
-          this.logger.warn(`Retrying query because failed with: ${error.stack}`)
+          const sensitiveValues = requestTiming ? requestTiming.getLogSensitiveValues() : new Set()
+          const loggedError = this.configuration.getLogRedactor().redactString(error.stack || error.message, sensitiveValues)
+
+          this.logger.warn(`Retrying query because failed with: ${loggedError}`)
           // Retry
         } else {
           throw error
@@ -2064,17 +2073,32 @@ export default class VelociousDatabaseDriversBase {
     let result
 
     try {
-      const runQueryActualWithHooks = async () => await this._queryActualWithHooks(querySql, options, originalSql)
+      try {
+        const runQueryActualWithHooks = async () => await this._queryActualWithHooks(querySql, options, originalSql)
 
-      if (requestTiming && tries === 1) {
-        result = await requestTiming.measureDbQuery(runQueryActualWithHooks)
-      } else if (requestTiming) {
-        result = await requestTiming.measure("db", runQueryActualWithHooks)
-      } else {
-        result = await runQueryActualWithHooks()
+        if (requestTiming && tries === 1) {
+          result = await requestTiming.measureDbQuery(runQueryActualWithHooks)
+        } else if (requestTiming) {
+          result = await requestTiming.measure("db", runQueryActualWithHooks)
+        } else {
+          result = await runQueryActualWithHooks()
+        }
+      } finally {
+        this._activeQuery = previousActiveQuery
       }
-    } finally {
-      this._activeQuery = previousActiveQuery
+    } catch (error) {
+      if (options.logQuery !== false) {
+        await this._logQuery({
+          elapsedMs: nowMs() - startedAtMs,
+          error: ensureError(error),
+          logName: options.logName || "SQL",
+          requestTiming,
+          sourceStack: options.sourceStack,
+          sql: originalSql
+        })
+      }
+
+      throw error
     }
 
     const elapsedMs = nowMs() - startedAtMs
@@ -2083,6 +2107,7 @@ export default class VelociousDatabaseDriversBase {
       await this._logQuery({
         elapsedMs,
         logName: options.logName || "SQL",
+        requestTiming,
         sourceStack: options.sourceStack,
         sql: originalSql
       })
@@ -2374,17 +2399,25 @@ export default class VelociousDatabaseDriversBase {
    * Runs log query.
    * @param {object} args - Options object.
    * @param {number} args.elapsedMs - Elapsed milliseconds.
+   * @param {Error} [args.error] - Query failure, when the driver call failed.
    * @param {string} args.logName - Query log subject.
+   * @param {import("../../http-server/client/request-timing.js").default | undefined} args.requestTiming - Request timing.
    * @param {string | undefined} args.sourceStack - Source stack.
    * @param {string} args.sql - SQL string.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async _logQuery({elapsedMs, logName, sourceStack, sql}) {
+  async _logQuery({elapsedMs, error, logName, requestTiming, sourceStack, sql}) {
     const logger = new Logger(logName, {configuration: this.configuration})
     const sourceLine = this._querySourceLine(sourceStack)
+    const sensitiveValues = requestTiming ? requestTiming.getLogSensitiveValues() : new Set()
+    const redactor = this.configuration.getLogRedactor()
+    const loggedSql = redactor.redactString(sql, sensitiveValues)
+    const failure = error
+      ? ` FAILED ${error.name}: ${redactor.redactString(error.message, sensitiveValues)}`
+      : ""
     const message = sourceLine
-      ? `(${formatElapsedMs(elapsedMs)})  ${sql}\n  ↳ ${sourceLine}`
-      : `(${formatElapsedMs(elapsedMs)})  ${sql}`
+      ? `(${formatElapsedMs(elapsedMs)})${failure}  ${loggedSql}\n  ↳ ${sourceLine}`
+      : `(${formatElapsedMs(elapsedMs)})${failure}  ${loggedSql}`
 
     await logger.info(message)
   }
@@ -2533,23 +2566,28 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async rollbackTransaction(options = {}) {
-    await this._transactionsActionsMutex.sync(async () => {
-      try {
-        await this._runProfiledTransactionAction("rollback", async () => {
-          await this._rollbackTransactionAction(options)
-        })
-      } finally {
-        this._transactionsCount--
-        this._resolveCompletedTransaction()
-
-        // A rolled-back transaction may have reverted DDL (e.g. a CREATE TABLE
-        // run lazily inside the transaction), so any cached schema metadata is
-        // now stale and must be invalidated. Without this, a later tableExists()
-        // check can report a table that the rollback already removed, so callers
-        // skip recreating it and then fail with "no such table".
-        this.clearSchemaCache()
-      }
-    })
+    await coordinateSharedTransactionConnection(this, async () => {
+      await this._transactionsActionsMutex.sync(async () => {
+        try {
+          await this._runProfiledTransactionAction("rollback", async () => {
+            await this._rollbackTransactionAction(options)
+          })
+        } finally {
+          // Driver recovery may need to clear a stale physical transaction when
+          // no logical transaction is active. Never let that cleanup underflow
+          // the logical depth and turn the next root transaction into a savepoint.
+          if (this._transactionsCount > 0) this._transactionsCount--
+          this._resolveCompletedTransaction()
+
+          // A rolled-back transaction may have reverted DDL (e.g. a CREATE TABLE
+          // run lazily inside the transaction), so any cached schema metadata is
+          // now stale and must be invalidated. Without this, a later tableExists()
+          // check can report a table that the rollback already removed, so callers
+          // skip recreating it and then fail with "no such table".
+          this.clearSchemaCache()
+        }
+      })
+    }, options.operationOwner)
   }
 
   /**
@@ -2576,9 +2614,11 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async startSavePoint(savePointName, options = {}) {
-    await this._transactionsActionsMutex.sync(async () => {
-      await this._startSavePointAction(savePointName, options)
-    })
+    await coordinateSharedTransactionConnection(this, async () => {
+      await this._transactionsActionsMutex.sync(async () => {
+        await this._startSavePointAction(savePointName, options)
+      })
+    }, options.operationOwner)
   }
 
   /**
@@ -2622,9 +2662,11 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async releaseSavePoint(savePointName, options = {}) {
-    await this._transactionsActionsMutex.sync(async () => {
-      await this._releaseSavePointAction(savePointName, options)
-    })
+    await coordinateSharedTransactionConnection(this, async () => {
+      await this._transactionsActionsMutex.sync(async () => {
+        await this._releaseSavePointAction(savePointName, options)
+      })
+    }, options.operationOwner)
   }
 
   /**
@@ -2656,9 +2698,11 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async rollbackSavePoint(savePointName, options = {}) {
-    await this._transactionsActionsMutex.sync(async () => {
-      await this._rollbackSavePointAction(savePointName, options)
-    })
+    await coordinateSharedTransactionConnection(this, async () => {
+      await this._transactionsActionsMutex.sync(async () => {
+        await this._rollbackSavePointAction(savePointName, options)
+      })
+    }, options.operationOwner)
   }
 
   /**

package/src/database/drivers/sqlite/index.web.js

@@ -17,6 +17,9 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
    * @type {ConnectionSqlJs | undefined} */
   _connection = undefined
 
+  /** @type {SqliteWebConnection | undefined} */
+  _externalConnection = undefined
+
   /**
    * Runs sql js locate file.
    * @returns {(file: string) => string} - locateFile callback for sql.js.
@@ -34,18 +37,21 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
   async connect() {
     this.args = this.getArgs()
 
-    if (!this.args.getConnection) {
-      if (this.args.reset) {
-        await deleteSqliteWebPersistences({databaseName: this.databaseName()})
-      }
-
-      const persistence = await createSqliteWebPersistence({databaseName: this.databaseName()})
-      const SQL = await initSqlJs({locateFile: this.sqlJsLocateFile()})
-      const databaseContent = await persistence.load()
-      const connectionSqlJs = new ConnectionSqlJs(this, new SQL.Database(databaseContent), persistence)
+    if (this.args.getConnection) {
+      this._externalConnection = this.args.getConnection()
+      return
+    }
 
-      this._connection = connectionSqlJs
+    if (this.args.reset) {
+      await deleteSqliteWebPersistences({databaseName: this.databaseName()})
     }
+
+    const persistence = await createSqliteWebPersistence({databaseName: this.databaseName()})
+    const SQL = await initSqlJs({locateFile: this.sqlJsLocateFile()})
+    const databaseContent = await persistence.load()
+    const connectionSqlJs = new ConnectionSqlJs(this, new SQL.Database(databaseContent), persistence)
+
+    this._connection = connectionSqlJs
   }
 
   async _close() {
@@ -152,7 +158,9 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
    */
   getConnection() {
     if (this.args?.getConnection) {
-      return /** @type {SqliteWebConnection} */ (this.args.getConnection())
+      if (!this._externalConnection) throw new Error("SQLite web external connection has not been initialized")
+
+      return this._externalConnection
     } else {
       if (!this._connection) throw new Error("SQLite web connection has not been initialized")
       return this._connection

package/src/database/migrator.js

@@ -265,15 +265,18 @@ export default class VelociousDatabaseMigrator {
     const environmentHandler = this.configuration.getEnvironmentHandler()
     const dbs = await this.configuration.getCurrentConnections()
     const filteredDbs = Object.fromEntries(
-      Object.entries(dbs).filter(([dbIdentifier]) => this.handlesDatabaseIdentifier(dbIdentifier))
+      Object.entries(dbs).filter(([dbIdentifier]) => {
+        if (!this.handlesDatabaseIdentifier(dbIdentifier)) return false
+
+        return Boolean(this.configuration.getDatabaseIdentifier(dbIdentifier).migrations)
+      })
     )
 
     if (!environmentHandler || Object.keys(filteredDbs).length == 0) return
 
-    // Ensure velocious' own framework schema (background jobs) before the structure
-    // dump, and unconditionally — the dump is gated to enabled environments but the
-    // framework schema must exist after every migrate so `db:migrate` (and thus
-    // schema:load of the dumped SQL) produces a complete DB in every environment.
+    // Ensure Velocious' own framework schema before the structure dump. The dump is
+    // gated to enabled environments, but migration-enabled databases must include
+    // framework tables so `db:migrate` and schema:load produce a complete database.
     await environmentHandler.ensureFrameworkSchema({dbs: filteredDbs})
     await environmentHandler.afterMigrations({dbs: filteredDbs})
   }

package/src/database/pool/async-tracked-multi-connection.js

@@ -17,6 +17,7 @@ import { currentTestProfileContext } from "../../testing/test-profile-context.js
  * @property {number | null} timeoutAt - Timestamp when the checkout will time out, or null when disabled.
  * @property {number | null} timeoutMillis - Milliseconds to wait before rejecting, or null when disabled.
  * @property {ReturnType<typeof setTimeout> | undefined} timeoutTimer - Timer that rejects the pending checkout.
+ * @property {{revoked: boolean} | undefined} [testDatabaseAccessScope] - Database-access scope captured at enqueue.
  * @property {import("../../testing/test-profiler.js").TestProfileAsyncContext | undefined} [testProfileContext] - Async-safe profile attribution captured at enqueue.
  */
 export const CLOSED_CONNECTION = Symbol("velociousClosedConnection")
@@ -227,7 +228,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     const trackedConnection = /** @type {import("../drivers/base.js").default & {[CLOSED_CONNECTION]?: boolean, [CONNECTION_CHECKED_OUT_AT]?: number, [IDLE_CONNECTION_CHECKED_IN_AT]?: number}} */ (connection)
 
     if (trackedConnection[CLOSED_CONNECTION]) {
-      this.untrackConnectionInUse(connection, id)
+      if (typeof id === "number") this.untrackConnectionInUse(connection, id)
       await this.drainPendingCheckouts()
       return
     }
@@ -343,6 +344,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {Promise<import("../drivers/base.js").default>} - Resolves with the checkout.
    */
   async checkout(options = {}) {
+    this.assertDatabaseAccessAllowed()
     let databaseConfig = this.getConfiguration()
     let reuseKey = this.getConfigurationReuseKey(databaseConfig)
     let connection = this.takeIdleConnectionForReuseKey(reuseKey)
@@ -380,6 +382,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {Promise<import("../drivers/base.js").default>} - Activated pooled connection.
    */
   async checkoutForConfiguration(databaseConfig, options = {}) {
+    this.assertDatabaseAccessAllowed()
     const reuseKey = this.getConfigurationReuseKey(databaseConfig)
     const lifecycleRetainedConnection = this.lifecycleRetainedConnections.get(reuseKey)
 
@@ -446,6 +449,11 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {Promise<import("../drivers/base.js").default>} - Activated connection.
    */
   async activateConnection(connection, options = {}) {
+    try {
+      this.assertDatabaseAccessAllowed()
+    } catch (error) {
+      await this.closeRejectedCheckoutAndThrow(connection, error)
+    }
     if (connection.getIdSeq() !== undefined) throw new Error(`Connection already has an ID-seq - is it in use? ${connection.getIdSeq()}`)
 
     const id = this.idSeq++
@@ -459,15 +467,48 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
     try {
       await connection.setConnectionCheckoutName(options.name)
+      this.assertDatabaseAccessAllowed()
     } catch (error) {
-      delete this.connectionsInUse[id]
-      connection.setIdSeq(undefined)
+      await this.closeRejectedCheckoutAndThrow(connection, error, id)
+    }
+
+    return connection
+  }
+
+  /**
+   * Closes a rejected checkout, then hands freed capacity to queued callers.
+   * @param {import("../drivers/base.js").default} connection - Rejected connection.
+   * @param {ReturnType<typeof JSON.parse>} error - Access revocation error.
+   * @param {number} [id] - Assigned checkout id, if activation reached that stage.
+   * @returns {Promise<never>} - Always rejects with the access or cleanup errors.
+   */
+  async closeRejectedCheckoutAndThrow(connection, error, id) {
+    if (id !== undefined) this.untrackConnectionInUse(connection, id)
+
+    /** @type {ReturnType<typeof JSON.parse>[]} */
+    const cleanupErrors = []
+
+    try {
       await this.closeConnection(connection)
+    } catch (closeError) {
+      cleanupErrors.push(closeError)
+    }
 
-      throw error
+    try {
+      if (this.pendingCheckoutDrainPromise) {
+        this.pendingCheckoutDrainRequested = true
+      } else {
+        await this.drainPendingCheckouts()
+      }
+    } catch (drainError) {
+      cleanupErrors.push(drainError)
     }
 
-    return connection
+    if (cleanupErrors.length > 0) {
+      throw new AggregateError([error, ...cleanupErrors], "Database checkout rejection cleanup failed", {cause: error})
+    }
+
+    throw error
   }
 
   /**
@@ -588,6 +629,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
         timeoutAt: timeoutMillis === null ? null : enqueuedAt + timeoutMillis,
         timeoutMillis,
         timeoutTimer: undefined,
+        testDatabaseAccessScope: this.configuration.getEnvironmentHandler().currentTestDatabaseAccessScope(),
         testProfileContext: currentTestProfileContext(this.configuration)
       }
 
@@ -887,20 +929,23 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     const environmentHandler = this.configuration.getEnvironmentHandler()
 
     return await environmentHandler.runWithTestProfileContext(checkout.testProfileContext, async () => {
-      let connection
-
-      try {
-        connection = await this.spawnConnectionForCheckout(
-          checkout.databaseConfig,
-          checkout.reuseKey,
-          checkout.testProfileContext
-        )
-      } catch (error) {
-        checkout.reject(error instanceof Error ? error : new Error("Failed to spawn database connection.", {cause: error}))
-        return
-      }
-
-      await this.resolvePendingCheckout(checkout, connection)
+      return await environmentHandler.runWithCapturedTestDatabaseAccessScope(checkout.testDatabaseAccessScope, async () => {
+        let connection
+
+        try {
+          this.assertDatabaseAccessAllowed()
+          connection = await this.spawnConnectionForCheckout(
+            checkout.databaseConfig,
+            checkout.reuseKey,
+            checkout.testProfileContext
+          )
+        } catch (error) {
+          checkout.reject(error instanceof Error ? error : new Error("Failed to spawn database connection.", {cause: error}))
+          return
+        }
+
+        await this.resolvePendingCheckout(checkout, connection)
+      })
     })
   }
 
@@ -914,11 +959,13 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     const environmentHandler = this.configuration.getEnvironmentHandler()
 
     return await environmentHandler.runWithTestProfileContext(checkout.testProfileContext, async () => {
-      try {
-        checkout.resolve(await this.activateConnection(connection, checkout.options))
-      } catch (error) {
-        checkout.reject(error instanceof Error ? error : new Error("Failed to activate database connection.", {cause: error}))
-      }
+      return await environmentHandler.runWithCapturedTestDatabaseAccessScope(checkout.testDatabaseAccessScope, async () => {
+        try {
+          checkout.resolve(await this.activateConnection(connection, checkout.options))
+        } catch (error) {
+          checkout.reject(error instanceof Error ? error : new Error("Failed to activate database connection.", {cause: error}))
+        }
+      })
     })
   }
 
@@ -945,6 +992,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withConnection(optionsOrCallback, callback) {
+    this.assertDatabaseAccessAllowed()
     const options = typeof optionsOrCallback == "function" ? {} : optionsOrCallback
     const actualCallback = typeof optionsOrCallback == "function" ? optionsOrCallback : callback
 
@@ -1046,6 +1094,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {import("../drivers/base.js").default} - The current connection.
    */
   getCurrentConnection() {
+    this.assertDatabaseAccessAllowed()
     const id = this.asyncLocalStorage.getStore()
 
     if (id === undefined) return this.currentFallbackConnectionOrFail()

package/src/database/pool/base.js

@@ -120,6 +120,11 @@ class VelociousDatabasePoolBase {
     this.logger = new Logger(this)
   }
 
+  /** Throws when a revoked test attempt tries to acquire database access. */
+  assertDatabaseAccessAllowed() {
+    this.configuration.assertDatabaseAccessAllowed()
+  }
+
   /**
    * Runs checkin.
    * @abstract