uql-orm 0.50.0 → 0.52.0

package/dist/schema/canonicalType.js

@@ -44,6 +44,9 @@ const SQL_TO_CANONICAL = {
     char: { category: 'string' },
     character: { category: 'string' },
     varchar: { category: 'string' },
+    varchar2: { category: 'string' },
+    nvarchar: { category: 'string' },
+    nchar: { category: 'string' },
     'character varying': { category: 'string' },
     text: { category: 'string', size: 'small' },
     tinytext: { category: 'string', size: 'tiny' },
@@ -64,11 +67,15 @@ const SQL_TO_CANONICAL = {
     'timestamp with time zone': { category: 'timestamp', withTimezone: true },
     timestamptz: { category: 'timestamp', withTimezone: true },
     datetime: { category: 'timestamp' },
+    datetime2: { category: 'timestamp' },
+    smalldatetime: { category: 'timestamp' },
+    datetimeoffset: { category: 'timestamp', withTimezone: true },
     // === JSON ===
     json: { category: 'json' },
     jsonb: { category: 'json' },
     // === UUID ===
     uuid: { category: 'uuid' },
+    uniqueidentifier: { category: 'uuid' },
     // === Binary ===
     blob: { category: 'blob' },
     bytea: { category: 'blob' },
@@ -77,15 +84,16 @@ const SQL_TO_CANONICAL = {
     tinyblob: { category: 'blob', size: 'tiny' },
     mediumblob: { category: 'blob', size: 'medium' },
     longblob: { category: 'blob', size: 'big' },
+    image: { category: 'blob', size: 'big' },
     // === Vector (for AI/embeddings) ===
     vector: { category: 'vector' },
     halfvec: { category: 'halfvec' },
     sparsevec: { category: 'sparsevec' },
 };
 /**
- * pgvector is the only engine with three vector column types, so every other dialect maps all three
- * canonical categories onto the single type it does have (see `hasNarrowVectorTypes` on the dialect, the
- * dialect-side half of the same fact).
+ * pgvector is the only engine with three vector column types, so every other engine maps all three
+ * canonical categories onto the single type it does have (see `hasNarrowVectorTypes` on the dialect,
+ * the dialect-side half of the same fact).
  */
 function withVectorType(scalars, vector) {
     return { ...scalars, vector, halfvec: vector, sparsevec: vector };
@@ -103,11 +111,9 @@ const PG_SCALAR_MAP = {
     uuid: 'UUID',
     blob: 'BYTEA',
 };
-const PG_TYPE_MAP = {
-    ...PG_SCALAR_MAP,
-    vector: 'VECTOR',
-    halfvec: 'HALFVEC',
-    sparsevec: 'SPARSEVEC',
+const PG_SIZES = {
+    integer: { tiny: 'SMALLINT', small: 'SMALLINT', medium: 'INTEGER', big: 'BIGINT' },
+    float: { tiny: 'REAL', small: 'REAL', medium: 'DOUBLE PRECISION', big: 'DOUBLE PRECISION' },
 };
 const MYSQL_SCALAR_MAP = {
     integer: 'INT',
@@ -122,6 +128,13 @@ const MYSQL_SCALAR_MAP = {
     uuid: 'CHAR(36)',
     blob: 'BLOB',
 };
+/** MariaDB is a MySQL fork and spells every one of these the same way, so both take the one map. */
+const MYSQL_SIZES = {
+    integer: { tiny: 'TINYINT', small: 'SMALLINT', medium: 'MEDIUMINT', big: 'BIGINT' },
+    float: { tiny: 'FLOAT', small: 'FLOAT', medium: 'DOUBLE', big: 'DOUBLE' },
+    string: { tiny: 'TINYTEXT', small: 'TEXT', medium: 'MEDIUMTEXT', big: 'LONGTEXT' },
+    blob: { tiny: 'TINYBLOB', small: 'BLOB', medium: 'MEDIUMBLOB', big: 'LONGBLOB' },
+};
 const SQLITE_SCALAR_MAP = {
     integer: 'INTEGER',
     float: 'REAL',
@@ -135,6 +148,35 @@ const SQLITE_SCALAR_MAP = {
     uuid: 'TEXT',
     blob: 'BLOB',
 };
+/**
+ * Every string column is `NVARCHAR`: `VARCHAR` is a codepage type on SQL Server and silently destroys
+ * anything outside it on write. UQL never exposes the choice, so there is nothing to weigh per column.
+ */
+const MSSQL_SCALAR_MAP = {
+    integer: 'INT',
+    float: 'REAL',
+    decimal: 'DECIMAL',
+    string: 'NVARCHAR',
+    boolean: 'BIT',
+    date: 'DATE',
+    time: 'TIME',
+    timestamp: 'DATETIME2',
+    json: 'NVARCHAR(MAX)',
+    uuid: 'UNIQUEIDENTIFIER',
+    blob: 'VARBINARY(MAX)',
+};
+/** `FLOAT` is eight bytes here and `REAL` four - the opposite of the MySQL family's spelling. */
+const MSSQL_SIZES = {
+    integer: { tiny: 'TINYINT', small: 'SMALLINT', medium: 'INT', big: 'BIGINT' },
+    float: { tiny: 'REAL', small: 'REAL', medium: 'FLOAT', big: 'FLOAT' },
+    string: { tiny: 'NVARCHAR(255)', small: 'NVARCHAR(MAX)', medium: 'NVARCHAR(MAX)', big: 'NVARCHAR(MAX)' },
+    blob: {
+        tiny: 'VARBINARY(255)',
+        small: 'VARBINARY(MAX)',
+        medium: 'VARBINARY(MAX)',
+        big: 'VARBINARY(MAX)',
+    },
+};
 /** MongoDB uses BSON types, not SQL types. These are placeholders for compatibility. */
 const MONGO_SCALAR_MAP = {
     integer: 'int',
@@ -149,73 +191,31 @@ const MONGO_SCALAR_MAP = {
     uuid: 'binData',
     blob: 'binData',
 };
-/** Every engine's scalars, and the one spelling it gives all three vector widths. */
-const CANONICAL_TO_SQL = {
-    postgres: PG_TYPE_MAP,
+/** Every engine's spelling of the canonical types. A new engine is one entry here and nothing else. */
+const ENGINE_TYPES = {
+    postgres: {
+        scalars: { ...PG_SCALAR_MAP, vector: 'VECTOR', halfvec: 'HALFVEC', sparsevec: 'SPARSEVEC' },
+        sizes: PG_SIZES,
+    },
     // CockroachDB's VECTOR is native, no extension needed.
-    cockroachdb: withVectorType(PG_SCALAR_MAP, 'VECTOR'),
+    cockroachdb: { scalars: withVectorType(PG_SCALAR_MAP, 'VECTOR'), sizes: PG_SIZES },
     // MySQL does have a `VECTOR` type (26.7), but no distance function outside HeatWave and no vector
     // index, so JSON keeps the column queryable with the JSON operators and needs no conversion.
-    mysql: withVectorType(MYSQL_SCALAR_MAP, 'JSON'),
-    mariadb: withVectorType(MYSQL_SCALAR_MAP, 'VECTOR'),
-    sqlite: withVectorType(SQLITE_SCALAR_MAP, 'TEXT'),
-    mongodb: withVectorType(MONGO_SCALAR_MAP, 'array'),
-};
-/**
- * Size variant modifiers for SQL types.
- */
-const PG_SIZE_MODIFIERS = {
-    integer: {
-        tiny: 'SMALLINT',
-        small: 'SMALLINT',
-        medium: 'INTEGER',
-        big: 'BIGINT',
-    },
-    float: {
-        tiny: 'REAL',
-        small: 'REAL',
-        medium: 'DOUBLE PRECISION',
-        big: 'DOUBLE PRECISION',
-    },
-};
-/**
- * MariaDB is a MySQL fork and spells every one of these the same way, so both take the one map.
- * Listed per-dialect, MariaDB's had only `integer`: a `double` column was created `FLOAT` there, four
- * bytes where the entity asked for eight, and a `big` string or blob lost its `LONG` prefix.
- */
-const MYSQL_SIZE_MODIFIERS = {
-    integer: {
-        tiny: 'TINYINT',
-        small: 'SMALLINT',
-        medium: 'MEDIUMINT',
-        big: 'BIGINT',
+    mysql: {
+        scalars: withVectorType(MYSQL_SCALAR_MAP, 'JSON'),
+        sizes: MYSQL_SIZES,
+        decimal: { precision: 10, scale: 2 },
     },
-    float: {
-        tiny: 'FLOAT',
-        small: 'FLOAT',
-        medium: 'DOUBLE',
-        big: 'DOUBLE',
+    mariadb: {
+        scalars: withVectorType(MYSQL_SCALAR_MAP, 'VECTOR'),
+        sizes: MYSQL_SIZES,
+        decimal: { precision: 10, scale: 2 },
     },
-    string: {
-        tiny: 'TINYTEXT',
-        small: 'TEXT',
-        medium: 'MEDIUMTEXT',
-        big: 'LONGTEXT',
-    },
-    blob: {
-        tiny: 'TINYBLOB',
-        small: 'BLOB',
-        medium: 'MEDIUMBLOB',
-        big: 'LONGBLOB',
-    },
-};
-const SIZE_MODIFIERS = {
-    postgres: PG_SIZE_MODIFIERS,
-    cockroachdb: PG_SIZE_MODIFIERS,
-    mysql: MYSQL_SIZE_MODIFIERS,
-    sqlite: {}, // SQLite uses affinity, no size modifiers
-    mariadb: MYSQL_SIZE_MODIFIERS,
-    mongodb: {},
+    // SQLite uses affinity, so no size variants.
+    sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'TEXT') },
+    // A 2025 server has a native `VECTOR`; below that the column is JSON text, which stays queryable.
+    mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'NVARCHAR(MAX)'), sizes: MSSQL_SIZES },
+    mongodb: { scalars: withVectorType(MONGO_SCALAR_MAP, 'array') },
 };
 /**
  * Maps canonical types to TypeScript types for entity generation.
@@ -317,61 +317,44 @@ export function canonicalColumnType(sqlType, reported = {}) {
 export function canonicalToSql(type, dialect) {
     if (type.raw)
         return type.raw;
-    const dialectName = dialect.dialectName;
-    let sqlType = getBaseSqlType(type, dialectName);
-    if (type.category === 'string') {
-        sqlType = formatStringSqlType(type, dialect);
+    const engine = ENGINE_TYPES[dialect.dialectName];
+    const { features } = dialect;
+    // A `size` the engine spells out wins outright; anything else falls through to the rules below.
+    // `TEXT` canonicalizes to `size: 'small'`, so a string counts as unsized only where the engine
+    // declares no variant for it, which is how Postgres reaches `TEXT` rather than its base `VARCHAR`.
+    const sized = engine.sizes?.[type.category]?.[type.size];
+    let sqlType = sized ?? engine.scalars[type.category];
+    if (type.category === 'string' && !sized) {
+        sqlType = formatStringSqlType(type, engine.scalars.string, features.stringSizing);
     }
     else if (type.category === 'decimal') {
-        sqlType = formatDecimalSqlType(type, dialectName, sqlType);
+        sqlType = formatDecimalSqlType(type, engine.decimal, sqlType);
     }
-    else if (isVectorCategory(type.category) && type.length && dialect.features.vectorSupportsLength) {
+    else if (isVectorCategory(type.category) && type.length && features.vectorSupportsLength) {
         sqlType = `${sqlType}(${type.length})`;
     }
-    if (type.category === 'timestamp' && type.withTimezone && dialect.features.supportsTimestamptz) {
+    if (type.category === 'timestamp' && type.withTimezone && features.supportsTimestamptz) {
         sqlType = 'TIMESTAMPTZ';
     }
-    if (type.unsigned && (dialectName === 'mysql' || dialectName === 'mariadb')) {
-        sqlType = `${sqlType} UNSIGNED`;
-    }
-    return sqlType;
+    return type.unsigned && features.supportsUnsigned ? `${sqlType} UNSIGNED` : sqlType;
 }
-function getBaseSqlType(type, dialect) {
-    let sqlType = CANONICAL_TO_SQL[dialect][type.category];
-    if (type.size) {
-        const sizeMap = SIZE_MODIFIERS[dialect][type.category];
-        if (sizeMap?.[type.size]) {
-            sqlType = sizeMap[type.size];
-        }
+/** See {@link EngineFeatures.stringSizing} for what each mode means. */
+function formatStringSqlType(type, base, sizing) {
+    if (sizing === 'text') {
+        return base;
     }
-    return sqlType;
-}
-function formatStringSqlType(type, dialect) {
-    const { dialectName, features } = dialect;
-    if (dialectName === 'sqlite')
-        return 'TEXT';
-    if (features.defaultStringAsText)
-        return type.length ? `VARCHAR(${type.length})` : 'TEXT';
-    if (dialectName === 'mysql' || dialectName === 'mariadb') {
-        if (type.size === 'tiny')
-            return 'TINYTEXT';
-        if (type.size === 'small')
-            return 'TEXT';
-        if (type.size === 'medium')
-            return 'MEDIUMTEXT';
-        if (type.size === 'big')
-            return 'LONGTEXT';
-        return type.length ? `VARCHAR(${type.length})` : 'VARCHAR(255)';
+    if (type.length) {
+        return `${base}(${type.length})`;
     }
-    return type.length ? `VARCHAR(${type.length})` : 'VARCHAR(255)';
+    return sizing === 'bounded-text' ? 'TEXT' : `${base}(255)`;
 }
-function formatDecimalSqlType(type, dialect, baseType) {
-    const p = type.precision ?? (dialect === 'mysql' || dialect === 'mariadb' ? 10 : undefined);
-    const s = type.scale ?? (dialect === 'mysql' || dialect === 'mariadb' ? 2 : undefined);
-    if (p !== undefined) {
-        return s !== undefined ? `${baseType}(${p}, ${s})` : `${baseType}(${p})`;
+function formatDecimalSqlType(type, fallback, baseType) {
+    const p = type.precision ?? fallback?.precision;
+    const s = type.scale ?? fallback?.scale;
+    if (p === undefined) {
+        return baseType;
     }
-    return baseType;
+    return s === undefined ? `${baseType}(${p})` : `${baseType}(${p}, ${s})`;
 }
 /**
  * Convert a canonical type to a TypeScript type string.

package/dist/sqlite/sqliteDialect.d.ts

@@ -46,24 +46,24 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      * element includes these keys" - `$elemMatch` always expands to per-field conditions.
      */
     protected readonly jsonContainmentIsPartial = false;
-    /** `json_each` exposes a JSON boolean as `0`/`1` and a number as a number - already comparable. */
+    /** `JSON_EACH` exposes a JSON boolean as `0`/`1` and a number as a number - already comparable. */
     protected readonly jsonScalarElemKeepsType = true;
     /**
      * Each element is read back as JSON text through `->` at its own `fullkey`, so it compares
-     * correctly whatever its type. `json_each`'s `value` column would not: it unquotes strings (`a`
+     * correctly whatever its type. `JSON_EACH`'s `value` column would not: it unquotes strings (`a`
      * vs `"a"`), flattens booleans to 0/1, and stringifies objects.
      */
     protected jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
     protected jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
-    /** `json_each` yields both scalar and object elements, so one form covers each case. */
+    /** `JSON_EACH` yields both scalar and object elements, so one form covers each case. */
     protected jsonElemFrom(jsonField: string, _fields: readonly string[], alias: string): string;
     protected jsonElemRef(alias: string, field?: string, asJson?: boolean): string;
     protected getJsonPathScalarExpr(escapedColumn: string, jsonPathStr: string): string;
     protected numericCast(expr: string): string;
     protected jsonCast(operand: string): string;
     /**
-     * `json_replace` leaves an absent key (and a NULL column) untouched. Elements are read back
-     * through `->` at their own `fullkey` so each keeps its JSON type - `json_each`'s `value` would
+     * `JSON_REPLACE` leaves an absent key (and a NULL column) untouched. Elements are read back
+     * through `->` at their own `fullkey` so each keeps its JSON type - `JSON_EACH`'s `value` would
      * flatten booleans to 0/1 and stringify objects.
      */
     protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
@@ -71,8 +71,8 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     /**
      * `[#]` appends, creating the array when the key is absent.
      *
-     * @remarks `json_set` rather than `json_insert`: the two are equivalent here because `[#]` always
-     * resolves past the end of the array, and Turso's engine implements `json_insert` as create-only,
+     * @remarks `JSON_SET` rather than `JSON_INSERT`: the two are equivalent here because `[#]` always
+     * resolves past the end of the array, and Turso's engine implements `JSON_INSERT` as create-only,
      * so it silently drops the element when the array already exists.
      */
     protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;

package/dist/sqlite/sqliteDialect.js

@@ -19,7 +19,10 @@ export class SqliteDialect extends AbstractSqlDialect {
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,
-        defaultStringAsText: true,
+        stringSizing: 'text',
+        supportsUnsigned: false,
+        multipleCascadePaths: true,
+        serverSideCursors: false,
     };
     dialectName = 'sqlite';
     escapeIdChar = '`';
@@ -94,11 +97,11 @@ export class SqliteDialect extends AbstractSqlDialect {
      * element includes these keys" - `$elemMatch` always expands to per-field conditions.
      */
     jsonContainmentIsPartial = false;
-    /** `json_each` exposes a JSON boolean as `0`/`1` and a number as a number - already comparable. */
+    /** `JSON_EACH` exposes a JSON boolean as `0`/`1` and a number as a number - already comparable. */
     jsonScalarElemKeepsType = true;
     /**
      * Each element is read back as JSON text through `->` at its own `fullkey`, so it compares
-     * correctly whatever its type. `json_each`'s `value` column would not: it unquotes strings (`a`
+     * correctly whatever its type. `JSON_EACH`'s `value` column would not: it unquotes strings (`a`
      * vs `"a"`), flattens booleans to 0/1, and stringifies objects.
      */
     jsonAll(ctx, jsonField, value) {
@@ -108,52 +111,52 @@ export class SqliteDialect extends AbstractSqlDialect {
         return `(${conditions.join(' AND ')})`;
     }
     jsonSize(ctx, jsonField, value) {
-        return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`json_array_length(${jsonField})`), value));
+        return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`JSON_ARRAY_LENGTH(${jsonField})`), value));
     }
-    /** `json_each` yields both scalar and object elements, so one form covers each case. */
+    /** `JSON_EACH` yields both scalar and object elements, so one form covers each case. */
     jsonElemFrom(jsonField, _fields, alias) {
-        return `json_each(${jsonField}) ${alias}`;
+        return `JSON_EACH(${jsonField}) ${alias}`;
     }
     jsonElemRef(alias, field, asJson = false) {
         if (field === undefined) {
             return `${alias}.value`;
         }
-        return asJson ? `${alias}.value -> ${jsonPath(field)}` : `json_extract(${alias}.value, ${jsonPath(field)})`;
+        return asJson ? `${alias}.value -> ${jsonPath(field)}` : `JSON_EXTRACT(${alias}.value, ${jsonPath(field)})`;
     }
     getJsonPathScalarExpr(escapedColumn, jsonPathStr) {
-        return `json_extract(${escapedColumn}, ${jsonPath(jsonPathStr)})`;
+        return `JSON_EXTRACT(${escapedColumn}, ${jsonPath(jsonPathStr)})`;
     }
     numericCast(expr) {
         return `CAST(${expr} AS REAL)`;
     }
     jsonCast(operand) {
-        return `json(${operand})`;
+        return `JSON(${operand})`;
     }
     /**
-     * `json_replace` leaves an absent key (and a NULL column) untouched. Elements are read back
-     * through `->` at their own `fullkey` so each keeps its JSON type - `json_each`'s `value` would
+     * `JSON_REPLACE` leaves an absent key (and a NULL column) untouched. Elements are read back
+     * through `->` at their own `fullkey` so each keeps its JSON type - `JSON_EACH`'s `value` would
      * flatten booleans to 0/1 and stringify objects.
      */
     jsonPullKey(ctx, expr, escapedCol, key, value) {
         const path = jsonPath(key);
         const elem = `${escapedCol} -> ${JSON_PULL_ALIAS}.fullkey`;
-        const kept = `SELECT json_group_array(json(${elem})) FROM json_each(${escapedCol}, ${path}) ${JSON_PULL_ALIAS} WHERE ${elem} <> ${this.jsonScalarParam(ctx, value)}`;
-        return `json_replace(${expr}, ${path}, (${kept}))`;
+        const kept = `SELECT JSON_GROUP_ARRAY(JSON(${elem})) FROM JSON_EACH(${escapedCol}, ${path}) ${JSON_PULL_ALIAS} WHERE ${elem} <> ${this.jsonScalarParam(ctx, value)}`;
+        return `JSON_REPLACE(${expr}, ${path}, (${kept}))`;
     }
     jsonSet(ctx, expr, set, field) {
-        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'json_set', jsonSetTarget(expr, field, `'{}'`), set);
+        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'JSON_SET', jsonSetTarget(expr, field, `'{}'`), set);
     }
     /**
      * `[#]` appends, creating the array when the key is absent.
      *
-     * @remarks `json_set` rather than `json_insert`: the two are equivalent here because `[#]` always
-     * resolves past the end of the array, and Turso's engine implements `json_insert` as create-only,
+     * @remarks `JSON_SET` rather than `JSON_INSERT`: the two are equivalent here because `[#]` always
+     * resolves past the end of the array, and Turso's engine implements `JSON_INSERT` as create-only,
      * so it silently drops the element when the array already exists.
      */
     jsonPush(ctx, expr, push) {
-        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'json_set', expr, push, '[#]');
+        return jsonAssignCall((value) => this.jsonScalarParam(ctx, value), 'JSON_SET', expr, push, '[#]');
     }
     jsonUnset(_ctx, expr, unset) {
-        return jsonRemoveCall('json_remove', expr, unset);
+        return jsonRemoveCall('JSON_REMOVE', expr, unset);
     }
 }

package/dist/type/dialect.d.ts

@@ -128,8 +128,35 @@ export interface EngineFeatures {
     readonly vectorSupportsLength: boolean;
     /** Whether the dialect natively supports the TIMESTAMPTZ alias/type. */
     readonly supportsTimestamptz: boolean;
-    /** Whether the dialect defaults to TEXT for strings when no length is specified (e.g. Postgres). */
-    readonly defaultStringAsText: boolean;
+    /**
+     * How a `string` column is sized: `text` is always the unbounded type whatever length was asked
+     * for (SQLite, whose affinity makes a bound meaningless), `bounded-text` takes the bound when there
+     * is one and the unbounded type otherwise (the Postgres family), `varchar` is always bounded and
+     * falls back to 255 (the MySQL family, SQL Server).
+     *
+     * Three-way for the reason {@link commentSyntax} is: a boolean puts SQLite and Postgres on the
+     * same branch, and they need different answers.
+     */
+    readonly stringSizing: 'text' | 'bounded-text' | 'varchar';
+    /** Whether the engine has unsigned integers, so `@Field({ unsigned: true })` reaches the column. */
+    readonly supportsUnsigned: boolean;
+    /**
+     * Whether one table can be reached by two cascading foreign-key paths. SQL Server refuses the
+     * constraint outright ("may cause cycles or multiple cascade paths", error 1785) and Oracle
+     * likewise, so a cascade is downgraded to `NO ACTION` there rather than emitting DDL the engine
+     * rejects - which would otherwise fail on any diamond-shaped schema at create time.
+     */
+    readonly multipleCascadePaths: boolean;
+    /**
+     * Whether the engine has SQL-level cursors (`DECLARE`/`FETCH FORWARD`/`CLOSE`), which is how a
+     * driver with no cursor API of its own still streams a result set instead of buffering it - see
+     * `postgres/pgCursorStream.ts`. True across the Postgres wire family, whose spelling that helper
+     * speaks; SQL Server and Oracle have cursors of their own but not this syntax.
+     *
+     * The node-`pg` family reports `true` and goes on using `pg-query-stream`: the flag says the engine
+     * has cursors, not that the driver needs them.
+     */
+    readonly serverSideCursors: boolean;
 }
 export interface DialectFeatures extends EngineFeatures, DriverCapabilities {
 }
@@ -219,13 +246,13 @@ export interface QueryDialect {
 /**
  * Supported SQL dialect identifiers.
  */
-export type SqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb' | 'sqlite';
+export type SqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb' | 'sqlite' | 'mssql';
 /**
  * Minimal dialect interface exposing escapeIdChar for SQL operations
  */
 export interface SqlQueryDialect extends QueryDialect {
     /**
-     * The SQL dialect name (postgres, mysql, mariadb, sqlite).
+     * The SQL dialect name (postgres, mysql, mariadb, sqlite, mssql).
      */
     readonly dialectName: SqlDialectName;
     /**

package/dist/type/migratorDialect.d.ts

@@ -1,5 +1,5 @@
 import type { DialectName } from './querier.js';
-declare const KNOWN_MIGRATOR_DIALECTS: readonly ["postgres", "cockroachdb", "mysql", "mariadb", "sqlite", "mongodb"];
+declare const KNOWN_MIGRATOR_DIALECTS: readonly ["postgres", "cockroachdb", "mysql", "mariadb", "sqlite", "mssql", "mongodb"];
 export type KnownMigratorDialect = (typeof KNOWN_MIGRATOR_DIALECTS)[number];
 /**
  * Whether `d` is supported by built-in migrator introspection / schema generators.

package/dist/type/migratorDialect.js

@@ -4,6 +4,7 @@ const KNOWN_MIGRATOR_DIALECTS = [
     'mysql',
     'mariadb',
     'sqlite',
+    'mssql',
     'mongodb',
 ];
 /**

package/dist/type/query.d.ts

@@ -1,4 +1,4 @@
-import type { FieldKey, IdKey, JsonFieldPaths, RelationKey, RelationTarget } from './entity.js';
+import type { FieldKey, IdKey, JsonFieldPaths, RelationKey, RelationTarget, WrittenId } from './entity.js';
 import type { QueryLock } from './queryLock.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
@@ -407,7 +407,29 @@ export type QueryStringified = {
     [K in keyof Query<unknown>]?: string;
 };
 /**
- * result of an update operation.
+ * What upserting one row reports, against the entity rather than the driver.
+ *
+ * `created` is here and not on {@link QueryUpsertManyResult} because it is only ever knowable for a
+ * single statement: a batch's `affectedRows` is a weighted sum on the dialects that report one at
+ * all, and a batch of mixed shapes is several statements.
+ */
+export type QueryUpsertOneResult<E> = {
+    readonly id?: WrittenId<E>;
+    readonly changes?: number;
+    /** Whether the record was created (`true`) or updated (`false`), where the dialect can tell. */
+    readonly created?: boolean;
+};
+/**
+ * What upserting many rows reports. `ids` is payload-aligned like an insert's, so it zips with the
+ * rows that were passed, and carries a composite key as the map naming it.
+ */
+export type QueryUpsertManyResult<E> = {
+    readonly ids: (WrittenId<E> | undefined)[];
+    readonly changes?: number;
+};
+/**
+ * result of an update operation, as the driver reports it - which is what `run` hands back, where
+ * there is no entity to name the ids against. The `QueryUpsert*Result` pair is the entity-level shape.
  */
 export type QueryUpdateResult = {
     /**
@@ -415,11 +437,12 @@ export type QueryUpdateResult = {
      */
     changes?: number;
     /**
-     * the inserted IDs, in insertion order. Exact on `'returning'` dialects; inferred from the
-     * driver header on the others (see {@link InsertIdSource}), and empty when the header
-     * reports no generated ID.
+     * the IDs the statement reported, in payload order, `undefined` where it reported none for that
+     * row - a MongoDB upsert names only the documents it inserted. Exact on `'returning'` dialects;
+     * inferred from the driver header on the others (see {@link InsertIdSource}), and absent
+     * altogether when the header reports nothing.
      */
-    ids?: PrimaryKey[];
+    ids?: (PrimaryKey | undefined)[];
     /**
      * first inserted ID.
      */

package/dist/type/universalQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { EntityData, EntityId, FieldKey, RelationKey, UpdatePayload, WrittenId } from './entity.js';
-import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult } from './query.js';
+import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpsertOneResult, QueryUpsertManyResult } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
 import type { QuerierCountedResult, QuerierResult, QuerierTransport } from './wire.js';
@@ -139,7 +139,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param payload the data to be persisted
      * @return operation metadata; see {@link QueryUpdateResult}
      */
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
     /**
      * Insert or update many records based on the conflict paths.
      * @param entity the entity to persist on
@@ -147,7 +147,7 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param payload the data to be persisted
      * @return operation metadata; see {@link QueryUpdateResult}
      */
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
     /**
      * insert or update a record.
      * @param entity the entity to persist on

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uql-orm",
   "homepage": "https://uql-orm.dev",
-  "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
+  "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -49,7 +49,8 @@
     "./pglite": "./dist/pglite/index.js",
     "./d1": "./dist/d1/index.js",
     "./bunSql": "./dist/bunSql/index.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./mssql": "./dist/mssql/index.js"
   },
   "files": [
     "dist",
@@ -75,6 +76,7 @@
     "express": ">=5.0.0",
     "mariadb": ">=3.0.0",
     "mongodb": ">=6.0.0",
+    "mssql": ">=11.0.0",
     "mysql2": ">=3.0.0",
     "pg": ">=8.0.0",
     "pg-query-stream": ">=4.0.0",
@@ -125,6 +127,9 @@
     },
     "rxjs": {
       "optional": true
+    },
+    "mssql": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -139,12 +144,14 @@
     "@tursodatabase/serverless": "^1.4.0",
     "@types/better-sqlite3": "^9.6.0",
     "@types/express": "^5.0.6",
+    "@types/mssql": "^12.3.0",
     "@types/pg": "^8.23.1",
     "@types/ws": "^8.18.1",
     "better-sqlite3": "^13.0.3",
     "express": "^5.2.1",
     "mariadb": "^3.5.4",
     "mongodb": "^7.6.0",
+    "mssql": "^11",
     "mysql2": "^3.24.4",
     "pg": "^8.23.0",
     "pg-query-stream": "^4.17.0",
@@ -185,6 +192,9 @@
     "sqlite",
     "sqlite3",
     "cockroachdb",
+    "mssql",
+    "sqlserver",
+    "sql-server",
     "mongodb",
     "mongo",
     "libsql",