uql-orm 0.41.1 → 0.42.1

package/dist/migrate/introspection/baseSqlIntrospector.js

@@ -64,10 +64,13 @@ export class BaseSqlIntrospector {
                     referencedBy: [],
                 };
                 columns.set(col.name, column);
-                if (col.isPrimaryKey) {
-                    table.primaryKey.push(column);
-                }
             }
+            // From the ordered list the query returned, not from the per-column flags: `(a, b)` is a
+            // different key from `(b, a)`, and a flag says only that a column is *in* the key. Falls back
+            // to the flags for an introspector that reports no key of its own.
+            const keyColumns = schema.primaryKey ?? schema.columns.filter((col) => col.isPrimaryKey).map((col) => col.name);
+            table.primaryKey.push(...keyColumns.flatMap((name) => columns.get(name) ?? []));
+            table.primaryKeyName = schema.primaryKeyName;
             tableNodes.set(schema.name, table);
             ast.addTable(table);
         }

package/dist/migrate/introspection/postgresIntrospector.js

@@ -160,7 +160,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     }
     getPrimaryKeyQuery(_tableName) {
         return /*sql*/ `
-      SELECT kcu.column_name
+      SELECT kcu.column_name, tc.constraint_name
       FROM information_schema.table_constraints tc
       JOIN information_schema.key_column_usage kcu
         ON tc.constraint_name = kcu.constraint_name

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -1,3 +1,4 @@
+import { derivedForeignKeyName } from '../../util/sql.util.js';
 import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.js';
 /**
  * SQLite schema introspector
@@ -104,11 +105,14 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             existing.push(row);
             grouped.set(id, existing);
         }
-        return Array.from(grouped.entries()).map(([id, rows]) => {
+        return Array.from(grouped.entries()).map(([, rows]) => {
             const first = rows[0];
+            const columns = rows.map((r) => r.from);
             return {
-                name: `fk_${tableName}_${id}`,
-                columns: rows.map((r) => r.from),
+                // `PRAGMA foreign_key_list` reports no name, so one is derived the same way the entity side
+                // derives it. Seeded from the columns, not the PRAGMA's row id, which nothing else knows.
+                name: derivedForeignKeyName(tableName, columns),
+                columns,
                 referencedTable: first.table,
                 referencedColumns: rows.map((r) => r.to),
                 onDelete: this.normalizeReferentialAction(first.on_delete),

package/dist/migrate/migrator.js

@@ -436,6 +436,12 @@ export class Migrator {
                 this.logger.logSkippedMigration(`[AutoSync] Skipped altering ${filteredDiff.columnsToAlter.length} columns in table '${diff.tableName}': ${filteredDiff.columnsToAlter.map((c) => c.to.name).join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
                 delete filteredDiff.columnsToAlter;
             }
+            if (filteredDiff.primaryKey) {
+                // Rewriting a key drops a constraint and rebuilds an index over the whole table, and fails
+                // outright where the new columns are null on rows that already exist. Firmly not additive.
+                this.logger.logSkippedMigration(`[AutoSync] Skipped changing the primary key of '${diff.tableName}' from (${filteredDiff.primaryKey.from.join(', ')}) to (${filteredDiff.primaryKey.to.join(', ')}) (safe mode active). Use a migration or { safe: false } to apply.`);
+                delete filteredDiff.primaryKey;
+            }
             delete filteredDiff.indexesToDrop;
             delete filteredDiff.foreignKeysToDrop;
         }

package/dist/migrate/schemaGenerator.d.ts

@@ -1,7 +1,8 @@
 import { type AbstractDialect, AbstractSqlDialect } from '../dialect/index.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
+import { type DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
-import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
+import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
 import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from './builder/types.js';
 import { type IndexDdl } from './ddl/index.js';
 /**
@@ -25,7 +26,7 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     /**
      * Primary key type for auto-increment integer IDs
      */
-    protected get serialPrimaryKeyType(): string;
+    protected get serialType(): string;
     /**
      * Convert FieldOptions to CanonicalType using the unified type system.
      */
@@ -66,13 +67,15 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      */
     generateDropIndex(tableName: string, indexName: string, schema?: string): string;
     /**
-     * Generate a column definition from a {@link ColumnSchema}, whose type is the engine's own spelling
-     * and may already carry its precision (or even `PRIMARY KEY`, for a serial).
+     * A column definition from a {@link ColumnSchema}, whose type is already the engine's own spelling
+     * and may carry its own size.
+     *
+     * Kept apart from {@link generateColumnFromNode} rather than folded into it: a `ColumnSchema` has no
+     * `enum`, because introspection reads one back as a `CHECK` constraint and not as a property of the
+     * column, so only the node knows enough to emit that clause. Both spell the definition through
+     * {@link renderColumn}, which is the part that must not be written twice.
      */
-    generateColumnDefinitionFromSchema(column: ColumnSchema, options?: {
-        includePrimaryKey?: boolean;
-        includeUnique?: boolean;
-    }): string;
+    generateColumnDefinitionFromSchema(column: ColumnSchema): string;
     /**
      * The one place a column definition is spelled. Both callers reach it - the `ColumnSchema` path above
      * and the `ColumnNode` path below - because the clause order and the "no NOT NULL on a primary key"
@@ -82,7 +85,7 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     /** ` DEFAULT <sql>`, or nothing where the column declares none. Empty rather than `DEFAULT NULL`
      * so an absent default stays absent - `defaultValue: null` is the way to ask for one. */
     private defaultClause;
-    getSqlType(field: FieldOptions, fieldType?: unknown): string;
+    getSqlType(field: FieldMeta, fieldType?: unknown, isSoleKey?: boolean): string;
     /**
      * Generate ALTER COLUMN statements (database-specific)
      */
@@ -94,39 +97,30 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     /**
      * Compare an entity with a database table node and return the differences.
      */
-    diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined): SchemaDiff | undefined;
     /**
-     * Indexes the entity declares that the table does not have, matched by name and built the same way
-     * `CREATE TABLE` builds them, so adding an `@Index` to an entity already in the database is picked
-     * up rather than waiting for the table to be created from scratch somewhere else.
+     * How this entity differs from the table the database reported, as the migrator's `SchemaDiff`.
      *
-     * Only ever additive. An index the entity does not name is left alone: it may well have been
-     * created deliberately outside the ORM, and dropping it is a decision for a reviewed migration.
-     *
-     * A vector index is one of these like any other: MariaDB's `CREATE VECTOR INDEX ... ON t (col)`
-     * adds one to a table that already exists, which the inline `CREATE TABLE` form it also has cannot.
+     * The comparison itself is {@link diffTable}, the same one drift detection runs, so the two can no
+     * longer disagree about what has changed. Only two things are this side's own: the entity becomes a
+     * table node first, and types are compared as the *engine* would store them - see `normalizeType`.
      */
-    private missingIndexes;
-    private columnNodeToSchema;
-    /**
-     * Convert field options to ColumnSchema. Both sides of a diff are the engine's SQL spelling: what it
-     * would create for this field, against what it reported for the existing column.
-     */
-    protected fieldToColumnSchema<E>(fieldKey: string, field: FieldOptions, meta: EntityMeta<E>): ColumnSchema;
+    diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined): SchemaDiff | undefined;
     /**
-     * Check if two columns differ enough to require alteration
+     * What the shared differ needs from a dialect: a type as this engine would actually store it.
+     *
+     * `boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite, so two canonical types that differ on
+     * paper can be one column in the database. Round-tripping through the engine's own spelling is what
+     * stops every such column reporting an alteration on every sync.
      */
-    protected columnsNeedAlteration(current: ColumnSchema, desired: ColumnSchema): boolean;
     /**
-     * Whether two column types are the same *as this engine stores them*.
+     * Indexes the entity declares that the table does not already have, in any shape.
      *
-     * Both sides are SQL spellings, parsed back to canonical so that `INT` and `INTEGER`, or `DATETIME`
-     * and `TIMESTAMP`, do not read as a change. Do not "simplify" this into comparing the entity's
-     * canonical type against the column's: several canonical types share one storage type per engine
-     * (`boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite), so that comparison reports an
-     * alteration for those columns on every single sync.
+     * Additive only: an index the entity does not name may well have been created deliberately outside
+     * the ORM, and dropping it is a decision for a reviewed migration.
      */
-    protected isTypeEqual(current: ColumnSchema, desired: ColumnSchema): boolean;
+    private missingIndexes;
+    protected diffOptions(): DiffOptions;
+    private columnNodeToSchema;
     /**
      * Compare two default values for equality
      */
@@ -156,6 +150,22 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     generateRenameColumnSql(tableName: string, oldName: string, newName: string): string;
     generateAddForeignKeySql(tableName: string, foreignKey: TableForeignKeyDefinition): string;
     generateDropForeignKeySql(tableName: string, constraintName: string): string;
+    /**
+     * `ALTER TABLE ... ADD CONSTRAINT <name> PRIMARY KEY (...)`, the other half of
+     * {@link generateDropPrimaryKeySql}. Refused where the engine cannot alter a key at all, by name,
+     * rather than emitting DDL it will reject.
+     */
+    generateAddPrimaryKeySql(tableName: string, columns: readonly string[], name?: string): string;
+    /**
+     * Drops whatever key the table has.
+     *
+     * `constraintName` has to be what the constraint is *actually* called: the name introspection
+     * reported for a key the database already had, or the derived one for a key this generator itself
+     * added, which is what reversing a migration drops. Guessing either way names nothing. MySQL takes
+     * no name at all - a table's key is always `PRIMARY` there.
+     */
+    generateDropPrimaryKeySql(tableName: string, constraintName?: string): string;
+    private assertPrimaryKeyAlterable;
 }
 /**
  * The entities as an AST, named the way `generator` names things.

package/dist/migrate/schemaGenerator.js

@@ -1,9 +1,11 @@
 import { AbstractSqlDialect } from '../dialect/index.js';
-import { getMeta } from '../entity/index.js';
+import { getMeta, soleIdOf } from '../entity/index.js';
 import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategory, sqlToCanonical, } from '../schema/canonicalType.js';
+import { indexSignature } from '../schema/indexDifferences.js';
 import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
-import { getKeys, isAutoIncrement, qualifyName } from '../util/index.js';
-import { derivedCheckName, derivedForeignKeyName } from '../util/sql.util.js';
+import { diffTable } from '../schema/schemaASTDiffer.js';
+import { getKeys, isAutoIncrement, isSoleIdField, qualifyName } from '../util/index.js';
+import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName } from '../util/sql.util.js';
 import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
 import { indexDdlFor } from './ddl/index.js';
 import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
@@ -47,8 +49,8 @@ export class SqlSchemaGenerator {
     /**
      * Primary key type for auto-increment integer IDs
      */
-    get serialPrimaryKeyType() {
-        return this.dialect.serialPrimaryKey;
+    get serialType() {
+        return this.dialect.serialType;
     }
     /**
      * Convert FieldOptions to CanonicalType using the unified type system.
@@ -128,6 +130,11 @@ export class SqlSchemaGenerator {
     generateAlterTable(diff) {
         const statements = [];
         const tableName = this.escapeId(diff.tableName);
+        // 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));
+        }
         // Add new columns
         if (diff.columnsToAdd?.length) {
             for (const column of diff.columnsToAdd) {
@@ -161,11 +168,21 @@ export class SqlSchemaGenerator {
                 statements.push(this.generateDropIndex(diff.tableName, indexName, diff.schema));
             }
         }
+        // Last, so every column it names exists by now.
+        if (diff.primaryKey?.to.length) {
+            statements.push(this.generateAddPrimaryKeySql(diff.tableName, diff.primaryKey.to));
+        }
         return statements;
     }
     generateAlterTableDown(diff) {
         const statements = [];
         const tableName = this.escapeId(diff.tableName);
+        // The key first, mirroring the up direction: 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)));
+        }
         // Reverse column additions by dropping them
         if (diff.columnsToAdd?.length) {
             for (const column of diff.columnsToAdd) {
@@ -175,7 +192,7 @@ export class SqlSchemaGenerator {
         // Reverse column alterations by restoring original schema
         if (diff.columnsToAlter?.length) {
             for (const { from } of diff.columnsToAlter) {
-                const colDef = this.generateColumnDefinitionFromSchema(from, { includePrimaryKey: false });
+                const colDef = this.generateColumnDefinitionFromSchema(from);
                 const colStatements = this.generateAlterColumnStatements(diff.tableName, from, colDef);
                 statements.push(...colStatements);
             }
@@ -186,6 +203,9 @@ export class SqlSchemaGenerator {
                 statements.push(this.generateDropIndex(diff.tableName, index.name, diff.schema));
             }
         }
+        if (diff.primaryKey?.from.length) {
+            statements.push(this.generateAddPrimaryKeySql(diff.tableName, diff.primaryKey.from, diff.primaryKey.fromName));
+        }
         if (diff.columnsToDrop?.length || diff.indexesToDrop?.length) {
             statements.push(`-- TODO: Manual reversal needed for dropped columns/indexes`);
         }
@@ -205,11 +225,15 @@ export class SqlSchemaGenerator {
         return `DROP INDEX IF EXISTS ${this.dialect.escapeQualifiedId(indexName, schema)};`;
     }
     /**
-     * Generate a column definition from a {@link ColumnSchema}, whose type is the engine's own spelling
-     * and may already carry its precision (or even `PRIMARY KEY`, for a serial).
+     * A column definition from a {@link ColumnSchema}, whose type is already the engine's own spelling
+     * and may carry its own size.
+     *
+     * Kept apart from {@link generateColumnFromNode} rather than folded into it: a `ColumnSchema` has no
+     * `enum`, because introspection reads one back as a `CHECK` constraint and not as a property of the
+     * column, so only the node knows enough to emit that clause. Both spell the definition through
+     * {@link renderColumn}, which is the part that must not be written twice.
      */
-    generateColumnDefinitionFromSchema(column, options = {}) {
-        const { includePrimaryKey = true, includeUnique = true } = options;
+    generateColumnDefinitionFromSchema(column) {
         let type = column.type;
         if (!type.includes('(')) {
             if (column.precision !== undefined) {
@@ -219,17 +243,7 @@ export class SqlSchemaGenerator {
                 type += `(${column.length})`;
             }
         }
-        if (!includePrimaryKey) {
-            type = type.replace(/\s+PRIMARY\s+KEY/i, '');
-        }
-        // `includePrimaryKey: false` suppresses the keyword, not the fact: the column is still the primary
-        // key, so it must not pick up `NOT NULL` (implied) or `UNIQUE` (redundant) on the way out.
-        return this.renderColumn({
-            ...column,
-            type,
-            isUnique: column.isUnique && includeUnique,
-            declaresPrimaryKey: includePrimaryKey && column.isPrimaryKey,
-        });
+        return this.renderColumn({ ...column, type });
     }
     /**
      * The one place a column definition is spelled. Both callers reach it - the `ColumnSchema` path above
@@ -238,9 +252,6 @@ export class SqlSchemaGenerator {
      */
     renderColumn(column) {
         let def = `${this.escapeId(column.name)} ${column.type}`;
-        if (column.declaresPrimaryKey && !column.type.includes('PRIMARY KEY')) {
-            def += ' PRIMARY KEY';
-        }
         if (!column.nullable && !column.isPrimaryKey) {
             def += ' NOT NULL';
         }
@@ -264,19 +275,19 @@ export class SqlSchemaGenerator {
             ? ''
             : ` DEFAULT ${formatDefaultValue(column.defaultValue, this.dialect, column.type)}`;
     }
-    getSqlType(field, fieldType) {
+    getSqlType(field, fieldType, isSoleKey = field.isId === true) {
         // If field has a reference, inherit type from the target primary key
         if (field.references) {
             const refEntity = field.references();
             const refMeta = getMeta(refEntity);
-            const refIdField = refMeta.fields[refMeta.id];
+            const refIdField = refMeta.fields[field.referencedKey ?? soleIdOf(refMeta, 'a foreign key')];
             return this.getSqlType({ ...refIdField, references: undefined, isId: undefined, autoIncrement: false }, refIdField.type);
         }
         // Get canonical type and convert to SQL
         const canonical = this.getCanonicalType(field, fieldType);
         // Special case for serial primary keys
-        if (isAutoIncrement(field, field.isId === true)) {
-            return this.dialect.serialPrimaryKey;
+        if (isAutoIncrement(field, isSoleKey)) {
+            return this.dialect.serialType;
         }
         return this.canonicalTypeToSql(canonical);
     }
@@ -323,80 +334,90 @@ export class SqlSchemaGenerator {
     /**
      * Compare an entity with a database table node and return the differences.
      */
+    /**
+     * How this entity differs from the table the database reported, as the migrator's `SchemaDiff`.
+     *
+     * The comparison itself is {@link diffTable}, the same one drift detection runs, so the two can no
+     * longer disagree about what has changed. Only two things are this side's own: the entity becomes a
+     * table node first, and types are compared as the *engine* would store them - see `normalizeType`.
+     */
     diffSchema(entity, currentTable) {
         const meta = getMeta(entity);
+        const tableName = this.resolveTableName(meta);
+        const schema = this.resolveSchema(meta);
         if (!currentTable) {
-            return {
-                tableName: this.resolveTableName(meta),
-                schema: this.resolveSchema(meta),
-                type: 'create',
-            };
-        }
-        const columnsToAdd = [];
-        const columnsToAlter = [];
-        const columnsToDrop = [];
-        const currentColumns = new Map(currentTable.columns);
-        const fieldKeys = getKeys(meta.fields);
-        for (const key of fieldKeys) {
-            const field = meta.fields[key];
-            if (!field || field.virtual)
-                continue;
-            const columnName = this.dialect.resolveColumnName(key, field);
-            const currentColumn = currentColumns.get(columnName);
-            if (!currentColumn) {
-                columnsToAdd.push(this.fieldToColumnSchema(key, field, meta));
-            }
-            else {
-                const desiredColumn = this.fieldToColumnSchema(key, field, meta);
-                const currentColumnSchema = this.columnNodeToSchema(currentColumn);
-                if (this.columnsNeedAlteration(currentColumnSchema, desiredColumn)) {
-                    columnsToAlter.push({ from: currentColumnSchema, to: desiredColumn });
-                }
-            }
-            currentColumns.delete(columnName);
+            return { tableName, schema, type: 'create' };
         }
-        for (const [name] of currentColumns) {
-            columnsToDrop.push(name);
+        // Keyed by the qualified name this generator resolves, which is the key the AST it just built
+        // stores the table under.
+        const desired = buildEntityAST(this, [entity]).getTable(tableName);
+        if (!desired) {
+            return undefined;
         }
-        const indexesToAdd = this.missingIndexes(entity, currentTable);
-        if (columnsToAdd.length === 0 &&
-            columnsToAlter.length === 0 &&
-            columnsToDrop.length === 0 &&
-            indexesToAdd.length === 0) {
+        // 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 a
+        // separate index rather than a change - no engine alters an index's columns or uniqueness.
+        const tableDiff = diffTable(desired, currentTable, { ...this.diffOptions(), compareIndexes: false });
+        const indexesToAdd = this.missingIndexes(desired, currentTable);
+        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] : []));
+        const columnsToAlter = columnDiffs.flatMap((it) => it.type === 'alter'
+            ? [{ from: this.columnNodeToSchema(it.actual), to: this.columnNodeToSchema(it.expected) }]
+            : []);
+        const primaryKey = tableDiff?.primaryKeyDiff && {
+            from: tableDiff.primaryKeyDiff.actual,
+            to: tableDiff.primaryKeyDiff.expected,
+            fromName: tableDiff.primaryKeyDiff.actualName,
+        };
+        if (!columnsToAdd.length &&
+            !columnsToAlter.length &&
+            !columnsToDrop.length &&
+            !indexesToAdd.length &&
+            !primaryKey) {
             return undefined;
         }
         return {
-            tableName: this.resolveTableName(meta),
-            schema: this.resolveSchema(meta),
+            tableName,
+            schema,
             type: 'alter',
-            columnsToAdd: columnsToAdd.length > 0 ? columnsToAdd : undefined,
-            columnsToAlter: columnsToAlter.length > 0 ? columnsToAlter : undefined,
-            columnsToDrop: columnsToDrop.length > 0 ? columnsToDrop : undefined,
-            indexesToAdd: indexesToAdd.length > 0 ? indexesToAdd : undefined,
+            primaryKey,
+            columnsToAdd: columnsToAdd.length ? columnsToAdd : undefined,
+            columnsToAlter: columnsToAlter.length ? columnsToAlter : undefined,
+            columnsToDrop: columnsToDrop.length ? columnsToDrop : undefined,
+            indexesToAdd: indexesToAdd.length ? indexesToAdd : undefined,
         };
     }
     /**
-     * Indexes the entity declares that the table does not have, matched by name and built the same way
-     * `CREATE TABLE` builds them, so adding an `@Index` to an entity already in the database is picked
-     * up rather than waiting for the table to be created from scratch somewhere else.
+     * What the shared differ needs from a dialect: a type as this engine would actually store it.
      *
-     * Only ever additive. An index the entity does not name is left alone: it may well have been
-     * created deliberately outside the ORM, and dropping it is a decision for a reviewed migration.
+     * `boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite, so two canonical types that differ on
+     * paper can be one column in the database. Round-tripping through the engine's own spelling is what
+     * stops every such column reporting an alteration on every sync.
+     */
+    /**
+     * Indexes the entity declares that the table does not already have, in any shape.
      *
-     * A vector index is one of these like any other: MariaDB's `CREATE VECTOR INDEX ... ON t (col)`
-     * adds one to a table that already exists, which the inline `CREATE TABLE` form it also has cannot.
+     * Additive only: an index the entity does not name may well have been created deliberately outside
+     * the ORM, and dropping it is a decision for a reviewed migration.
      */
-    missingIndexes(entity, currentTable) {
-        // Keyed by the qualified name, so a table in a schema finds itself rather than reporting that
-        // the entity declares no indexes at all.
-        const desired = buildEntityAST(this, [entity]).getTable(qualifyName(currentTable.name, currentTable.schema))?.indexes ?? [];
-        const present = new Set(currentTable.indexes.map((index) => index.name));
-        return desired.filter((index) => !present.has(index.name)).map(indexNodeToSchema);
+    missingIndexes(desired, currentTable) {
+        const present = new Set(currentTable.indexes.map(indexSignature));
+        return desired.indexes.filter((index) => !present.has(indexSignature(index))).map(indexNodeToSchema);
+    }
+    diffOptions() {
+        return {
+            normalizeType: (type) => sqlToCanonical(this.canonicalTypeToSql(type)),
+            defaultsEqual: (expected, actual) => this.isDefaultValueEqual(actual, expected),
+        };
     }
     columnNodeToSchema(col) {
         return {
             name: col.name,
-            type: this.canonicalTypeToSql(col.type),
+            // The same rule `generateColumnFromNode` renders by, so a column added to an existing table
+            // gets the type it would have had if the table were created from scratch.
+            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType : this.canonicalTypeToSql(col.type),
             nullable: col.nullable,
             defaultValue: col.defaultValue,
             isPrimaryKey: col.isPrimaryKey,
@@ -405,65 +426,17 @@ export class SqlSchemaGenerator {
             comment: col.comment,
         };
     }
-    /**
-     * Convert field options to ColumnSchema. Both sides of a diff are the engine's SQL spelling: what it
-     * would create for this field, against what it reported for the existing column.
-     */
-    fieldToColumnSchema(fieldKey, field, meta) {
-        const isPrimaryKey = field.isId === true && meta.id === fieldKey;
-        return {
-            name: this.dialect.resolveColumnName(fieldKey, field),
-            type: this.getSqlType(field, field.type),
-            nullable: field.nullable ?? !isPrimaryKey,
-            defaultValue: field.defaultValue,
-            isPrimaryKey,
-            isAutoIncrement: isAutoIncrement(field, isPrimaryKey),
-            isUnique: field.unique ?? false,
-            length: field.length,
-            precision: field.precision,
-            scale: field.scale,
-            comment: field.comment,
-        };
-    }
-    /**
-     * Check if two columns differ enough to require alteration
-     */
-    columnsNeedAlteration(current, desired) {
-        if (current.isPrimaryKey && desired.isPrimaryKey) {
-            return false;
-        }
-        if (current.isPrimaryKey !== desired.isPrimaryKey)
-            return true;
-        if (current.nullable !== desired.nullable)
-            return true;
-        if (current.isUnique !== desired.isUnique)
-            return true;
-        if (!this.isTypeEqual(current, desired))
-            return true;
-        if (!this.isDefaultValueEqual(current.defaultValue, desired.defaultValue))
-            return true;
-        return false;
-    }
-    /**
-     * Whether two column types are the same *as this engine stores them*.
-     *
-     * Both sides are SQL spellings, parsed back to canonical so that `INT` and `INTEGER`, or `DATETIME`
-     * and `TIMESTAMP`, do not read as a change. Do not "simplify" this into comparing the entity's
-     * canonical type against the column's: several canonical types share one storage type per engine
-     * (`boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite), so that comparison reports an
-     * alteration for those columns on every single sync.
-     */
-    isTypeEqual(current, desired) {
-        return areTypesEqual(sqlToCanonical(current.type), sqlToCanonical(desired.type));
-    }
     /**
      * Compare two default values for equality
      */
     isDefaultValueEqual(current, desired) {
         if (current === desired)
             return true;
-        if (current === undefined || desired === undefined)
-            return current === desired;
+        // 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) => {
             if (value === null)
                 return 'null';
@@ -493,9 +466,16 @@ export class SqlSchemaGenerator {
             const colDef = this.generateColumnFromNode(indexedVectorColumns.has(col.name) ? { ...col, nullable: false } : col);
             columns.push(colDef);
         }
-        if (table.primaryKey.length > 1) {
-            const pkCols = table.primaryKey.map((c) => this.escapeId(c.name)).join(', ');
-            constraints.push(`PRIMARY KEY (${pkCols})`);
+        // 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 declaredByColumn = this.dialect.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) => {
             const name = check.name ?? derivedCheckName(table.name, i + 1);
@@ -542,8 +522,7 @@ export class SqlSchemaGenerator {
     generateColumnFromNode(col) {
         return this.renderColumn({
             ...col,
-            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialPrimaryKeyType : this.canonicalTypeToSql(col.type),
-            declaresPrimaryKey: col.isPrimaryKey && col.table.primaryKey.length === 1,
+            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType : this.canonicalTypeToSql(col.type),
         });
     }
     /**
@@ -594,6 +573,44 @@ export class SqlSchemaGenerator {
     generateDropForeignKeySql(tableName, constraintName) {
         return `ALTER TABLE ${this.escapeId(tableName)} ${this.dialect.dropForeignKeySyntax} ${this.escapeId(constraintName)};`;
     }
+    /**
+     * `ALTER TABLE ... ADD CONSTRAINT <name> PRIMARY KEY (...)`, the other half of
+     * {@link generateDropPrimaryKeySql}. Refused where the engine cannot alter a key at all, by name,
+     * rather than emitting DDL it will reject.
+     */
+    generateAddPrimaryKeySql(tableName, columns, name) {
+        this.assertPrimaryKeyAlterable(tableName);
+        const constraintName = this.escapeId(name ?? derivedPrimaryKeyName(tableName, columns));
+        const pkCols = columns.map((c) => this.escapeId(c)).join(', ');
+        return `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${constraintName} PRIMARY KEY (${pkCols});`;
+    }
+    /**
+     * Drops whatever key the table has.
+     *
+     * `constraintName` has to be what the constraint is *actually* called: the name introspection
+     * reported for a key the database already had, or the derived one for a key this generator itself
+     * added, which is what reversing a migration drops. Guessing either way names nothing. MySQL takes
+     * no name at all - a table's key is always `PRIMARY` there.
+     */
+    generateDropPrimaryKeySql(tableName, constraintName) {
+        this.assertPrimaryKeyAlterable(tableName);
+        const table = this.escapeId(tableName);
+        if (this.dialect.dropPrimaryKeySyntax === 'DROP PRIMARY KEY') {
+            return `ALTER TABLE ${table} DROP PRIMARY KEY;`;
+        }
+        if (!constraintName) {
+            throw new TypeError(`Cannot drop the primary key of "${tableName}": ${this.dialect} names the constraint, and ` +
+                'introspection did not report a name for it.');
+        }
+        return `ALTER TABLE ${table} DROP CONSTRAINT ${this.escapeId(constraintName)};`;
+    }
+    assertPrimaryKeyAlterable(tableName) {
+        if (this.features.primaryKeyAlter) {
+            return;
+        }
+        throw new TypeError(`${this.dialect}: Cannot change the primary key of "${tableName}" - this database has no ALTER ` +
+            'for it. Recreate the table in a written migration.');
+    }
 }
 /**
  * The entities as an AST, named the way `generator` names things.