uql-orm 0.51.0 → 0.53.0

package/dist/bunSql/bunSqlQuerierPool.js

@@ -1,19 +1,28 @@
 import { SQL } from 'bun';
+import { CockroachDialect } from '../cockroachdb/cockroachDialect.js';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { MariaDialect } from '../maria/mariaDialect.js';
 import { MySqlDialect } from '../mysql/mysqlDialect.js';
+import { PostgresDialect } from '../postgres/postgresDialect.js';
+import { POSTGRES_WIRE_DRIVER_CAPABILITIES } from '../postgres/postgresWireDriverCapabilities.js';
 import { AbstractSqlQuerierPool } from '../querier/index.js';
-import { getAffectedRows, inferDialectName, isPoolableDialect, normalizeBunOpts, normalizeRows, } from './bunSql.util.js';
-import { BunSqlCockroachDialect } from './bunSqlCockroachDialect.js';
-import { BunSqlPostgresDialect } from './bunSqlPostgresDialect.js';
+import { SqliteDialect } from '../sqlite/sqliteDialect.js';
+import { getAffectedRows, inferDialectName, normalizeBunOpts, normalizeRows, } from './bunSql.util.js';
 import { BunSqlQuerier } from './bunSqlQuerier.js';
-import { BunSqliteDialect } from './bunSqliteDialect.js';
+/**
+ * The dialect each engine `bun:sql` drives is given, and how this driver shapes its parameters.
+ *
+ * The engine dialects themselves, not `bun:sql` subclasses of them: what Bun changes is the binding,
+ * never the SQL, and a per-instance `driverCapabilities` is where the base class already takes that -
+ * so the Postgres and CockroachDB entries differ from `PgQuerierPool`'s only by naming the same
+ * constant. Total over {@link BunSqlDialectName}, so a new Bun adapter has to be answered here.
+ */
 const DialectMap = {
-    postgres: BunSqlPostgresDialect,
-    mysql: MySqlDialect,
-    mariadb: MariaDialect,
-    sqlite: BunSqliteDialect,
-    cockroachdb: BunSqlCockroachDialect,
+    postgres: [PostgresDialect, POSTGRES_WIRE_DRIVER_CAPABILITIES],
+    cockroachdb: [CockroachDialect, POSTGRES_WIRE_DRIVER_CAPABILITIES],
+    mysql: [MySqlDialect],
+    mariadb: [MariaDialect],
+    sqlite: [SqliteDialect],
 };
 export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
     config;
@@ -22,7 +31,8 @@ export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
     foreignKeysOn;
     constructor(config, extra) {
         const dialectName = inferDialectName(config);
-        super(new DialectMap[dialectName](dialectOptionsFrom(extra)), extra);
+        const [Dialect, driverCapabilities] = DialectMap[dialectName];
+        super(new Dialect({ ...dialectOptionsFrom(extra), driverCapabilities }), extra);
         this.config = config;
         this.sqlDialectName = dialectName;
         const opts = normalizeBunOpts(config, dialectName);
@@ -34,28 +44,31 @@ export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
      */
     get pool() {
         return {
-            query: (text, values) => this.sql.unsafe(text, this.dialect.normalizeValues(values)).then((res) => ({
-                rows: normalizeRows(res),
-                rowCount: getAffectedRows(res),
-            })),
+            query: (text, values) => this.sql.unsafe(text, this.dialect.normalizeValues(values)).then((res) => {
+                const rows = normalizeRows(res);
+                return { rows, rowCount: getAffectedRows(res) ?? rows.length };
+            }),
             on: () => {
                 /* no-op for event listeners */
             },
         };
     }
     async getQuerier() {
-        const connFactory = async () => {
-            // Bun's SQLite adapter does not support connection reservation (it's unpooled), and leaves
-            // `foreign_keys` off as `bun:sqlite` does, so without the pragma the constraints uql emits in
-            // its own DDL are decorative. One connection means one pragma, issued on the first acquisition.
-            if (!isPoolableDialect(this.sqlDialectName)) {
-                this.foreignKeysOn ??= this.sql.unsafe('PRAGMA foreign_keys = ON');
-                await this.foreignKeysOn;
-                return this.sql;
-            }
+        return new BunSqlQuerier(this.sql, this.dialect, () => this.acquire(), this.extra);
+    }
+    /**
+     * Bun's SQLite adapter does not support connection reservation (it's unpooled), and leaves
+     * `foreign_keys` off as `bun:sqlite` does, so without the pragma the constraints uql emits in its
+     * own DDL are decorative. One connection means one pragma, issued on the first acquisition, and a
+     * `release` that does nothing: the handle is the pool's, and outlives every querier over it.
+     */
+    async acquire() {
+        if (this.sqlDialectName !== 'sqlite') {
             return this.sql.reserve();
-        };
-        return new BunSqlQuerier(this.sql, this.dialect, connFactory, this.extra);
+        }
+        this.foreignKeysOn ??= this.sql.unsafe('PRAGMA foreign_keys = ON');
+        await this.foreignKeysOn;
+        return { unsafe: this.sql.unsafe.bind(this.sql), release: () => { } };
     }
     async end() {
         await this.sql.close();

package/dist/bunSql/index.d.ts

@@ -1,5 +1,3 @@
-export * from './bunSqliteDialect.js';
-export * from './bunSqlCockroachDialect.js';
-export * from './bunSqlPostgresDialect.js';
+export type { BunSqlConn, BunSqlDialectName, BunSqlResult } from './bunSql.util.js';
 export * from './bunSqlQuerier.js';
 export * from './bunSqlQuerierPool.js';

package/dist/bunSql/index.js

@@ -1,5 +1,2 @@
-export * from './bunSqliteDialect.js';
-export * from './bunSqlCockroachDialect.js';
-export * from './bunSqlPostgresDialect.js';
 export * from './bunSqlQuerier.js';
 export * from './bunSqlQuerierPool.js';

package/dist/dialect/abstractDialect.d.ts

@@ -1,4 +1,4 @@
-import type { DialectFeatures, DialectName, EntityMeta, ExtraOptions, FieldOptions, InsertIdSource, NamingStrategy, QueryGroupOp, QueryOptions, QueryWhere, QueryWhereArray, QueryWhereMap } from '../type/index.js';
+import type { DialectFeatures, DialectName, EntityMeta, ExtraOptions, FieldOptions, InsertIdSource, NamingStrategy, QueryGroupOp, QueryOptions, QueryWhere, QueryWhereArray } from '../type/index.js';
 /**
  * Options for initializing a dialect.
  */
@@ -72,11 +72,11 @@ export declare abstract class AbstractDialect {
      */
     columnOf<E>(meta: EntityMeta<E>, key: string): string;
     /**
-     * A `$where` normalized to a map with the entity's active filters merged in - the only way any
-     * dialect should enter a new query scope, so a scope cannot be rendered with its `security: true`
-     * filters skipped. Recursion within one scope renders the returned map directly instead.
+     * A `$where` with the entity's active filters merged in - the only way any dialect should enter a
+     * new query scope, so a scope cannot be rendered with its `security: true` filters skipped.
+     * Recursion within one scope renders the returned map directly instead.
      */
-    protected scopedWhereMap<E>(meta: EntityMeta<E>, where?: QueryWhere<E>, opts?: QueryOptions): QueryWhereMap<E>;
+    protected scopedWhere<E>(meta: EntityMeta<E>, where?: QueryWhere<E>, opts?: QueryOptions): QueryWhere<E>;
     /**
      * How each clause-grouping operator renders: which operator joins its clauses, and whether the
      * group is negated afterwards - so `$not` is `NOT (a AND b)` and `$nor` is `NOT (a OR b)`. SQL

package/dist/dialect/abstractDialect.js

@@ -1,4 +1,4 @@
-import { applyFilters, buildQueryWhereAsMap } from '../util/dialect.util.js';
+import { applyFilters, assertWhere } from '../util/dialect.util.js';
 import { entityName } from '../util/index.js';
 import { qualifyName } from '../util/sql.util.js';
 /**
@@ -81,12 +81,13 @@ export class AbstractDialect {
         return this.resolveColumnName(key, meta.fields[key]);
     }
     /**
-     * A `$where` normalized to a map with the entity's active filters merged in - the only way any
-     * dialect should enter a new query scope, so a scope cannot be rendered with its `security: true`
-     * filters skipped. Recursion within one scope renders the returned map directly instead.
+     * A `$where` with the entity's active filters merged in - the only way any dialect should enter a
+     * new query scope, so a scope cannot be rendered with its `security: true` filters skipped.
+     * Recursion within one scope renders the returned map directly instead.
      */
-    scopedWhereMap(meta, where = {}, opts) {
-        return applyFilters(meta, buildQueryWhereAsMap(meta, where), opts);
+    scopedWhere(meta, where = {}, opts) {
+        assertWhere(meta, where);
+        return applyFilters(meta, where, opts);
     }
     /**
      * How each clause-grouping operator renders: which operator joins its clauses, and whether the

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { type EntityData, type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
 import { type ParentPartition } from '../util/index.js';
 import type { HydrateKind } from './hydrateColumn.js';
 import { type JsonAccessMode } from './jsonSql.js';
@@ -6,6 +6,15 @@ import { type QueryJoins, type QuerySortOptions } from './queryJoins.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
 /** How a column's values are bound: see {@link AbstractSqlDialect.persistKind}. */
 type PersistKind = 'plain' | 'json' | 'vector';
+/** What {@link AbstractSqlDialect.insertShape} resolves once for a write, indexed in step. */
+type InsertShape<E> = {
+    readonly meta: EntityMeta<E>;
+    readonly payloads: EntityData<E>[];
+    readonly keys: FieldKey<E>[];
+    readonly fields: (FieldOptions | undefined)[];
+    readonly columns: string[];
+    readonly kinds: PersistKind[];
+};
 /** One entry of {@link AbstractSqlDialect.hydratableFields}: a field key and how it decodes. */
 type HydratableField = readonly [string, HydrateKind];
 export type { HydrateKind };
@@ -45,7 +54,6 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     readonly dropPrimaryKeySyntax: 'DROP CONSTRAINT' | 'DROP PRIMARY KEY';
     readonly dropIndexSyntax: 'on-table' | 'standalone';
-    readonly renameTableSyntax: 'rename-table' | 'alter-table';
     readonly booleanLiteral: 'native' | 'integer';
     /**
      * Maximum number of bind parameters the driver accepts in a single statement.
@@ -111,6 +119,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected returningIdExpression<E>(meta: EntityMeta<E>): string;
     search<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, joins?: QueryJoins): void;
     selectFields<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelectValue<E> | undefined, opts?: QuerySelectOptions, exclude?: QueryExclude<E>): void;
+    /**
+     * What follows `SELECT` before the projection. Empty everywhere but SQL Server, whose `FETCH` will
+     * not take a zero and which spells "no rows" as `TOP (0)` instead.
+     */
+    protected selectModifier<E>(_q: Query<E>): string;
     /**
      * The expression a scalar field is read through, the plain column by default. MariaDB reads a
      * vector column back with `VEC_ToText`, since selecting it raw yields its binary form.
@@ -280,7 +293,9 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected jsonScalarParam(ctx: QueryContext, value: unknown): string;
     /** {@link resolveOperandField}, appended. */
     getComparisonKey<E>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, opts?: QueryOptions): void;
-    sort<E>(ctx: QueryContext, entity: Type<E>, sort: QuerySortMap<E> | undefined, opts?: QuerySortOptions): void;
+    /** Appends the `ORDER BY`, reporting whether there was one - which {@link pager} needs on the
+     * engines that refuse to page an unordered statement. */
+    sort<E>(ctx: QueryContext, entity: Type<E>, sort: QuerySortMap<E> | undefined, opts?: QuerySortOptions): boolean;
     /**
      * Walks `$sort` against the metadata of the entity each level addresses, rather than flattening it
      * to dotted strings and reading every key off the root: only that way does a related column resolve
@@ -293,7 +308,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * `$agg` alias - is an output alias, which is never table-qualified and needs no resolving.
      */
     private sortColumn;
-    pager(ctx: QueryContext, opts: QueryPager): void;
+    /**
+     * `LIMIT`/`OFFSET`. `sorted` says whether an `ORDER BY` was emitted just before, which
+     * {@link MergeSqlDialect} needs: SQL Server refuses to page a statement that has none.
+     */
+    pager(ctx: QueryContext, opts: QueryPager, _sorted?: boolean): void;
     /** Whether this engine has row locks at all. The SQLite family locks the database instead. */
     readonly supportsRowLocks: boolean;
     /**
@@ -306,6 +325,12 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     readonly supportsLockOf: boolean;
     /** Validated before the querier checks for a transaction, so the clearer error wins. */
     assertLockSupported<E>(entity: Type<E>, q: Query<E>, joins?: QueryJoins): void;
+    /**
+     * The lock as a hint on the table itself, for the engine that has no trailing `FOR UPDATE`. Empty
+     * everywhere else, which is where {@link appendLock} does the work instead - the two are the same
+     * lock spelled at opposite ends of the statement, so exactly one of them ever emits.
+     */
+    protected lockHint<E>(_q: Query<E>): string;
     /**
      * The trailing `FOR UPDATE`. Narrowing to the queried table is not a nicety once a relation is
      * joined: Postgres refuses a bare `FOR UPDATE` over the nullable side of an outer join outright,
@@ -354,11 +379,32 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected readonly totalOverExpr = "COUNT(*) OVER ()";
     find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    /**
+     * Where the clause reporting an insert's generated ids goes. `suffix` is `RETURNING ...` at the end
+     * of the statement, which every engine here but one spells that way; SQL Server's `OUTPUT` has no
+     * trailing form and sits between the column list and `VALUES`.
+     *
+     * A knob rather than a pair of hooks: one concept decides where the string {@link returningId}
+     * already built ends up, so the two ends cannot disagree.
+     */
+    readonly returningPosition: 'suffix' | 'after-target';
     /**
      * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
      * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
      */
-    protected appendInsertValues<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[]): void;
+    protected appendInsertValues<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], 
+    /** Spliced between the column list and `VALUES`; see {@link returningPosition}. */
+    afterTarget?: string): void;
+    /**
+     * The columns an insert writes and the records it writes them from, resolved once.
+     *
+     * Split out of {@link appendInsertValues} because a `MERGE` needs the same rows as a `VALUES` row
+     * source rather than as an `INSERT`, and both have to apply `onInsert` defaults and the
+     * JSON/vector binding rules identically.
+     */
+    protected insertShape<E>(entity: Type<E>, payload: E | E[]): InsertShape<E>;
+    /** `(a, b), (c, d)` - the row constructor an INSERT and a MERGE source both write. */
+    protected appendValueRows<E>(ctx: QueryContext, { payloads, keys, fields, kinds }: InsertShape<E>): void;
     /**
      * Emit the value for a column a payload record does not provide (the column list is the union
      * across all records). `DEFAULT` delegates to the database default; SQLite overrides this since
@@ -550,7 +596,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     private appendRelationSubquery;
     /** Filter by relation: a parent matches when {@link appendRelationSubquery} finds one target row. */
-    protected compareRelation<E>(ctx: QueryContext, entity: Type<E>, val: QueryWhereMap<unknown>, rel: RelationMeta, opts: QueryComparisonOptions): void;
+    protected compareRelation<E>(ctx: QueryContext, entity: Type<E>, val: QueryWhere<unknown>, rel: RelationMeta, opts: QueryComparisonOptions): void;
     /** Filter by relation size: the same subquery, counting instead of testing for existence. */
     protected compareRelationSize<E>(ctx: QueryContext, entity: Type<E>, sizeVal: number | QuerySizeComparisonOps, rel: RelationMeta, opts: QueryComparisonOptions): void;
     /**
@@ -587,6 +633,13 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
     escape(value: unknown): string;
     protected get regexpOp(): string;
+    /**
+     * The `$regex` predicate. An infix operator on the MySQL family (`REGEXP`) and the Postgres one
+     * (`~`), but a function on Oracle and SQL Server 2025 (`REGEXP_LIKE(col, ?)`) - which is why this
+     * is a method rather than the operator token alone. An engine with no regex at all overrides it to
+     * throw, the way {@link appendTextSearch} already does.
+     */
+    protected regexCondition(operand: string, placeholder: string): string;
     protected get likeFn(): string;
     /**
      * Not-equal operator token for non-null comparisons.

package/dist/dialect/abstractSqlDialect.js

@@ -1,7 +1,7 @@
 import { getMeta, soleIdOf } from '../entity/index.js';
 import { parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, VECTOR_QUERY_KEYS, } from '../type/index.js';
 import { computedExpression, isInlinedExpression } from '../util/field.util.js';
-import { asSelectMap, assertNonNegativeInteger, buildQueryWhereAsMap, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, columnFamily, isJsonUpdateOp, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationSize, parseSortByCount, populatesRelations, queryChildrenOf, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, columnFamily, isJsonUpdateOp, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationSize, parseSortByCount, populatesRelations, queryChildrenOf, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { COUNT_ALIAS, DISTINCT_DERIVED_ALIAS, JSON_ELEM_ALIAS_PREFIX, PER_PARENT_BRANCH_ALIAS } from './aliases.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
@@ -36,7 +36,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      */
     dropPrimaryKeySyntax = 'DROP CONSTRAINT';
     dropIndexSyntax = 'standalone';
-    renameTableSyntax = 'alter-table';
     booleanLiteral = 'native';
     /**
      * Maximum number of bind parameters the driver accepts in a single statement.
@@ -168,8 +167,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             opts = { ...opts, prefix };
         }
         this.where(ctx, entity, q.$where, opts);
-        this.sort(ctx, entity, q.$sort, { prefix, joins, distinct: q.$distinct });
-        this.pager(ctx, q);
+        const sorted = this.sort(ctx, entity, q.$sort, { prefix, joins, distinct: q.$distinct });
+        this.pager(ctx, q, sorted);
     }
     selectFields(ctx, entity, select, opts = {}, exclude) {
         const meta = getMeta(entity);
@@ -227,6 +226,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             }
         });
     }
+    /**
+     * What follows `SELECT` before the projection. Empty everywhere but SQL Server, whose `FETCH` will
+     * not take a zero and which spells "no rows" as `TOP (0)` instead.
+     */
+    selectModifier(_q) {
+        return '';
+    }
     /**
      * The expression a scalar field is read through, the plain column by default. MariaDB reads a
      * vector column back with `VEC_ToText`, since selecting it raw yields its binary form.
@@ -248,6 +254,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const { alias, ref } = this.tableRef(meta);
         const prefix = this.resolveRelationAwarePrefix(alias, meta, opts, q.$populate, joins);
         ctx.append(q.$distinct ? 'SELECT DISTINCT ' : 'SELECT ');
+        ctx.append(this.selectModifier(q));
         this.selectFields(ctx, entity, q.$select, { prefix }, q.$exclude);
         // Add related fields BEFORE FROM clause
         this.selectRelationFields(ctx, joins);
@@ -261,7 +268,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         if (totalAlias) {
             ctx.append(`, ${this.totalOverExpr} ${this.escapeId(totalAlias, true)}`);
         }
-        ctx.append(` FROM ${ref}`);
+        ctx.append(` FROM ${ref}${this.lockHint(q)}`);
         // Add JOINs AFTER FROM clause
         this.selectRelationJoins(ctx, meta, alias, joins);
     }
@@ -322,21 +329,19 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     where(ctx, entity, where = {}, opts = {}) {
         const meta = getMeta(entity);
         // Filters are applied once, here at the scope entry point; recursion uses `renderWhere`.
-        this.renderWhere(ctx, entity, this.scopedWhereMap(meta, where, opts), opts);
+        this.renderWhere(ctx, entity, this.scopedWhere(meta, where, opts), opts);
     }
     /** Renders a `$where` tree without applying entity filters (used for same-scope group-operator recursion). */
     renderWhere(ctx, entity, where = {}, opts = {}) {
-        const meta = getMeta(entity);
         const { clause = 'WHERE' } = opts;
-        const whereMap = buildQueryWhereAsMap(meta, where);
         // An `undefined` value emits nothing, so it must not count towards the terms either: it decides
         // whether the keys below render as operands of an `AND`.
-        const whereKeys = getKeys(whereMap).filter((key) => whereMap[key] !== undefined);
+        const whereKeys = getKeys(where).filter((key) => where[key] !== undefined);
         // Each key is an operand of the `AND` joining them; a lone key emits this fragment verbatim, so
         // it inherits this one's position instead.
         const childOperand = whereKeys.length > 1 || opts.operand || clause === 'AND';
         const childOpts = opts.operand === childOperand ? opts : { ...opts, operand: childOperand };
-        const parts = this.renderOperands(ctx, whereKeys, (fragmentCtx, key) => this.compare(fragmentCtx, entity, key, whereMap[key], childOpts));
+        const parts = this.renderOperands(ctx, whereKeys, (fragmentCtx, key) => this.compare(fragmentCtx, entity, key, where[key], childOpts));
         if (!parts.length) {
             return;
         }
@@ -582,7 +587,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             case '$ne':
                 return val === null ? `${operand} IS NOT NULL` : this.neExpr(operand, this.addValue(ctx.values, val));
             case '$regex':
-                return `${operand} ${this.regexpOp} ${this.addValue(ctx.values, val)}`;
+                return this.regexCondition(operand, this.addValue(ctx.values, val));
             case '$in':
             case '$nin': {
                 if (!Array.isArray(val)) {
@@ -643,7 +648,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                     return `${jsonField} IS NOT NULL`;
                 return this.neExpr(comparand(value), this.jsonOperand(ctx, value, asJson));
             case '$regex':
-                return `${jsonField} ${this.regexpOp} ${this.addValue(ctx.values, value)}`;
+                return this.regexCondition(jsonField, this.addValue(ctx.values, value));
             case '$in':
             case '$nin':
                 return this.jsonInNin(ctx, jsonField, comparand, op, value, asJson);
@@ -737,15 +742,18 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             return this.addValue(ctx.values, value);
         }
         ctx.pushValue(JSON.stringify(value));
-        return this.jsonCast('?');
+        // The placeholder for the value just pushed, so a named or numbered one is spelled correctly.
+        return this.jsonCast(this.placeholder(ctx.values.length));
     }
     /** {@link resolveOperandField}, appended. */
     getComparisonKey(ctx, entity, key, opts = {}) {
         ctx.append(this.resolveOperandField(ctx, entity, key, opts));
     }
+    /** Appends the `ORDER BY`, reporting whether there was one - which {@link pager} needs on the
+     * engines that refuse to page an unordered statement. */
     sort(ctx, entity, sort, opts = {}) {
         if (!hasKeys(sort)) {
-            return;
+            return false;
         }
         // Collected before anything is appended so an unorderable key is reported instead of half a
         // clause, and because a vector distance is the primary ordering wherever it appears in the map.
@@ -756,6 +764,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         if (terms.length) {
             ctx.append(` ORDER BY ${terms.join(', ')}`);
         }
+        return terms.length > 0;
     }
     /**
      * Walks `$sort` against the metadata of the entity each level addresses, rather than flattening it
@@ -815,7 +824,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const json = this.resolveJsonDotPath(meta, key, prefix);
         return json ? this.jsonPathExpr(json.column, json.jsonPath, 'text') : this.escapeId(key);
     }
-    pager(ctx, opts) {
+    /**
+     * `LIMIT`/`OFFSET`. `sorted` says whether an `ORDER BY` was emitted just before, which
+     * {@link MergeSqlDialect} needs: SQL Server refuses to page a statement that has none.
+     */
+    pager(ctx, opts, _sorted = false) {
         // `!== undefined`, not truthiness: `$limit: 0` asks for no rows, where "unset" means every row.
         if (opts.$limit !== undefined) {
             ctx.append(` LIMIT ${assertNonNegativeInteger(opts.$limit, '$limit')}`);
@@ -847,6 +860,14 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             throw new TypeError(`${this.dialectName} cannot narrow a row lock to one table, so $lock cannot be combined with a joined relation`);
         }
     }
+    /**
+     * The lock as a hint on the table itself, for the engine that has no trailing `FOR UPDATE`. Empty
+     * everywhere else, which is where {@link appendLock} does the work instead - the two are the same
+     * lock spelled at opposite ends of the statement, so exactly one of them ever emits.
+     */
+    lockHint(_q) {
+        return '';
+    }
     /**
      * The trailing `FOR UPDATE`. Narrowing to the queried table is not a nicety once a relation is
      * joined: Postgres refuses a bare `FOR UPDATE` over the nullable side of an outer join outright,
@@ -946,8 +967,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         if (q.$having) {
             this.having(ctx, q.$having, emittedColumns);
         }
-        this.aggregateSort(ctx, q.$sort, emittedColumns);
-        this.pager(ctx, q);
+        const sorted = this.aggregateSort(ctx, q.$sort, emittedColumns);
+        this.pager(ctx, q, sorted);
     }
     /**
      * ORDER BY for aggregate queries - handles both entity-field and alias references. A grouped
@@ -956,13 +977,14 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      */
     aggregateSort(ctx, sort, emittedColumns) {
         if (!hasKeys(sort))
-            return;
+            return false;
         ctx.append(' ORDER BY ');
         Object.entries(sort).forEach(([key, dir], index) => {
             if (index > 0)
                 ctx.append(', ');
             ctx.append(this.aggregateRef(emittedColumns, key, '$sort') + this.resolveSortDirection(dir));
         });
+        return true;
     }
     /** The SQL referencing one of an aggregate's emitted columns, rejecting any other name. */
     aggregateRef(emittedColumns, key, clause) {
@@ -1021,22 +1043,48 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         this.appendLock(ctx, entity, q, joins);
     }
     insert(ctx, entity, payload, opts) {
-        this.appendInsertValues(ctx, entity, payload);
         // Every engine whose ids come back from the statement itself wants the same clause, so it is
-        // appended once here instead of in an identical `insert` override per dialect. `returningId` is
+        // built once here instead of in an identical `insert` override per dialect. `returningId` is
         // empty on a composite key, which has no id to ask for.
-        if (this.insertIdSource === 'returning') {
-            const returning = this.returningId(getMeta(entity));
-            if (returning) {
-                ctx.append(` ${returning}`);
-            }
+        const returning = this.insertIdSource === 'returning' ? this.returningId(getMeta(entity)) : '';
+        if (returning && this.returningPosition === 'after-target') {
+            this.appendInsertValues(ctx, entity, payload, returning);
+            return;
+        }
+        this.appendInsertValues(ctx, entity, payload);
+        if (returning) {
+            ctx.append(` ${returning}`);
         }
     }
+    /**
+     * Where the clause reporting an insert's generated ids goes. `suffix` is `RETURNING ...` at the end
+     * of the statement, which every engine here but one spells that way; SQL Server's `OUTPUT` has no
+     * trailing form and sits between the column list and `VALUES`.
+     *
+     * A knob rather than a pair of hooks: one concept decides where the string {@link returningId}
+     * already built ends up, so the two ends cannot disagree.
+     */
+    returningPosition = 'suffix';
     /**
      * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
      * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
      */
-    appendInsertValues(ctx, entity, payload) {
+    appendInsertValues(ctx, entity, payload, 
+    /** Spliced between the column list and `VALUES`; see {@link returningPosition}. */
+    afterTarget = '') {
+        const shape = this.insertShape(entity, payload);
+        const tableName = this.escapedTableName(getMeta(entity));
+        ctx.append(`INSERT INTO ${tableName} (${shape.columns.join(', ')})${afterTarget ? ` ${afterTarget}` : ''} VALUES `);
+        this.appendValueRows(ctx, shape);
+    }
+    /**
+     * The columns an insert writes and the records it writes them from, resolved once.
+     *
+     * Split out of {@link appendInsertValues} because a `MERGE` needs the same rows as a `VALUES` row
+     * source rather than as an `INSERT`, and both have to apply `onInsert` defaults and the
+     * JSON/vector binding rules identically.
+     */
+    insertShape(entity, payload) {
         const meta = getMeta(entity);
         const payloads = fillOnFields(meta, payload, 'onInsert');
         const keys = getInsertFieldKeys(meta, payloads);
@@ -1053,12 +1101,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             columns[i] = this.escapedColumnName(meta, key);
             kinds[i] = this.persistKind(field);
         }
-        const tableName = this.escapedTableName(meta);
-        ctx.append(`INSERT INTO ${tableName} (${columns.join(', ')}) VALUES (`);
+        return { meta, payloads, keys, fields, columns, kinds };
+    }
+    /** `(a, b), (c, d)` - the row constructor an INSERT and a MERGE source both write. */
+    appendValueRows(ctx, { payloads, keys, fields, kinds }) {
+        const width = keys.length;
         for (let r = 0; r < payloads.length; r++) {
-            if (r > 0) {
-                ctx.append('), (');
-            }
+            ctx.append(r > 0 ? '), (' : '(');
             const record = payloads[r];
             for (let i = 0; i < width; i++) {
                 if (i > 0) {
@@ -1532,7 +1581,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const relatedMeta = getMeta(relatedEntity);
         const { alias: relatedAlias, ref: relatedRef } = this.tableRef(relatedMeta);
         // Resolved before any SQL is emitted: it also decides whether the mm form reaches the target.
-        const targetWhere = this.scopedWhereMap(relatedMeta, val);
+        const targetWhere = this.scopedWhere(relatedMeta, val);
         ctx.append(`(SELECT ${projection} FROM `);
         // One equality per key of the parent, anded: a composite correlates on every column, and matching
         // on part of one would find the rows of a different parent. `parentJoins` is what keeps the two
@@ -1677,6 +1726,15 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     get regexpOp() {
         return 'REGEXP';
     }
+    /**
+     * The `$regex` predicate. An infix operator on the MySQL family (`REGEXP`) and the Postgres one
+     * (`~`), but a function on Oracle and SQL Server 2025 (`REGEXP_LIKE(col, ?)`) - which is why this
+     * is a method rather than the operator token alone. An engine with no regex at all overrides it to
+     * throw, the way {@link appendTextSearch} already does.
+     */
+    regexCondition(operand, placeholder) {
+        return `${operand} ${this.regexpOp} ${placeholder}`;
+    }
     get likeFn() {
         return 'LIKE';
     }

package/dist/dialect/aliases.d.ts

@@ -32,6 +32,8 @@ export declare const REL_NESTED_KEY = "_uql_target";
  * syntax and keeps `VALUES(col)`.
  */
 export declare const UPSERT_NEW_ROW_ALIAS = "_uql_new";
+/** The row source a `MERGE` upsert reads its incoming values from, on SQL Server and Oracle. */
+export declare const UPSERT_SOURCE_ALIAS = "_uql_src";
 /**
  * Where a `$sort` by a relation's size parks its tally until the ordering has run. A function, so the
  * `$sort` that names the field and the stage that produces it cannot spell it differently - MongoDB

package/dist/dialect/aliases.js

@@ -32,6 +32,8 @@ export const REL_NESTED_KEY = '_uql_target';
  * syntax and keeps `VALUES(col)`.
  */
 export const UPSERT_NEW_ROW_ALIAS = '_uql_new';
+/** The row source a `MERGE` upsert reads its incoming values from, on SQL Server and Oracle. */
+export const UPSERT_SOURCE_ALIAS = '_uql_src';
 /**
  * Where a `$sort` by a relation's size parks its tally until the ordering has run. A function, so the
  * `$sort` that names the field and the stage that produces it cannot spell it differently - MongoDB