uql-orm 0.53.0 → 0.55.0

package/dist/migrate/builder/migrationBuilder.js

@@ -10,10 +10,6 @@ import { derivedIndexName } from '../../util/sql.util.js';
 import { createSchemaGenerator } from '../schemaGenerator.js';
 import { splitSqlStatements } from './splitSqlStatements.js';
 import { TableBuilder } from './tableBuilder.js';
-/**
- * Builder for altering a table.
- * Delegates to parent builder for operation recording.
- */
 /**
  * One `createIndex` operation. Shared because the alter-table builder, the recorder and the
  * executing builder all record the same thing, and an entry left unnormalized reaches the generator

package/dist/migrate/ddl/index.d.ts

@@ -7,9 +7,9 @@ export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
 /**
- * The index DDL a dialect gets, most specific first. `instanceof` rather than `dialectName` so a
- * dialect subclassed by a user keeps its family's DDL, which is what overriding gave it while this
- * lived on the dialect itself. Anything else gets the portable form, which is SQLite's.
+ * The index DDL a dialect gets, most specific first. `instanceof` rather than the `dialectName`
+ * {@link tableDdlFor} reads, because each family's index DDL is typed to its dialect and the narrowing
+ * is what hands it one. Anything else gets the portable form, which is SQLite's.
  */
 export declare function indexDdlFor(dialect: AbstractSqlDialect): IndexDdl;
 /**

package/dist/migrate/ddl/index.js

@@ -14,9 +14,9 @@ export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
 /**
- * The index DDL a dialect gets, most specific first. `instanceof` rather than `dialectName` so a
- * dialect subclassed by a user keeps its family's DDL, which is what overriding gave it while this
- * lived on the dialect itself. Anything else gets the portable form, which is SQLite's.
+ * The index DDL a dialect gets, most specific first. `instanceof` rather than the `dialectName`
+ * {@link tableDdlFor} reads, because each family's index DDL is typed to its dialect and the narrowing
+ * is what hands it one. Anything else gets the portable form, which is SQLite's.
  */
 export function indexDdlFor(dialect) {
     if (dialect instanceof CockroachDialect) {

package/dist/migrate/migrator.d.ts

@@ -105,14 +105,10 @@ export declare class Migrator {
      */
     private forceStatements;
     /**
-     * Sync one entity, for a schema that grows while the process runs: a content type an admin just
-     * created is one table to add, where the whole set would read the catalogue to work that out.
-     *
-     * The new-table case costs one existence check and creates with `IF NOT EXISTS`, so instances racing
-     * the same admin save settle instead of colliding. An existing table still pays for introspection,
-     * since a column diff needs the columns.
+     * The DDL for one entity: {@link planSync} narrowed to the table it names. A new table costs one
+     * existence check and is created with `IF NOT EXISTS`, so instances racing the same admin save
+     * settle instead of colliding; an existing one still pays for introspection, as a diff needs columns.
      */
-    /** The DDL for one entity: {@link planSync} narrowed to the table it names. */
     private planEntity;
     /** An alter diff as statements, narrowed to what the caller allows. */
     private alterFromDiff;

package/dist/migrate/migrator.js

@@ -345,14 +345,10 @@ export class Migrator {
         ];
     }
     /**
-     * Sync one entity, for a schema that grows while the process runs: a content type an admin just
-     * created is one table to add, where the whole set would read the catalogue to work that out.
-     *
-     * The new-table case costs one existence check and creates with `IF NOT EXISTS`, so instances racing
-     * the same admin save settle instead of colliding. An existing table still pays for introspection,
-     * since a column diff needs the columns.
+     * The DDL for one entity: {@link planSync} narrowed to the table it names. A new table costs one
+     * existence check and is created with `IF NOT EXISTS`, so instances racing the same admin save
+     * settle instead of colliding; an existing one still pays for introspection, as a diff needs columns.
      */
-    /** The DDL for one entity: {@link planSync} narrowed to the table it names. */
     async planEntity(entity, options) {
         const meta = getMeta(entity);
         // Before anything reads `this.generator`, whose own failure names neither the entity nor the

package/dist/migrate/schemaGenerator.d.ts

@@ -25,9 +25,6 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     resolveColumnName(key: string, field: FieldOptions): string;
     /** Escape an identifier (table name, column name, etc.) */
     protected escapeId(identifier: string): string;
-    /**
-     * Primary key type for auto-increment integer IDs
-     */
     /**
      * How an auto-increment key of `type` is spelled: the type as any other column renders it, plus what
      * the engine appends to make it generated.
@@ -128,9 +125,6 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
         name: string;
         comment?: string;
     }, schema?: string): string[];
-    /**
-     * Compare an entity with a database table node and return the differences.
-     */
     /**
      * How this entity differs from the table the database reported, as the migrator's `SchemaDiff`.
      *
@@ -139,13 +133,6 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      * table node first, and types are compared as the *engine* would store them - see `normalizeType`.
      */
     diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
-    /**
-     * What the shared differ needs from a dialect: a type as this engine would actually store it.
-     *
-     * `boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite, so two canonical types that differ on
-     * paper can be one column in the database. Round-tripping through the engine's own spelling is what
-     * stops every such column reporting an alteration on every sync.
-     */
     /**
      * Indexes the entity declares that the table does not already have, in any shape.
      *

package/dist/migrate/schemaGenerator.js

@@ -50,9 +50,6 @@ export class SqlSchemaGenerator {
     escapeId(identifier) {
         return this.dialect.escapeId(identifier);
     }
-    /**
-     * Primary key type for auto-increment integer IDs
-     */
     /**
      * How an auto-increment key of `type` is spelled: the type as any other column renders it, plus what
      * the engine appends to make it generated.
@@ -361,9 +358,6 @@ export class SqlSchemaGenerator {
         const tableRef = this.dialect.escapeQualifiedId(tableName, schema);
         return [`COMMENT ON COLUMN ${tableRef}.${this.escapeId(column.name)} IS ${this.dialect.escape(column.comment)};`];
     }
-    /**
-     * Compare an entity with a database table node and return the differences.
-     */
     /**
      * How this entity differs from the table the database reported, as the migrator's `SchemaDiff`.
      *
@@ -447,13 +441,6 @@ export class SqlSchemaGenerator {
             foreignKeysToAlter: foreignKeysToAlter.length ? foreignKeysToAlter : undefined,
         };
     }
-    /**
-     * What the shared differ needs from a dialect: a type as this engine would actually store it.
-     *
-     * `boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite, so two canonical types that differ on
-     * paper can be one column in the database. Round-tripping through the engine's own spelling is what
-     * stops every such column reporting an alteration on every sync.
-     */
     /**
      * Indexes the entity declares that the table does not already have, in any shape.
      *

package/dist/migrate/storage/databaseStorage.d.ts

@@ -1,10 +1,10 @@
 import type { MigrationStorage, QuerierPool, SqlQuerier } from '../../type/index.js';
+/** Where executed migrations are recorded when the config does not name a table. */
+export declare const DEFAULT_MIGRATIONS_TABLE = "uql_migrations";
 /**
  * Stores migration state in a database table.
  * Uses the querier's dialect for escaping and placeholders.
  */
-/** Where executed migrations are recorded when the config does not name a table. */
-export declare const DEFAULT_MIGRATIONS_TABLE = "uql_migrations";
 export declare class DatabaseMigrationStorage implements MigrationStorage {
     private readonly pool;
     private readonly tableName;

package/dist/migrate/storage/databaseStorage.js

@@ -1,10 +1,10 @@
 import { withSqlQuerierForMigrations } from '../acquireQuerierForMigrations.js';
+/** Where executed migrations are recorded when the config does not name a table. */
+export const DEFAULT_MIGRATIONS_TABLE = 'uql_migrations';
 /**
  * Stores migration state in a database table.
  * Uses the querier's dialect for escaping and placeholders.
  */
-/** Where executed migrations are recorded when the config does not name a table. */
-export const DEFAULT_MIGRATIONS_TABLE = 'uql_migrations';
 export class DatabaseMigrationStorage {
     pool;
     tableName;

package/dist/mongo/index.d.ts

@@ -1,5 +1,4 @@
 export { MongoSchemaGenerator } from '../migrate/generator/mongoSchemaGenerator.js';
 export * from './mongoDialect.js';
-export * from './mongodbNativeDialect.js';
 export * from './mongodbQuerier.js';
 export * from './mongodbQuerierPool.js';

package/dist/mongo/index.js

@@ -1,5 +1,4 @@
 export { MongoSchemaGenerator } from '../migrate/generator/mongoSchemaGenerator.js';
 export * from './mongoDialect.js';
-export * from './mongodbNativeDialect.js';
 export * from './mongodbQuerier.js';
 export * from './mongodbQuerierPool.js';

package/dist/mongo/mongoDialect.d.ts

@@ -20,7 +20,6 @@ export declare class MongoDialect extends AbstractDialect {
     private static readonly ID_KEY;
     /** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
     private static readonly MAX_NUM_CANDIDATES;
-    private static readonly AGGREGATE_OP_MAP;
     /**
      * MongoDB stores the primary key as `_id`; everything else resolves as usual. Projections, sorts,
      * `$group` refs and `$where` keys all map through here, so no read path can address a property name

package/dist/mongo/mongoDialect.js

@@ -39,14 +39,6 @@ export class MongoDialect extends AbstractDialect {
     static ID_KEY = '_id';
     /** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
     static MAX_NUM_CANDIDATES = 10_000;
-    // Direct field aggregates → MongoDB accumulator. `$count` is handled separately (COUNT(*) vs
-    // COUNT(field) differ), so it is not listed here.
-    static AGGREGATE_OP_MAP = new Map([
-        ['$sum', '$sum'],
-        ['$avg', '$avg'],
-        ['$min', '$min'],
-        ['$max', '$max'],
-    ]);
     /**
      * MongoDB stores the primary key as `_id`; everything else resolves as usual. Projections, sorts,
      * `$group` refs and `$where` keys all map through here, so no read path can address a property name
@@ -511,7 +503,7 @@ export class MongoDialect extends AbstractDialect {
      */
     aliasSort(sort) {
         const normalized = {};
-        for (const [alias, dir] of Object.entries(sort ?? {})) {
+        for (const [alias, dir] of Object.entries(sort)) {
             normalized[alias] = sortDirection(dir);
         }
         return normalized;
@@ -999,11 +991,8 @@ export class MongoDialect extends AbstractDialect {
                     entry.fieldRef === '*' ? { $sum: 1 } : { $sum: { $cond: [{ $ne: [ref, null] }, 1, 0] } };
             }
             else {
-                const mongoOp = MongoDialect.AGGREGATE_OP_MAP.get(entry.op);
-                if (!mongoOp) {
-                    throw TypeError(`unsupported aggregate operator: ${entry.op}`);
-                }
-                groupAccumulators[entry.alias] = { [mongoOp]: ref };
+                // `$sum`, `$avg`, `$min` and `$max` are MongoDB accumulators of the same name.
+                groupAccumulators[entry.alias] = { [entry.op]: ref };
             }
         }
         return { groupId, groupAccumulators, distinctReducers };

package/dist/mongo/mongodbQuerier.d.ts

@@ -1,6 +1,6 @@
 import type { Document, MongoClient } from 'mongodb';
 import { AbstractQuerier } from '../querier/index.js';
-import type { EntityData, ExtraOptions, IdValue, PrimaryKey, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, PrimaryKey, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import { type ParentPartition } from '../util/index.js';
 import type { MongoDialect } from './mongoDialect.js';
 export declare class MongodbQuerier extends AbstractQuerier {
@@ -56,7 +56,7 @@ export declare class MongodbQuerier extends AbstractQuerier {
      * the floor, and skipped the relation-sort rejection {@link MongoDialect.sort} raises.
      */
     private settleIds;
-    internalInsertMany<E extends Document>(entity: Type<E>, payloads: EntityData<E>[]): Promise<IdValue<E>[]>;
+    internalInsertMany<E extends Document>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
     internalUpdateMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     /**
      * `_id` is immutable, so a key the payload names can only be written on the insert branch of an
@@ -65,18 +65,16 @@ export declare class MongodbQuerier extends AbstractQuerier {
     private upsertUpdate;
     private buildConflictFilter;
     protected internalUpsertOne<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<{
-        firstId: PrimaryKey | undefined;
+        ids: (PrimaryKey | undefined)[];
         changes: number;
         created: boolean;
     }>;
     protected internalUpsertMany<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<{
         changes: number;
         ids?: undefined;
-        firstId?: undefined;
     } | {
         changes: number;
         ids: (PrimaryKey | undefined)[];
-        firstId: PrimaryKey | undefined;
     }>;
     protected internalDeleteMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     get hasOpenTransaction(): boolean;

package/dist/mongo/mongodbQuerier.js

@@ -1,6 +1,6 @@
 import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
-import { getMeta, idOf, soleIdOf } from '../entity/index.js';
+import { fieldOf, getMeta, idOf, namesKey, soleIdOf } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
 import { clone, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, isPagedQuery, populatesRelations, queryChildrenOf, throwNoPendingTransaction, throwPendingTransaction, withoutSoftDeleteFilter, } from '../util/index.js';
 /**
@@ -259,22 +259,17 @@ export class MongodbQuerier extends AbstractQuerier {
         // are named the same way every other driver names them.
         return (this.dialect.normalizeIds(meta, founds) || []).map((found) => idOf(meta, found));
     }
-    async internalInsertMany(entity, payloads) {
+    async internalInsertMany(entity, rows) {
         return this.timed('internalInsertMany', undefined, async () => {
-            if (!payloads?.length) {
-                return [];
-            }
-            payloads = clone(payloads);
             const meta = getMeta(entity);
-            const persistables = this.dialect.getPersistables(meta, payloads, 'onInsert');
+            const persistables = this.dialect.getPersistables(meta, rows, 'onInsert');
             const { insertedIds } = await this.execute((session) => this.collection(entity).insertMany(persistables, { session }));
             const ids = Object.values(insertedIds).map((id) => this.dialect.fromWireId(id));
             const idKey = soleIdOf(meta, 'insert');
-            for (const [index, it] of payloads.entries()) {
-                it[idKey] = ids[index];
+            for (let index = 0; index < rows.length; index++) {
+                rows[index][idKey] = ids[index];
             }
-            await this.insertRelations(entity, payloads);
-            return ids;
+            await this.insertRelations(entity, rows);
         });
     }
     async internalUpdateMany(entity, qm, payload, opts) {
@@ -332,10 +327,11 @@ export class MongodbQuerier extends AbstractQuerier {
                 includeResultMetadata: true,
                 session,
             }));
-            const firstId = this.dialect.fromWireId(res?.value?._id);
+            // Read off the document as written, which carries its `_id` on either branch.
+            const id = this.dialect.fromWireId(res?.value?._id);
             // `updatedExisting` is false when a new document was inserted (upserted).
             const created = res?.lastErrorObject?.['updatedExisting'] === false;
-            return { firstId, changes: firstId ? 1 : 0, created };
+            return { ids: [id], changes: id === undefined ? 0 : 1, created };
         });
     }
     async internalUpsertMany(entity, conflictPaths, payload) {
@@ -343,8 +339,10 @@ export class MongodbQuerier extends AbstractQuerier {
             if (!payload?.length) {
                 return { changes: 0 };
             }
-            payload = clone(payload);
             const meta = getMeta(entity);
+            // Asked before `getPersistable` fills an `onInsert` key into rows it may only update.
+            const unnamed = payload.map((row) => !namesKey(meta, row));
+            payload = clone(payload);
             const operations = payload.map((item) => {
                 const persistable = this.dialect.getPersistable(meta, item, 'onInsert');
                 const filter = this.buildConflictFilter(entity, conflictPaths, item);
@@ -359,23 +357,24 @@ export class MongodbQuerier extends AbstractQuerier {
             });
             const res = await this.execute((session) => this.collection(entity).bulkWrite(operations, { session }));
             const changes = (res.upsertedCount ?? 0) + (res.modifiedCount ?? 0);
-            // `upsertedIds` only covers newly-inserted documents, keyed by operation index: a matched and
-            // updated document's `_id` is not in the response. Read by that index rather than flattened,
-            // so each id lands on the row it belongs to and the gaps stay gaps.
-            const ids = payload.map((_, index) => {
+            // `upsertedIds` names only the documents inserted, keyed by operation index, so each lands on
+            // its own row; an updated document's `_id` is read back by the conflict fields instead.
+            const reported = payload.map((_, index) => {
                 const id = res.upsertedIds[index];
                 return id === undefined ? undefined : this.dialect.fromWireId(id);
             });
-            return { changes, ids, firstId: ids.find((id) => id !== undefined) };
+            const unplaced = reported.some((id, index) => id === undefined && unnamed[index]);
+            const found = unplaced ? await this.idsByConflict(entity, conflictPaths, payload) : [];
+            return { changes, ids: reported.map((id, index) => id ?? found[index]) };
         });
     }
     async internalDeleteMany(entity, qm, opts = {}) {
         return this.timed('internalDeleteMany', undefined, async () => {
             const meta = getMeta(entity);
             // Soft-delete (stamp) unless `hardDelete` is requested or the entity has no soft-delete field.
-            const field = !opts.hardDelete && meta.softDelete ? meta.fields[meta.softDelete] : undefined;
+            const softDelete = opts.hardDelete ? undefined : meta.softDelete;
             // Hard delete targets matching rows regardless of soft-delete state (keeps other filters).
-            const findOpts = field ? opts : { ...opts, filters: withoutSoftDeleteFilter(opts.filters) };
+            const findOpts = softDelete ? opts : { ...opts, filters: withoutSoftDeleteFilter(opts.filters) };
             // Delete has always resolved its ids first (it stamps or removes them by `_id`), so a relation
             // condition needs nothing extra here - and passing the whole query is what makes its page apply.
             const ids = await this.settleIds(entity, qm, findOpts);
@@ -383,10 +382,11 @@ export class MongodbQuerier extends AbstractQuerier {
                 return 0;
             }
             let changes;
-            if (field) {
+            if (softDelete) {
+                const field = fieldOf(meta, softDelete);
                 // Stamp the mapped column: reads filter on it, so a `@Field({ name })` mismatch here would
                 // report a successful delete and leave the row visible.
-                const softDeleteColumn = this.dialect.resolveColumnName(meta.softDelete, field);
+                const softDeleteColumn = this.dialect.resolveColumnName(softDelete, field);
                 const updateResult = await this.execute((session) => this.collection(entity).updateMany({ _id: { $in: this.dialect.toWireId(ids) } }, { $set: { [softDeleteColumn]: getSoftDeleteValue(field) } }, {
                     session,
                 }));

package/dist/mongo/mongodbQuerierPool.d.ts

@@ -1,9 +1,9 @@
 import { type MongoClientOptions } from 'mongodb';
 import { AbstractQuerierPool } from '../querier/index.js';
 import type { ExtraOptions } from '../type/index.js';
-import { MongodbNativeDialect } from './mongodbNativeDialect.js';
+import { MongoDialect } from './mongoDialect.js';
 import { MongodbQuerier } from './mongodbQuerier.js';
-export declare class MongodbQuerierPool extends AbstractQuerierPool<MongodbQuerier, MongodbNativeDialect> {
+export declare class MongodbQuerierPool extends AbstractQuerierPool<MongodbQuerier, MongoDialect> {
     private readonly client;
     constructor(uri: string, opts?: MongoClientOptions, extra?: ExtraOptions);
     getQuerier(): Promise<MongodbQuerier>;

package/dist/mongo/mongodbQuerierPool.js

@@ -1,12 +1,12 @@
 import { MongoClient } from 'mongodb';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractQuerierPool } from '../querier/index.js';
-import { MongodbNativeDialect } from './mongodbNativeDialect.js';
+import { MongoDialect } from './mongoDialect.js';
 import { MongodbQuerier } from './mongodbQuerier.js';
 export class MongodbQuerierPool extends AbstractQuerierPool {
     client;
     constructor(uri, opts, extra) {
-        super(new MongodbNativeDialect(dialectOptionsFrom(extra)), extra);
+        super(new MongoDialect(dialectOptionsFrom(extra)), extra);
         this.client = new MongoClient(uri, opts);
     }
     async getQuerier() {

package/dist/mssql/mssqlDialect.d.ts

@@ -18,18 +18,18 @@ export declare class MsSqlDialect extends MergeSqlDialect {
     readonly commitTransactionCommand = "COMMIT TRANSACTION";
     readonly rollbackTransactionCommand = "ROLLBACK TRANSACTION";
     /**
-     * The level rides the `BEGIN` rather than preceding it as its own statement: a `SET TRANSACTION
-     * ISOLATION LEVEL` sent on its own would go to whichever pooled connection served it, not the one
-     * the transaction opens on, and would then stick to that connection for unrelated later queries.
-     * `MsSqlQuerier` reads the level back off this command and hands it to the driver.
+     * T-SQL has no inline form, so the level is set before the `BEGIN`. What a driver that sends these
+     * as statements would run; `MsSqlQuerier` opens its transactions through the driver instead.
      */
-    readonly isolationLevelStrategy = "inline";
+    readonly isolationLevelStrategy = "set-before";
     readonly dropIndexSyntax = "on-table";
     readonly booleanLiteral = "integer";
     /** [The hard server limit](https://github.com/yiisoft/yii2/issues/10371), not a driver preference. */
     readonly maxBindValues = 2100;
     /** `OUTPUT` has no trailing form: it sits between the column list and `VALUES`. */
     readonly returningPosition = "after-target";
+    /** Microsoft documents no row order for a `MERGE ... OUTPUT`. */
+    readonly upsertReturningOrdered = false;
     readonly insertIdSource: InsertIdSource;
     /** Holds the update key lock across the insert; without it two concurrent upserts of one key race. */
     protected readonly mergeTargetHint = " WITH (HOLDLOCK)";

package/dist/mssql/mssqlDialect.js

@@ -52,18 +52,18 @@ export class MsSqlDialect extends MergeSqlDialect {
     commitTransactionCommand = 'COMMIT TRANSACTION';
     rollbackTransactionCommand = 'ROLLBACK TRANSACTION';
     /**
-     * The level rides the `BEGIN` rather than preceding it as its own statement: a `SET TRANSACTION
-     * ISOLATION LEVEL` sent on its own would go to whichever pooled connection served it, not the one
-     * the transaction opens on, and would then stick to that connection for unrelated later queries.
-     * `MsSqlQuerier` reads the level back off this command and hands it to the driver.
+     * T-SQL has no inline form, so the level is set before the `BEGIN`. What a driver that sends these
+     * as statements would run; `MsSqlQuerier` opens its transactions through the driver instead.
      */
-    isolationLevelStrategy = 'inline';
+    isolationLevelStrategy = 'set-before';
     dropIndexSyntax = 'on-table';
     booleanLiteral = 'integer';
     /** [The hard server limit](https://github.com/yiisoft/yii2/issues/10371), not a driver preference. */
     maxBindValues = 2100;
     /** `OUTPUT` has no trailing form: it sits between the column list and `VALUES`. */
     returningPosition = 'after-target';
+    /** Microsoft documents no row order for a `MERGE ... OUTPUT`. */
+    upsertReturningOrdered = false;
     insertIdSource = 'returning';
     /** Holds the update key lock across the insert; without it two concurrent upserts of one key race. */
     mergeTargetHint = ' WITH (HOLDLOCK)';
@@ -268,11 +268,14 @@ export class MsSqlDialect extends MergeSqlDialect {
         return typeof value === 'boolean' ? `CAST(${placeholder} AS BIT)` : placeholder;
     }
     /**
-     * An object or array bound as JSON, which is the half both binders spell the same way, or
-     * `undefined` for a scalar - where they diverge.
+     * An object or array bound as JSON, or a `raw()` rendered in place, which is the half both binders
+     * spell the same way; `undefined` for a scalar - where they diverge.
      */
     #jsonCompound(ctx, value) {
-        if (value === null || typeof value !== 'object' || value instanceof QueryRaw) {
+        if (value instanceof QueryRaw) {
+            return this.rawFragment(ctx, value);
+        }
+        if (value === null || typeof value !== 'object') {
             return undefined;
         }
         ctx.pushValue(JSON.stringify(value));

package/dist/mssql/mssqlQuerier.d.ts

@@ -1,7 +1,6 @@
 import type { ConnectionPool } from 'mssql';
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
-import type { ExtraOptions, QueryUpdateResult } from '../type/index.js';
-import type { MsSqlDialect } from './mssqlDialect.js';
+import type { QueryUpdateResult, TransactionOptions } from '../type/index.js';
 /**
  * A connection is a `ConnectionPool` handle here rather than a checked-out socket: `mssql` owns its
  * own pool and hands out `Request`s, so what UQL holds is the pool plus, once a transaction opens,
@@ -9,15 +8,23 @@ import type { MsSqlDialect } from './mssqlDialect.js';
  */
 export declare class MsSqlQuerier extends AbstractPoolQuerier<ConnectionPool> {
     #private;
-    constructor(connect: () => Promise<ConnectionPool>, dialect: MsSqlDialect, extra?: ExtraOptions);
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<QueryUpdateResult>;
     /**
-     * `tedious` streams by event, not by async iterator, so rows are handed over as they arrive rather
-     * than collected first - buffering the whole result set would make this `all()` with extra steps.
-     * The `query` promise is awaited at the end so its rejection surfaces rather than going unhandled.
+     * The driver's own stream over the request, which pauses the request while the loop is behind, so
+     * rows arrive only as fast as they are read. A failure the driver reports through the promise alone
+     * would leave the loop waiting for rows, so it ends the stream instead.
      */
     internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;
+    /**
+     * `mssql` owns its pool and hands out a `Request` per call, so a `BEGIN TRANSACTION` sent as text
+     * would open one on a connection the next call may not be given. Its `Transaction` object is the
+     * only thing that pins them together, so the transaction is that object rather than statements, and
+     * the level goes to its `begin`: sent as a statement it would land on whichever connection served it.
+     */
+    protected internalBegin(opts?: TransactionOptions): Promise<void>;
+    protected internalCommit(): Promise<void>;
+    protected internalRollback(): Promise<void>;
     /** The pool owns the socket; releasing a querier only drops this one's claim on it. */
     protected releaseConn(_conn: ConnectionPool, _discard: boolean): Promise<void>;
 }