uql-orm 0.52.0 → 0.54.0

package/dist/http/handler.js

@@ -1,5 +1,6 @@
 import { withContext } from '../context/context.js';
 import { getEntities, getMeta, soleIdOf } from '../entity/index.js';
+import { whereIds } from '../util/dialect.util.js';
 import { entityPath, matchRoute } from './contract.js';
 import { parseQueryParams } from './query.js';
 /** `Company (crm.Company)`: the class, and the table it maps, which is what tells two apart. */
@@ -145,7 +146,7 @@ export function createRequestHandler(opts) {
                         if (founds.length) {
                             const idKey = soleIdOf(meta, 'the HTTP handler');
                             ids = founds.map((found) => found[idKey]);
-                            count = await querier.deleteMany(entity, { $where: ids }, { hardDelete });
+                            count = await querier.deleteMany(entity, { $where: whereIds(meta, ids) }, { hardDelete });
                         }
                         return ok({ data: ids, count });
                     });
@@ -157,16 +158,6 @@ function ok(body) {
     return { status: 200, body };
 }
 function buildIdQuery(meta, id, query) {
-    const idKey = soleIdOf(meta, 'the HTTP handler');
-    const where = query.$where;
-    if (Array.isArray(where)) {
-        query.$where = { $and: [{ [idKey]: { $in: where } }, { [idKey]: id }] };
-    }
-    else if (typeof where === 'object' && where !== null) {
-        query.$where = { ...where, [idKey]: id };
-    }
-    else {
-        query.$where = { [idKey]: id };
-    }
+    query.$where = { ...query.$where, [soleIdOf(meta, 'the HTTP handler')]: id };
     return query;
 }

package/dist/http/query.js

@@ -1,7 +1,7 @@
 // the clause lists themselves, not the barrel: this module is in the browser bundle's graph
 import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_ROOT_NUMBER_CLAUSES, QUERY_ROOT_OBJECT_CLAUSES, } from '../type/query.js';
 // the specific util module, not the barrel, so the browser bundle does not pull in entity metadata
-import { getKeys } from '../util/object.util.js';
+import { getKeys, isWhereMap } from '../util/object.util.js';
 /**
  * Keys accepted from the wire - query structure ({@link Query}) plus the `hardDelete`/`count` scalar
  * flags. Anything else (e.g. `filters`, `context`, `$entity`) is dropped so a remote client can't
@@ -50,6 +50,9 @@ export function parseQueryParams(params = {}) {
         }
     }
     query['$where'] ??= {};
+    if (!isWhereMap(query['$where'])) {
+        throw Object.assign(new TypeError("'$where' must be a JSON object"), { status: 400 });
+    }
     // A query string carries every value as text, so what decodes a clause is the shape its group
     // declares. `'false'` is the reason the boolean pass exists rather than the raw value being taken:
     // it is a non-empty string, so a `$distinct=false` would otherwise read as asking for one.

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

@@ -1,11 +1,19 @@
 import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
 import { IndexDdl } from './indexDdl.js';
+import { TableDdl } from './tableDdl.js';
 export { IndexDdl } from './indexDdl.js';
+export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 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.
  */
 export declare function indexDdlFor(dialect: AbstractSqlDialect): IndexDdl;
+/**
+ * The table DDL a dialect gets: SQL Server's, or the portable form every other engine takes. By
+ * `dialectName`, which a subclass inherits too, so this entry need not carry the dialect itself.
+ */
+export declare function tableDdlFor(dialect: AbstractSqlDialect): TableDdl;

package/dist/migrate/ddl/index.js

@@ -4,11 +4,15 @@ import { PgLikeSqlDialect } from '../../dialect/pgLikeSqlDialect.js';
 import { MariaDialect } from '../../maria/mariaDialect.js';
 import { MySqlDialect } from '../../mysql/mysqlDialect.js';
 import { IndexDdl } from './indexDdl.js';
+import { MsSqlTableDdl } from './mssqlTableDdl.js';
 import { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 import { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+import { TableDdl } from './tableDdl.js';
 export { IndexDdl } from './indexDdl.js';
+export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 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
@@ -32,3 +36,10 @@ export function indexDdlFor(dialect) {
     }
     return new IndexDdl(dialect);
 }
+/**
+ * The table DDL a dialect gets: SQL Server's, or the portable form every other engine takes. By
+ * `dialectName`, which a subclass inherits too, so this entry need not carry the dialect itself.
+ */
+export function tableDdlFor(dialect) {
+    return dialect.dialectName === 'mssql' ? new MsSqlTableDdl(dialect) : new TableDdl(dialect);
+}

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

@@ -0,0 +1,23 @@
+import type { ColumnSchema } from '../../type/index.js';
+import { TableDdl } from './tableDdl.js';
+/**
+ * SQL Server keeps a column's `DEFAULT`, `CHECK` and `UNIQUE` as constraints under names it picks, and
+ * refuses to drop or retype the column past one, so they go first - looked up by column, as no two
+ * databases name them alike. Renames are `sp_rename`, T-SQL having no `RENAME` clause.
+ */
+export declare class MsSqlTableDdl extends TableDdl {
+    /** T-SQL rejects the optional `COLUMN` keyword after `ADD`. */
+    addColumn(table: string, definition: string): string;
+    /** Its constraints go with the column, as they do on every other engine. */
+    dropColumn(table: string, column: string): string[];
+    /**
+     * `ALTER COLUMN` takes the type and nullability alone, so the default is dropped and added back as a
+     * constraint of its own. A `CHECK` or `UNIQUE` stays, and the server refuses a retype it blocks.
+     */
+    alterColumn(table: string, column: ColumnSchema): string[];
+    renameColumn(table: string, oldName: string, newName: string): string;
+    renameTable(oldName: string, newName: string): string;
+    storedGeneratedColumn(_type: string, expression: string): string;
+    /** One statement, so a split on `;` cannot part the lookup from the `EXEC` it feeds. */
+    private dropConstraints;
+}

package/dist/migrate/ddl/mssqlTableDdl.js

@@ -0,0 +1,61 @@
+import { escapeSingleQuotes } from '../../util/sqlLiteral.js';
+import { sizedType, TableDdl } from './tableDdl.js';
+/** The constraints of each kind on column `c`, the `sys.columns` row {@link MsSqlTableDdl} reads. */
+const CONSTRAINTS_ON = {
+    default: /*sql*/ `SELECT d.name FROM sys.default_constraints d
+    WHERE d.parent_object_id = c.object_id AND d.parent_column_id = c.column_id`,
+    check: /*sql*/ `SELECT k.name FROM sys.check_constraints k
+    WHERE k.parent_object_id = c.object_id AND k.parent_column_id = c.column_id`,
+    unique: /*sql*/ `SELECT u.name FROM sys.key_constraints u
+    JOIN sys.index_columns ic ON ic.object_id = u.parent_object_id AND ic.index_id = u.unique_index_id
+    WHERE u.parent_object_id = c.object_id AND u.type = 'UQ' AND ic.column_id = c.column_id`,
+};
+/**
+ * SQL Server keeps a column's `DEFAULT`, `CHECK` and `UNIQUE` as constraints under names it picks, and
+ * refuses to drop or retype the column past one, so they go first - looked up by column, as no two
+ * databases name them alike. Renames are `sp_rename`, T-SQL having no `RENAME` clause.
+ */
+export class MsSqlTableDdl extends TableDdl {
+    /** T-SQL rejects the optional `COLUMN` keyword after `ADD`. */
+    addColumn(table, definition) {
+        return /*sql*/ `ALTER TABLE ${this.dialect.escapeId(table)} ADD ${definition};`;
+    }
+    /** Its constraints go with the column, as they do on every other engine. */
+    dropColumn(table, column) {
+        return [this.dropConstraints(table, column, Object.values(CONSTRAINTS_ON)), ...super.dropColumn(table, column)];
+    }
+    /**
+     * `ALTER COLUMN` takes the type and nullability alone, so the default is dropped and added back as a
+     * constraint of its own. A `CHECK` or `UNIQUE` stays, and the server refuses a retype it blocks.
+     */
+    alterColumn(table, column) {
+        const target = this.dialect.escapeId(table);
+        const name = this.dialect.escapeId(column.name);
+        const statements = [
+            this.dropConstraints(table, column.name, [CONSTRAINTS_ON.default]),
+            /*sql*/ `ALTER TABLE ${target} ALTER COLUMN ${name} ${sizedType(column)} ${column.nullable ? 'NULL' : 'NOT NULL'};`,
+        ];
+        if (column.defaultValue !== undefined) {
+            statements.push(/*sql*/ `ALTER TABLE ${target} ADD${this.defaultClause(column)} FOR ${name};`);
+        }
+        return statements;
+    }
+    renameColumn(table, oldName, newName) {
+        const qualified = `${this.dialect.escapeId(table)}.${this.dialect.escapeId(oldName)}`;
+        return /*sql*/ `EXEC sp_rename ${this.dialect.escape(qualified)}, ${this.dialect.escape(newName)}, 'COLUMN';`;
+    }
+    renameTable(oldName, newName) {
+        return /*sql*/ `EXEC sp_rename ${this.dialect.escape(this.dialect.escapeId(oldName))}, ${this.dialect.escape(newName)};`;
+    }
+    storedGeneratedColumn(_type, expression) {
+        return /*sql*/ `AS (${expression}) PERSISTED`;
+    }
+    /** One statement, so a split on `;` cannot part the lookup from the `EXEC` it feeds. */
+    dropConstraints(table, column, kinds) {
+        const target = this.dialect.escapeId(table);
+        return (`DECLARE @drop nvarchar(max) = (SELECT STRING_AGG(N'ALTER TABLE ${escapeSingleQuotes(target)} DROP CONSTRAINT ' ` +
+            `+ QUOTENAME(pinned.name), N'; ') FROM sys.columns c CROSS APPLY (${kinds.join(' UNION ALL ')}) pinned ` +
+            `WHERE c.object_id = OBJECT_ID(${this.dialect.escape(target)}) AND c.name = ${this.dialect.escape(column)}) ` +
+            'EXEC (@drop);');
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
+import type { ColumnSchema } from '../../type/index.js';
+/**
+ * A column's type with the size it was read back with, unless its spelling already carries one:
+ * introspection reports `VARCHAR` and `255` apart, where a type from an entity is already whole.
+ */
+export declare function sizedType(column: Pick<ColumnSchema, 'type' | 'length' | 'precision' | 'scale'>): string;
+/**
+ * The `ALTER TABLE` statements an engine spells its own way: the migrator's, for the reason
+ * {@link IndexDdl} is. The form here is the portable one; SQL Server's is {@link MsSqlTableDdl}.
+ */
+export declare class TableDdl {
+    protected readonly dialect: AbstractSqlDialect;
+    constructor(dialect: AbstractSqlDialect);
+    addColumn(table: string, definition: string): string;
+    dropColumn(table: string, column: string): string[];
+    /**
+     * What changes `column` to what it now declares. `definition` is the whole column, which MySQL's
+     * `MODIFY COLUMN` restates; Postgres takes each change as a clause of its own.
+     */
+    alterColumn(table: string, column: ColumnSchema, definition: string): string[];
+    renameColumn(table: string, oldName: string, newName: string): string;
+    renameTable(oldName: string, newName: string): string;
+    /** A stored generated column's type, with the clause computing it. */
+    storedGeneratedColumn(type: string, expression: string): string;
+    /**
+     * ` DEFAULT <sql>`, or nothing where the column declares none. Empty rather than `DEFAULT NULL`, so
+     * an absent default stays absent - `defaultValue: null` is the way to ask for one.
+     */
+    defaultClause(column: {
+        readonly defaultValue?: unknown;
+        readonly type: string;
+    }): string;
+}

package/dist/migrate/ddl/tableDdl.js

@@ -0,0 +1,71 @@
+import { formatDefaultValue } from '../builder/expressions.js';
+/**
+ * A column's type with the size it was read back with, unless its spelling already carries one:
+ * introspection reports `VARCHAR` and `255` apart, where a type from an entity is already whole.
+ */
+export function sizedType(column) {
+    if (column.type.includes('(')) {
+        return column.type;
+    }
+    if (column.precision !== undefined) {
+        const size = column.scale === undefined ? column.precision : `${column.precision}, ${column.scale}`;
+        return `${column.type}(${size})`;
+    }
+    return column.length === undefined ? column.type : `${column.type}(${column.length})`;
+}
+/**
+ * The `ALTER TABLE` statements an engine spells its own way: the migrator's, for the reason
+ * {@link IndexDdl} is. The form here is the portable one; SQL Server's is {@link MsSqlTableDdl}.
+ */
+export class TableDdl {
+    dialect;
+    constructor(dialect) {
+        this.dialect = dialect;
+    }
+    addColumn(table, definition) {
+        return `ALTER TABLE ${this.dialect.escapeId(table)} ADD COLUMN ${definition};`;
+    }
+    dropColumn(table, column) {
+        return [`ALTER TABLE ${this.dialect.escapeId(table)} DROP COLUMN ${this.dialect.escapeId(column)};`];
+    }
+    /**
+     * What changes `column` to what it now declares. `definition` is the whole column, which MySQL's
+     * `MODIFY COLUMN` restates; Postgres takes each change as a clause of its own.
+     */
+    alterColumn(table, column, definition) {
+        if (this.dialect.alterColumnSyntax === 'none') {
+            throw new TypeError(`${this.dialect}: Cannot alter column "${column.name}" - you must recreate the table. ` +
+                `This database does not support ALTER COLUMN.`);
+        }
+        const target = this.dialect.escapeId(table);
+        if (this.dialect.alterColumnStrategy !== 'separate-clauses') {
+            return [`ALTER TABLE ${target} ${this.dialect.alterColumnSyntax} ${definition};`];
+        }
+        const alter = `ALTER TABLE ${target} ALTER COLUMN ${this.dialect.escapeId(column.name)}`;
+        return [
+            `${alter} TYPE ${column.type};`,
+            `${alter} ${column.nullable ? 'DROP NOT NULL' : 'SET NOT NULL'};`,
+            column.defaultValue === undefined ? `${alter} DROP DEFAULT;` : `${alter} SET${this.defaultClause(column)};`,
+        ];
+    }
+    renameColumn(table, oldName, newName) {
+        const [target, from, to] = [table, oldName, newName].map((name) => this.dialect.escapeId(name));
+        return `ALTER TABLE ${target} RENAME COLUMN ${from} TO ${to};`;
+    }
+    renameTable(oldName, newName) {
+        return `ALTER TABLE ${this.dialect.escapeId(oldName)} RENAME TO ${this.dialect.escapeId(newName)};`;
+    }
+    /** A stored generated column's type, with the clause computing it. */
+    storedGeneratedColumn(type, expression) {
+        return `${type} GENERATED ALWAYS AS (${expression}) STORED`;
+    }
+    /**
+     * ` DEFAULT <sql>`, or nothing where the column declares none. Empty rather than `DEFAULT NULL`, so
+     * an absent default stays absent - `defaultValue: null` is the way to ask for one.
+     */
+    defaultClause(column) {
+        return column.defaultValue === undefined
+            ? ''
+            : ` DEFAULT ${formatDefaultValue(column.defaultValue, this.dialect, column.type)}`;
+    }
+}

package/dist/migrate/introspection/mssqlIntrospector.d.ts

@@ -16,21 +16,16 @@ export declare class MsSqlSchemaIntrospector extends AbstractSqlSchemaIntrospect
         count?: number;
     }[]): boolean;
     /**
-     * `is_identity` and the default come from `sys`, not `INFORMATION_SCHEMA`: the latter has no
-     * identity flag, and reports a default already wrapped in the parentheses the engine reprints it
-     * with, which is the same text either way but only nameable as a constraint through `sys`.
+     * From `sys` rather than `INFORMATION_SCHEMA`, which has no identity flag and no per-column view of
+     * the key or of a unique index. A key column is not also `isUnique`, as on MySQL: only a unique index
+     * of its own, other than the key's, makes it so.
      */
     protected getColumnsQuery(_tableName: string): string;
     /** `is_primary_key` is excluded: the key is read separately, the way every other engine reads it. */
     protected getIndexesQuery(_tableName: string): string;
     protected getForeignKeysQuery(_tableName: string): string;
     protected getPrimaryKeyQuery(_tableName: string): string;
-    /**
-     * `max_length` is in bytes, so an `NVARCHAR` column reports twice its declared length and `MAX`
-     * reports `-1`. Read as characters, every Unicode column would drift to double its width the first
-     * time it was diffed against the entity that declared it.
-     */
-    protected mapColumnsResult(read: TableRowReader, tableName: string, results: MsSqlColumnRow[]): Promise<ColumnSchema[]>;
+    protected mapColumnsResult(_read: TableRowReader, _tableName: string, results: MsSqlColumnRow[]): Promise<ColumnSchema[]>;
     protected mapIndexesResult(_read: TableRowReader, _tableName: string, results: {
         index_name: string;
         columns: string;
@@ -59,5 +54,7 @@ type MsSqlColumnRow = {
     is_nullable: boolean;
     is_identity: boolean;
     column_default: string | null;
+    is_primary_key: number | null;
+    is_unique: number | null;
 };
 export {};

package/dist/migrate/introspection/mssqlIntrospector.js

@@ -30,9 +30,9 @@ export class MsSqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return (this.toNumber(results[0]?.count) ?? 0) > 0;
     }
     /**
-     * `is_identity` and the default come from `sys`, not `INFORMATION_SCHEMA`: the latter has no
-     * identity flag, and reports a default already wrapped in the parentheses the engine reprints it
-     * with, which is the same text either way but only nameable as a constraint through `sys`.
+     * From `sys` rather than `INFORMATION_SCHEMA`, which has no identity flag and no per-column view of
+     * the key or of a unique index. A key column is not also `isUnique`, as on MySQL: only a unique index
+     * of its own, other than the key's, makes it so.
      */
     getColumnsQuery(_tableName) {
         return /*sql*/ `
@@ -44,12 +44,27 @@ export class MsSqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         c.scale as numeric_scale,
         c.is_nullable as is_nullable,
         c.is_identity as is_identity,
-        d.definition as column_default
+        d.definition as column_default,
+        f.is_primary_key,
+        f.is_unique
       FROM sys.columns c
       JOIN sys.objects o ON o.object_id = c.object_id
       JOIN sys.schemas s ON s.schema_id = o.schema_id
       JOIN sys.types t ON t.user_type_id = c.user_type_id
       LEFT JOIN sys.default_constraints d ON d.object_id = c.default_object_id
+      OUTER APPLY (
+        SELECT
+          MAX(CAST(i.is_primary_key AS INT)) as is_primary_key,
+          MAX(CASE WHEN i.is_primary_key = 0 AND n.key_columns = 1 THEN 1 ELSE 0 END) as is_unique
+        FROM sys.index_columns ic
+        JOIN sys.indexes i ON i.object_id = ic.object_id AND i.index_id = ic.index_id
+        CROSS APPLY (
+          SELECT COUNT(*) as key_columns FROM sys.index_columns k
+          WHERE k.object_id = i.object_id AND k.index_id = i.index_id AND k.is_included_column = 0
+        ) n
+        WHERE ic.object_id = c.object_id AND ic.column_id = c.column_id
+          AND ic.is_included_column = 0 AND i.is_unique = 1
+      ) f
       WHERE s.name = ${this.schemaExpr} AND o.name = @p1
       ORDER BY c.column_id
     `;
@@ -105,44 +120,19 @@ export class MsSqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       ORDER BY ic.key_ordinal
     `;
     }
-    /**
-     * `max_length` is in bytes, so an `NVARCHAR` column reports twice its declared length and `MAX`
-     * reports `-1`. Read as characters, every Unicode column would drift to double its width the first
-     * time it was diffed against the entity that declared it.
-     */
-    async mapColumnsResult(read, tableName, results) {
-        // One extra statement for both flags, and the reader sends it once: a column is in the key or
-        // uniquely indexed on its own, and `sys` is the only place either is readable per column.
-        const flags = await read(
-        /*sql*/ `
-      SELECT c.name as column_name, MAX(CAST(i.is_primary_key AS INT)) as is_primary_key
-      FROM sys.indexes i
-      JOIN sys.objects o ON o.object_id = i.object_id
-      JOIN sys.schemas s ON s.schema_id = o.schema_id
-      JOIN sys.index_columns ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
-      JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
-      WHERE s.name = ${this.schemaExpr} AND o.name = @p1
-        AND i.is_unique = 1 AND ic.is_included_column = 0
-        AND (SELECT COUNT(*) FROM sys.index_columns k
-             WHERE k.object_id = i.object_id AND k.index_id = i.index_id AND k.is_included_column = 0) = 1
-      GROUP BY c.name
-    `, [tableName]);
-        const unique = new Set(flags.map((row) => row.column_name));
-        const keys = new Set(flags.filter((row) => Boolean(row.is_primary_key)).map((row) => row.column_name));
+    async mapColumnsResult(_read, _tableName, results) {
         return results.map((row) => {
             const type = row.data_type.toUpperCase();
-            const wide = type.startsWith('N');
             const bytes = this.toNumber(row.max_length);
-            const length = bytes === undefined || bytes < 0 || !CHARACTER_TYPES.has(type) ? undefined : wide ? bytes / 2 : bytes;
             return {
                 name: row.column_name,
                 type: bytes === -1 && CHARACTER_TYPES.has(type) ? `${type}(MAX)` : type,
                 nullable: Boolean(row.is_nullable),
                 defaultValue: this.parseDefaultValue(row.column_default),
                 isAutoIncrement: Boolean(row.is_identity),
-                isPrimaryKey: keys.has(row.column_name),
-                isUnique: unique.has(row.column_name),
-                length,
+                isPrimaryKey: Boolean(row.is_primary_key),
+                isUnique: Boolean(row.is_unique),
+                length: widthOf(type, bytes),
                 precision: NUMERIC_TYPES.has(type) ? this.toNumber(row.numeric_precision) : undefined,
                 scale: NUMERIC_TYPES.has(type) ? this.toNumber(row.numeric_scale) : undefined,
             };
@@ -196,3 +186,20 @@ export class MsSqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
 /** The types whose `max_length` is a width rather than a fixed storage size. */
 const CHARACTER_TYPES = new Set(['CHAR', 'NCHAR', 'VARCHAR', 'NVARCHAR', 'BINARY', 'VARBINARY']);
 const NUMERIC_TYPES = new Set(['DECIMAL', 'NUMERIC']);
+/**
+ * A column's declared width from `max_length`, which is bytes: an `N` type holds two a character, a
+ * `VECTOR` is an 8-byte header and four a dimension, and `MAX` is `-1`. Read as bytes, every Unicode
+ * column would drift to double its width against the entity that declared it.
+ */
+function widthOf(type, bytes) {
+    if (bytes === undefined || bytes < 0) {
+        return undefined;
+    }
+    if (type === 'VECTOR') {
+        return (bytes - 8) / 4;
+    }
+    if (!CHARACTER_TYPES.has(type)) {
+        return undefined;
+    }
+    return type.startsWith('N') ? bytes / 2 : bytes;
+}

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

@@ -4,7 +4,7 @@ import { type DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
 import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
 import type { FullColumnDefinition, TableDefinition } from './builder/types.js';
-import { type IndexDdl } from './ddl/index.js';
+import { type IndexDdl, type TableDdl } from './ddl/index.js';
 /**
  * Unified SQL schema generator.
  * Parameterized by dialect to handle Postgres, MySQL, MariaDB, and SQLite.
@@ -14,6 +14,8 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     protected readonly defaultForeignKeyAction: ForeignKeyAction;
     /** `CREATE INDEX` for this dialect: the migrator's, so a runtime import carries none of it. */
     protected readonly indexDdl: IndexDdl;
+    /** The `ALTER TABLE` statements this dialect spells its own way, the migrator's for the same reason. */
+    protected readonly tableDdl: TableDdl;
     constructor(dialect: AbstractSqlDialect, defaultForeignKeyAction?: ForeignKeyAction);
     get namingStrategy(): NamingStrategy | undefined;
     get features(): DialectFeatures;
@@ -23,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.
@@ -97,18 +96,14 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      */
     generateColumnDefinitionFromSchema(column: ColumnSchema): string;
     /**
-     * The one place a column definition is spelled. Both callers reach it - the `ColumnSchema` path above
-     * and the `ColumnNode` path below - because the clause order and the "no NOT NULL on a primary key"
-     * rules are the same everywhere, and having them written twice is how the two paths drifted.
+     * The one place a column definition is spelled, so the `ColumnSchema` and `ColumnNode` paths cannot
+     * drift. A key column states `NOT NULL` rather than leave it to the key: SQLite lets a key column hold
+     * NULL otherwise, and SQL Server adds no key over a nullable column. `UNIQUE` is left to the key. An
+     * enum's `CHECK` comes last, the only place MariaDB takes it.
      */
     private renderColumn;
-    /** ` DEFAULT <sql>`, or nothing where the column declares none. Empty rather than `DEFAULT NULL`
-     * so an absent default stays absent - `defaultValue: null` is the way to ask for one. */
-    private defaultClause;
     getSqlType(field: FieldMeta): string;
-    /**
-     * Generate ALTER COLUMN statements (database-specific)
-     */
+    /** The statements that alter `column` in place, as this dialect spells them. */
     generateAlterColumnStatements(tableName: string, column: ColumnSchema, newDefinition: string): string[];
     /** The inline ` COMMENT '...'` a column declaration carries, where the engine takes one there. */
     generateColumnComment(comment: string): string;
@@ -130,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`.
      *
@@ -141,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.
      *