uql-orm 0.42.0 → 0.42.1

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';
@@ -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;

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";

package/dist/sqlite/sqliteDialect.js

@@ -13,6 +13,7 @@ export class SqliteDialect extends AbstractSqlDialect {
         dropTableCascade: false,
         renameColumn: true,
         foreignKeyAlter: false, // SQLite does not support adding FKs to existing tables
+        primaryKeyAlter: false, // nor changing a key: the only route is rebuilding the table
         columnComment: false, // SQLite does not support column comments
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
@@ -21,7 +22,9 @@ export class SqliteDialect extends AbstractSqlDialect {
     };
     dialectName = 'sqlite';
     escapeIdChar = '`';
-    serialPrimaryKey = 'INTEGER PRIMARY KEY AUTOINCREMENT';
+    serialType = 'INTEGER PRIMARY KEY AUTOINCREMENT';
+    // `AUTOINCREMENT` is only legal in that exact phrase, so the key cannot be lifted to table level.
+    serialDeclaresPrimaryKey = true;
     tableOptions = '';
     beginTransactionCommand = 'BEGIN TRANSACTION';
     commitTransactionCommand = 'COMMIT';

package/dist/type/dialect.d.ts

@@ -91,6 +91,12 @@ export interface EngineFeatures {
     readonly dropTableCascade: boolean;
     readonly renameColumn: boolean;
     readonly foreignKeyAlter: boolean;
+    /**
+     * Whether a table's primary key can be changed on an existing table. False on SQLite, whose only
+     * route is rebuilding the table - so a migration that would change one is refused by name rather
+     * than emitting DDL the engine rejects.
+     */
+    readonly primaryKeyAlter: boolean;
     /** Whether the dialect supports inline COMMENT on columns (MySQL/MariaDB). */
     readonly columnComment: boolean;
     /**

package/dist/type/migration.d.ts

@@ -123,7 +123,14 @@ export interface ColumnSchema {
 export interface TableSchema {
     readonly name: string;
     readonly columns: ColumnSchema[];
+    /** The key's columns **in order**, which is what a composite is: `(a, b)` is not `(b, a)`. */
     readonly primaryKey?: string[];
+    /**
+     * What the engine calls the key's constraint, where it names one at all - Postgres's `Member_pkey`,
+     * MySQL's literal `PRIMARY`, nothing on SQLite. Only a `DROP` needs it, and only the name the
+     * database actually reported will do: a derived one would name a constraint that is not there.
+     */
+    readonly primaryKeyName?: string;
     readonly indexes?: IndexSchema[];
     readonly foreignKeys?: ForeignKeySchema[];
 }
@@ -176,6 +183,18 @@ export interface SchemaDiff {
      */
     readonly schema?: string;
     readonly type: 'create' | 'alter' | 'drop';
+    /**
+     * The key the table has against the key the entity declares, set only when they differ.
+     *
+     * Compared by columns, never by name: the engine named the existing one, so requiring a derived
+     * name to match would rewrite the primary key of every table on the first migration after
+     * upgrading. `fromName` is what the database reported, and the only name a `DROP` can use.
+     */
+    readonly primaryKey?: {
+        readonly from: string[];
+        readonly to: string[];
+        readonly fromName?: string;
+    };
     readonly columnsToAdd?: ColumnSchema[];
     readonly columnsToAlter?: {
         from: ColumnSchema;

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

@@ -1,4 +1,4 @@
-import type { FieldOptions } from '../type/index.js';
+import type { EntityMeta, FieldOptions } from '../type/index.js';
 /**
  * Checks if a field type is numeric (Number, BigInt, or explicit numeric logical types)
  */
@@ -11,6 +11,16 @@ export declare function isBooleanType(type: unknown): boolean;
  * Checks if a field type is JSON
  */
 export declare function isJsonType(type: unknown): boolean;
+/**
+ * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,
+ * and the only one that may state `PRIMARY KEY` in its own column definition.
+ *
+ * One column of a composite is a value the caller supplies, and the table states the key over every
+ * column at once. Asked in one place because the two schema paths - the AST that builds a
+ * `CREATE TABLE` and the diff that builds an `ALTER` - have to answer it the same way, and each
+ * answering for itself is what put a serial `PRIMARY KEY` on both columns of a composite.
+ */
+export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOptions): boolean;
 /**
  * Checks if a field should be treated as auto-incrementing.
  */

package/dist/util/field.util.js

@@ -52,6 +52,18 @@ export function isJsonType(type) {
     }
     return false;
 }
+/**
+ * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,
+ * and the only one that may state `PRIMARY KEY` in its own column definition.
+ *
+ * One column of a composite is a value the caller supplies, and the table states the key over every
+ * column at once. Asked in one place because the two schema paths - the AST that builds a
+ * `CREATE TABLE` and the diff that builds an `ALTER` - have to answer it the same way, and each
+ * answering for itself is what put a serial `PRIMARY KEY` on both columns of a composite.
+ */
+export function isSoleIdField(meta, field) {
+    return field.isId === true && meta.ids.length === 1;
+}
 /**
  * Checks if a field should be treated as auto-incrementing.
  */

package/dist/util/object.util.js

@@ -69,7 +69,15 @@ export function getFieldKeys(fields) {
  * is what a `$where` map and a composite key's id object both are; an array is a list of either.
  */
 export function isScalarId(value) {
-    return (typeof value !== 'object' ||
-        value === null ||
-        (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype));
+    if (typeof value !== 'object' || value === null) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return false;
+    }
+    // `null` as well as `Object.prototype`: an object with no prototype is what a query-string parser
+    // hands back (`qs`, express's `req.params`), and reading one as a bare id would name one column
+    // with a map of several.
+    const proto = Object.getPrototypeOf(value);
+    return proto !== Object.prototype && proto !== null;
 }

package/dist/util/relationQuery.util.d.ts

@@ -32,6 +32,16 @@ export declare function parentJoins(relOpts: Pick<RelationMeta, 'references' | '
  * which is the mistake this module exists to prevent.
  */
 export declare function targetKeyColumns(relOpts: Pick<RelationMeta, 'references'>, parentKeyCount: number): string[];
+/** `{ joined column: true }`: the projection or grouping that keeps a parent's key on the rows read. */
+export declare function joinedColumns(joins: readonly ParentJoin[]): Record<string, true>;
+/**
+ * A parent row keyed by the columns a relation joins *from*, and a child or tally row keyed by the
+ * columns it carries that key in. The two halves of matching children to parents: they must agree on
+ * every column, so each is read through `joins` rather than through the parent's own key list - which
+ * is the same set only for a to-many, and silently a different one otherwise.
+ */
+export declare function parentRowKey(joins: readonly ParentJoin[], parent: unknown): string;
+export declare function joinedRowKey(joins: readonly ParentJoin[], row: unknown): string;
 /**
  * `{ joined column: every parent's value for it }`, the filter that fetches a whole page of parents'
  * children in one statement.