uql-orm 0.44.0 → 0.45.0

package/README.md

@@ -7,9 +7,10 @@
   </picture>
 </a>
 
-<h3>The JSON-native ORM</h3>
+<h3>The JSON-native TypeScript ORM</h3>
 
-<p>Queries are plain JSON, typed to the leaf. Unified across SQL databases and MongoDB.</p>
+<p>UQL stands for Unified Query Language. With pure (type-safe) JSON queries, complex jobs can be done simply across SQL vendors + MongoDB. It got some inspiration from Mongo's best syntax.
+</p>
 
 <p>
   <a href="https://uql-orm.dev"><b>Website</b></a> ·

package/dist/dialect/abstractSqlDialect.d.ts

@@ -16,9 +16,9 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * declares over its columns as one named constraint. SQLite is the exception - see
      * {@link serialDeclaresPrimaryKey}.
      */
-    abstract readonly serialType: string;
+    abstract readonly autoIncrementSuffix: string;
     /**
-     * Whether {@link serialType} states `PRIMARY KEY` itself, so the table must not state it again.
+     * Whether {@link autoIncrementSuffix} states `PRIMARY KEY` itself, so the table must not state it again.
      *
      * True on SQLite alone, where `AUTOINCREMENT` is legal only in the exact phrase
      * `INTEGER PRIMARY KEY AUTOINCREMENT` - the key cannot be lifted out of the column there.

package/dist/dialect/abstractSqlDialect.js

@@ -11,7 +11,7 @@ import { resolveVectorCast } from './vectorCast.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
 export class AbstractSqlDialect extends VectorSqlDialect {
     /**
-     * Whether {@link serialType} states `PRIMARY KEY` itself, so the table must not state it again.
+     * Whether {@link autoIncrementSuffix} states `PRIMARY KEY` itself, so the table must not state it again.
      *
      * True on SQLite alone, where `AUTOINCREMENT` is legal only in the exact phrase
      * `INTEGER PRIMARY KEY AUTOINCREMENT` - the key cannot be lifted out of the column there.

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -24,7 +24,14 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     estimatedCount<E>(ctx: QueryContext, entity: Type<E>): void;
     /** `OFFSET` is only legal after a `LIMIT` here, so a bare `$skip` needs one. */
     pager(ctx: QueryContext, opts: QueryPager): void;
-    readonly serialType = "BIGINT UNSIGNED AUTO_INCREMENT";
+    /**
+     * Signed, though MySQL's own convention is `UNSIGNED`: a foreign key column takes its type from the
+     * key it points at, resolved through the *canonical* type, which has no way to know this string said
+     * `UNSIGNED`. The two then disagree and the engine refuses the constraint - the same trap knex hit
+     * (knex#6129) and MikroORM still carries (mikro-orm#5485). Signed is also the portable half: no
+     * other engine here has unsigned integers, so an `@Id` means one range everywhere.
+     */
+    readonly autoIncrementSuffix = "AUTO_INCREMENT";
     readonly escapeIdChar = "`";
     readonly tableOptions = "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4";
     readonly beginTransactionCommand = "START TRANSACTION";

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -63,7 +63,14 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         }
         super.pager(ctx, opts);
     }
-    serialType = 'BIGINT UNSIGNED AUTO_INCREMENT';
+    /**
+     * Signed, though MySQL's own convention is `UNSIGNED`: a foreign key column takes its type from the
+     * key it points at, resolved through the *canonical* type, which has no way to know this string said
+     * `UNSIGNED`. The two then disagree and the engine refuses the constraint - the same trap knex hit
+     * (knex#6129) and MikroORM still carries (mikro-orm#5485). Signed is also the portable half: no
+     * other engine here has unsigned integers, so an `@Id` means one range everywhere.
+     */
+    autoIncrementSuffix = 'AUTO_INCREMENT';
     escapeIdChar = '`';
     tableOptions = 'ENGINE=InnoDB DEFAULT CHARSET=utf8mb4';
     beginTransactionCommand = 'START TRANSACTION';

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -15,7 +15,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for Postgres-wire dialects. */
     protected readonly featureDefaults: DialectFeatures;
     readonly escapeIdChar = "\"";
-    readonly serialType: string;
+    readonly autoIncrementSuffix: string;
     readonly tableOptions = "";
     readonly beginTransactionCommand = "BEGIN";
     readonly commitTransactionCommand = "COMMIT";

package/dist/dialect/pgLikeSqlDialect.js

@@ -40,7 +40,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     // under heavy concurrent insert load (writes concentrate on one range); this default still beats
     // `SERIAL` (CockroachDB's `unique_rowid()`, a ~64-bit value that overflows JS's safe-integer
     // range). High-throughput CockroachDB users should override this per-entity with a UUID PK.
-    serialType = 'BIGINT GENERATED BY DEFAULT AS IDENTITY';
+    autoIncrementSuffix = 'GENERATED BY DEFAULT AS IDENTITY';
     tableOptions = '';
     beginTransactionCommand = 'BEGIN';
     commitTransactionCommand = 'COMMIT';

package/dist/migrate/builder/migrationBuilder.js

@@ -49,8 +49,7 @@ function addForeignKeyOperation(tableName, columns, target, options = {}) {
         foreignKey: {
             name: options.name,
             columns,
-            referencesTable: target.table,
-            referencesColumns: target.columns,
+            references: { table: target.table, columns: target.columns },
             onDelete: options.onDelete ?? 'NO ACTION',
             onUpdate: options.onUpdate ?? 'NO ACTION',
         },

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

@@ -16,6 +16,7 @@ export declare class TableBuilder implements ITableBuilder {
     private _foreignKeyBuilders;
     private _comment?;
     constructor(name: string);
+    /** Big, matching an entity's `@Id`: a key is spelled from this type, so it has to state the real one. */
     id(name?: string, options?: BaseColumnOptions): IColumnBuilder;
     integer(name: string, options?: BaseColumnOptions): IColumnBuilder;
     smallint(name: string, options?: BaseColumnOptions): IColumnBuilder;

package/dist/migrate/builder/tableBuilder.js

@@ -12,8 +12,8 @@ import { expr } from './expressions.js';
  */
 class TableForeignKeyBuilder {
     _columns;
-    _referencesTable;
-    _referencesColumns = [];
+    _referencedTable;
+    _referencedColumns = [];
     _onDelete = 'NO ACTION';
     _onUpdate = 'NO ACTION';
     _name;
@@ -21,8 +21,8 @@ class TableForeignKeyBuilder {
         this._columns = columns;
     }
     references(table, columns) {
-        this._referencesTable = table;
-        this._referencesColumns = columns;
+        this._referencedTable = table;
+        this._referencedColumns = columns;
         return this;
     }
     onDelete(action) {
@@ -41,13 +41,12 @@ class TableForeignKeyBuilder {
      * Build the foreign key definition.
      */
     build() {
-        if (!this._referencesTable)
+        if (!this._referencedTable)
             return undefined;
         return {
             name: this._name,
             columns: this._columns,
-            referencesTable: this._referencesTable,
-            referencesColumns: this._referencesColumns,
+            references: { table: this._referencedTable, columns: this._referencedColumns },
             onDelete: this._onDelete,
             onUpdate: this._onUpdate,
         };
@@ -66,8 +65,9 @@ export class TableBuilder {
     constructor(name) {
         this._name = name;
     }
+    /** Big, matching an entity's `@Id`: a key is spelled from this type, so it has to state the real one. */
     id(name = 'id', options = {}) {
-        return this.add(name, { category: 'integer' }, { ...options, primaryKey: true, autoIncrement: true });
+        return this.add(name, { category: 'integer', size: 'big' }, { ...options, primaryKey: true, autoIncrement: true });
     }
     integer(name, options) {
         return this.add(name, { category: 'integer' }, options);
@@ -217,8 +217,7 @@ export class TableBuilder {
                 foreignKeys.push({
                     name: col.foreignKey.name,
                     columns: [col.name],
-                    referencesTable: col.foreignKey.table,
-                    referencesColumns: col.foreignKey.columns,
+                    references: { table: col.foreignKey.table, columns: col.foreignKey.columns },
                     onDelete: col.foreignKey.onDelete,
                     onUpdate: col.foreignKey.onUpdate,
                 });

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

@@ -6,6 +6,7 @@
  */
 import type { CanonicalType, ForeignKeyAction } from '../../schema/types.js';
 import type { IndexColumnInput, IndexOptions, IndexSchema } from '../../type/index.js';
+import type { ForeignKeySchema } from '../../type/migration.js';
 /**
  * Foreign key reference options.
  */
@@ -124,27 +125,10 @@ export interface TableDefinition {
     /** Index definitions */
     indexes: IndexSchema[];
     /** Foreign key definitions at table level */
-    foreignKeys: TableForeignKeyDefinition[];
+    foreignKeys: ForeignKeySchema[];
     /** Table comment */
     comment?: string;
 }
-/**
- * Table-level foreign key (for composite FKs).
- */
-export interface TableForeignKeyDefinition {
-    /** Constraint name */
-    name?: string;
-    /** Local columns */
-    columns: string[];
-    /** Referenced table */
-    referencesTable: string;
-    /** Referenced columns */
-    referencesColumns: string[];
-    /** Action on delete */
-    onDelete: ForeignKeyAction;
-    /** Action on update */
-    onUpdate: ForeignKeyAction;
-}
 /**
  * Type of migration operation.
  */
@@ -238,7 +222,7 @@ export interface DropIndexOperation extends MigrationOperation {
 export interface AddForeignKeyOperation extends MigrationOperation {
     type: 'addForeignKey';
     tableName: string;
-    foreignKey: TableForeignKeyDefinition;
+    foreignKey: ForeignKeySchema;
 }
 /**
  * Drop foreign key operation.

package/dist/migrate/generator/definitionToNode.js

@@ -40,8 +40,8 @@ export function tableDefinitionToNode(def) {
                 columns: fkDef.columns.map((name) => columns.get(name)).filter((c) => c !== undefined),
             },
             to: {
-                table: { name: fkDef.referencesTable },
-                columns: fkDef.referencesColumns.map((name) => ({ name })),
+                table: { name: fkDef.references.table },
+                columns: fkDef.references.columns.map((name) => ({ name })),
             },
             onDelete: fkDef.onDelete,
             onUpdate: fkDef.onUpdate,

package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts

@@ -1,9 +1,6 @@
+import type { ForeignKeyAction } from '../../schema/types.js';
 import type { ColumnSchema, ForeignKeySchema, IndexSchema, QuerierPool, RawRow, SchemaIntrospector, SqlQuerier, TableSchema } from '../../type/index.js';
 import { BaseSqlIntrospector } from './baseSqlIntrospector.js';
-/**
- * Referential action type for foreign key constraints.
- */
-export type ReferentialAction = 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
 /**
  * Reads the rows of one statement while introspecting a table.
  *
@@ -72,7 +69,7 @@ export declare abstract class AbstractSqlSchemaIntrospector extends BaseSqlIntro
     /**
      * Normalize referential action string to standard type.
      */
-    protected normalizeReferentialAction(action: string): ReferentialAction | undefined;
+    protected normalizeReferentialAction(action: string): ForeignKeyAction | undefined;
     /**
      * Convert bigint/null values to number safely.
      */

package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js

@@ -131,6 +131,8 @@ export class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector {
                 return 'RESTRICT';
             case 'NO ACTION':
                 return 'NO ACTION';
+            case 'SET DEFAULT':
+                return 'SET DEFAULT';
             default:
                 return undefined;
         }

package/dist/migrate/introspection/baseSqlIntrospector.js

@@ -1,6 +1,7 @@
 import { canonicalColumnType } from '../../schema/canonicalType.js';
 import { createTableNode, SchemaAST } from '../../schema/schemaAST.js';
 import { escapeSqlId } from '../../util/index.js';
+import { derivedForeignKeyName } from '../../util/sql.util.js';
 /**
  * Base class for SQL introspectors with shared AST building logic.
  */
@@ -83,14 +84,14 @@ export class BaseSqlIntrospector {
             if (!fromTable)
                 continue;
             for (const fk of schema.foreignKeys) {
-                const toTable = tableNodes.get(fk.referencedTable);
+                const toTable = tableNodes.get(fk.references.table);
                 if (!toTable)
                     continue;
                 const fromColumns = fk.columns.flatMap((name) => fromTable.columns.get(name) ?? []);
-                const toColumns = fk.referencedColumns.flatMap((name) => toTable.columns.get(name) ?? []);
+                const toColumns = fk.references.columns.flatMap((name) => toTable.columns.get(name) ?? []);
                 if (fromColumns.length > 0 && toColumns.length > 0) {
                     const rel = {
-                        name: fk.name,
+                        name: fk.name ?? derivedForeignKeyName(schema.name, fk.columns),
                         type: fromColumns[0].isUnique ? 'OneToOne' : 'ManyToOne',
                         from: { table: fromTable, columns: fromColumns },
                         to: { table: toTable, columns: toColumns },

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -123,8 +123,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return results.map((row) => ({
             name: row.constraint_name,
             columns: (row.columns || '').split(','),
-            referencedTable: row.referenced_table,
-            referencedColumns: (row.referenced_columns || '').split(','),
+            references: { table: row.referenced_table, columns: (row.referenced_columns || '').split(',') },
             onDelete: this.normalizeReferentialAction(row.delete_rule),
             onUpdate: this.normalizeReferentialAction(row.update_rule),
         }));

package/dist/migrate/introspection/postgresIntrospector.js

@@ -204,8 +204,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return results.map((row) => ({
             name: row.constraint_name,
             columns: row.columns,
-            referencedTable: row.referenced_table,
-            referencedColumns: row.referenced_columns,
+            references: { table: row.referenced_table, columns: row.referenced_columns },
             onDelete: this.normalizeReferentialAction(row.delete_rule),
             onUpdate: this.normalizeReferentialAction(row.update_rule),
         }));

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -113,8 +113,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
                 // 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),
+                references: { table: first.table, columns: rows.map((r) => r.to) },
                 onDelete: this.normalizeReferentialAction(first.on_delete),
                 onUpdate: this.normalizeReferentialAction(first.on_update),
             };

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);
             }
@@ -390,7 +394,9 @@ export class Migrator {
     }
     /** The same for one entity against the table it already has, and nothing where the two agree. */
     alterFromEntity(entity, table, options) {
-        const diff = this.generator.diffSchema(entity, table);
+        // 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. */
@@ -480,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;
         }

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.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';
@@ -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[];

package/dist/schema/schemaASTDiffer.js

@@ -65,7 +65,9 @@ export function diffSchemas(source, target, options = {}) {
     const indexDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.indexDiffs ?? []);
     const primaryKeyDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.primaryKeyDiff ?? []);
     // Relationships span tables, so they are compared over the whole schema rather than per table.
-    const relationshipDiffs = opts.compareRelationships ? diffRelationships(source, target, opts) : [];
+    const relationshipDiffs = opts.compareRelationships
+        ? diffRelationshipNodes(source.relationships, target.relationships, opts)
+        : [];
     const hasDifferences = tablesToCreate.length > 0 ||
         tablesToDrop.length > 0 ||
         tablesToAlter.length > 0 ||
@@ -167,7 +169,7 @@ function diffColumn(tableName, source, target, opts) {
     const differences = [];
     // Two things a key column implies rather than states, and catalogues report inconsistently: its
     // type, which is the dialect's serial spelling rather than one the entity chose and does not round
-    // trip (`BIGINT UNSIGNED AUTO_INCREMENT` reads back as `BIGINT(20) UNSIGNED`), and its nullability,
+    // trip (`BIGINT AUTO_INCREMENT` reads back as `BIGINT(20)`), and its nullability,
     // which is NOT NULL in every engine whatever is reported - SQLite's `PRAGMA table_info` says
     // `notnull: 0` for the `INTEGER PRIMARY KEY` that is the table's own rowid. Comparing either asked
     // to rewrite the column on every sync, and on SQLite, which cannot alter one at all, failed
@@ -179,6 +181,14 @@ function diffColumn(tableName, source, target, opts) {
     if (typeChanged) {
         differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
     }
+    // Signedness is the one thing compared on a generated key, because it is the one part of the serial
+    // spelling that does round trip - and a key left unsigned refuses every foreign key pointing at it,
+    // since the referencing column takes its type from the canonical one, which is signed. Without this
+    // a database created before the serial became signed could never gain a foreign key.
+    const signednessChanged = generatedType && !!source.type.unsigned !== !!target.type.unsigned;
+    if (signednessChanged) {
+        differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
+    }
     if (!impliedNotNull && source.nullable !== target.nullable) {
         differences.push(`nullable: ${target.nullable} → ${source.nullable}`);
     }
@@ -206,7 +216,7 @@ function diffColumn(tableName, source, target, opts) {
         // Only the type this diff actually reports: a column altered for its default carries no data loss,
         // and a generated key's type - never compared above - reads as unsigned against an entity that
         // cannot say so.
-        isBreaking: typeChanged && isBreakingTypeChange(target.type, source.type),
+        isBreaking: (typeChanged || signednessChanged) && isBreakingTypeChange(target.type, source.type),
         description: differences.join(', '),
     };
 }
@@ -228,11 +238,17 @@ function diffIndex(tableName, source, target, facets) {
     };
 }
 /**
- * Compare relationships at the schema level.
+ * 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.
  */
-function diffRelationships(source, target, opts) {
-    const normalizeName = nameNormalizer(opts);
-    const { created, dropped, matched } = matchByKey(source.relationships, target.relationships, (relation) => getRelationshipKey(relation, normalizeName));
+export function diffRelationshipNodes(source, target, opts = {}) {
+    const normalizeName = nameNormalizer({ ...DEFAULT_OPTIONS, ...opts });
+    const { created, dropped, matched } = matchByKey(source, target, (relation) => getRelationshipKey(relation, normalizeName));
     return [
         ...created.map((relation) => ({
             ...relationEnds(relation),

package/dist/schema/types.d.ts

@@ -272,14 +272,29 @@ export interface IndexDiff {
 /**
  * Difference between two relationship definitions.
  */
-export interface RelationshipDiff {
+interface RelationshipDiffBase {
     readonly name: string;
     readonly fromTable: string;
     readonly toTable: string;
-    readonly type: 'create' | 'drop' | 'alter';
-    readonly expected?: RelationshipNode;
-    readonly actual?: RelationshipNode;
 }
+/**
+ * Difference between two relationships, shaped like {@link ColumnDiff} and for the same reason: which
+ * node is present follows from the kind of difference, so a reader never asserts its way past an
+ * `undefined` the kind had already ruled out.
+ */
+export type RelationshipDiff = RelationshipDiffBase & ({
+    readonly type: 'create';
+    readonly expected: RelationshipNode;
+    readonly actual?: undefined;
+} | {
+    readonly type: 'drop';
+    readonly expected?: undefined;
+    readonly actual: RelationshipNode;
+} | {
+    readonly type: 'alter';
+    readonly expected: RelationshipNode;
+    readonly actual: RelationshipNode;
+});
 /**
  * Complete diff between two schemas.
  */

package/dist/sqlite/sqliteDialect.d.ts

@@ -5,7 +5,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     protected readonly featureDefaults: DialectFeatures;
     readonly dialectName = "sqlite";
     readonly escapeIdChar = "`";
-    readonly serialType = "INTEGER PRIMARY KEY AUTOINCREMENT";
+    readonly autoIncrementSuffix = "PRIMARY KEY AUTOINCREMENT";
     readonly serialDeclaresPrimaryKey = true;
     readonly tableOptions = "";
     readonly beginTransactionCommand = "BEGIN TRANSACTION";

package/dist/sqlite/sqliteDialect.js

@@ -22,7 +22,7 @@ export class SqliteDialect extends AbstractSqlDialect {
     };
     dialectName = 'sqlite';
     escapeIdChar = '`';
-    serialType = 'INTEGER PRIMARY KEY AUTOINCREMENT';
+    autoIncrementSuffix = 'PRIMARY KEY AUTOINCREMENT';
     // `AUTOINCREMENT` is only legal in that exact phrase, so the key cannot be lifted to table level.
     serialDeclaresPrimaryKey = true;
     tableOptions = '';

package/dist/type/entity.d.ts

@@ -232,7 +232,7 @@ export type RelationValue<E> = E[RelationKey<E>];
 /**
  * SQL numeric column types
  */
-export type NumericColumnType = 'int' | 'integer' | 'tinyint' | 'smallint' | 'bigint' | 'float' | 'float4' | 'float8' | 'double' | 'double precision' | 'decimal' | 'numeric' | 'real' | 'serial' | 'smallserial' | 'bigserial';
+export type NumericColumnType = 'int' | 'integer' | 'tinyint' | 'smallint' | 'bigint' | 'float' | 'float4' | 'float8' | 'double' | 'double precision' | 'decimal' | 'numeric' | 'real';
 /**
  * SQL string column types
  */

package/dist/type/migration.d.ts

@@ -1,5 +1,5 @@
 import type { VectorCast } from '../dialect/vectorCast.js';
-import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from '../migrate/builder/types.js';
+import type { FullColumnDefinition, TableDefinition } from '../migrate/builder/types.js';
 import type { IndexFacet } from '../schema/indexDifferences.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import type { ForeignKeyAction, IndexNode, IndexType, TableNode } from '../schema/types.js';
@@ -161,15 +161,25 @@ export interface IndexSchema extends VectorIndexOptions {
     readonly vectorType?: VectorCast;
 }
 /**
- * Represents a foreign key constraint
+ * A foreign key constraint, wherever one is described: read back by introspection, planned into a
+ * {@link SchemaDiff}, or declared through the migration builder. One shape for all three - they
+ * differed only in spelling, and the translation between them was pure overhead.
  */
 export interface ForeignKeySchema {
-    readonly name: string;
+    /** Absent when nothing named it, which the generator fills in with `derivedForeignKeyName`. */
+    readonly name?: string;
     readonly columns: string[];
-    readonly referencedTable: string;
-    readonly referencedColumns: string[];
-    readonly onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
-    readonly onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    /**
+     * The far end, as one thing. Same shape and same name as everywhere else a relationship's target is
+     * described - `@Field({ references })`, `addForeignKey`'s `target`, a `RelationshipNode`'s `to` -
+     * so nothing has to be destructured on the way between them.
+     */
+    readonly references: {
+        readonly table: string;
+        readonly columns: string[];
+    };
+    readonly onDelete?: ForeignKeyAction;
+    readonly onUpdate?: ForeignKeyAction;
 }
 /**
  * Represents a difference between current and desired schema
@@ -204,7 +214,17 @@ export interface SchemaDiff {
     readonly indexesToAdd?: IndexSchema[];
     readonly indexesToDrop?: string[];
     readonly foreignKeysToAdd?: ForeignKeySchema[];
+    /** Dropped under the name the *database* reported, which is the only name a `DROP` can use. */
     readonly foreignKeysToDrop?: string[];
+    /**
+     * A constraint whose referential actions changed. Its own field rather than a pair of entries in
+     * the two above, because no engine alters an action in place: it is a drop and an add that have to
+     * travel together, and safe mode has to hold back both or neither.
+     */
+    readonly foreignKeysToAlter?: {
+        readonly from: ForeignKeySchema;
+        readonly to: ForeignKeySchema;
+    }[];
 }
 /**
  * What every sync entry point takes: `safe` keeps it additive, `drop` lets it remove a column, and
@@ -278,8 +298,21 @@ export interface SchemaGenerator {
     getSqlType(fieldOptions: FieldOptions): string;
     /**
      * Compare an entity with a database table node and return the differences.
+     *
+     * `desiredAst` is the entity side, from {@link buildAST}, and must span every entity a foreign key
+     * on this table points at: a relation whose target is absent resolves to nothing, so the constraint
+     * reads as missing from both sides, which is a match and no statement. Defaults to this entity
+     * alone, which is right only where it has no relations.
+     */
+    diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
+    /**
+     * The entity side as an AST, to hand to every {@link diffSchema} of one run - building it per
+     * entity instead is quadratic in the number of entities.
+     *
+     * Optional because not every generator compares one: MongoDB has no foreign keys and diffs only
+     * indexes, so it neither implements this nor reads the argument.
      */
-    diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined): SchemaDiff | undefined;
+    buildAST?(entities: readonly Type<unknown>[]): SchemaAST;
     /**
      * The table's key: {@link resolveTableAlias} behind {@link resolveSchema}, which is how a
      * `SchemaAST` stores it and how a diff finds it again.
@@ -326,7 +359,7 @@ export interface SqlDdlGenerator extends SchemaGenerator {
     /** Generate RENAME COLUMN statement */
     generateRenameColumnSql(tableName: string, oldName: string, newName: string): string;
     /** Generate ADD FOREIGN KEY statement */
-    generateAddForeignKeySql(tableName: string, foreignKey: TableForeignKeyDefinition): string;
+    generateAddForeignKeySql(tableName: string, foreignKey: ForeignKeySchema): string;
     /** Generate DROP FOREIGN KEY statement */
     generateDropForeignKeySql(tableName: string, constraintName: string): string;
 }

package/dist/util/field.util.d.ts

@@ -12,7 +12,7 @@ export type ColumnFamily = 'string' | 'numeric' | 'boolean' | 'date' | 'json' |
  * restates the unions: the compile-time side of the same question reads them directly.
  */
 export declare const COLUMN_TYPES_BY_FAMILY: {
-    readonly numeric: readonly ["int", "integer", "tinyint", "smallint", "bigint", "float", "float4", "float8", "double", "double precision", "decimal", "numeric", "real", "serial", "smallserial", "bigserial"];
+    readonly numeric: readonly ["int", "integer", "tinyint", "smallint", "bigint", "float", "float4", "float8", "double", "double precision", "decimal", "numeric", "real"];
     readonly string: readonly ["char", "varchar", "text", "uuid"];
     readonly date: readonly ["date", "time", "datetime", "timestamp", "timestamptz"];
     readonly json: readonly ["json", "jsonb"];
@@ -33,6 +33,11 @@ export declare function columnFamily(type: unknown): ColumnFamily | undefined;
  */
 export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOptions): boolean;
 /**
- * Checks if a field should be treated as auto-incrementing.
+ * Whether the database generates this column's value.
+ *
+ * The only answer: the schema AST asked it separately and disagreed on three counts - it ignored
+ * `onInsert`, so a key the application generates was still emitted `AUTO_INCREMENT`, and it ignored
+ * `columnType`, where this one used to let *any* declared width suppress the whole inference. A key
+ * that states its width is still a generated key; one that states how it is filled is not.
  */
 export declare function isAutoIncrement(field: FieldOptions, isPrimaryKey: boolean): boolean;

package/dist/util/field.util.js

@@ -20,9 +20,6 @@ export const COLUMN_TYPES_BY_FAMILY = {
         'decimal',
         'numeric',
         'real',
-        'serial',
-        'smallserial',
-        'bigserial',
     ],
     string: ['char', 'varchar', 'text', 'uuid'],
     date: ['date', 'time', 'datetime', 'timestamp', 'timestamptz'],
@@ -62,15 +59,15 @@ export function isSoleIdField(meta, field) {
     return field.isId === true && meta.ids.length === 1;
 }
 /**
- * Checks if a field should be treated as auto-incrementing.
+ * Whether the database generates this column's value.
+ *
+ * The only answer: the schema AST asked it separately and disagreed on three counts - it ignored
+ * `onInsert`, so a key the application generates was still emitted `AUTO_INCREMENT`, and it ignored
+ * `columnType`, where this one used to let *any* declared width suppress the whole inference. A key
+ * that states its width is still a generated key; one that states how it is filled is not.
  */
 export function isAutoIncrement(field, isPrimaryKey) {
-    if (field.autoIncrement === false)
-        return false;
-    if (field.autoIncrement)
-        return true;
-    const colType = field.columnType?.toLowerCase();
-    if (colType === 'serial' || colType === 'smallserial' || colType === 'bigserial')
-        return true;
-    return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.columnType;
+    if (field.autoIncrement !== undefined)
+        return field.autoIncrement;
+    return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert;
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uql-orm",
   "homepage": "https://uql-orm.dev",
-  "description": "JSON-native TypeScript ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
+  "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "type": "module",
   "engines": {
     "node": ">=24"