velocious 1.0.581 → 1.0.583

package/README.md

@@ -23,8 +23,8 @@
 * Gap-less positional lists with automatic reordering via `actsAsList`, including models with numeric, string, or UUID primary keys (see [docs/acts-as-list.md](docs/acts-as-list.md))
 * Rails-style nested-attribute writes on frontend-model `save()` (see [docs/nested-attributes.md](docs/nested-attributes.md))
 * Async-aware test-data factories with inherited traits, graph-first native association autosave, metadata-aware override precedence, callbacks, sequences, and linting (see [docs/factories.md](docs/factories.md))
-* Per-row association counts via `.withCount(...)`, including cohort-safe intersected filters and safe batching of structurally identical aggregates, on frontend and backend queries (see [docs/with-count.md](docs/with-count.md))
-* Consumer-defined per-row SQL aggregates/computations via `.queryData(...)`, with compatible projections sharing a roundtrip while preserving declared alias-overwrite order, on frontend and backend queries (see [docs/query-data.md](docs/query-data.md))
+* Per-row association counts via `.withCount(...)`, including cohort-safe intersected filters, safe batching of structurally identical aggregates, and automatic IN-list chunking for large parent sets, on frontend and backend queries (see [docs/with-count.md](docs/with-count.md))
+* Consumer-defined per-row SQL aggregates/computations via `.queryData(...)`, with compatible projections sharing a roundtrip while preserving declared alias-overwrite order and automatic IN-list chunking for large parent sets, on frontend and backend queries (see [docs/query-data.md](docs/query-data.md))
 * Per-record ability checks via `.abilities(...)` on frontend queries + `record.can(action)` (see [docs/abilities.md](docs/abilities.md))
 * Translated model attributes with current-locale relationship sorting (see [docs/translations.md](docs/translations.md))
 * Cross-process broadcast bus for `broadcastToChannel` via `velocious beacon`, including background job runner processes (see [docs/beacon.md](docs/beacon.md))
@@ -290,10 +290,26 @@ npx velocious test --groups=4 --group-number=2
 
 # Combine with tags
 npx velocious test --groups=3 --group-number=1 --tag fast
+
+# Prefer recorded file durations when balancing groups
+npx velocious test --groups=4 --group-number=1 --timing-manifest=tmp/test-timings.json
 ```
 
 Files are distributed using a greedy load-balancing algorithm. Each file is
-weighted by its spec directory (`system/` = 20, `frontend-models/` = 10,
+primarily weighted by a positive finite duration from the optional timing
+manifest. Manifest keys are normalized project-relative test paths using `/`
+separators:
+
+```json
+{
+  "spec/system/sign-in-spec.js": 42.7,
+  "spec/controller/accounts-spec.js": 8.1
+}
+```
+
+Files absent from the manifest, unknown files, invalid duration values, and
+unreadable or malformed JSON all fall back to the existing deterministic
+heuristic. The heuristic weights files by spec directory (`system/` = 20, `frontend-models/` = 10,
 `controller/` = 3, default = 1) with a 2x multiplier for `.browser-spec.js`
 files. The heaviest files are assigned first to the group with the least
 accumulated weight, producing balanced wall-clock times across groups.

package/build/configuration-types.js

@@ -75,6 +75,8 @@
  * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so a whole structure SQL dump loads in one round-trip via `StructureSqlLoader`. Off by default; ordinary queries otherwise reject stacked statements.
  * @property {number} [maxRowsPerInsert] - Maximum rows per `INSERT ... VALUES (...), (...), ...` statement generated by `Record.insertMultiple`. Defaults to 500.
  * @property {number} [maxInsertSqlBytes] - Maximum serialized SQL size, in bytes, for a single `INSERT ... VALUES (...), (...), ...` statement. Defaults to 1 MiB (1048576).
+ * @property {number} [maxInClauseValues] - Maximum values in a single `IN (...)` cohort used by preloads, association counts, and queryData aggregates. Defaults to 999.
+ * @property {number} [maxQuerySqlBytes] - Maximum serialized SQL size, in bytes, for a single cohort query used by preloads, association counts, and queryData aggregates. Defaults to 1 MiB (1048576).
  * @property {string} [password] - Password for the database user.
  * @property {number} [port] - Database port.
  * @property {string} [primaryKeyType] - Default type for implicit migration primary keys and references. Defaults to `uuid`.

package/build/database/drivers/base.js

@@ -118,6 +118,14 @@
  * @property {string[]} updateColumns - Columns to update on conflict.
  */
 
+/**
+ * SqlTokenResult type.
+ * @typedef {object} SqlTokenResult
+ * @property {boolean} incomplete - Whether the scan hit its bound before finishing trivia/token parsing.
+ * @property {string | undefined} token - Lowercased token when parsing completed; undefined when no token was found.
+ * @property {number} index - Index immediately after the parsed token or trivia.
+ */
+
 import BacktraceCleaner from "../../utils/backtrace-cleaner.js"
 import { getDatabaseAnnotations } from "../annotations.js"
 import { formatDateForDatabase } from "../datetime-storage.js"
@@ -134,6 +142,11 @@ import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/build/wait.js"
 import {optionalPositiveInteger} from "typanic"
 
+/** Maximum characters inspected when building the debug SQL preview. */
+const SQL_PREVIEW_SCAN_LIMIT = 4096
+/** Maximum characters inspected when deciding whether a statement invalidates schema metadata. */
+const SCHEMA_INVALIDATION_SCAN_LIMIT = 8192
+
 /**
  * Marks a callback failure that happened after the owning transaction was durably committed.
  * The public transaction boundary unwraps it before deadlock classification.
@@ -793,10 +806,82 @@ export default class VelociousDatabaseDriversBase {
     return optionalPositiveInteger(this.getArgs().maxInsertSqlBytes, "maxInsertSqlBytes") ?? 1048576
   }
 
+  /**
+   * Maximum values in a single `IN (...)` cohort used by preloads, association
+   * counts, and queryData aggregates. The default stays under SQLite's default
+   * `MAX_VARIABLE_NUMBER` compile-time limit.
+   *
+   * Override via `maxInClauseValues` in the database configuration.
+   * @returns {number} - Maximum values per IN clause cohort.
+   */
+  maxInClauseValues() {
+    return optionalPositiveInteger(this.getArgs().maxInClauseValues, "maxInClauseValues") ?? 999
+  }
+
+  /**
+   * Maximum serialized SQL size, in bytes, for a single cohort query used by
+   * preloads, association counts, and queryData aggregates. Cohort chunking
+   * stops when the next value would push the generated string over this threshold.
+   *
+   * Override via `maxQuerySqlBytes` in the database configuration.
+   * @returns {number} - Maximum bytes per cohort query.
+   */
+  maxQuerySqlBytes() {
+    return optionalPositiveInteger(this.getArgs().maxQuerySqlBytes, "maxQuerySqlBytes") ?? 1048576
+  }
+
+  /**
+   * Splits `values` into cohort chunks that stay within both `maxCount` and
+   * `maxBytes` while preserving order.
+   *
+   * A chunk always contains at least one value, even if that single value exceeds
+   * the byte limit, so progress is guaranteed.
+   * @template T
+   * @param {Array<T>} values - Values to chunk.
+   * @param {(values: Array<T>) => string} buildSql - Function that builds the full SQL for a candidate chunk.
+   * @param {{maxCount?: number, maxBytes?: number}} [options] - Chunking bounds.
+   * @returns {Array<Array<T>>} - Value cohorts.
+   */
+  chunkValues(values, buildSql, {maxCount = this.maxInClauseValues(), maxBytes = this.maxQuerySqlBytes()} = {}) {
+    if (values.length === 0) return []
+
+    /**
+     * Chunks.
+     * @type {Array<Array<T>>} */
+    const chunks = []
+    /**
+     * Current chunk.
+     * @type {Array<T>} */
+    let currentChunk = []
+
+    for (const value of values) {
+      const candidate = [...currentChunk, value]
+      const candidateBytes = Buffer.byteLength(buildSql(candidate), "utf8")
+
+      if (currentChunk.length > 0 && (candidate.length > maxCount || candidateBytes > maxBytes)) {
+        chunks.push(currentChunk)
+        currentChunk = [value]
+      } else {
+        currentChunk = candidate
+      }
+    }
+
+    if (currentChunk.length > 0) {
+      chunks.push(currentChunk)
+    }
+
+    return chunks
+  }
+
   /**
    * Splits `rows` into chunks that stay within both {@link maxRowsPerInsert}
    * and {@link maxInsertSqlBytes} while preserving order.
    *
+   * Byte accounting is incremental: `buildSql` is called once with `[]` to
+   * measure the statement prefix and once per row with `[row]` to measure the
+   * row's values tuple. This keeps chunking linear in the number of rows
+   * instead of rebuilding the full multi-row SQL for every candidate.
+   *
    * A chunk always contains at least one row, even if that single row exceeds
    * the byte limit, so progress is guaranteed.
    * @param {Array<Array<ReturnType<typeof JSON.parse>>>} rows - Rows to insert.
@@ -811,6 +896,9 @@ export default class VelociousDatabaseDriversBase {
     const prefix = `${emptySql} VALUES `
     const baseByteLength = Buffer.byteLength(prefix, "utf8")
 
+    /**
+     * Current chunk.
+     * @type {Array<Array<ReturnType<typeof JSON.parse>>>} */
     let currentChunk = []
     let currentBytes = 0
 
@@ -1604,13 +1692,25 @@ export default class VelociousDatabaseDriversBase {
     }
   }
 
+  /**
+   * Returns a bounded prefix of `sql` for lightweight diagnostic scanning.
+   * @param {string} sql - SQL string.
+   * @param {number} limit - Maximum code units to inspect.
+   * @returns {string} - Prefix of `sql`.
+   */
+  _diagnosticSqlPrefix(sql, limit) {
+    return sql.length <= limit ? sql : sql.slice(0, limit)
+  }
+
   /**
    * Runs debug sql preview.
    * @param {string} sql - SQL to preview.
    * @returns {string} - Normalized truncated SQL preview for diagnostics.
    */
   _debugSqlPreview(sql) {
-    return sql
+    const prefix = this._diagnosticSqlPrefix(sql, SQL_PREVIEW_SCAN_LIMIT)
+
+    return prefix
       .replace(/\s+/g, " ")
       .trim()
       .slice(0, 500)
@@ -1664,25 +1764,121 @@ export default class VelociousDatabaseDriversBase {
       .replace(/"/g, "'")
   }
 
+  /**
+   * Reads the next SQL token starting at `startIndex`, skipping leading trivia
+   * (BOM, whitespace, block comments, line comments). If the scan cannot finish
+   * skipping trivia before `limit`, the result is marked incomplete so callers
+   * can conservatively treat the statement as schema-invalidating.
+   * @param {string} sql - SQL string.
+   * @param {number} startIndex - Index to start scanning.
+   * @param {number} limit - Maximum absolute index to scan while skipping leading trivia.
+   * @returns {SqlTokenResult} - Token result.
+   */
+  _readSqlToken(sql, startIndex, limit) {
+    let i = startIndex
+    const len = sql.length
+
+    while (i < len && i < limit) {
+      const char = sql[i]
+
+      if (char === "\ufeff" || /\s/.test(char)) {
+        i++
+        continue
+      }
+
+      if (char === "/" && sql[i + 1] === "*") {
+        const close = sql.indexOf("*/", i + 2)
+
+        if (close === -1 || close + 2 > limit) {
+          return {incomplete: true, index: i, token: undefined}
+        }
+
+        i = close + 2
+        continue
+      }
+
+      if (char === "-" && sql[i + 1] === "-") {
+        const newline = sql.indexOf("\n", i + 2)
+
+        if (newline === -1) {
+          return {incomplete: false, index: len, token: undefined}
+        }
+
+        if (newline + 1 > limit) {
+          return {incomplete: true, index: i, token: undefined}
+        }
+
+        i = newline + 1
+        continue
+      }
+
+      let token = ""
+
+      while (i < len) {
+        const c = sql[i]
+
+        if (/\s/.test(c) || c === "\ufeff") break
+        if (c === "/" && sql[i + 1] === "*") break
+        if (c === "-" && sql[i + 1] === "-") break
+
+        token += c
+        i++
+      }
+
+      return {incomplete: false, token: token.toLowerCase(), index: i}
+    }
+
+    if (i >= len) {
+      return {incomplete: false, index: len, token: undefined}
+    }
+
+    return {incomplete: true, index: i, token: undefined}
+  }
+
   /**
    * Runs schema cache invalidating sql.
    * @param {string} sql - SQL string.
    * @returns {boolean} - Whether the SQL should invalidate schema metadata.
    */
   _schemaCacheInvalidatingSql(sql) {
-    const normalized = sql
-      .trim()
-      .replace(/^\ufeff/, "")
-      .replace(/\/\*[\s\S]*?\*\//g, " ")
-      .replace(/--[^\n]*(\n|$)/g, " ")
-      .replace(/\s+/g, " ")
-      .toLowerCase()
+    const first = this._readSqlToken(sql, 0, SCHEMA_INVALIDATION_SCAN_LIMIT)
 
-    if (!normalized) return false
-    if (/^(create|alter|drop|rename)\b/.test(normalized)) return true
-    if (/^comment\s+on\b/.test(normalized)) return true
-    if (/^exec(?:ute)?\s+sp_rename\b/.test(normalized)) return true
-    if (/^if\b[\s\S]*\bbegin\s+(create|alter|drop|rename)\b/.test(normalized)) return true
+    if (first.incomplete) return true
+
+    const firstToken = first.token
+
+    if (!firstToken) return false
+    if (/^(create|alter|drop|rename)$/.test(firstToken)) return true
+
+    if (firstToken === "comment") {
+      const next = this._readSqlToken(sql, first.index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+      return next.incomplete || next.token === "on"
+    }
+
+    if (firstToken === "exec" || firstToken === "execute") {
+      const next = this._readSqlToken(sql, first.index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+      return next.incomplete || next.token === "sp_rename"
+    }
+
+    if (firstToken === "if") {
+      let index = first.index
+
+      while (true) {
+        const result = this._readSqlToken(sql, index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+        if (result.incomplete) return true
+        if (!result.token) return false
+        if (result.token === "begin") {
+          const ddlResult = this._readSqlToken(sql, result.index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+          return ddlResult.incomplete || /^(create|alter|drop|rename)$/.test(ddlResult.token || "")
+        }
+
+        index = result.index
+      }
+    }
 
     return false
   }

package/build/database/query/preloader/belongs-to.js

@@ -87,25 +87,27 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
     if (foreignKeyValues.size > 0) {
       await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration(), modelsToLoad[0])
 
-      /**
-       * Where args.
-       * @type {Record<string, string | number | Array<string | number>>} */
-      const whereArgs = {}
+      // Build the query once with scope and selection, then clone it per cohort so
+      // the IN-list size stays within driver limits without rebuilding shared state.
+      let baseQuery = preloadQueryForModel(modelsToLoad, targetModelClass)
 
-      whereArgs[primaryKey] = [...foreignKeyValues]
+      baseQuery = this.relationship.applyScope(baseQuery)
+      baseQuery = this.selection.applyToQuery({query: baseQuery, targetModelClass, mappingColumns: [primaryKey]})
 
-      // Load target models to be preloaded on the given models
-      let query = preloadQueryForModel(modelsToLoad, targetModelClass).where(whereArgs)
+      const driver = baseQuery.driver
+      const cohorts = driver.chunkValues([...foreignKeyValues], (chunk) => baseQuery.clone().where({[primaryKey]: chunk}).toSql())
 
-      query = this.relationship.applyScope(query)
-      query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [primaryKey]})
+      for (const cohort of cohorts) {
+        const cohortQuery = baseQuery.clone().where({[primaryKey]: cohort})
+        const foundTargetModels = await cohortQuery.toArray()
 
-      targetModels = await query.toArray()
+        targetModels.push(...foundTargetModels)
 
-      for (const targetModel of targetModels) {
-        const primaryKeyValue = /** @type {string | number} */ (targetModel.readColumn(primaryKey))
+        for (const targetModel of foundTargetModels) {
+          const primaryKeyValue = /** @type {string | number} */ (targetModel.readColumn(primaryKey))
 
-        targetModelsById[primaryKeyValue] = targetModel
+          targetModelsById[primaryKeyValue] = targetModel
+        }
       }
     }
 
@@ -205,33 +207,32 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
 
       await ensureModelClassInitialized(targetModelClass, configuration, this.models[0])
 
-      /**
-       * Where args.
-       * @type {Record<string, string | number | Array<string | number>>} */
-      const whereArgs = {}
+      let baseQuery = preloadQueryForModel(this.models, targetModelClass)
 
-      whereArgs[primaryKey] = [...foreignKeyValuesByType[targetType]]
+      baseQuery = this.relationship.applyScope(baseQuery)
+      baseQuery = this.selection.applyToQuery({query: baseQuery, targetModelClass, mappingColumns: [primaryKey]})
 
-      let query = preloadQueryForModel(this.models, targetModelClass).where(whereArgs)
+      const driver = baseQuery.driver
+      const cohorts = driver.chunkValues([...foreignKeyValuesByType[targetType]], (chunk) => baseQuery.clone().where({[primaryKey]: chunk}).toSql())
 
-      query = this.relationship.applyScope(query)
-      query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [primaryKey]})
+      targetModelsByTypeAndId[targetType] = {}
 
-      const foundTargetModels = await query.toArray()
+      for (const cohort of cohorts) {
+        const cohortQuery = baseQuery.clone().where({[primaryKey]: cohort})
+        const foundTargetModels = await cohortQuery.toArray()
 
-      targetModels.push(...foundTargetModels)
+        targetModels.push(...foundTargetModels)
 
-      const className = targetModelClass.getModelName()
+        const className = targetModelClass.getModelName()
 
-      if (!targetModelsByClassName[className]) targetModelsByClassName[className] = []
-      targetModelsByClassName[className].push(...foundTargetModels)
+        if (!targetModelsByClassName[className]) targetModelsByClassName[className] = []
+        targetModelsByClassName[className].push(...foundTargetModels)
 
-      targetModelsByTypeAndId[targetType] = {}
+        for (const targetModel of foundTargetModels) {
+          const primaryKeyValue = /** @type {string | number} */ (targetModel.readColumn(primaryKey))
 
-      for (const targetModel of foundTargetModels) {
-        const primaryKeyValue = /** @type {string | number} */ (targetModel.readColumn(primaryKey))
-
-        targetModelsByTypeAndId[targetType][primaryKeyValue] = targetModel
+          targetModelsByTypeAndId[targetType][primaryKeyValue] = targetModel
+        }
       }
     }
 

package/build/database/query/preloader/has-many.js

@@ -155,10 +155,11 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
       modelsByPrimaryKeyValue[primaryKeyValue].push(model)
     }
 
-    // Step 1: Query the through table to build parent→target ID mapping
-    const throughModels = await preloadQueryForModel(modelsToLoad, throughModelClass)
-      .where({[throughForeignKey]: [...modelsPrimaryKeyValues]})
-      .toArray()
+    // Step 1: Query the through table to build parent→target ID mapping.
+    // Chunk the parent PK cohort so the through query's IN-list stays bounded.
+    const throughBaseQuery = preloadQueryForModel(modelsToLoad, throughModelClass)
+    const throughDriver = throughBaseQuery.driver
+    const throughCohorts = throughDriver.chunkValues([...modelsPrimaryKeyValues], (chunk) => throughBaseQuery.clone().where({[throughForeignKey]: chunk}).toSql())
 
     /**
      * Parent to target ids.
@@ -170,28 +171,43 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
      * @type {Set<string | number>} */
     const allTargetIds = new Set()
 
-    for (const throughModel of throughModels) {
-      const parentId = /** @type {string | number} */ (throughModel.readColumn(throughForeignKey))
-      const throughId = /** @type {string | number} */ (throughModel.readColumn(throughModelClass.primaryKey()))
+    for (const cohort of throughCohorts) {
+      const throughQuery = throughBaseQuery.clone().where({[throughForeignKey]: cohort})
+      const throughModels = await throughQuery.toArray()
 
-      if (!(parentId in parentToTargetIds)) parentToTargetIds[parentId] = []
+      for (const throughModel of throughModels) {
+        const parentId = /** @type {string | number} */ (throughModel.readColumn(throughForeignKey))
+        const throughId = /** @type {string | number} */ (throughModel.readColumn(throughModelClass.primaryKey()))
 
-      parentToTargetIds[parentId].push(throughId)
-      allTargetIds.add(throughId)
+        if (!(parentId in parentToTargetIds)) parentToTargetIds[parentId] = []
+
+        parentToTargetIds[parentId].push(throughId)
+        allTargetIds.add(throughId)
+      }
     }
 
-    // Step 2: Load target models by the foreign key that points to the through table
+    // Step 2: Load target models by the foreign key that points to the through table.
+    // Chunk the target ID cohort so the target query's IN-list stays bounded.
     /**
      * Target models.
      * @type {import("../../record/index.js").default[]} */
     let targetModels = []
 
     if (allTargetIds.size > 0) {
-      let query = preloadQueryForModel(modelsToLoad, targetModelClass).where({[targetForeignKey]: [...allTargetIds]})
+      let targetBaseQuery = preloadQueryForModel(modelsToLoad, targetModelClass)
+
+      targetBaseQuery = this.relationship.applyScope(targetBaseQuery)
+      targetBaseQuery = this.selection.applyToQuery({query: targetBaseQuery, targetModelClass, mappingColumns: [targetForeignKey]})
+
+      const targetDriver = targetBaseQuery.driver
+      const targetCohorts = targetDriver.chunkValues([...allTargetIds], (chunk) => targetBaseQuery.clone().where({[targetForeignKey]: chunk}).toSql())
 
-      query = this.relationship.applyScope(query)
-      query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [targetForeignKey]})
-      targetModels = await query.toArray()
+      for (const cohort of targetCohorts) {
+        const cohortQuery = targetBaseQuery.clone().where({[targetForeignKey]: cohort})
+        const foundTargetModels = await cohortQuery.toArray()
+
+        targetModels.push(...foundTargetModels)
+      }
     }
 
     // Step 3: Index target models by their foreign key (maps to through model ID)
@@ -285,27 +301,35 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
       modelsByPrimaryKeyValue[primaryKeyValue].push(model)
     }
 
-    /**
-     * Where args.
-     * @type {Record<string, string | number | Array<string | number>>} */
-    const whereArgs = {}
+    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration(), modelsToLoad[0])
 
-    whereArgs[foreignKey] = [...modelsPrimaryKeyValues]
+    // Build the query once with the polymorphic type constant (when present),
+    // relationship scope, and selection. The parent ID IN-list is cloned per cohort
+    // so the generated SQL stays within driver limits.
+    let baseQuery = preloadQueryForModel(modelsToLoad, targetModelClass)
 
     if (this.relationship.getPolymorphic()) {
       const typeColumn = this.relationship.getPolymorphicTypeColumn()
 
-      whereArgs[typeColumn] = this.relationship.getModelClass().getModelName()
+      baseQuery = baseQuery.where({[typeColumn]: this.relationship.getModelClass().getModelName()})
     }
 
-    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration(), modelsToLoad[0])
+    baseQuery = this.relationship.applyScope(baseQuery)
+    baseQuery = this.selection.applyToQuery({query: baseQuery, targetModelClass, mappingColumns: [foreignKey]})
 
-    let query = preloadQueryForModel(modelsToLoad, targetModelClass).where(whereArgs)
+    /**
+     * Target models.
+     * @type {import("../../record/index.js").default[]} */
+    const targetModels = []
+    const driver = baseQuery.driver
+    const cohorts = driver.chunkValues([...modelsPrimaryKeyValues], (chunk) => baseQuery.clone().where({[foreignKey]: chunk}).toSql())
 
-    query = this.relationship.applyScope(query)
-    query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [foreignKey]})
+    for (const cohort of cohorts) {
+      const cohortQuery = baseQuery.clone().where({[foreignKey]: cohort})
+      const foundTargetModels = await cohortQuery.toArray()
 
-    const targetModels = await query.toArray()
+      targetModels.push(...foundTargetModels)
+    }
 
     for (const targetModel of targetModels) {
       const foreignKeyValue = /** @type {string | number} */ (targetModel.readColumn(foreignKey))

package/build/database/query/preloader/has-one.js

@@ -72,28 +72,36 @@ export default class VelociousDatabaseQueryPreloaderHasOne {
 
     if (modelsPrimaryKeyValues.size == 0) return satisfiedTargets
 
-    /**
-     * Where args.
-     * @type {Record<string, string | number | Array<string | number>>} */
-    const whereArgs = {}
+    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration(), this.models[0])
 
-    whereArgs[foreignKey] = [...modelsPrimaryKeyValues]
+    // Load target models to be preloaded on the given models.
+    // Build the query once with the polymorphic type constant (when present),
+    // relationship scope, and selection. The parent ID IN-list is cloned per cohort
+    // so the generated SQL stays within driver limits.
+    let baseQuery = preloadQueryForModel(this.models, targetModelClass)
 
     if (this.relationship.getPolymorphic()) {
       const typeColumn = this.relationship.getPolymorphicTypeColumn()
 
-      whereArgs[typeColumn] = this.relationship.getModelClass().getModelName()
+      baseQuery = baseQuery.where({[typeColumn]: this.relationship.getModelClass().getModelName()})
     }
 
-    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration(), this.models[0])
+    baseQuery = this.relationship.applyScope(baseQuery)
+    baseQuery = this.selection.applyToQuery({query: baseQuery, targetModelClass, mappingColumns: [foreignKey]})
 
-    // Load target models to be preloaded on the given models
-    let query = preloadQueryForModel(this.models, targetModelClass).where(whereArgs)
+    /**
+     * Target models.
+     * @type {import("../../record/index.js").default[]} */
+    const targetModels = []
+    const driver = baseQuery.driver
+    const cohorts = driver.chunkValues([...modelsPrimaryKeyValues], (chunk) => baseQuery.clone().where({[foreignKey]: chunk}).toSql())
 
-    query = this.relationship.applyScope(query)
-    query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [foreignKey]})
+    for (const cohort of cohorts) {
+      const cohortQuery = baseQuery.clone().where({[foreignKey]: cohort})
+      const foundTargetModels = await cohortQuery.toArray()
 
-    const targetModels = await query.toArray()
+      targetModels.push(...foundTargetModels)
+    }
 
     for (const targetModel of targetModels) {
       const foreignKeyValue = /** @type {string | number} */ (targetModel.readColumn(foreignKey))

package/build/database/query/query-data.js

@@ -227,7 +227,7 @@ export async function runQueryData({rootModelClass, rootModels, entries}) {
   }
 
   for (const {query} of queryGroups) {
-    await executeEntryQuery({primaryKey, query, rootModels})
+    await executeChunkedEntryQuery({primaryKey, query, rootIds, rootModels})
   }
 }
 
@@ -267,13 +267,6 @@ function prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass, s
   const rootTable = rootModelClass.tableName()
   const rootPkSql = `${driver.quoteTable(rootTable)}.${driver.quoteColumn(primaryKey)}`
 
-  /**
-   * Root where.
-   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
-  const rootWhere = {}
-  rootWhere[primaryKey] = rootIds
-  query.where(rootWhere)
-
   const joinDescriptor = buildNestedJoinDescriptor(entry.chain)
 
   if (joinDescriptor !== true) {
@@ -370,3 +363,25 @@ async function executeEntryQuery({primaryKey, query, rootModels}) {
     }
   }
 }
+
+/**
+ * Executes one compatible queryData group in cohorts so the root ID IN-list
+ * stays within driver limits, attaching each selected alias to the matching
+ * root record.
+ * @param {object} args - Options.
+ * @param {string} args.primaryKey - Root model primary key column.
+ * @param {import("./model-class-query.js").default} args.query - Prepared grouped query.
+ * @param {Array<string | number>} args.rootIds - Root primary-key values.
+ * @param {import("../record/index.js").default[]} args.rootModels - Loaded root records.
+ * @returns {Promise<void>}
+ */
+async function executeChunkedEntryQuery({primaryKey, query, rootIds, rootModels}) {
+  const driver = query.driver
+  const cohorts = driver.chunkValues(rootIds, (chunk) => query.clone().where({[primaryKey]: chunk}).toSql())
+
+  for (const cohort of cohorts) {
+    const cohortQuery = query.clone().where({[primaryKey]: cohort})
+
+    await executeEntryQuery({primaryKey, query: cohortQuery, rootModels})
+  }
+}