velocious 1.0.714 → 1.0.716

package/src/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/src/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/src/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
+  }
+}

package/src/sync/sync-client-registry.js

@@ -28,3 +28,15 @@ export function currentSyncClient() {
 
   return currentClient
 }
+
+/**
+ * Returns the current sync client when one is registered.
+ *
+ * Background jobs that replay the sync queue can legitimately run before an app has
+ * registered its client, or after it cleared it on sign-out. They need a non-throwing
+ * lookup so that state is a no-op instead of a failed job.
+ * @returns {ReturnType<typeof JSON.parse> | null} Current sync client, or null.
+ */
+export function currentSyncClientOrNull() {
+  return currentClient
+}

package/src/utils/bounded-task-runner.js

@@ -0,0 +1,51 @@
+// @ts-check
+
+/**
+ * Runs one callback per item with a bounded number of callbacks in flight.
+ *
+ * Used where a startup pass has to touch many independent records (model
+ * metadata, per-table schema reads) and running them sequentially multiplies the
+ * round-trip latency by the item count, while running them all at once would
+ * open an unbounded number of database connections.
+ */
+export default class BoundedTaskRunner {
+  /**
+   * Runs the worker for every item, keeping at most `concurrency` callbacks in
+   * flight and returning the results in input order.
+   * @template T, R
+   * @param {object} args - Run args.
+   * @param {number} [args.concurrency] - Maximum callbacks in flight.
+   * @param {T[]} args.items - Items to process.
+   * @param {(item: T, index: number) => Promise<R>} args.worker - Callback per item.
+   * @returns {Promise<R[]>} - Results in input order.
+   */
+  static async run({concurrency = 8, items, worker}) {
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+      throw new Error(`Concurrency must be a positive integer but got ${String(concurrency)}`)
+    }
+
+    /** @type {R[]} */
+    const results = new Array(items.length)
+    let nextIndex = 0
+
+    const runNext = async () => {
+      while (nextIndex < items.length) {
+        const index = nextIndex
+
+        nextIndex += 1
+        results[index] = await worker(items[index], index)
+      }
+    }
+
+    /** @type {Promise<void>[]} */
+    const runners = []
+
+    for (let index = 0; index < Math.min(concurrency, items.length); index++) {
+      runners.push(runNext())
+    }
+
+    await Promise.all(runners)
+
+    return results
+  }
+}