velocious 1.0.543 → 1.0.545

package/README.md

@@ -4,6 +4,7 @@
 * Database framework with familiar MVC concepts
 * Database models with migrations and validations
 * Database models that work almost the same in frontend and backend
+* Connection-scoped advisory locks with automatic cleanup before pooled connections are reused or closed (see [docs/advisory-locks.md](docs/advisory-locks.md))
 * Built-in record auditing for model lifecycle changes (see [docs/auditing.md](docs/auditing.md))
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
 * Migrations for schema changes and UTC datetime storage (see [docs/database-migrations.md](docs/database-migrations.md))

package/build/database/advisory-lock-runner.js

@@ -148,7 +148,9 @@ export default class AdvisoryLockRunner {
     try {
       return await callback(connection)
     } finally {
-      if (!connection.getArgs().getConnection) {
+      if (connection.getArgs().getConnection) {
+        await connection.releaseHeldAdvisoryLocks()
+      } else {
         await connection.close()
       }
     }

package/build/database/drivers/base.js

@@ -57,6 +57,7 @@
  * @property {string} [logName] - Query log subject.
  * @property {boolean} [logQuery] - Whether to log the query.
  * @property {boolean} [processListComment] - Whether to add process-list comments to the query.
+ * @property {boolean} [retry] - Whether retryable errors may retry the query; defaults to true.
  * @property {boolean} [sessionTimeZone] - Whether to ensure the configured database session time zone before the query.
  * @property {string} [sourceStack] - Stack captured at the caller boundary.
  */
@@ -170,6 +171,8 @@ export default class VelociousDatabaseDriversBase {
    * Active query.
    * @type {ActiveQueryState | null} */
   _activeQuery = null
+  /** @type {Map<string, number>} */
+  _heldAdvisoryLocks = new Map()
 
   /**
    * Runs constructor.
@@ -239,10 +242,40 @@ export default class VelociousDatabaseDriversBase {
   }
 
   /**
-   * Optional close hook for database drivers.
-   * @returns {Promise<void>} - Resolves when complete.
+   * Releases tracked advisory locks and closes the physical database connection.
+   * @returns {Promise<void>} - Resolves when cleanup and close complete.
    */
   async close() {
+    /** @type {Error | undefined} */
+    let advisoryLockError
+
+    try {
+      await this.releaseHeldAdvisoryLocks()
+    } catch (error) {
+      advisoryLockError = error instanceof Error ? error : new Error("Failed to release held advisory locks", {cause: error})
+    }
+
+    try {
+      await this._close()
+      this._heldAdvisoryLocks.clear()
+    } catch (error) {
+      const closeError = error instanceof Error ? error : new Error("Failed to close database connection", {cause: error})
+
+      if (advisoryLockError) {
+        throw new AggregateError([advisoryLockError, closeError], "Failed to release advisory locks and close database connection", {cause: error})
+      }
+
+      throw closeError
+    }
+
+    if (advisoryLockError) throw advisoryLockError
+  }
+
+  /**
+   * Driver-specific physical close hook.
+   * @returns {Promise<void>} - Resolves when the underlying connection closes.
+   */
+  async _close() {
     // No-op by default
   }
 
@@ -1127,7 +1160,7 @@ export default class VelociousDatabaseDriversBase {
 
         const retryInfo = this.retryableDatabaseError(error)
 
-        if (tries < maxTries && retryInfo.retry) {
+        if (options.retry !== false && tries < maxTries && retryInfo.retry) {
           if (retryInfo.reconnect) {
             if (this._transactionsCount > 0) {
               throw new Error(`Cannot reconnect while a transaction is active (${this._transactionsCount}). Original error: ${error.message}`, {cause: error})
@@ -1773,33 +1806,124 @@ export default class VelociousDatabaseDriversBase {
    * table locks; they are purely cooperative between callers that use the
    * same name and let you serialize functionality without blocking readers
    * or writers that do not participate in the same lock.
-   * @abstract
    * @param {string} name - Lock name.
-   * @param {{timeoutMs?: number | null}} [_args] - Optional timeout in milliseconds; `null` or undefined blocks forever.
+   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null` or undefined blocks forever.
    * @returns {Promise<boolean>} - Resolves to true when the lock has been acquired, false if the timeout elapsed.
    */
-  acquireAdvisoryLock(name, _args = {}) {
-    throw new Error(`'acquireAdvisoryLock' not implemented for ${this.constructor.name}`)
+  async acquireAdvisoryLock(name, args = {}) {
+    const acquired = await this._acquireAdvisoryLock(name, args)
+
+    if (acquired) this._trackAdvisoryLock(name)
+
+    return acquired
   }
 
   /**
-   * Attempts to acquire a named advisory lock without blocking.
+   * Driver-specific blocking advisory-lock acquisition hook.
    * @abstract
    * @param {string} name - Lock name.
+   * @param {{timeoutMs?: number | null}} [_args] - Lock timeout options.
+   * @returns {Promise<boolean>} - Whether the lock was acquired.
+   */
+  _acquireAdvisoryLock(name, _args = {}) {
+    throw new Error(`'_acquireAdvisoryLock' not implemented for ${this.constructor.name}`)
+  }
+
+  /**
+   * Attempts to acquire a named advisory lock without blocking.
+   * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - Resolves to true if the lock was acquired, false if it was already held.
    */
-  tryAcquireAdvisoryLock(name) { // eslint-disable-line no-unused-vars
-    throw new Error(`'tryAcquireAdvisoryLock' not implemented for ${this.constructor.name}`)
+  async tryAcquireAdvisoryLock(name) {
+    const acquired = await this._tryAcquireAdvisoryLock(name)
+
+    if (acquired) this._trackAdvisoryLock(name)
+
+    return acquired
   }
 
   /**
-   * Releases a named advisory lock previously acquired on this connection.
+   * Driver-specific non-blocking advisory-lock acquisition hook.
    * @abstract
    * @param {string} name - Lock name.
+   * @returns {Promise<boolean>} - Whether the lock was acquired.
+   */
+  _tryAcquireAdvisoryLock(name) { // eslint-disable-line no-unused-vars
+    throw new Error(`'_tryAcquireAdvisoryLock' not implemented for ${this.constructor.name}`)
+  }
+
+  /**
+   * Releases a named advisory lock previously acquired on this connection.
+   * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - Resolves to true if the lock was held by this session and has now been released.
    */
-  releaseAdvisoryLock(name) { // eslint-disable-line no-unused-vars
-    throw new Error(`'releaseAdvisoryLock' not implemented for ${this.constructor.name}`)
+  async releaseAdvisoryLock(name) {
+    const released = await this._releaseAdvisoryLock(name)
+
+    if (released) {
+      this._untrackAdvisoryLock(name)
+    } else {
+      this._heldAdvisoryLocks.delete(name)
+    }
+
+    return released
+  }
+
+  /**
+   * Driver-specific advisory-lock release hook.
+   * @abstract
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>} - Whether the lock was released.
+   */
+  _releaseAdvisoryLock(name) { // eslint-disable-line no-unused-vars
+    throw new Error(`'_releaseAdvisoryLock' not implemented for ${this.constructor.name}`)
+  }
+
+  /**
+   * Releases every advisory lock still tracked on this connection.
+   * @returns {Promise<void>} - Resolves when every tracked lock is released.
+   */
+  async releaseHeldAdvisoryLocks() {
+    /** @type {Error[]} */
+    const errors = []
+
+    for (const name of [...this._heldAdvisoryLocks.keys()]) {
+      while (this._heldAdvisoryLocks.has(name)) {
+        try {
+          await this.releaseAdvisoryLock(name)
+        } catch (error) {
+          errors.push(error instanceof Error ? error : new Error(`Failed to release advisory lock ${JSON.stringify(name)}`, {cause: error}))
+          break
+        }
+      }
+    }
+
+    if (errors.length == 1) throw errors[0]
+    if (errors.length > 1) throw new AggregateError(errors, "Failed to release held advisory locks")
+  }
+
+  /**
+   * Records one successful acquisition, including re-entrant acquisitions.
+   * @param {string} name - Lock name.
+   * @returns {void}
+   */
+  _trackAdvisoryLock(name) {
+    this._heldAdvisoryLocks.set(name, (this._heldAdvisoryLocks.get(name) || 0) + 1)
+  }
+
+  /**
+   * Removes one successful acquisition from the connection registry.
+   * @param {string} name - Lock name.
+   * @returns {void}
+   */
+  _untrackAdvisoryLock(name) {
+    const remainingCount = (this._heldAdvisoryLocks.get(name) || 0) - 1
+
+    if (remainingCount > 0) {
+      this._heldAdvisoryLocks.set(name, remainingCount)
+    } else {
+      this._heldAdvisoryLocks.delete(name)
+    }
   }
 
   /**

package/build/database/drivers/mssql/index.js

@@ -47,7 +47,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
     }
   }
 
-  async close() {
+  async _close() {
     if (!this.connection) return
 
     const connection = this.connection
@@ -616,7 +616,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if the timeout elapsed.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const timeoutValue = typeof timeoutMs === "number" && timeoutMs >= 0 ? Math.ceil(timeoutMs) : -1
     const rows = await this.query(
       `DECLARE @velocious_advisory_lock_result INT; EXEC @velocious_advisory_lock_result = sp_getapplock @Resource = ${this.quote(name)}, @LockMode = 'Exclusive', @LockOwner = 'Session', @LockTimeout = ${timeoutValue}; SELECT @velocious_advisory_lock_result AS velocious_advisory_lock_result`
@@ -634,8 +634,8 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if it was already held.
    */
-  async tryAcquireAdvisoryLock(name) {
-    return await this.acquireAdvisoryLock(name, {timeoutMs: 0})
+  async _tryAcquireAdvisoryLock(name) {
+    return await this._acquireAdvisoryLock(name, {timeoutMs: 0})
   }
 
   /**
@@ -643,7 +643,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was held by this session and has now been released.
    */
-  async releaseAdvisoryLock(name) {
+  async _releaseAdvisoryLock(name) {
     const rows = await this.query(
       `DECLARE @velocious_advisory_lock_result INT; EXEC @velocious_advisory_lock_result = sp_releaseapplock @Resource = ${this.quote(name)}, @LockOwner = 'Session'; SELECT @velocious_advisory_lock_result AS velocious_advisory_lock_result`
     )

package/build/database/drivers/mysql/index.js

@@ -63,7 +63,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * Runs close.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async close() {
+  async _close() {
     await this.pool?.end()
     this.pool = undefined
     this.resetCurrentSessionTimeZone()
@@ -574,7 +574,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks for `MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS`.
    * @returns {Promise<boolean>} - True if acquired, false if the timeout elapsed.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const timeoutSeconds = typeof timeoutMs === "number" && timeoutMs >= 0
       ? Math.ceil(timeoutMs / 1000)
       : MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS
@@ -593,7 +593,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if it was already held.
    */
-  async tryAcquireAdvisoryLock(name) {
+  async _tryAcquireAdvisoryLock(name) {
     const rows = await this.query(`SELECT GET_LOCK(${this.quote(name)}, 0) AS velocious_advisory_lock_result`)
     const result = rows?.[0]?.velocious_advisory_lock_result
 
@@ -609,8 +609,8 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was held by this session and has now been released.
    */
-  async releaseAdvisoryLock(name) {
-    const rows = await this.query(`SELECT RELEASE_LOCK(${this.quote(name)}) AS velocious_advisory_lock_result`)
+  async _releaseAdvisoryLock(name) {
+    const rows = await this.query(`SELECT RELEASE_LOCK(${this.quote(name)}) AS velocious_advisory_lock_result`, {retry: false})
     const result = rows?.[0]?.velocious_advisory_lock_result
 
     return Number(result) === 1

package/build/database/drivers/pgsql/index.js

@@ -60,7 +60,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return connectArgs
   }
 
-  async close() {
+  async _close() {
     await this.connection?.end()
     this.connection = undefined
     this._transactionsCount = 0
@@ -411,7 +411,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if the timeout elapsed.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const key = this.advisoryLockKey(name)
 
     if (typeof timeoutMs !== "number" || timeoutMs < 0) {
@@ -423,7 +423,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     const pollIntervalMs = 50
 
     while (true) {
-      if (await this.tryAcquireAdvisoryLock(name)) return true
+      if (await this._tryAcquireAdvisoryLock(name)) return true
       if (Date.now() >= deadline) return false
 
       const remaining = deadline - Date.now()
@@ -437,7 +437,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if it was already held.
    */
-  async tryAcquireAdvisoryLock(name) {
+  async _tryAcquireAdvisoryLock(name) {
     const key = this.advisoryLockKey(name)
     const rows = await this.query(`SELECT pg_try_advisory_lock(${key}) AS velocious_advisory_lock_result`)
     const result = rows?.[0]?.velocious_advisory_lock_result
@@ -450,7 +450,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was held by this session and has now been released.
    */
-  async releaseAdvisoryLock(name) {
+  async _releaseAdvisoryLock(name) {
     const key = this.advisoryLockKey(name)
     const rows = await this.query(`SELECT pg_advisory_unlock(${key}) AS velocious_advisory_lock_result`)
     const result = rows?.[0]?.velocious_advisory_lock_result

package/build/database/drivers/sqlite/base.js

@@ -385,7 +385,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if the timeout elapsed.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const state = VelociousDatabaseDriversSqliteBase._advisoryLockState
 
     while (state.ownersByName.has(name)) {
@@ -445,7 +445,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if it was already held.
    */
-  async tryAcquireAdvisoryLock(name) {
+  async _tryAcquireAdvisoryLock(name) {
     const state = VelociousDatabaseDriversSqliteBase._advisoryLockState
 
     if (state.ownersByName.has(name)) return false
@@ -464,7 +464,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - True if the lock was held by this driver and has now been released.
    */
-  async releaseAdvisoryLock(name) {
+  async _releaseAdvisoryLock(name) {
     const state = VelociousDatabaseDriversSqliteBase._advisoryLockState
     const owner = state.ownersByName.get(name)
 

package/build/database/drivers/sqlite/index.js

@@ -62,7 +62,7 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
     return `VelociousDatabaseDriversSqlite---${args.name}`
   }
 
-  async close() {
+  async _close() {
     await this.connection?.close()
     this.connection = undefined
   }
@@ -105,10 +105,10 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
    * @returns {Promise<boolean>} - Whether the advisory lock was acquired.
    */
-  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+  async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
     const deadline = typeof timeoutMs === "number" && timeoutMs >= 0 ? Date.now() + timeoutMs : null
     const remainingForInProcess = deadline !== null ? Math.max(0, deadline - Date.now()) : null
-    const inProcessAcquired = await super.acquireAdvisoryLock(name, {timeoutMs: remainingForInProcess})
+    const inProcessAcquired = await super._acquireAdvisoryLock(name, {timeoutMs: remainingForInProcess})
 
     if (!inProcessAcquired) return false
 
@@ -117,11 +117,11 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
       const fileAcquired = await this._acquireAdvisoryLockFile(name, {timeoutMs: remainingForFile})
 
       if (!fileAcquired) {
-        await super.releaseAdvisoryLock(name)
+        await super._releaseAdvisoryLock(name)
         return false
       }
     } catch (error) {
-      await super.releaseAdvisoryLock(name)
+      await super._releaseAdvisoryLock(name)
       throw error
     }
 
@@ -133,8 +133,8 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - Whether the advisory lock was acquired immediately.
    */
-  async tryAcquireAdvisoryLock(name) {
-    const inProcessAcquired = await super.tryAcquireAdvisoryLock(name)
+  async _tryAcquireAdvisoryLock(name) {
+    const inProcessAcquired = await super._tryAcquireAdvisoryLock(name)
 
     if (!inProcessAcquired) return false
 
@@ -142,11 +142,11 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
       const fileAcquired = await this._tryAcquireAdvisoryLockFile(name)
 
       if (!fileAcquired) {
-        await super.releaseAdvisoryLock(name)
+        await super._releaseAdvisoryLock(name)
         return false
       }
     } catch (error) {
-      await super.releaseAdvisoryLock(name)
+      await super._releaseAdvisoryLock(name)
       throw error
     }
 
@@ -163,8 +163,8 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
    * @param {string} name - Lock name.
    * @returns {Promise<boolean>} - Whether the advisory lock was released.
    */
-  async releaseAdvisoryLock(name) {
-    const inProcessReleased = await super.releaseAdvisoryLock(name)
+  async _releaseAdvisoryLock(name) {
+    const inProcessReleased = await super._releaseAdvisoryLock(name)
 
     if (inProcessReleased) {
       await this._releaseAdvisoryLockFile(name)

package/build/database/drivers/sqlite/index.native.js

@@ -64,7 +64,7 @@ export default class VelociousDatabaseDriversSqliteNative extends Base {
     return connectArgs
   }
 
-  async close() {
+  async _close() {
     await this.connection.closeAsync()
     this.connection = undefined
   }

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

@@ -48,7 +48,7 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
     }
   }
 
-  async close() {
+  async _close() {
     await this.getConnection().close()
   }
 

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

@@ -125,6 +125,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
     try {
       await this.rollbackLeftOpenTransaction(connection)
+      await connection.releaseHeldAdvisoryLocks()
       await connection.clearConnectionCheckoutName()
     } catch (error) {
       await this.closeCheckedOutConnectionAfterCheckinFailure(connection, id, error)

package/build/database/pool/single-multi-use.js

@@ -3,15 +3,58 @@
 import BasePool from "./base.js"
 
 export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
+  activeCheckoutCount = 0
   suppressedConnectionContextCount = 0
 
+  /**
+   * Checkout names of the currently-active nested checkouts, innermost last. The
+   * shared connection carries a single checkout name, so nesting requires restoring
+   * the enclosing scope's name when an inner checkout checks in.
+   * @type {Array<string | undefined>}
+   */
+  checkoutNameStack = []
+
   /**
    * Runs checkin.
    * @param {import("../drivers/base.js").default} connection - Connection.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async checkin(connection) {
-    await connection.clearConnectionCheckoutName()
+    if (this.connection === connection && this.activeCheckoutCount > 0) {
+      this.activeCheckoutCount--
+      this.checkoutNameStack.pop()
+
+      // A nested checkout is checking in while an outer one is still active: restore
+      // the enclosing scope's checkout name instead of leaving this inner name (or
+      // clearing it) on the shared connection.
+      if (this.activeCheckoutCount > 0) {
+        await connection.setConnectionCheckoutName(this.checkoutNameStack[this.checkoutNameStack.length - 1])
+
+        return
+      }
+    }
+
+    try {
+      await connection.releaseHeldAdvisoryLocks()
+      await connection.clearConnectionCheckoutName()
+    } catch (error) {
+      if (this.connection === connection) {
+        this.activeCheckoutCount = 0
+        this.checkoutNameStack = []
+        this.connection = undefined
+      }
+
+      try {
+        await connection.close()
+      } catch (closeError) {
+        const cleanupError = error instanceof Error ? error : new Error("Failed to clean checked-in database connection", {cause: error})
+        const connectionCloseError = closeError instanceof Error ? closeError : new Error("Failed to close database connection after check-in cleanup failed", {cause: closeError})
+
+        throw new AggregateError([cleanupError, connectionCloseError], "Failed to clean and close checked-in database connection", {cause: closeError})
+      }
+
+      throw error
+    }
   }
 
   /**
@@ -23,6 +66,8 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
     if (this.connection && !this.connectionMatchesCurrentConfiguration(this.connection)) {
       const previousConnection = this.connection
 
+      this.activeCheckoutCount = 0
+      this.checkoutNameStack = []
       this.connection = undefined
 
       await previousConnection.close()
@@ -32,7 +77,9 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
       this.connection = await this.spawnConnection()
     }
 
+    this.checkoutNameStack.push(options.name)
     await this.connection.setConnectionCheckoutName(options.name)
+    this.activeCheckoutCount++
 
     return this.connection
   }
@@ -103,6 +150,7 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
 
     const connection = this.connection
 
+    this.activeCheckoutCount = 0
     this.connection = undefined
 
     await connection.close()

package/build/environment-handlers/node.js

@@ -1020,12 +1020,24 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     const {default: BackgroundJobsStore} = await import("../background-jobs/store.js")
     const store = new BackgroundJobsStore({configuration: this.getConfiguration()})
     const databaseIdentifier = store.getDatabaseIdentifier() ?? "default"
+    const frameworkDb = dbs[databaseIdentifier]
+
+    // Only ensure the framework schema when the background-jobs database is actually
+    // part of this migrate operation. When it isn't among the migrated set — e.g.
+    // `db:tenants:migrate <tenant>`, which migrates only tenant databases — the
+    // framework store lives elsewhere (typically the default DB) and was already
+    // ensured by the plain `db:migrate` that precedes it. Reaching into it here would
+    // open a fresh connection to that shared database and re-run the concurrency
+    // reconcile UPDATEs; under `db:tenants:migrate --parallel N` that happens once per
+    // tenant worker, and the concurrent auto-committed UPDATEs on the shared
+    // background_jobs / background_job_concurrency rows InnoDB-deadlock
+    // (ER_LOCK_DEADLOCK). So skip when the framework DB isn't in this set; the runtime
+    // store still creates it lazily if a plain migrate never ran.
+    if (!frameworkDb) return
 
     // Reuse the connection db:migrate already holds for this database; opening a
-    // nested checkout would deadlock a database whose pool is capped at one
-    // connection. When the background-jobs database isn't among the migrated set,
-    // this passes undefined and the store checks out its own (that pool is free).
-    await store.ensureSchema(dbs[databaseIdentifier])
+    // nested checkout would deadlock a database whose pool is capped at one connection.
+    await store.ensureSchema(frameworkDb)
   }
 
   /**

package/build/src/database/advisory-lock-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"advisory-lock-runner.d.ts","sourceRoot":"","sources":["../../../src/database/advisory-lock-runner.js"],"names":[],"mappings":"AAoDA;;;GAGG;AACH;IAoGE;;;;;;;;;OASG;IACH,sCANa,CAAC,QACH,MAAM,YACN,MAAM,OAAO,CAAC,CAAC,CAAC,kBAChB,MAAM,GAAG,IAAI,GACX,OAAO,CAAC,CAAC,CAAC,CAwBtB;IAnID;;;OAGG;IACH,uEAFW;QAAC,aAAa,EAAE,OAAO,qBAAqB,EAAE,OAAO,CAAC;QAAC,kBAAkB,EAAE,MAAM,OAAO,mBAAmB,EAAE,OAAO,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAA;KAAC,EAM3J;IAHC,qDAAkC;IAClC,0BAJ0F,OAAO,mBAAmB,EAAE,OAAO,CAIjF;IAC5C,2BAA4C;IAG9C;;;;;;;OAOG;IACH,iBANa,CAAC,QACH,MAAM,YACN,MAAM,OAAO,CAAC,CAAC,CAAC,SAChB;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAC,GACxD,OAAO,CAAC,CAAC,CAAC,CAYtB;IAED;;;;;;;OAOG;IACH,uBANa,CAAC,QACH,MAAM,YACN,MAAM,OAAO,CAAC,CAAC,CAAC,SAChB;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAYtB;IAED;;;;;OAKG;IACH,kBAJa,CAAC,iDACH;QAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;QAAC,UAAU,EAAE,OAAO,mBAAmB,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GACxH,OAAO,CAAC,CAAC,CAAC,CAQtB;IAED;;;;;;;OAOG;IACH,mBALa,CAAC,iBACH,MAAM,GAAG,IAAI,GAAG,SAAS,YACzB,CAAC,UAAU,EAAE,OAAO,mBAAmB,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7D,OAAO,CAAC,CAAC,CAAC,CAQtB;IAED;;;;;;OAMG;IACH,wBAJa,CAAC,YACH,CAAC,UAAU,EAAE,OAAO,mBAAmB,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7D,OAAO,CAAC,CAAC,CAAC,CAYtB;CAmCF;AAzKD;;GAEG;AACH;IACE;;;;OAIG;IACH,qBAHW,MAAM,YACN;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAMxB;IADC,iBAAoB;CAEvB;AAED;;GAEG;AACH;IACE;;;;OAIG;IACH,qBAHW,MAAM,YACN;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAMxB;IADC,iBAAoB;CAEvB;AA9CD;;GAEG;AACH;IACE;;;;OAIG;IACH,qBAHW,MAAM,YACN;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAMxB;IADC,iBAAoB;CAEvB"}
+{"version":3,"file":"advisory-lock-runner.d.ts","sourceRoot":"","sources":["../../../src/database/advisory-lock-runner.js"],"names":[],"mappings":"AAoDA;;;GAGG;AACH;IAsGE;;;;;;;;;OASG;IACH,sCANa,CAAC,QACH,MAAM,YACN,MAAM,OAAO,CAAC,CAAC,CAAC,kBAChB,MAAM,GAAG,IAAI,GACX,OAAO,CAAC,CAAC,CAAC,CAwBtB;IArID;;;OAGG;IACH,uEAFW;QAAC,aAAa,EAAE,OAAO,qBAAqB,EAAE,OAAO,CAAC;QAAC,kBAAkB,EAAE,MAAM,OAAO,mBAAmB,EAAE,OAAO,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAA;KAAC,EAM3J;IAHC,qDAAkC;IAClC,0BAJ0F,OAAO,mBAAmB,EAAE,OAAO,CAIjF;IAC5C,2BAA4C;IAG9C;;;;;;;OAOG;IACH,iBANa,CAAC,QACH,MAAM,YACN,MAAM,OAAO,CAAC,CAAC,CAAC,SAChB;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAC,GACxD,OAAO,CAAC,CAAC,CAAC,CAYtB;IAED;;;;;;;OAOG;IACH,uBANa,CAAC,QACH,MAAM,YACN,MAAM,OAAO,CAAC,CAAC,CAAC,SAChB;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAYtB;IAED;;;;;OAKG;IACH,kBAJa,CAAC,iDACH;QAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;QAAC,UAAU,EAAE,OAAO,mBAAmB,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GACxH,OAAO,CAAC,CAAC,CAAC,CAQtB;IAED;;;;;;;OAOG;IACH,mBALa,CAAC,iBACH,MAAM,GAAG,IAAI,GAAG,SAAS,YACzB,CAAC,UAAU,EAAE,OAAO,mBAAmB,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7D,OAAO,CAAC,CAAC,CAAC,CAQtB;IAED;;;;;;OAMG;IACH,wBAJa,CAAC,YACH,CAAC,UAAU,EAAE,OAAO,mBAAmB,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7D,OAAO,CAAC,CAAC,CAAC,CActB;CAmCF;AA3KD;;GAEG;AACH;IACE;;;;OAIG;IACH,qBAHW,MAAM,YACN;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAMxB;IADC,iBAAoB;CAEvB;AAED;;GAEG;AACH;IACE;;;;OAIG;IACH,qBAHW,MAAM,YACN;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAMxB;IADC,iBAAoB;CAEvB;AA9CD;;GAEG;AACH;IACE;;;;OAIG;IACH,qBAHW,MAAM,YACN;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAMxB;IADC,iBAAoB;CAEvB"}