uql-orm 0.79.0 → 0.81.0

package/dist/dialect/operators.js

@@ -0,0 +1,129 @@
+import { VECTOR_QUERY_KEYS, } from '../type/index.js';
+import { isOperatorMap } from '../util/dialect.util.js';
+import { kindOf, UqlUsageError } from '../util/uqlError.js';
+/**
+ * How each grouping operator renders: the operator joining its clauses, and whether the group is
+ * negated (`$not` is `NOT (a AND b)`). Total over {@link QueryGroupOp}.
+ */
+export const GROUP_OPS = {
+    $and: { join: '$and', negate: false },
+    $or: { join: '$or', negate: false },
+    $not: { join: '$and', negate: true },
+    $nor: { join: '$or', negate: true },
+};
+/** Whether a `$where` key groups clauses, narrowing it for the renderers that read {@link GROUP_OPS}. */
+export function isGroupOp(key) {
+    return Object.hasOwn(GROUP_OPS, key);
+}
+/**
+ * A group operator's clauses, rejecting what the types do not cover: `/http` casts client JSON
+ * straight to `Query`, so a scalar can arrive where an array belongs. Shared so both backends
+ * refuse the same payload rather than one throwing and the other failing further in.
+ */
+export function groupClauses(key, val) {
+    if (val !== undefined && !Array.isArray(val)) {
+        throw new UqlUsageError(`${key} expects an array, got ${kindOf(val)}`);
+    }
+    return val ?? [];
+}
+/**
+ * A WHERE value as the operators it applies: an array is `$in`, an operator map its own entries, and
+ * anything else `$eq`. Each key is checked here, once, refused as `refusal` where it is no operator.
+ */
+export function whereOperators(val, refusal) {
+    const ops = Array.isArray(val) ? { $in: val } : isOperatorMap(val) ? val : { $eq: val };
+    return Object.entries(ops).map(([op, value]) => {
+        if (!isFieldOp(op)) {
+            throw new UqlUsageError(`${refusal}: ${op}`);
+        }
+        return [op, value];
+    });
+}
+/** An `$in`/`$nin` operand, which the types require to be an array but `/http` hands over untyped. */
+export function inOperands(op, value) {
+    if (!Array.isArray(value)) {
+        throw new UqlUsageError(`${op} expects an array, got ${kindOf(value)}`);
+    }
+    return value;
+}
+/** A `$between`'s two bounds, which `/http` hands over untyped too; one missing would bind `undefined`. */
+export function betweenBounds(value) {
+    if (!Array.isArray(value) || value.length !== 2) {
+        const got = Array.isArray(value) ? `${value.length} values` : kindOf(value);
+        throw new UqlUsageError(`$between expects [min, max], got ${got}`);
+    }
+    const [min, max] = value;
+    return [min, max];
+}
+/**
+ * Every field operator as data, which is what checks a key `/http` hands over; `satisfies` fails the
+ * build on one {@link QueryWhereFieldOp} gains and this misses.
+ */
+const FIELD_OPS = {
+    $eq: true,
+    $ne: true,
+    $not: true,
+    $lt: true,
+    $lte: true,
+    $gt: true,
+    $gte: true,
+    $between: true,
+    $startsWith: true,
+    $istartsWith: true,
+    $endsWith: true,
+    $iendsWith: true,
+    $includes: true,
+    $iincludes: true,
+    $like: true,
+    $ilike: true,
+    $regex: true,
+    $in: true,
+    $nin: true,
+    $isNull: true,
+    $isNotNull: true,
+    $all: true,
+    $size: true,
+    $elemMatch: true,
+    $near: true,
+};
+function isFieldOp(op) {
+    return Object.hasOwn(FIELD_OPS, op);
+}
+/** Whether a `$near` names the vector it measures from, which its type requires and `/http` does not. */
+export function isVectorQuery(near) {
+    return Boolean(near['$vector']);
+}
+export const COMPARE_OPS = new Map([
+    ['$gt', ' > '],
+    ['$gte', ' >= '],
+    ['$lt', ' < '],
+    ['$lte', ' <= '],
+]);
+/**
+ * The ordered comparisons, `QueryOrderedOp` at runtime, derived from {@link COMPARE_OPS} rather than spelled
+ * again: {@link QueryVectorNear}'s bounds, so `$near` never accepts one the renderer has no operator
+ * for, and the operators that read a JSON path as a number.
+ */
+export const ORDERED_OPS = new Set([...COMPARE_OPS.keys(), '$between']);
+export function isOrderedOp(op) {
+    return ORDERED_OPS.has(op);
+}
+/** The operators an equality compares by value, which a JSON path reads the way that value compares. */
+export const EQUALITY_OPS = new Set(['$eq', '$ne', '$in', '$nin']);
+/**
+ * Every `$like`-family operator: the pattern it wraps its value in, and whether it ignores case.
+ * Each case-sensitive operator is paired here with the `$i` twin that shares its pattern, so the
+ * two can never drift apart - and neither one decides case folding, which is
+ * `AbstractSqlDialect.caseInsensitiveMatch`'s single call.
+ */
+export const LIKE_OPS = new Map([
+    ['$like', '$ilike', (v) => v],
+    ['$startsWith', '$istartsWith', (v) => `${v}%`],
+    ['$endsWith', '$iendsWith', (v) => `%${v}`],
+    ['$includes', '$iincludes', (v) => `%${v}%`],
+].flatMap(([sensitive, insensitive, pattern]) => [
+    [sensitive, { pattern, insensitive: false }],
+    [insensitive, { pattern, insensitive: true }],
+]));
+/** What a `$near` says about the search itself; everything else in it is a bound. */
+export const VECTOR_QUERY_KEY_SET = new Set(VECTOR_QUERY_KEYS);

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,4 +1,5 @@
 import type { IndexType } from '../schema/types.js';
+import type { SqlDialectName } from '../type/index.js';
 import { type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QueryTextSearchOptions, type SqlDialectFeatures, type VectorDistance, type VectorMetric } from '../type/index.js';
 import type { DialectOptions } from './abstractDialect.js';
 import { AbstractSqlDialect, type RelationRows } from './abstractSqlDialect.js';
@@ -13,6 +14,8 @@ export declare const PG_VECTOR_METRICS: ReadonlyMap<VectorDistance, VectorMetric
 export declare const PG_FEATURES: SqlDialectFeatures;
 /** What Postgres and CockroachDB share: JSONB, full-text search, pgvector's operators, and the upsert. */
 export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
+    /** Every member of this family runs the same SQL, so a body written once serves them all. */
+    get dialectFamily(): SqlDialectName;
     /** How the driver binds a parameter: node-`pg`'s, unless the pool states its own. */
     readonly driverCapabilities: DriverCapabilities;
     constructor(options?: PgLikeDialectOptions);
@@ -96,7 +99,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     jsonPathExpr(escapedColumn: string, path: string, mode: JsonAccessMode): string;
     protected get regexpOp(): string;
     protected readonly caseInsensitiveMatch = "ilike";
-    protected get neOp(): string;
+    neExpr(field: string, ph: string): string;
     /**
      * One array parameter, which a context that inlines values has none of: it lists them instead. The
      * array takes its type from `operand`, so it needs none of the casts `bind` would give each value.

package/dist/dialect/pgLikeSqlDialect.js

@@ -17,7 +17,6 @@ export const PG_VECTOR_METRICS = new Map([
 const HNSW_EF_SEARCH = 'hnsw.ef_search';
 /** What the Postgres-wire engines have. */
 export const PG_FEATURES = {
-    ifNotExists: true,
     indexIfNotExists: true,
     schemas: true,
     dropTableCascade: true,
@@ -41,9 +40,23 @@ export const PG_FEATURES = {
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: true,
     serialDeclaresPrimaryKey: false,
+    triggers: {
+        preamble: '',
+        assignsRow: true,
+        body: 'function',
+        guards: 'clause',
+        layout: 'timingFirst',
+        rows: 'row',
+        scope: 'table',
+        before: true,
+    },
 };
 /** What Postgres and CockroachDB share: JSONB, full-text search, pgvector's operators, and the upsert. */
 export class PgLikeSqlDialect extends AbstractSqlDialect {
+    /** Every member of this family runs the same SQL, so a body written once serves them all. */
+    get dialectFamily() {
+        return 'postgres';
+    }
     /** How the driver binds a parameter: node-`pg`'s, unless the pool states its own. */
     driverCapabilities;
     constructor(options = {}) {
@@ -213,8 +226,8 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         return '~';
     }
     caseInsensitiveMatch = 'ilike';
-    get neOp() {
-        return 'IS DISTINCT FROM';
+    neExpr(field, ph) {
+        return `${field} IS DISTINCT FROM ${ph}`;
     }
     /**
      * One array parameter, which a context that inlines values has none of: it lists them instead. The

package/dist/dialect/vectorSqlDialect.d.ts

@@ -30,6 +30,8 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
     /** Whether this engine has a vector index: the one a metric's `index` names. */
     hasVectorIndex(): boolean;
+    /** The distance a vector index built for `metric`, as {@link vectorMetrics} names it for an index, measures. */
+    indexedDistance(metric: string | undefined): VectorDistance | undefined;
     /** Quotes an identifier; supplied by the SQL dialect built on top of this layer. */
     abstract escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
     /** What a distance expression reads, for a `$sort` and a `$near` alike. */

package/dist/dialect/vectorSqlDialect.js

@@ -45,6 +45,10 @@ export class VectorSqlDialect extends AbstractDialect {
     hasVectorIndex() {
         return [...this.vectorMetrics.values()].some((metric) => metric.index);
     }
+    /** The distance a vector index built for `metric`, as {@link vectorMetrics} names it for an index, measures. */
+    indexedDistance(metric) {
+        return [...this.vectorMetrics].find(([, { index }]) => index === metric)?.[0];
+    }
     /** What a distance expression reads, for a `$sort` and a `$near` alike. */
     resolveVectorDistance(meta, key, search) {
         const field = meta.fields[key];

package/dist/entity/decorator/entity.d.ts

@@ -1,4 +1,4 @@
-import type { EntityIndexColumnInput, EntityIndexOptions, EntityOptions, FilterName, FilterOptions, RefMap, Type } from '../../type/index.js';
+import type { EntityIndexColumnInput, EntityIndexOptions, EntityOptions, FilterName, FilterOptions, RefMap, TriggerOptions, Type } from '../../type/index.js';
 /**
  * Marks a class as an entity and finalizes its metadata, draining `context.metadata`: the class gets
  * `Symbol.metadata` only after its decorators return.
@@ -16,3 +16,8 @@ export declare function Filter<E, N extends string>(name: FilterName<N>, opts: F
  * @example `@Index((user) => [user.lastName, raw`lower(${user.email})`], { unique: true })`
  */
 export declare function Index<E>(columns: (refs: RefMap<E>) => readonly EntityIndexColumnInput<E>[], options?: EntityIndexOptions<E>): (entity: Type<E>) => void;
+/**
+ * Declares triggers the database runs, in the order written. Stacks, so several may sit above one class.
+ * @example ``@Trigger({ on: 'beforeUpdate', of: (post) => [post.body], run: (newRow) => raw`...` })``
+ */
+export declare function Trigger<E>(...triggers: readonly TriggerOptions<E>[]): (entity: Type<E>) => void;

package/dist/entity/decorator/entity.js

@@ -1,4 +1,4 @@
-import { applyMembers, defineEntity, defineFilter, defineIndex } from '../metadata/definition.js';
+import { applyMembers, defineEntity, defineFilter, defineIndex, defineTrigger } from '../metadata/definition.js';
 import { drainRegistrations } from './bag.js';
 // The class-level decorators. Unlike the member ones they receive the class, so each is a direct call
 // into the registry with no bag in between.
@@ -32,3 +32,14 @@ export function Index(columns, options = {}) {
         defineIndex(entity, { ...options, columns });
     };
 }
+/**
+ * Declares triggers the database runs, in the order written. Stacks, so several may sit above one class.
+ * @example ``@Trigger({ on: 'beforeUpdate', of: (post) => [post.body], run: (newRow) => raw`...` })``
+ */
+export function Trigger(...triggers) {
+    return (entity) => {
+        for (const trigger of triggers) {
+            defineTrigger(entity, trigger);
+        }
+    };
+}

package/dist/entity/index.d.ts

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, defineTrigger, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';

package/dist/entity/index.js

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, defineTrigger, getEntities, getMeta, removeEntity, assertSoleId, fieldOf, idOf, namesKey, relationOf, soleIdOf, } from './metadata/definition.js';

package/dist/entity/metadata/definition.d.ts

@@ -1,4 +1,4 @@
-import type { EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldMeta, FieldOptions, FilterName, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, RelationRegistration, Type, WrittenId } from '../../type/index.js';
+import type { EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldMeta, FieldOptions, FilterName, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, RelationRegistration, TriggerOptions, Type, WrittenId } from '../../type/index.js';
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
 /** `T` is the relation's target, independent of the owner `E`. */
@@ -15,6 +15,11 @@ export declare function defineHook<E>(entity: Type<E>, methodName: string, event
  * sugar are normalized here, which is what lets the dialects render one shape instead of re-parsing it.
  */
 export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexInput<E>): EntityMeta<E>;
+/**
+ * Registers a trigger, its watched columns read off the entity's refs so a rename reaches them and a
+ * column the entity has not got does not compile. Appended, since triggers fire in the order written.
+ */
+export declare function defineTrigger<E>(entity: Type<E>, trigger: TriggerOptions<E>): EntityMeta<E>;
 export declare function defineFilter<E, N extends string>(entity: Type<E>, name: FilterName<N>, opts: FilterOptions<E>): EntityMeta<E>;
 /**
  * Feeds fields, relations and hooks into the `define*` primitives, so the decorators and the imperative

package/dist/entity/metadata/definition.js

@@ -112,6 +112,22 @@ export function defineIndex(entity, index) {
     });
     return meta;
 }
+/**
+ * Registers a trigger, its watched columns read off the entity's refs so a rename reaches them and a
+ * column the entity has not got does not compile. Appended, since triggers fire in the order written.
+ */
+export function defineTrigger(entity, trigger) {
+    const meta = ensureWritableMeta(entity);
+    // The type already refuses an empty map; this is the same answer for plain JavaScript.
+    if (typeof trigger.run !== 'function' && !hasKeys(trigger.run)) {
+        throw new TypeError(`'${entity.name}' has a trigger whose body names at least one engine to run on`);
+    }
+    if (trigger.name && meta.triggers?.some((it) => it.name === trigger.name)) {
+        throw new TypeError(`'${entity.name}' already has a trigger named '${trigger.name}'`);
+    }
+    (meta.triggers ??= []).push({ ...trigger, of: trigger.of?.(memberRefs()).map((ref) => ref.key) });
+    return meta;
+}
 export function defineFilter(entity, name, opts) {
     const meta = ensureWritableMeta(entity);
     if (name === SOFT_DELETE_FILTER) {
@@ -178,6 +194,9 @@ export function defineEntity(entity, opts = {}) {
     for (const index of opts.indexes ?? []) {
         defineIndex(entity, index);
     }
+    for (const trigger of opts.triggers ?? []) {
+        defineTrigger(entity, trigger);
+    }
     for (const [name, filter] of definedEntries(opts.filters ?? {})) {
         defineFilter(entity, name, filter);
     }

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

@@ -83,6 +83,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`

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/entityTypes.js

@@ -1,6 +1,5 @@
 import { getMeta } from '../../entity/index.js';
-import { canonicalToTypeScript } from '../../schema/canonicalType.js';
-import { resolveColumnCanonicalType } from '../../schema/schemaASTBuilder.js';
+import { canonicalToTypeScript, resolveColumnCanonicalType } from '../../schema/canonicalType.js';
 import { isToManyRelation, upperFirst } from '../../util/index.js';
 import { isIdentifierName } from './sourceLiteral.js';
 /**

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/mssqlIndexDdl.d.ts

@@ -1,3 +1,4 @@
+import type { IndexSchema } from '../../type/index.js';
 import { IndexDdl } from './indexDdl.js';
 /**
  * SQL Server's `CREATE INDEX` is the portable form minus what 2025 rejects: an expression (Msg 16216),
@@ -7,4 +8,8 @@ import { IndexDdl } from './indexDdl.js';
 export declare class MsSqlIndexDdl extends IndexDdl {
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
     protected readonly indexTypes: Set<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch">;
+    /** T-SQL has no `IF NOT EXISTS` on an index, so the create is guarded by a lookup in the same statement. */
+    getCreateIndexStatement(tableName: string, index: IndexSchema, opts?: {
+        ifNotExists?: boolean;
+    }): string;
 }

package/dist/migrate/ddl/mssqlIndexDdl.js

@@ -7,4 +7,14 @@ import { IndexDdl } from './indexDdl.js';
 export class MsSqlIndexDdl extends IndexDdl {
     indexFeatures = new Set(['partial']);
     indexTypes = new Set(['btree']);
+    /** T-SQL has no `IF NOT EXISTS` on an index, so the create is guarded by a lookup in the same statement. */
+    getCreateIndexStatement(tableName, index, opts = {}) {
+        const create = super.getCreateIndexStatement(tableName, index, { ifNotExists: false });
+        if (!(opts.ifNotExists ?? this.dialect.features.indexIfNotExists)) {
+            return create;
+        }
+        const table = this.dialect.escape(this.dialect.escapeId(tableName));
+        const name = this.dialect.escape(index.name);
+        return `IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = ${name} AND object_id = OBJECT_ID(${table})) ${create}`;
+    }
 }

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

@@ -2,13 +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
@@ -19,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,28 +1,37 @@
 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. */
+    createTable(target, ifNotExists) {
+        const guard = ifNotExists ? `IF OBJECT_ID(${this.dialect.escape(target)}, N'U') IS NULL ` : '';
+        return `${guard}${super.createTable(target, false)}`;
+    }
     /** 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. */
+    /** 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
@@ -32,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) {
@@ -51,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,5 @@
 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 { IndexDdl } from './indexDdl.js';
 /**
  * A full-text index is its own keyword here (`CREATE FULLTEXT INDEX ... (cols)`); `USING fulltext` is
@@ -84,15 +84,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}`;
         }