uql-orm 0.80.0 → 0.81.0

package/dist/migrate/schemaGenerator.js

@@ -5,13 +5,14 @@ import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
 import { diffRelationshipNodes, diffTable } from '../schema/schemaASTDiffer.js';
 import { isAutoIncrement, qualifyName } from '../util/index.js';
 import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName, isOwnedName } from '../util/sql.util.js';
-import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
+import { sameDefault } from './builder/expressions.js';
 import { splitSqlStatements } from './builder/splitSqlStatements.js';
 import { indexDdlFor, tableDdlFor } from './ddl/index.js';
 import { sizedType } from './ddl/tableDdl.js';
 import { columnForeignKey, columnIndex, fullColumnDefinitionToNode, renderIndexDefinition, tableDefinitionToNode, } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 import { assertIndexPredicate } from './indexPredicate.js';
+import { added, alterations, dropped, nonEmpty, sides } from './schemaChange.js';
 import { dropTrigger, renderTrigger, stampTriggers } from './triggerSql.js';
 /**
  * Unified SQL schema generator.
@@ -78,6 +79,7 @@ export class SqlSchemaGenerator {
         return buildEntityAST(this, entities, {
             defaultForeignKeyAction: this.defaultForeignKeyAction,
             textScoreIndexes: this.dialect.features.textScoreIndexes,
+            vectorIndexRequiresNotNull: this.features.vectorIndexRequiresNotNull,
         });
     }
     /**
@@ -173,97 +175,45 @@ export class SqlSchemaGenerator {
         const cascade = options.cascade && this.features.dropTableCascade ? ' CASCADE' : '';
         return `DROP TABLE ${ifExists}${this.escapeId(tableName)}${cascade};`;
     }
+    /**
+     * The statements taking a table through `diff`, in the one order both directions need: whatever holds
+     * something down goes before it and comes back after it. A foreign key holds its columns and the key it
+     * points at, so it goes first and comes back last; the key holds its columns; and some engines drop an
+     * index along with its column, which would leave nothing to name. An alter is its drop, then its add.
+     */
     generateAlterTable(diff) {
-        const statements = [];
-        // Before the columns, because a key column being added cannot be part of the old key, and after
-        // it is dropped the table is free to take the new one below.
-        if (diff.primaryKey?.from.length) {
-            statements.push(this.generateDropPrimaryKeySql(diff.tableName, diff.primaryKey.fromName));
-        }
-        // Before the columns: a constraint holds its columns down, so one the entity dropped cannot go
-        // while a foreign key still names it. An alter is a drop and an add, and this is its drop half.
-        statements.push(...this.dropForeignKeyStatements(diff.tableName, [
-            ...(diff.foreignKeysToDrop ?? []),
-            ...(diff.foreignKeysToAlter ?? []).map((it) => constraintNameOf(diff.tableName, it.from)),
-        ]));
-        // Before the adds, which may reuse a dropped index's name, and before the columns: some engines
-        // drop an index along with its column, which would leave nothing here to name.
-        statements.push(...this.dropIndexStatements(diff.tableName, diff.indexesToDrop, diff.schema));
-        for (const column of diff.columnsToAdd ?? []) {
-            this.assertColumnAddable(diff.tableName, column);
-            statements.push(this.tableDdl.addColumn(diff.tableName, this.generateColumnDefinitionFromSchema(column)));
-            statements.push(...this.generateColumnCommentStatement(diff.tableName, column, diff.schema));
-        }
-        statements.push(...this.alterColumnStatements(diff.tableName, (diff.columnsToAlter ?? []).map((it) => it.to)));
-        for (const columnName of diff.columnsToDrop ?? []) {
-            statements.push(...this.tableDdl.dropColumn(diff.tableName, columnName));
-        }
-        statements.push(...this.addIndexStatements(diff.tableName, diff.indexesToAdd));
-        // Last, so every column it names exists by now.
-        if (diff.primaryKey?.to.length) {
-            statements.push(this.generateAddPrimaryKeySql(diff.tableName, diff.primaryKey.to));
-        }
-        // After the columns, for the same reason the key is: a constraint cannot name one that is not
-        // there yet. The add half of an alter rides along, its drop having gone out above.
-        statements.push(...this.addForeignKeyStatements(diff.tableName, [
-            ...(diff.foreignKeysToAdd ?? []),
-            ...(diff.foreignKeysToAlter ?? []).map((it) => it.to),
-        ]));
-        return statements;
+        const { tableName, schema, primaryKey } = diff;
+        const { columns } = diff;
+        return [
+            ...sides(diff.foreignKeys, 'from').map((foreignKey) => this.generateDropForeignKeySql(tableName, constraintNameOf(tableName, foreignKey))),
+            ...(primaryKey?.from ? [this.generateDropPrimaryKeySql(tableName, primaryKey.from.name)] : []),
+            ...sides(diff.indexes, 'from').map((index) => this.generateDropIndex(tableName, index.name, schema)),
+            ...added(columns).flatMap((column) => this.addColumnStatements(tableName, column, schema)),
+            ...alterations(columns).flatMap(({ from, to }) => this.tableDdl.alterColumn(tableName, to, this.generateColumnDefinitionFromSchema(to), from)),
+            ...dropped(columns).flatMap((column) => this.tableDdl.dropColumn(tableName, column.name)),
+            ...this.addIndexStatements(tableName, sides(diff.indexes, 'to')),
+            ...(primaryKey?.to ? [this.generateAddPrimaryKeySql(tableName, primaryKey.to.columns, primaryKey.to.name)] : []),
+            ...this.addForeignKeyStatements(tableName, sides(diff.foreignKeys, 'to')),
+        ];
     }
     /** `ADD CONSTRAINT` for each of `foreignKeys`. */
     addForeignKeyStatements(tableName, foreignKeys) {
         return foreignKeys.map((foreignKey) => this.generateAddForeignKeySql(tableName, foreignKey));
     }
-    /** `DROP CONSTRAINT` for each of `constraintNames`, the mirror of {@link addForeignKeyStatements}. */
-    dropForeignKeyStatements(tableName, constraintNames) {
-        return constraintNames.map((name) => this.generateDropForeignKeySql(tableName, name));
-    }
-    /** The `ALTER COLUMN` restating each of `columns`. */
-    alterColumnStatements(tableName, columns) {
-        return columns.flatMap((column) => this.generateAlterColumnStatements(tableName, column, this.generateColumnDefinitionFromSchema(column)));
-    }
     /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
-    addIndexStatements(tableName, indexes = []) {
+    addIndexStatements(tableName, indexes) {
         return indexes.flatMap((index) => [
             this.generateCreateIndex(tableName, index),
             ...this.indexDdl.settleStatements(tableName, index),
         ]);
     }
-    /** `DROP INDEX` for each of `indexes`, the mirror of {@link addIndexStatements}. */
-    dropIndexStatements(tableName, indexes = [], schema) {
-        return indexes.map((index) => this.generateDropIndex(tableName, index.name, schema));
-    }
-    generateAlterTableDown(diff) {
-        const statements = [];
-        // Constraints first, mirroring the up direction: the up added them last, so the down drops them
-        // first, and a column it is about to drop is then free of anything naming it.
-        statements.push(...this.dropForeignKeyStatements(diff.tableName, [
-            ...(diff.foreignKeysToAdd ?? []).map((it) => constraintNameOf(diff.tableName, it)),
-            ...(diff.foreignKeysToAlter ?? []).map((it) => constraintNameOf(diff.tableName, it.to)),
-        ]));
-        // The key next, for the same reason: a column the up added cannot be dropped below while the new
-        // key still names it. Restored under the name the database gave it, which is what the table had
-        // before, rather than a derived one that was never on it.
-        if (diff.primaryKey?.to.length) {
-            statements.push(this.generateDropPrimaryKeySql(diff.tableName, derivedPrimaryKeyName(diff.tableName, diff.primaryKey.to)));
-        }
-        for (const column of diff.columnsToAdd ?? []) {
-            statements.push(...this.tableDdl.dropColumn(diff.tableName, column.name));
-        }
-        statements.push(...this.alterColumnStatements(diff.tableName, (diff.columnsToAlter ?? []).map((it) => it.from)));
-        statements.push(...this.dropIndexStatements(diff.tableName, diff.indexesToAdd, diff.schema));
-        statements.push(...this.addIndexStatements(diff.tableName, diff.indexesToDrop));
-        if (diff.primaryKey?.from.length) {
-            statements.push(this.generateAddPrimaryKeySql(diff.tableName, diff.primaryKey.from, diff.primaryKey.fromName));
-        }
-        // The constraint the up replaced, back under the name the database had for it. A foreign key the
-        // up *dropped* is not restored: only its name survived the diff, never what it pointed at.
-        statements.push(...this.addForeignKeyStatements(diff.tableName, (diff.foreignKeysToAlter ?? []).map((it) => it.from)));
-        if (diff.columnsToDrop?.length || diff.foreignKeysToDrop?.length) {
-            statements.push(`-- TODO: Manual reversal needed for dropped columns/foreign keys`);
-        }
-        return statements;
+    /** A column added to a table that exists, and its comment where the engine keeps one apart. */
+    addColumnStatements(tableName, column, schema) {
+        this.assertColumnAddable(tableName, column);
+        return [
+            this.tableDdl.addColumn(tableName, this.generateColumnDefinitionFromSchema(column)),
+            ...this.generateColumnCommentStatement(tableName, column, schema),
+        ];
     }
     generateCreateIndex(tableName, index, options = {}) {
         return this.indexDdl.getCreateIndexStatement(tableName, index, options);
@@ -288,8 +238,8 @@ export class SqlSchemaGenerator {
     /**
      * 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.
+     * NULL otherwise, and SQL Server adds no key over a nullable column. Never `UNIQUE`: a unique column is
+     * a unique index, which the table creates beside it. An enum's `CHECK` comes last, the only place MariaDB takes it.
      */
     renderColumn(column) {
         const type = column.generatedAs
@@ -299,9 +249,6 @@ export class SqlSchemaGenerator {
         if (!column.nullable) {
             def += ' NOT NULL';
         }
-        if (column.isUnique && !column.isPrimaryKey) {
-            def += ' UNIQUE';
-        }
         def += this.tableDdl.defaultClause(column);
         if (column.comment) {
             def += this.generateColumnComment(column.comment);
@@ -367,72 +314,61 @@ export class SqlSchemaGenerator {
         if (!desired) {
             return undefined;
         }
-        // Indexes are matched here rather than by the differ, which pairs them by name so that a changed
-        // one reads as one index that altered. A migration needs the opposite: an index already in the
-        // table, under whatever name, must not be created again, and one whose shape differs is dropped
-        // and created anew - no engine alters an index's columns or uniqueness.
         const tableDiff = diffTable(desired, currentTable, { ...this.diffOptions(), compareIndexes: false });
-        const indexes = indexChanges(currentTable.name, desired.indexes, currentTable.indexes);
-        const indexesToAdd = indexes.toAdd.map(indexNodeToSchema);
-        const indexesToDrop = indexes.toDrop.map(indexNodeToSchema);
-        const columnDiffs = tableDiff?.columnDiffs ?? [];
-        const columnsToAdd = columnDiffs.flatMap((it) => (it.type === 'add' ? [this.columnNodeToSchema(it.expected)] : []));
-        const columnsToDrop = columnDiffs.flatMap((it) => (it.type === 'drop' ? [it.column] : []));
-        // Without its values: an alter restates the whole column, and MySQL answers a restated `CHECK` by
-        // adding a *second* constraint rather than replacing the first, so the column would accumulate one
-        // per alter. An enum's values reach the database with the column and are never restated - which is
-        // also why changing them is a hand-written migration. See architecture/roadmap.md.
-        const columnsToAlter = columnDiffs.flatMap((it) => it.type === 'alter'
-            ? [
-                {
-                    from: this.columnNodeToSchema(it.actual),
-                    to: { ...this.columnNodeToSchema(it.expected), enum: undefined },
-                },
-            ]
-            : []);
-        const primaryKey = tableDiff?.primaryKeyDiff && {
-            from: tableDiff.primaryKeyDiff.actual,
-            to: tableDiff.primaryKeyDiff.expected,
-            fromName: tableDiff.primaryKeyDiff.actualName,
+        const indexes = indexChanges(currentTable.name, desired.indexes, currentTable.indexes, currentTable.indexFacets);
+        // An alter's `to` without its values: an alter restates the whole column, and MySQL answers a
+        // restated `CHECK` by adding a *second* constraint rather than replacing the first, so the column
+        // would accumulate one per alter. An enum's values reach the database with the column and are never
+        // restated - which is also why changing them is a hand-written migration. See architecture/roadmap.md.
+        const columns = (tableDiff?.columnDiffs ?? []).map((it) => {
+            if (it.type === 'add') {
+                return { to: this.columnNodeToSchema(it.expected) };
+            }
+            if (it.type === 'drop') {
+                return { from: this.columnNodeToSchema(it.actual) };
+            }
+            return {
+                from: this.columnNodeToSchema(it.actual),
+                to: { ...this.columnNodeToSchema(it.expected), enum: undefined },
+            };
+        });
+        const keyDiff = tableDiff?.primaryKeyDiff;
+        // The key added named as this generator names it, so the rollback can drop it by that name.
+        const primaryKey = keyDiff && {
+            from: keyDiff.actual,
+            to: keyDiff.expected && {
+                columns: keyDiff.expected.columns,
+                name: derivedPrimaryKeyName(tableName, keyDiff.expected.columns),
+            },
         };
         // This table's own foreign keys. None where the engine cannot alter one (SQLite, short of rebuilding
         // the table), since a difference nothing can apply would throw on every sync; `drift:check` names it.
         const relationDiffs = this.features.foreignKeyAlter
             ? diffRelationshipNodes(desired.outgoingRelations, currentTable.outgoingRelations, this.diffOptions())
             : [];
-        const foreignKeysToAdd = relationDiffs.flatMap((it) => (it.type === 'create' ? [foreignKeyOf(it.expected)] : []));
-        const foreignKeysToDrop = relationDiffs.flatMap((it) => (it.type === 'drop' ? [it.name] : []));
-        const foreignKeysToAlter = relationDiffs.flatMap((it) => it.type === 'alter' ? [{ from: foreignKeyOf(it.actual), to: foreignKeyOf(it.expected) }] : []);
-        if (!columnsToAdd.length &&
-            !columnsToAlter.length &&
-            !columnsToDrop.length &&
-            !indexesToAdd.length &&
-            !indexesToDrop.length &&
-            !foreignKeysToAdd.length &&
-            !foreignKeysToDrop.length &&
-            !foreignKeysToAlter.length &&
-            !primaryKey) {
-            return undefined;
-        }
-        return {
+        const foreignKeys = relationDiffs.map(({ actual, expected }) => ({
+            from: actual && foreignKeyOf(actual),
+            to: expected && foreignKeyOf(expected),
+        }));
+        const alter = {
             tableName,
             schema,
             type: 'alter',
             primaryKey,
-            columnsToAdd: columnsToAdd.length ? columnsToAdd : undefined,
-            columnsToAlter: columnsToAlter.length ? columnsToAlter : undefined,
-            columnsToDrop: columnsToDrop.length ? columnsToDrop : undefined,
-            indexesToAdd: indexesToAdd.length ? indexesToAdd : undefined,
-            indexesToDrop: indexesToDrop.length ? indexesToDrop : undefined,
-            foreignKeysToAdd: foreignKeysToAdd.length ? foreignKeysToAdd : undefined,
-            foreignKeysToDrop: foreignKeysToDrop.length ? foreignKeysToDrop : undefined,
-            foreignKeysToAlter: foreignKeysToAlter.length ? foreignKeysToAlter : undefined,
+            columns: nonEmpty(columns),
+            indexes: nonEmpty([
+                ...indexes.toAdd.map((to) => ({ to: indexNodeToSchema(to) })),
+                ...indexes.toDrop.map((from) => ({ from: indexNodeToSchema(from) })),
+                ...indexes.toAlter.map(({ from, to }) => ({ from: indexNodeToSchema(from), to: indexNodeToSchema(to) })),
+            ]),
+            foreignKeys: nonEmpty(foreignKeys),
         };
+        return alter.primaryKey || alter.columns || alter.indexes || alter.foreignKeys ? alter : undefined;
     }
     diffOptions() {
         return {
             normalizeType: engineType(this.dialect),
-            defaultsEqual: (expected, actual) => this.isDefaultValueEqual(actual, expected),
+            defaultsEqual: this.defaultsEqual,
         };
     }
     /** Spread, not copied field by field, so a field the node gains cannot go missing here. */
@@ -440,58 +376,28 @@ export class SqlSchemaGenerator {
         const { table: _table, referencedBy: _referencedBy, references: _references, ...column } = col;
         return { ...column, type: this.columnSqlType(col) };
     }
-    /**
-     * Compare two default values for equality
-     */
-    isDefaultValueEqual(current, desired) {
-        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, this.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);
-    }
+    /** Whether a column's stored default is the one the entity declares, as this engine reprints it. */
+    defaultsEqual = (desired, current) => sameDefault(desired, current, this.dialect);
     generateCreateTableFromNode(table, options = {}) {
         const columns = [];
         const constraints = [];
-        // MariaDB rejects a `VECTOR INDEX` whose column is nullable ("All parts of a VECTOR index must
-        // be NOT NULL"), so being indexed decides it rather than the entity's own nullability.
-        const indexedVectorColumns = new Set(this.features.vectorIndexRequiresNotNull
-            ? table.indexes.filter((index) => index.type === 'vector').flatMap((idx) => idx.entries.map((e) => e.column))
-            : []);
         for (const col of table.columns.values()) {
-            const colDef = this.generateColumnFromNode(indexedVectorColumns.has(col.name) ? { ...col, nullable: false } : col);
-            columns.push(colDef);
+            columns.push(this.generateColumnFromNode(col));
         }
         // Every key, of any width, as one named constraint beside the checks and foreign keys - so a
         // later `DROP` has something to name. The exception is a dialect whose serial type states the key
         // itself (SQLite's `INTEGER PRIMARY KEY AUTOINCREMENT`, which cannot be split): there the column
         // has already declared it, and saying it again is a second primary key.
+        const key = table.primaryKey;
         const declaredByColumn = this.dialect.features.serialDeclaresPrimaryKey &&
-            table.primaryKey.length === 1 &&
-            table.primaryKey[0].isAutoIncrement;
-        if (table.primaryKey.length && !declaredByColumn) {
-            const pkColumns = table.primaryKey.map((c) => c.name);
-            const pkName = table.primaryKeyName ?? derivedPrimaryKeyName(table.name, pkColumns);
-            const pkCols = pkColumns.map((c) => this.escapeId(c)).join(', ');
-            constraints.push(`CONSTRAINT ${this.escapeId(pkName)} PRIMARY KEY (${pkCols})`);
-        }
-        (table.checks ?? []).forEach((check, i) => {
+            key?.columns.length === 1 &&
+            table.columns.get(key.columns[0])?.isAutoIncrement;
+        if (key && !declaredByColumn) {
+            const name = key.name ?? derivedPrimaryKeyName(table.name, key.columns);
+            const columns = key.columns.map((column) => this.escapeId(column)).join(', ');
+            constraints.push(`CONSTRAINT ${this.escapeId(name)} PRIMARY KEY (${columns})`);
+        }
+        table.checks.forEach((check, i) => {
             const name = check.name ?? derivedCheckName(table.name, i + 1);
             constraints.push(`CONSTRAINT ${this.escapeId(name)} CHECK (${check.expression})`);
         });

package/dist/schema/indexDifferences.d.ts

@@ -1,10 +1,12 @@
+import type { IndexSchema } from '../type/index.js';
 import type { IndexNode } from './types.js';
 /**
  * What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits.
- * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it.
+ * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it;
+ * `distance` is the metric a vector index was built for.
  * `textIndex` is a text index's weights and language, kept by an engine that lists its fields in no declared order.
  */
-export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'textIndex';
+export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'distance' | 'textIndex';
 type ComparableIndex = Pick<IndexNode, 'name' | 'entries' | 'unique'>;
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
@@ -17,16 +19,30 @@ export declare function indexSignature(index: ComparableIndex): string;
  */
 export declare function indexNameStem(name: string): string;
 /**
- * The indexes a table lacks and the ones it no longer needs, matched by `keyOf`. Only an index uql
- * named, or whose name the entity claims, is dropped: any other may have been made outside the ORM.
+ * Pairs by name, then what is left by shape: an index the database has under another name is still
+ * the one asked for. What stays unpaired is created or dropped.
  */
-export declare function indexChanges<I extends ComparableIndex>(table: string, declared: readonly I[], current: readonly IndexNode[], keyOf?: (index: ComparableIndex) => string): {
+export declare function pairIndexes<S extends ComparableIndex, T extends ComparableIndex>(source: readonly S[], target: readonly T[], normalizeName?: (name: string) => string): {
+    created: S[];
+    dropped: T[];
+    matched: (readonly [S, T])[];
+};
+/**
+ * The indexes a table lacks, the ones it no longer needs, and the ones to rebuild, differing in what
+ * `facets` let the engine report. Only an unpaired index uql named, or whose name the entity claims, is
+ * dropped: any other may have been made outside the ORM.
+ */
+export declare function indexChanges<I extends IndexSchema>(table: string, declared: readonly I[], current: readonly IndexNode[], facets: ReadonlySet<IndexFacet>): {
     toAdd: I[];
     toDrop: IndexNode[];
+    toAlter: {
+        from: IndexNode;
+        to: I;
+    }[];
 };
 /**
  * What two indexes differ by, comparing only what both sides state structurally: an expression, a JSON
  * path or a predicate is reprinted by the engine, so never compared.
  */
-export declare function describeIndexDifferences(source: IndexNode, target: IndexNode, facets: ReadonlySet<IndexFacet>): string[];
+export declare function describeIndexDifferences(source: IndexSchema, target: IndexSchema, facets: ReadonlySet<IndexFacet>): string[];
 export {};

package/dist/schema/indexDifferences.js

@@ -1,6 +1,7 @@
-import { isVectorIndexType } from '../type/vector.js';
+import { indexDistance, isVectorIndexType } from '../type/vector.js';
 import { fulltextConfig } from '../util/dialect.util.js';
 import { derivedIndexName } from '../util/sql.util.js';
+import { matchByKey } from './matchByKey.js';
 /** An entry the engine reprints in its own words, so never compared as written. */
 function isReprinted(entry) {
     return Boolean(entry.expression || entry.jsonPath || entry.jsonArray);
@@ -26,17 +27,27 @@ export function indexNameStem(name) {
     return bare.replace(/__/g, '_');
 }
 /**
- * The indexes a table lacks and the ones it no longer needs, matched by `keyOf`. Only an index uql
- * named, or whose name the entity claims, is dropped: any other may have been made outside the ORM.
+ * Pairs by name, then what is left by shape: an index the database has under another name is still
+ * the one asked for. What stays unpaired is created or dropped.
  */
-export function indexChanges(table, declared, current, keyOf = indexSignature) {
-    const present = new Set(current.map(keyOf));
-    const wanted = new Set(declared.map(keyOf));
+export function pairIndexes(source, target, normalizeName = (name) => name) {
+    const byName = matchByKey(source, target, (index) => normalizeName(indexNameStem(index.name)));
+    const byShape = matchByKey(byName.created, byName.dropped, indexSignature);
+    return { created: byShape.created, dropped: byShape.dropped, matched: [...byName.matched, ...byShape.matched] };
+}
+/**
+ * The indexes a table lacks, the ones it no longer needs, and the ones to rebuild, differing in what
+ * `facets` let the engine report. Only an unpaired index uql named, or whose name the entity claims, is
+ * dropped: any other may have been made outside the ORM.
+ */
+export function indexChanges(table, declared, current, facets) {
+    const { created, dropped, matched } = pairIndexes(declared, current);
     const claimed = new Set(declared.map((index) => index.name));
     const owned = (index) => claimed.has(index.name) || hasDerivedName(table, index);
     return {
-        toAdd: declared.filter((index) => !present.has(keyOf(index))),
-        toDrop: current.filter((index) => !wanted.has(keyOf(index)) && owned(index)),
+        toAdd: created,
+        toDrop: dropped.filter(owned),
+        toAlter: matched.flatMap(([to, from]) => (describeIndexDifferences(to, from, facets).length ? [{ from, to }] : [])),
     };
 }
 /**
@@ -85,6 +96,10 @@ export function describeIndexDifferences(source, target, facets) {
     if (facets.has('accessMethod') && (source.type ?? 'btree') !== (target.type ?? 'btree')) {
         differences.push(`type: ${target.type ?? 'btree'} -> ${source.type ?? 'btree'}`);
     }
+    const bothVector = isVectorIndexType(source.type) && isVectorIndexType(target.type);
+    if (facets.has('distance') && bothVector && indexDistance(source) !== indexDistance(target)) {
+        differences.push(`distance: ${indexDistance(target)} -> ${indexDistance(source)}`);
+    }
     if (facets.has('vector') && isVectorIndexType(source.type) !== isVectorIndexType(target.type)) {
         const [expected, actual] = [source, target].map((index) => (isVectorIndexType(index.type) ? 'yes' : 'no'));
         differences.push(`vector index: ${actual} -> ${expected}`);

package/dist/schema/matchByKey.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The only three ways two keyed collections can differ, which is the shape of every comparison in
+ * the schema diff: tables, columns, indexes and relationships all key and then split the same way.
+ * One counterpart each, so two items sharing a key (a duplicate index) are not collapsed into one.
+ */
+export declare function matchByKey<S, T>(source: Iterable<S>, target: Iterable<T>, key: (item: S | T) => string): {
+    created: S[];
+    dropped: T[];
+    matched: (readonly [S, T])[];
+};

package/dist/schema/matchByKey.js

@@ -0,0 +1,18 @@
+/**
+ * The only three ways two keyed collections can differ, which is the shape of every comparison in
+ * the schema diff: tables, columns, indexes and relationships all key and then split the same way.
+ * One counterpart each, so two items sharing a key (a duplicate index) are not collapsed into one.
+ */
+export function matchByKey(source, target, key) {
+    const unpaired = Map.groupBy(target, key);
+    const created = [];
+    const matched = [];
+    for (const item of source) {
+        const counterpart = unpaired.get(key(item))?.shift();
+        if (counterpart === undefined)
+            created.push(item);
+        else
+            matched.push([item, counterpart]);
+    }
+    return { created, dropped: [...unpaired.values()].flat(), matched };
+}

package/dist/schema/schemaAST.d.ts

@@ -1,6 +1,10 @@
-import type { IndexNode, RelationshipNode, TableNode } from './types.js';
+import type { PrimaryKeySchema } from '../type/migration.js';
+import type { IndexFacet } from './indexDifferences.js';
+import type { ColumnNode, IndexNode, RelationshipNode, TableNode } from './types.js';
 /** A table node with its collections empty, ready to be filled. */
-export declare function createTableNode(name: string, schema?: string, comment?: string): TableNode;
+export declare function createTableNode(name: string, schema?: string, indexFacets?: ReadonlySet<IndexFacet>): TableNode;
+/** The key the columns' own flags say, in their order, for a source that reports no key of its own. */
+export declare function keyOfColumns(columns: Iterable<Pick<ColumnNode, 'name' | 'isPrimaryKey'>>): PrimaryKeySchema | undefined;
 /** A database schema as a graph: tables, the foreign keys between them, and their indexes. */
 export declare class SchemaAST {
     readonly tables: Map<string, TableNode>;

package/dist/schema/schemaAST.js

@@ -1,19 +1,23 @@
 import { qualifyName } from '../util/sql.util.js';
 import { createOrder, dropOrder } from './dependencyGraph.js';
 /** A table node with its collections empty, ready to be filled. */
-export function createTableNode(name, schema, comment) {
+export function createTableNode(name, schema, indexFacets = new Set()) {
     return {
         name,
         schema,
-        comment,
+        indexFacets,
         columns: new Map(),
-        primaryKey: [],
         indexes: [],
         checks: [],
         incomingRelations: [],
         outgoingRelations: [],
     };
 }
+/** The key the columns' own flags say, in their order, for a source that reports no key of its own. */
+export function keyOfColumns(columns) {
+    const keyColumns = [...columns].filter((column) => column.isPrimaryKey).map((column) => column.name);
+    return keyColumns.length ? { columns: keyColumns } : undefined;
+}
 /** A database schema as a graph: tables, the foreign keys between them, and their indexes. */
 export class SchemaAST {
     tables = new Map();

package/dist/schema/schemaASTBuilder.d.ts

@@ -25,6 +25,8 @@ export interface BuildSchemaASTOptions {
     compileIndexPredicate?: (where: EntityWhereMeta<object>, entity: Type<object>, indexName: string) => string;
     /** Whether a weighted fulltext index declares one of its own for each heavier column, as MySQL scores through one. */
     textScoreIndexes?: boolean;
+    /** Whether a column a vector index covers is `NOT NULL` whatever the entity declares, as MariaDB demands. */
+    vectorIndexRequiresNotNull?: boolean;
 }
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).

package/dist/schema/schemaASTBuilder.js

@@ -5,7 +5,7 @@ import { isAutoIncrement, isInlinedExpression, isSoleIdField } from '../util/fie
 import { definedEntries } from '../util/object.util.js';
 import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
 import { resolveColumnCanonicalType } from './canonicalType.js';
-import { createTableNode, SchemaAST } from './schemaAST.js';
+import { createTableNode, keyOfColumns, SchemaAST } from './schemaAST.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).
@@ -26,6 +26,7 @@ export function buildSchemaAST(entities, options = {}) {
         compileDdl,
         compileIndexPredicate: options.compileIndexPredicate ?? compileDdl,
         textScoreIndexes: options.textScoreIndexes ?? false,
+        vectorIndexRequiresNotNull: options.vectorIndexRequiresNotNull ?? false,
     };
     for (const pass of [addTableFromEntity, addRelationshipsFromEntity, addIndexesFromEntity]) {
         for (const entity of entities) {
@@ -38,14 +39,21 @@ export function buildSchemaAST(entities, options = {}) {
 function refuseDdl() {
     throw new TypeError('building the schema of an entity that declares SQL (a check, a stored computed column, an index expression or predicate) needs a dialect to render it: pass `compileDdl`, as `buildEntityAST` does');
 }
+/** The entries a vector index of `meta` covers: the members it names, and any expression. */
+function vectorIndexedEntries(meta) {
+    return new Set((meta.indexes ?? [])
+        .filter((index) => index.type === 'vector')
+        .flatMap((index) => index.columns.map((entry) => entry.column)));
+}
 /**
  * Add a table from entity metadata.
  */
 function addTableFromEntity(ctx, meta) {
     const tableName = ctx.resolveTableName(meta);
     const table = createTableNode(tableName, ctx.resolveSchema(meta));
-    const { columns, primaryKey } = table;
-    table.checks?.push(...(meta.checks ?? []).map(({ name, where }) => ({ name, expression: ctx.compileDdl(where, meta.entity) })));
+    const { columns } = table;
+    table.checks.push(...(meta.checks ?? []).map(({ name, where }) => ({ name, expression: ctx.compileDdl(where, meta.entity) })));
+    const notNull = ctx.vectorIndexRequiresNotNull ? vectorIndexedEntries(meta) : new Set();
     // Add columns from fields
     for (const [key, field] of definedEntries(meta.fields)) {
         // An inlined expression has no column; a stored one is a column like any other.
@@ -60,7 +68,7 @@ function addTableFromEntity(ctx, meta) {
             type,
             // A primary key is NOT NULL in every engine, whatever the entity's property says: `id?: number`
             // is optional because the database assigns it, not because the column accepts a null.
-            nullable: isPrimaryKey ? false : (field.nullable ?? true),
+            nullable: isPrimaryKey || notNull.has(key) ? false : (field.nullable ?? true),
             defaultValue: field.defaultValue,
             isPrimaryKey,
             isAutoIncrement: isAutoIncrement(field, isSoleKey),
@@ -74,10 +82,8 @@ function addTableFromEntity(ctx, meta) {
             references: undefined,
         };
         columns.set(columnName, column);
-        if (field.isId) {
-            primaryKey.push(column);
-        }
     }
+    table.primaryKey = keyOfColumns(columns.values());
     ctx.ast.addTable(table);
 }
 /** The node an entity maps to, found under the key {@link SchemaAST} stores it by. */
@@ -157,11 +163,10 @@ function addForeignKeyIndexes(ctx, meta, table) {
         });
     }
 }
-/** Whether the key, a unique column or an index already leads with `columns`, which is all a lookup needs. */
+/** Whether the key or an index already leads with `columns`, which is all a lookup needs. */
 function isIndexedBy(table, columns) {
     const leads = (indexed) => columns.every((column, at) => indexed[at] === column);
-    return (leads(table.primaryKey.map((column) => column.name)) ||
-        (columns.length === 1 && table.columns.get(columns[0])?.isUnique === true) ||
+    return (leads(table.primaryKey?.columns ?? []) ||
         table.indexes.some((index) => leads(index.entries.map((entry) => entry.expression || entry.jsonPath || entry.jsonArray ? undefined : entry.column))));
 }
 /** An `include` column is named like any other, so a naming strategy has to reach it too. */