velocious 1.0.691 → 1.0.693

package/README.md

@@ -50,6 +50,7 @@
 * AbortSignal-driven MySQL/MariaDB query cancellation for raw, model, and cross-tenant aggregate queries (see [docs/database-query-cancellation.md](docs/database-query-cancellation.md))
 * Optional built-in debug endpoint for inspecting server and database connection state (see [docs/debug-endpoint.md](docs/debug-endpoint.md))
 * Optional built-in API manifest endpoint describing every registered frontend-model resource as human- and machine-readable JSON (see [docs/api-manifest-endpoint.md](docs/api-manifest-endpoint.md))
+* Built-in MCP server command `velocious mcp` exposing every registered frontend-model command as MCP tools for AI clients, dispatched through the frontend-model controller with the app's own ability resolver (see [docs/mcp-server.md](docs/mcp-server.md))
 * Backend record attachments with filesystem, S3, native callback, bounded Node path-input persistence, and model-declared client sync policy (see [docs/attachments.md](docs/attachments.md))
 
 # Setup
@@ -975,6 +976,10 @@ Frontend-model command transport preserves `Date` and `undefined` by encoding th
 
 Frontend-model commands raise an `Error` when the backend responds with `{status: "error"}` (using `errorMessage` when present), so unauthorized or missing-record update/find/destroy responses fail fast in frontend code.
 
+## Route catch-all
+
+Applications can declare their own 404 response in the routes file with `route.catchAll({action: "notFound", controller: "errors"})` instead of hand-wiring a route resolver hook. Unmatched requests then resolve to the given controller/action through the standard controller lookup, without tenant/ability/connection resolution. See [docs/route-catch-all.md](docs/route-catch-all.md).
+
 ## Route resolver hooks
 
 Libraries can hook unresolved routes and hijack them before Velocious falls back to the built-in 404 controller.
@@ -2905,7 +2910,7 @@ backgroundJobs: {
 
 `background-jobs-main` registers a built-in `velocious:prune-terminal-background-jobs` job on the scheduler when retention is enabled, so pruning runs as an ordinary scheduled/queued job (it needs a worker, appears in the job tables, and is bounded to one non-overlapping run). See [docs/background-jobs.md](docs/background-jobs.md#retention-pruning-old-job-rows).
 
-Candidate discovery is ordered by terminal timestamp and job id and runs outside the singleton count-revision mutation lock. Only the short transaction that revalidates and deletes the selected ids publishes a count delta, using the database's actual affected-row count, so a slow sweep or a concurrent pruner does not block enqueue acknowledgements or double-decrement counts. Queued and in-flight jobs never match retention deletion. Composite retention-index activation is intentionally staged for a later release because MariaDB online index DDL conflicts with schema inspection by older serving generations.
+Candidate discovery is ordered by terminal timestamp and job id and runs outside the singleton count-revision mutation lock. Only the short transaction that revalidates and deletes the selected ids publishes a count delta, using the database's actual affected-row count, so a slow sweep or a concurrent pruner does not block enqueue acknowledgements or double-decrement counts. Queued and in-flight jobs never match retention deletion. Composite retention indexes `(status, completed_at_ms, id)`, `(status, failed_at_ms, id)`, and `(status, orphaned_at_ms, id)` are installed once during routine readiness and recorded in the internal-migrations ledger; MariaDB schema-metadata reads that collide with that online index build are retried with bounded backoff so the DDL does not block enqueue acknowledgements.
 
 ## Dashboard
 

package/build/background-jobs/scheduled-enqueue-bound.js

@@ -0,0 +1,18 @@
+// @ts-check
+
+import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "../database/advisory-lock-bound.js"
+
+/**
+ * Default bound for one scheduled background-job enqueue attempt.
+ *
+ * A durable enqueue that never settles (wedged DB connection, advisory lock held by a dead process)
+ * used to poison its schedule key forever: `BackgroundJobsScheduler` kept the in-flight promise in
+ * `pendingEnqueuesByJobKey`, every later tick returned early, and shutdown could never drain. The
+ * bound makes that stall observable and self-healing instead of silent.
+ *
+ * It is deliberately larger than the advisory-lock acquisition bound, because a scheduled enqueue
+ * waits for a lock *and then* inserts. Keeping the enqueue watchdog outside the lock bound lets the
+ * precise `AdvisoryLockTimeoutError` surface first — naming the lock that is actually stuck —
+ * instead of a generic enqueue timeout that hides which lock caused the stall.
+ * @type {number} */
+export const DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS = DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS + 5 * 60 * 1000

package/build/background-jobs/scheduled-enqueue-timeout-error.js

@@ -0,0 +1,25 @@
+// @ts-check
+
+import {TimeoutError} from "awaitery/build/timeout.js"
+
+/** Typed failure for a scheduled background-job enqueue that never settled within its bound. */
+export default class ScheduledBackgroundJobEnqueueTimeoutError extends TimeoutError {
+  /**
+   * Builds a scheduled-enqueue timeout error without job arguments or connection details.
+   * @param {object} args - Safe timeout context.
+   * @param {string} args.jobKey - Schedule key whose enqueue stalled.
+   * @param {string} args.jobName - Resolved job class name.
+   * @param {number} args.scheduledEnqueueTimeoutMs - Configured bound that expired.
+   * @param {TimeoutError} [args.cause] - Original watchdog timeout.
+   */
+  constructor({jobKey, jobName, scheduledEnqueueTimeoutMs, cause}) {
+    super(`Scheduled background job enqueue did not settle within ${scheduledEnqueueTimeoutMs}ms`, cause ? {cause} : undefined)
+
+    this.name = "ScheduledBackgroundJobEnqueueTimeoutError"
+    /** @type {"BACKGROUND_JOB_SCHEDULED_ENQUEUE_TIMEOUT"} */
+    this.code = "BACKGROUND_JOB_SCHEDULED_ENQUEUE_TIMEOUT"
+    this.jobKey = jobKey
+    this.jobName = jobName
+    this.scheduledEnqueueTimeoutMs = scheduledEnqueueTimeoutMs
+  }
+}

package/build/background-jobs/scheduler.js

@@ -1,5 +1,8 @@
 // @ts-check
 
+import {DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS} from "./scheduled-enqueue-bound.js"
+import ScheduledBackgroundJobEnqueueTimeoutError from "./scheduled-enqueue-timeout-error.js"
+
 import Logger from "../logger.js"
 import {nextCronFireDate, parseCronExpression} from "./cron-expression.js"
 
@@ -25,6 +28,12 @@ const DURATION_MULTIPLIERS = {
   weeks: 7 * 24 * 60 * 60 * 1000
 }
 
+// The watchdog below is internal machinery, not a schedule timer. Capturing the
+// platform timers at module load keeps them out of a caller's schedule-timer
+// observation, so bounding an enqueue never appears as an extra scheduled job.
+const armWatchdogTimer = globalThis.setTimeout
+const cancelWatchdogTimer = globalThis.clearTimeout
+
 /**
  * Runs the parseScheduledDuration helper.
  * @param {number | string} value - Duration value.
@@ -73,6 +82,8 @@ export default class BackgroundJobsScheduler {
     this.configuration = configuration
     this.enqueueJob = enqueueJob
     this.logger = new Logger(this)
+    /** @type {number | null} - Bound (ms) for one scheduled enqueue attempt; `null` disables the bound. */
+    this.scheduledEnqueueTimeoutMs = this._resolveScheduledEnqueueTimeoutMs()
     /**
      * Narrows the runtime value to the documented type.
      * @type {Array<ReturnType<typeof setInterval>>} */
@@ -270,17 +281,123 @@ export default class BackgroundJobsScheduler {
       // of identical scheduled jobs when the queue backed up. Dedup is by job identity (see the
       // store), so the job keeps its queue-derived concurrency cap. A schedule can opt out with
       // `deduplicateWhileQueued: false`.
-      await this.enqueueJob({
-        args: Array.isArray(jobConfiguration.args) ? jobConfiguration.args : [],
-        jobClass: jobConfiguration.class,
+      await this._withScheduledEnqueueTimeout({
         jobKey,
-        options: {deduplicateWhileQueued: true, ...(jobConfiguration.options || {})}
+        jobName: jobConfiguration.class.jobName(),
+        run: async () => {
+          await this.enqueueJob({
+            args: Array.isArray(jobConfiguration.args) ? jobConfiguration.args : [],
+            jobClass: jobConfiguration.class,
+            jobKey,
+            options: {deduplicateWhileQueued: true, ...(jobConfiguration.options || {})}
+          })
+        }
       })
     } catch (error) {
+      if (error instanceof ScheduledBackgroundJobEnqueueTimeoutError) {
+        this._reportScheduledEnqueueStall({error, jobKey})
+
+        return
+      }
+
       await this.logger.error(() => ["Failed to enqueue scheduled background job", {jobKey, jobName: jobConfiguration.class.jobName()}, error])
     }
   }
 
+  /**
+   * Runs one durable enqueue attempt under the scheduled-enqueue bound.
+   *
+   * The bound is applied with a local race rather than `awaitery`'s `timeout()`:
+   * that helper starts its callback through `Promise.resolve().then(...)`, which
+   * would defer every scheduled enqueue by a microtask and change the tick
+   * semantics callers rely on. Here the attempt starts synchronously, and the
+   * watchdog uses the module-captured timers so it is never observable as a
+   * schedule timer. Only the watchdog raises the typed timeout error, so a
+   * timeout raised inside the enqueue itself keeps its own error path.
+   * @param {object} args - Options.
+   * @param {string} args.jobKey - Schedule key.
+   * @param {string} args.jobName - Resolved job class name.
+   * @param {() => Promise<void>} args.run - Enqueue attempt.
+   * @returns {Promise<void>} - Resolves when the attempt settles within the bound.
+   */
+  async _withScheduledEnqueueTimeout({jobKey, jobName, run}) {
+    const timeoutMs = this.scheduledEnqueueTimeoutMs
+    /** @type {Promise<void>} */
+    let attempt
+
+    try {
+      attempt = Promise.resolve(run())
+    } catch (error) {
+      attempt = Promise.reject(/** @type {Error} */ (error))
+    }
+
+    if (timeoutMs === null) return await attempt
+
+    /**
+     * Rejects the watchdog promise when the bound expires.
+     * @type {(error: Error) => void} */
+    let rejectScheduledEnqueueTimeout = () => {}
+    const watchdog = new Promise((_, reject) => { rejectScheduledEnqueueTimeout = reject })
+    /**
+     * Watchdog timer handle.
+     * @type {ReturnType<typeof armWatchdogTimer>} */
+    const watchdogId = armWatchdogTimer(() => {
+      rejectScheduledEnqueueTimeout(new ScheduledBackgroundJobEnqueueTimeoutError({
+        jobKey,
+        jobName,
+        scheduledEnqueueTimeoutMs: timeoutMs
+      }))
+    }, timeoutMs)
+
+    try {
+      return await Promise.race([attempt, watchdog])
+    } finally {
+      cancelWatchdogTimer(watchdogId)
+    }
+  }
+
+  /**
+   * Surfaces a scheduled enqueue whose store call never settled. Without this report the only
+   * symptom is a schedule that silently stops enqueueing after one wedged call.
+   * @param {object} args - Options.
+   * @param {Error} args.error - Timeout error.
+   * @param {string} args.jobKey - Schedule key.
+   * @returns {void}
+   */
+  _reportScheduledEnqueueStall({error, jobKey}) {
+    const payload = {
+      context: {
+        jobKey,
+        scheduledEnqueueTimeoutMs: this.scheduledEnqueueTimeoutMs,
+        stage: "background-jobs-scheduled-enqueue-stall"
+      },
+      error
+    }
+
+    void this.logger.error(() => ["Scheduled background job enqueue stalled", payload.context, error])
+
+    const errorEvents = typeof this.configuration?.getErrorEvents === "function" ? this.configuration.getErrorEvents() : undefined
+
+    if (!errorEvents) return
+
+    errorEvents.emit("framework-error", payload)
+    errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+  }
+
+  /**
+   * Resolves the scheduled-enqueue bound from configuration.
+   * @returns {number | null} - Bound in milliseconds, or `null` for an unbounded wait.
+   */
+  _resolveScheduledEnqueueTimeoutMs() {
+    const backgroundJobsConfig = typeof this.configuration?.getBackgroundJobsConfig === "function" ? this.configuration.getBackgroundJobsConfig() : undefined
+    const configured = backgroundJobsConfig?.scheduledEnqueueTimeoutMs
+
+    if (configured === null) return null
+    if (typeof configured === "number" && configured > 0) return configured
+
+    return DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS
+  }
+
   /**
    * Runs normalize every.
    * @param {NonNullable<import("../configuration-types.js").ScheduledBackgroundJobConfiguration["every"]>} every - Every config (caller must guarantee not undefined).

package/build/background-jobs/store.js

@@ -116,6 +116,17 @@ const SCHEDULE_KEYS_TABLE = "background_job_schedule_keys"
 const SCHEDULE_ORDER_WATERMARKS_TABLE = "background_job_schedule_order_watermarks"
 const SCHEDULE_ORDER_WATERMARK_MIGRATION_VERSION = "20260911120000"
 const SCHEDULE_HISTORY_ORDER_INDEX = "index_background_jobs_schedule_history_order"
+// Composite retention indexes bound the terminal-status discovery scan to the expired
+// (status, terminal_timestamp) range, so retention candidate pages stay cheap on
+// multi-million-row tables. Activation was staged separately from the lock-scope fix
+// because MariaDB online index DDL makes concurrent metadata inspection fail with
+// ER_WARN_I_S_SKIPPED_TABLE; the driver now outlasts that skip with a bounded retry.
+const RETENTION_INDEX_MIGRATION_VERSION = "20261012120000"
+const RETENTION_INDEX_DEFINITIONS = [
+  {columns: ["status", "completed_at_ms", "id"], name: "index_background_jobs_completed_retention"},
+  {columns: ["status", "failed_at_ms", "id"], name: "index_background_jobs_failed_retention"},
+  {columns: ["status", "orphaned_at_ms", "id"], name: "index_background_jobs_orphaned_retention"}
+]
 const CONCURRENCY_TABLE = "background_job_concurrency"
 const COUNTS_REVISION_TABLE = "background_job_count_revisions"
 const COUNTS_REVISION_KEY = "counts"
@@ -2155,6 +2166,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       await this._ensureScheduleKeysTable(db)
       await this._ensureConcurrencyTable(db)
       await this._ensureCountRevisionTable(db)
+      await this._ensureRetentionIndexesOnce(db)
 
       return
     }
@@ -2360,6 +2372,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     await this._ensureJobTimeoutColumn(db)
     await this._ensureChildAcceptanceColumns(db)
     await this._ensureJobsTableIndexesOnce(db)
+    await this._ensureRetentionIndexesOnce(db)
   }
 
   /**
@@ -2451,6 +2464,54 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     }
   }
 
+  /**
+   * Idempotently creates the ordered composite retention indexes. An index
+   * with the expected name but a different column order is a manual-repair
+   * situation and fails readiness loudly instead of being rebuilt or
+   * re-recorded; the migration ledger is written only once every expected
+   * index exists with its exact ordered columns.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when all retention indexes exist.
+   */
+  async _ensureRetentionIndexesOnce(db) {
+    const migrationVersion = RETENTION_INDEX_MIGRATION_VERSION
+    const migrationKey = this._migrationKey(migrationVersion)
+
+    if (await this._hasMigration(db, migrationVersion)) return
+
+    const acquired = await db.acquireAdvisoryLock(migrationKey)
+
+    if (!acquired) throw new Error("Failed to acquire background jobs retention index lock")
+
+    try {
+      if (await this._hasMigration(db, migrationVersion)) return
+
+      db.clearSchemaCache()
+      const table = await db.getTableByNameOrFail(JOBS_TABLE)
+      const existingIndexColumns = new Map(
+        (await table.getIndexes()).map((index) => [index.getName(), index.getColumnNames()])
+      )
+
+      for (const {columns, name} of RETENTION_INDEX_DEFINITIONS) {
+        const existingColumns = existingIndexColumns.get(name)
+
+        if (existingColumns) {
+          if (existingColumns.join(",") === columns.join(",")) continue
+          throw new Error(`Background jobs retention index ${name} exists with unexpected columns: ${existingColumns.join(",")}`)
+        }
+
+        for (const sql of await db.createIndexSQLs({columns, ifNotExists: db.getType() === "sqlite", name, tableName: JOBS_TABLE})) {
+          await db.query(sql)
+        }
+      }
+
+      db.clearSchemaCache()
+      await this._recordMigration(db, migrationVersion)
+    } finally {
+      await db.releaseAdvisoryLock(migrationKey)
+    }
+  }
+
   /**
    * Idempotently adds the per-job wall-clock timeout to existing job tables.
    * @param {import("../database/drivers/base.js").default} db - Database connection.

package/build/cli/commands/mcp.js

@@ -0,0 +1,7 @@
+import BaseCommand from "../base-command.js"
+
+export default class VelociousCliCommandsMcp extends BaseCommand{
+  async execute() {
+    return await this.getConfiguration().getEnvironmentHandler().cliCommandsMcp(this)
+  }
+}

package/build/cli/index.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-const COMMAND_VALUE_OPTIONS = new Set(["--generation", "--initial-generation-state", "--lifecycle-socket", "--phase", "--socket", "--tenant"])
+const COMMAND_VALUE_OPTIONS = new Set(["--generation", "--initial-generation-state", "--lifecycle-socket", "--phase", "--request-context", "--socket", "--tenant"])
 
 export default class VelociousCli {
   /**

package/build/configuration-types.js

@@ -68,6 +68,7 @@
 
 /**
  * @typedef {object} DatabaseConfigurationType
+ * @property {number | null} [advisoryLockAcquireTimeoutMs] - Bound (ms) a blocking advisory-lock acquisition waits for a contended lock before reporting failure. Default: `900000` (15 minutes). `null` opts out and restores the driver's indefinite wait. A per-call `timeoutMs` argument always overrides this.
  * @property {string} [databaseCharset] - Default character set applied by `db:create` via mysql/mariadb `CREATE DATABASE ... CHARACTER SET`. Distinct from `charset`, which is the client connection charset forwarded to the mysql2 driver.
  * @property {string} [databaseCollation] - Default collation applied by `db:create` via mysql/mariadb `CREATE DATABASE ... COLLATE`.
  * @property {string} [database] - Database name for this connection.
@@ -93,6 +94,7 @@
  * @property {boolean} [readOnly] - Whether writes should be blocked for this database.
  * @property {string} [schema] - Default schema for unqualified table lookups (MSSQL).
  * @property {boolean} [schemaCache] - Whether schema metadata should be cached on the driver. Defaults to true.
+ * @property {number} [schemaMetadataRetryDeadlineMs] - Bounded deadline (ms) for outlasting a cached schema-metadata read the server skipped because concurrent online DDL is modifying the table. Defaults to 60000.
  * @property {object} [record] - Record-level configuration.
  * @property {boolean} [record.transactions] - Whether record operations should use transactions.
  * @property {boolean} [reset] - Whether to reset the database on startup.
@@ -221,6 +223,7 @@
  *   Priorities may be any number, including negative to sink a queue below the
  *   default. Jobs within the same priority keep FIFO (`scheduled_at`, then
  *   `created_at`) order. Default: `{}` (no queue caps, all queues priority `0`).
+ * @property {number | null} [scheduledEnqueueTimeoutMs] - Bounds one scheduled enqueue attempt in the main process. A durable enqueue that never settles (wedged DB connection, contended advisory lock) would otherwise keep its schedule key permanently in flight, so every later tick skipped itself and shutdown could never drain. On timeout the attempt is reported as `background-jobs-scheduled-enqueue-stall` and the key clears for the next tick. Default: 20 minutes — deliberately 5 minutes above `advisoryLockAcquireTimeoutMs` so the precise lock error surfaces first. `null` opts out.
  * @property {BackgroundJobsDispatchStrategy} [dispatchStrategy] - How the main process
  *   detects new work. Defaults to `"beacon"` (event-driven). Set to `"polling"`
  *   to restore the legacy fixed-interval poll.

package/build/configuration.js

@@ -26,6 +26,7 @@ import UUID from "pure-uuid"
 import translate from "gettext-universal/build/src/translate.js"
 import Ability from "./authorization/ability.js"
 import BackgroundJobsAdapter from "./background-jobs/adapter.js"
+import {DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS} from "./background-jobs/scheduled-enqueue-bound.js"
 import DatabaseOperation from "./database/operation.js"
 import { initializeAuditedModelRelationships } from "./database/record/auditing.js"
 import EventEmitter from "./utils/event-emitter.js"
@@ -1707,6 +1708,20 @@ export default class VelociousConfiguration {
     const drainStoreOperationTimeoutMs = typeof configured.drainStoreOperationTimeoutMs === "number" && configured.drainStoreOperationTimeoutMs >= 1
       ? configured.drainStoreOperationTimeoutMs
       : 60_000
+    // `null` is an explicit opt-out of the scheduled-enqueue bound. A present
+    // but non-positive number is a mistake, not an opt-out, so it falls back to
+    // the framework default rather than silently disabling the watchdog.
+    const scheduledEnqueueTimeoutMs = "scheduledEnqueueTimeoutMs" in configured
+      ? (
+        configured.scheduledEnqueueTimeoutMs === null ?
+          null
+        : (
+          typeof configured.scheduledEnqueueTimeoutMs === "number" && configured.scheduledEnqueueTimeoutMs > 0 ?
+            configured.scheduledEnqueueTimeoutMs
+          : DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS
+        )
+      )
+      : DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS
     const queues = configured.queues && typeof configured.queues === "object" ? configured.queues : {}
     // An explicit config value wins over the env var — including `null`/`0`,
     // which disable the backstop even when the environment sets a default.
@@ -1732,7 +1747,7 @@ export default class VelociousConfiguration {
 
     const jobClasses = this.getBackgroundJobClasses()
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, scheduledEnqueueTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
   }
 
   /**

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

@@ -0,0 +1,16 @@
+// @ts-check
+
+/**
+ * Default bound for one blocking advisory-lock acquisition.
+ *
+ * A blocking `acquireAdvisoryLock(name)` call with no explicit timeout used to park a pooled
+ * connection for the driver's indefinite wait (MySQL/MariaDB: one year). One wedged holder — a
+ * killed process, a runner that died while holding the lock, a connection that never returned —
+ * then convoyed every later caller on the same lock name: the queue kept growing while every pool
+ * connection sat in MariaDB's `User lock` state and no dispatch happened anywhere.
+ *
+ * The default is deliberately far above any contention observed in healthy production operation, so
+ * a legitimate lock handover is never cut off, while a wedged holder stops stealing pool capacity
+ * forever. Pass `null` explicitly to opt back in to the indefinite wait.
+ * @type {number} */
+export const DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS = 15 * 60 * 1000

package/build/database/drivers/base.js

@@ -160,6 +160,7 @@ import BacktraceCleaner from "../../utils/backtrace-cleaner.js"
 import { getDatabaseAnnotations } from "../annotations.js"
 import { formatDateForDatabase } from "../datetime-storage.js"
 import isDate from "../../utils/is-date.js"
+import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "../advisory-lock-bound.js"
 import Logger from "../../logger.js"
 import Query from "../query/index.js"
 import QueryAbortedError from "../query-aborted-error.js"
@@ -183,6 +184,12 @@ const SCHEMA_INVALIDATION_SCAN_LIMIT = 8192
 /** Maximum checkout-name characters inspected by retry diagnostics. */
 const OPERATION_NAME_SCAN_LIMIT = 1024
 const REDACTED_DIAGNOSTIC_LABEL = "[REDACTED]"
+/** First backoff between retries of a schema-metadata read blocked by concurrent online DDL. */
+const SCHEMA_METADATA_RETRY_INITIAL_DELAY_MS = 250
+/** Largest backoff between retries of a schema-metadata read blocked by concurrent online DDL. */
+const SCHEMA_METADATA_RETRY_MAX_DELAY_MS = 2000
+/** Default bounded deadline for outlasting a concurrent online-DDL metadata skip. */
+const SCHEMA_METADATA_RETRY_DEADLINE_MS = 60000
 
 /**
  * Builds a non-reversible, stable SQL fingerprint without retaining SQL text. Literal spelling is
@@ -777,6 +784,52 @@ export default class VelociousDatabaseDriversBase {
     return this.getArgs().schemaCache !== false
   }
 
+  /**
+   * Runs schema metadata retry deadline ms.
+   * @returns {number} - Bounded deadline for outlasting transient schema-metadata contention.
+   */
+  _schemaMetadataRetryDeadlineMs() {
+    const configured = this.getArgs().schemaMetadataRetryDeadlineMs
+
+    return typeof configured === "number" ? configured : SCHEMA_METADATA_RETRY_DEADLINE_MS
+  }
+
+  /**
+   * Whether an error raised by a schema-metadata read is transient contention that a bounded
+   * retry can outlast. Drivers override this for their own contention signatures; the default
+   * treats every failure as final so only drivers that prove the transient shape retry it.
+   * @param {unknown} _error - Error raised by a schema-metadata read.
+   * @returns {boolean} - Whether the read may be retried.
+   */
+  _isTransientSchemaMetadataError(_error) {
+    return false
+  }
+
+  /**
+   * Runs a schema-metadata read, retrying transient concurrent-DDL contention until the bounded
+   * deadline. Non-transient failures and exhausted deadlines propagate the original error.
+   * @template T
+   * @param {() => Promise<T>} callback - Cache-miss schema read.
+   * @returns {Promise<T>} - Resolves with the read result.
+   */
+  async _withSchemaMetadataDdlRetry(callback) {
+    const deadlineMs = this._schemaMetadataRetryDeadlineMs()
+    const startedAt = Date.now()
+    let delayMs = SCHEMA_METADATA_RETRY_INITIAL_DELAY_MS
+
+    for (;;) {
+      try {
+        return await callback()
+      } catch (error) {
+        if (!this._isTransientSchemaMetadataError(error)) throw error
+        if (Date.now() - startedAt + delayMs > deadlineMs) throw error
+
+        await wait(delayMs)
+        delayMs = Math.min(delayMs * 2, SCHEMA_METADATA_RETRY_MAX_DELAY_MS)
+      }
+    }
+  }
+
   /**
    * Runs cached schema metadata.
    * @template T
@@ -785,7 +838,7 @@ export default class VelociousDatabaseDriversBase {
    * @returns {Promise<T>} - Resolves with the cached metadata.
    */
   async _cachedSchemaMetadata(cacheKey, callback) {
-    if (!this._schemaCacheEnabled()) return await callback()
+    if (!this._schemaCacheEnabled()) return await this._withSchemaMetadataDdlRetry(callback)
 
     const existingPromise = this._schemaCache.get(cacheKey)
 
@@ -793,7 +846,7 @@ export default class VelociousDatabaseDriversBase {
       return /** @type {T} */ (this._schemaCacheReturnValue(await existingPromise))
     }
 
-    const promise = (async () => await callback())()
+    const promise = (async () => await this._withSchemaMetadataDdlRetry(callback))()
 
     this._schemaCache.set(cacheKey, promise)
 
@@ -2876,17 +2929,37 @@ export default class VelociousDatabaseDriversBase {
    * same name and let you serialize functionality without blocking readers
    * or writers that do not participate in the same lock.
    * @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` blocks forever, and an omitted value uses the database's `advisoryLockAcquireTimeoutMs` or the framework default.
    * @returns {Promise<boolean>} - Resolves to true when the lock has been acquired, false if the timeout elapsed.
    */
   async acquireAdvisoryLock(name, args = {}) {
-    const acquired = await this._acquireAdvisoryLock(name, args)
+    const acquired = await this._acquireAdvisoryLock(name, {timeoutMs: this.advisoryLockAcquireTimeoutMs(args)})
 
     if (acquired) this._trackAdvisoryLock(name)
 
     return acquired
   }
 
+  /**
+   * Resolves the wait bound for one advisory-lock acquisition.
+   * An explicit `timeoutMs` — including an explicit `null` opt-out — always
+   * wins. Otherwise the database configuration's `advisoryLockAcquireTimeoutMs`
+   * applies, and a null there opts out too. Only when neither is configured does
+   * the framework default bound the wait.
+   * @param {{timeoutMs?: number | null}} [args] - Acquisition options from the caller.
+   * @returns {number | null} - Wait bound in milliseconds, or `null` for an indefinite wait.
+   */
+  advisoryLockAcquireTimeoutMs(args = {}) {
+    if (args.timeoutMs !== undefined) return args.timeoutMs
+
+    const configured = this.getArgs()?.advisoryLockAcquireTimeoutMs
+
+    if (configured === null) return null
+    if (typeof configured === "number" && configured >= 0) return configured
+
+    return DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS
+  }
+
   /**
    * Driver-specific blocking advisory-lock acquisition hook.
    * @abstract

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

@@ -723,6 +723,29 @@ export default class VelociousDatabaseDriversMysql extends Base{
     return insert.toSql()
   }
 
+  /**
+   * MariaDB skips information-schema/SHOW reads for a table whose definition is being modified
+   * by concurrent online DDL (ER_WARN_I_S_SKIPPED_TABLE). The build completes in seconds, so the
+   * skip is transient contention that the bounded schema-metadata retry can outlast. Query
+   * helpers wrap the driver error, so the code is searched through the cause chain.
+   * @param {unknown} error - Error raised by a schema-metadata read.
+   * @returns {boolean} - Whether the read hit concurrent-DDL metadata contention.
+   */
+  _isTransientSchemaMetadataError(error) {
+    let currentError = /** @type {{code?: string, cause?: unknown} | undefined} */ (
+      /** @type {unknown} */ (error)
+    )
+
+    for (let depth = 0; depth < 5 && currentError; depth++) {
+      if (currentError.code === "ER_WARN_I_S_SKIPPED_TABLE") return true
+      currentError = /** @type {{code?: string, cause?: unknown} | undefined} */ (
+        /** @type {unknown} */ (currentError.cause)
+      )
+    }
+
+    return false
+  }
+
   /**
    * Runs get tables.
    * @returns {Promise<Array<import("../base-table.js").default>>} - Resolves with the tables.

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

@@ -171,7 +171,7 @@ export default async function query(pool, sql, {signal} = {}) {
           connection.release()
         }
 
-        reject(new Error(`Query failed because of ${error}: ${sql}`))
+        reject(new Error(`Query failed because of ${error}: ${sql}`, {cause: error}))
 
         return
       }

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

@@ -22,6 +22,11 @@ import Update from "./sql/update.js"
 
 const PG_TIMESTAMP_WITHOUT_TIMEZONE_OID = 1114
 
+/** Smallest wait between `pg_try_advisory_lock` probes; preserves the historical 50ms cadence for short bounds. */
+const PGSQL_ADVISORY_LOCK_POLL_MIN_INTERVAL_MS = 50
+/** Largest wait between `pg_try_advisory_lock` probes; keeps a long bounded wait from probing tens of thousands of times. */
+const PGSQL_ADVISORY_LOCK_POLL_MAX_INTERVAL_MS = 2000
+
 pgTypes.setTypeParser(PG_TIMESTAMP_WITHOUT_TIMEZONE_OID, (value) => new Date(`${value.replace(" ", "T")}Z`))
 
 export default class VelociousDatabaseDriversPgsql extends Base{
@@ -425,14 +430,32 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return signed.toString()
   }
 
+  /**
+   * Resolves the `pg_try_advisory_lock` probe cadence for one bounded wait.
+   *
+   * `pg_advisory_lock` has no native timeout, so a bounded acquisition polls. Scaling the interval
+   * with the bound keeps the historical 50ms cadence — and its fast acquisition — for the short
+   * explicit `timeoutMs` values callers already pass, while a long framework default stays
+   * responsive without turning one contended lock into tens of thousands of probe queries.
+   * @param {number} timeoutMs - Bounded wait in milliseconds.
+   * @returns {number} - Probe interval in milliseconds.
+   */
+  static advisoryLockPollIntervalMs(timeoutMs) {
+    return Math.min(
+      Math.max(Math.floor(timeoutMs / 100), PGSQL_ADVISORY_LOCK_POLL_MIN_INTERVAL_MS),
+      PGSQL_ADVISORY_LOCK_POLL_MAX_INTERVAL_MS
+    )
+  }
+
   /**
    * Blocks until a PostgreSQL session-level advisory lock is acquired on
    * this connection. Implemented via `pg_advisory_lock(bigint)`, which has
    * no native timeout — the `timeoutMs` argument is emulated by racing a
-   * `pg_try_advisory_lock` poll loop so callers on MySQL and Postgres see
-   * the same contract.
+   * `pg_try_advisory_lock` poll loop so callers on MySQL and Postgres see the
+   * same contract. The poll interval backs off to a cap so a long bounded wait
+   * does not turn one contended lock into thousands of probe queries.
    * @param {string} name - Lock name.
-   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks forever.
+   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null` or negative blocks forever, and an omitted value uses the database's `advisoryLockAcquireTimeoutMs` or the framework default.
    * @returns {Promise<boolean>} - True if the lock was acquired, false if the timeout elapsed.
    */
   async _acquireAdvisoryLock(name, {timeoutMs} = {}) {
@@ -444,7 +467,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     }
 
     const deadline = Date.now() + timeoutMs
-    const pollIntervalMs = 50
+    const pollIntervalMs = VelociousDatabaseDriversPgsql.advisoryLockPollIntervalMs(timeoutMs)
 
     while (true) {
       if (await this._tryAcquireAdvisoryLock(name)) return true