velocious 1.0.714 → 1.0.715

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

@@ -1598,6 +1598,9 @@ export default class LocalBackgroundJobsStore {
       failedAtMs: this._numberOrNull(row.failed_at_ms),
       handedOffAtMs: this._numberOrNull(row.handed_off_at_ms),
       handoffId: row.handoff_id === null || row.handoff_id === undefined ? null : String(row.handoff_id),
+      // Local (browser/Expo) dispatch is strictly FIFO and has no priority column,
+      // so every row reports the default priority.
+      priority: 0,
       id: String(row.id),
       jobName: String(row.job_name),
       lastError: row.last_error === null || row.last_error === undefined ? null : String(row.last_error),

package/build/background-jobs/store.js

@@ -41,6 +41,7 @@ import {
  * @property {string} jobId - New job id.
  * @property {string} jobName - Job name.
  * @property {number} maxRetries - Retry cap.
+ * @property {number} priority - Dispatch priority within the queue.
  * @property {string} queue - Queue name.
  * @property {number} scheduledAtMs - Eligibility timestamp.
  * @property {number | null} timeoutMs - Per-job timeout override, or null when omitted.
@@ -137,8 +138,22 @@ export const BACKGROUND_JOB_COUNT_BUCKETS = ["all", "queued", "handed_off", "com
 const COUNTED_JOB_STATUSES = BACKGROUND_JOB_COUNT_BUCKETS.slice(1)
 const MAX_JOB_TIMEOUT_MS = 2_147_483_647
 const JOB_TIMEOUT_VALIDATION_MESSAGE = `background job timeoutMs must be a finite non-positive number or an integer between 1 and ${MAX_JOB_TIMEOUT_MS}`
+const BACKGROUND_JOB_PRIORITY_VALIDATION_MESSAGE = "background job priority must be a non-negative integer"
 const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
 
+/**
+ * Priority a job is demoted to when it is re-queued after a failed attempt.
+ * A retry has already consumed capacity and time, so it must never overtake
+ * work that has not had its first chance yet. Enqueue priorities are validated
+ * to be non-negative integers, which makes `-1` the lowest reachable priority.
+ */
+export const RETRY_BACKGROUND_JOB_PRIORITY = -1
+
+/**
+ * Priority a job gets when the producer does not ask for one.
+ */
+export const DEFAULT_BACKGROUND_JOB_PRIORITY = 0
+
 /**
  * Columns the dashboard is allowed to sort job listings by, mapped to their
  * database column names. Restricting to this set keeps the sort parameter
@@ -1159,6 +1174,12 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       const priorityOrder = this._queuePriorityOrderSql(db)
 
       if (priorityOrder) query = query.order(`${priorityOrder} DESC`)
+
+      // Job-level priority applies inside the queue ranking above. A retry is
+      // stored at RETRY_BACKGROUND_JOB_PRIORITY (-1), so it sorts behind every
+      // first attempt without delaying itself further than the backoff already
+      // does. COALESCE covers rows written before the column existed.
+      query = query.order(`COALESCE(${db.quoteColumn("priority")}, ${DEFAULT_BACKGROUND_JOB_PRIORITY}) DESC`)
     }
 
     query = query
@@ -1965,12 +1986,33 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       jobId: randomUUID(),
       jobName,
       maxRetries: this._normalizeMaxRetries(options?.maxRetries),
+      priority: this._normalizeJobPriority(options),
       queue,
       scheduledAtMs: this._normalizeScheduledAtMs(options?.scheduledAtMs, createdAtMs),
       timeoutMs: this._normalizeJobTimeoutMs(options)
     }
   }
 
+  /**
+   * Normalizes a requested dispatch priority. Priorities order jobs within their
+   * queue on the dispatch path only: higher goes first, and the default keeps
+   * FIFO order. Negative priorities are rejected because the store reserves them
+   * for {@link RETRY_BACKGROUND_JOB_PRIORITY}, which must stay the lowest.
+   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
+   * @returns {number} - Priority.
+   */
+  _normalizeJobPriority(options) {
+    const priority = options?.priority
+
+    if (priority === undefined) return DEFAULT_BACKGROUND_JOB_PRIORITY
+
+    if (typeof priority !== "number" || !Number.isInteger(priority) || priority < 0) {
+      throw VelociousError.safe(BACKGROUND_JOB_PRIORITY_VALIDATION_MESSAGE)
+    }
+
+    return priority
+  }
+
   /**
    * Normalizes a per-job timeout while preserving omitted (worker fallback)
    * separately from explicitly disabled.
@@ -2024,6 +2066,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
         execution_mode: preparedJob.executionMode,
         queue: preparedJob.queue,
         max_retries: preparedJob.maxRetries,
+        priority: preparedJob.priority,
         attempts: 0,
         status: "queued",
         scheduled_at_ms: preparedJob.scheduledAtMs,
@@ -2334,6 +2377,30 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       }
     }
 
+    const priorityLockName = `${MIGRATION_SCOPE}:priority_column`
+    const priorityLockAcquired = await db.acquireAdvisoryLock(priorityLockName)
+
+    if (!priorityLockAcquired) throw new Error("Failed to acquire background jobs priority schema lock")
+
+    try {
+      db.clearSchemaCache()
+      const priorityTable = await db.getTableByNameOrFail(JOBS_TABLE)
+
+      if (!(await priorityTable.getColumnByName("priority"))) {
+        const tableData = new TableData(JOBS_TABLE)
+        tableData.bigint("priority", {null: true})
+        const sqls = await db.alterTableSQLs(tableData)
+
+        for (const sql of sqls) {
+          await db.query(sql)
+        }
+
+        db.clearSchemaCache()
+      }
+    } finally {
+      await db.releaseAdvisoryLock(priorityLockName)
+    }
+
     await this._backfillExecutionModesOnce(db)
     await this._dropForkedColumnOnce(db)
 
@@ -3109,6 +3176,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
 
     if (markOrphaned) transitionedJob.orphanedAtMs = now
     if (shouldRetry) {
+      transitionedJob.priority = RETRY_BACKGROUND_JOB_PRIORITY
       transitionedJob.scheduledAtMs = scheduledAt
     } else if (!markOrphaned) {
       transitionedJob.failedAtMs = now
@@ -3142,7 +3210,14 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     // A retry starts a fresh handoff with a possibly different runner, so the
     // previous child's acceptance evidence must not leak into the next attempt.
     // Terminal failures keep it as historical evidence for the lost attempt.
-    if (shouldRetry) Object.assign(update, this._clearedChildAcceptanceData())
+    if (shouldRetry) {
+      Object.assign(update, this._clearedChildAcceptanceData())
+
+      // Retried work goes to the back of the dispatch order. It has already had
+      // a turn, and letting it overtake first attempts is how a failing producer
+      // starves healthy jobs of the same queue.
+      update.priority = RETRY_BACKGROUND_JOB_PRIORITY
+    }
 
     this._applyOrphanedFailureUpdate({markOrphaned, now, update})
     this._applyFailureStatusUpdate({markOrphaned, now, scheduledAt, shouldRetry, update})
@@ -3211,6 +3286,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       status: normalizeBackgroundJobStatus(row.status ? String(row.status) : "queued"),
       attempts: this._normalizeNumber(row.attempts),
       maxRetries: this._normalizeNumber(row.max_retries),
+      priority: this._normalizeNumber(row.priority) ?? DEFAULT_BACKGROUND_JOB_PRIORITY,
       scheduledAtMs: this._normalizeNumber(row.scheduled_at_ms),
       createdAtMs: this._normalizeNumber(row.created_at_ms),
       handedOffAtMs: this._normalizeNumber(row.handed_off_at_ms),

package/build/background-jobs/types.js

@@ -169,6 +169,7 @@
  * @typedef {object} BackgroundJobOptions
  * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Node defaults to `"pooled"` (a warm, reused local runner process). Browser/Expo local dispatch defaults to and only accepts `"inline"`. `"forked"` runs a Node job in a fresh `child_process.fork()` child, and `"spawned"` in a detached CLI runner.
  * @property {number} [maxRetries] - Max retries for a failed job before it is marked failed.
+ * @property {number} [priority] - Dispatch priority within the queue: higher runs first, default `0`, retries always run last.
  * @property {string} [queue] - Queue name. Defaults to `"default"`. When the queue has a configured cap in `backgroundJobs.queues`, that cap is enforced cluster-wide.
  * @property {string} [concurrencyKey] - Opaque non-empty key used to share a concurrency cap. Overrides any queue-derived cap.
  * @property {number} [maxConcurrency] - Positive integer cap; must be paired with `concurrencyKey`.
@@ -207,6 +208,7 @@
  * @property {BackgroundJobStatus} status - Current job status.
  * @property {number | null} attempts - Failure attempts count.
  * @property {number | null} maxRetries - Max retry attempts.
+ * @property {number} priority - Dispatch priority; `-1` means retried and therefore queued last.
  * @property {number | null} scheduledAtMs - Next scheduled time in ms.
  * @property {number | null} createdAtMs - Creation time in ms.
  * @property {number | null} handedOffAtMs - Time handed to worker in ms.

package/build/database/drivers/base.js

@@ -157,6 +157,7 @@
  */
 
 import BacktraceCleaner from "../../utils/backtrace-cleaner.js"
+import BoundedTaskRunner from "../../utils/bounded-task-runner.js"
 import { getDatabaseAnnotations } from "../annotations.js"
 import { formatDateForDatabase } from "../datetime-storage.js"
 import isDate from "../../utils/is-date.js"
@@ -911,6 +912,65 @@ export default class VelociousDatabaseDriversBase {
     return await this._cachedSchemaMetadata(`table:${tableName}:${metadataName}`, callback)
   }
 
+  /**
+   * Seeds schema metadata that was loaded in one batch for many tables, so a later
+   * per-table read resolves from the cache instead of issuing its own query.
+   * @template T
+   * @param {string} tableName - Table name.
+   * @param {string} metadataName - Metadata name.
+   * @param {T} value - Already-resolved metadata.
+   * @returns {void}
+   */
+  seedTableSchemaMetadata(tableName, metadataName, value) {
+    if (!this._schemaCacheEnabled()) return
+
+    this._schemaCache.set(`table:${tableName}:${metadataName}`, Promise.resolve(value))
+  }
+
+  /**
+   * Loads column metadata for several tables, combining the reads into one query
+   * when the driver can answer for all of them at once and seeding the per-table
+   * cache so the models that follow initialize without querying.
+   * @param {Array<import("./base-table.js").default>} tables - Tables to load columns for.
+   * @param {{concurrency?: number}} [args] - Concurrency for drivers that can only read per table.
+   * @returns {Promise<void>}
+   */
+  async prefetchTableColumns(tables, {concurrency = 8} = {}) {
+    if (!this._schemaCacheEnabled()) return
+    if (tables.length === 0) return
+
+    const batchedColumns = await this.batchTableColumns(tables)
+
+    if (batchedColumns) {
+      for (const [tableName, columns] of batchedColumns) {
+        this.seedTableSchemaMetadata(tableName, "columns", columns)
+      }
+
+      return
+    }
+
+    await BoundedTaskRunner.run({
+      concurrency,
+      items: tables,
+      worker: async (table) => {
+        await table.getColumns()
+      }
+    })
+  }
+
+  /**
+   * Batched column metadata for many tables at once. Drivers whose engine cannot
+   * answer for several tables in one statement return null, leaving the caller to
+   * read them per table.
+   * @param {Array<import("./base-table.js").default>} tables - Tables to load columns for.
+   * @returns {Promise<Map<string, Array<import("./base-column.js").default>> | null>} - Columns keyed by table name, or null when unsupported.
+   */
+  async batchTableColumns(tables) {
+    void tables
+
+    return null
+  }
+
   /**
    * Runs schema cache return value.
    * @param {ReturnType<typeof JSON.parse>} value - Cached value.

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

@@ -2,6 +2,7 @@
 
 import AlterTable from "./sql/alter-table.js"
 import Base from "../base.js"
+import Column from "./column.js"
 import CreateDatabase from "./sql/create-database.js"
 import CreateIndex from "./sql/create-index.js"
 import CreateTable from "./sql/create-table.js"
@@ -516,6 +517,64 @@ export default class VelociousDatabaseDriversMssql extends Base{
     })
   }
 
+  /**
+   * Reads column metadata for many tables in one query. The per-table read of the
+   * same three-way `INFORMATION_SCHEMA` join is one of the slowest things a boot
+   * does against the legacy SQL Server, so it is worth combining regardless of the
+   * number of tables.
+   * @param {Array<import("../base-table.js").default>} tables - Tables to load columns for.
+   * @returns {Promise<Map<string, Array<import("../base-column.js").default>>>} - Columns keyed by table name.
+   */
+  async batchTableColumns(tables) {
+    /** @type {Map<string, Array<import("../base-column.js").default>>} */
+    const columnsByTable = new Map()
+
+    if (tables.length === 0) return columnsByTable
+
+    const schema = this.getArgs()?.schema || this.getArgs()?.sqlConfig?.options?.schema
+    const schemaClause = schema
+      ? ` AND columns.[TABLE_SCHEMA] = ${this.quote(schema)}`
+      : " AND columns.[TABLE_SCHEMA] = SCHEMA_NAME()"
+    const tablesByName = new Map(tables.map((table) => [table.getName(), table]))
+    const tableNamesSql = [...tablesByName.keys()].map((tableName) => this.quote(tableName)).join(", ")
+    const rows = await this.query(`
+      SELECT
+        columns.*,
+        COLUMNPROPERTY(object_id(columns.TABLE_SCHEMA + '.' + columns.TABLE_NAME), columns.COLUMN_NAME, 'IsIdentity') AS isIdentity,
+        CASE WHEN keyColumnUsage.COLUMN_NAME IS NOT NULL THEN 1 ELSE 0 END AS isPrimaryKey
+      FROM [INFORMATION_SCHEMA].[COLUMNS] AS columns
+      LEFT JOIN [INFORMATION_SCHEMA].[TABLE_CONSTRAINTS] AS tableConstraints ON
+        tableConstraints.CONSTRAINT_TYPE = 'PRIMARY KEY' AND
+        tableConstraints.TABLE_CATALOG = columns.TABLE_CATALOG AND
+        tableConstraints.TABLE_SCHEMA = columns.TABLE_SCHEMA AND
+        tableConstraints.TABLE_NAME = columns.TABLE_NAME
+      LEFT JOIN [INFORMATION_SCHEMA].[KEY_COLUMN_USAGE] AS keyColumnUsage ON
+        keyColumnUsage.CONSTRAINT_CATALOG = tableConstraints.CONSTRAINT_CATALOG AND
+        keyColumnUsage.CONSTRAINT_SCHEMA = tableConstraints.CONSTRAINT_SCHEMA AND
+        keyColumnUsage.CONSTRAINT_NAME = tableConstraints.CONSTRAINT_NAME AND
+        keyColumnUsage.TABLE_CATALOG = columns.TABLE_CATALOG AND
+        keyColumnUsage.TABLE_SCHEMA = columns.TABLE_SCHEMA AND
+        keyColumnUsage.TABLE_NAME = columns.TABLE_NAME AND
+        keyColumnUsage.COLUMN_NAME = columns.COLUMN_NAME
+      WHERE columns.TABLE_NAME IN (${tableNamesSql})${schemaClause}
+      ORDER BY columns.TABLE_NAME, columns.ORDINAL_POSITION
+    `)
+
+    for (const row of rows) {
+      const tableName = /** @type {string} */ (row.TABLE_NAME)
+      const table = tablesByName.get(tableName)
+
+      if (!table) continue
+
+      const columns = columnsByTable.get(tableName) || []
+
+      columns.push(new Column(table, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)))
+      columnsByTable.set(tableName, columns)
+    }
+
+    return columnsByTable
+  }
+
   /**
    * Keeps constraint toggles and cleanup inside each physical SQL Server
    * request so a pool cannot split lifecycle ownership across sessions.

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

@@ -2,6 +2,7 @@
 
 import AlterTable from "./sql/alter-table.js"
 import Base from "../base.js"
+import Column from "./column.js"
 import CreateDatabase from "./sql/create-database.js"
 import CreateIndex from "./sql/create-index.js"
 import CreateTable from "./sql/create-table.js"
@@ -765,6 +766,56 @@ export default class VelociousDatabaseDriversMysql extends Base{
     })
   }
 
+  /**
+   * Reads column metadata for many tables in one query. `SHOW FULL COLUMNS` only
+   * describes a single table, but `information_schema.COLUMNS` carries the same
+   * fields, so the result is aliased to the shape `Column` already reads.
+   *
+   * `NULLIF(COLUMN_DEFAULT, 'NULL')` compensates for MariaDB reporting a SQL NULL
+   * default as the literal string 'NULL', where `SHOW FULL COLUMNS` reports NULL.
+   * Verified column-for-column against `SHOW FULL COLUMNS` on a 44-table MariaDB
+   * schema; the only divergence was that sentinel.
+   * @param {Array<import("../base-table.js").default>} tables - Tables to load columns for.
+   * @returns {Promise<Map<string, Array<import("../base-column.js").default>>>} - Columns keyed by table name.
+   */
+  async batchTableColumns(tables) {
+    /** @type {Map<string, Array<import("../base-column.js").default>>} */
+    const columnsByTable = new Map()
+
+    if (tables.length === 0) return columnsByTable
+
+    const tablesByName = new Map(tables.map((table) => [table.getName(), table]))
+    const tableNamesSql = [...tablesByName.keys()].map((tableName) => this.quote(tableName)).join(", ")
+    const rows = await this.query(`
+      SELECT
+        TABLE_NAME AS tableName,
+        COLUMN_NAME AS Field,
+        COLUMN_TYPE AS Type,
+        IS_NULLABLE AS \`Null\`,
+        COLUMN_KEY AS \`Key\`,
+        NULLIF(COLUMN_DEFAULT, 'NULL') AS \`Default\`,
+        EXTRA AS Extra,
+        COLUMN_COMMENT AS Comment
+      FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (${tableNamesSql})
+      ORDER BY TABLE_NAME, ORDINAL_POSITION
+    `)
+
+    for (const row of rows) {
+      const tableName = /** @type {string} */ (row.tableName)
+      const table = tablesByName.get(tableName)
+
+      if (!table) continue
+
+      const columns = columnsByTable.get(tableName) || []
+
+      columns.push(new Column(table, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)))
+      columnsByTable.set(tableName, columns)
+    }
+
+    return columnsByTable
+  }
+
   /**
    * Runs structure sql.
    * @returns {Promise<string | null>} - Resolves with SQL string.

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

@@ -3,6 +3,7 @@
 import AlterTable from "./sql/alter-table.js"
 import wait from "awaitery/build/wait.js"
 import Base from "../base.js"
+import Column from "./column.js"
 import { Client, types as pgTypes } from "pg"
 import CreateDatabase from "./sql/create-database.js"
 import CreateIndex from "./sql/create-index.js"
@@ -329,6 +330,10 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return insert.toSql()
   }
 
+  /**
+   * Runs get tables.
+   * @returns {Promise<Array<import("../base-table.js").default>>} - Resolves with the tables.
+   */
   async getTables() {
     return await this._cachedSchemaMetadata("tables", async () => {
       const result = await this.query("SELECT * FROM information_schema.tables WHERE table_catalog = CURRENT_DATABASE() AND table_schema = 'public'")
@@ -344,6 +349,62 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     })
   }
 
+  /**
+   * Reads column metadata for many tables in one query instead of one catalog
+   * join per table.
+   * @param {Array<import("../base-table.js").default>} tables - Tables to load columns for.
+   * @returns {Promise<Map<string, Array<import("../base-column.js").default>>>} - Columns keyed by table name.
+   */
+  async batchTableColumns(tables) {
+    /** @type {Map<string, Array<import("../base-column.js").default>>} */
+    const columnsByTable = new Map()
+
+    if (tables.length === 0) return columnsByTable
+
+    const tablesByName = new Map(tables.map((table) => [table.getName(), table]))
+    const tableNamesSql = [...tablesByName.keys()].map((tableName) => this.quote(tableName)).join(", ")
+    const rows = await this.query(`
+      SELECT
+        columns.*,
+        CASE WHEN key_column_usage.column_name IS NOT NULL THEN 1 ELSE 0 END AS is_primary_key,
+        col_description((columns.table_schema || '.' || columns.table_name)::regclass, columns.ordinal_position) AS column_comment
+
+      FROM
+        information_schema.columns AS columns
+
+      LEFT JOIN information_schema.table_constraints AS table_constraints ON
+        table_constraints.table_name = columns.table_name AND
+        table_constraints.table_schema = columns.table_schema AND
+        table_constraints.constraint_type = 'PRIMARY KEY'
+
+      LEFT JOIN information_schema.key_column_usage AS key_column_usage ON
+        key_column_usage.constraint_name = table_constraints.constraint_name AND
+        key_column_usage.table_schema = table_constraints.table_schema AND
+        key_column_usage.table_name = columns.table_name AND
+        key_column_usage.column_name = columns.column_name
+
+      WHERE
+        columns.table_catalog = CURRENT_DATABASE() AND
+        columns.table_schema = 'public' AND
+        columns.table_name IN (${tableNamesSql})
+      ORDER BY columns.table_name, columns.ordinal_position
+    `)
+
+    for (const row of rows) {
+      const tableName = /** @type {string} */ (row.table_name)
+      const table = tablesByName.get(tableName)
+
+      if (!table) continue
+
+      const columns = columnsByTable.get(tableName) || []
+
+      columns.push(new Column(table, /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)))
+      columnsByTable.set(tableName, columns)
+    }
+
+    return columnsByTable
+  }
+
   /**
    * Truncates all eligible tables in one PostgreSQL request.
    * @param {Array<import("../base-table.js").default>} tables - Eligible tables.

package/build/database/initializer-from-require-context.js

@@ -10,7 +10,15 @@
  */
 
 import Logger from "../logger.js"
+import BoundedTaskRunner from "../utils/bounded-task-runner.js"
 import restArgsError from "../utils/rest-args-error.js"
+import SchemaMetadataPrefetcher from "./schema-metadata-prefetcher.js"
+
+/**
+ * How many model classes initialize at once. Metadata comes from the prefetched
+ * schema cache, so this is CPU-bound attribute mapping rather than database work.
+ */
+const MODEL_INITIALIZATION_CONCURRENCY = 8
 
 export default class VelociousDatabaseInitializerFromRequireContext {
   /**
@@ -34,6 +42,9 @@ export default class VelociousDatabaseInitializerFromRequireContext {
   async initialize({configuration, ...restArgs}) {
     restArgsError(restArgs)
 
+    /** @type {Array<typeof import("./record/index.js").default>} */
+    const modelClasses = []
+
     for (const fileName of this.requireContext.keys()) {
       const modelClassImport = this.requireContext(fileName)
 
@@ -50,14 +61,27 @@ export default class VelociousDatabaseInitializerFromRequireContext {
         continue
       }
 
-      if (!modelClass.getEagerLoadRecordMetadata()) {
-        modelClass.registerRecordClass({configuration})
-        await this._bestEffortInitializeDeferredModel({configuration, modelClass})
-        continue
-      }
-
-      await this._initializeModelRecord({configuration, modelClass})
+      modelClass.registerRecordClass({configuration})
+      modelClasses.push(modelClass)
     }
+
+    // One catalog read per database instead of one per model, shared by every
+    // model initialized below through the driver's schema cache.
+    await new SchemaMetadataPrefetcher({configuration, logger: this.logger}).prefetch({modelClasses})
+
+    await BoundedTaskRunner.run({
+      concurrency: MODEL_INITIALIZATION_CONCURRENCY,
+      items: modelClasses,
+      worker: async (modelClass) => {
+        if (!modelClass.getEagerLoadRecordMetadata()) {
+          await this._bestEffortInitializeDeferredModel({configuration, modelClass})
+
+          return
+        }
+
+        await this._initializeModelRecord({configuration, modelClass})
+      }
+    })
   }
 
   /**

package/build/database/schema-metadata-prefetcher.js

@@ -0,0 +1,108 @@
+// @ts-check
+
+import Logger from "../logger.js"
+
+/**
+ * Loads table and column metadata for a whole set of model classes up front.
+ *
+ * Model initialization otherwise reads each table's columns on its own, which
+ * turns a boot into one catalog query per model (and per HTTP worker process).
+ * Drivers that can answer for many tables in one statement are asked to do so;
+ * the resulting columns are seeded into the driver's per-table schema cache, so
+ * the initialization pass that follows resolves without querying at all.
+ */
+export default class SchemaMetadataPrefetcher {
+  /**
+   * Builds a prefetcher for one configuration.
+   * @param {object} args - Prefetcher args.
+   * @param {import("../configuration.js").default} args.configuration - Configuration owning the database connections.
+   * @param {number} [args.concurrency] - Concurrency for drivers that can only read one table per query.
+   * @param {import("../logger.js").default} [args.logger] - Logger for debug output.
+   */
+  constructor({configuration, concurrency = 8, logger}) {
+    this.configuration = configuration
+    this.concurrency = concurrency
+    this.logger = logger || new Logger(this)
+  }
+
+  /**
+   * Prefetches column metadata for every model class that has a reachable table.
+   *
+   * Models whose table or connection is unavailable are skipped: their
+   * initialization stays deferred and will initialize lazily on first use, which
+   * is the same contract the per-model initialization applies.
+   * @param {{modelClasses: Array<typeof import("./record/index.js").default>}} args - Model classes to prefetch for.
+   * @returns {Promise<void>}
+   */
+  async prefetch({modelClasses}) {
+    /** @type {Map<import("./drivers/base.js").default, Map<string, import("./drivers/base-table.js").default>>} */
+    const tablesByDriver = new Map()
+
+    for (const modelClass of modelClasses) {
+      const table = await this.tableFor(modelClass)
+
+      if (!table) continue
+
+      const driver = table.getDriver()
+      let tables = tablesByDriver.get(driver)
+
+      if (!tables) {
+        tables = new Map()
+        tablesByDriver.set(driver, tables)
+      }
+
+      tables.set(table.getName(), table)
+
+      // Translated models initialize their translation class as part of the same
+      // startup pass, so its table has to be part of the batch as well - otherwise
+      // every translated model still costs its own catalog read.
+      const translationTable = await this.tableByName(driver, modelClass.getTranslationsTableName())
+
+      if (translationTable) tables.set(translationTable.getName(), translationTable)
+    }
+
+    const startedAt = Date.now()
+    let tableCount = 0
+
+    for (const [driver, tables] of tablesByDriver) {
+      await driver.prefetchTableColumns([...tables.values()], {concurrency: this.concurrency})
+      tableCount += tables.size
+    }
+
+    void this.logger.debug(() => ["schema metadata prefetched", {
+      databases: tablesByDriver.size,
+      durationMs: Date.now() - startedAt,
+      tables: tableCount
+    }])
+  }
+
+  /**
+   * Resolves a model's table without initializing its record metadata.
+   * @param {typeof import("./record/index.js").default} modelClass - Model class to resolve a table for.
+   * @returns {Promise<import("./drivers/base-table.js").default | null>} Table, or null when it is not reachable.
+   */
+  async tableFor(modelClass) {
+    try {
+      const driver = modelClass.connection({enforceTenantDatabaseScope: false})
+
+      return await this.tableByName(driver, modelClass.tableName())
+    } catch (error) {
+      // A model whose database is unreachable - or whose table is optional and
+      // absent - stays deferred rather than failing startup; it initializes
+      // lazily on first use.
+      void this.logger.debug(() => [`Leaving ${modelClass.name} out of schema prefetch`, error])
+
+      return null
+    }
+  }
+
+  /**
+   * Looks a table up in the driver's table list without throwing when absent.
+   * @param {import("./drivers/base.js").default} driver - Driver owning the table.
+   * @param {string} tableName - Table name to resolve.
+   * @returns {Promise<import("./drivers/base-table.js").default | null>} Table, or null when it does not exist.
+   */
+  async tableByName(driver, tableName) {
+    return await driver.getTableByName(tableName, {throwError: false}) || null
+  }
+}