uql-orm 0.41.1 → 0.42.1

package/dist/querier/relationCount.js

@@ -1,7 +1,7 @@
 import { COUNT_ALIAS } from '../dialect/aliases.js';
-import { getMeta } from '../entity/index.js';
+import { getMeta, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
-import { asSelectMap, getKeys, parentKeyColumn, targetKeyColumn } 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
@@ -9,27 +9,33 @@ import { asSelectMap, getKeys, parentKeyColumn, targetKeyColumn } from '../util/
  */
 export function withIdForCounts(entity, q) {
     const meta = getMeta(entity);
-    if (!q.$count || !meta.id) {
+    if (!q.$count) {
         return q;
     }
+    const { ids } = meta;
+    const named = ids.join(', ');
     if (q.$distinct) {
-        // The id would have to join the projection for the tallies to group by, and that is the set
-        // `$distinct` collapses on: adding it silently stops the grouping collapsing anything at all.
-        throw new TypeError(`$count cannot be combined with $distinct: the tallies group by each row's '${String(meta.id)}', which the grouping does not keep.`);
+        // The keys would have to join the projection for the tallies to group by, and that is the set
+        // `$distinct` collapses on: adding them silently stops the grouping collapsing anything at all.
+        throw new TypeError(`$count cannot be combined with $distinct: the tallies group by each row's '${named}', which the grouping does not keep.`);
     }
     if (Array.isArray(q.$select)) {
-        // Nothing to add the id to, and without it every tally would be looked up by `undefined` and
+        // Nothing to add the keys to, and without them every tally would be looked up by `undefined` and
         // come back zero. Refused rather than answered wrong, the way an unorderable clause is.
-        throw new TypeError(`$count needs the '${String(meta.id)}' of each row to group its tallies by, which a raw $select cannot carry. Use a $select map, or drop the $count.`);
+        throw new TypeError(`$count needs the '${named}' of each row to group its tallies by, which a raw $select cannot carry. Use a $select map, or drop the $count.`);
     }
     const next = { ...q };
     const select = asSelectMap(q.$select);
-    if (select && !select[meta.id]) {
-        next.$select = { ...select, [meta.id]: true };
+    const missing = select ? ids.filter((key) => !select[key]) : [];
+    if (missing.length) {
+        next.$select = { ...select, ...Object.fromEntries(missing.map((key) => [key, true])) };
     }
-    if (q.$exclude?.[meta.id]) {
+    const excluded = ids.filter((key) => q.$exclude?.[key]);
+    if (excluded.length) {
         const kept = { ...q.$exclude };
-        delete kept[meta.id];
+        for (const key of excluded) {
+            delete kept[key];
+        }
         next.$exclude = kept;
     }
     return next;
@@ -44,9 +50,9 @@ export async function fillRelationCounts(querier, entity, payload, count) {
         return;
     }
     const meta = getMeta(entity);
-    // The ids cross the same boundary the entity does: past here every column is named by metadata,
-    // so they are read as {@link CountedRow}'s values rather than as this entity's own id type.
-    const ids = payload.map((it) => it[meta.id]);
+    // 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];
@@ -55,50 +61,55 @@ export async function fillRelationCounts(querier, entity, payload, count) {
             continue;
         }
         const where = typeof value === 'object' ? value.$where : undefined;
-        counted.set(relKey, await countPerParent(querier, relOpts, ids, where));
+        const joins = parentJoins(relOpts, meta.ids.length);
+        counted.set(relKey, { joins, byParent: await countPerParent(querier, relOpts, joins, payload, where) });
     }
     for (const parent of payload) {
-        const id = String(parent[meta.id]);
         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;
     }
 }
-async function countPerParent(querier, relOpts, ids, where) {
+async function countPerParent(querier, relOpts, joins, parents, where) {
     const through = relOpts.through;
     if (through) {
-        return countThroughPerParent(querier, relOpts, through(), ids, where);
+        return countThroughPerParent(querier, relOpts, through(), joins, parents, where);
     }
-    const foreign = parentKeyColumn(relOpts);
-    return groupedCount(querier, relOpts.entity(), foreign, { ...where, [foreign]: ids });
+    return groupedCount(querier, relOpts.entity(), joins, {
+        ...where,
+        ...parentsIn(joins, parents),
+    });
 }
 /**
  * A many-to-many counts its junction rows, one per pairing. A filter names the target's columns,
  * which the junction does not have, so the matching targets are resolved first and the junction
  * counted against them - the one shape here that costs a second statement, and only when filtered.
  */
-async function countThroughPerParent(querier, relOpts, throughEntity, ids, where) {
-    const local = parentKeyColumn(relOpts);
-    const throughWhere = { [local]: ids };
+async function countThroughPerParent(querier, relOpts, throughEntity, joins, parents, where) {
+    const throughWhere = parentsIn(joins, parents);
     if (where) {
         const target = relOpts.entity();
-        const targetId = getMeta(target).id;
+        const targetId = soleIdOf(getMeta(target), 'a many-to-many target');
         const targets = await querier.findMany(target, { $select: { [targetId]: true }, $where: where });
-        throughWhere[targetKeyColumn(relOpts)] = targets.map((it) => it[targetId]);
+        const [targetColumn] = targetKeyColumns(relOpts, joins.length);
+        throughWhere[targetColumn] = targets.map((it) => it[targetId]);
     }
-    return groupedCount(querier, throughEntity, local, throughWhere);
+    return groupedCount(querier, throughEntity, joins, throughWhere);
 }
-/** `SELECT <key>, COUNT(*) ... GROUP BY <key>`, as a lookup from parent key to tally. */
-async function groupedCount(querier, entity, groupKey, where) {
+/** `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 rows = await querier.aggregate(entity, { $group: { [groupKey]: true }, $agg, $where: where });
+    const $group = joinedColumns(joins);
+    const rows = await querier.aggregate(entity, { $group, $agg, $where: where });
     const byParent = {};
     for (const row of rows) {
-        byParent[String(row[groupKey])] = Number(row[COUNT_ALIAS]);
+        // 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[joinedRowKey(joins, row)] = Number(row[COUNT_ALIAS]);
     }
     return byParent;
 }

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

@@ -5,7 +5,8 @@
  * - Entity metadata (decorator-based entities)
  * - Database introspection results (TableSchema[])
  */
-import { getMeta } from '../entity/metadata/definition.js';
+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';
@@ -57,7 +58,9 @@ function resolveColumnCanonicalType(field, seen = new Set()) {
     if (!hasExplicitType && field.references && !seen.has(field.references)) {
         seen.add(field.references);
         const referencedMeta = getMeta(field.references());
-        const referencedIdField = referencedMeta.fields[referencedMeta.id];
+        // The column names which key it points at when the target has several; otherwise there is one.
+        const referencedKey = field.referencedKey ?? soleIdOf(referencedMeta, 'a foreign key');
+        const referencedIdField = referencedMeta.fields[referencedKey];
         if (referencedIdField) {
             return resolveColumnCanonicalType(referencedIdField, seen);
         }
@@ -83,7 +86,8 @@ function addTableFromEntity(ctx, meta) {
             continue;
         const columnName = ctx.resolveColumnName(key, field);
         const type = resolveColumnCanonicalType(field);
-        const isPrimaryKey = key === meta.id;
+        const isPrimaryKey = field.isId === true;
+        const isSoleKey = isSoleIdField(meta, field);
         const column = {
             name: columnName,
             type,
@@ -92,7 +96,7 @@ function addTableFromEntity(ctx, meta) {
             nullable: isPrimaryKey ? false : (field.nullable ?? true),
             defaultValue: field.defaultValue,
             isPrimaryKey,
-            isAutoIncrement: field.autoIncrement ?? (isPrimaryKey && type.category === 'integer'),
+            isAutoIncrement: field.autoIncrement ?? (isSoleKey && type.category === 'integer'),
             isUnique: field.unique ?? false,
             comment: field.comment,
             enum: field.enum,
@@ -101,7 +105,7 @@ function addTableFromEntity(ctx, meta) {
             references: undefined,
         };
         columns.set(columnName, column);
-        if (key === meta.id) {
+        if (field.isId) {
             primaryKey.push(column);
         }
     }
@@ -133,33 +137,36 @@ function addRelationshipsFromEntity(ctx, meta) {
         // user_profile(creatorId)`), which SQLite rejects outright as a foreign key mismatch.
         const ownsForeignKey = relation.cardinality === 'm1' || (relation.cardinality === '11' && !relation.mappedBy);
         if (ownsForeignKey) {
-            const localPropName = relation.references[0].local;
-            const foreignPropName = relation.references[0].foreign;
-            const localField = meta.fields[localPropName];
-            if (!localField)
-                continue;
-            const localColName = ctx.resolveColumnName(localPropName, localField);
-            const foreignField = relatedMeta.fields[foreignPropName];
-            if (!foreignField)
-                continue;
-            const foreignColName = ctx.resolveColumnName(foreignPropName, foreignField);
-            const localColumn = table.columns.get(localColName);
-            const foreignColumn = relatedTable.columns.get(foreignColName);
-            if (localColumn && foreignColumn) {
-                const relNode = {
-                    name: derivedForeignKeyName(table.name, [localColName]),
-                    type: relation.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
-                    from: { table, columns: [localColumn] },
-                    to: { table: relatedTable, columns: [foreignColumn] },
-                    // 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 ?? localField.onDelete ?? ctx.defaultForeignKeyAction,
-                    onUpdate: relation.onUpdate ?? ctx.defaultForeignKeyAction,
-                    confidence: 1.0,
-                    inferredFrom: 'entity_decorator',
-                };
-                ctx.ast.addRelationship(relNode);
+            // Every pair, not just the first: a composite key is one constraint over all its columns, and
+            // the engine requires the referenced columns to match a unique constraint as a whole.
+            const localColumns = [];
+            const foreignColumns = [];
+            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);
             }
+            // 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;

package/dist/schema/schemaASTDiffer.js

@@ -8,7 +8,7 @@
  * - Schema synchronization
  */
 import { areTypesEqual, isBreakingTypeChange } from './canonicalType.js';
-import { describeIndexDifferences } from './indexDifferences.js';
+import { describeIndexDifferences, indexNameStem } from './indexDifferences.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Default diff options.
@@ -17,6 +17,8 @@ const DEFAULT_OPTIONS = {
     compareIndexes: true,
     indexFacets: new Set(),
     compareRelationships: true,
+    normalizeType: (type) => type,
+    defaultsEqual: (expected, actual) => normalizeDefault(expected) === normalizeDefault(actual),
     ignoreCase: false,
     excludeTables: [],
 };
@@ -61,20 +63,25 @@ export function diffSchemas(source, target, options = {}) {
         .filter((tableDiff) => tableDiff !== undefined);
     const columnDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.columnDiffs ?? []);
     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 hasDifferences = tablesToCreate.length > 0 ||
         tablesToDrop.length > 0 ||
         tablesToAlter.length > 0 ||
         relationshipDiffs.length > 0 ||
-        indexDiffs.length > 0;
-    const hasBreakingChanges = tablesToDrop.length > 0 || columnDiffs.some((d) => d.isBreaking);
+        indexDiffs.length > 0 ||
+        primaryKeyDiffs.length > 0;
+    // Rewriting a key drops a constraint and rebuilds an index over the whole table, and fails outright
+    // where its new columns are null on rows that already exist. Breaking by any measure.
+    const hasBreakingChanges = tablesToDrop.length > 0 || primaryKeyDiffs.length > 0 || columnDiffs.some((d) => d.isBreaking);
     return {
         tablesToCreate,
         tablesToDrop,
         tablesToAlter,
         columnDiffs,
         indexDiffs,
+        primaryKeyDiffs,
         relationshipDiffs,
         hasDifferences,
         hasBreakingChanges,
@@ -82,14 +89,35 @@ export function diffSchemas(source, target, options = {}) {
 }
 /**
  * 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.
  */
-function diffTable(source, target, opts) {
+export function diffTable(source, target, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
     const columnDiffs = diffTableColumns(source, target, opts);
     const indexDiffs = opts.compareIndexes ? diffTableIndexes(source, target, opts) : [];
-    if (columnDiffs.length === 0 && indexDiffs.length === 0) {
+    const primaryKeyDiff = diffPrimaryKey(source, target);
+    if (columnDiffs.length === 0 && indexDiffs.length === 0 && !primaryKeyDiff) {
         return undefined;
     }
-    return { name: source.name, type: 'alter', columnDiffs, indexDiffs };
+    return { name: source.name, type: 'alter', columnDiffs, indexDiffs, primaryKeyDiff };
+}
+/**
+ * The two keys, where they hold different columns.
+ *
+ * Compared by columns and in order. Not by name: the engine named the constraint on every table that
+ * already exists, so matching on one would report every table as drifted the moment the convention
+ * that derives names changes.
+ */
+function diffPrimaryKey(source, target) {
+    const expected = source.primaryKey.map((column) => column.name);
+    const actual = target.primaryKey.map((column) => column.name);
+    if (expected.length === actual.length && expected.every((column, i) => column === actual[i])) {
+        return undefined;
+    }
+    return { table: source.name, expected, actual, actualName: target.primaryKeyName };
 }
 /**
  * Compare columns between two tables.
@@ -114,7 +142,7 @@ function diffTableColumns(source, target, opts) {
             description: `Drop column "${column.name}"`,
         })),
         ...matched
-            .map(([sourceColumn, targetColumn]) => diffColumn(source.name, sourceColumn, targetColumn))
+            .map(([sourceColumn, targetColumn]) => diffColumn(source.name, sourceColumn, targetColumn, opts))
             .filter((diff) => diff !== undefined),
     ];
 }
@@ -123,7 +151,7 @@ function diffTableColumns(source, target, opts) {
  */
 function diffTableIndexes(source, target, opts) {
     const normalizeName = nameNormalizer(opts);
-    const { created, dropped, matched } = matchByKey(source.indexes, target.indexes, (index) => normalizeName(index.name));
+    const { created, dropped, matched } = matchByKey(source.indexes, target.indexes, (index) => normalizeName(indexNameStem(index.name)));
     return [
         ...created.map((index) => ({ name: index.name, table: source.name, type: 'create', expected: index })),
         ...dropped.map((index) => ({ name: index.name, table: target.name, type: 'drop', actual: index })),
@@ -135,26 +163,34 @@ function diffTableIndexes(source, target, opts) {
 /**
  * Compare two columns and return the difference.
  */
-function diffColumn(tableName, source, target) {
+function diffColumn(tableName, source, target, opts) {
     const differences = [];
-    // Compare types
-    if (!areTypesEqual(source.type, target.type)) {
+    // 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,
+    // 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
+    // outright. Everything else about a key column is still compared, which the blanket "never alter a
+    // key column" rule these two replace used to hide.
+    const generatedType = source.isAutoIncrement && target.isAutoIncrement;
+    const impliedNotNull = source.isPrimaryKey && target.isPrimaryKey;
+    if (!generatedType && !areTypesEqual(opts.normalizeType(source.type), opts.normalizeType(target.type))) {
         differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
     }
-    // Compare nullability
-    if (source.nullable !== target.nullable) {
+    if (!impliedNotNull && source.nullable !== target.nullable) {
         differences.push(`nullable: ${target.nullable} → ${source.nullable}`);
     }
     // Compare unique constraint
     if (source.isUnique !== target.isUnique) {
         differences.push(`unique: ${target.isUnique} → ${source.isUnique}`);
     }
-    // Compare auto-increment
-    if (source.isAutoIncrement !== target.isAutoIncrement) {
-        differences.push(`autoIncrement: ${target.isAutoIncrement} → ${source.isAutoIncrement}`);
-    }
+    // Auto-increment is deliberately not compared. No engine turns a column into an identity, or out of
+    // one, without rewriting the table, and there is no DDL here that does it - so a difference could
+    // only ever be reported, never settled, and the statements emitted for it (a bare `ALTER COLUMN
+    // TYPE`) do not change it. The same rule `describeIndexDifferences` follows for what it cannot read.
     // Compare default values (if both defined)
-    if (normalizeDefault(source.defaultValue) !== normalizeDefault(target.defaultValue)) {
+    if (!opts.defaultsEqual(source.defaultValue, target.defaultValue)) {
         differences.push(`default: ${target.defaultValue ?? 'NULL'} → ${source.defaultValue ?? 'NULL'}`);
     }
     if (differences.length === 0) {

package/dist/schema/types.d.ts

@@ -122,7 +122,7 @@ export interface ColumnNode {
 export interface TableNode {
     /**
      * The table's own name, never qualified. Everything derived from a table reads this: an index or
-     * constraint name is a single identifier, and `idx_sales.Order_total` is a syntax error.
+     * constraint name is a single identifier, and `sales.Order_total_idx` is a syntax error.
      */
     readonly name: string;
     /**
@@ -133,8 +133,14 @@ export interface TableNode {
     readonly schema?: string;
     /** Map of column name to column node */
     readonly columns: Map<string, ColumnNode>;
-    /** Primary key columns (supports composite keys) */
+    /** Primary key columns, in key order (supports composite keys) */
     readonly primaryKey: ColumnNode[];
+    /**
+     * What the constraint is called, where a name is known: read back from the database on an
+     * introspected table, absent on one built from entities, where nothing has named it yet. A `DROP`
+     * is the only thing that needs it - see {@link TableSchema.primaryKeyName}.
+     */
+    primaryKeyName?: string;
     /** Indexes on this table */
     readonly indexes: IndexNode[];
     /** `CHECK` constraints on this table. Optional: a node can be built without ever naming one. */
@@ -151,7 +157,7 @@ export interface TableNode {
  * Represents a foreign key relationship between tables.
  */
 export interface RelationshipNode {
-    /** Constraint name (e.g., fk_posts_author_id) */
+    /** Constraint name (e.g., posts_author_id_fk) */
     readonly name: string;
     /** Type of relationship */
     readonly type: RelationshipType;
@@ -202,13 +208,28 @@ export interface SchemaAST {
 }
 /**
  * Difference between two column definitions.
+ *
+ * A union rather than one shape with two optional sides, so which node is present follows from the
+ * kind of difference: an added column has only the `expected` one, a dropped column only the
+ * `actual` one, and an altered column both. Stated as optionals, every reader had to assert its way
+ * past a `undefined` the kind had already ruled out.
  */
-export interface ColumnDiff {
+export type ColumnDiff = ColumnDiffBase & ({
+    readonly type: 'add';
+    readonly expected: ColumnNode;
+    readonly actual?: undefined;
+} | {
+    readonly type: 'drop';
+    readonly expected?: undefined;
+    readonly actual: ColumnNode;
+} | {
+    readonly type: 'alter';
+    readonly expected: ColumnNode;
+    readonly actual: ColumnNode;
+});
+interface ColumnDiffBase {
     readonly table: string;
     readonly column: string;
-    readonly type: 'add' | 'drop' | 'alter';
-    readonly expected?: ColumnNode;
-    readonly actual?: ColumnNode;
     /** Whether this change could cause data loss */
     readonly isBreaking?: boolean;
     readonly description?: string;
@@ -221,6 +242,21 @@ export interface TableDiff {
     readonly type: 'create' | 'drop' | 'alter';
     readonly columnDiffs?: ColumnDiff[];
     readonly indexDiffs?: IndexDiff[];
+    /** Set only where the two keys hold different columns. See {@link PrimaryKeyDiff}. */
+    readonly primaryKeyDiff?: PrimaryKeyDiff;
+}
+/**
+ * Two primary keys that hold different columns.
+ *
+ * By columns and in order, never by name: `(a, b)` is a different key from `(b, a)`, while the same
+ * key called `Member_pkey` on one side and `Member__userId_pk` on the other is one key, not two.
+ */
+export interface PrimaryKeyDiff {
+    readonly table: string;
+    readonly expected: string[];
+    readonly actual: string[];
+    /** What the *actual* side calls its constraint, which is the only name a `DROP` can use. */
+    readonly actualName?: string;
 }
 /**
  * Difference between two index definitions.
@@ -258,6 +294,8 @@ export interface SchemaDiffResult {
     readonly columnDiffs: ColumnDiff[];
     /** All index diffs */
     readonly indexDiffs: IndexDiff[];
+    /** Every table whose primary key holds different columns than the entity declares. */
+    readonly primaryKeyDiffs: PrimaryKeyDiff[];
     /** All relationship/FK diffs */
     readonly relationshipDiffs: RelationshipDiff[];
     /** Whether there are any differences */
@@ -321,3 +359,4 @@ export interface DriftReport {
         readonly info: number;
     };
 }
+export {};

package/dist/sqlite/sqliteDialect.d.ts

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