uql-orm 0.50.0 → 0.52.0

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/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 QueryWhereMap, 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 };
@@ -111,6 +120,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.
@@ -118,7 +132,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected selectFieldExpr(escapedColumn: string, _field: FieldOptions): string;
     /**
      * The `$text` full-text predicate, which every engine spells differently: `MATCH ... AGAINST`
-     * (MySQL family), `to_tsvector @@ websearch_to_tsquery` (Postgres-wire), an FTS5 `MATCH` against
+     * (MySQL family), `TO_TSVECTOR @@ WEBSEARCH_TO_TSQUERY` (Postgres-wire), an FTS5 `MATCH` against
      * the table itself (SQLite). No portable form exists, so a dialect without one says so here rather
      * than inheriting another engine's syntax.
      */
@@ -253,7 +267,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     protected readonly jsonContainmentIsPartial: boolean;
     /**
-     * Whether an exploded *scalar* element keeps its SQL type. SQLite's `json_each` yields JSON
+     * Whether an exploded *scalar* element keeps its SQL type. SQLite's `JSON_EACH` yields JSON
      * booleans as `0`/`1` integers and numbers as numbers, so such an element compares directly to a
      * bound value; PostgreSQL and MySQL explode scalars to text, losing the type, so a non-string
      * operand there has to compare as JSON (see {@link isJsonbOp}).
@@ -280,7 +294,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 +309,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 +326,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 +380,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
@@ -562,7 +609,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     private buildExprComparison;
     /**
      * Build a complete `$size` comparison expression.
-     * @param sizeExprFn - function that appends the size expression to ctx (e.g. `jsonb_array_length("col")`)
+     * @param sizeExprFn - function that appends the size expression to ctx (e.g. `JSONB_ARRAY_LENGTH("col")`)
      */
     protected buildSizeComparison(ctx: QueryContext, sizeExprFn: () => void, sizeVal: number | QuerySizeComparisonOps): void;
     /**
@@ -587,6 +634,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

@@ -168,8 +168,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 +227,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.
@@ -236,7 +243,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /**
      * The `$text` full-text predicate, which every engine spells differently: `MATCH ... AGAINST`
-     * (MySQL family), `to_tsvector @@ websearch_to_tsquery` (Postgres-wire), an FTS5 `MATCH` against
+     * (MySQL family), `TO_TSVECTOR @@ WEBSEARCH_TO_TSQUERY` (Postgres-wire), an FTS5 `MATCH` against
      * the table itself (SQLite). No portable form exists, so a dialect without one says so here rather
      * than inheriting another engine's syntax.
      */
@@ -248,6 +255,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 +269,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);
     }
@@ -582,7 +590,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 +651,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);
@@ -679,7 +687,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      */
     jsonContainmentIsPartial = true;
     /**
-     * Whether an exploded *scalar* element keeps its SQL type. SQLite's `json_each` yields JSON
+     * Whether an exploded *scalar* element keeps its SQL type. SQLite's `JSON_EACH` yields JSON
      * booleans as `0`/`1` integers and numbers as numbers, so such an element compares directly to a
      * bound value; PostgreSQL and MySQL explode scalars to text, losing the type, so a non-string
      * operand there has to compare as JSON (see {@link isJsonbOp}).
@@ -737,15 +745,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 +767,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 +827,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 +863,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 +970,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 +980,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 +1046,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 +1104,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) {
@@ -1597,7 +1649,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /**
      * Build a complete `$size` comparison expression.
-     * @param sizeExprFn - function that appends the size expression to ctx (e.g. `jsonb_array_length("col")`)
+     * @param sizeExprFn - function that appends the size expression to ctx (e.g. `JSONB_ARRAY_LENGTH("col")`)
      */
     buildSizeComparison(ctx, sizeExprFn, sizeVal) {
         if (typeof sizeVal === 'number') {
@@ -1677,6 +1729,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

package/dist/dialect/jsonSql.d.ts

@@ -7,7 +7,7 @@ import type { FieldOptions, FieldType } from '../type/index.js';
 export declare function jsonPath(path: string, suffix?: string): string;
 /**
  * `FN(target, path, value, ...)` - the multi-pair JSON assignment shape shared by MySQL's
- * `JSON_SET` and SQLite's `json_set`/`json_insert`. `pathSuffix` appends an accessor per key
+ * `JSON_SET` and SQLite's `JSON_SET`/`JSON_INSERT`. `pathSuffix` appends an accessor per key
  * (SQLite's `[#]` append). Values bind in key order through `bindValue`, the caller's
  * `jsonScalarParam` bound to its `QueryContext`.
  */
@@ -54,7 +54,7 @@ export declare function jsonTypeMode(type: FieldType): JsonAccessMode;
  * Whether the operator reads the JSON *value* instead of its text form. The array operators always
  * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in
  * a way no cast recovers portably: PostgreSQL raises `operator does not exist: text = boolean`,
- * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `json_extract` yields
+ * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `JSON_EXTRACT` yields
  * `1`. Comparing the JSON value against a JSON-encoded parameter is exact on every dialect.
  *
  * Numbers stay on the text accessor with a numeric cast, which keeps `1` equal to `1.0` - JSON

package/dist/dialect/jsonSql.js

@@ -11,7 +11,7 @@ export function jsonPath(path, suffix = '') {
 }
 /**
  * `FN(target, path, value, ...)` - the multi-pair JSON assignment shape shared by MySQL's
- * `JSON_SET` and SQLite's `json_set`/`json_insert`. `pathSuffix` appends an accessor per key
+ * `JSON_SET` and SQLite's `JSON_SET`/`JSON_INSERT`. `pathSuffix` appends an accessor per key
  * (SQLite's `[#]` append). Values bind in key order through `bindValue`, the caller's
  * `jsonScalarParam` bound to its `QueryContext`.
  */
@@ -77,7 +77,7 @@ export function jsonTypeMode(type) {
  * Whether the operator reads the JSON *value* instead of its text form. The array operators always
  * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in
  * a way no cast recovers portably: PostgreSQL raises `operator does not exist: text = boolean`,
- * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `json_extract` yields
+ * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `JSON_EXTRACT` yields
  * `1`. Comparing the JSON value against a JSON-encoded parameter is exact on every dialect.
  *
  * Numbers stay on the text accessor with a numeric cast, which keeps `1` equal to `1.0` - JSON

package/dist/dialect/mergeSqlDialect.d.ts

@@ -0,0 +1,45 @@
+import type { QueryConflictPaths, QueryContext, QueryPager, Type } from '../type/index.js';
+import { AbstractSqlDialect } from './abstractSqlDialect.js';
+/**
+ * Shared SQL between SQL Server and Oracle: the two engines that spell paging and upsert the way the
+ * standard does, where the Postgres and MySQL families each predate it.
+ *
+ * A family base rather than a pair of knobs, the way {@link PgLikeSqlDialect} and
+ * {@link MysqlLikeSqlDialect} already are - `pager` and `upsert` are both plain overrides, so nothing
+ * in the core has to learn that a second spelling exists.
+ */
+export declare abstract class MergeSqlDialect extends AbstractSqlDialect {
+    readonly escapeIdChar = "\"";
+    /**
+     * `OFFSET ... ROWS FETCH NEXT ... ROWS ONLY`, and an `ORDER BY` where the statement has none.
+     *
+     * SQL Server refuses to page an unordered statement. A constant `ORDER BY` costs one clause the
+     * optimizer discards and keeps `$limit` and `$skip` meaning the same thing here as everywhere
+     * else; the alternative, `TOP (n)` in the select list, needs a second hook and still leaves a
+     * `$skip` with no `$sort` unanswerable.
+     */
+    pager(ctx: QueryContext, opts: QueryPager & {
+        $distinct?: boolean;
+    }, sorted?: boolean): void;
+    /**
+     * `MERGE`, which both engines take in place of the `ON CONFLICT`/`ON DUPLICATE KEY` the other
+     * families have. The rows go in as a `VALUES` row source rather than an `INSERT`, built by
+     * {@link AbstractSqlDialect.insertShape} so both shapes apply `onInsert` defaults identically.
+     *
+     * Every value binds before the assignments are rendered, so a `?`-placeholder engine needs none of
+     * the scratch-context reordering `ON CONFLICT` does - the source is read positionally, in order.
+     */
+    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
+    /** `<target>.<col> = <source>.<col>` for every conflict key, which is what makes a row "the same". */
+    private mergeOn;
+    /**
+     * A lock hint on the merge target. `MERGE` takes an update key lock but releases it before the
+     * insert, so two concurrent upserts of the same key race into a duplicate-key error; `HOLDLOCK`
+     * holds it across both. Empty on Oracle, which does not have the hint and does not need it.
+     */
+    protected readonly mergeTargetHint: string;
+    /** How the merge reports the row it wrote. Oracle has no such clause on a `MERGE` and omits it. */
+    protected mergeReturning(expression: string): string;
+    /** `MERGE` must be terminated on SQL Server; nothing else here cares. */
+    protected readonly statementTerminator: string;
+}

package/dist/dialect/mergeSqlDialect.js

@@ -0,0 +1,89 @@
+import { getMeta } from '../entity/index.js';
+import { assertNonNegativeInteger, getKeys } from '../util/index.js';
+import { AbstractSqlDialect } from './abstractSqlDialect.js';
+import { UPSERT_SOURCE_ALIAS } from './aliases.js';
+/**
+ * Shared SQL between SQL Server and Oracle: the two engines that spell paging and upsert the way the
+ * standard does, where the Postgres and MySQL families each predate it.
+ *
+ * A family base rather than a pair of knobs, the way {@link PgLikeSqlDialect} and
+ * {@link MysqlLikeSqlDialect} already are - `pager` and `upsert` are both plain overrides, so nothing
+ * in the core has to learn that a second spelling exists.
+ */
+export class MergeSqlDialect extends AbstractSqlDialect {
+    escapeIdChar = '"';
+    /**
+     * `OFFSET ... ROWS FETCH NEXT ... ROWS ONLY`, and an `ORDER BY` where the statement has none.
+     *
+     * SQL Server refuses to page an unordered statement. A constant `ORDER BY` costs one clause the
+     * optimizer discards and keeps `$limit` and `$skip` meaning the same thing here as everywhere
+     * else; the alternative, `TOP (n)` in the select list, needs a second hook and still leaves a
+     * `$skip` with no `$sort` unanswerable.
+     */
+    pager(ctx, opts, sorted = false) {
+        if (opts.$limit === undefined && opts.$skip === undefined) {
+            return;
+        }
+        if (!sorted) {
+            // A `SELECT DISTINCT` may only order by something it projects, so the constant cannot be used
+            // there; the first projected column is the one term always available.
+            ctx.append(` ORDER BY ${opts.$distinct ? '1' : '(SELECT NULL)'}`);
+        }
+        ctx.append(` OFFSET ${assertNonNegativeInteger(opts.$skip ?? 0, '$skip')} ROWS`);
+        if (opts.$limit !== undefined) {
+            ctx.append(` FETCH NEXT ${assertNonNegativeInteger(opts.$limit, '$limit')} ROWS ONLY`);
+        }
+    }
+    /**
+     * `MERGE`, which both engines take in place of the `ON CONFLICT`/`ON DUPLICATE KEY` the other
+     * families have. The rows go in as a `VALUES` row source rather than an `INSERT`, built by
+     * {@link AbstractSqlDialect.insertShape} so both shapes apply `onInsert` defaults identically.
+     *
+     * Every value binds before the assignments are rendered, so a `?`-placeholder engine needs none of
+     * the scratch-context reordering `ON CONFLICT` does - the source is read positionally, in order.
+     */
+    upsert(ctx, entity, conflictPaths, payload, extraReturning = '') {
+        const meta = getMeta(entity);
+        const table = this.escapedTableName(meta);
+        const source = this.escapeId(UPSERT_SOURCE_ALIAS, true);
+        // Before the row source, which is what fills the payload's `onInsert` fields: a column that
+        // exists only there - the generated key, `createdAt` - must not join the update set, or a row
+        // that already existed has both rewritten.
+        const update = this.getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, (col) => `${source}.${col}`);
+        const shape = this.insertShape(entity, payload);
+        const columns = shape.columns.join(', ');
+        ctx.append(`MERGE INTO ${table}${this.mergeTargetHint} USING (VALUES `);
+        this.appendValueRows(ctx, shape);
+        ctx.append(`) AS ${source} (${columns}) ON ${this.mergeOn(meta, conflictPaths, table, source)}`);
+        if (update) {
+            ctx.append(` WHEN MATCHED THEN UPDATE SET ${update}`);
+        }
+        ctx.append(` WHEN NOT MATCHED THEN INSERT (${columns}) VALUES (${shape.columns.map((col) => `${source}.${col}`).join(', ')})`);
+        const returning = [this.returningIdExpression(meta), extraReturning].filter(Boolean).join(', ');
+        if (returning) {
+            ctx.append(` ${this.mergeReturning(returning)}`);
+        }
+        ctx.append(this.statementTerminator);
+    }
+    /** `<target>.<col> = <source>.<col>` for every conflict key, which is what makes a row "the same". */
+    mergeOn(meta, conflictPaths, table, source) {
+        return getKeys(conflictPaths)
+            .map((key) => {
+            const column = this.escapeId(this.resolveColumnName(key, meta.fields[key]));
+            return `${table}.${column} = ${source}.${column}`;
+        })
+            .join(' AND ');
+    }
+    /**
+     * A lock hint on the merge target. `MERGE` takes an update key lock but releases it before the
+     * insert, so two concurrent upserts of the same key race into a duplicate-key error; `HOLDLOCK`
+     * holds it across both. Empty on Oracle, which does not have the hint and does not need it.
+     */
+    mergeTargetHint = '';
+    /** How the merge reports the row it wrote. Oracle has no such clause on a `MERGE` and omits it. */
+    mergeReturning(expression) {
+        return `RETURNING ${expression}`;
+    }
+    /** `MERGE` must be terminated on SQL Server; nothing else here cares. */
+    statementTerminator = '';
+}

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -37,7 +37,10 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,
-        defaultStringAsText: false,
+        stringSizing: 'varchar',
+        supportsUnsigned: true,
+        multipleCascadePaths: true,
+        serverSideCursors: false,
     };
     /**
      * `information_schema` keeps InnoDB's own row estimate, which is live enough to answer before

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -3,7 +3,7 @@ import { type ParentPartition } from '../util/relationQuery.util.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
- * CockroachDB (wire- and SQL-compatible for everything below, including `to_tsvector`/`to_tsquery`
+ * CockroachDB (wire- and SQL-compatible for everything below, including `TO_TSVECTOR`/`TO_TSQUERY`
  * and pgvector's `<=>`/`<->`/`<#>` distance operators, which CockroachDB implements natively).
  * `xmax`-based upsert `created` detection is Postgres-only (CockroachDB has no `xmax`/`ctid`) and
  * stays in {@link PostgresDialect}, along with the `vectorExtension`/`vectorIndexStyle` values that
@@ -64,8 +64,8 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     normalizeValue(value: unknown): unknown;
     placeholder(index: number): string;
     /**
-     * `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes free-form user input
-     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `to_tsquery`, which
+     * `TO_TSVECTOR(...) @@ WEBSEARCH_TO_TSQUERY(...)`. `WEBSEARCH_TO_TSQUERY` takes free-form user input
+     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`, which
      * rejects anything unparseable - including a plain two-word search.
      */
     protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;