uql-orm 0.42.0 → 0.43.0

package/dist/querier/relationCount.js

@@ -1,7 +1,7 @@
 import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { getMeta, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
-import { asSelectMap, getKeys, parentJoins, parentsIn, rowKey, targetKeyColumns, } from '../util/index.js';
+import { asSelectMap, getKeys, joinedColumns, joinedRowKey, parentJoins, parentRowKey, parentsIn, targetKeyColumns, } from '../util/index.js';
 /**
  * A `$count` groups its tallies by the parent's id, so the id has to outlive the projection - the
  * same reason populating a relation keeps it. A whitelisting `$select` gains the key and an
@@ -50,6 +50,9 @@ export async function fillRelationCounts(querier, entity, payload, count) {
         return;
     }
     const meta = getMeta(entity);
+    // The tallies come back keyed by the columns *this relation* joins from, so its `joins` are kept
+    // beside them: reading the parent through `meta.ids` instead matches only where the two coincide,
+    // which is a to-many and nothing else.
     const counted = new Map();
     for (const relKey of getKeys(count)) {
         const value = count[relKey];
@@ -59,15 +62,14 @@ export async function fillRelationCounts(querier, entity, payload, count) {
         }
         const where = typeof value === 'object' ? value.$where : undefined;
         const joins = parentJoins(relOpts, meta.ids.length);
-        counted.set(relKey, await countPerParent(querier, relOpts, joins, payload, where));
+        counted.set(relKey, { joins, byParent: await countPerParent(querier, relOpts, joins, payload, where) });
     }
     for (const parent of payload) {
-        const id = rowKey(meta.ids.map((key) => parent[key]));
         const row = {};
-        for (const [relKey, byParent] of counted) {
+        for (const [relKey, { joins, byParent }] of counted) {
             // A parent the grouped result has no row for matched nothing, which is a zero rather than a
             // gap: `_count` names what the caller asked to count, so every key it asked for is present.
-            row[relKey] = byParent[id] ?? 0;
+            row[relKey] = byParent[parentRowKey(joins, parent)] ?? 0;
         }
         parent[COUNT_RESULT_KEY] = row;
     }
@@ -101,13 +103,13 @@ async function countThroughPerParent(querier, relOpts, throughEntity, joins, par
 /** `SELECT <keys>, COUNT(*) ... GROUP BY <keys>`, as a lookup from parent key to tally. */
 async function groupedCount(querier, entity, joins, where) {
     const $agg = { [COUNT_ALIAS]: { $count: '*' } };
-    const $group = Object.fromEntries(joins.map(({ joined }) => [joined, true]));
+    const $group = joinedColumns(joins);
     const rows = await querier.aggregate(entity, { $group, $agg, $where: where });
     const byParent = {};
     for (const row of rows) {
         // Keyed by every joined column, which is how a tally finds the one parent whose whole key it
         // matches - and how the rows an over-selecting `IN` brought back find no parent at all.
-        byParent[rowKey(joins.map(({ joined }) => row[joined]))] = Number(row[COUNT_ALIAS]);
+        byParent[joinedRowKey(joins, row)] = Number(row[COUNT_ALIAS]);
     }
     return byParent;
 }

package/dist/schema/canonicalType.d.ts

@@ -36,17 +36,32 @@ export declare function canonicalToSql(type: CanonicalType, dialect: AbstractDia
  * Convert a canonical type to a TypeScript type string.
  */
 export declare function canonicalToTypeScript(type: CanonicalType): string;
+/**
+ * A type as `dialect` would actually store it: rendered to that engine's SQL and read back.
+ *
+ * Several canonical types share one storage type per engine - a `boolean` is `TINYINT(1)` on MySQL and
+ * `INTEGER` on SQLite - and only the engine settles an unstated bound, since `VARCHAR` is 255 on MySQL
+ * and `TEXT` on Postgres. Both paths that diff a schema compare through this, so a migration and a
+ * drift report cannot disagree about what changed.
+ */
+export declare function engineType(dialect: AbstractDialect): (type: CanonicalType) => CanonicalType;
 /**
  * Convert UQL FieldOptions to a canonical type.
  */
-export declare function fieldOptionsToCanonical(options: FieldOptions, tsType?: unknown): CanonicalType;
+export declare function fieldOptionsToCanonical(options: FieldOptions): CanonicalType;
 /**
- * Compare two canonical types for equality.
- * Used for schema diffing.
+ * Compare two canonical types for equality. Used for schema diffing.
+ *
+ * Nothing here guesses an engine's own default for an unstated bound: `VARCHAR` is 255 on MySQL and
+ * `TEXT` on Postgres, and a comparison that assumed either was blind to that difference on the other.
+ * `DiffOptions.normalizeType` is what settles it, by putting both sides through the engine first.
  */
 export declare function areTypesEqual(a: CanonicalType, b: CanonicalType): boolean;
 /**
- * Check if changing from type A to type B could cause data loss.
+ * Whether changing a column from one type to the other can lose what it holds.
+ *
+ * An unstated bound is the engine's widest, so stating one for the first time narrows the column just
+ * as lowering one does: `TEXT` to `VARCHAR(50)` truncates, and `NUMERIC` to `NUMERIC(5,2)` rounds.
  */
 export declare function isBreakingTypeChange(from: CanonicalType, to: CanonicalType): boolean;
 /**

package/dist/schema/canonicalType.js

@@ -6,6 +6,7 @@
  * - Canonical types (dialect-agnostic)
  * - TypeScript types (for entity generation)
  */
+import { columnFamily } from '../util/field.util.js';
 /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
 export function isVectorCategory(category) {
     return category === 'vector' || category === 'halfvec' || category === 'sparsevec';
@@ -108,66 +109,57 @@ const PG_TYPE_MAP = {
     halfvec: 'HALFVEC',
     sparsevec: 'SPARSEVEC',
 };
+const MYSQL_SCALAR_MAP = {
+    integer: 'INT',
+    float: 'FLOAT',
+    decimal: 'DECIMAL',
+    string: 'VARCHAR',
+    boolean: 'TINYINT(1)',
+    date: 'DATE',
+    time: 'TIME',
+    timestamp: 'DATETIME',
+    json: 'JSON',
+    uuid: 'CHAR(36)',
+    blob: 'BLOB',
+};
+const SQLITE_SCALAR_MAP = {
+    integer: 'INTEGER',
+    float: 'REAL',
+    decimal: 'REAL',
+    string: 'TEXT',
+    boolean: 'INTEGER',
+    date: 'TEXT',
+    time: 'TEXT',
+    timestamp: 'TEXT',
+    json: 'TEXT',
+    uuid: 'TEXT',
+    blob: 'BLOB',
+};
+/** MongoDB uses BSON types, not SQL types. These are placeholders for compatibility. */
+const MONGO_SCALAR_MAP = {
+    integer: 'int',
+    float: 'double',
+    decimal: 'decimal128',
+    string: 'string',
+    boolean: 'bool',
+    date: 'date',
+    time: 'string',
+    timestamp: 'timestamp',
+    json: 'object',
+    uuid: 'binData',
+    blob: 'binData',
+};
+/** Every engine's scalars, and the one spelling it gives all three vector widths. */
 const CANONICAL_TO_SQL = {
     postgres: PG_TYPE_MAP,
     // CockroachDB's VECTOR is native, no extension needed.
     cockroachdb: withVectorType(PG_SCALAR_MAP, 'VECTOR'),
-    mysql: withVectorType({
-        integer: 'INT',
-        float: 'FLOAT',
-        decimal: 'DECIMAL',
-        string: 'VARCHAR',
-        boolean: 'TINYINT(1)',
-        date: 'DATE',
-        time: 'TIME',
-        timestamp: 'DATETIME',
-        json: 'JSON',
-        uuid: 'CHAR(36)',
-        blob: 'BLOB',
-    }, 
     // MySQL does have a `VECTOR` type (26.7), but no distance function outside HeatWave and no vector
     // index, so JSON keeps the column queryable with the JSON operators and needs no conversion.
-    'JSON'),
-    sqlite: withVectorType({
-        integer: 'INTEGER',
-        float: 'REAL',
-        decimal: 'REAL',
-        string: 'TEXT',
-        boolean: 'INTEGER',
-        date: 'TEXT',
-        time: 'TEXT',
-        timestamp: 'TEXT',
-        json: 'TEXT',
-        uuid: 'TEXT',
-        blob: 'BLOB',
-    }, 'TEXT'),
-    mariadb: withVectorType({
-        integer: 'INT',
-        float: 'FLOAT',
-        decimal: 'DECIMAL',
-        string: 'VARCHAR',
-        boolean: 'TINYINT(1)',
-        date: 'DATE',
-        time: 'TIME',
-        timestamp: 'DATETIME',
-        json: 'JSON',
-        uuid: 'CHAR(36)',
-        blob: 'BLOB',
-    }, 'VECTOR'),
-    // MongoDB uses BSON types, not SQL types. These are placeholders for compatibility.
-    mongodb: withVectorType({
-        integer: 'int',
-        float: 'double',
-        decimal: 'decimal128',
-        string: 'string',
-        boolean: 'bool',
-        date: 'date',
-        time: 'string',
-        timestamp: 'timestamp',
-        json: 'object',
-        uuid: 'binData',
-        blob: 'binData',
-    }, 'array'),
+    mysql: withVectorType(MYSQL_SCALAR_MAP, 'JSON'),
+    mariadb: withVectorType(MYSQL_SCALAR_MAP, 'VECTOR'),
+    sqlite: withVectorType(SQLITE_SCALAR_MAP, 'TEXT'),
+    mongodb: withVectorType(MONGO_SCALAR_MAP, 'array'),
 };
 /**
  * Size variant modifiers for SQL types.
@@ -239,7 +231,7 @@ const CANONICAL_TO_TS = {
     timestamp: 'Date',
     json: 'unknown',
     uuid: 'string',
-    blob: 'Buffer',
+    blob: 'Uint8Array',
     vector: 'number[]',
     halfvec: 'number[]',
     sparsevec: 'number[]',
@@ -387,136 +379,94 @@ function formatDecimalSqlType(type, dialect, baseType) {
 export function canonicalToTypeScript(type) {
     return CANONICAL_TO_TS[type.category];
 }
+/**
+ * A type as `dialect` would actually store it: rendered to that engine's SQL and read back.
+ *
+ * Several canonical types share one storage type per engine - a `boolean` is `TINYINT(1)` on MySQL and
+ * `INTEGER` on SQLite - and only the engine settles an unstated bound, since `VARCHAR` is 255 on MySQL
+ * and `TEXT` on Postgres. Both paths that diff a schema compare through this, so a migration and a
+ * drift report cannot disagree about what changed.
+ */
+export function engineType(dialect) {
+    return (type) => sqlToCanonical(canonicalToSql(type, dialect));
+}
 /**
  * Convert UQL FieldOptions to a canonical type.
  */
-export function fieldOptionsToCanonical(options, tsType) {
-    // If explicit columnType is specified, use it
+export function fieldOptionsToCanonical(options) {
+    // An explicit column type is read exactly as an introspected one is: the SQL type, plus whatever
+    // bounds are stated beside it.
     if (options.columnType) {
-        const base = sqlToCanonical(options.columnType);
-        return {
-            ...base,
-            length: options.length ?? base.length,
-            precision: options.precision ?? base.precision,
-            scale: options.scale ?? base.scale,
-        };
-    }
-    // Infer from type (could be constructor or string)
-    const type = options.type || tsType;
-    if (type === String) {
-        return {
-            category: 'string',
-            length: options.length,
-        };
-    }
-    if (type === Number) {
-        if (options.precision || options.scale) {
-            return {
-                category: 'decimal',
-                precision: options.precision,
-                scale: options.scale,
-            };
-        }
-        // BIGINT for every `Number`, key or not: a 32-bit column is a migration waiting to happen, and
-        // the pools decode it back to a JS number at the wire (see `pgNumericTypes`).
-        return { category: 'integer', size: 'big' };
-    }
-    if (type === Boolean) {
-        return { category: 'boolean' };
-    }
-    if (type === Date) {
-        return { category: 'timestamp' };
-    }
-    if (type === BigInt) {
-        return { category: 'integer', size: 'big' };
+        return canonicalColumnType(options.columnType, options);
     }
+    // Infer from type, which is a SQL type string or one of the constructors.
+    const { type } = options;
     if (typeof type === 'string') {
         const canonical = sqlToCanonical(type);
         // Propagate explicit dimensions into CanonicalType.length for vector types
-        if (options.dimensions && isVectorCategory(canonical.category)) {
-            return { ...canonical, length: options.dimensions };
-        }
-        return canonical;
+        return options.dimensions && isVectorCategory(canonical.category)
+            ? { ...canonical, length: options.dimensions }
+            : canonical;
+    }
+    switch (columnFamily(type)) {
+        case 'numeric':
+            // BIGINT for every `Number` without a scale, key or not: a 32-bit column is a migration waiting
+            // to happen, and the pools decode it back to a JS number at the wire (see `pgNumericTypes`).
+            return type === Number && (options.precision || options.scale)
+                ? { category: 'decimal', precision: options.precision, scale: options.scale }
+                : { category: 'integer', size: 'big' };
+        case 'boolean':
+            return { category: 'boolean' };
+        case 'date':
+            return { category: 'timestamp' };
+        // `String`, and anything a reflected type left unrecognised.
+        default:
+            return { category: 'string', length: options.length };
     }
-    // Default to string
-    return { category: 'string', length: options.length };
 }
 /**
- * Compare two canonical types for equality.
- * Used for schema diffing.
+ * Compare two canonical types for equality. Used for schema diffing.
+ *
+ * Nothing here guesses an engine's own default for an unstated bound: `VARCHAR` is 255 on MySQL and
+ * `TEXT` on Postgres, and a comparison that assumed either was blind to that difference on the other.
+ * `DiffOptions.normalizeType` is what settles it, by putting both sides through the engine first.
  */
 export function areTypesEqual(a, b) {
-    // Category must match
-    if (a.category !== b.category) {
-        return false;
-    }
-    // Size must match (if specified)
-    if (a.size !== b.size) {
-        return false;
-    }
-    // For strings, compare length (allowing for default 255)
-    if (a.category === 'string') {
-        const lengthA = a.length ?? 255;
-        const lengthB = b.length ?? 255;
-        if (lengthA !== lengthB) {
-            return false;
-        }
-    }
-    // For decimals, compare precision and scale (allowing for default 10, 2)
-    if (a.category === 'decimal') {
-        const pA = a.precision ?? 10;
-        const pB = b.precision ?? 10;
-        const sA = a.scale ?? 2;
-        const sB = b.scale ?? 2;
-        if (pA !== pB || sA !== sB) {
-            return false;
-        }
-    }
-    // For timestamps, compare timezone
-    if (a.category === 'timestamp') {
-        if (!!a.withTimezone !== !!b.withTimezone) {
-            return false;
-        }
-    }
-    // Unsigned must match
-    if (!!a.unsigned !== !!b.unsigned) {
-        return false;
-    }
-    return true;
+    return (a.category === b.category &&
+        a.size === b.size &&
+        a.length === b.length &&
+        a.precision === b.precision &&
+        a.scale === b.scale &&
+        !!a.withTimezone === !!b.withTimezone &&
+        !!a.unsigned === !!b.unsigned);
 }
 /**
- * Check if changing from type A to type B could cause data loss.
+ * Whether changing a column from one type to the other can lose what it holds.
+ *
+ * An unstated bound is the engine's widest, so stating one for the first time narrows the column just
+ * as lowering one does: `TEXT` to `VARCHAR(50)` truncates, and `NUMERIC` to `NUMERIC(5,2)` rounds.
  */
 export function isBreakingTypeChange(from, to) {
-    // Changing category is always potentially breaking
     if (from.category !== to.category) {
         return true;
     }
-    // Reducing size is breaking
-    const sizeOrder = ['tiny', 'small', 'medium', 'big'];
-    if (from.size && to.size) {
-        const fromIndex = sizeOrder.indexOf(from.size);
-        const toIndex = sizeOrder.indexOf(to.size);
-        if (toIndex < fromIndex) {
-            return true;
-        }
-    }
-    // Reducing string length is breaking
-    if (from.category === 'string' && from.length && to.length) {
-        if (to.length < from.length) {
-            return true;
-        }
-    }
-    // Reducing precision/scale is breaking
-    if (from.category === 'decimal') {
-        if (from.precision && to.precision && to.precision < from.precision) {
-            return true;
-        }
-        if (from.scale && to.scale && to.scale < from.scale) {
-            return true;
-        }
+    // Only where both state a size: an unsized member of a family is the engine's base type, wider than
+    // `tiny` and narrower than `big`, and which of those it is depends on a family this does not know.
+    if (from.size && to.size && SIZE_ORDER.indexOf(to.size) < SIZE_ORDER.indexOf(from.size)) {
+        return true;
     }
-    return false;
+    return (narrows(from.length, to.length) ||
+        narrows(from.precision, to.precision) ||
+        narrows(from.scale, to.scale) ||
+        // Either direction drops half the range: signed loses the top bit, unsigned the negatives.
+        !!from.unsigned !== !!to.unsigned ||
+        // An offset the column stops keeping cannot be recovered from what is left.
+        (!!from.withTimezone && !to.withTimezone));
+}
+const SIZE_ORDER = ['tiny', 'small', 'medium', 'big'];
+/** A bound narrowed, where an unstated one is unbounded. */
+function narrows(from, to) {
+    return to !== undefined && (from === undefined || to < from);
 }
 /**
  * Get the UQL ColumnType that best matches a canonical type.

package/dist/schema/indexDifferences.d.ts

@@ -9,6 +9,34 @@ import type { IndexNode } from './types.js';
  * back, MySQL emits one it cannot describe afterwards.
  */
 export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include';
+/**
+ * Whether the table already has this index, for the additive sync that only ever *creates* one.
+ *
+ * Its shape, never its name: the table's indexes were named by whoever created them, so an index
+ * that is already there must not be created a second time under a name we happen to prefer. A
+ * derived name is no handle at all - the convention can change, an engine silently truncates one
+ * past its identifier limit, and SQLite reports names it made up.
+ *
+ * Uniqueness counts, because a unique index and a plain one over the same columns enforce different
+ * things and no engine can alter one into the other. An index over an expression or a JSON path has
+ * no comparable columns - engines reprint SQL text from their parse tree, the same reason
+ * {@link describeIndexDifferences} leaves those entries alone - so it falls back to its name.
+ */
+export declare function indexSignature(index: Pick<IndexNode, 'name' | 'entries' | 'unique'>): string;
+/**
+ * A constraint name without its kind marker.
+ *
+ * What pairs two sides of a *report*: an index whose uniqueness or columns changed is one index that
+ * differs, not one dropped and another created, and only a handle independent of its shape can say
+ * so. Stripping the marker is what lets `idx_User_email`, named before the convention moved it to
+ * the end, recognise the `User__email_idx` derived for it now, so upgrading reports no drift.
+ *
+ * Exactly one marker, and the trailing one first. Stripping both ends would eat a leading marker
+ * that belongs to the *table* - an index over `pk_registry` is not a primary key - leaving it unable
+ * to pair with its own older name. The separator is levelled last, since only one convention doubles
+ * it.
+ */
+export declare function indexNameStem(name: string): string;
 /**
  * Everything an index differs by, named, or nothing when the two match.
  *

package/dist/schema/indexDifferences.js

@@ -1,3 +1,49 @@
+/**
+ * Whether the table already has this index, for the additive sync that only ever *creates* one.
+ *
+ * Its shape, never its name: the table's indexes were named by whoever created them, so an index
+ * that is already there must not be created a second time under a name we happen to prefer. A
+ * derived name is no handle at all - the convention can change, an engine silently truncates one
+ * past its identifier limit, and SQLite reports names it made up.
+ *
+ * Uniqueness counts, because a unique index and a plain one over the same columns enforce different
+ * things and no engine can alter one into the other. An index over an expression or a JSON path has
+ * no comparable columns - engines reprint SQL text from their parse tree, the same reason
+ * {@link describeIndexDifferences} leaves those entries alone - so it falls back to its name.
+ */
+export function indexSignature(index) {
+    const comparable = !index.entries.some((entry) => entry.expression || entry.jsonPath || entry.jsonArray);
+    const identity = comparable
+        ? index.entries.map((entry) => entry.column).join(',')
+        : `name:${indexNameStem(index.name)}`;
+    return `${index.unique ? 'unique' : 'plain'}(${identity})`;
+}
+/**
+ * A constraint name without its kind marker.
+ *
+ * What pairs two sides of a *report*: an index whose uniqueness or columns changed is one index that
+ * differs, not one dropped and another created, and only a handle independent of its shape can say
+ * so. Stripping the marker is what lets `idx_User_email`, named before the convention moved it to
+ * the end, recognise the `User__email_idx` derived for it now, so upgrading reports no drift.
+ *
+ * Exactly one marker, and the trailing one first. Stripping both ends would eat a leading marker
+ * that belongs to the *table* - an index over `pk_registry` is not a primary key - leaving it unable
+ * to pair with its own older name. The separator is levelled last, since only one convention doubles
+ * it.
+ */
+export function indexNameStem(name) {
+    const withoutSuffix = name.replace(KIND_SUFFIX, '');
+    const bare = withoutSuffix === name ? name.replace(KIND_PREFIX, '') : withoutSuffix;
+    return bare.replace(/__/g, '_');
+}
+/** What this version emits. */
+const KIND_SUFFIX = /_(?:idx|fk|ck|pk|uk|uq)$/i;
+/**
+ * What it only ever *reads*: uql wrote `idx_User_email` until 0.42.1, and a database it did not
+ * create at all - the one `generate:from-db` points at - most often spells it that way too. Tried
+ * second, so a name already marked at the end keeps a leading `pk_` that is part of its table.
+ */
+const KIND_PREFIX = /^(?:idx|fk|ck|pk|uk|uq)_/i;
 /**
  * Everything an index differs by, named, or nothing when the two match.
  *

package/dist/schema/schemaASTBuilder.js

@@ -6,6 +6,7 @@
  * - Database introspection results (TableSchema[])
  */
 import { getMeta, soleIdOf } from '../entity/metadata/definition.js';
+import { isSoleIdField } 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';
@@ -64,7 +65,7 @@ function resolveColumnCanonicalType(field, seen = new Set()) {
             return resolveColumnCanonicalType(referencedIdField, seen);
         }
     }
-    return fieldOptionsToCanonical(field, field.type);
+    return fieldOptionsToCanonical(field);
 }
 /**
  * Add a table from entity metadata.
@@ -86,7 +87,7 @@ function addTableFromEntity(ctx, meta) {
         const columnName = ctx.resolveColumnName(key, field);
         const type = resolveColumnCanonicalType(field);
         const isPrimaryKey = field.isId === true;
-        const isSoleKey = isPrimaryKey && meta.ids.length === 1;
+        const isSoleKey = isSoleIdField(meta, field);
         const column = {
             name: columnName,
             type,
@@ -95,9 +96,7 @@ function addTableFromEntity(ctx, meta) {
             nullable: isPrimaryKey ? false : (field.nullable ?? true),
             defaultValue: field.defaultValue,
             isPrimaryKey,
-            // Only a sole integer key defaults to auto-increment: a composite's columns are values the
-            // caller supplies, and the serial type carries an inline `PRIMARY KEY` the table already states.
-            isAutoIncrement: field.autoIncrement ?? (isPrimaryKey && isSoleKey && type.category === 'integer'),
+            isAutoIncrement: field.autoIncrement ?? (isSoleKey && type.category === 'integer'),
             isUnique: field.unique ?? false,
             comment: field.comment,
             enum: field.enum,
@@ -142,37 +141,32 @@ function addRelationshipsFromEntity(ctx, meta) {
             // the engine requires the referenced columns to match a unique constraint as a whole.
             const localColumns = [];
             const foreignColumns = [];
-            let firstLocalField;
-            for (const { local: localPropName, foreign: foreignPropName } of relation.references) {
-                const localField = meta.fields[localPropName];
-                const foreignField = relatedMeta.fields[foreignPropName];
-                if (!localField || !foreignField) {
-                    continue;
-                }
-                const localColumn = table.columns.get(ctx.resolveColumnName(localPropName, localField));
-                const foreignColumn = relatedTable.columns.get(ctx.resolveColumnName(foreignPropName, foreignField));
-                if (!localColumn || !foreignColumn) {
-                    continue;
-                }
-                firstLocalField ??= localField;
+            for (const { local: localProp, foreign: foreignProp } of relation.references) {
+                const localField = meta.fields[localProp];
+                const foreignField = relatedMeta.fields[foreignProp];
+                const localColumn = localField && table.columns.get(ctx.resolveColumnName(localProp, localField));
+                const foreignColumn = foreignField && relatedTable.columns.get(ctx.resolveColumnName(foreignProp, foreignField));
+                if (!localColumn || !foreignColumn)
+                    break;
                 localColumns.push(localColumn);
                 foreignColumns.push(foreignColumn);
             }
-            if (localColumns.length === relation.references.length && firstLocalField) {
-                const relNode = {
-                    name: derivedForeignKeyName(table.name, localColumns.map((column) => column.name)),
-                    type: relation.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
-                    from: { table, columns: localColumns },
-                    to: { table: relatedTable, columns: foreignColumns },
-                    // Falls back to the FK column's own `onDelete`, which is what makes a bare `@Field({
-                    // references, onDelete })` work with no relation declared at all.
-                    onDelete: relation.onDelete ?? firstLocalField.onDelete ?? ctx.defaultForeignKeyAction,
-                    onUpdate: relation.onUpdate ?? ctx.defaultForeignKeyAction,
-                    confidence: 1.0,
-                    inferredFrom: 'entity_decorator',
-                };
-                ctx.ast.addRelationship(relNode);
-            }
+            // A pair that cannot be resolved drops the whole constraint: half of one enforces a rule
+            // nobody declared, over a subset of the key.
+            if (localColumns.length !== relation.references.length)
+                continue;
+            ctx.ast.addRelationship({
+                name: derivedForeignKeyName(table.name, localColumns.map((column) => column.name)),
+                type: relation.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
+                from: { table, columns: localColumns },
+                to: { table: relatedTable, columns: foreignColumns },
+                // Falls back to the FK column's own `onDelete`, which is what makes a bare `@Field({
+                // references, onDelete })` work with no relation declared at all.
+                onDelete: relation.onDelete ?? meta.fields[relation.references[0].local]?.onDelete ?? ctx.defaultForeignKeyAction,
+                onUpdate: relation.onUpdate ?? ctx.defaultForeignKeyAction,
+                confidence: 1.0,
+                inferredFrom: 'entity_decorator',
+            });
         }
     }
 }

package/dist/schema/schemaASTDiffer.d.ts

@@ -9,7 +9,8 @@
  */
 import { type IndexFacet } from './indexDifferences.js';
 import type { SchemaAST } from './schemaAST.js';
-import type { SchemaDiffResult } from './types.js';
+import type { CanonicalType } from './types.js';
+import type { SchemaDiffResult, TableDiff, TableNode } from './types.js';
 /**
  * Options for schema diffing.
  */
@@ -24,6 +25,23 @@ export interface DiffOptions {
     ignoreCase?: boolean;
     /** Tables to exclude from comparison */
     excludeTables?: string[];
+    /**
+     * A type as the engine would actually store it, for the caller that has a dialect.
+     *
+     * Several canonical types share one storage type per engine - a `boolean` is `TINYINT(1)` on MySQL
+     * and `INTEGER` on SQLite - so comparing them canonically reports an alteration on every sync for
+     * those columns. Passing both sides through the engine first is what settles that, and it is the
+     * only thing here a dialect is needed for, so it arrives as a function rather than as a dependency.
+     */
+    normalizeType?: (type: CanonicalType) => CanonicalType;
+    /**
+     * Whether two defaults are the same value, for the caller that has a dialect.
+     *
+     * A database reprints a default from its parse tree, so `'active'` comes back as
+     * `'active'::character varying` on Postgres and a symbolic `now()` matches no spelling of
+     * `CURRENT_TIMESTAMP`. Undoing that needs the dialect that wrote it, so it arrives as a function.
+     */
+    defaultsEqual?: (expected: unknown, actual: unknown) => boolean;
 }
 /**
  * Compare two schemas and return the differences.
@@ -34,3 +52,11 @@ export interface DiffOptions {
  * @returns Detailed diff result
  */
 export declare function diffSchemas(source: SchemaAST, target: SchemaAST, options?: DiffOptions): SchemaDiffResult;
+/**
+ * Compare two tables and return the differences.
+ *
+ * Exported because it is also how a migration is planned: the generator diffs one entity's table
+ * against the one the database reported, then projects the result into a `SchemaDiff`. One
+ * 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;