velocious 1.0.558 → 1.0.560

package/build/database/drivers/base.js

@@ -59,6 +59,7 @@
  * @property {boolean} [processListComment] - Whether to add process-list comments to the query.
  * @property {boolean} [retry] - Whether retryable errors may retry the query; defaults to true.
  * @property {boolean} [sessionTimeZone] - Whether to ensure the configured database session time zone before the query.
+ * @property {AbortSignal} [signal] - Aborts the in-flight query (destroying its connection) when it fires.
  * @property {string} [sourceStack] - Stack captured at the caller boundary.
  */
 
@@ -116,6 +117,7 @@ import { formatDateForDatabase } from "../datetime-storage.js"
 import isDate from "../../utils/is-date.js"
 import Logger from "../../logger.js"
 import Query from "../query/index.js"
+import QueryAbortedError from "../query-aborted-error.js"
 import Handler from "../handler.js"
 import Mutex from "epic-locks/build/mutex.js"
 import UUID from "pure-uuid"
@@ -1170,6 +1172,10 @@ export default class VelociousDatabaseDriversBase {
       } catch (error) {
         if (!(error instanceof Error)) throw error
 
+        // A deliberately-aborted query must never be silently re-run — its
+        // connection was destroyed on purpose, so treat it as terminal.
+        if (error instanceof QueryAbortedError) throw error
+
         const retryInfo = this.retryableDatabaseError(error)
 
         if (options.retry !== false && tries < maxTries && retryInfo.retry) {
@@ -1274,7 +1280,7 @@ export default class VelociousDatabaseDriversBase {
     await this.beforeQuery(sql, options)
 
     try {
-      return await this._queryActual(sql)
+      return await this._queryActual(sql, options)
     } finally {
       await this.afterQuery(sql, options)
     }
@@ -1463,9 +1469,10 @@ export default class VelociousDatabaseDriversBase {
    * Runs query actual.
    * @abstract
    * @param {string} sql - SQL string.
+   * @param {QueryOptions} [options] - Query options (carries the optional abort signal).
    * @returns {Promise<QueryResultType>} - Resolves with the query actual.
    */
-  _queryActual(sql) { // eslint-disable-line no-unused-vars
+  _queryActual(sql, options) { // eslint-disable-line no-unused-vars
     throw new Error(`queryActual not implemented`)
   }
 

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

@@ -13,6 +13,7 @@ import Insert from "./sql/insert.js"
 import Options from "./options.js"
 import mysql from "mysql"
 import query from "./query.js"
+import QueryAbortedError from "../../query-aborted-error.js"
 import QueryParser from "./query-parser.js"
 import streamQuery from "./query-stream.js"
 import RemoveIndex from "./sql/remove-index.js"
@@ -371,15 +372,23 @@ export default class VelociousDatabaseDriversMysql extends Base{
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.
+   * @param {import("../base.js").QueryOptions} [options] - Query options (carries the optional abort signal).
    * @returns {Promise<import("../base.js").QueryResultType>} - Resolves with the query actual.
    */
-  async _queryActual(sql) {
+  async _queryActual(sql, options = {}) {
     if (!this.pool) await this.connect()
     if (!this.pool) throw new Error("MySQL pool failed to initialize")
 
     try {
-      return await query(this.pool, sql)
+      return await query(this.pool, sql, {signal: options.signal})
     } catch (error) {
+      // Preserve an abort as-is so the retry loop can recognise it as terminal
+      // (wrapping it in a plain Error would lose the QueryAbortedError type).
+      if (error instanceof QueryAbortedError) {
+        if (error.connectionDestroyed) this.resetCurrentSessionTimeZone()
+        throw error
+      }
+
       // Re-throw to un-corrupt stacktrace
       if (error instanceof Error) {
         throw new Error(`Query failed: ${error.message}`, {cause: error})

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

@@ -1,37 +1,213 @@
+// @ts-check
+
+import mysql from "mysql"
+import QueryAbortedError from "../../query-aborted-error.js"
+
 /**
- * Runs query.
- * @param {import("mysql").Pool} pool - Pool.
- * @param {string} sql - SQL string.
- * @returns {Promise<Record<string, ?>[]>} - Resolves with string value.
+ * Checks out one pool connection while honoring cancellation before checkout completes.
+ * A connection returned after cancellation is released without running the query.
+ * @param {import("mysql").Pool} pool - Pool to check out from.
+ * @param {string} sql - SQL associated with the checkout.
+ * @param {AbortSignal | undefined} signal - Optional cancellation signal.
+ * @returns {Promise<import("mysql").PoolConnection>} - Checked-out connection.
  */
-export default async function query(pool, sql) {
+function checkoutConnection(pool, sql, signal) {
   return new Promise((resolve, reject) => {
-    pool.query(sql, (error, results, fields) => {
+    let settled = false
+    /** @type {(() => void) | undefined} */
+    let removeAbortListener
+
+    const settle = () => {
+      settled = true
+      if (removeAbortListener) removeAbortListener()
+    }
+
+    const onAbort = () => {
+      if (settled) return
+
+      settle()
+      reject(new QueryAbortedError({sql}))
+    }
+
+    if (signal) {
+      signal.addEventListener("abort", onAbort, {once: true})
+      removeAbortListener = () => signal.removeEventListener("abort", onAbort)
+    }
+
+    if (signal?.aborted) {
+      onAbort()
+
+      return
+    }
+
+    pool.getConnection((error, connection) => {
+      if (settled) {
+        if (connection) connection.release()
+
+        return
+      }
+
+      settle()
+
       if (error) {
-        reject(new Error(`Query failed because of ${error}: ${sql}`))
+        reject(error)
       } else {
-        const rows = []
-        const resultRows = Array.isArray(results) ? results : []
-        const resultFields = Array.isArray(fields) ? fields : []
+        resolve(connection)
+      }
+    })
+  })
+}
+
+/**
+ * Best-effort `KILL QUERY` so the server aborts the running statement — releasing
+ * its locks/resources immediately — instead of finishing it after the client
+ * socket is destroyed. Destroying the socket alone does not interrupt a
+ * non-cooperative running statement (e.g. `SLEEP` or a long scan) server-side, so
+ * the deadline would otherwise only suppress the client while the query keeps
+ * holding database resources. Runs on a throwaway connection because the driver
+ * pool is capped at one connection (the one running the aborted query). Any
+ * failure is swallowed: the caller still destroys the socket and rejects.
+ * @param {import("mysql").Pool} pool - Pool whose connection config seeds the kill connection.
+ * @param {number | null | undefined} threadId - Server thread id of the query to kill.
+ * @returns {Promise<void>} - Resolves once the kill has been attempted.
+ */
+function killServerQuery(pool, threadId) {
+  return new Promise((resolve) => {
+    const connectionConfig = /** @type {{config?: {connectionConfig?: unknown}}} */ (pool).config?.connectionConfig
+
+    if (!threadId || !connectionConfig) {
+      resolve()
+
+      return
+    }
+
+    let killConnection
+
+    try {
+      killConnection = mysql.createConnection(/** @type {?} */ (connectionConfig))
+    } catch {
+      resolve()
+
+      return
+    }
+
+    killConnection.on("error", () => {})
+    killConnection.query(`KILL QUERY ${Number(threadId)}`, () => {
+      killConnection.destroy()
+      resolve()
+    })
+  })
+}
+
+/**
+ * Runs `sql` on a dedicated connection checked out of `pool` so it can be
+ * aborted while it is still executing. When `signal` fires before the query
+ * settles the connection is destroyed — which aborts the running statement at
+ * the socket and removes the connection from the pool so it is never handed back
+ * mid-statement — and the promise rejects with a {@link QueryAbortedError}. On
+ * success the connection is released back to the pool. On a fatal connection
+ * error it is destroyed; on an ordinary query error (syntax, constraint, etc.)
+ * it is released, because the connection itself is still healthy.
+ * @param {import("mysql").Pool} pool - Pool.
+ * @param {string} sql - SQL string.
+ * @param {{signal?: AbortSignal}} [options] - Query options.
+ * @returns {Promise<Record<string, ?>[]>} - Resolves with the mapped rows.
+ */
+export default async function query(pool, sql, {signal} = {}) {
+  if (signal?.aborted) throw new QueryAbortedError({sql})
+
+  const connection = await checkoutConnection(pool, sql, signal)
+
+  return await new Promise((resolve, reject) => {
+    let settled = false
+    /** @type {(() => void) | undefined} */
+    let removeAbortListener
+
+    const settle = () => {
+      settled = true
+      if (removeAbortListener) removeAbortListener()
+    }
+
+    const onAbort = () => {
+      if (settled) return
+
+      settle()
+      const threadId = connection.threadId
+
+      // Destroy — never release — so a connection still mid-statement is not
+      // returned to the pool and the pool slot is freed even if the separate
+      // server-side kill attempt stalls. The pool spawns a fresh connection on
+      // the next checkout.
+      connection.destroy()
+      void killServerQuery(pool, threadId)
+      reject(new QueryAbortedError({connectionDestroyed: true, sql}))
+    }
+
+    if (signal) {
+      signal.addEventListener("abort", onAbort, {once: true})
+      removeAbortListener = () => signal.removeEventListener("abort", onAbort)
+    }
 
-        for (const rowData of resultRows) {
-          /**
-           * Result.
-           * @type {Record<string, ?>} */
-          const result = {}
+    // An abort that landed between the checkout above and attaching the listener
+    // would not fire the listener (the event already dispatched), so re-check and
+    // abort synchronously to close that race before issuing the query.
+    if (signal?.aborted) {
+      onAbort()
 
-          for (const fieldData of resultFields) {
-            const field = fieldData.name
-            const value = rowData[field]
+      return
+    }
 
-            result[field] = value
-          }
+    connection.query(sql, (/** @type {?} */ error, /** @type {?} */ results, /** @type {?} */ fields) => {
+      if (settled) return
 
-          rows.push(result)
+      settle()
+
+      if (error) {
+        // A fatal error leaves the socket unusable, so discard it; an ordinary
+        // query error keeps a healthy connection that can be reused.
+        if (error.fatal) {
+          connection.destroy()
+        } else {
+          connection.release()
         }
 
-        resolve(rows)
+        reject(new Error(`Query failed because of ${error}: ${sql}`))
+
+        return
       }
+
+      connection.release()
+      resolve(mapRows(results, fields))
     })
   })
 }
+
+/**
+ * Materializes the driver rows as isolated plain records keyed by field name.
+ * @param {?} results - Driver result rows.
+ * @param {?} fields - Driver result fields.
+ * @returns {Record<string, ?>[]} - Mapped rows.
+ */
+function mapRows(results, fields) {
+  const rows = []
+  const resultRows = Array.isArray(results) ? results : []
+  const resultFields = Array.isArray(fields) ? fields : []
+
+  for (const rowData of resultRows) {
+    /**
+     * Result.
+     * @type {Record<string, ?>} */
+    const result = {}
+
+    for (const fieldData of resultFields) {
+      const field = fieldData.name
+      const value = rowData[field]
+
+      result[field] = value
+    }
+
+    rows.push(result)
+  }
+
+  return rows
+}

package/build/database/query/index.js

@@ -125,6 +125,7 @@ function mergeJoinValue(existing, incoming) {
  * @property {Record<string, string[]>} [preloadSelects] - Attribute names to load for preloaded relationships, keyed by target model name.
  * @property {Record<string, string[]>} [preloadSelectsExtra] - Extra selects to load in addition to the defaults for preloaded relationships, keyed by target model name.
  * @property {Array<import("./select-base.js").default>} [selects] - SELECT clauses for the query.
+ * @property {AbortSignal} [signal] - Signal passed to database query execution.
  * @property {boolean} [distinct] - Whether the query should use DISTINCT.
  * @property {Array<import("./where-base.js").default>} [wheres] - WHERE conditions for the query.
  */
@@ -150,6 +151,7 @@ export default class VelociousDatabaseQuery {
     preloadSelectsExtra = {},
     distinct = false,
     selects = [],
+    signal,
     wheres = []
   }) {
     if (!driver) throw new Error("No driver given to query")
@@ -182,6 +184,7 @@ export default class VelociousDatabaseQuery {
     this._preloadSelectsExtra = preloadSelectsExtra
     this._distinct = distinct
     this._selects = selects
+    this._signal = signal
 
     /**
      * Narrows the runtime value to the documented type.
@@ -213,6 +216,7 @@ export default class VelociousDatabaseQuery {
       preload: {...this._preload},
       distinct: this._distinct,
       selects: [...this._selects],
+      signal: this._signal,
       wheres: [...this._wheres]
     })
 
@@ -482,11 +486,22 @@ export default class VelociousDatabaseQuery {
    */
   async _executeQuery({logName = this.queryLogName("Load")} = {}) {
     const sql = this.toSql()
-    const results = await this.driver.query(sql, {logName})
+    const results = await this.driver.query(sql, {logName, signal: this._signal})
 
     return results
   }
 
+  /**
+   * Sets the signal used to cancel database execution for this query and its clones.
+   * @param {AbortSignal | undefined} signal - Cancellation signal, or undefined to clear it.
+   * @returns {this} - Query for chaining.
+   */
+  signal(signal) {
+    this._signal = signal
+
+    return this
+  }
+
   /**
    * Runs results.
    * @returns {Promise<Array<object>>} Array of results from the database

package/build/database/query/model-class-query.js

@@ -234,6 +234,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
       preloadSelectsExtra: clonePreloadSelectMap(this._preloadSelectsExtra),
       distinct: this._distinct,
       selects: [...this._selects],
+      signal: this._signal,
       wheres: [...this._wheres],
       joinBasePath: [...this._joinBasePath],
       joinTracker: this._joinTracker.clone(),
@@ -373,7 +374,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     ].join(" ")
     const results = /** @type {{count: number}[]} */ (await this.driver.query(
       sql,
-      {logName: this.queryLogName("Count")}
+      {logName: this.queryLogName("Count"), signal: this._signal}
     ))
 
     if (results.length != 1 || !("count" in results[0])) {
@@ -780,7 +781,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
       sql = `UPDATE ${driver.quoteTable(tableName)} SET ${setCols}${whereSql}`
     }
 
-    await driver.query(sql, {logName: this.queryLogName("Update All")})
+    await driver.query(sql, {logName: this.queryLogName("Update All"), signal: this._signal})
   }
 
   /**

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

@@ -190,23 +190,50 @@ export async function runQueryData({rootModelClass, rootModels, entries}) {
 
   const primaryKey = rootModelClass.primaryKey()
   const rootIds = rootModels.map((model) => /** @type {string | number} */ (model.readColumn(primaryKey)))
+  const preparedEntries = entries.map((entry, entryIndex) => prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass}))
+  /**
+   * Compatible query groups.
+   * @type {Array<{aliases: Set<string>, query: import("./model-class-query.js").default, signature: string}>} */
+  const queryGroups = []
+
+  for (const preparedEntry of preparedEntries) {
+    const compatibleGroup = queryGroups.find((group, groupIndex) => {
+      if (group.signature !== preparedEntry.signature) return false
+      if (queryGroups.slice(groupIndex + 1).some((interveningGroup) => (
+        preparedEntry.aliases.some((alias) => interveningGroup.aliases.has(alias))
+      ))) return false
+
+      return preparedEntry.aliases.every((alias) => !group.aliases.has(alias))
+    })
+
+    if (compatibleGroup) {
+      compatibleGroup.query.select(preparedEntry.query.getSelects().slice(1))
+      for (const alias of preparedEntry.aliases) compatibleGroup.aliases.add(alias)
+    } else {
+      queryGroups.push({
+        aliases: new Set(preparedEntry.aliases),
+        query: preparedEntry.query,
+        signature: preparedEntry.signature
+      })
+    }
+  }
 
-  for (const entry of entries) {
-    await runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels})
+  for (const {query} of queryGroups) {
+    await executeEntryQuery({primaryKey, query, rootModels})
   }
 }
 
 /**
- * Runs run entry.
+ * Prepares one queryData entry and its compatibility metadata.
  * @param {object} args - Options.
  * @param {QueryDataEntry} args.entry - Entry being evaluated.
+ * @param {number} args.entryIndex - Stable position used to isolate opaque projections.
  * @param {string} args.primaryKey - Root model primary key column.
  * @param {Array<string | number>} args.rootIds - Root primary-key values.
  * @param {typeof import("../record/index.js").default} args.rootModelClass - Root model class.
- * @param {import("../record/index.js").default[]} args.rootModels - Loaded root records.
- * @returns {Promise<void>}
+ * @returns {{aliases: string[], query: import("./model-class-query.js").default, signature: string}} - Prepared entry.
  */
-async function runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels}) {
+function prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass}) {
   const targetModelClass = resolveTargetModelClass(rootModelClass, entry.chain)
   const fn = targetModelClass.getQueryDataByName(entry.fnName)
 
@@ -219,7 +246,7 @@ async function runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels}
 
   // Empty out any defaults the query factory added — queryData runs
   // a bare aggregate, not a full model load.
-  query._selects = []
+  query.reselect()
   query._preload = {}
 
   // Force the root WHERE to qualify by table name so it survives the
@@ -264,6 +291,47 @@ async function runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels}
     tableName: targetTableRef
   })
 
+  const aliases = selectedAliases(query)
+  const signatureQuery = query.clone()
+  signatureQuery.reselect(signatureQuery.getSelects().slice(0, 1))
+
+  return {
+    aliases: aliases || [],
+    query,
+    signature: aliases ? signatureQuery.toSql() : `opaque:${entryIndex}`
+  }
+}
+
+/**
+ * Returns explicit aliases selected after the reserved parent id.
+ * Entries with an opaque select stay isolated by receiving a unique compatibility alias.
+ * @param {import("./model-class-query.js").default} query - Prepared queryData query.
+ * @returns {string[] | null} - Selected aliases, or null for an opaque projection.
+ */
+function selectedAliases(query) {
+  const aliases = []
+
+  for (const select of query.getSelects().slice(1)) {
+    const sql = select.toSql()
+    const match = sql.match(/\sAS\s+([^\s]+)\s*$/iu)
+
+    if (!match) return null
+
+    aliases.push(match[1].replace(/^["[`]|["`\]]$/gu, ""))
+  }
+
+  return aliases
+}
+
+/**
+ * Executes one compatible queryData group and attaches every selected alias.
+ * @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 {import("../record/index.js").default[]} args.rootModels - Loaded root records.
+ * @returns {Promise<void>}
+ */
+async function executeEntryQuery({primaryKey, query, rootModels}) {
   const rows = /** @type {Array<Record<string, ?>>} */ (await query._executeQuery())
   const byParent = new Map()
 

package/build/database/query/with-count.js

@@ -111,40 +111,36 @@ export async function runWithCount({models, modelClass, entries}) {
 
   const primaryKey = modelClass.primaryKey()
   const parentIds = models.map((model) => /** @type {string | number} */ (model.readColumn(primaryKey)))
+  const queryGroups = new Map()
 
   for (const entry of entries) {
-    const counts = await countForEntry({entries, entry, modelClass, parentIds})
-
-    for (const model of models) {
-      const modelPrimaryKeyValue = /** @type {string | number} */ (model.readColumn(primaryKey))
-      // Tolerate driver differences in numeric return types: SQLite
-      // returns integers as JS numbers, but MySQL's raw driver can
-      // return count primary keys as strings. Try both.
-      const resolvedCount = counts.has(modelPrimaryKeyValue)
-        ? /** @type {number} */ (counts.get(modelPrimaryKeyValue))
-        : Number(counts.get(String(modelPrimaryKeyValue)) ?? 0)
-
-      // Counts go on the record's dedicated association-count map,
-      // NOT on `_attributes`, so a virtual `tasksCount` can't shadow a
-      // real `tasks_count` column (e.g. a counter_cache) nor leak into
-      // attribute-level serialization / change tracking.
-      model._setAssociationCount(entry.attributeName, resolvedCount)
+    const countQuery = queryForEntry({entry, modelClass, parentIds})
+    const sql = countQuery.toSql()
+    const existingGroup = queryGroups.get(sql)
+
+    if (existingGroup) {
+      existingGroup.entries.push(entry)
+    } else {
+      queryGroups.set(sql, {countQuery, entries: [entry]})
     }
   }
+
+  for (const {countQuery, entries: groupedEntries} of queryGroups.values()) {
+    const counts = await executeCountQuery(countQuery)
+
+    for (const entry of groupedEntries) attachCounts({counts, entry, models, primaryKey})
+  }
 }
 
 /**
- * Runs count for entry.
+ * Builds the grouped count query for an entry.
  * @param {object} args - Options.
- * @param {WithCountEntry[]} args.entries - All entries, used for error context only.
  * @param {WithCountEntry} args.entry - Entry being evaluated.
  * @param {typeof import("../record/index.js").default} args.modelClass - Parent model class.
  * @param {Array<string | number>} args.parentIds - Primary keys of the loaded parents.
- * @returns {Promise<Map<string | number, number>>} - Map of parent pk → count.
+ * @returns {import("./model-class-query.js").default} - Prepared count query.
  */
-async function countForEntry({entries, entry, modelClass, parentIds}) {
-  void entries
-
+function queryForEntry({entry, modelClass, parentIds}) {
   const relationship = modelClass.getRelationshipByName(entry.relationshipName)
 
   if (!relationship) {
@@ -176,20 +172,33 @@ async function countForEntry({entries, entry, modelClass, parentIds}) {
     Object.assign(whereConditions, entry.where)
   }
 
-  const countQuery = targetModelClass
-    .where(whereConditions)
-    .group(foreignKey)
+  const baseQuery = targetModelClass._newQuery()
+  baseQuery._forceQualifyBaseTable = true
+  baseQuery.where(whereConditions)
+
+  const countQuery = relationship.applyScope(baseQuery)
 
   countQuery._preload = {}
-  countQuery._selects = []
+  countQuery.reselect()
 
   const driver = countQuery.driver
-  const quotedTable = driver.quoteTable(targetModelClass.tableName())
+  const quotedTable = driver.quoteTable(countQuery.rootTableReference())
   const quotedFk = driver.quoteColumn(foreignKey)
+  const qualifiedForeignKey = `${quotedTable}.${quotedFk}`
 
-  countQuery.select(`${quotedTable}.${quotedFk} AS parent_id`)
+  countQuery.group(qualifiedForeignKey)
+  countQuery.select(`${qualifiedForeignKey} AS parent_id`)
   countQuery.select("COUNT(*) AS count_value")
 
+  return countQuery
+}
+
+/**
+ * Executes a prepared grouped count query.
+ * @param {import("./model-class-query.js").default} countQuery - Prepared count query.
+ * @returns {Promise<Map<string | number, number>>} - Map of parent pk → count.
+ */
+async function executeCountQuery(countQuery) {
   const rows = /** @type {Array<{parent_id: string | number, count_value: string | number}>} */ (
     await countQuery._executeQuery()
   )
@@ -207,3 +216,30 @@ async function countForEntry({entries, entry, modelClass, parentIds}) {
 
   return counts
 }
+
+/**
+ * Attaches one entry's resolved counts to the loaded models.
+ * @param {object} args - Options.
+ * @param {Map<string | number, number>} args.counts - Counts keyed by parent primary key.
+ * @param {WithCountEntry} args.entry - Entry whose alias receives the counts.
+ * @param {import("../record/index.js").default[]} args.models - Loaded parent records.
+ * @param {string} args.primaryKey - Parent primary key column.
+ * @returns {void}
+ */
+function attachCounts({counts, entry, models, primaryKey}) {
+  for (const model of models) {
+    const modelPrimaryKeyValue = /** @type {string | number} */ (model.readColumn(primaryKey))
+    // Tolerate driver differences in numeric return types: SQLite
+    // returns integers as JS numbers, but MySQL's raw driver can
+    // return count primary keys as strings. Try both.
+    const resolvedCount = counts.has(modelPrimaryKeyValue)
+      ? /** @type {number} */ (counts.get(modelPrimaryKeyValue))
+      : Number(counts.get(String(modelPrimaryKeyValue)) ?? 0)
+
+    // Counts go on the record's dedicated association-count map,
+    // NOT on `_attributes`, so a virtual `tasksCount` can't shadow a
+    // real `tasks_count` column (e.g. a counter_cache) nor leak into
+    // attribute-level serialization / change tracking.
+    model._setAssociationCount(entry.attributeName, resolvedCount)
+  }
+}

package/build/database/query-aborted-error.js

@@ -0,0 +1,24 @@
+// @ts-check
+
+/**
+ * Thrown when a query is aborted via its `AbortSignal`/deadline. This is a
+ * terminal, non-retryable outcome whether cancellation happened before checkout
+ * or after an in-flight connection had to be destroyed.
+ */
+export default class QueryAbortedError extends Error {
+  /**
+   * Runs constructor.
+   * @param {object} [args] - Options.
+   * @param {unknown} [args.cause] - Error cause.
+   * @param {boolean} [args.connectionDestroyed] - Whether cancellation destroyed an in-flight connection.
+   * @param {string} [args.sql] - The SQL that was aborted.
+   */
+  constructor({cause, connectionDestroyed = false, sql} = {}) {
+    super("Query aborted before it completed", {cause})
+
+    this.name = "QueryAbortedError"
+    this.code = "VELOCIOUS_QUERY_ABORTED"
+    this.connectionDestroyed = connectionDestroyed
+    this.sql = sql
+  }
+}