uql-orm 0.41.1 → 0.42.1

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -31,6 +31,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         dropTableCascade: false,
         renameColumn: true,
         foreignKeyAlter: true,
+        primaryKeyAlter: true,
         columnComment: true,
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
@@ -62,7 +63,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         }
         super.pager(ctx, opts);
     }
-    serialPrimaryKey = 'BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY';
+    serialType = 'BIGINT UNSIGNED AUTO_INCREMENT';
     escapeIdChar = '`';
     tableOptions = 'ENGINE=InnoDB DEFAULT CHARSET=utf8mb4';
     beginTransactionCommand = 'START TRANSACTION';
@@ -70,6 +71,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     rollbackTransactionCommand = 'ROLLBACK';
     isolationLevelStrategy = 'set-before';
     dropForeignKeySyntax = 'DROP FOREIGN KEY';
+    dropPrimaryKeySyntax = 'DROP PRIMARY KEY';
     dropIndexSyntax = 'on-table';
     renameTableSyntax = 'rename-table';
     alterColumnSyntax = 'MODIFY COLUMN';
@@ -91,7 +93,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         const alias = this.upsertNewRowAlias && this.escapeId(this.upsertNewRowAlias, true);
         const updateCtx = this.createContext();
         const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => alias ? `${alias}.${name}` : `VALUE(${name})`);
-        const returning = this.upsertReturning(entity);
+        const returning = this.upsertReturning(meta);
         if (update) {
             this.appendInsertValues(ctx, entity, payload);
             ctx.append(`${alias ? ` AS ${alias}` : ''} ON DUPLICATE KEY UPDATE ${update}${returning}`);
@@ -108,7 +110,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
      * Appended to both branches above. Empty on MySQL, which has no `INSERT ... RETURNING`; MariaDB
      * 10.5+ has it, and used to restate this whole method just to add it.
      */
-    upsertReturning(_entity) {
+    upsertReturning(_meta) {
         return '';
     }
     /**

package/dist/dialect/pgLikeSqlDialect.d.ts

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

package/dist/dialect/pgLikeSqlDialect.js

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

package/dist/entity/decorator/entity.d.ts

@@ -21,7 +21,7 @@ export declare function Filter<E>(name: string, opts: FilterOptions<E>): (entity
  * `E` is inferred from the class the returned decorator is applied to, which is what lets the column
  * names be checked against it: `@Index(['nope'])` does not compile.
  *
- * @example `@Index(['lastName', 'firstName'], { name: 'idx_users_fullname' })`
+ * @example `@Index(['lastName', 'firstName'], { name: 'users_fullname_idx' })`
  * @example `@Index(['email'], { unique: true })`
  * @example `@Index(['status'], { where: "status = 'active'" })`
  */

package/dist/entity/decorator/entity.js

@@ -33,7 +33,7 @@ export function Filter(name, opts) {
  * `E` is inferred from the class the returned decorator is applied to, which is what lets the column
  * names be checked against it: `@Index(['nope'])` does not compile.
  *
- * @example `@Index(['lastName', 'firstName'], { name: 'idx_users_fullname' })`
+ * @example `@Index(['lastName', 'firstName'], { name: 'users_fullname_idx' })`
  * @example `@Index(['email'], { unique: true })`
  * @example `@Index(['status'], { where: "status = 'active'" })`
  */

package/dist/entity/decorator/members.d.ts

@@ -7,6 +7,14 @@ type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext
  * primary key's own type. Which is what makes `@Field({ references: () => User })` on a `number`, where
  * `User.id` is a `uuid`, a compile error rather than a column that disagrees with its property.
  */
+/**
+ * Maps any option the type does not declare to `never`, turning a typo into a compile error.
+ *
+ * Needed because the decorators capture their options as a naked type parameter, and TypeScript
+ * skips excess-property checking on one of those: `@Field({ nulable: true })` compiled and was
+ * silently ignored. Resolves to `unknown` - an inert intersection member - when there are none.
+ */
+type RejectUnknown<O, Known> = [Exclude<keyof O, keyof Known>] extends [never] ? unknown : Record<Exclude<keyof O, keyof Known> & string, never>;
 /**
  * The value type the options declare, which the decorated property is then checked against.
  *
@@ -43,7 +51,7 @@ export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
     type: FieldType;
 } | {
     references: EntityGetter;
-})>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
+}) & RejectUnknown<O, FieldOptions>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
  * Declares the primary key, checked the same way as `@Field`.
  *
@@ -52,7 +60,7 @@ export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
  */
 export declare function Id<O extends FieldOptions<DeclaredValue<O>> & {
     type: FieldType;
-}>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
+} & RejectUnknown<O, FieldOptions>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
  * `E` comes from the mandatory `entity` getter, so the context can insist the property really holds that
  * entity: `@ManyToOne({ entity: () => Other })` on a `Company` field stops compiling, and a to-many

package/dist/entity/index.d.ts

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, assertSoleId, idOf, soleIdOf, } from './metadata/definition.js';

package/dist/entity/index.js

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, assertSoleId, idOf, soleIdOf, } from './metadata/definition.js';

package/dist/entity/metadata/definition.d.ts

@@ -1,4 +1,4 @@
-import type { EntityIndexInput, EntityMeta, EntityOptions, FieldKey, FieldOptions, FilterOptions, HookEvent, RelationOptions, Type } from '../../type/index.js';
+import type { EntityId, EntityIndexInput, EntityMeta, EntityOptions, FieldKey, FieldOptions, FilterOptions, HookEvent, IdKey, RelationOptions, Type } from '../../type/index.js';
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
 export declare function defineRelation<E>(entity: Type<E>, key: string, opts: RelationOptions): EntityMeta<E>;
@@ -25,6 +25,23 @@ type MemberSpecs = {
  */
 export declare function applyMembers<E>(entity: Type<E>, specs: MemberSpecs | undefined): void;
 export declare function defineEntity<E>(entity: Type<E>, opts?: EntityOptions<E>): EntityMeta<E>;
+/**
+ * Refuses an entity whose primary key is not one column, naming the path that cannot express it.
+ *
+ * Refusing rather than taking the first of several is the whole guarantee: pairing one column of a
+ * two-column key is how a statement silently addresses rows that merely agree on it.
+ */
+export declare function assertSoleId<E>(meta: EntityMeta<E>, what: string): void;
+/** The entity's one primary key, for a path that cannot express a composite. See {@link assertSoleId}. */
+export declare function soleIdOf<E>(meta: EntityMeta<E>, what: string): IdKey<E>;
+/**
+ * A row's primary key in the shape a `$where` takes: the value itself for a single key, an object
+ * carrying every key for a composite - which is exactly {@link EntityId}.
+ *
+ * What a settled write names its rows by, and what an insert hands back. Naming a composite row by
+ * one of its columns would address every row agreeing on that one.
+ */
+export declare function idOf<E>(meta: EntityMeta<E>, row: E): EntityId<E>;
 export declare function getEntities(): Type<unknown>[];
 export declare function getMeta<E>(entity: Type<E>): EntityMeta<E>;
 export {};

package/dist/entity/metadata/definition.js

@@ -24,12 +24,6 @@ export function defineField(entity, key, opts = {}) {
     return meta;
 }
 export function defineId(entity, key, opts) {
-    const meta = ensureMeta(entity);
-    const id = getIdKey(meta);
-    if (id) {
-        // A subclass narrowing the inherited primary key: drop the old one so exactly one stays marked.
-        delete meta.fields[id];
-    }
     return defineField(entity, key, { ...opts, isId: true });
 }
 // `RelationOptions` is parameterized by the *target* entity, which is independent of the owner `E`, so it
@@ -167,16 +161,51 @@ export function defineEntity(entity, opts = {}) {
             meta.filters = {};
         meta.filters[SOFT_DELETE_FILTER] = { condition: { [meta.softDelete]: null }, default: true };
     }
-    const id = getIdKey(meta);
-    if (!id) {
-        throw TypeError(`'${entity.name}' must have exactly one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);
+    const ids = getIdKeys(meta);
+    if (!ids.length) {
+        throw TypeError(`'${entity.name}' must have at least one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);
     }
-    meta.id = id;
+    meta.ids = ids;
     return meta;
 }
+/**
+ * Refuses an entity whose primary key is not one column, naming the path that cannot express it.
+ *
+ * Refusing rather than taking the first of several is the whole guarantee: pairing one column of a
+ * two-column key is how a statement silently addresses rows that merely agree on it.
+ */
+export function assertSoleId(meta, what) {
+    const { ids } = meta;
+    if (ids.length === 1) {
+        return;
+    }
+    throw new TypeError(ids.length
+        ? `'${meta.entity.name}' has a composite primary key (${ids.join(', ')}), which ${what} does not support yet.`
+        : // An entity registered with `@Field` but no `@Entity` never ran the check in `defineEntity`.
+            `'${meta.entity.name}' has no primary key, which ${what} needs.`);
+}
+/** The entity's one primary key, for a path that cannot express a composite. See {@link assertSoleId}. */
+export function soleIdOf(meta, what) {
+    assertSoleId(meta, what);
+    return meta.ids[0];
+}
+/**
+ * A row's primary key in the shape a `$where` takes: the value itself for a single key, an object
+ * carrying every key for a composite - which is exactly {@link EntityId}.
+ *
+ * What a settled write names its rows by, and what an insert hands back. Naming a composite row by
+ * one of its columns would address every row agreeing on that one.
+ */
+export function idOf(meta, row) {
+    const { ids } = meta;
+    if (ids.length === 1) {
+        return row[ids[0]];
+    }
+    return Object.fromEntries(ids.map((key) => [key, row[key]]));
+}
 export function getEntities() {
     return [...metas.entries()].reduce((acc, [key, val]) => {
-        if (val.id) {
+        if (val.ids.length) {
             acc.push(key);
         }
         return acc;
@@ -187,7 +216,7 @@ function ensureMeta(entity) {
     if (meta) {
         return meta;
     }
-    meta = { entity, id: '', fields: {}, relations: {} };
+    meta = { entity, ids: [], fields: {}, relations: {} };
     metas.set(entity, meta);
     return meta;
 }
@@ -210,7 +239,7 @@ function fillRelations(meta) {
             continue;
         const at = `'${meta.entity.name}.${relKey}'`;
         if (relOpts.mappedBy) {
-            fillInverseSide(at, relOpts);
+            fillInverseSide(at, meta, relOpts);
         }
         else if (!relOpts.references) {
             fillOwningSide(at, meta, relKey, relOpts);
@@ -234,13 +263,13 @@ function fillRelations(meta) {
 }
 function fillOwningSide(at, meta, relKey, relOpts) {
     const relMeta = ensureMeta(relOpts.entity());
-    const relIdKey = relMeta.id;
     if (relOpts.through) {
         // Both columns live on the junction, whatever the cardinality: `fillToManyThroughRelation`,
-        // `deleteRelations` and every dialect read them as junction columns.
+        // `deleteRelations` and every dialect read them as junction columns. A composite key contributes
+        // one pair per column of it, which is what makes the join address a whole key rather than part.
         relOpts.references = [
-            { local: junctionColumn(meta, meta.id), foreign: meta.id },
-            { local: junctionColumn(relMeta, relIdKey), foreign: relIdKey },
+            ...meta.ids.map((key) => ({ local: junctionColumn(meta, key), foreign: key })),
+            ...relMeta.ids.map((key) => ({ local: junctionColumn(relMeta, key), foreign: key })),
         ];
         return;
     }
@@ -248,21 +277,29 @@ function fillOwningSide(at, meta, relKey, relOpts) {
         throw new TypeError(`${at} is a to-many relation with no way to join: it needs 'mappedBy' (the field on the other side), ` +
             "'through' (a junction entity), or 'references' (the columns).");
     }
-    const fkKey = `${relKey}Id`;
-    relOpts.references = [{ local: fkKey, foreign: relIdKey }];
+    // `<rel>Id` for the one-key case it has always been; `<rel><Key>` per column otherwise. Both name a
+    // property, so both are spelled from the referenced *property* - a column name is what the naming
+    // strategy makes of this afterwards.
+    const sole = relMeta.ids.length === 1;
+    relOpts.references = relMeta.ids.map((key) => ({
+        local: sole ? `${relKey}Id` : `${relKey}${upperFirst(key)}`,
+        foreign: key,
+    }));
     // `typeFromReference` so schema generation resolves the referenced primary key's exact type
     // (columnType, length, chained keys) rather than trusting the fallback, as it does for an
     // explicit `@Field({ references })`.
-    if (!meta.fields[fkKey]) {
-        meta.fields[fkKey] = {
-            name: fkKey,
-            type: relMeta.fields[relIdKey]?.type ?? Number,
+    const fields = meta.fields;
+    for (const { local, foreign } of relOpts.references) {
+        fields[local] ??= {
+            name: local,
+            type: relMeta.fields[foreign]?.type ?? Number,
             references: relOpts.entity,
+            referencedKey: foreign,
             typeFromReference: true,
         };
     }
 }
-function fillInverseSide(at, relOpts) {
+function fillInverseSide(at, meta, relOpts) {
     const relEntity = relOpts.entity();
     const relMeta = getMeta(relEntity);
     const mappedBy = getMappedByKey(relOpts);
@@ -270,7 +307,13 @@ function fillInverseSide(at, relOpts) {
     if (relOpts.references)
         return;
     if (relMeta.fields[mappedBy]) {
-        relOpts.references = [{ local: relMeta.id, foreign: mappedBy }];
+        if (meta.ids.length > 1) {
+            throw new TypeError(`${at} is mapped by '${relEntity.name}.${mappedBy}', one column, but the primary key of ` +
+                `'${meta.entity.name}' is composite (${meta.ids.join(', ')}). Map it by the relation on the other side ` +
+                'instead, which joins every column of the key.');
+        }
+        // `local` is this entity's own key, as in every other pair.
+        relOpts.references = [{ local: meta.ids[0], foreign: mappedBy }];
         return;
     }
     // Authored view again: with each side mapped by the other, the target is still mid-resolution here and
@@ -282,11 +325,12 @@ function fillInverseSide(at, relOpts) {
     if (!owner.references?.length) {
         throw new TypeError(`${at} is mapped by '${relEntity.name}.${mappedBy}', an inverse side too, so neither owns the foreign key.`);
     }
-    // Two different flips: a junction pair is `[thisSide, otherSide]`, so the array reverses; a plain
-    // foreign key is one pair whose ends swap.
+    // Two different flips: a junction's pairs are the owner's group followed by ours, so the two groups
+    // swap - `toReversed` would also reverse each group, pairing a composite's columns crosswise. A
+    // plain foreign key is one pair per key whose ends swap.
     relOpts.references =
         relOpts.cardinality === 'm1' || relOpts.cardinality === 'mm'
-            ? owner.references.toReversed()
+            ? [...owner.references.slice(relMeta.ids.length), ...owner.references.slice(0, relMeta.ids.length)]
             : owner.references.map(({ local, foreign }) => ({ local: foreign, foreign: local }));
     relOpts.through = owner.through;
 }
@@ -303,7 +347,16 @@ function fillForeignKeyRelations(meta) {
         const references = meta.fields[fieldKey]?.references;
         if (!references || joined.has(fieldKey))
             continue;
-        const foreign = ensureMeta(references()).id;
+        const target = ensureMeta(references());
+        // Nothing to derive from an entity that has not registered its own fields yet.
+        if (!target.ids.length)
+            continue;
+        if (target.ids.length > 1) {
+            throw new TypeError(`'${meta.entity.name}.${fieldKey}' cannot reference '${target.entity.name}', whose primary key is composite ` +
+                `(${target.ids.join(', ')}): a column points at one. Use ` +
+                `'@ManyToOne({ entity: () => ${target.entity.name} })', which declares one column per key.`);
+        }
+        const [foreign] = target.ids;
         // The relation takes the column's name minus the key it points at (`itemId` -> `item`); a column
         // named anything else has no name to take, so it stays a plain foreign key.
         const suffix = upperFirst(foreign);
@@ -330,16 +383,18 @@ function getMappedByKey(relOpts) {
         ? relOpts.mappedBy(RELATION_KEY_MAP)
         : relOpts.mappedBy;
 }
-function getIdKey(meta) {
-    const id = getKeys(meta.fields).find((key) => meta.fields[key]?.isId);
-    return id;
+/** Every key the entity marks, in declaration order. More than one is a composite primary key. */
+function getIdKeys(meta) {
+    return getKeys(meta.fields).filter((key) => meta.fields[key]?.isId);
 }
 function extendMeta(target, source) {
     const sourceFields = { ...source.fields };
-    const sourceId = getIdKey(source);
-    // A subclass that declares its own primary key drops the parent's, so exactly one stays marked.
-    if (sourceId && getIdKey(target)) {
-        delete sourceFields[sourceId];
+    // A subclass declaring its own primary key drops the parent's - every column of it, or a composite
+    // parent would leave its remaining keys marked and silently widen the child's key.
+    if (getIdKeys(target).length) {
+        for (const key of getIdKeys(source)) {
+            delete sourceFields[key];
+        }
     }
     target.fields = { ...sourceFields, ...target.fields };
     target.relations = { ...source.relations, ...target.relations };

package/dist/http/handler.js

@@ -1,5 +1,5 @@
 import { withContext } from '../context/context.js';
-import { getEntities, getMeta } from '../entity/index.js';
+import { getEntities, getMeta, soleIdOf } from '../entity/index.js';
 import { entityPath, matchRoute } from './contract.js';
 import { parseQueryParams } from './query.js';
 /** `Company (crm.Company)`: the class, and the table it maps, which is what tells two apart. */
@@ -142,8 +142,8 @@ export function createRequestHandler(opts) {
                         const founds = await querier.findMany(entity, query);
                         let ids = [];
                         let count = 0;
-                        if (founds.length && meta.id) {
-                            const idKey = meta.id;
+                        if (founds.length) {
+                            const idKey = soleIdOf(meta, 'the HTTP handler');
                             ids = founds.map((found) => found[idKey]);
                             count = await querier.deleteMany(entity, { $where: ids }, { hardDelete });
                         }
@@ -157,7 +157,7 @@ function ok(body) {
     return { status: 200, body };
 }
 function buildIdQuery(meta, id, query) {
-    const idKey = meta.id;
+    const idKey = soleIdOf(meta, 'the HTTP handler');
     const where = query.$where;
     if (Array.isArray(where)) {
         query.$where = { $and: [{ [idKey]: { $in: where } }, { [idKey]: id }] };

package/dist/maria/mariaDialect.d.ts

@@ -1,5 +1,5 @@
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import type { DialectFeatures, FieldOptions, Query, QueryContext, QueryOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, Query, QueryContext, QueryOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
@@ -10,7 +10,7 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      * and `CREATE INDEX` takes `IF NOT EXISTS` - which MySQL's grammar has no place for.
      */
     protected readonly featureOverrides: Partial<DialectFeatures>;
-    protected upsertReturning<E>(entity: Type<E>): string;
+    protected upsertReturning<E>(meta: EntityMeta<E>): string;
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
      * reads a scalar and `JSON_EXTRACT` the subtree that the array operators need.

package/dist/maria/mariaDialect.js

@@ -18,8 +18,9 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
     };
-    upsertReturning(entity) {
-        return ` ${this.returningId(entity)}`;
+    upsertReturning(meta) {
+        const returning = this.returningId(meta);
+        return returning ? ` ${returning}` : '';
     }
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`

package/dist/migrate/builder/tableBuilder.js

@@ -154,10 +154,10 @@ export class TableBuilder {
         return this;
     }
     unique(columns, options) {
-        return this.addIndex('uq', columns, options, true);
+        return this.addIndex(columns, options, true);
     }
     index(columns, options) {
-        return this.addIndex('idx', columns, options, false);
+        return this.addIndex(columns, options, false);
     }
     /**
      * `@Index` and `table.index(...)` differ only in how the name is defaulted, so both normalize their
@@ -165,12 +165,13 @@ export class TableBuilder {
      * form, and anything left as a bare string would reach it as a column literally named `[object
      * Object]`.
      */
-    addIndex(prefix, columns, options, unique) {
+    addIndex(columns, options, unique) {
         const { name, ...rest } = typeof options === 'string' ? { name: options } : (options ?? {});
         const entries = columns.map(normalizeIndexColumn);
         this._indexes.push({
             ...rest,
-            name: name ?? `${prefix}_${this._name}_${entries.map((entry) => entry.column).join('_')}`,
+            name: name ??
+                derivedIndexName(this._name, entries.map((entry) => entry.column), unique),
             where: ddlText(rest.where, 'a partial-index predicate'),
             entries,
             unique,

package/dist/migrate/drift/driftDetector.js

@@ -34,6 +34,7 @@ export function detectDrift(expectedAST, actualAST, options = {}) {
         ...detectTableDrifts(diff),
         ...detectColumnDrifts(diff, opts),
         ...detectIndexDrifts(diff),
+        ...detectPrimaryKeyDrifts(diff),
         ...detectRelationshipDrifts(diff),
     ];
     return {
@@ -43,6 +44,21 @@ export function detectDrift(expectedAST, actualAST, options = {}) {
         generatedAt: new Date(),
     };
 }
+/**
+ * A table whose key holds different columns than the entity declares.
+ *
+ * Critical, and reported as a `constraint_mismatch` like any other: rows the database will accept
+ * are not the rows the ORM believes are unique, so it addresses by a key nothing enforces.
+ */
+function detectPrimaryKeyDrifts(diff) {
+    return diff.primaryKeyDiffs.map((pkDiff) => ({
+        type: 'constraint_mismatch',
+        severity: 'critical',
+        table: pkDiff.table,
+        details: `Primary key of "${pkDiff.table}" is (${pkDiff.actual.join(', ') || 'none'}) in the database but (${pkDiff.expected.join(', ') || 'none'}) in the entity`,
+        suggestion: 'Generate a migration to change the primary key',
+    }));
+}
 /**
  * Detect table-level drifts (missing/unexpected tables).
  */

package/dist/migrate/generator/mongoSchemaGenerator.d.ts

@@ -16,6 +16,13 @@ export declare class MongoSchemaGenerator extends AbstractDialect implements Sch
     generateCreateSchema(entities: readonly Type<unknown>[], options?: CreateSchemaOptions): string[];
     generateDropSchema(entities: readonly Type<unknown>[]): string[];
     private selected;
+    /**
+     * The indexes `@Field({ index })` declares, as the collection would hold them.
+     *
+     * One owner because two paths need it: creating a collection, and working out which of its indexes
+     * are missing. Derived twice, they drifted the moment either changed how a name is settled.
+     */
+    private fieldIndexes;
     generateCreateTable<E>(entity: Type<E>, _options?: {
         ifNotExists?: boolean;
     }): string[];

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -32,22 +32,32 @@ export class MongoSchemaGenerator extends AbstractDialect {
         const wanted = new Set(only);
         return entities.filter((entity) => wanted.has(this.resolveTableName(getMeta(entity))));
     }
-    generateCreateTable(entity, _options) {
-        const meta = getMeta(entity);
-        const collectionName = this.resolveTableName(meta);
-        const indexes = [];
-        for (const key of getKeys(meta.fields)) {
+    /**
+     * The indexes `@Field({ index })` declares, as the collection would hold them.
+     *
+     * One owner because two paths need it: creating a collection, and working out which of its indexes
+     * are missing. Derived twice, they drifted the moment either changed how a name is settled.
+     */
+    fieldIndexes(meta, collectionName) {
+        return getKeys(meta.fields).flatMap((key) => {
             const field = meta.fields[key];
-            if (field?.index) {
-                const columnName = this.resolveColumnName(key, field);
-                const indexName = typeof field.index === 'string' ? field.index : derivedIndexName(collectionName, [columnName]);
-                indexes.push({
-                    name: indexName,
+            if (!field?.index) {
+                return [];
+            }
+            const columnName = this.resolveColumnName(key, field);
+            return [
+                {
+                    name: typeof field.index === 'string' ? field.index : derivedIndexName(collectionName, [columnName]),
                     entries: [{ column: columnName }],
                     unique: !!field.unique,
-                });
-            }
-        }
+                },
+            ];
+        });
+    }
+    generateCreateTable(entity, _options) {
+        const meta = getMeta(entity);
+        const collectionName = this.resolveTableName(meta);
+        const indexes = this.fieldIndexes(meta, collectionName);
         // One `createIndex` command each, mirroring the SQL generator's `[CREATE TABLE, ...CREATE INDEX]`,
         // so the key spec is built here and the migrator only executes it.
         return [
@@ -137,22 +147,8 @@ export class MongoSchemaGenerator extends AbstractDialect {
         if (!currentTable) {
             return { tableName: collectionName, type: 'create' };
         }
-        const indexesToAdd = [];
         const existingIndexes = new Set(currentTable.indexes?.map((i) => i.name) ?? []);
-        for (const key of getKeys(meta.fields)) {
-            const field = meta.fields[key];
-            if (field?.index) {
-                const columnName = this.resolveColumnName(key, field);
-                const indexName = typeof field.index === 'string' ? field.index : derivedIndexName(collectionName, [columnName]);
-                if (!existingIndexes.has(indexName)) {
-                    indexesToAdd.push({
-                        name: indexName,
-                        entries: [{ column: columnName }],
-                        unique: !!field.unique,
-                    });
-                }
-            }
-        }
+        const indexesToAdd = this.fieldIndexes(meta, collectionName).filter((index) => !existingIndexes.has(index.name));
         if (indexesToAdd.length === 0) {
             return undefined;
         }

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

@@ -60,7 +60,10 @@ export declare abstract class AbstractSqlSchemaIntrospector extends BaseSqlIntro
     protected getColumns(read: TableRowReader, tableName: string): Promise<ColumnSchema[]>;
     protected getIndexes(read: TableRowReader, tableName: string): Promise<IndexSchema[]>;
     protected getForeignKeys(read: TableRowReader, tableName: string): Promise<ForeignKeySchema[]>;
-    protected getPrimaryKey(read: TableRowReader, tableName: string): Promise<string[] | undefined>;
+    protected getPrimaryKey(read: TableRowReader, tableName: string): Promise<{
+        columns?: string[];
+        name?: string;
+    }>;
     protected tableExistsParams(tableName: string): unknown[];
     protected getColumnsParams(tableName: string): unknown[];
     protected getIndexesParams(tableName: string): unknown[];
@@ -108,6 +111,11 @@ export declare abstract class AbstractSqlSchemaIntrospector extends BaseSqlIntro
      * overrides this.
      */
     protected mapPrimaryKeyResult(results: RawRow[]): string[] | undefined;
+    /**
+     * What the engine calls the key's constraint, where the query reported one. Only a `DROP` needs it,
+     * and only the reported name will do - see {@link TableSchema.primaryKeyName}.
+     */
+    protected mapPrimaryKeyName(results: RawRow[]): string | undefined;
     /** Parse default value string to appropriate type. */
     protected abstract parseDefaultValue(defaultValue: string | null): unknown;
 }

package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js

@@ -55,7 +55,8 @@ export class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector {
             return {
                 name: tableName,
                 columns,
-                primaryKey,
+                primaryKey: primaryKey.columns,
+                primaryKeyName: primaryKey.name,
                 indexes,
                 foreignKeys,
             };
@@ -100,7 +101,7 @@ export class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector {
     }
     async getPrimaryKey(read, tableName) {
         const results = await read(this.getPrimaryKeyQuery(tableName), this.getPrimaryKeyParams(tableName));
-        return this.mapPrimaryKeyResult(results);
+        return { columns: this.mapPrimaryKeyResult(results), name: this.mapPrimaryKeyName(results) };
     }
     tableExistsParams(tableName) {
         return [tableName];
@@ -162,6 +163,14 @@ export class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector {
         const columns = results.map((row) => String(row['column_name']));
         return columns.length ? columns : undefined;
     }
+    /**
+     * What the engine calls the key's constraint, where the query reported one. Only a `DROP` needs it,
+     * and only the reported name will do - see {@link TableSchema.primaryKeyName}.
+     */
+    mapPrimaryKeyName(results) {
+        const name = results[0]?.['constraint_name'];
+        return name === undefined || name === null ? undefined : String(name);
+    }
 }
 /** A {@link TableRowReader} over one querier: the same statement is only ever sent once. */
 function createTableRowReader(querier) {