@mikro-orm/knex 6.0.0-rc.0 → 6.0.0-rc.2

package/query/QueryBuilderHelper.js

@@ -300,7 +300,7 @@ class QueryBuilderHelper {
     }
     isOneToOneInverse(field, meta) {
         meta ??= this.metadata.find(this.entityName);
-        const prop = meta.properties[field];
+        const prop = meta.properties[field.replace(/:ref$/, '')];
         return prop && prop.kind === core_1.ReferenceKind.ONE_TO_ONE && !prop.owner;
     }
     getTableName(entityName) {
@@ -462,24 +462,21 @@ class QueryBuilderHelper {
     }
     getQueryOrder(type, orderBy, populate) {
         if (Array.isArray(orderBy)) {
-            return orderBy
-                .map(o => this.getQueryOrder(type, o, populate))
-                .filter(o => o)
-                .join(', ');
+            return orderBy.flatMap(o => this.getQueryOrder(type, o, populate));
         }
         return this.getQueryOrderFromObject(type, orderBy, populate);
     }
     getQueryOrderFromObject(type, orderBy, populate) {
         const ret = [];
-        Object.keys(orderBy).forEach(key => {
+        for (const key of Object.keys(orderBy)) {
             const direction = orderBy[key];
             const order = core_1.Utils.isNumber(direction) ? core_1.QueryOrderNumeric[direction] : direction;
             const raw = core_1.RawQueryFragment.getKnownFragment(key);
             if (raw) {
                 ret.push(`${this.platform.formatQuery(raw.sql, raw.params)} ${order.toLowerCase()}`);
-                return;
+                continue;
             }
-            core_1.Utils.splitPrimaryKeys(key).forEach(f => {
+            for (const f of core_1.Utils.splitPrimaryKeys(key)) {
                 // eslint-disable-next-line prefer-const
                 let [alias, field] = this.splitField(f, true);
                 alias = populate[alias] || alias;
@@ -496,14 +493,14 @@ class QueryBuilderHelper {
                     colPart = this.platform.formatQuery(colPart.sql, colPart.params);
                 }
                 if (Array.isArray(order)) {
-                    order.forEach(part => ret.push(this.getQueryOrderFromObject(type, part, populate)));
+                    order.forEach(part => ret.push(...this.getQueryOrderFromObject(type, part, populate)));
                 }
                 else {
                     ret.push(`${colPart} ${order.toLowerCase()}`);
                 }
-            });
-        });
-        return ret.join(', ');
+            }
+        }
+        return ret;
     }
     finalize(type, qb, meta, data, returning) {
         if (!meta || !data || !this.platform.usesReturningStatement()) {
@@ -532,17 +529,21 @@ class QueryBuilderHelper {
     }
     splitField(field, greedyAlias = false) {
         const parts = field.split('.');
+        const ref = parts[parts.length - 1].split(':')[1];
+        if (ref) {
+            parts[parts.length - 1] = parts[parts.length - 1].substring(0, parts[parts.length - 1].indexOf(':'));
+        }
         if (parts.length === 1) {
-            return [this.alias, parts[0]];
+            return [this.alias, parts[0], ref];
         }
         if (greedyAlias) {
             const fromField = parts.pop();
             const fromAlias = parts.join('.');
-            return [fromAlias, fromField];
+            return [fromAlias, fromField, ref];
         }
         const fromAlias = parts.shift();
         const fromField = parts.join('.');
-        return [fromAlias, fromField];
+        return [fromAlias, fromField, ref];
     }
     getLockSQL(qb, lockMode, lockTables = []) {
         const meta = this.metadata.find(this.entityName);

package/query/ScalarCriteriaNode.d.ts

@@ -1,10 +1,10 @@
 import { CriteriaNode } from './CriteriaNode';
-import type { IQueryBuilder } from '../typings';
+import type { IQueryBuilder, ICriteriaNodeProcessOptions } from '../typings';
 /**
  * @internal
  */
 export declare class ScalarCriteriaNode<T extends object> extends CriteriaNode<T> {
-    process(qb: IQueryBuilder<T>, alias?: string): any;
+    process(qb: IQueryBuilder<T>, options?: ICriteriaNodeProcessOptions): any;
     willAutoJoin<T>(qb: IQueryBuilder<T>, alias?: string): boolean;
     shouldJoin(): boolean;
 }

package/query/ScalarCriteriaNode.js

@@ -8,16 +8,16 @@ const enums_1 = require("./enums");
  * @internal
  */
 class ScalarCriteriaNode extends CriteriaNode_1.CriteriaNode {
-    process(qb, alias) {
+    process(qb, options) {
         if (this.shouldJoin()) {
             const path = this.getPath();
             const parentPath = this.parent.getPath(); // the parent is always there, otherwise `shouldJoin` would return `false`
             const nestedAlias = qb.getAliasForJoinPath(path) || qb.getNextAlias(this.prop?.pivotTable ?? this.entityName);
-            const field = `${alias}.${this.prop.name}`;
+            const field = this.aliased(this.prop.name, options?.alias);
             const type = this.prop.kind === core_1.ReferenceKind.MANY_TO_MANY ? enums_1.JoinType.pivotJoin : enums_1.JoinType.leftJoin;
             qb.join(field, nestedAlias, undefined, type, path);
             // select the owner as virtual property when joining from 1:1 inverse side, but only if the parent is root entity
-            if (this.prop.kind === core_1.ReferenceKind.ONE_TO_ONE && !parentPath.includes('.')) {
+            if (this.prop.kind === core_1.ReferenceKind.ONE_TO_ONE && !parentPath.includes('.') && !qb._fields?.includes(field)) {
                 qb.addSelect(field);
             }
         }

package/schema/DatabaseSchema.js

@@ -73,7 +73,7 @@ class DatabaseSchema {
             table.comment = meta.comment;
             meta.props
                 .filter(prop => this.shouldHaveColumn(meta, prop))
-                .forEach(prop => table.addColumnFromProperty(prop, meta));
+                .forEach(prop => table.addColumnFromProperty(prop, meta, config));
             meta.indexes.forEach(index => table.addIndex(meta, index, 'index'));
             meta.uniques.forEach(index => table.addIndex(meta, index, 'unique'));
             table.addIndex(meta, { properties: meta.props.filter(prop => prop.primary).map(prop => prop.name) }, 'primary');

package/schema/DatabaseTable.d.ts

@@ -1,4 +1,4 @@
-import { type Dictionary, type EntityMetadata, type EntityProperty, type NamingStrategy } from '@mikro-orm/core';
+import { type Configuration, type Dictionary, type EntityMetadata, type EntityProperty, type MikroORMOptions, type NamingStrategy } from '@mikro-orm/core';
 import type { SchemaHelper } from './SchemaHelper';
 import type { CheckDef, Column, ForeignKey, IndexDef } from '../typings';
 import type { AbstractSqlPlatform } from '../AbstractSqlPlatform';
@@ -23,9 +23,13 @@ export declare class DatabaseTable {
     getChecks(): CheckDef[];
     init(cols: Column[], indexes: IndexDef[] | undefined, checks: CheckDef<unknown>[] | undefined, pks: string[], fks?: Dictionary<ForeignKey>, enums?: Dictionary<string[]>): void;
     addColumn(column: Column): void;
-    addColumnFromProperty(prop: EntityProperty, meta: EntityMetadata): void;
+    addColumnFromProperty(prop: EntityProperty, meta: EntityMetadata, config: Configuration): void;
     private getIndexName;
-    getEntityDeclaration(namingStrategy: NamingStrategy, schemaHelper: SchemaHelper): EntityMetadata;
+    getEntityDeclaration(namingStrategy: NamingStrategy, schemaHelper: SchemaHelper, scalarPropertiesForRelations: NonNullable<MikroORMOptions['entityGenerator']['scalarPropertiesForRelations']>): EntityMetadata;
+    private foreignKeysToProps;
+    private findFkIndex;
+    private getIndexProperties;
+    private getSafeBaseNameForFkProp;
     /**
      * The shortest name is stripped of the default namespace. All other namespaced elements are returned as full-qualified names.
      */
@@ -38,10 +42,12 @@ export declare class DatabaseTable {
     hasCheck(checkName: string): boolean;
     getPrimaryKey(): IndexDef | undefined;
     hasPrimaryKey(): boolean;
+    private getForeignKeyDeclaration;
     private getPropertyDeclaration;
     private getReferenceKind;
     private getPropertyName;
-    private getPropertyType;
+    private getPropertyTypeForForeignKey;
+    private getPropertyTypeForColumn;
     private getPropertyDefaultValue;
     addIndex(meta: EntityMetadata, index: {
         properties: string | string[];

package/schema/DatabaseTable.js

@@ -57,7 +57,7 @@ class DatabaseTable {
     addColumn(column) {
         this.columns[column.name] = column;
     }
-    addColumnFromProperty(prop, meta) {
+    addColumnFromProperty(prop, meta, config) {
         prop.fieldNames.forEach((field, idx) => {
             const type = prop.enum ? 'enum' : prop.columnTypes[idx];
             const mappedType = this.platform.getMappedType(type);
@@ -105,7 +105,7 @@ class DatabaseTable {
         });
         if ([core_1.ReferenceKind.MANY_TO_ONE, core_1.ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
             const constraintName = this.getIndexName(true, prop.fieldNames, 'foreign');
-            let schema = prop.targetMeta.schema === '*' ? this.schema : prop.targetMeta.schema ?? this.schema;
+            let schema = prop.targetMeta.root.schema === '*' ? this.schema : (prop.targetMeta.root.schema ?? config.get('schema', this.platform.getDefaultSchemaName()));
             if (prop.referencedTableName.includes('.')) {
                 schema = undefined;
             }
@@ -151,40 +151,285 @@ class DatabaseTable {
         }
         return this.platform.getIndexName(this.name, columnNames, type);
     }
-    getEntityDeclaration(namingStrategy, schemaHelper) {
+    getEntityDeclaration(namingStrategy, schemaHelper, scalarPropertiesForRelations) {
+        const { fksOnColumnProps, fksOnStandaloneProps, columnFks, fkIndexes, nullableForeignKeys, skippedColumnNames, } = this.foreignKeysToProps(namingStrategy, scalarPropertiesForRelations);
         let name = namingStrategy.getClassName(this.name, '_');
         name = name.match(/^\d/) ? 'E' + name : name;
         const schema = new core_1.EntitySchema({ name, collection: this.name, schema: this.schema });
         const compositeFkIndexes = {};
         const compositeFkUniques = {};
-        for (const index of this.indexes.filter(index => index.columnNames.length > 1)) {
-            const properties = index.columnNames.map(col => this.getPropertyName(namingStrategy, this.getColumn(col)));
-            const ret = { name: index.keyName, properties: core_1.Utils.unique(properties) };
-            if (ret.properties.length === 1) {
+        const potentiallyUnmappedIndexes = this.indexes.filter(index => !index.primary // Skip primary index. Whether it's in use by scalar column or FK, it's already mapped.
+            && (index.columnNames.length > 1 // All composite indexes are to be mapped to entity decorators or FK props.
+                || !(index.columnNames[0] in columnFks) // Non-composite indexes for scalar props are to be mapped to the column.
+                || skippedColumnNames.includes(index.columnNames[0]) // Non-composite indexes for skipped columns are to be mapped as entity decorators.
+            )
+            // ignore indexes that don't have all column names (this can happen in sqlite where there is no way to infer this for expressions)
+            && !(index.columnNames.some(col => !col) && !index.expression));
+        for (const index of potentiallyUnmappedIndexes) {
+            const ret = { name: index.keyName };
+            // Index is for FK. Map to the FK prop and move on.
+            const fkForIndex = fkIndexes.get(index);
+            if (fkForIndex) {
+                ret.properties = [this.getPropertyName(namingStrategy, fkForIndex.baseName, fkForIndex.fk)];
                 const map = index.unique ? compositeFkUniques : compositeFkIndexes;
                 map[ret.properties[0]] = { keyName: index.keyName };
                 continue;
             }
-            if (index.primary) {
-                //
+            const properties = this.getIndexProperties(index, columnFks, fksOnColumnProps, fksOnStandaloneProps, namingStrategy);
+            // If there is a column that cannot be unambiguously mapped to a prop, render an expression.
+            if (index.expression) {
+                ret.expression = index.expression;
             }
-            else if (index.unique) {
-                schema.addUnique(ret);
+            else if (typeof properties === 'undefined') {
+                ret.expression = schemaHelper.getCreateIndexSQL(this.name, index);
             }
             else {
-                schema.addIndex(ret);
+                ret.properties = properties;
+                // If the index is for one property that is not a FK prop, map to the column prop and move on.
+                if (properties.length === 1 && !fksOnStandaloneProps.has(properties[0])) {
+                    const map = index.unique ? compositeFkUniques : compositeFkIndexes;
+                    map[properties[0]] = { keyName: index.keyName };
+                    continue;
+                }
+            }
+            // Composite indexes that aren't exclusively mapped to FK props get an entity decorator.
+            if (index.unique) {
+                schema.addUnique(ret);
+                continue;
             }
+            schema.addIndex(ret);
         }
-        for (const column of this.getColumns()) {
-            const prop = this.getPropertyDeclaration(column, namingStrategy, schemaHelper, compositeFkIndexes, compositeFkUniques);
+        const addedStandaloneFkPropsBasedOnColumn = new Set;
+        const nonSkippedColumns = this.getColumns().filter(column => !skippedColumnNames.includes(column.name));
+        for (const column of nonSkippedColumns) {
+            const columnName = column.name;
+            const standaloneFkPropBasedOnColumn = fksOnStandaloneProps.get(columnName);
+            if (standaloneFkPropBasedOnColumn && !fksOnColumnProps.get(columnName)) {
+                addedStandaloneFkPropsBasedOnColumn.add(columnName);
+                const [fkIndex, currentFk] = standaloneFkPropBasedOnColumn;
+                const prop = this.getForeignKeyDeclaration(currentFk, namingStrategy, schemaHelper, fkIndex, nullableForeignKeys.has(currentFk), columnName);
+                schema.addProperty(prop.name, prop.type, prop);
+            }
+            const prop = this.getPropertyDeclaration(column, namingStrategy, schemaHelper, compositeFkIndexes, compositeFkUniques, columnFks, fksOnColumnProps.get(columnName));
+            schema.addProperty(prop.name, prop.type, prop);
+        }
+        for (const [propBaseName, [fkIndex, currentFk]] of fksOnStandaloneProps.entries()) {
+            if (addedStandaloneFkPropsBasedOnColumn.has(propBaseName)) {
+                continue;
+            }
+            const prop = this.getForeignKeyDeclaration(currentFk, namingStrategy, schemaHelper, fkIndex, nullableForeignKeys.has(currentFk), propBaseName);
             schema.addProperty(prop.name, prop.type, prop);
         }
         const meta = schema.init().meta;
-        meta.relations
-            .filter(prop => prop.primary && prop.kind === core_1.ReferenceKind.MANY_TO_ONE && !meta.compositePK)
-            .forEach(prop => prop.kind = core_1.ReferenceKind.ONE_TO_ONE);
+        const oneToOneCandidateProperties = meta.relations
+            .filter(prop => prop.primary && prop.kind === core_1.ReferenceKind.MANY_TO_ONE);
+        if (oneToOneCandidateProperties.length === 1
+            && oneToOneCandidateProperties[0].fieldNames.length === (new Set(meta.getPrimaryProps().flatMap(prop => prop.fieldNames))).size) {
+            oneToOneCandidateProperties[0].kind = core_1.ReferenceKind.ONE_TO_ONE;
+        }
         return meta;
     }
+    foreignKeysToProps(namingStrategy, scalarPropertiesForRelations) {
+        const fks = Object.values(this.getForeignKeys());
+        const fksOnColumnProps = new Map();
+        const fksOnStandaloneProps = new Map();
+        const columnFks = {};
+        const fkIndexes = new Map();
+        const nullableForeignKeys = new Set();
+        for (const currentFk of fks) {
+            const fkIndex = this.findFkIndex(currentFk);
+            if (currentFk.columnNames.length === 1 && !fks.some(fk => fk !== currentFk && fk.columnNames.length === 1 && currentFk.columnNames[0] === fk.columnNames[0])) {
+                // Non-composite FK is the only possible one for a column. Render the column with it.
+                const columnName = currentFk.columnNames[0];
+                columnFks[columnName] ??= [];
+                columnFks[columnName].push(currentFk);
+                if (this.getColumn(columnName)?.nullable) {
+                    nullableForeignKeys.add(currentFk);
+                }
+                if (scalarPropertiesForRelations === 'always') {
+                    const baseName = this.getSafeBaseNameForFkProp(namingStrategy, currentFk, fks, columnName);
+                    fksOnStandaloneProps.set(baseName, [fkIndex, currentFk]);
+                    fkIndexes.set(fkIndex, { fk: currentFk, baseName });
+                }
+                else {
+                    fksOnColumnProps.set(columnName, currentFk);
+                    fkIndexes.set(fkIndex, { fk: currentFk, baseName: columnName });
+                }
+                continue;
+            }
+            const specificColumnNames = [];
+            const nullableColumnsInFk = [];
+            for (const columnName of currentFk.columnNames) {
+                columnFks[columnName] ??= [];
+                columnFks[columnName].push(currentFk);
+                if (!fks.some(fk => fk !== currentFk && fk.columnNames.includes(columnName))) {
+                    specificColumnNames.push(columnName);
+                }
+                if (this.getColumn(columnName)?.nullable) {
+                    nullableColumnsInFk.push(columnName);
+                }
+            }
+            if (nullableColumnsInFk.length > 0) {
+                nullableForeignKeys.add(currentFk);
+            }
+            if (specificColumnNames.length === 1 && ((nullableColumnsInFk.length === currentFk.columnNames.length || nullableColumnsInFk.length === 0) || (nullableColumnsInFk.length === 1 && nullableColumnsInFk[0] === specificColumnNames[0]))) {
+                // Composite FK has exactly one column which is not used in any other FK.
+                // The FK also doesn't have a mix of nullable and non-nullable columns,
+                // or its only nullable column is this very one.
+                // It is safe to just render this FK attached to the specific column.
+                const columnName = specificColumnNames[0];
+                if (scalarPropertiesForRelations === 'always') {
+                    const baseName = this.getSafeBaseNameForFkProp(namingStrategy, currentFk, fks, columnName);
+                    fksOnStandaloneProps.set(baseName, [fkIndex, currentFk]);
+                    fkIndexes.set(fkIndex, { fk: currentFk, baseName });
+                }
+                else {
+                    fksOnColumnProps.set(columnName, currentFk);
+                    fkIndexes.set(fkIndex, { fk: currentFk, baseName: columnName });
+                }
+                continue;
+            }
+            if (specificColumnNames.length === currentFk.columnNames.length) {
+                // All columns involved with this FK are only covered by this one FK.
+                if (nullableColumnsInFk.length <= 1) {
+                    // Also, this FK is either not nullable, or has only one nullable column.
+                    // It is safe to name the FK after the nullable column, or any non-nullable one (the first one is picked).
+                    const columnName = nullableColumnsInFk.at(0) ?? currentFk.columnNames[0];
+                    if (scalarPropertiesForRelations === 'always') {
+                        const baseName = this.getSafeBaseNameForFkProp(namingStrategy, currentFk, fks, columnName);
+                        fksOnStandaloneProps.set(baseName, [fkIndex, currentFk]);
+                        fkIndexes.set(fkIndex, { fk: currentFk, baseName });
+                    }
+                    else {
+                        fksOnColumnProps.set(columnName, currentFk);
+                        fkIndexes.set(fkIndex, { fk: currentFk, baseName: columnName });
+                    }
+                    continue;
+                }
+                // If the first nullable column's name with FK is different from the name without FK,
+                // name a standalone prop after the column, but treat the column prop itself as not having FK.
+                const columnName = nullableColumnsInFk[0];
+                const baseName = this.getSafeBaseNameForFkProp(namingStrategy, currentFk, fks, columnName);
+                fksOnStandaloneProps.set(baseName, [fkIndex, currentFk]);
+                fkIndexes.set(fkIndex, { fk: currentFk, baseName });
+                continue;
+            }
+            // FK is not unambiguously mappable to a column. Pick another name for a standalone FK prop.
+            const baseName = this.getSafeBaseNameForFkProp(namingStrategy, currentFk, fks);
+            fksOnStandaloneProps.set(baseName, [fkIndex, currentFk]);
+            fkIndexes.set(fkIndex, { fk: currentFk, baseName });
+        }
+        const columnsInFks = Object.keys(columnFks);
+        const skippingHandlers = {
+            // Never generate scalar props for composite keys,
+            // i.e. always skip columns if they are covered by foreign keys.
+            never: (column) => columnsInFks.includes(column.name) && !fksOnColumnProps.has(column.name),
+            // Always generate scalar props for composite keys,
+            // i.e. do not skip columns, even if they are covered by foreign keys.
+            always: (column) => false,
+            // Smart scalar props generation.
+            // Skips columns if they are covered by foreign keys.
+            // But also does not skip if the column is not nullable, and yet all involved FKs are nullable,
+            // or if one or more FKs involved has multiple nullable columns.
+            smart: (column) => {
+                return columnsInFks.includes(column.name)
+                    && !fksOnColumnProps.has(column.name)
+                    && (column.nullable
+                        ? columnFks[column.name].some(fk => !fk.columnNames.some(fkColumnName => fkColumnName !== column.name && this.getColumn(fkColumnName)?.nullable))
+                        : columnFks[column.name].some(fk => !nullableForeignKeys.has(fk)));
+            },
+        };
+        const skippedColumnNames = this.getColumns().filter(skippingHandlers[scalarPropertiesForRelations]).map(column => column.name);
+        return { fksOnColumnProps, fksOnStandaloneProps, columnFks, fkIndexes, nullableForeignKeys, skippedColumnNames };
+    }
+    findFkIndex(currentFk) {
+        const fkColumnsLength = currentFk.columnNames.length;
+        const possibleIndexes = this.indexes.filter(index => {
+            return index.columnNames.length >= fkColumnsLength && !currentFk.columnNames.some((columnName, i) => index.columnNames[i] !== columnName);
+        });
+        possibleIndexes.sort((a, b) => {
+            if (a.primary !== b.primary) {
+                return a.primary ? -1 : 1;
+            }
+            if (a.unique !== b.unique) {
+                return a.unique ? -1 : 1;
+            }
+            if (a.columnNames.length !== b.columnNames.length) {
+                return a.columnNames.length < b.columnNames.length ? -1 : 1;
+            }
+            return a.keyName.localeCompare(b.keyName);
+        });
+        return possibleIndexes[0];
+    }
+    getIndexProperties(index, columnFks, fksOnColumnProps, fksOnStandaloneProps, namingStrategy) {
+        const propBaseNames = new Set();
+        const columnNames = index.columnNames;
+        const l = columnNames.length;
+        if (columnNames.some(col => !col)) {
+            return;
+        }
+        for (let i = 0; i < l; ++i) {
+            const columnName = columnNames[i];
+            // The column is not involved with FKs.
+            // It has a prop named after it.
+            // Add it and move on.
+            if (!(columnName in columnFks)) {
+                propBaseNames.add(columnName);
+                continue;
+            }
+            // If the prop named after the column has a FK and the FK's columns are a subset of this index,
+            // include this prop and move on.
+            const columnPropFk = fksOnColumnProps.get(columnName);
+            if (columnPropFk && !columnPropFk.columnNames.some(fkColumnName => !columnNames.includes(fkColumnName))) {
+                propBaseNames.add(columnName);
+                continue;
+            }
+            // If there is at least one standalone FK featuring this column,
+            // and all of its columns are a subset of this index,
+            // include that FK, and consider mapping of this column to a prop a success.
+            let propAdded = false;
+            for (const [propName, [, fk]] of fksOnStandaloneProps) {
+                if (!columnFks[columnName].includes(fk)) {
+                    continue;
+                }
+                if (!fk.columnNames.some(fkColumnName => !columnNames.includes(fkColumnName))) {
+                    propBaseNames.add(propName);
+                    propAdded = true;
+                }
+            }
+            if (propAdded) {
+                continue;
+            }
+            // If we have reached this point, it means the column is not mappable to a prop name.
+            // Break the whole prop creation.
+            return;
+        }
+        return Array.from(propBaseNames).map(baseName => this.getPropertyName(namingStrategy, baseName, fksOnColumnProps.get(baseName)));
+    }
+    getSafeBaseNameForFkProp(namingStrategy, currentFk, fks, columnName) {
+        if (columnName && this.getPropertyName(namingStrategy, columnName, currentFk) !== this.getPropertyName(namingStrategy, columnName)) {
+            // The eligible scalar column name is different from the name of the FK prop of the same column.
+            // Both can be safely rendered.
+            // Use the column name as a base for the FK prop.
+            return columnName;
+        }
+        if (!fks.some(fk => fk !== currentFk && fk.referencedTableName === currentFk.referencedTableName) && !this.getColumn(currentFk.referencedTableName)) {
+            // FK is the only one in this table that references this other table.
+            // The name of the referenced table is not shared with a column in this table,
+            // so it is safe to output prop name based on the referenced entity.
+            return currentFk.referencedTableName;
+        }
+        // Any ambiguous FK is rendered with a name based on the FK constraint name
+        let finalPropBaseName = currentFk.constraintName;
+        while (this.getColumn(finalPropBaseName)) {
+            // In the unlikely event that the FK constraint name is shared by a column name, generate a name by
+            // continuously prefixing with "fk_", until a non-existent column is hit.
+            // The worst case scenario is a very long name with several repeated "fk_"
+            // that is not really a valid DB identifier but a valid JS variable name.
+            finalPropBaseName = `fk_${finalPropBaseName}`;
+        }
+        return finalPropBaseName;
+    }
     /**
      * The shortest name is stripped of the default namespace. All other namespaced elements are returned as full-qualified names.
      */
@@ -218,13 +463,48 @@ class DatabaseTable {
     hasPrimaryKey() {
         return !!this.getPrimaryKey();
     }
-    getPropertyDeclaration(column, namingStrategy, schemaHelper, compositeFkIndexes, compositeFkUniques) {
-        const fk = Object.values(this.foreignKeys).find(fk => fk.columnNames.includes(column.name));
-        const prop = this.getPropertyName(namingStrategy, column);
+    getForeignKeyDeclaration(fk, namingStrategy, schemaHelper, fkIndex, nullable, propNameBase) {
+        const prop = this.getPropertyName(namingStrategy, propNameBase, fk);
+        const kind = (fkIndex.unique && !fkIndex.primary) ? this.getReferenceKind(fk, fkIndex) : this.getReferenceKind(fk);
+        const type = this.getPropertyTypeForForeignKey(namingStrategy, fk);
+        const fkOptions = {};
+        fkOptions.fieldNames = fk.columnNames;
+        fkOptions.referencedTableName = fk.referencedTableName;
+        fkOptions.referencedColumnNames = fk.referencedColumnNames;
+        fkOptions.updateRule = fk.updateRule?.toLowerCase();
+        fkOptions.deleteRule = fk.deleteRule?.toLowerCase();
+        const columnOptions = {};
+        if (fk.columnNames.length === 1) {
+            const column = this.getColumn(fk.columnNames[0]);
+            columnOptions.default = this.getPropertyDefaultValue(schemaHelper, column, type);
+            columnOptions.defaultRaw = this.getPropertyDefaultValue(schemaHelper, column, type, true);
+            columnOptions.nullable = column.nullable;
+            columnOptions.primary = column.primary;
+            columnOptions.length = column.length;
+            columnOptions.precision = column.precision;
+            columnOptions.scale = column.scale;
+            columnOptions.enum = !!column.enumItems?.length;
+            columnOptions.items = column.enumItems;
+        }
+        return {
+            name: prop,
+            type,
+            kind,
+            ...columnOptions,
+            nullable,
+            primary: fkIndex.primary || !fk.columnNames.some(columnName => !this.getPrimaryKey()?.columnNames.includes(columnName)),
+            index: !fkIndex.unique ? fkIndex.keyName : undefined,
+            unique: (fkIndex.unique && !fkIndex.primary) ? fkIndex.keyName : undefined,
+            ...fkOptions,
+        };
+    }
+    getPropertyDeclaration(column, namingStrategy, schemaHelper, compositeFkIndexes, compositeFkUniques, columnFks, fk) {
+        const prop = this.getPropertyName(namingStrategy, column.name, fk);
+        const persist = !(column.name in columnFks && typeof fk === 'undefined');
         const index = compositeFkIndexes[prop] || this.indexes.find(idx => idx.columnNames[0] === column.name && !idx.composite && !idx.unique && !idx.primary);
         const unique = compositeFkUniques[prop] || this.indexes.find(idx => idx.columnNames[0] === column.name && !idx.composite && idx.unique && !idx.primary);
         const kind = this.getReferenceKind(fk, unique);
-        const type = this.getPropertyType(namingStrategy, column, fk);
+        const type = this.getPropertyTypeForColumn(namingStrategy, column, fk);
         const fkOptions = {};
         if (fk) {
             fkOptions.fieldNames = fk.columnNames;
@@ -241,7 +521,7 @@ class DatabaseTable {
             default: this.getPropertyDefaultValue(schemaHelper, column, type),
             defaultRaw: this.getPropertyDefaultValue(schemaHelper, column, type, true),
             nullable: column.nullable,
-            primary: column.primary,
+            primary: column.primary && persist,
             fieldName: column.name,
             length: column.length,
             precision: column.precision,
@@ -250,6 +530,7 @@ class DatabaseTable {
             unique: unique ? unique.keyName : undefined,
             enum: !!column.enumItems?.length,
             items: column.enumItems,
+            persist,
             ...fkOptions,
         };
     }
@@ -262,19 +543,28 @@ class DatabaseTable {
         }
         return core_1.ReferenceKind.SCALAR;
     }
-    getPropertyName(namingStrategy, column) {
-        const fk = Object.values(this.foreignKeys).find(fk => fk.columnNames.includes(column.name));
-        let field = column.name;
+    getPropertyName(namingStrategy, baseName, fk) {
+        let field = baseName;
         if (fk) {
-            const idx = fk.columnNames.indexOf(column.name);
-            field = field.replace(new RegExp(`_${fk.referencedColumnNames[idx]}$`), '');
+            const idx = fk.columnNames.indexOf(baseName);
+            let replacedFieldName = field.replace(new RegExp(`_${fk.referencedColumnNames[idx]}$`), '');
+            if (replacedFieldName === field) {
+                replacedFieldName = field.replace(new RegExp(`_${namingStrategy.referenceColumnName()}$`), '');
+            }
+            field = replacedFieldName;
+        }
+        if (field.startsWith('_')) {
+            return field;
         }
         return namingStrategy.columnNameToProperty(field);
     }
-    getPropertyType(namingStrategy, column, fk) {
+    getPropertyTypeForForeignKey(namingStrategy, fk) {
+        const parts = fk.referencedTableName.split('.', 2);
+        return namingStrategy.getClassName(parts.length > 1 ? parts[1] : parts[0], '_');
+    }
+    getPropertyTypeForColumn(namingStrategy, column, fk) {
         if (fk) {
-            const parts = fk.referencedTableName.split('.', 2);
-            return namingStrategy.getClassName(parts.length > 1 ? parts[1] : parts[0], '_');
+            return this.getPropertyTypeForForeignKey(namingStrategy, fk);
         }
         // If this column is using an enum.
         if (column.enumItems?.length) {

package/schema/SchemaComparator.d.ts

@@ -17,12 +17,12 @@ export declare class SchemaComparator {
      * operations to change the schema stored in fromSchema to the schema that is
      * stored in toSchema.
      */
-    compare(fromSchema: DatabaseSchema, toSchema: DatabaseSchema): SchemaDifference;
+    compare(fromSchema: DatabaseSchema, toSchema: DatabaseSchema, inverseDiff?: SchemaDifference): SchemaDifference;
     /**
      * Returns the difference between the tables fromTable and toTable.
      * If there are no differences this method returns the boolean false.
      */
-    diffTable(fromTable: DatabaseTable, toTable: DatabaseTable): TableDifference | false;
+    diffTable(fromTable: DatabaseTable, toTable: DatabaseTable, inverseTableDiff?: TableDifference): TableDifference | false;
     /**
      * Try to find columns that only changed their name, rename operations maybe cheaper than add/drop
      * however ambiguities between different possibilities should not lead to renaming at all.