uql-orm 0.80.0 → 0.82.0

package/dist/index.d.ts

@@ -8,4 +8,5 @@ export { withDeleted } from './util/filters.util.js';
 export type { HookContext } from './util/hook.util.js';
 export { DefaultLogger } from './util/logger.js';
 export { raw, refs } from './util/raw.js';
+export { deleteFrom, insertInto, updateTable } from './util/triggerWrite.js';
 export * from './util/uqlError.js';

package/dist/index.js

@@ -7,4 +7,5 @@ export * from './type/index.js';
 export { withDeleted } from './util/filters.util.js';
 export { DefaultLogger } from './util/logger.js';
 export { raw, refs } from './util/raw.js';
+export { deleteFrom, insertInto, updateTable } from './util/triggerWrite.js';
 export * from './util/uqlError.js';

package/dist/migrate/acquireQuerierForMigrations.js

@@ -1,4 +1,5 @@
 import { isMongoQuerier, isSqlQuerier, } from '../type/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * Querier used for schema migrations and the migration journal.
  *
@@ -34,7 +35,7 @@ export function withMongoQuerierForMigrations(pool, requiredBy, task) {
 function withQuerierOfKind(pool, isKind, error, task) {
     return withQuerierForMigrations(pool, (querier) => {
         if (!isKind(querier)) {
-            throw new TypeError(error);
+            throw new UqlUsageError(error);
         }
         return task(querier);
     });

package/dist/migrate/assertCliConfig.js

@@ -1,30 +1,31 @@
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * Validates shape required for the migrations CLI (real `QuerierPool`, not config stubs).
  */
 export function assertCliConfig(config) {
     if (config === null || typeof config !== 'object') {
-        throw new TypeError('Config must be a non-null object');
+        throw new UqlUsageError('Config must be a non-null object');
     }
     const c = config;
     const pool = c['pool'];
     if (pool === null || typeof pool !== 'object') {
-        throw new TypeError('Config.pool is required and must be an object');
+        throw new UqlUsageError('Config.pool is required and must be an object');
     }
     const p = pool;
     for (const key of ['getQuerier', 'transaction', 'withQuerier']) {
         if (typeof p[key] !== 'function') {
-            throw new TypeError(`Config.pool.${key} must be a function`);
+            throw new UqlUsageError(`Config.pool.${key} must be a function`);
         }
     }
     if (p['end'] !== undefined && typeof p['end'] !== 'function') {
-        throw new TypeError('Config.pool.end must be a function when provided');
+        throw new UqlUsageError('Config.pool.end must be a function when provided');
     }
     const dialect = p['dialect'];
     if (dialect === null || typeof dialect !== 'object') {
-        throw new TypeError('Config.pool.dialect is required and must be an object');
+        throw new UqlUsageError('Config.pool.dialect is required and must be an object');
     }
     const dialectName = dialect['dialectName'];
     if (typeof dialectName !== 'string') {
-        throw new TypeError('Config.pool.dialect.dialectName must be a string');
+        throw new UqlUsageError('Config.pool.dialect.dialectName must be a string');
     }
 }

package/dist/migrate/builder/expressions.d.ts

@@ -63,3 +63,5 @@ export declare const expr: {
  * the result needs wrapping, which MySQL demands on its large types whatever the value.
  */
 export declare function formatDefaultValue(value: unknown, dialect: AbstractSqlDialect, columnType?: string): string;
+/** Whether a stored default is the declared one, as the engine reprints it: `'a'::character varying` is `'a'`. */
+export declare function sameDefault(desired: unknown, current: unknown, dialect: AbstractSqlDialect): boolean;

package/dist/migrate/builder/expressions.js

@@ -1,3 +1,4 @@
+import { UqlUsageError } from '../../util/uqlError.js';
 const ANSI = {
     now: 'CURRENT_TIMESTAMP',
     currentDate: 'CURRENT_DATE',
@@ -83,6 +84,30 @@ export function formatDefaultValue(value, dialect, columnType) {
     const { wrapTypes } = DIALECT_DEFAULTS[dialect.dialectName];
     return columnType !== undefined && wrapTypes?.test(columnType) ? `(${sql})` : sql;
 }
+/** Whether a stored default is the declared one, as the engine reprints it: `'a'::character varying` is `'a'`. */
+export function sameDefault(desired, current, dialect) {
+    if (current === desired)
+        return true;
+    // Both spellings of "no default" are the same fact, and engines disagree on which they report:
+    // MariaDB says `null` where MySQL says nothing at all. Reading them as different values asked to
+    // `MODIFY` every nullable column, on every sync, forever.
+    if (current == null || desired == null)
+        return current == null && desired == null;
+    const normalize = (value) => {
+        // Render first: the desired side may be a symbolic expression, the current side is always the
+        // engine's own text, and `{"kind":"now"}` matches no spelling of `CURRENT_TIMESTAMP`.
+        const val = SqlExpression.isExpression(value) ? formatDefaultValue(value, dialect) : value;
+        if (typeof val === 'string') {
+            let s = val.replace(/::[a-z_]+(\s+[a-z_]+)*(\[\])?$/i, '');
+            s = s.replace(/^'(.*)'$/, '$1');
+            if (s.toLowerCase() === 'null')
+                return 'null';
+            return s;
+        }
+        return typeof val === 'object' ? JSON.stringify(val) : String(val);
+    };
+    return normalize(current) === normalize(desired);
+}
 /**
  * Quoting is the dialect's `escape`, so a backslash in a default is escaped the way the engine reads
  * it - MySQL takes `'a\b'` as a backspace where Postgres takes it literally. Only the cases `escape`
@@ -105,7 +130,7 @@ function expressionSql(expression, dialect) {
     const { expressions } = DIALECT_DEFAULTS[dialect.dialectName];
     const sql = expression.kind === 'raw' ? expression.sql : expressions[expression.kind];
     if (sql == null) {
-        throw new TypeError(`${dialect.dialectName} has no '${expression.kind}' default; pass expr.raw(...) with SQL this engine accepts`);
+        throw new UqlUsageError(`${dialect.dialectName} has no '${expression.kind}' default; pass expr.raw(...) with SQL this engine accepts`);
     }
     return sql;
 }

package/dist/migrate/cli-config.js

@@ -1,13 +1,14 @@
 import { stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * Loads the config with a plain `import()`, leaving TypeScript to the runtime: uql bundles no transpiler,
  * since only the project knows its decorator spec. Node's type stripping handles no decorators.
  */
 async function importConfig(path) {
     const mod = (await import(pathToFileURL(path).href).catch((cause) => {
-        throw new TypeError(`Could not import ${path}: ${cause?.message}\n` +
+        throw new UqlUsageError(`Could not import ${path}: ${cause?.message}\n` +
             'If it reaches entity classes, their decorators need a runtime that transforms TypeScript, not ' +
             'just one that strips its types. Run the CLI with `bun`, or with `node --import tsx` ' +
             '(`npm i -D tsx`). A JavaScript config, or passing the config inline, needs neither.', { cause });
@@ -21,14 +22,14 @@ export async function loadConfig(customPath) {
             .then(() => true)
             .catch(() => false);
         if (!exists) {
-            throw new TypeError(`Could not find uql configuration file at ${customPath}`);
+            throw new UqlUsageError(`Could not find uql configuration file at ${customPath}`);
         }
         try {
             const config = await importConfig(fullPath);
             return config;
         }
         catch (error) {
-            throw new TypeError(`Could not load configuration file at ${customPath}: ${error.message}`);
+            throw new UqlUsageError(`Could not load configuration file at ${customPath}: ${error.message}`);
         }
     }
     const configPaths = ['uql.config.ts', 'uql.config.js', 'uql.config.mjs', '.uqlrc.ts', '.uqlrc.js'];
@@ -42,5 +43,5 @@ export async function loadConfig(customPath) {
             return config;
         }
     }
-    throw new TypeError('Could not find uql configuration file. Create a uql.config.ts or uql.config.js file in your project root.');
+    throw new UqlUsageError('Could not find uql configuration file. Create a uql.config.ts or uql.config.js file in your project root.');
 }

package/dist/migrate/cli.js

@@ -247,7 +247,7 @@ export async function runDriftCheck(migrator, config) {
         // `unknown` and type drift compares equal, silently reporting a mismatched column as in sync.
         const report = detectDrift(expectedAST, actualAST, {
             dialect: config.pool?.dialect,
-            indexFacets: migrator.schemaIntrospector.indexFacets,
+            defaultsEqual: generator.defaultsEqual,
             excludeTables: [config.tableName ?? DEFAULT_MIGRATIONS_TABLE],
         });
         printDriftReport(report);

package/dist/migrate/codegen/entityCodeGenerator.js

@@ -252,8 +252,8 @@ export class EntityCodeGenerator {
         }
         const member = (param, column) => memberSource(param, this.options.propertyNameTransformer(column.name));
         const own = lowerFirst(this.options.classNameTransformer(rel.from.table.name));
-        const key = rel.to.table.primaryKey;
-        if (rel.from.columns.length === 1 && key.length === 1 && rel.to.columns[0].name === key[0].name) {
+        const key = rel.to.table.primaryKey?.columns ?? [];
+        if (rel.from.columns.length === 1 && key.length === 1 && rel.to.columns[0].name === key[0]) {
             return `(${own}) => ${member(own, rel.from.columns[0])}`;
         }
         const target = lowerFirst(relatedClassName);

package/dist/migrate/codegen/indexDecoratorSource.d.ts

@@ -1,8 +1,9 @@
 import type { IndexNode } from '../../schema/types.js';
 /**
  * Whether `@Field({ index })` can carry the whole index. It says only "this column is indexed under
- * this name", so anything else the index declares - an expression, a predicate, uniqueness, an access
- * method, stored columns, a stored order - has to be written out as an `@Index` instead.
+ * this name", and `unique` beside it that the index is unique, so anything else the index declares - an
+ * expression, a predicate, an access method, stored columns, a stored order - has to be written out as
+ * an `@Index` instead.
  */
 export declare function isPlainFieldIndex(index: IndexNode): boolean;
 /**

package/dist/migrate/codegen/indexDecoratorSource.js

@@ -1,24 +1,5 @@
 import { isVectorIndexType } from '../../type/index.js';
 import { memberSource, rawTag } from './sourceLiteral.js';
-/**
- * A vector index carries its metric in the operator class pgvector names after it
- * (`vector_cosine_ops`), which is the only place introspection can recover it from. `@Index` requires
- * a `distance` beside a vector `type`, so emitting the type without one would not compile.
- */
-const DISTANCE_BY_OPS_SUFFIX = new Map([
-    ['cosine', 'cosine'],
-    ['l2', 'l2'],
-    ['ip', 'inner'],
-    ['l1', 'l1'],
-]);
-function vectorDistance(index) {
-    if (index.distance) {
-        return index.distance;
-    }
-    const opsClass = index.entries.map((entry) => entry.opsClass).find(Boolean);
-    const suffix = opsClass?.match(/_(\w+)_ops$/)?.[1];
-    return suffix === undefined ? undefined : DISTANCE_BY_OPS_SUFFIX.get(suffix);
-}
 /**
  * The per-entry modifiers worth writing into an entity, which is not everything introspection reports.
  * Postgres states an entry in full - a plain column comes back `order: 'asc', nulls: 'last'` - and
@@ -37,8 +18,9 @@ function significantModifiers(entry) {
 }
 /**
  * Whether `@Field({ index })` can carry the whole index. It says only "this column is indexed under
- * this name", so anything else the index declares - an expression, a predicate, uniqueness, an access
- * method, stored columns, a stored order - has to be written out as an `@Index` instead.
+ * this name", and `unique` beside it that the index is unique, so anything else the index declares - an
+ * expression, a predicate, an access method, stored columns, a stored order - has to be written out as
+ * an `@Index` instead.
  */
 export function isPlainFieldIndex(index) {
     const entries = index.entries;
@@ -46,7 +28,6 @@ export function isPlainFieldIndex(index) {
     return (entries.length === 1 &&
         entry !== undefined &&
         !entry.expression &&
-        !index.unique &&
         index.where === undefined &&
         // Postgres names an access method on every index, so the default one still counts as plain.
         (index.type === undefined || index.type === 'btree') &&
@@ -60,8 +41,9 @@ export function isPlainFieldIndex(index) {
  */
 export function buildIndexDecoratorSource(index, propertyName, param) {
     const entries = index.entries.map((entry) => indexEntrySource(entry, propertyName, param)).join(', ');
+    // `@Index` requires a `distance` beside a vector `type`, as the introspector reads it back.
     const isVector = isVectorIndexType(index.type);
-    const distance = isVector ? vectorDistance(index) : undefined;
+    const distance = isVector ? index.distance : undefined;
     const options = [];
     if (index.name)
         options.push(`name: '${index.name}'`);

package/dist/migrate/ddl/indexDdl.js

@@ -2,6 +2,7 @@ import { jsonTypeMode } from '../../dialect/jsonSql.js';
 import { INDEX_TYPES } from '../../schema/types.js';
 import { INDEX_FEATURE_LABELS, } from '../../type/index.js';
 import { fulltextConfig, getKeys } from '../../util/index.js';
+import { UqlUsageError } from '../../util/uqlError.js';
 /**
  * What in an index asks for each feature. A `Record` over the feature union rather than a list, so a
  * feature added to {@link INDEX_FEATURE_LABELS} cannot reach a dialect without the test that decides
@@ -20,14 +21,14 @@ const INDEX_FEATURE_PROBES = {
 /** Refuses an index of a type `types` lacks, `hints` naming what to declare instead. */
 export function assertIndexType(index, types, dialectName, hints = new Map()) {
     if (index.type && !types.has(index.type)) {
-        throw new TypeError(`${dialectName} has no ${index.type} index (index "${index.name}")` + (hints.get(index.type) ?? ''));
+        throw new UqlUsageError(`${dialectName} has no ${index.type} index (index "${index.name}")` + (hints.get(index.type) ?? ''));
     }
 }
 /** Refuses an index asking for a feature `features` lacks. */
 export function assertIndexFeatures(index, features, dialectName) {
     for (const feature of getKeys(INDEX_FEATURE_PROBES)) {
         if (INDEX_FEATURE_PROBES[feature](index) && !features.has(feature)) {
-            throw new TypeError(`${dialectName} does not support ${INDEX_FEATURE_LABELS[feature]} (index "${index.name}")`);
+            throw new UqlUsageError(`${dialectName} does not support ${INDEX_FEATURE_LABELS[feature]} (index "${index.name}")`);
         }
     }
 }
@@ -122,7 +123,7 @@ export class IndexDdl {
      * every other dialect refuses `jsonArray` in {@link assertIndexFeatures} and never reaches this.
      */
     jsonArrayIndexExpr(_escapedColumn, _json) {
-        throw new TypeError(`${this.dialect.dialectName} has no multi-valued index`);
+        throw new UqlUsageError(`${this.dialect.dialectName} has no multi-valued index`);
     }
     /** Postgres-wire dialects put a vector or user-declared operator class here. */
     indexColumnOpsClass(_entry, _index) {

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

@@ -2,15 +2,15 @@ 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.
+ * refuses to drop or retype the column past one or past an index over it, 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 has no `IF NOT EXISTS` on a table, so the create is guarded by a lookup in the same statement. */
     createTable(target: string, ifNotExists: boolean): string;
     /** 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. */
+    /** Its constraints and indexes 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
@@ -21,5 +21,5 @@ export declare class MsSqlTableDdl extends TableDdl {
     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;
+    private dropPinning;
 }

package/dist/migrate/ddl/mssqlTableDdl.js

@@ -1,19 +1,23 @@
 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
+/** What pins column `c`, the `sys.columns` row {@link MsSqlTableDdl} reads: each constraint, then each index, by kind. */
+const PINNED_BY = {
+    default: /*sql*/ `SELECT d.name, 0 AS is_index 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
+    check: /*sql*/ `SELECT k.name, 0 AS is_index 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
+    unique: /*sql*/ `SELECT u.name, 0 AS is_index 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`,
+    index: /*sql*/ `SELECT DISTINCT i.name, 1 AS is_index FROM sys.indexes i
+    JOIN sys.index_columns ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
+    WHERE i.object_id = c.object_id AND ic.column_id = c.column_id
+      AND i.is_primary_key = 0 AND i.is_unique_constraint = 0`,
 };
 /**
  * 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.
+ * refuses to drop or retype the column past one or past an index over it, 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 has no `IF NOT EXISTS` on a table, so the create is guarded by a lookup in the same statement. */
@@ -25,9 +29,9 @@ export class MsSqlTableDdl extends TableDdl {
     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. */
+    /** Its constraints and indexes 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)];
+        return [this.dropPinning(table, column, Object.values(PINNED_BY)), ...super.dropColumn(table, column)];
     }
     /**
      * `ALTER COLUMN` takes the type and nullability alone, so the default is dropped and added back as a
@@ -37,7 +41,7 @@ export class MsSqlTableDdl extends TableDdl {
         const target = this.dialect.escapeId(table);
         const name = this.dialect.escapeId(column.name);
         const statements = [
-            this.dropConstraints(table, column.name, [CONSTRAINTS_ON.default]),
+            this.dropPinning(table, column.name, [PINNED_BY.default]),
             /*sql*/ `ALTER TABLE ${target} ALTER COLUMN ${name} ${sizedType(column)} ${column.nullable ? 'NULL' : 'NOT NULL'};`,
         ];
         if (column.defaultValue !== undefined) {
@@ -56,10 +60,12 @@ export class MsSqlTableDdl extends TableDdl {
         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 ` +
+    dropPinning(table, column, kinds) {
+        const target = escapeSingleQuotes(this.dialect.escapeId(table));
+        return (`DECLARE @drop nvarchar(max) = (SELECT STRING_AGG(CASE pinned.is_index ` +
+            `WHEN 1 THEN N'DROP INDEX ' + QUOTENAME(pinned.name) + N' ON ${target}' ` +
+            `ELSE N'ALTER TABLE ${target} DROP CONSTRAINT ' + QUOTENAME(pinned.name) END, 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/mysqlIndexDdl.d.ts

@@ -48,8 +48,8 @@ export declare class MariaIndexDdl extends MysqlLikeIndexDdl {
     protected readonly indexTypeHints: Map<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch", string>;
     /**
      * `M=n DISTANCE=metric`, trailing its `CREATE VECTOR INDEX`. The metric names are MariaDB's own
-     * (`euclidean`, not `l2`), and an unsupported one throws rather than being dropped, which would
-     * silently build the index on euclidean - its default - instead of what the entity asked for.
+     * (`euclidean`, not `l2`), stated even for the default distance, cosine, since MariaDB's own is
+     * euclidean; and an unsupported one throws rather than silently building on euclidean.
      */
     protected indexTuning(index: IndexSchema): string;
 }

package/dist/migrate/ddl/mysqlIndexDdl.js

@@ -1,5 +1,6 @@
 import { jsonTypeMode } from '../../dialect/jsonSql.js';
-import { unsupportedVectorMetric, VECTOR_INDEX_TYPES } from '../../type/vector.js';
+import { indexDistance, isVectorIndexType, unsupportedVectorMetric, VECTOR_INDEX_TYPES } from '../../type/vector.js';
+import { UqlUsageError } from '../../util/uqlError.js';
 import { IndexDdl } from './indexDdl.js';
 /**
  * A full-text index is its own keyword here (`CREATE FULLTEXT INDEX ... (cols)`); `USING fulltext` is
@@ -38,14 +39,14 @@ export class MySqlIndexDdl extends MysqlLikeIndexDdl {
     jsonPathIndexExpr(escapedColumn, json) {
         const mode = jsonTypeMode(json.type);
         if (mode === 'json') {
-            throw new TypeError(`mysql cannot index the boolean JSON path '${json.path}', which compares as JSON`);
+            throw new UqlUsageError(`mysql cannot index the boolean JSON path '${json.path}', which compares as JSON`);
         }
         const expr = super.jsonPathIndexExpr(escapedColumn, json);
         if (mode === 'numeric') {
             return expr;
         }
         if (!json.length) {
-            throw new TypeError(`a MySQL index over the string JSON path '${json.path}' needs a length`);
+            throw new UqlUsageError(`a MySQL index over the string JSON path '${json.path}' needs a length`);
         }
         return `CAST(${expr} AS CHAR(${json.length}) CHARACTER SET utf8mb4) COLLATE utf8mb4_bin`;
     }
@@ -84,15 +85,16 @@ export class MariaIndexDdl extends MysqlLikeIndexDdl {
     ]);
     /**
      * `M=n DISTANCE=metric`, trailing its `CREATE VECTOR INDEX`. The metric names are MariaDB's own
-     * (`euclidean`, not `l2`), and an unsupported one throws rather than being dropped, which would
-     * silently build the index on euclidean - its default - instead of what the entity asked for.
+     * (`euclidean`, not `l2`), stated even for the default distance, cosine, since MariaDB's own is
+     * euclidean; and an unsupported one throws rather than silently building on euclidean.
      */
     indexTuning(index) {
         let tuning = super.indexTuning(index) + (index.m === undefined ? '' : ` M=${index.m}`);
-        if (index.distance) {
-            const metric = this.dialect.vectorMetrics.get(index.distance)?.index;
+        if (isVectorIndexType(index.type)) {
+            const distance = indexDistance(index);
+            const metric = this.dialect.vectorMetrics.get(distance)?.index;
             if (!metric) {
-                throw unsupportedVectorMetric(this.dialect.dialectName, index.distance, index.name);
+                throw unsupportedVectorMetric(this.dialect.dialectName, distance, index.name);
             }
             tuning += ` DISTANCE=${metric}`;
         }
@@ -131,13 +133,13 @@ function arrayCastType(json) {
     const type = json.type;
     const cast = ARRAY_CASTS.get(typeof type === 'string' ? type.toLowerCase() : type);
     if (!cast) {
-        throw new TypeError(`mysql has no array cast for ${typeof type === 'string' ? type : type.name} elements`);
+        throw new UqlUsageError(`mysql has no array cast for ${typeof type === 'string' ? type : type.name} elements`);
     }
     if (cast !== 'CHAR' && cast !== 'BINARY') {
         return cast;
     }
     if (!json.length) {
-        throw new TypeError(`a multi-valued index over ${cast === 'CHAR' ? 'string' : 'binary'} elements needs a length`);
+        throw new UqlUsageError(`a multi-valued index over ${cast === 'CHAR' ? 'string' : 'binary'} elements needs a length`);
     }
     return `${cast}(${json.length})`;
 }

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

@@ -10,7 +10,8 @@ export declare class PgIndexDdl extends IndexDdl {
     protected indexAccessMethod(index: IndexSchema): string;
     /**
      * A vector index's operator class, `{type}_{metric}_ops` (`halfvec_cosine_ops`), refusing a metric it
-     * lacks rather than build with the default; any other entry takes the class it declares.
+     * lacks rather than build with the default; any other entry takes the class it declares. Stated even
+     * for the default distance: pgvector's own default class is L2, which a cosine search never uses.
      */
     protected indexColumnOpsClass(entry: IndexColumnSchema, index: IndexSchema): string;
     protected indexInclude(index: IndexSchema): string;

package/dist/migrate/ddl/pgIndexDdl.js

@@ -1,4 +1,5 @@
-import { unsupportedVectorMetric } from '../../type/vector.js';
+import { indexDistance, unsupportedVectorMetric } from '../../type/vector.js';
+import { UqlUsageError } from '../../util/uqlError.js';
 import { IndexDdl } from './indexDdl.js';
 /** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
 export class PgIndexDdl extends IndexDdl {
@@ -33,21 +34,23 @@ export class PgIndexDdl extends IndexDdl {
     }
     /**
      * A vector index's operator class, `{type}_{metric}_ops` (`halfvec_cosine_ops`), refusing a metric it
-     * lacks rather than build with the default; any other entry takes the class it declares.
+     * lacks rather than build with the default; any other entry takes the class it declares. Stated even
+     * for the default distance: pgvector's own default class is L2, which a cosine search never uses.
      */
     indexColumnOpsClass(entry, index) {
-        if (!this.isVectorIndex(index) || !index.distance) {
+        if (!this.isVectorIndex(index)) {
             return entry.opsClass ? ` ${entry.opsClass}` : '';
         }
-        const metric = this.dialect.vectorMetrics.get(index.distance)?.index;
+        const distance = indexDistance(index);
+        const metric = this.dialect.vectorMetrics.get(distance)?.index;
         if (!metric) {
-            throw unsupportedVectorMetric(this.dialect.dialectName, index.distance, index.name);
+            throw unsupportedVectorMetric(this.dialect.dialectName, distance, index.name);
         }
         const vectorType = this.dialect.supportedVectorType(index.vectorType ?? 'vector');
         const opsClass = `${vectorType}_${metric}_ops`;
         // IVFFlat has neither a sparsevec nor an L1 operator class; HNSW has all of them (pgvector 0.8.2).
-        if (index.type === 'ivfflat' && (vectorType === 'sparsevec' || index.distance === 'l1')) {
-            throw new TypeError(`ivfflat has no ${opsClass} operator class (index "${index.name}"); use hnsw`);
+        if (index.type === 'ivfflat' && (vectorType === 'sparsevec' || distance === 'l1')) {
+            throw new UqlUsageError(`ivfflat has no ${opsClass} operator class (index "${index.name}"); use hnsw`);
         }
         return ` ${opsClass}`;
     }

package/dist/migrate/ddl/sqliteIndexDdl.js

@@ -1,4 +1,5 @@
 import { indexDistance, isVectorIndexType, unsupportedVectorMetric } from '../../type/vector.js';
+import { UqlUsageError } from '../../util/uqlError.js';
 import { IndexDdl } from './indexDdl.js';
 /**
  * SQLite's `CREATE INDEX`, which names no index type. A vector index is libSQL's DiskANN where the dialect
@@ -31,7 +32,7 @@ export class SqliteIndexDdl extends IndexDdl {
         }
         // Its tables are named after the index, unquoted: any other name fails with "unable to initialize diskann".
         if (!/^\w+$/.test(index.name) || index.entries.length !== 1) {
-            throw new TypeError(`libSQL names a vector index only by letters, digits and underscores, over one column (index "${index.name}")`);
+            throw new UqlUsageError(`libSQL names a vector index only by letters, digits and underscores, over one column (index "${index.name}")`);
         }
         return metric;
     }

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

@@ -18,9 +18,10 @@ export declare class TableDdl {
     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.
+     * `MODIFY COLUMN` restates; Postgres takes each change as a clause of its own, so given what the
+     * column was (`from`), only the clauses that changed.
      */
-    alterColumn(table: string, column: ColumnSchema, definition: string): string[];
+    alterColumn(table: string, column: ColumnSchema, definition: string, from?: ColumnSchema): 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. */

package/dist/migrate/ddl/tableDdl.js

@@ -1,4 +1,5 @@
-import { formatDefaultValue } from '../builder/expressions.js';
+import { UqlUsageError } from '../../util/uqlError.js';
+import { formatDefaultValue, sameDefault } 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.
@@ -34,11 +35,12 @@ export class TableDdl {
     }
     /**
      * 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.
+     * `MODIFY COLUMN` restates; Postgres takes each change as a clause of its own, so given what the
+     * column was (`from`), only the clauses that changed.
      */
-    alterColumn(table, column, definition) {
+    alterColumn(table, column, definition, from) {
         if (this.dialect.alterColumnSyntax === 'none') {
-            throw new TypeError(`${this.dialect}: Cannot alter column "${column.name}" - you must recreate the table. ` +
+            throw new UqlUsageError(`${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);
@@ -47,10 +49,11 @@ export class TableDdl {
         }
         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)};`,
-        ];
+            (!from || from.type !== column.type) && `${alter} TYPE ${column.type};`,
+            (!from || from.nullable !== column.nullable) && `${alter} ${column.nullable ? 'DROP NOT NULL' : 'SET NOT NULL'};`,
+            (!from || !sameDefault(column.defaultValue, from.defaultValue, this.dialect)) &&
+                (column.defaultValue === undefined ? `${alter} DROP DEFAULT;` : `${alter} SET${this.defaultClause(column)};`),
+        ].filter((statement) => statement !== false);
     }
     renameColumn(table, oldName, newName) {
         const [target, from, to] = [table, oldName, newName].map((name) => this.dialect.escapeId(name));

package/dist/migrate/drift/driftDetector.d.ts

@@ -5,7 +5,6 @@
  * actual database schema.
  */
 import type { AbstractDialect } from '../../dialect/abstractDialect.js';
-import type { IndexFacet } from '../../schema/indexDifferences.js';
 import type { SchemaAST } from '../../schema/schemaAST.js';
 import type { DriftReport } from '../../schema/types.js';
 /**
@@ -18,15 +17,15 @@ export interface DriftDetectorOptions {
     checkNullable?: boolean;
     /** Include index differences */
     checkIndexes?: boolean;
-    /** `indexFacets` of the introspector that produced the actual schema; anything else goes uncompared. */
-    indexFacets?: ReadonlySet<IndexFacet>;
     /** Include foreign key differences */
     checkForeignKeys?: boolean;
     /**
-     * Include default value differences. Off by default: an engine reports a default as it stored it
-     * (`now()`, `CURRENT_TIMESTAMP`, `'active'::text`), which rarely matches the entity's literal.
+     * Include default value differences. Off unless {@link defaultsEqual} is given: without it defaults
+     * compare as written, and an engine reports one as it stored it (`now()`, `'active'::text`).
      */
     checkDefaults?: boolean;
+    /** How the engine's generator compares a default, so drift reports the ones a migration would change. */
+    defaultsEqual?: (expected: unknown, actual: unknown) => boolean;
     /**
      * Tables to leave out of the comparison. The migrations bookkeeping table belongs here - it exists in
      * the database by design and has no entity, so reporting it as unexpected told every project to