turbine-orm 0.19.2 → 0.21.0

package/dist/query/builder.js

@@ -11,7 +11,7 @@
  * metadata — nothing is hardcoded.
  */
 import { postgresDialect } from '../dialect.js';
-import { CircularRelationError, NotFoundError, OptimisticLockError, RelationError, TimeoutError, ValidationError, wrapPgError, } from '../errors.js';
+import { CircularRelationError, NotFoundError, OptimisticLockError, RelationError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from '../errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { escapeLike, LRUCache, OPERATOR_KEYS, sqlToPreparedName } from './utils.js';
@@ -301,6 +301,89 @@ export class QueryInterface {
     p(index) {
         return this.dialect.paramPlaceholder(index);
     }
+    /**
+     * Cast an aggregate expression to an integer/float result type through the
+     * active dialect. PostgreSQL keeps the historical postfix cast (`expr::int` /
+     * `expr::float`); SQLite (no `::` operator) maps to `CAST(expr AS INTEGER/REAL)`.
+     * Falls back to the Postgres postfix cast for dialects without the hook.
+     */
+    castAgg(expr, target) {
+        return this.dialect.castAggregate?.(expr, target) ?? `${expr}::${target}`;
+    }
+    /**
+     * Build the trailing pagination clause for an OUTER SELECT. PostgreSQL/MySQL/
+     * SQLite use ` LIMIT <ph>` and/or ` OFFSET <ph>`. SQL Server has no `LIMIT`, so
+     * its dialect implements {@link Dialect.buildLimitOffset} to emit
+     * `[ORDER BY (SELECT NULL)] OFFSET <off> ROWS [FETCH NEXT <lim> ROWS ONLY]`.
+     * Param-push order (limit before offset) is owned by the caller and unchanged —
+     * this only varies the SQL text, so PG output stays byte-identical.
+     */
+    buildPagination(limitPh, offsetPh, hasOrderBy) {
+        if (this.dialect.buildLimitOffset) {
+            return this.dialect.buildLimitOffset({ limitPlaceholder: limitPh, offsetPlaceholder: offsetPh, hasOrderBy });
+        }
+        let s = '';
+        if (limitPh !== undefined)
+            s += ` LIMIT ${limitPh}`;
+        if (offsetPh !== undefined)
+            s += ` OFFSET ${offsetPh}`;
+        return s;
+    }
+    /**
+     * The single-row limit appended to findUnique / findFirst-style lookups. ` LIMIT 1`
+     * for PG/MySQL/SQLite; SQL Server routes through {@link Dialect.buildLimitOffset}
+     * (literal `1`, no params) → ` ORDER BY (SELECT NULL) OFFSET 0 ROWS FETCH NEXT 1
+     * ROWS ONLY`. No params are pushed, so the collect path is unaffected.
+     */
+    limitOneClause() {
+        if (this.dialect.buildLimitOffset) {
+            return this.dialect.buildLimitOffset({ limitPlaceholder: '1', offsetPlaceholder: undefined, hasOrderBy: false });
+        }
+        return ' LIMIT 1';
+    }
+    /**
+     * Validate a LIMIT/OFFSET value as a non-negative integer and return it as an
+     * inline SQL literal. Used only on `dialect.inlineLimitOffset` engines (MySQL).
+     * The input is always a Turbine-controlled pagination value, never a raw user
+     * string — and this guard guarantees the output is `String` of a validated
+     * integer, so inlining cannot inject SQL.
+     */
+    limitOffsetLiteral(value) {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 0) {
+            throw new ValidationError(`LIMIT/OFFSET must be a non-negative integer, received: ${String(value)}`);
+        }
+        return String(n);
+    }
+    /**
+     * Resolve a LIMIT/OFFSET value to either an inline literal (no param pushed, on
+     * `dialect.inlineLimitOffset` engines) or a bound placeholder (the value is
+     * pushed to `params`). Build and collect paths both gate on the same flag so
+     * the param order stays mirrored; PG/SQLite/SQL Server keep parameterizing and
+     * stay byte-identical.
+     */
+    paginationRef(value, params) {
+        if (this.dialect.inlineLimitOffset) {
+            return this.limitOffsetLiteral(value);
+        }
+        params.push(Number(value));
+        return this.p(params.length);
+    }
+    /**
+     * Build an `IN` / `NOT IN` predicate through the active dialect. PostgreSQL
+     * keeps the array-param form (`expr = ANY($n)` / `expr != ALL($n)`); other
+     * engines (SQLite) use a length-independent single-placeholder form. Paired
+     * with {@link inParam}, which supplies the single bound value.
+     */
+    inClause(expr, paramRef, negated) {
+        if (this.dialect.buildInClause)
+            return this.dialect.buildInClause(expr, paramRef, negated);
+        return negated ? `${expr} != ALL(${paramRef})` : `${expr} = ANY(${paramRef})`;
+    }
+    /** The single bound parameter for an `IN` list (PG: the array; SQLite: a JSON string). */
+    inParam(values) {
+        return this.dialect.inClauseParam ? this.dialect.inClauseParam(values) : values;
+    }
     /**
      * Return cache hit/miss statistics for this QueryInterface instance.
      * Useful for monitoring and benchmarking.
@@ -401,6 +484,49 @@ export class QueryInterface {
             clearTimeout(timer);
         }
     }
+    /**
+     * Execute a write `DeferredQuery` (create/update/delete/upsert) according to
+     * the active dialect's {@link Dialect.resultStrategy}, then apply its
+     * transform.
+     *
+     *   - `'returning'` / `'output'`: the statement returns its own affected rows
+     *     (`RETURNING *` / `OUTPUT INSERTED.*`). Byte-identical to the historical
+     *     single `queryWithTimeout` + `transform(result)` path — the PostgreSQL
+     *     route is unchanged.
+     *   - `'reselect'`: the engine cannot return rows from a write, so the build
+     *     method attached a {@link DeferredQuery.reselect} plan that runs the
+     *     write and a follow-up SELECT; the SELECT's rows feed the transform.
+     */
+    async executeMutation(deferred, timeout) {
+        if (this.dialect.resultStrategy === 'reselect' && deferred.reselect) {
+            const exec = (sql, params, preparedName) => this.queryWithTimeout(sql, params, timeout, preparedName);
+            const result = await deferred.reselect(exec);
+            return deferred.transform(result);
+        }
+        const result = await this.queryWithTimeout(deferred.sql, deferred.params, timeout, deferred.preparedName);
+        return deferred.transform(result);
+    }
+    /**
+     * Build a `SELECT * ... WHERE <predicate>` that re-fetches the row(s) matched
+     * by a write's `where` clause. Used by the `'reselect'` result strategy to
+     * return rows from non-RETURNING engines. Reuses the same parameterized WHERE
+     * builder as reads, so no user value is interpolated.
+     */
+    buildReselectByWhere(whereObj) {
+        const params = [];
+        const clause = this.buildWhereClause(whereObj, params);
+        const where = clause ? ` WHERE ${clause}` : '';
+        return { sql: `SELECT * FROM ${this.q(this.table)}${where}`, params };
+    }
+    /**
+     * Best-effort extraction of an auto-generated primary key from a write
+     * result for `'reselect'` engines (e.g. mysql2's `insertId`). Returns
+     * `undefined` when the driver exposes no such field.
+     */
+    mutationInsertId(result) {
+        const r = result;
+        return r.insertId ?? r.lastID;
+    }
     /**
      * Execute a query through the middleware chain.
      * If no middlewares are registered, executes directly.
@@ -471,7 +597,7 @@ export class QueryInterface {
                 const whereSql = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
                 void tempParams; // params are positional, SQL is value-invariant
-                return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
+                return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
             });
             // Collect params (same order as build)
             for (const k of whereKeys) {
@@ -496,7 +622,7 @@ export class QueryInterface {
                 const whereSql = clause ? ` WHERE ${clause}` : '';
                 const qt = this.q(this.table);
                 const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${this.q(c)}`).join(', ') : `${qt}.*`;
-                return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
+                return `SELECT ${selectExpr} FROM ${qt}${whereSql}${this.limitOneClause()}`;
             });
             // Collect params
             this.collectWhereParams(whereObj, params);
@@ -521,7 +647,7 @@ export class QueryInterface {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             const selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
-            return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql} LIMIT 1`;
+            return `SELECT ${selectClause} FROM ${this.q(this.table)}${whereSql}${this.limitOneClause()}`;
         });
         // Collect params in exact build order: where first, then with-clause relations
         this.collectWhereParams(whereObj, params);
@@ -681,14 +807,18 @@ export class QueryInterface {
                 // vector at the correct position (after cursor params, before LIMIT).
                 sql += ` ORDER BY ${this.buildOrderBy(args.orderBy, freshParams)}`;
             }
+            // Pagination — push params in the same order the collect path mirrors
+            // (limit before offset); the SQL TEXT shape is dialect-owned via
+            // buildPagination (PG: ` LIMIT $n`/` OFFSET $n`; SQL Server: OFFSET/FETCH).
+            let limitPh;
+            let offsetPh;
             if (effectiveLimit !== undefined) {
-                freshParams.push(Number(effectiveLimit));
-                sql += ` LIMIT ${this.p(freshParams.length)}`;
+                limitPh = this.paginationRef(effectiveLimit, freshParams);
             }
             if (args?.offset !== undefined) {
-                freshParams.push(Number(args.offset));
-                sql += ` OFFSET ${this.p(freshParams.length)}`;
+                offsetPh = this.paginationRef(args.offset, freshParams);
             }
+            sql += this.buildPagination(limitPh, offsetPh, !!args?.orderBy);
             return sql;
         });
         // Collect params in exact build order:
@@ -712,12 +842,13 @@ export class QueryInterface {
         if (args?.orderBy) {
             this.collectOrderByParams(args.orderBy, params);
         }
-        // 5. LIMIT param
-        if (effectiveLimit !== undefined) {
+        // 5. LIMIT param — skipped when the dialect inlines pagination (build path
+        //    mirrors via paginationRef → no placeholder, no param).
+        if (effectiveLimit !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(Number(effectiveLimit));
         }
-        // 6. OFFSET param
-        if (args?.offset !== undefined) {
+        // 6. OFFSET param — same inline gate as LIMIT above.
+        if (args?.offset !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(Number(args.offset));
         }
         return {
@@ -777,34 +908,19 @@ export class QueryInterface {
         }
         // --- Overflow: fall back to cursor path from scratch ---
         const deferred = this.buildFindMany(args);
-        // Acquire a dedicated connection — cursors require a single connection in a transaction
+        // Acquire a dedicated connection — cursors require a single connection in a
+        // transaction. The dialect owns the streaming SQL (Postgres: BEGIN → DECLARE
+        // … NO SCROLL CURSOR FOR → FETCH n → CLOSE → COMMIT, ROLLBACK on error); we
+        // just parse + yield the row batches it produces.
         const client = await this.pool.connect();
-        const cursorName = `turbine_cursor_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-        const quotedCursor = this.q(cursorName);
         try {
-            await client.query('BEGIN');
-            await client.query(`DECLARE ${quotedCursor} NO SCROLL CURSOR FOR ${deferred.sql}`, deferred.params);
-            while (true) {
-                const batch = await client.query(`FETCH ${batchSize} FROM ${quotedCursor}`);
-                if (batch.rows.length === 0)
-                    break;
-                for (const row of batch.rows) {
+            for await (const batch of this.dialect.openStream(client, deferred.sql, deferred.params, batchSize)) {
+                for (const row of batch) {
                     yield (hasRelations ? this.parseNestedRow(row, this.table) : this.parseRow(row, this.table));
                 }
-                if (batch.rows.length < batchSize)
-                    break;
             }
-            await client.query(`CLOSE ${quotedCursor}`);
-            await client.query('COMMIT');
         }
         catch (err) {
-            // Rollback on error (also closes cursor implicitly)
-            try {
-                await client.query('ROLLBACK');
-            }
-            catch {
-                // Connection may already be broken — ignore rollback error
-            }
             // Wrap pg constraint errors so streaming surfaces typed errors like the rest of the API
             throw wrapPgError(err);
         }
@@ -906,8 +1022,7 @@ export class QueryInterface {
                 return this.nestedCreate(args);
             }
             const deferred = this.buildCreate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
+            return this.executeMutation(deferred, args.timeout);
         });
     }
     buildCreate(args) {
@@ -936,6 +1051,33 @@ export class QueryInterface {
                 return this.parseRow(row, this.table);
             },
             tag: `${this.table}.create`,
+            // Non-RETURNING engines: INSERT, then re-fetch the new row by primary key
+            // (provided value, else the driver's generated insert id).
+            reselect: this.makeCreateReselect(sql, params, args.data),
+        };
+    }
+    /**
+     * Build the `'reselect'` plan for {@link buildCreate}: run the INSERT, then
+     * `SELECT * WHERE pk = ?`. Returns `undefined` (skipped) unless the active
+     * dialect's result strategy is `'reselect'`, so the PostgreSQL/RETURNING path
+     * pays nothing. Not yet wired to a real non-RETURNING engine.
+     */
+    makeCreateReselect(insertSql, insertParams, data) {
+        if (this.dialect.resultStrategy !== 'reselect')
+            return undefined;
+        return async (exec) => {
+            const writeResult = await exec(insertSql, insertParams);
+            const insertId = this.mutationInsertId(writeResult);
+            const conds = [];
+            const selParams = [];
+            let idx = 1;
+            for (const pk of this.tableMeta.primaryKey) {
+                const field = this.tableMeta.reverseColumnMap[pk] ?? snakeToCamel(pk);
+                selParams.push(data[field] ?? data[pk] ?? insertId);
+                conds.push(`${this.q(pk)} = ${this.p(idx++)}`);
+            }
+            const where = conds.length > 0 ? ` WHERE ${conds.join(' AND ')}` : '';
+            return exec(`SELECT * FROM ${this.q(this.table)}${where}`, selParams);
         };
     }
     // -------------------------------------------------------------------------
@@ -991,8 +1133,7 @@ export class QueryInterface {
                 return this.nestedUpdate(args);
             }
             const deferred = this.buildUpdate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
+            return this.executeMutation(deferred, args.timeout);
         });
     }
     buildUpdate(args) {
@@ -1020,7 +1161,12 @@ export class QueryInterface {
                 whereSql = whereSql ? `${whereSql} AND ${versionCheck}` : ` WHERE ${versionCheck}`;
             }
             this.assertMutationHasPredicate('update', whereSql, args.allowFullTableScan);
-            return `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}${this.dialect.buildReturningClause('*')}`;
+            // Engines that inject their returning shape MID-statement (SQL Server
+            // `OUTPUT INSERTED.*` between SET and WHERE) override buildUpdateStatement;
+            // absent → the trailing-clause PG/SQLite/MySQL form (byte-identical).
+            return this.dialect.buildUpdateStatement
+                ? this.dialect.buildUpdateStatement({ table: this.q(this.table), setClauses, whereSql, returning: '*' })
+                : `UPDATE ${this.q(this.table)} SET ${setClauses.join(', ')}${whereSql}${this.dialect.buildReturningClause('*')}`;
         };
         let sql;
         let preparedName;
@@ -1064,6 +1210,26 @@ export class QueryInterface {
             },
             tag: `${this.table}.update`,
             preparedName,
+            // Non-RETURNING engines: UPDATE, then re-fetch the row by the same where.
+            reselect: this.dialect.resultStrategy === 'reselect'
+                ? async (exec) => {
+                    const writeResult = await exec(sql, params, preparedName);
+                    // Optimistic-lock conflict: the version-checked UPDATE matched no
+                    // row. The re-fetch below uses `where` WITHOUT the version
+                    // predicate, so it would return the stale row and silently mask
+                    // the conflict — detect it from affected-rows here instead, to
+                    // match the OptimisticLockError thrown on RETURNING/OUTPUT engines.
+                    if (lock && (writeResult.rowCount ?? 0) === 0) {
+                        throw new OptimisticLockError({
+                            table: this.table,
+                            versionField: lock.field,
+                            expectedVersion: lock.expected,
+                        });
+                    }
+                    const sel = this.buildReselectByWhere(whereObj);
+                    return exec(sel.sql, sel.params);
+                }
+                : undefined,
         };
     }
     // -------------------------------------------------------------------------
@@ -1095,19 +1261,19 @@ export class QueryInterface {
     async runInImplicitTx(fn) {
         const client = await this.pool.connect();
         try {
-            await client.query('BEGIN');
+            await client.query(this.dialect.beginStatement());
             const { TransactionClient } = await import('../client.js');
             // biome-ignore lint/suspicious/noExplicitAny: MiddlewareFn and Middleware are structurally identical
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.options);
             // biome-ignore lint/suspicious/noExplicitAny: TransactionClient satisfies NestedWriteContext['tx'] at runtime
             const ctx = { schema: this.schema, tx: tx };
             const result = await fn(ctx);
-            await client.query('COMMIT');
+            await client.query(this.dialect.commitStatement());
             return result;
         }
         catch (err) {
             try {
-                await client.query('ROLLBACK');
+                await client.query(this.dialect.rollbackStatement());
             }
             catch {
                 // Best-effort rollback — connection may have died.
@@ -1140,8 +1306,7 @@ export class QueryInterface {
     async delete(args) {
         return this.executeWithMiddleware('delete', args, async () => {
             const deferred = this.buildDelete(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
+            return this.executeMutation(deferred, args.timeout);
         });
     }
     buildDelete(args) {
@@ -1156,7 +1321,11 @@ export class QueryInterface {
             const clause = this.buildWhereClause(whereObj, freshParams);
             const whereSql = clause ? ` WHERE ${clause}` : '';
             this.assertMutationHasPredicate('delete', whereSql, args.allowFullTableScan);
-            return `DELETE FROM ${this.q(this.table)}${whereSql}${this.dialect.buildReturningClause('*')}`;
+            // SQL Server injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and WHERE;
+            // absent override → the trailing-clause PG/SQLite/MySQL form (byte-identical).
+            return this.dialect.buildDeleteStatement
+                ? this.dialect.buildDeleteStatement({ table: this.q(this.table), whereSql, returning: '*' })
+                : `DELETE FROM ${this.q(this.table)}${whereSql}${this.dialect.buildReturningClause('*')}`;
         });
         // On cache hit, still validate the predicate
         if (whereFp === '') {
@@ -1179,6 +1348,16 @@ export class QueryInterface {
             },
             tag: `${this.table}.delete`,
             preparedName: entry.name,
+            // Non-RETURNING engines: the row is gone after DELETE, so pre-SELECT it
+            // by the same where, then run the DELETE, returning the captured row.
+            reselect: this.dialect.resultStrategy === 'reselect'
+                ? async (exec) => {
+                    const sel = this.buildReselectByWhere(whereObj);
+                    const pre = await exec(sel.sql, sel.params);
+                    await exec(entry.sql, params, entry.name);
+                    return pre;
+                }
+                : undefined,
         };
     }
     // -------------------------------------------------------------------------
@@ -1187,8 +1366,7 @@ export class QueryInterface {
     async upsert(args) {
         return this.executeWithMiddleware('upsert', args, async () => {
             const deferred = this.buildUpsert(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
+            return this.executeMutation(deferred, args.timeout);
         });
     }
     buildUpsert(args) {
@@ -1234,6 +1412,14 @@ export class QueryInterface {
                 return this.parseRow(row, this.table);
             },
             tag: `${this.table}.upsert`,
+            // Non-RETURNING engines: run the upsert, then re-fetch by the where keys.
+            reselect: this.dialect.resultStrategy === 'reselect'
+                ? async (exec) => {
+                    await exec(sql, params);
+                    const sel = this.buildReselectByWhere(args.where);
+                    return exec(sel.sql, sel.params);
+                }
+                : undefined,
         };
     }
     // -------------------------------------------------------------------------
@@ -1328,7 +1514,7 @@ export class QueryInterface {
             const freshParams = [];
             const clause = args?.where ? this.buildWhereClause(whereObj, freshParams) : null;
             const whereSql = clause ? ` WHERE ${clause}` : '';
-            return `SELECT COUNT(*)::int AS count FROM ${this.q(this.table)}${whereSql}`;
+            return `SELECT ${this.castAgg('COUNT(*)', 'int')} AS count FROM ${this.q(this.table)}${whereSql}`;
         });
         if (args?.where) {
             this.collectWhereParams(whereObj, params);
@@ -1368,7 +1554,7 @@ export class QueryInterface {
         // _count
         if (args._count === true || args._count === undefined) {
             // default: always include count
-            selectExprs.push('COUNT(*)::int AS _count');
+            selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
         // _sum
         if (args._sum) {
@@ -1384,7 +1570,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._avg)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${this.q(col)})::float AS ${this.q(`_avg_${col}`)}`);
+                    selectExprs.push(`${this.castAgg(`AVG(${this.q(col)})`, 'float')} AS ${this.q(`_avg_${col}`)}`);
                 }
             }
         }
@@ -1585,12 +1771,12 @@ export class QueryInterface {
             clauses.push(`${expr} <= ${this.p(params.length)}`);
         }
         if (op.in !== undefined) {
-            params.push(op.in);
-            clauses.push(`${expr} = ANY(${this.p(params.length)})`);
+            params.push(this.inParam(op.in));
+            clauses.push(this.inClause(expr, this.p(params.length), false));
         }
         if (op.notIn !== undefined) {
-            params.push(op.notIn);
-            clauses.push(`${expr} != ALL(${this.p(params.length)})`);
+            params.push(this.inParam(op.notIn));
+            clauses.push(this.inClause(expr, this.p(params.length), true));
         }
         return clauses;
     }
@@ -1628,13 +1814,13 @@ export class QueryInterface {
         const selectExprs = [];
         // _count
         if (args._count === true) {
-            selectExprs.push('COUNT(*)::int AS _count');
+            selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
         else if (args._count && typeof args._count === 'object') {
             for (const [field, enabled] of Object.entries(args._count)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`COUNT(${this.q(col)})::int AS ${this.q(`_count_${col}`)}`);
+                    selectExprs.push(`${this.castAgg(`COUNT(${this.q(col)})`, 'int')} AS ${this.q(`_count_${col}`)}`);
                 }
             }
         }
@@ -1652,7 +1838,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._avg)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${this.q(col)})::float AS ${this.q(`_avg_${col}`)}`);
+                    selectExprs.push(`${this.castAgg(`AVG(${this.q(col)})`, 'float')} AS ${this.q(`_avg_${col}`)}`);
                 }
             }
         }
@@ -1675,7 +1861,7 @@ export class QueryInterface {
             }
         }
         if (selectExprs.length === 0) {
-            selectExprs.push('COUNT(*)::int AS _count');
+            selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
         const sql = `SELECT ${selectExprs.join(', ')} FROM ${this.q(this.table)}${whereSql}`;
         return {
@@ -2169,9 +2355,9 @@ export class QueryInterface {
         if (op.not !== undefined && op.not !== null)
             params.push(op.not);
         if (op.in !== undefined)
-            params.push(op.in);
+            params.push(this.inParam(op.in));
         if (op.notIn !== undefined)
-            params.push(op.notIn);
+            params.push(this.inParam(op.notIn));
         if (op.contains !== undefined)
             params.push(`%${escapeLike(op.contains)}%`);
         if (op.startsWith !== undefined)
@@ -2336,7 +2522,7 @@ export class QueryInterface {
             if (spec.where) {
                 this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
             }
-            if (spec.limit !== undefined) {
+            if (spec.limit !== undefined && !this.dialect.inlineLimitOffset) {
                 params.push(Number(spec.limit));
             }
             if (spec.with) {
@@ -2369,7 +2555,7 @@ export class QueryInterface {
         // buildRelationSubquery). belongsTo/hasOne ignore limit (always LIMIT 1), so
         // pushing one here would orphan a param and desync the collect path.
         // `limit: 0` pushes (LIMIT 0 is honored), so check !== undefined.
-        if (relDef.type === 'hasMany' && spec.limit !== undefined) {
+        if (relDef.type === 'hasMany' && spec.limit !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(Number(spec.limit));
         }
         // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
@@ -2888,12 +3074,12 @@ export class QueryInterface {
             }
         }
         if (op.in !== undefined) {
-            params.push(op.in);
-            clauses.push(`${column} = ANY(${this.p(params.length)})`);
+            params.push(this.inParam(op.in));
+            clauses.push(this.inClause(column, this.p(params.length), false));
         }
         if (op.notIn !== undefined) {
-            params.push(op.notIn);
-            clauses.push(`${column} != ALL(${this.p(params.length)})`);
+            params.push(this.inParam(op.notIn));
+            clauses.push(this.inClause(column, this.p(params.length), true));
         }
         const buildLikeClause = (paramRef) => op.mode === 'insensitive' ? this.dialect.buildInsensitiveLike(column, paramRef) : `${column} LIKE ${paramRef}`;
         if (op.contains !== undefined) {
@@ -2964,6 +3150,9 @@ export class QueryInterface {
      * non-vector column — a user-supplied string can never become a SQL operator.
      */
     vectorOperator(field, rawColumn, metric) {
+        if (!this.dialect.supportsVector) {
+            throw new UnsupportedFeatureError('pgvector distance operations', this.dialect.name, 'Vector search requires PostgreSQL with the pgvector extension.');
+        }
         const colType = this.getColumnPgType(rawColumn);
         if (colType !== 'vector') {
             throw new ValidationError(`[turbine] Column "${field}" on table "${this.table}" is not a vector column ` +
@@ -2984,6 +3173,9 @@ export class QueryInterface {
      * placeholder string.
      */
     pushVectorParam(field, _rawColumn, to, params) {
+        if (!this.dialect.supportsVector) {
+            throw new UnsupportedFeatureError('pgvector distance operations', this.dialect.name, 'Vector search requires PostgreSQL with the pgvector extension.');
+        }
         if (!Array.isArray(to) || to.length === 0) {
             throw new ValidationError(`[turbine] Vector distance on "${field}" requires a non-empty array of numbers for "to".`);
         }
@@ -3294,6 +3486,32 @@ export class QueryInterface {
                 .map(([k]) => targetMeta.columnMap[k] ?? camelToSnake(k)));
             targetColumns = targetMeta.allColumns.filter((col) => !omittedFields.has(col));
         }
+        // Engine override seam (additive): a dialect whose JSON-aggregation shape does
+        // not map onto buildJsonObject/buildJsonArrayAgg (SQL Server FOR JSON PATH) owns
+        // the WHOLE subquery. Absent for PG/MySQL/SQLite → the native path below runs
+        // unchanged (byte-identical output, all their tests stay green). The override
+        // pushes params per the documented RelationSubqueryContext ordering contract,
+        // which mirrors collectRelationSubqueryParams so the SQL cache / pipeline stay
+        // in sync.
+        if (this.dialect.buildRelationSubquery) {
+            return this.dialect.buildRelationSubquery({
+                relDef,
+                spec,
+                params,
+                parentRef,
+                alias,
+                targetTable,
+                targetMeta,
+                targetColumns,
+                depth: currentDepth,
+                path: currentPath,
+                quote: (name) => this.q(name),
+                buildWhere: (whereAlias) => (spec !== true && spec.where
+                    ? this.buildAliasWhere(targetTable, targetMeta, whereAlias, spec.where, params)
+                    : '') ?? '',
+                recurse: (nRelDef, nSpec, nParent, nDepth, nPath) => this.buildRelationSubquery(nRelDef, nSpec, params, nParent, aliasCounter, nDepth, nPath),
+            });
+        }
         // Build JSON object pairs for resolved columns
         const jsonPairs = targetColumns.map((col) => [
             targetMeta.reverseColumnMap[col] ?? snakeToCamel(col),
@@ -3325,7 +3543,7 @@ export class QueryInterface {
                 const nestedSubquery = this.buildRelationSubquery(nestedRelDef, nestedSpec, params, alias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name]);
                 // Use '[]'::json for hasMany (empty array), NULL for belongsTo/hasOne (no object)
                 const fallback = nestedRelDef.type === 'hasMany' ? this.dialect.emptyJsonArrayLiteral : this.dialect.nullJsonLiteral;
-                jsonPairs.push([nestedRelName, `COALESCE((${nestedSubquery}), ${fallback})`]);
+                jsonPairs.push([nestedRelName, this.dialect.wrapJsonSubresult(nestedSubquery, fallback)]);
             }
         }
         const jsonObj = this.dialect.buildJsonObject(jsonPairs);
@@ -3373,8 +3591,7 @@ export class QueryInterface {
         // `limit: 0` is honored (LIMIT 0 → empty array), so check !== undefined.
         let limitClause = '';
         if (relDef.type === 'hasMany' && spec !== true && spec.limit !== undefined) {
-            params.push(Number(spec.limit));
-            limitClause = ` LIMIT ${this.p(params.length)}`;
+            limitClause = ` LIMIT ${this.paginationRef(spec.limit, params)}`;
         }
         if (relDef.type === 'hasMany') {
             // When LIMIT or ORDER BY is used, wrap in a subquery so LIMIT applies to rows
@@ -3399,13 +3616,17 @@ export class QueryInterface {
                         }
                         const nestedSub = this.buildRelationSubquery(nestedRelDef, nestedSpec, params, innerAlias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name]);
                         const fallback = nestedRelDef.type === 'hasMany' ? this.dialect.emptyJsonArrayLiteral : this.dialect.nullJsonLiteral;
-                        innerJsonPairs.push([nestedRelName, `COALESCE((${nestedSub}), ${fallback})`]);
+                        innerJsonPairs.push([nestedRelName, this.dialect.wrapJsonSubresult(nestedSub, fallback)]);
                     }
                 }
                 const innerJsonObj = this.dialect.buildJsonObject(innerJsonPairs);
                 return `SELECT ${this.dialect.buildJsonArrayAgg(innerJsonObj)} FROM (${innerSql}) ${innerAlias}`;
             }
-            return `SELECT ${this.dialect.buildJsonArrayAgg(jsonObj, orderClause.trim() || undefined)} FROM ${qTarget} ${alias} WHERE ${whereClause}`;
+            // Inline ORDER BY only when the dialect's array-agg supports it (PG). For
+            // hasMany this path is reached only when there is no orderClause, so the
+            // argument is `undefined` either way — keeping PG output byte-identical.
+            const inlineOrder = this.dialect.aggSupportsInlineOrderBy ? orderClause.trim() || undefined : undefined;
+            return `SELECT ${this.dialect.buildJsonArrayAgg(jsonObj, inlineOrder)} FROM ${qTarget} ${alias} WHERE ${whereClause}`;
         }
         // belongsTo / hasOne — return single object
         return `SELECT ${jsonObj} FROM ${qTarget} ${alias} WHERE ${whereClause} LIMIT 1`;
@@ -3493,8 +3714,7 @@ export class QueryInterface {
         // LIMIT — `limit: 0` is honored (LIMIT 0 → empty array)
         let limitClause = '';
         if (spec !== true && spec.limit !== undefined) {
-            params.push(Number(spec.limit));
-            limitClause = ` LIMIT ${this.p(params.length)}`;
+            limitClause = ` LIMIT ${this.paginationRef(spec.limit, params)}`;
         }
         const fromJoin = `FROM ${qTarget} ${talias} JOIN ${qJunction} ${jalias} ON ${joinOn}`;
         // When LIMIT or ORDER BY is present, wrap the joined rows in an inner subquery
@@ -3519,7 +3739,7 @@ export class QueryInterface {
                     const fallback = nestedRelDef.type === 'belongsTo' || nestedRelDef.type === 'hasOne'
                         ? this.dialect.nullJsonLiteral
                         : this.dialect.emptyJsonArrayLiteral;
-                    innerJsonPairs.push([nestedRelName, `COALESCE((${nestedSub}), ${fallback})`]);
+                    innerJsonPairs.push([nestedRelName, this.dialect.wrapJsonSubresult(nestedSub, fallback)]);
                 }
             }
             const innerJsonObj = this.dialect.buildJsonObject(innerJsonPairs);
@@ -3542,7 +3762,7 @@ export class QueryInterface {
                 const fallback = nestedRelDef.type === 'belongsTo' || nestedRelDef.type === 'hasOne'
                     ? this.dialect.nullJsonLiteral
                     : this.dialect.emptyJsonArrayLiteral;
-                jsonPairs.push([nestedRelName, `COALESCE((${nestedSub}), ${fallback})`]);
+                jsonPairs.push([nestedRelName, this.dialect.wrapJsonSubresult(nestedSub, fallback)]);
             }
         }
         const jsonObj = this.dialect.buildJsonObject(jsonPairs);