uql-orm 0.42.0 → 0.42.1

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 { 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,8 +49,8 @@ export class SqlSchemaGenerator {
     /**
      * Primary key type for auto-increment integer IDs
      */
-    get serialPrimaryKeyType() {
-        return this.dialect.serialPrimaryKey;
+    get serialType() {
+        return this.dialect.serialType;
     }
     /**
      * Convert FieldOptions to CanonicalType using the unified type system.
@@ -128,6 +130,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 +168,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 +192,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 +203,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 +225,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 +243,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 +252,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,7 +275,7 @@ export class SqlSchemaGenerator {
             ? ''
             : ` DEFAULT ${formatDefaultValue(column.defaultValue, this.dialect, column.type)}`;
     }
-    getSqlType(field, fieldType) {
+    getSqlType(field, fieldType, isSoleKey = field.isId === true) {
         // If field has a reference, inherit type from the target primary key
         if (field.references) {
             const refEntity = field.references();
@@ -275,8 +286,8 @@ export class SqlSchemaGenerator {
         // Get canonical type and convert to SQL
         const canonical = this.getCanonicalType(field, fieldType);
         // Special case for serial primary keys
-        if (isAutoIncrement(field, field.isId === true)) {
-            return this.dialect.serialPrimaryKey;
+        if (isAutoIncrement(field, isSoleKey)) {
+            return this.dialect.serialType;
         }
         return this.canonicalTypeToSql(canonical);
     }
@@ -323,80 +334,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: (type) => sqlToCanonical(this.canonicalTypeToSql(type)),
+            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 +426,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 +466,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 +522,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 +573,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 })));
                 }
             }

package/dist/querier/relationCount.js

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