uql-orm 0.43.0 → 0.45.0

package/dist/migrate/migrator.js

@@ -282,12 +282,16 @@ export class Migrator {
             throw new TypeError('Schema generator and introspector must be set');
         }
         const ast = await this.introspectClaimedSchemas();
+        // Both sides built once: the database's above, the entities' here. Left to `diffSchema`, each
+        // entity would rebuild the whole AST, which is quadratic in the number of entities. Absent on a
+        // generator that compares no schema of its own - MongoDB, which reads only indexes.
+        const desiredAst = this.schemaGenerator.buildAST?.(this.entities);
         const diffs = [];
         for (const entity of this.entities) {
             const meta = getMeta(entity);
             const tableName = this.schemaGenerator.resolveTableName(meta);
             const currentTable = ast.getTable(tableName);
-            const diff = this.schemaGenerator.diffSchema(entity, currentTable);
+            const diff = this.schemaGenerator.diffSchema(entity, currentTable, desiredAst);
             if (diff) {
                 diffs.push(diff);
             }
@@ -305,7 +309,7 @@ export class Migrator {
         const claimed = new Set(this.entities.map((entity) => this.pool.dialect.resolveSchema(getMeta(entity))));
         const merged = new SchemaAST();
         for (const schema of claimed) {
-            const introspector = schema === undefined ? this.schemaIntrospector : this.createIntrospector(schema);
+            const introspector = this.introspectorFor(schema);
             if (!introspector) {
                 continue;
             }
@@ -330,52 +334,92 @@ export class Migrator {
         return undefined;
     }
     /**
-     * Sync schema directly (for development only - not for production!)
+     * Applies the entity schema to the database: every registered entity, or the one `entity` names.
+     *
+     * The whole surface is this and {@link planSync}, which answers the same question without running
+     * it - `force` and a single entity included, so `--dry-run` means the same thing whatever else was
+     * asked for.
      */
     async sync(options = {}) {
-        if (options.force) {
-            return this.syncForce();
+        const statements = await this.planSync(options);
+        if (statements.length) {
+            await this.executeSyncStatements(statements, options);
+        }
+        else if (options.logging) {
+            this.logger.logSchema('Schema is already in sync.');
         }
-        return this.autoSync({ safe: true });
     }
     /**
-     * Drops and recreates all tables (Development only!)
+     * Every table dropped and recreated.
+     *
+     * Both directions span the whole entity set rather than looping an entity at a time. A per-entity
+     * AST cannot resolve a cross-entity foreign key, so the old create loop silently produced a schema
+     * with no referential integrity; and the old drop loop went in reverse *declaration* order, which
+     * says nothing about the relation graph and is rejected as soon as the constraints are really there.
      */
-    async syncForce() {
-        await this.ensureSchemaGenerator();
-        // Both directions span the whole entity set rather than looping an entity at a time. A per-entity
-        // AST cannot resolve a cross-entity foreign key, so the old create loop silently produced a schema
-        // with no referential integrity; and the old drop loop went in reverse *declaration* order, which
-        // says nothing about the relation graph and is rejected as soon as the constraints are really there.
-        const statements = [
+    forceStatements() {
+        return [
             ...this.generator.generateDropSchema(this.entities, { ifExists: true, cascade: true }),
             ...this.generator.generateCreateSchema(this.entities),
         ];
-        await withSqlQuerierForMigrations(this.pool, 'Migrator', (querier) => querier.transaction(async () => {
-            for (const sql of statements) {
-                this.logger.logSchema(`Executing: ${sql}`);
-                await querier.run(sql);
-            }
-        }));
-        this.logger.logSchema('Schema sync (force) completed');
     }
     /**
-     * Safely synchronizes the schema by only adding missing tables and columns.
+     * Sync one entity, for a schema that grows while the process runs: a content type an admin just
+     * created is one table to add, where the whole set would read the catalogue to work that out.
+     *
+     * The new-table case costs one existence check and creates with `IF NOT EXISTS`, so instances racing
+     * the same admin save settle instead of colliding. An existing table still pays for introspection,
+     * since a column diff needs the columns.
      */
-    async autoSync(options = {}) {
-        const statements = await this.planSync(options);
-        if (statements.length === 0) {
-            if (options.logging)
-                this.logger.logSchema('Schema is already in sync.');
-            return;
+    /** The DDL for one entity: {@link planSync} narrowed to the table it names. */
+    async planEntity(entity, options) {
+        const meta = getMeta(entity);
+        // Before anything reads `this.generator`, whose own failure names neither the entity nor the
+        // dialect that has no support.
+        const introspector = this.introspectorFor(this.pool.dialect.resolveSchema(meta));
+        if (!introspector) {
+            throw new TypeError(`No introspector for '${meta.entity.name}' on '${this.dialectName}'`);
         }
-        await this.executeSyncStatements(statements, options);
+        const tableName = this.generator.resolveTableName(meta);
+        return (await introspector.tableExists(tableName))
+            ? this.alterFromEntity(entity, (await introspectSchema(introspector)).getTable(tableName), options)
+            : // Spanning the whole set, so a foreign key resolves against the tables it points at, and
+                // always including this entity: pinned to an explicit `entities` list, a sync of one outside
+                // it emitted nothing at all. `only` is what keeps the statements to this table.
+                this.generator.generateCreateSchema(this.entitiesWith(entity), { only: [tableName], ifNotExists: true });
+    }
+    /** An alter diff as statements, narrowed to what the caller allows. */
+    alterFromDiff(diff, options) {
+        return this.generator.generateAlterTable(this.filterDiff(diff, options));
+    }
+    /** The same for one entity against the table it already has, and nothing where the two agree. */
+    alterFromEntity(entity, table, options) {
+        // Spanning the set for the reason `planEntity` spells out: a foreign key needs the table it
+        // points at, which a sync of one entity outside the configured list would not otherwise have.
+        const diff = this.generator.diffSchema(entity, table, this.generator.buildAST?.(this.entitiesWith(entity)));
+        return diff?.type === 'alter' ? this.alterFromDiff(diff, options) : [];
+    }
+    /** The configured entities, with `entity` among them however the migrator was built. */
+    entitiesWith(entity) {
+        const entities = this.entities;
+        return entities.includes(entity) ? entities : [...entities, entity];
+    }
+    /** The introspector for a claimed schema, which is the connection's own where none is claimed. */
+    introspectorFor(schema) {
+        return schema === undefined ? this.schemaIntrospector : this.createIntrospector(schema);
     }
     /**
-     * The DDL {@link autoSync} would run, without running it. Separate so `--dry-run` shows the real
+     * The DDL {@link sync} would run, without running it. Separate so `--dry-run` shows the real
      * statements rather than a summary of a second, differently-computed diff.
      */
     async planSync(options = {}) {
+        await this.ensureSchemaGenerator();
+        if (options.force) {
+            return this.forceStatements();
+        }
+        if (options.entity) {
+            return this.planEntity(options.entity, options);
+        }
         const creating = [];
         const altering = [];
         for (const { diff, entity } of await this.pendingDiffs()) {
@@ -384,7 +428,7 @@ export class Migrator {
                     creating.push(diff.tableName);
             }
             else if (diff.type === 'alter') {
-                altering.push(...this.generator.generateAlterTable(this.filterDiff(diff, options)));
+                altering.push(...this.alterFromDiff(diff, options));
             }
         }
         return [...this.createSchema(creating), ...altering];
@@ -442,6 +486,12 @@ export class Migrator {
                 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;
             }
+            if (filteredDiff.foreignKeysToAlter?.length) {
+                // Altering one is dropping it and adding it back, so letting the add through while the drop
+                // is held would emit `ADD CONSTRAINT` for a constraint the table still has.
+                this.logger.logSkippedMigration(`[AutoSync] Skipped altering ${filteredDiff.foreignKeysToAlter.length} foreign keys in table '${diff.tableName}': ${filteredDiff.foreignKeysToAlter.map((fk) => fk.to.name).join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
+                delete filteredDiff.foreignKeysToAlter;
+            }
             delete filteredDiff.indexesToDrop;
             delete filteredDiff.foreignKeysToDrop;
         }
@@ -452,10 +502,15 @@ export class Migrator {
         return filteredDiff;
     }
     async executeSyncStatements(statements, options) {
-        // Mongo creates collections and indexes outside any transaction, so only the SQL path opens one.
-        await withQuerierForMigrations(this.pool, (querier) => this.dialectName === 'mongodb'
-            ? this.executeMongoSyncStatements(statements, options, querier)
-            : querier.transaction(() => this.executeSqlSyncStatements(statements, options, querier)));
+        // Mongo creates collections and indexes outside any transaction, so only the SQL path opens one -
+        // and asks for a SQL querier before it opens it, since `transaction` is what a Mongo one lacks and
+        // reaching for it first reports that instead of which querier the dialect needs.
+        if (this.dialectName === 'mongodb') {
+            await withQuerierForMigrations(this.pool, (querier) => this.executeMongoSyncStatements(statements, options, querier));
+        }
+        else {
+            await withSqlQuerierForMigrations(this.pool, 'Migrator', (querier) => querier.transaction(() => this.executeSqlSyncStatements(statements, options, querier)));
+        }
         if (options.logging)
             this.logger.logSchema('Schema synchronization completed');
     }

package/dist/migrate/schemaGenerator.d.ts

@@ -2,8 +2,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, FieldMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
-import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from './builder/types.js';
+import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
+import type { FullColumnDefinition, TableDefinition } from './builder/types.js';
 import { type IndexDdl } from './ddl/index.js';
 /**
  * Unified SQL schema generator.
@@ -26,8 +26,19 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     /**
      * Primary key type for auto-increment integer IDs
      */
-    protected get serialType(): string;
+    /**
+     * How an auto-increment key of `type` is spelled: the type as any other column renders it, plus what
+     * the engine appends to make it generated.
+     *
+     * Derived rather than a fixed string per dialect, because a foreign key column takes its type from
+     * the key it points at, resolved through the same canonical type. A key whose spelling ignored that
+     * type could never be referenced: `@Id({ columnType: 'int' })` emitted `BIGINT` while the column
+     * pointing at it emitted `INT`, and every engine refuses that constraint.
+     */
+    protected serialType(type: CanonicalType): string;
     protected canonicalTypeToSql(type: CanonicalType): string;
+    /** The entity side as an AST, carrying this generator's default referential action. */
+    buildAST(entities: readonly Type<unknown>[]): SchemaAST;
     /**
      * Every `CREATE TABLE` for `entities`, then their foreign keys.
      *
@@ -53,6 +64,10 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     private orderedTables;
     generateDropTable(tableName: string, options?: DropSchemaOptions): string;
     generateAlterTable(diff: SchemaDiff): string[];
+    /** `ADD CONSTRAINT` for each of `foreignKeys`. */
+    private addForeignKeyStatements;
+    /** `DROP CONSTRAINT` for each of `constraintNames`, the mirror of {@link addForeignKeyStatements}. */
+    private dropForeignKeyStatements;
     generateAlterTableDown(diff: SchemaDiff): string[];
     generateCreateIndex(tableName: string, index: IndexSchema, options?: {
         ifNotExists?: boolean;
@@ -100,7 +115,7 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      * 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<E>(entity: Type<E>, currentTable: TableNode | undefined): SchemaDiff | undefined;
+    diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
     /**
      * What the shared differ needs from a dialect: a type as this engine would actually store it.
      *
@@ -144,7 +159,7 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     generateAlterColumnSql(tableName: string, columnName: string, column: FullColumnDefinition): string;
     generateDropColumnSql(tableName: string, columnName: string): string;
     generateRenameColumnSql(tableName: string, oldName: string, newName: string): string;
-    generateAddForeignKeySql(tableName: string, foreignKey: TableForeignKeyDefinition): string;
+    generateAddForeignKeySql(tableName: string, foreignKey: ForeignKeySchema): string;
     generateDropForeignKeySql(tableName: string, constraintName: string): string;
     /**
      * `ALTER TABLE ... ADD CONSTRAINT <name> PRIMARY KEY (...)`, the other half of

package/dist/migrate/schemaGenerator.js

@@ -3,7 +3,7 @@ import { getMeta, soleIdOf } from '../entity/index.js';
 import { areTypesEqual, canonicalToSql, engineType, fieldOptionsToCanonical, isVectorCategory, } from '../schema/canonicalType.js';
 import { indexSignature } from '../schema/indexDifferences.js';
 import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
-import { diffTable } from '../schema/schemaASTDiffer.js';
+import { diffRelationshipNodes, 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';
@@ -49,12 +49,25 @@ export class SqlSchemaGenerator {
     /**
      * Primary key type for auto-increment integer IDs
      */
-    get serialType() {
-        return this.dialect.serialType;
+    /**
+     * How an auto-increment key of `type` is spelled: the type as any other column renders it, plus what
+     * the engine appends to make it generated.
+     *
+     * Derived rather than a fixed string per dialect, because a foreign key column takes its type from
+     * the key it points at, resolved through the same canonical type. A key whose spelling ignored that
+     * type could never be referenced: `@Id({ columnType: 'int' })` emitted `BIGINT` while the column
+     * pointing at it emitted `INT`, and every engine refuses that constraint.
+     */
+    serialType(type) {
+        return `${this.canonicalTypeToSql(type)} ${this.dialect.autoIncrementSuffix}`;
     }
     canonicalTypeToSql(type) {
         return canonicalToSql(type, this.dialect);
     }
+    /** The entity side as an AST, carrying this generator's default referential action. */
+    buildAST(entities) {
+        return buildEntityAST(this, entities, this.defaultForeignKeyAction);
+    }
     /**
      * Every `CREATE TABLE` for `entities`, then their foreign keys.
      *
@@ -76,16 +89,7 @@ export class SqlSchemaGenerator {
         statements.push(...tables.flatMap((table) => this.generateCreateTableFromNode(inline ? table : { ...table, outgoingRelations: [] }, options)));
         if (withForeignKeys && !inline) {
             for (const table of tables) {
-                for (const rel of table.outgoingRelations) {
-                    statements.push(this.generateAddForeignKeySql(qualifyName(table.name, table.schema), {
-                        name: rel.name,
-                        columns: rel.from.columns.map((c) => c.name),
-                        referencesTable: qualifyName(rel.to.table.name, rel.to.table.schema),
-                        referencesColumns: rel.to.columns.map((c) => c.name),
-                        onDelete: rel.onDelete ?? this.defaultForeignKeyAction,
-                        onUpdate: rel.onUpdate ?? this.defaultForeignKeyAction,
-                    }));
-                }
+                statements.push(...this.addForeignKeyStatements(qualifyName(table.name, table.schema), table.outgoingRelations.map(foreignKeyOf)));
             }
         }
         return statements;
@@ -129,6 +133,12 @@ export class SqlSchemaGenerator {
         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)),
+        ]));
         // Add new columns
         if (diff.columnsToAdd?.length) {
             for (const column of diff.columnsToAdd) {
@@ -166,14 +176,34 @@ export class SqlSchemaGenerator {
         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;
     }
+    /** `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));
+    }
     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.
+        // 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)));
         }
@@ -200,8 +230,11 @@ export class SqlSchemaGenerator {
         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`);
+        // 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.indexesToDrop?.length || diff.foreignKeysToDrop?.length) {
+            statements.push(`-- TODO: Manual reversal needed for dropped columns/indexes/foreign keys`);
         }
         return statements;
     }
@@ -283,7 +316,7 @@ export class SqlSchemaGenerator {
         const canonical = fieldOptionsToCanonical(field);
         // Special case for serial primary keys
         if (isAutoIncrement(field, field.isId === true)) {
-            return this.dialect.serialType;
+            return this.serialType(canonical);
         }
         return this.canonicalTypeToSql(canonical);
     }
@@ -337,16 +370,16 @@ export class SqlSchemaGenerator {
      * 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) {
+    diffSchema(entity, currentTable, desiredAst) {
         const meta = getMeta(entity);
         const tableName = this.resolveTableName(meta);
         const schema = this.resolveSchema(meta);
         if (!currentTable) {
             return { tableName, schema, type: 'create' };
         }
-        // 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);
+        // Keyed by the qualified name this generator resolves, which is the key the AST stores the table
+        // under.
+        const desired = (desiredAst ?? buildEntityAST(this, [entity], this.defaultForeignKeyAction)).getTable(tableName);
         if (!desired) {
             return undefined;
         }
@@ -367,10 +400,26 @@ export class SqlSchemaGenerator {
             to: tableDiff.primaryKeyDiff.expected,
             fromName: tableDiff.primaryKeyDiff.actualName,
         };
+        // This table's own constraints, which is what `outgoingRelations` holds on both sides: the
+        // entity's as the AST derived them, the database's as the introspector read them back.
+        //
+        // None at all where the engine cannot alter one: SQLite resolves foreign keys lazily and keeps
+        // them inline at CREATE time, and its only way to change one afterwards is the twelve-step table
+        // rebuild, which a sync does not do. Reporting a difference nothing can apply would throw on
+        // every sync of an entity that has a relation. `drift:check` still 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 &&
+            !foreignKeysToAdd.length &&
+            !foreignKeysToDrop.length &&
+            !foreignKeysToAlter.length &&
             !primaryKey) {
             return undefined;
         }
@@ -383,6 +432,9 @@ export class SqlSchemaGenerator {
             columnsToAlter: columnsToAlter.length ? columnsToAlter : undefined,
             columnsToDrop: columnsToDrop.length ? columnsToDrop : undefined,
             indexesToAdd: indexesToAdd.length ? indexesToAdd : undefined,
+            foreignKeysToAdd: foreignKeysToAdd.length ? foreignKeysToAdd : undefined,
+            foreignKeysToDrop: foreignKeysToDrop.length ? foreignKeysToDrop : undefined,
+            foreignKeysToAlter: foreignKeysToAlter.length ? foreignKeysToAlter : undefined,
         };
     }
     /**
@@ -413,7 +465,7 @@ export class SqlSchemaGenerator {
             name: col.name,
             // 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),
+            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type),
             nullable: col.nullable,
             defaultValue: col.defaultValue,
             isPrimaryKey: col.isPrimaryKey,
@@ -518,7 +570,7 @@ export class SqlSchemaGenerator {
     generateColumnFromNode(col) {
         return this.renderColumn({
             ...col,
-            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType : this.canonicalTypeToSql(col.type),
+            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type),
         });
     }
     /**
@@ -555,15 +607,13 @@ export class SqlSchemaGenerator {
     }
     generateAddForeignKeySql(tableName, foreignKey) {
         const fkCols = foreignKey.columns.map((c) => this.escapeId(c)).join(', ');
-        const refCols = foreignKey.referencesColumns.map((c) => this.escapeId(c)).join(', ');
-        const constraintName = foreignKey.name
-            ? this.escapeId(foreignKey.name)
-            : this.escapeId(derivedForeignKeyName(tableName, foreignKey.columns));
+        const refCols = foreignKey.references.columns.map((c) => this.escapeId(c)).join(', ');
+        const constraintName = this.escapeId(constraintNameOf(tableName, foreignKey));
         if (!this.features.foreignKeyAlter) {
             throw new TypeError(`Dialect ${this.dialect} does not support adding foreign keys to existing tables`);
         }
         return (`ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${constraintName} ` +
-            `FOREIGN KEY (${fkCols}) REFERENCES ${this.escapeId(foreignKey.referencesTable)} (${refCols}) ` +
+            `FOREIGN KEY (${fkCols}) REFERENCES ${this.escapeId(foreignKey.references.table)} (${refCols}) ` +
             `ON DELETE ${foreignKey.onDelete ?? this.defaultForeignKeyAction} ON UPDATE ${foreignKey.onUpdate ?? this.defaultForeignKeyAction};`);
     }
     generateDropForeignKeySql(tableName, constraintName) {
@@ -608,6 +658,31 @@ export class SqlSchemaGenerator {
             'for it. Recreate the table in a written migration.');
     }
 }
+/**
+ * What a constraint is called: its own name, or one derived from its columns where nothing named it.
+ * Shared by the add and the drop so a `DROP CONSTRAINT` names exactly what an `ADD CONSTRAINT` made.
+ */
+function constraintNameOf(tableName, foreignKey) {
+    return foreignKey.name ?? derivedForeignKeyName(tableName, foreignKey.columns);
+}
+/**
+ * A relationship node as the migration's own `ForeignKeySchema`. The node's `name` is kept rather
+ * than derived: on the database's side it is the only name a `DROP` can use, and on the entity's it
+ * is already the derived one. An unset action stays unset - the default belongs to the one place
+ * that spends it, `addForeignKeyStatements`.
+ */
+function foreignKeyOf(relation) {
+    return {
+        name: relation.name,
+        columns: relation.from.columns.map((column) => column.name),
+        references: {
+            table: qualifyName(relation.to.table.name, relation.to.table.schema),
+            columns: relation.to.columns.map((column) => column.name),
+        },
+        onDelete: relation.onDelete,
+        onUpdate: relation.onUpdate,
+    };
+}
 /**
  * The entities as an AST, named the way `generator` names things.
  *

package/dist/schema/schemaASTBuilder.d.ts

@@ -5,10 +5,11 @@
  * - Entity metadata (decorator-based entities)
  * - Database introspection results (TableSchema[])
  */
-import type { EntityMeta, FieldOptions, Type } from '../type/index.js';
+import type { EntityGetter } from '../type/entity.js';
+import type { EntityMeta, FieldMeta, FieldOptions, Type } from '../type/index.js';
 import type { NamingStrategy } from '../type/namingStrategy.js';
 import { SchemaAST } from './schemaAST.js';
-import { type ForeignKeyAction } from './types.js';
+import { type CanonicalType, type ForeignKeyAction } from './types.js';
 /**
  * Options for building SchemaAST from entities.
  */
@@ -31,3 +32,23 @@ export interface BuildSchemaASTOptions {
  * resolves against a table another entity declares, and an index against the columns of its own.
  */
 export declare function buildSchemaAST(entities: readonly Type<unknown>[], options?: BuildSchemaASTOptions): SchemaAST;
+/**
+ * Resolve the canonical type for a field, inheriting from the referenced
+ * entity's primary key when the field is a foreign-key reference
+ * (`@Field({ references: () => SomeEntity })`) with no explicit type of its
+ * own.
+ *
+ * Without this, a field like `creatorId?: UUID` (a bare TypeScript alias for
+ * `string`, erased at runtime) falls back to the generic string inference in
+ * {@link fieldOptionsToCanonical} and gets typed as TEXT/VARCHAR - producing a
+ * foreign key column whose type doesn't match the UUID primary key it
+ * references, which Postgres (and most databases) reject outright.
+ *
+ * `field.typeFromReference` (set by `defineField`, see entity/metadata/definition.ts)
+ * is what distinguishes "no type was given" from "the decorator explicitly set
+ * a type" - including explicit constructor overrides like `type: BigInt`, which
+ * a value-based check (e.g. `typeof field.type === 'string'`) would miss since
+ * reflection also produces constructor values like `String`/`Number`.
+ * `columnType` remains the unambiguous, always-respected explicit override.
+ */
+export declare function resolveColumnCanonicalType(field: FieldMeta, seen?: Set<EntityGetter>): CanonicalType;

package/dist/schema/schemaASTBuilder.js

@@ -7,6 +7,7 @@
  */
 import { getMeta, soleIdOf } from '../entity/metadata/definition.js';
 import { isSoleIdField } from '../util/field.util.js';
+import { isAutoIncrement } from '../util/field.util.js';
 import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
 import { fieldOptionsToCanonical } from './canonicalType.js';
 import { createTableNode, SchemaAST } from './schemaAST.js';
@@ -53,7 +54,7 @@ export function buildSchemaAST(entities, options = {}) {
  * reflection also produces constructor values like `String`/`Number`.
  * `columnType` remains the unambiguous, always-respected explicit override.
  */
-function resolveColumnCanonicalType(field, seen = new Set()) {
+export function resolveColumnCanonicalType(field, seen = new Set()) {
     const hasExplicitType = !!field.columnType || !field.typeFromReference;
     if (!hasExplicitType && field.references && !seen.has(field.references)) {
         seen.add(field.references);
@@ -96,7 +97,7 @@ function addTableFromEntity(ctx, meta) {
             nullable: isPrimaryKey ? false : (field.nullable ?? true),
             defaultValue: field.defaultValue,
             isPrimaryKey,
-            isAutoIncrement: field.autoIncrement ?? (isSoleKey && type.category === 'integer'),
+            isAutoIncrement: isAutoIncrement(field, isSoleKey),
             isUnique: field.unique ?? false,
             comment: field.comment,
             enum: field.enum,

package/dist/schema/schemaASTDiffer.d.ts

@@ -10,7 +10,7 @@
 import { type IndexFacet } from './indexDifferences.js';
 import type { SchemaAST } from './schemaAST.js';
 import type { CanonicalType } from './types.js';
-import type { SchemaDiffResult, TableDiff, TableNode } from './types.js';
+import type { RelationshipDiff, RelationshipNode, SchemaDiffResult, TableDiff, TableNode } from './types.js';
 /**
  * Options for schema diffing.
  */
@@ -60,3 +60,13 @@ export declare function diffSchemas(source: SchemaAST, target: SchemaAST, option
  * comparison serves both, so drift and migrations can no longer disagree about what has changed.
  */
 export declare function diffTable(source: TableNode, target: TableNode, options?: DiffOptions): TableDiff | undefined;
+/**
+ * Compare two lists of relationships.
+ *
+ * Lists rather than whole schemas, because a migration diffs one table: its two sides are that
+ * table's `outgoingRelations`, where `diffSchemas` passes the schema's every relationship.
+ *
+ * Matched by columns, never by name - the engine named every constraint that already exists, so
+ * pairing on names would report every hand-named one as a drop and an add.
+ */
+export declare function diffRelationshipNodes(source: readonly RelationshipNode[], target: readonly RelationshipNode[], opts?: DiffOptions): RelationshipDiff[];