velocious 1.0.632 → 1.0.634

package/README.md

@@ -682,8 +682,9 @@ Task.hasOneAttachment("descriptionFile")
 Task.hasOneAttachment("archivedPdf", {driver: "s3"})
 ```
 
-See [Backend record attachments](docs/attachments.md) for the complete input,
-storage-driver, lifecycle, and path-security contracts.
+`db:migrate` provisions the framework-owned attachment table before runtime
+attachment work begins. See [Backend record attachments](docs/attachments.md)
+for the complete input, storage-driver, lifecycle, and path-security contracts.
 
 You can also pass a driver class or instance directly on the attachment:
 
@@ -2179,6 +2180,8 @@ If you are developing on Velocious, you can run the tests with:
 
 Tests default to a 60-second timeout. Override per test with `{timeoutSeconds: 5}` or set a suite-wide default via `configureTests({defaultTimeoutSeconds: 30})`.
 
+Database-backed tests default `testArgs.databaseCleaning` to transaction rollback. The configured testing hook uses this metadata to cover `beforeEach`, the test body, and `afterEach` hooks on one pinned connection. Use `{databaseCleaning: {transaction: false, truncate: true}}` only for behavior that requires physical root transactions, independent commits, DDL that auto-commits or cannot run inside the wrapper transaction, lock contention, or genuine concurrency. Transaction-disabled non-request tests use ordinary independently owned checkouts instead of a runner-pinned connection. Tests that own their pool lifecycle or use only private databases can disable configured cleaning with `{databaseCleaning: {transaction: false, truncate: false}}`. See [database cleanup guidance](docs/testing-guidelines.md#preferred-strategy).
+
 Truncation-based test cleanup batches eligible tables into one request on PostgreSQL,
 SQL Server, and SQLite while preserving each driver's existing identity behavior,
 foreign-key restoration, stale-schema retry, and SQL.js persistence guarantees.
@@ -2461,7 +2464,7 @@ npx velocious background-jobs:retire --generation release-20260828.1 --socket /s
 ```
 
 Each lifecycle command sends one request with no retry and has a hard 10000ms
-deadline; `--timeout-ms` accepts 1 through 25000ms. Generation-aware workers,
+deadline; `--timeout-ms` accepts 1 through 60000ms. Generation-aware workers,
 clients, and reporters require their hello acknowledgement before readiness or
 mutation and bound it to 4000ms by default.
 

package/build/background-jobs/lifecycle-client.js

@@ -6,7 +6,7 @@ import timeout from "awaitery/build/timeout.js"
 import JsonSocket from "./json-socket.js"
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 10000
-const MAX_REQUEST_TIMEOUT_MS = 25000
+export const MAX_LIFECYCLE_REQUEST_TIMEOUT_MS = 60000
 
 /** One-request acknowledged lifecycle client. */
 export default class BackgroundJobsLifecycleClient {
@@ -26,8 +26,8 @@ export default class BackgroundJobsLifecycleClient {
     })
     this.generationId = generationConfig.generationId
     this.socketPath = generationConfig.lifecycleSocketPath
-    if (!Number.isInteger(requestTimeoutMs) || requestTimeoutMs < 1 || requestTimeoutMs > MAX_REQUEST_TIMEOUT_MS) {
-      throw new TypeError(`requestTimeoutMs must be an integer between 1 and ${MAX_REQUEST_TIMEOUT_MS}`)
+    if (!Number.isInteger(requestTimeoutMs) || requestTimeoutMs < 1 || requestTimeoutMs > MAX_LIFECYCLE_REQUEST_TIMEOUT_MS) {
+      throw new TypeError(`requestTimeoutMs must be an integer between 1 and ${MAX_LIFECYCLE_REQUEST_TIMEOUT_MS}`)
     }
     this.requestTimeoutMs = requestTimeoutMs
     if (!this.generationId) throw new Error("Background jobs lifecycle client requires generationId")

package/build/background-jobs/local-dispatcher.js

@@ -102,25 +102,36 @@ export default class LocalBackgroundJobsDispatcher {
     }
 
     this._wakeQueued = true
-    const drain = Promise.resolve().then(async () => {
-      this._wakeQueued = false
-      await this._drain()
-    })
-    const drainPromise = drain
-      .catch((error) => {
-        this._reportFrameworkError({error, stage: "local-background-jobs-drain"})
-        this._armRecoveryTimer()
-      })
-      .finally(() => {
-        if (this._drainPromise === drainPromise) this._drainPromise = null
-
-        if (this._redrain && this._accepting) {
-          this._redrain = false
-          this.wake()
-        } else {
-          this._resolveIdleWaiters()
-        }
+    /** @type {Promise<void>} */
+    let drainPromise
+
+    drainPromise = this.configuration.withoutCurrentTestDatabaseAccessScope(() => {
+      return this.configuration.withoutCurrentConnectionContexts(() => {
+        return Promise
+          .resolve()
+          .then(async () => {
+            this._wakeQueued = false
+            await this._drain()
+          })
+          .catch((error) => {
+            try {
+              this._reportFrameworkError({error, stage: "local-background-jobs-drain"})
+            } finally {
+              this._armRecoveryTimer()
+            }
+          })
+          .finally(() => {
+            if (this._drainPromise === drainPromise) this._drainPromise = null
+
+            if (this._redrain && this._accepting) {
+              this._redrain = false
+              this.wake()
+            } else {
+              this._resolveIdleWaiters()
+            }
+          })
       })
+    })
 
     this._drainPromise = drainPromise
   }

package/build/configuration.js

@@ -3526,6 +3526,32 @@ export default class VelociousConfiguration {
     return payload
   }
 
+  /**
+   * Runs one test attempt in a revocable database-access context.
+   * @template T
+   * @param {{revoked: boolean}} scope - Attempt-owned access scope.
+   * @param {() => T | Promise<T>} callback - Attempt work.
+   * @returns {T | Promise<T>} - Callback result.
+   */
+  runWithTestDatabaseAccessScope(scope, callback) {
+    return this.getEnvironmentHandler().runWithTestDatabaseAccessScope(scope, callback)
+  }
+
+  /**
+   * Runs persistent framework work without inheriting a test attempt's revocable database-access scope.
+   * @template T
+   * @param {() => T | Promise<T>} callback - Persistent work to run.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async withoutCurrentTestDatabaseAccessScope(callback) {
+    return await this.getEnvironmentHandler().runWithCapturedTestDatabaseAccessScope(undefined, callback)
+  }
+
+  /** Throws when a timed-out test attempt tries to start more database work. */
+  assertDatabaseAccessAllowed() {
+    this.getEnvironmentHandler().assertTestDatabaseAccessAllowed()
+  }
+
   /**
    * Runs with connections.
    * @template T
@@ -3534,6 +3560,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withConnections(optionsOrCallback, callback) {
+    this.assertDatabaseAccessAllowed()
     const {
       callback: actualWithConnectionsCallback,
       databaseIdentifiers,
@@ -3564,6 +3591,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withTransaction({databaseIdentifier, name = "Configuration.withTransaction", ...restArgs}, callback) {
+    this.assertDatabaseAccessAllowed()
     restArgsError(restArgs)
 
     if (!databaseIdentifier) throw new Error("Configuration.withTransaction requires a databaseIdentifier")
@@ -3577,6 +3605,7 @@ export default class VelociousConfiguration {
     const pool = this.getDatabasePool(databaseIdentifier)
 
     return await pool.withOperationConnection({name}, async (connection, owner) => {
+      this.assertDatabaseAccessAllowed()
       const operation = new DatabaseOperation({
         configuration: this,
         databaseConfiguration,
@@ -3588,7 +3617,10 @@ export default class VelociousConfiguration {
       })
 
       try {
-        return await operation.transaction(async () => await callback(operation))
+        return await operation.transaction(async () => {
+          this.assertDatabaseAccessAllowed()
+          return await callback(operation)
+        })
       } finally {
         operation.complete()
       }
@@ -3605,6 +3637,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Callback result.
    */
   async withDatabaseOperation({databaseConfiguration, databaseIdentifier, name = "Configuration.withDatabaseOperation", schemaGeneration, tenant, ...restArgs}, callback) {
+    this.assertDatabaseAccessAllowed()
     restArgsError(restArgs)
 
     if (!databaseIdentifier) throw new Error("Configuration.withDatabaseOperation requires a databaseIdentifier")
@@ -3615,6 +3648,7 @@ export default class VelociousConfiguration {
     const configurationReuseKey = pool.getConfigurationReuseKey(databaseConfiguration)
 
     return await pool.withCapturedOperationConnection({databaseConfiguration, name}, async (connection, owner) => {
+      this.assertDatabaseAccessAllowed()
       const operation = new DatabaseOperation({
         configuration: this,
         databaseConfiguration,
@@ -3644,6 +3678,7 @@ export default class VelociousConfiguration {
   async withDatabaseIdentifierConnections({callback, dbs, identifiers, name, stackLabel}) {
     const stack = Error().stack
     const actualCallback = async () => {
+      this.assertDatabaseAccessAllowed()
       return await withTrackedStack(stack || stackLabel, async () => {
         return await callback(dbs)
       })
@@ -3677,6 +3712,7 @@ export default class VelociousConfiguration {
    * @returns {Record<string, import("./database/drivers/base.js").default>} A map of database connections with identifier as key
    */
   getCurrentConnections(databaseIdentifiers = this.getDatabaseIdentifiers()) {
+    this.assertDatabaseAccessAllowed()
     /**
      * Dbs.
      * @type {{[key: string]: import("./database/drivers/base.js").default}} */
@@ -3766,6 +3802,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async ensureConnections(optionsOrCallback, callback) {
+    this.assertDatabaseAccessAllowed()
     const {
       callback: actualWithConnectionsCallback,
       databaseIdentifiers,

package/build/database/drivers/base.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. */
@@ -2560,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)
   }
 
   /**
@@ -2603,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)
   }
 
   /**
@@ -2649,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)
   }
 
   /**
@@ -2683,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/build/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/build/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})
   }