uql-orm 0.42.0 → 0.43.0

package/dist/migrate/schemaGenerator.js

@@ -1,9 +1,11 @@
 import { AbstractSqlDialect } from '../dialect/index.js';
 import { getMeta, soleIdOf } from '../entity/index.js';
-import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategory, sqlToCanonical, } from '../schema/canonicalType.js';
+import { areTypesEqual, canonicalToSql, engineType, fieldOptionsToCanonical, isVectorCategory, } from '../schema/canonicalType.js';
+import { indexSignature } from '../schema/indexDifferences.js';
 import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
-import { getKeys, isAutoIncrement, qualifyName } from '../util/index.js';
-import { derivedCheckName, derivedForeignKeyName } from '../util/sql.util.js';
+import { diffTable } from '../schema/schemaASTDiffer.js';
+import { getKeys, isAutoIncrement, isSoleIdField, qualifyName } from '../util/index.js';
+import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName } from '../util/sql.util.js';
 import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
 import { indexDdlFor } from './ddl/index.js';
 import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
@@ -47,14 +49,8 @@ export class SqlSchemaGenerator {
     /**
      * Primary key type for auto-increment integer IDs
      */
-    get serialPrimaryKeyType() {
-        return this.dialect.serialPrimaryKey;
-    }
-    /**
-     * Convert FieldOptions to CanonicalType using the unified type system.
-     */
-    getCanonicalType(field, fieldType) {
-        return fieldOptionsToCanonical(field, fieldType);
+    get serialType() {
+        return this.dialect.serialType;
     }
     canonicalTypeToSql(type) {
         return canonicalToSql(type, this.dialect);
@@ -128,6 +124,11 @@ export class SqlSchemaGenerator {
     generateAlterTable(diff) {
         const statements = [];
         const tableName = this.escapeId(diff.tableName);
+        // Before the columns, because a key column being added cannot be part of the old key, and after
+        // it is dropped the table is free to take the new one below.
+        if (diff.primaryKey?.from.length) {
+            statements.push(this.generateDropPrimaryKeySql(diff.tableName, diff.primaryKey.fromName));
+        }
         // Add new columns
         if (diff.columnsToAdd?.length) {
             for (const column of diff.columnsToAdd) {
@@ -161,11 +162,21 @@ export class SqlSchemaGenerator {
                 statements.push(this.generateDropIndex(diff.tableName, indexName, diff.schema));
             }
         }
+        // Last, so every column it names exists by now.
+        if (diff.primaryKey?.to.length) {
+            statements.push(this.generateAddPrimaryKeySql(diff.tableName, diff.primaryKey.to));
+        }
         return statements;
     }
     generateAlterTableDown(diff) {
         const statements = [];
         const tableName = this.escapeId(diff.tableName);
+        // The key first, mirroring the up direction: a column the up added cannot be dropped below while
+        // the new key still names it. Restored under the name the database gave it, which is what the
+        // table had before, rather than a derived one that was never on it.
+        if (diff.primaryKey?.to.length) {
+            statements.push(this.generateDropPrimaryKeySql(diff.tableName, derivedPrimaryKeyName(diff.tableName, diff.primaryKey.to)));
+        }
         // Reverse column additions by dropping them
         if (diff.columnsToAdd?.length) {
             for (const column of diff.columnsToAdd) {
@@ -175,7 +186,7 @@ export class SqlSchemaGenerator {
         // Reverse column alterations by restoring original schema
         if (diff.columnsToAlter?.length) {
             for (const { from } of diff.columnsToAlter) {
-                const colDef = this.generateColumnDefinitionFromSchema(from, { includePrimaryKey: false });
+                const colDef = this.generateColumnDefinitionFromSchema(from);
                 const colStatements = this.generateAlterColumnStatements(diff.tableName, from, colDef);
                 statements.push(...colStatements);
             }
@@ -186,6 +197,9 @@ export class SqlSchemaGenerator {
                 statements.push(this.generateDropIndex(diff.tableName, index.name, diff.schema));
             }
         }
+        if (diff.primaryKey?.from.length) {
+            statements.push(this.generateAddPrimaryKeySql(diff.tableName, diff.primaryKey.from, diff.primaryKey.fromName));
+        }
         if (diff.columnsToDrop?.length || diff.indexesToDrop?.length) {
             statements.push(`-- TODO: Manual reversal needed for dropped columns/indexes`);
         }
@@ -205,11 +219,15 @@ export class SqlSchemaGenerator {
         return `DROP INDEX IF EXISTS ${this.dialect.escapeQualifiedId(indexName, schema)};`;
     }
     /**
-     * Generate a column definition from a {@link ColumnSchema}, whose type is the engine's own spelling
-     * and may already carry its precision (or even `PRIMARY KEY`, for a serial).
+     * A column definition from a {@link ColumnSchema}, whose type is already the engine's own spelling
+     * and may carry its own size.
+     *
+     * Kept apart from {@link generateColumnFromNode} rather than folded into it: a `ColumnSchema` has no
+     * `enum`, because introspection reads one back as a `CHECK` constraint and not as a property of the
+     * column, so only the node knows enough to emit that clause. Both spell the definition through
+     * {@link renderColumn}, which is the part that must not be written twice.
      */
-    generateColumnDefinitionFromSchema(column, options = {}) {
-        const { includePrimaryKey = true, includeUnique = true } = options;
+    generateColumnDefinitionFromSchema(column) {
         let type = column.type;
         if (!type.includes('(')) {
             if (column.precision !== undefined) {
@@ -219,17 +237,7 @@ export class SqlSchemaGenerator {
                 type += `(${column.length})`;
             }
         }
-        if (!includePrimaryKey) {
-            type = type.replace(/\s+PRIMARY\s+KEY/i, '');
-        }
-        // `includePrimaryKey: false` suppresses the keyword, not the fact: the column is still the primary
-        // key, so it must not pick up `NOT NULL` (implied) or `UNIQUE` (redundant) on the way out.
-        return this.renderColumn({
-            ...column,
-            type,
-            isUnique: column.isUnique && includeUnique,
-            declaresPrimaryKey: includePrimaryKey && column.isPrimaryKey,
-        });
+        return this.renderColumn({ ...column, type });
     }
     /**
      * The one place a column definition is spelled. Both callers reach it - the `ColumnSchema` path above
@@ -238,9 +246,6 @@ export class SqlSchemaGenerator {
      */
     renderColumn(column) {
         let def = `${this.escapeId(column.name)} ${column.type}`;
-        if (column.declaresPrimaryKey && !column.type.includes('PRIMARY KEY')) {
-            def += ' PRIMARY KEY';
-        }
         if (!column.nullable && !column.isPrimaryKey) {
             def += ' NOT NULL';
         }
@@ -264,19 +269,21 @@ export class SqlSchemaGenerator {
             ? ''
             : ` DEFAULT ${formatDefaultValue(column.defaultValue, this.dialect, column.type)}`;
     }
-    getSqlType(field, fieldType) {
-        // If field has a reference, inherit type from the target primary key
+    getSqlType(field) {
+        // A foreign key takes the type of the key it points at. A `referencedKey` the target does not
+        // have falls through to this column's own options, as the AST builder does with the same case.
         if (field.references) {
-            const refEntity = field.references();
-            const refMeta = getMeta(refEntity);
+            const refMeta = getMeta(field.references());
             const refIdField = refMeta.fields[field.referencedKey ?? soleIdOf(refMeta, 'a foreign key')];
-            return this.getSqlType({ ...refIdField, references: undefined, isId: undefined, autoIncrement: false }, refIdField.type);
+            if (refIdField) {
+                return this.getSqlType({ ...refIdField, references: undefined, isId: undefined, autoIncrement: false });
+            }
         }
         // Get canonical type and convert to SQL
-        const canonical = this.getCanonicalType(field, fieldType);
+        const canonical = fieldOptionsToCanonical(field);
         // Special case for serial primary keys
         if (isAutoIncrement(field, field.isId === true)) {
-            return this.dialect.serialPrimaryKey;
+            return this.dialect.serialType;
         }
         return this.canonicalTypeToSql(canonical);
     }
@@ -323,80 +330,90 @@ export class SqlSchemaGenerator {
     /**
      * Compare an entity with a database table node and return the differences.
      */
+    /**
+     * How this entity differs from the table the database reported, as the migrator's `SchemaDiff`.
+     *
+     * The comparison itself is {@link diffTable}, the same one drift detection runs, so the two can no
+     * longer disagree about what has changed. Only two things are this side's own: the entity becomes a
+     * table node first, and types are compared as the *engine* would store them - see `normalizeType`.
+     */
     diffSchema(entity, currentTable) {
         const meta = getMeta(entity);
+        const tableName = this.resolveTableName(meta);
+        const schema = this.resolveSchema(meta);
         if (!currentTable) {
-            return {
-                tableName: this.resolveTableName(meta),
-                schema: this.resolveSchema(meta),
-                type: 'create',
-            };
-        }
-        const columnsToAdd = [];
-        const columnsToAlter = [];
-        const columnsToDrop = [];
-        const currentColumns = new Map(currentTable.columns);
-        const fieldKeys = getKeys(meta.fields);
-        for (const key of fieldKeys) {
-            const field = meta.fields[key];
-            if (!field || field.virtual)
-                continue;
-            const columnName = this.dialect.resolveColumnName(key, field);
-            const currentColumn = currentColumns.get(columnName);
-            if (!currentColumn) {
-                columnsToAdd.push(this.fieldToColumnSchema(key, field, meta));
-            }
-            else {
-                const desiredColumn = this.fieldToColumnSchema(key, field, meta);
-                const currentColumnSchema = this.columnNodeToSchema(currentColumn);
-                if (this.columnsNeedAlteration(currentColumnSchema, desiredColumn)) {
-                    columnsToAlter.push({ from: currentColumnSchema, to: desiredColumn });
-                }
-            }
-            currentColumns.delete(columnName);
+            return { tableName, schema, type: 'create' };
         }
-        for (const [name] of currentColumns) {
-            columnsToDrop.push(name);
+        // Keyed by the qualified name this generator resolves, which is the key the AST it just built
+        // stores the table under.
+        const desired = buildEntityAST(this, [entity]).getTable(tableName);
+        if (!desired) {
+            return undefined;
         }
-        const indexesToAdd = this.missingIndexes(entity, currentTable);
-        if (columnsToAdd.length === 0 &&
-            columnsToAlter.length === 0 &&
-            columnsToDrop.length === 0 &&
-            indexesToAdd.length === 0) {
+        // Indexes are matched here rather than by the differ, which pairs them by name so that a changed
+        // one reads as one index that altered. A migration needs the opposite: an index already in the
+        // table, under whatever name, must not be created again, and one whose shape differs is a
+        // separate index rather than a change - no engine alters an index's columns or uniqueness.
+        const tableDiff = diffTable(desired, currentTable, { ...this.diffOptions(), compareIndexes: false });
+        const indexesToAdd = this.missingIndexes(desired, currentTable);
+        const columnDiffs = tableDiff?.columnDiffs ?? [];
+        const columnsToAdd = columnDiffs.flatMap((it) => (it.type === 'add' ? [this.columnNodeToSchema(it.expected)] : []));
+        const columnsToDrop = columnDiffs.flatMap((it) => (it.type === 'drop' ? [it.column] : []));
+        const columnsToAlter = columnDiffs.flatMap((it) => it.type === 'alter'
+            ? [{ from: this.columnNodeToSchema(it.actual), to: this.columnNodeToSchema(it.expected) }]
+            : []);
+        const primaryKey = tableDiff?.primaryKeyDiff && {
+            from: tableDiff.primaryKeyDiff.actual,
+            to: tableDiff.primaryKeyDiff.expected,
+            fromName: tableDiff.primaryKeyDiff.actualName,
+        };
+        if (!columnsToAdd.length &&
+            !columnsToAlter.length &&
+            !columnsToDrop.length &&
+            !indexesToAdd.length &&
+            !primaryKey) {
             return undefined;
         }
         return {
-            tableName: this.resolveTableName(meta),
-            schema: this.resolveSchema(meta),
+            tableName,
+            schema,
             type: 'alter',
-            columnsToAdd: columnsToAdd.length > 0 ? columnsToAdd : undefined,
-            columnsToAlter: columnsToAlter.length > 0 ? columnsToAlter : undefined,
-            columnsToDrop: columnsToDrop.length > 0 ? columnsToDrop : undefined,
-            indexesToAdd: indexesToAdd.length > 0 ? indexesToAdd : undefined,
+            primaryKey,
+            columnsToAdd: columnsToAdd.length ? columnsToAdd : undefined,
+            columnsToAlter: columnsToAlter.length ? columnsToAlter : undefined,
+            columnsToDrop: columnsToDrop.length ? columnsToDrop : undefined,
+            indexesToAdd: indexesToAdd.length ? indexesToAdd : undefined,
         };
     }
     /**
-     * Indexes the entity declares that the table does not have, matched by name and built the same way
-     * `CREATE TABLE` builds them, so adding an `@Index` to an entity already in the database is picked
-     * up rather than waiting for the table to be created from scratch somewhere else.
+     * What the shared differ needs from a dialect: a type as this engine would actually store it.
      *
-     * Only ever additive. An index the entity does not name is left alone: it may well have been
-     * created deliberately outside the ORM, and dropping it is a decision for a reviewed migration.
+     * `boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite, so two canonical types that differ on
+     * paper can be one column in the database. Round-tripping through the engine's own spelling is what
+     * stops every such column reporting an alteration on every sync.
+     */
+    /**
+     * Indexes the entity declares that the table does not already have, in any shape.
      *
-     * A vector index is one of these like any other: MariaDB's `CREATE VECTOR INDEX ... ON t (col)`
-     * adds one to a table that already exists, which the inline `CREATE TABLE` form it also has cannot.
+     * Additive only: an index the entity does not name may well have been created deliberately outside
+     * the ORM, and dropping it is a decision for a reviewed migration.
      */
-    missingIndexes(entity, currentTable) {
-        // Keyed by the qualified name, so a table in a schema finds itself rather than reporting that
-        // the entity declares no indexes at all.
-        const desired = buildEntityAST(this, [entity]).getTable(qualifyName(currentTable.name, currentTable.schema))?.indexes ?? [];
-        const present = new Set(currentTable.indexes.map((index) => index.name));
-        return desired.filter((index) => !present.has(index.name)).map(indexNodeToSchema);
+    missingIndexes(desired, currentTable) {
+        const present = new Set(currentTable.indexes.map(indexSignature));
+        return desired.indexes.filter((index) => !present.has(indexSignature(index))).map(indexNodeToSchema);
+    }
+    diffOptions() {
+        return {
+            normalizeType: engineType(this.dialect),
+            defaultsEqual: (expected, actual) => this.isDefaultValueEqual(actual, expected),
+        };
     }
     columnNodeToSchema(col) {
         return {
             name: col.name,
-            type: this.canonicalTypeToSql(col.type),
+            // The same rule `generateColumnFromNode` renders by, so a column added to an existing table
+            // gets the type it would have had if the table were created from scratch.
+            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType : this.canonicalTypeToSql(col.type),
             nullable: col.nullable,
             defaultValue: col.defaultValue,
             isPrimaryKey: col.isPrimaryKey,
@@ -405,65 +422,17 @@ export class SqlSchemaGenerator {
             comment: col.comment,
         };
     }
-    /**
-     * Convert field options to ColumnSchema. Both sides of a diff are the engine's SQL spelling: what it
-     * would create for this field, against what it reported for the existing column.
-     */
-    fieldToColumnSchema(fieldKey, field, meta) {
-        const isPrimaryKey = field.isId === true;
-        return {
-            name: this.dialect.resolveColumnName(fieldKey, field),
-            type: this.getSqlType(field, field.type),
-            nullable: field.nullable ?? !isPrimaryKey,
-            defaultValue: field.defaultValue,
-            isPrimaryKey,
-            isAutoIncrement: isAutoIncrement(field, isPrimaryKey),
-            isUnique: field.unique ?? false,
-            length: field.length,
-            precision: field.precision,
-            scale: field.scale,
-            comment: field.comment,
-        };
-    }
-    /**
-     * Check if two columns differ enough to require alteration
-     */
-    columnsNeedAlteration(current, desired) {
-        if (current.isPrimaryKey && desired.isPrimaryKey) {
-            return false;
-        }
-        if (current.isPrimaryKey !== desired.isPrimaryKey)
-            return true;
-        if (current.nullable !== desired.nullable)
-            return true;
-        if (current.isUnique !== desired.isUnique)
-            return true;
-        if (!this.isTypeEqual(current, desired))
-            return true;
-        if (!this.isDefaultValueEqual(current.defaultValue, desired.defaultValue))
-            return true;
-        return false;
-    }
-    /**
-     * Whether two column types are the same *as this engine stores them*.
-     *
-     * Both sides are SQL spellings, parsed back to canonical so that `INT` and `INTEGER`, or `DATETIME`
-     * and `TIMESTAMP`, do not read as a change. Do not "simplify" this into comparing the entity's
-     * canonical type against the column's: several canonical types share one storage type per engine
-     * (`boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite), so that comparison reports an
-     * alteration for those columns on every single sync.
-     */
-    isTypeEqual(current, desired) {
-        return areTypesEqual(sqlToCanonical(current.type), sqlToCanonical(desired.type));
-    }
     /**
      * Compare two default values for equality
      */
     isDefaultValueEqual(current, desired) {
         if (current === desired)
             return true;
-        if (current === undefined || desired === undefined)
-            return current === desired;
+        // Both spellings of "no default" are the same fact, and engines disagree on which they report:
+        // MariaDB says `null` where MySQL says nothing at all. Reading them as different values asked to
+        // `MODIFY` every nullable column, on every sync, forever.
+        if (current == null || desired == null)
+            return current == null && desired == null;
         const normalize = (value) => {
             if (value === null)
                 return 'null';
@@ -493,9 +462,16 @@ export class SqlSchemaGenerator {
             const colDef = this.generateColumnFromNode(indexedVectorColumns.has(col.name) ? { ...col, nullable: false } : col);
             columns.push(colDef);
         }
-        if (table.primaryKey.length > 1) {
-            const pkCols = table.primaryKey.map((c) => this.escapeId(c.name)).join(', ');
-            constraints.push(`PRIMARY KEY (${pkCols})`);
+        // Every key, of any width, as one named constraint beside the checks and foreign keys - so a
+        // later `DROP` has something to name. The exception is a dialect whose serial type states the key
+        // itself (SQLite's `INTEGER PRIMARY KEY AUTOINCREMENT`, which cannot be split): there the column
+        // has already declared it, and saying it again is a second primary key.
+        const declaredByColumn = this.dialect.serialDeclaresPrimaryKey && table.primaryKey.length === 1 && table.primaryKey[0].isAutoIncrement;
+        if (table.primaryKey.length && !declaredByColumn) {
+            const pkColumns = table.primaryKey.map((c) => c.name);
+            const pkName = table.primaryKeyName ?? derivedPrimaryKeyName(table.name, pkColumns);
+            const pkCols = pkColumns.map((c) => this.escapeId(c)).join(', ');
+            constraints.push(`CONSTRAINT ${this.escapeId(pkName)} PRIMARY KEY (${pkCols})`);
         }
         (table.checks ?? []).forEach((check, i) => {
             const name = check.name ?? derivedCheckName(table.name, i + 1);
@@ -542,8 +518,7 @@ export class SqlSchemaGenerator {
     generateColumnFromNode(col) {
         return this.renderColumn({
             ...col,
-            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialPrimaryKeyType : this.canonicalTypeToSql(col.type),
-            declaresPrimaryKey: col.isPrimaryKey && col.table.primaryKey.length === 1,
+            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType : this.canonicalTypeToSql(col.type),
         });
     }
     /**
@@ -594,6 +569,44 @@ export class SqlSchemaGenerator {
     generateDropForeignKeySql(tableName, constraintName) {
         return `ALTER TABLE ${this.escapeId(tableName)} ${this.dialect.dropForeignKeySyntax} ${this.escapeId(constraintName)};`;
     }
+    /**
+     * `ALTER TABLE ... ADD CONSTRAINT <name> PRIMARY KEY (...)`, the other half of
+     * {@link generateDropPrimaryKeySql}. Refused where the engine cannot alter a key at all, by name,
+     * rather than emitting DDL it will reject.
+     */
+    generateAddPrimaryKeySql(tableName, columns, name) {
+        this.assertPrimaryKeyAlterable(tableName);
+        const constraintName = this.escapeId(name ?? derivedPrimaryKeyName(tableName, columns));
+        const pkCols = columns.map((c) => this.escapeId(c)).join(', ');
+        return `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${constraintName} PRIMARY KEY (${pkCols});`;
+    }
+    /**
+     * Drops whatever key the table has.
+     *
+     * `constraintName` has to be what the constraint is *actually* called: the name introspection
+     * reported for a key the database already had, or the derived one for a key this generator itself
+     * added, which is what reversing a migration drops. Guessing either way names nothing. MySQL takes
+     * no name at all - a table's key is always `PRIMARY` there.
+     */
+    generateDropPrimaryKeySql(tableName, constraintName) {
+        this.assertPrimaryKeyAlterable(tableName);
+        const table = this.escapeId(tableName);
+        if (this.dialect.dropPrimaryKeySyntax === 'DROP PRIMARY KEY') {
+            return `ALTER TABLE ${table} DROP PRIMARY KEY;`;
+        }
+        if (!constraintName) {
+            throw new TypeError(`Cannot drop the primary key of "${tableName}": ${this.dialect} names the constraint, and ` +
+                'introspection did not report a name for it.');
+        }
+        return `ALTER TABLE ${table} DROP CONSTRAINT ${this.escapeId(constraintName)};`;
+    }
+    assertPrimaryKeyAlterable(tableName) {
+        if (this.features.primaryKeyAlter) {
+            return;
+        }
+        throw new TypeError(`${this.dialect}: Cannot change the primary key of "${tableName}" - this database has no ALTER ` +
+            'for it. Recreate the table in a written migration.');
+    }
 }
 /**
  * The entities as an AST, named the way `generator` names things.

package/dist/mongo/mongoDialect.js

@@ -4,7 +4,7 @@ import { COUNT_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '..
 import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js';
 import { assertSoleId, getMeta, soleIdOf } from '../entity/index.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationSize, parseSortByCount, someKey, } from '../util/index.js';
+import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, buildQueryWhereAsMap, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export const mongoDialectFeatures = {
     explicitJsonCast: false,
@@ -16,6 +16,7 @@ export const mongoDialectFeatures = {
     dropTableCascade: false,
     renameColumn: false,
     foreignKeyAlter: false,
+    primaryKeyAlter: false,
     columnComment: false,
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,
@@ -168,7 +169,7 @@ export class MongoDialect extends AbstractDialect {
      */
     relationLookup(meta, relOpts, relMeta, relEntity, targetScope, temp, tail, opts) {
         return relOpts.cardinality === 'mm' && relOpts.through
-            ? this.junctionLookup(relOpts, relMeta, relEntity, targetScope, temp, tail, opts)
+            ? this.junctionLookup(meta, relOpts, relMeta, targetScope, temp, tail, opts)
             : {
                 $lookup: {
                     from: this.resolveTableName(relMeta),
@@ -182,22 +183,29 @@ export class MongoDialect extends AbstractDialect {
      * ManyToMany counts/tests junction rows, so the target is reached from inside the junction's own
      * lookup - the junction's filters apply too, since a soft-deleted link is not a link.
      */
-    junctionLookup(relOpts, relMeta, relEntity, targetScope, temp, tail, opts) {
+    junctionLookup(meta, relOpts, relMeta, targetScope, temp, tail, opts) {
         const throughEntity = relOpts.through();
         const throughMeta = getMeta(throughEntity);
         const junctionScope = this.renderFilter(throughEntity, this.scopedWhereMap(throughMeta, {}), opts);
         const nested = REL_NESTED_KEY;
+        // Both ends are one column here - each `$lookup` matches one field against `_id` - so both sides
+        // must be sole-keyed. Sliced rather than indexed positionally: `references[1]` is the parent's
+        // *second* column on a composite, a real column of the wrong side.
+        assertSoleId(meta, 'MongoDB');
+        assertSoleId(relMeta, 'MongoDB');
+        const [parentJoin] = parentJoins(relOpts, meta.ids.length);
+        const [targetColumn] = targetKeyColumns(relOpts, meta.ids.length);
         return {
             $lookup: {
                 from: this.resolveTableName(throughMeta),
                 localField: MongoDialect.ID_KEY,
-                foreignField: this.columnOf(throughMeta, relOpts.references[0].local),
+                foreignField: this.columnOf(throughMeta, parentJoin.joined),
                 pipeline: [
                     ...(hasKeys(junctionScope) ? [{ $match: junctionScope }] : []),
                     {
                         $lookup: {
                             from: this.resolveTableName(relMeta),
-                            localField: this.columnOf(throughMeta, relOpts.references[1].local),
+                            localField: this.columnOf(throughMeta, targetColumn),
                             foreignField: MongoDialect.ID_KEY,
                             pipeline: [...(hasKeys(targetScope) ? [{ $match: targetScope }] : []), { $limit: 1 }],
                             as: nested,
@@ -659,9 +667,15 @@ export class MongoDialect extends AbstractDialect {
      * direction joins the parent's `_id` to the target's FK.
      */
     joinKeys(meta, relMeta, relOpts) {
-        return relOpts.cardinality === 'm1'
-            ? { localField: this.columnOf(meta, relOpts.references[0].local), foreignField: MongoDialect.ID_KEY }
-            : { localField: MongoDialect.ID_KEY, foreignField: this.columnOf(relMeta, relOpts.references[0].foreign) };
+        if (relOpts.cardinality === 'm1') {
+            // The target's side, not this entity's: a lookup matches one `localField` against one
+            // `foreignField`, so a composite target would join on its first column alone and gather the
+            // rows of every key that agrees on it. The other branch is refused by `columnOf` below, whose
+            // key *is* an id column; this one names a plain foreign key, so it has to say so itself.
+            assertSoleId(relMeta, 'MongoDB');
+            return { localField: this.columnOf(meta, relOpts.references[0].local), foreignField: MongoDialect.ID_KEY };
+        }
+        return { localField: MongoDialect.ID_KEY, foreignField: this.columnOf(relMeta, relOpts.references[0].foreign) };
     }
     /** `[column, key]` for the fields whose stored name differs from their property name, memoized per entity. */
     renamedColumns(meta) {

package/dist/postgres/postgresDialect.js

@@ -15,7 +15,7 @@ export class PostgresDialect extends PgLikeSqlDialect {
     hasNarrowVectorTypes = true;
     upsert(ctx, entity, conflictPaths, payload) {
         // The xmax system column is 0 for a newly inserted row and non-zero for an updated one (MVCC).
-        super.upsert(ctx, entity, conflictPaths, payload, `, (xmax = 0) AS ${this.escapeId('_created')}`);
+        super.upsert(ctx, entity, conflictPaths, payload, `(xmax = 0) AS ${this.escapeId('_created')}`);
     }
     /**
      * `to_regclass` rather than a `::regclass` cast: it answers `NULL` for a table that does not exist

package/dist/querier/abstractQuerier.js

@@ -1,5 +1,5 @@
-import { getMeta, idOf, soleIdOf } from '../entity/index.js';
-import { asSelectMap, augmentWhere, childrenOf, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, LoggerWrapper, parentJoins, parentsIn, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, withoutSoftDeleteFilter, } from '../util/index.js';
+import { assertSoleId, getMeta, idOf, soleIdOf } from '../entity/index.js';
+import { asSelectMap, augmentWhere, childrenOf, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, joinedRowKey, LoggerWrapper, parentJoins, parentRowKey, parentsIn, parseRelationAtKey, parseRelationQueryValue, runHooks, someKey, targetKeyColumns, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
@@ -306,7 +306,7 @@ export class AbstractQuerier {
         const { $select: _select, $exclude: _exclude, $where: _where, ...throughQuery } = relationQuery;
         const throughFounds = await this.findMany(throughEntity, {
             ...throughQuery,
-            $select: Object.fromEntries(joins.map(({ joined }) => [joined, true])),
+            $select: joinedColumns(joins),
             $populate: {
                 [targetRelKey]: {
                     ...relationQuery,
@@ -315,6 +315,8 @@ export class AbstractQuerier {
             },
             $where: parentsIn(joins, payload),
         });
+        // The junction's own columns carried onto the target's row, which is where `putChildrenInParents`
+        // reads them back from - a junction row holds the parent's key under `joined`, not under `parent`.
         const founds = throughFounds.map((it) => ({
             ...it[targetRelKey],
             ...Object.fromEntries(joins.map(({ joined }) => [joined, it[joined]])),
@@ -343,15 +345,13 @@ export class AbstractQuerier {
         for (const child of children) {
             // Every joined column, so two children agreeing on one column of a composite key are not
             // gathered under the same parent.
-            const parentId = rowKey(joins.map(({ joined }) => child[joined]));
-            (childrenByParentId[parentId] ??= []).push(child);
+            (childrenByParentId[joinedRowKey(joins, child)] ??= []).push(child);
         }
         for (const parent of parents) {
             // `[]` rather than nothing for a parent with no children: a populated to-many is a list the
             // caller asked for, so it maps and counts without a guard, and its type can say so. An
             // unpopulated one stays absent, which is what tells the two apart.
-            const key = rowKey(joins.map(({ parent: parentKey }) => parent[parentKey]));
-            parent[relKey] = (childrenByParentId[key] ?? []);
+            parent[relKey] = (childrenByParentId[parentRowKey(joins, parent)] ?? []);
         }
     }
     async insertRelations(entity, payload) {
@@ -411,6 +411,11 @@ export class AbstractQuerier {
         const relOpts = meta.relations[relKey];
         if (!relOpts)
             return;
+        // Here rather than only in the callers below: writing the parent's key into a child is one column
+        // per key, so a composite takes a statement per parent. `soleParentColumn` and the sole
+        // `targetKeyColumns` under it read the *first* pair, which is a real column of a wrong pairing
+        // unless this has run - and this method is `protected`, so a caller can arrive without them.
+        assertSoleId(meta, 'saving a relation');
         const relEntity = relOpts.entity();
         const relPayload = relValue;
         switch (relOpts.cardinality) {
@@ -438,6 +443,12 @@ export class AbstractQuerier {
                 // would link every parent to a single shared row instead.
                 for (const id of ids) {
                     const savedIds = await this.saveMany(relEntity, relPayload);
+                    // A link needs the target's id, and a driver that cannot report one (a MySQL batch mixing
+                    // supplied and generated keys) would otherwise write a row pointing at `undefined`.
+                    if (savedIds.some((relId) => relId === undefined)) {
+                        throw new TypeError(`'${relEntity.name}' rows saved through '${throughEntity.name}' reported no id, so they cannot be linked. ` +
+                            'Insert them with their own ids, or save the relation in its own statement.');
+                    }
                     await this.insertMany(throughEntity, savedIds.map((relId) => ({ [localField]: id, [targetColumn]: relId })));
                 }
             }