@mikro-orm/core 7.0.0-dev.99 → 7.0.0-rc.1

package/metadata/MetadataDiscovery.js

@@ -1,13 +1,16 @@
 import { EntityMetadata, } from '../typings.js';
-import { Utils } from '../utils/Utils.js';
+import { compareArrays, Utils } from '../utils/Utils.js';
+import { QueryHelper } from '../utils/QueryHelper.js';
 import { MetadataValidator } from './MetadataValidator.js';
+import { MetadataProvider } from './MetadataProvider.js';
 import { MetadataStorage } from './MetadataStorage.js';
 import { EntitySchema } from './EntitySchema.js';
 import { Cascade, ReferenceKind } from '../enums.js';
 import { MetadataError } from '../errors.js';
 import { t, Type } from '../types/index.js';
 import { colors } from '../logging/colors.js';
-import { raw, RawQueryFragment } from '../utils/RawQueryFragment.js';
+import { raw, Raw } from '../utils/RawQueryFragment.js';
+import { BaseEntity } from '../entity/BaseEntity.js';
 export class MetadataDiscovery {
     metadata;
     platform;
@@ -30,7 +33,8 @@ export class MetadataDiscovery {
     async discover(preferTs = true) {
         this.discovered.length = 0;
         const startTime = Date.now();
-        this.logger.log('discovery', `ORM entity discovery started, using ${colors.cyan(this.metadataProvider.constructor.name)}`);
+        const suffix = this.metadataProvider.constructor === MetadataProvider ? '' : `, using ${colors.cyan(this.metadataProvider.constructor.name)}`;
+        this.logger.log('discovery', `ORM entity discovery started${suffix}`);
         await this.findEntities(preferTs);
         for (const meta of this.discovered) {
             /* v8 ignore next */
@@ -47,7 +51,8 @@ export class MetadataDiscovery {
     discoverSync() {
         this.discovered.length = 0;
         const startTime = Date.now();
-        this.logger.log('discovery', `ORM entity discovery started, using ${colors.cyan(this.metadataProvider.constructor.name)} in sync mode`);
+        const suffix = this.metadataProvider.constructor === MetadataProvider ? '' : `, using ${colors.cyan(this.metadataProvider.constructor.name)}`;
+        this.logger.log('discovery', `ORM entity discovery started${suffix} in sync mode`);
         const refs = this.config.get('entities');
         this.discoverReferences(refs);
         for (const meta of this.discovered) {
@@ -62,9 +67,6 @@ export class MetadataDiscovery {
         void this.config.get('discovery').afterDiscovered?.(storage, this.platform);
         return storage;
     }
-    validateDiscovered(metadata) {
-        return this.validator.validateDiscovered(metadata, this.config.get('discovery'));
-    }
     mapDiscoveredEntities() {
         const discovered = new MetadataStorage();
         this.discovered
@@ -72,8 +74,14 @@ export class MetadataDiscovery {
             .sort((a, b) => b.root.name.localeCompare(a.root.name))
             .forEach(meta => {
             this.platform.validateMetadata(meta);
-            discovered.set(meta.className, meta);
+            discovered.set(meta.class, meta);
         });
+        for (const meta of discovered) {
+            meta.root = discovered.get(meta.root.class);
+            if (meta.inheritanceType === 'tpt') {
+                this.computeTPTOwnProps(meta);
+            }
+        }
         return discovered;
     }
     initAccessors(meta) {
@@ -117,35 +125,48 @@ export class MetadataDiscovery {
         // sort so we discover entities first to get around issues with nested embeddables
         filtered.sort((a, b) => !a.embeddable === !b.embeddable ? 0 : (a.embeddable ? 1 : -1));
         filtered.forEach(meta => this.initSingleTableInheritance(meta, filtered));
+        filtered.forEach(meta => this.initTPTRelationships(meta, filtered));
         filtered.forEach(meta => this.defineBaseEntityProperties(meta));
-        filtered.forEach(meta => this.metadata.set(meta.className, EntitySchema.fromMetadata(meta).init().meta));
+        filtered.forEach(meta => {
+            const newMeta = EntitySchema.fromMetadata(meta).init().meta;
+            return this.metadata.set(newMeta.class, newMeta);
+        });
         filtered.forEach(meta => this.initAutoincrement(meta));
-        filtered.forEach(meta => Object.values(meta.properties).forEach(prop => this.initEmbeddables(meta, prop)));
-        filtered.forEach(meta => Object.values(meta.properties).forEach(prop => this.initFactoryField(meta, prop)));
-        filtered.forEach(meta => Object.values(meta.properties).forEach(prop => this.initFieldName(prop)));
-        filtered.forEach(meta => Object.values(meta.properties).forEach(prop => this.initVersionProperty(meta, prop)));
-        filtered.forEach(meta => Object.values(meta.properties).forEach(prop => this.initCustomType(meta, prop)));
-        filtered.forEach(meta => Object.values(meta.properties).forEach(prop => this.initGeneratedColumn(meta, prop)));
+        const forEachProp = (cb) => {
+            filtered.forEach(meta => Object.values(meta.properties).forEach(prop => cb(meta, prop)));
+        };
+        forEachProp((m, p) => this.initFactoryField(m, p));
+        forEachProp((m, p) => this.initPolymorphicRelation(m, p, filtered));
+        forEachProp((_m, p) => this.initRelation(p));
+        forEachProp((m, p) => this.initEmbeddables(m, p));
+        forEachProp((_m, p) => this.initFieldName(p));
+        filtered.forEach(meta => this.finalizeTPTInheritance(meta, filtered));
+        filtered.forEach(meta => this.computeTPTOwnProps(meta));
+        forEachProp((m, p) => this.initVersionProperty(m, p));
+        forEachProp((m, p) => this.initCustomType(m, p));
+        forEachProp((m, p) => this.initGeneratedColumn(m, p));
         filtered.forEach(meta => this.initAutoincrement(meta)); // once again after we init custom types
         filtered.forEach(meta => this.initCheckConstraints(meta));
-        for (const meta of filtered) {
-            for (const prop of Object.values(meta.properties)) {
-                this.initDefaultValue(prop);
-                this.inferTypeFromDefault(prop);
-                this.initColumnType(prop);
-            }
-        }
-        filtered.forEach(meta => Object.values(meta.properties).forEach(prop => this.initIndexes(meta, prop)));
+        forEachProp((_m, p) => {
+            this.initDefaultValue(p);
+            this.inferTypeFromDefault(p);
+            this.initRelation(p);
+            this.initColumnType(p);
+        });
+        forEachProp((m, p) => this.initIndexes(m, p));
         filtered.forEach(meta => this.autoWireBidirectionalProperties(meta));
-        filtered.forEach(meta => this.findReferencingProperties(meta, filtered));
         for (const meta of filtered) {
             discovered.push(...this.processEntity(meta));
         }
         discovered.forEach(meta => meta.sync(true));
         this.metadataProvider.combineCache();
         return discovered.map(meta => {
-            meta = this.metadata.get(meta.className);
+            meta = this.metadata.get(meta.class);
             meta.sync(true);
+            this.findReferencingProperties(meta, filtered);
+            if (meta.inheritanceType === 'tpt') {
+                this.computeTPTOwnProps(meta);
+            }
             return meta;
         });
     }
@@ -153,15 +174,19 @@ export class MetadataDiscovery {
         const { entities, entitiesTs, baseDir } = this.config.getAll();
         const targets = (preferTs && entitiesTs.length > 0) ? entitiesTs : entities;
         const processed = [];
+        const paths = [];
         for (const entity of targets) {
             if (typeof entity === 'string') {
-                const { discoverEntities } = await import('@mikro-orm/core/file-discovery');
-                processed.push(...await discoverEntities(entity, { baseDir }));
+                paths.push(entity);
             }
             else {
                 processed.push(entity);
             }
         }
+        if (paths.length > 0) {
+            const { discoverEntities } = await import('@mikro-orm/core/file-discovery');
+            processed.push(...await discoverEntities(paths, { baseDir }));
+        }
         return this.discoverReferences(processed);
     }
     discoverMissingTargets() {
@@ -171,17 +196,22 @@ export class MetadataDiscovery {
             .replace(/\((.*)\)/, '$1'); // unwrap union types
         const missing = [];
         this.discovered.forEach(meta => Object.values(meta.properties).forEach(prop => {
-            if (prop.kind === ReferenceKind.MANY_TO_MANY && prop.pivotEntity && !this.discovered.find(m => m.className === Utils.className(prop.pivotEntity))) {
-                const target = typeof prop.pivotEntity === 'function'
-                    ? prop.pivotEntity()
-                    : prop.pivotEntity;
-                missing.push(target);
-            }
-            if (prop.kind !== ReferenceKind.SCALAR && !unwrap(prop.type).split(/ ?\| ?/).every(type => this.discovered.find(m => m.className === type))) {
-                const target = typeof prop.entity === 'function'
+            if (prop.kind === ReferenceKind.MANY_TO_MANY && prop.pivotEntity) {
+                const pivotEntity = prop.pivotEntity;
+                const target = typeof pivotEntity === 'function' && !pivotEntity.prototype
+                    ? pivotEntity()
+                    : pivotEntity;
+                if (!this.discovered.find(m => m.className === Utils.className(target))) {
+                    missing.push(target);
+                }
+            }
+            if (prop.kind !== ReferenceKind.SCALAR) {
+                const target = typeof prop.entity === 'function' && !prop.entity.prototype
                     ? prop.entity()
                     : prop.type;
-                missing.push(...Utils.asArray(target));
+                if (!unwrap(prop.type).split(/ ?\| ?/).every(type => this.discovered.find(m => m.className === type))) {
+                    missing.push(...Utils.asArray(target));
+                }
             }
         }));
         if (missing.length > 0) {
@@ -190,10 +220,15 @@ export class MetadataDiscovery {
     }
     tryDiscoverTargets(targets) {
         for (const target of targets) {
-            const isDiscoverable = typeof target === 'function' || target instanceof EntitySchema;
-            if (isDiscoverable && target.name && !this.metadata.has(target.name)) {
-                this.discoverReferences([target], false);
-                this.discoverMissingTargets();
+            const schema = target instanceof EntitySchema ? target : undefined;
+            const isDiscoverable = typeof target === 'function' || schema;
+            if (isDiscoverable && target.name) {
+                // Get the actual class for EntitySchema, or use target directly for classes
+                const targetClass = schema ? schema.meta.class : target;
+                if (!this.metadata.has(targetClass)) {
+                    this.discoverReferences([target], false);
+                    this.discoverMissingTargets();
+                }
             }
         }
     }
@@ -205,16 +240,16 @@ export class MetadataDiscovery {
             }
             const schema = this.getSchema(entity);
             const meta = schema.init().meta;
-            this.metadata.set(meta.className, meta);
+            this.metadata.set(meta.class, meta);
             found.push(schema);
         }
         // discover parents (base entities) automatically
         for (const meta of this.metadata) {
             let parent = meta.extends;
-            if (parent instanceof EntitySchema && !this.metadata.has(parent.meta.className)) {
+            if (parent instanceof EntitySchema && !this.metadata.has(parent.init().meta.class)) {
                 this.discoverReferences([parent], false);
             }
-            if (typeof parent === 'function' && parent.name && !this.metadata.has(parent.name)) {
+            if (typeof parent === 'function' && parent.name && !this.metadata.has(parent)) {
                 this.discoverReferences([parent], false);
             }
             /* v8 ignore next */
@@ -222,7 +257,8 @@ export class MetadataDiscovery {
                 continue;
             }
             parent = Object.getPrototypeOf(meta.class);
-            if (parent.name !== '' && !this.metadata.has(parent.name)) {
+            // Skip if parent is the auto-generated base class for the same entity (from setClass usage)
+            if (parent.name !== '' && parent.name !== meta.className && !this.metadata.has(parent) && parent !== BaseEntity) {
                 this.discoverReferences([parent], false);
             }
         }
@@ -231,14 +267,14 @@ export class MetadataDiscovery {
         }
         this.discoverMissingTargets();
         if (validate) {
-            this.validateDiscovered(this.discovered);
+            this.validator.validateDiscovered(this.discovered, this.config.get('discovery'));
         }
         return this.discovered.filter(meta => found.find(m => m.name === meta.className));
     }
-    reset(className) {
-        const exists = this.discovered.findIndex(m => m.className === className);
+    reset(entityName) {
+        const exists = this.discovered.findIndex(m => m.class === entityName || m.className === Utils.className(entityName));
         if (exists !== -1) {
-            this.metadata.reset(this.discovered[exists].className);
+            this.metadata.reset(this.discovered[exists].class);
             this.discovered.splice(exists, 1);
         }
     }
@@ -253,23 +289,25 @@ export class MetadataDiscovery {
         const path = entity[MetadataStorage.PATH_SYMBOL];
         if (path) {
             const meta = Utils.copy(MetadataStorage.getMetadata(entity.name, path), false);
-            meta.path = Utils.relativePath(path, this.config.get('baseDir'));
-            this.metadata.set(entity.name, meta);
+            meta.path = path;
+            this.metadata.set(entity, meta);
         }
-        const exists = this.metadata.has(entity.name);
-        const meta = this.metadata.get(entity.name, true);
+        const exists = this.metadata.has(entity);
+        const meta = this.metadata.get(entity, true);
         meta.abstract ??= !(exists && meta.name);
         const schema = EntitySchema.fromMetadata(meta);
         schema.setClass(entity);
         return schema;
     }
     getRootEntity(meta) {
-        const base = meta.extends && this.metadata.find(Utils.className(meta.extends));
+        const base = meta.extends && this.metadata.find(meta.extends);
         if (!base || base === meta) { // make sure we do not fall into infinite loop
             return meta;
         }
         const root = this.getRootEntity(base);
-        if (root.discriminatorColumn) {
+        // For STI or TPT, use the root entity.
+        // Check both `inheritanceType` (set during discovery) and raw `inheritance` option (set before discovery).
+        if (root.discriminatorColumn || root.inheritanceType || root.inheritance === 'tpt') {
             return root;
         }
         return meta;
@@ -279,7 +317,7 @@ export class MetadataDiscovery {
         const path = meta.path;
         this.logger.log('discovery', `- processing entity ${colors.cyan(meta.className)}${colors.grey(path ? ` (${path})` : '')}`);
         const root = this.getRootEntity(meta);
-        schema.meta.path = Utils.relativePath(meta.path, this.config.get('baseDir'));
+        schema.meta.path = meta.path;
         const cache = this.metadataProvider.getCachedMetadata(meta, root);
         if (cache) {
             this.logger.log('discovery', `- using cached metadata for entity ${colors.cyan(meta.className)}`);
@@ -292,9 +330,9 @@ export class MetadataDiscovery {
         }
         // if the definition is using EntitySchema we still want it to go through the metadata provider to validate no types are missing
         this.metadataProvider.loadEntityMetadata(meta);
-        if (!meta.collection && meta.name) {
+        if (!meta.tableName && meta.name) {
             const entityName = root.discriminatorColumn ? root.name : meta.name;
-            meta.collection = this.namingStrategy.classToTableName(entityName);
+            meta.tableName = this.namingStrategy.classToTableName(entityName);
         }
         this.metadataProvider.saveToCache(meta);
         meta.root = root;
@@ -326,6 +364,12 @@ export class MetadataDiscovery {
             if (!prop.joinColumns || !prop.columnTypes || prop.ownColumns || ![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
                 continue;
             }
+            // For polymorphic relations, ownColumns should include all fieldNames
+            // (discriminator + ID columns) since they are all owned by this relation
+            if (prop.polymorphic) {
+                prop.ownColumns = prop.fieldNames;
+                continue;
+            }
             if (prop.joinColumns.length > 1) {
                 prop.ownColumns = prop.joinColumns.filter(col => {
                     return !meta.props.find(p => p.name !== prop.name && (!p.fieldNames || p.fieldNames.includes(col)));
@@ -356,30 +400,30 @@ export class MetadataDiscovery {
         if (prop.kind === ReferenceKind.SCALAR || prop.kind === ReferenceKind.EMBEDDED) {
             prop.fieldNames = [this.namingStrategy.propertyToColumnName(prop.name, object)];
         }
-        else if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+        else if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && !prop.polymorphic) {
             prop.fieldNames = this.initManyToOneFieldName(prop, prop.name);
         }
         else if (prop.kind === ReferenceKind.MANY_TO_MANY && prop.owner) {
             prop.fieldNames = this.initManyToManyFieldName(prop, prop.name);
         }
     }
-    initManyToOneFieldName(prop, name) {
-        const meta2 = this.metadata.get(prop.type);
+    initManyToOneFieldName(prop, name, tableName) {
+        const meta2 = prop.targetMeta;
         const ret = [];
         for (const primaryKey of meta2.primaryKeys) {
             this.initFieldName(meta2.properties[primaryKey]);
             for (const fieldName of meta2.properties[primaryKey].fieldNames) {
-                ret.push(this.namingStrategy.joinKeyColumnName(name, fieldName, meta2.compositePK));
+                ret.push(this.namingStrategy.joinKeyColumnName(name, fieldName, meta2.compositePK, tableName));
             }
         }
         return ret;
     }
     initManyToManyFieldName(prop, name) {
-        const meta2 = this.metadata.get(prop.type);
+        const meta2 = prop.targetMeta;
         return meta2.primaryKeys.map(() => this.namingStrategy.propertyToColumnName(name));
     }
     initManyToManyFields(meta, prop) {
-        const meta2 = this.metadata.get(prop.type);
+        const meta2 = prop.targetMeta;
         Utils.defaultValue(prop, 'fixedOrder', !!prop.fixedOrderColumn);
         const pivotMeta = this.metadata.find(prop.pivotEntity);
         const props = Object.values(pivotMeta?.properties ?? {});
@@ -400,35 +444,77 @@ export class MetadataDiscovery {
             prop.inverseJoinColumns ??= second.fieldNames;
         }
         if (!prop.pivotTable && prop.owner && this.platform.usesPivotTable()) {
-            prop.pivotTable = this.namingStrategy.joinTableName(meta.tableName, meta2.tableName, prop.name);
+            prop.pivotTable = this.namingStrategy.joinTableName(meta.className, meta2.tableName, prop.name, meta.tableName);
         }
         if (prop.mappedBy) {
             const prop2 = meta2.properties[prop.mappedBy];
             this.initManyToManyFields(meta2, prop2);
             prop.pivotTable = prop2.pivotTable;
-            prop.pivotEntity = prop2.pivotEntity ?? prop2.pivotTable;
+            prop.pivotEntity = prop2.pivotEntity;
             prop.fixedOrder = prop2.fixedOrder;
             prop.fixedOrderColumn = prop2.fixedOrderColumn;
             prop.joinColumns = prop2.inverseJoinColumns;
             prop.inverseJoinColumns = prop2.joinColumns;
+            prop.polymorphic = prop2.polymorphic;
+            prop.discriminator = prop2.discriminator;
+            prop.discriminatorColumn = prop2.discriminatorColumn;
+            prop.discriminatorValue = prop2.discriminatorValue;
         }
         prop.referencedColumnNames ??= Utils.flatten(meta.primaryKeys.map(primaryKey => meta.properties[primaryKey].fieldNames));
-        prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.namingStrategy.joinKeyColumnName(meta.root.className, referencedColumnName, meta.compositePK));
-        prop.inverseJoinColumns ??= this.initManyToOneFieldName(prop, meta2.root.className);
+        // For polymorphic M:N, use discriminator base name for FK column (e.g., taggable_id instead of post_id)
+        if (prop.polymorphic && prop.discriminator) {
+            prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.namingStrategy.joinKeyColumnName(prop.discriminator, referencedColumnName, prop.referencedColumnNames.length > 1));
+        }
+        else {
+            const ownerTableName = this.isExplicitTableName(meta.root) ? meta.root.tableName : undefined;
+            prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.namingStrategy.joinKeyColumnName(meta.root.className, referencedColumnName, meta.compositePK, ownerTableName));
+        }
+        const inverseTableName = this.isExplicitTableName(meta2.root) ? meta2.root.tableName : undefined;
+        prop.inverseJoinColumns ??= this.initManyToOneFieldName(prop, meta2.root.className, inverseTableName);
+    }
+    isExplicitTableName(meta) {
+        return meta.tableName !== this.namingStrategy.classToTableName(meta.className);
     }
     initManyToOneFields(prop) {
-        const meta2 = this.metadata.get(prop.type);
-        const fieldNames = Utils.flatten(meta2.primaryKeys.map(primaryKey => meta2.properties[primaryKey].fieldNames));
-        Utils.defaultValue(prop, 'referencedTableName', meta2.collection);
+        if (prop.polymorphic && prop.polymorphTargets) {
+            const fieldNames1 = prop.targetMeta.getPrimaryProps().flatMap(pk => pk.fieldNames);
+            const idColumns = fieldNames1.map(fieldName => this.namingStrategy.joinKeyColumnName(prop.discriminator, fieldName, fieldNames1.length > 1));
+            prop.fieldNames ??= [prop.discriminatorColumn, ...idColumns];
+            prop.joinColumns ??= idColumns;
+            prop.referencedColumnNames ??= fieldNames1;
+            prop.referencedTableName ??= prop.targetMeta.tableName;
+            return;
+        }
+        const meta2 = prop.targetMeta;
+        let fieldNames;
+        // If targetKey is specified, use that property's field names instead of PKs
+        if (prop.targetKey) {
+            const targetProp = meta2.properties[prop.targetKey];
+            fieldNames = targetProp.fieldNames;
+        }
+        else {
+            fieldNames = Utils.flatten(meta2.primaryKeys.map(primaryKey => meta2.properties[primaryKey].fieldNames));
+        }
+        Utils.defaultValue(prop, 'referencedTableName', meta2.tableName);
         if (!prop.joinColumns) {
             prop.joinColumns = fieldNames.map(fieldName => this.namingStrategy.joinKeyColumnName(prop.name, fieldName, fieldNames.length > 1));
         }
         if (!prop.referencedColumnNames) {
             prop.referencedColumnNames = fieldNames;
         }
+        // Relations to composite PK targets need cascade update by default,
+        // since composite PKs are more likely to have mutable components
+        if (meta2.compositePK) {
+            prop.updateRule ??= 'cascade';
+        }
+        // Nullable relations default to 'set null' on delete - when the referenced
+        // entity is deleted, set the FK to null rather than failing
+        if (prop.nullable) {
+            prop.deleteRule ??= 'set null';
+        }
     }
     initOneToManyFields(prop) {
-        const meta2 = this.metadata.get(prop.type);
+        const meta2 = prop.targetMeta;
         if (!prop.joinColumns) {
             prop.joinColumns = [this.namingStrategy.joinColumnName(prop.name)];
         }
@@ -441,12 +527,17 @@ export class MetadataDiscovery {
         const pks = Object.values(meta.properties).filter(prop => prop.primary);
         meta.primaryKeys = pks.map(prop => prop.name);
         meta.compositePK = pks.length > 1;
-        // FK used as PK, we need to cascade
-        if (pks.length === 1 && pks[0].kind !== ReferenceKind.SCALAR) {
-            pks[0].deleteRule ??= 'cascade';
+        // FK used as PK, we need to cascade - applies to both single FK-as-PK
+        // and composite PKs where all PKs are FKs (e.g., pivot-like entities)
+        const fkPks = pks.filter(pk => pk.kind !== ReferenceKind.SCALAR);
+        if (fkPks.length > 0 && fkPks.length === pks.length) {
+            for (const pk of fkPks) {
+                pk.deleteRule ??= 'cascade';
+                pk.updateRule ??= 'cascade';
+            }
         }
         meta.forceConstructor ??= this.shouldForceConstructorUsage(meta);
-        this.validator.validateEntityDefinition(this.metadata, meta.className, this.config.get('discovery'));
+        this.validator.validateEntityDefinition(this.metadata, meta.class, this.config.get('discovery'));
         for (const prop of Object.values(meta.properties)) {
             this.initNullability(prop);
             this.applyNamingStrategy(meta, prop);
@@ -466,7 +557,14 @@ export class MetadataDiscovery {
         if (this.platform.usesPivotTable()) {
             return Object.values(meta.properties)
                 .filter(prop => prop.kind === ReferenceKind.MANY_TO_MANY && prop.owner && prop.pivotTable)
-                .map(prop => this.definePivotTableEntity(meta, prop));
+                .map(prop => {
+                const pivotMeta = this.definePivotTableEntity(meta, prop);
+                prop.pivotEntity = pivotMeta.class;
+                if (prop.inversedBy) {
+                    prop.targetMeta.properties[prop.inversedBy].pivotEntity = pivotMeta.class;
+                }
+                return pivotMeta;
+            });
         }
         return [];
     }
@@ -483,8 +581,11 @@ export class MetadataDiscovery {
         ['mappedBy', 'inversedBy', 'pivotEntity'].forEach(type => {
             const value = prop[type];
             if (value instanceof Function) {
-                const meta2 = this.metadata.get(prop.type);
+                const meta2 = prop.targetMeta ?? this.metadata.get(prop.target);
                 prop[type] = value(meta2.properties)?.name;
+                if (type === 'pivotEntity' && value) {
+                    prop[type] = value(meta2.properties);
+                }
                 if (prop[type] == null) {
                     throw MetadataError.fromWrongReference(meta, prop, type);
                 }
@@ -500,9 +601,9 @@ export class MetadataDiscovery {
         }
         else if (fks.length >= 2) {
             [first, second] = fks;
-            /* v8 ignore next */
         }
         else {
+            /* v8 ignore next */
             return [];
         }
         // wrong FK order, first FK needs to point to the owning side
@@ -516,7 +617,9 @@ export class MetadataDiscovery {
         return [first, second];
     }
     definePivotTableEntity(meta, prop) {
-        const pivotMeta = this.metadata.find(prop.pivotEntity);
+        const pivotMeta = prop.pivotEntity
+            ? this.metadata.find(prop.pivotEntity)
+            : this.metadata.getByClassName(prop.pivotTable, false);
         // ensure inverse side exists so we can join it when populating via pivot tables
         if (!prop.inversedBy && prop.targetMeta) {
             const inverseName = `${meta.className}_${prop.name}__inverse`;
@@ -525,6 +628,8 @@ export class MetadataDiscovery {
                 name: inverseName,
                 kind: ReferenceKind.MANY_TO_MANY,
                 type: meta.className,
+                target: meta.class,
+                targetMeta: meta,
                 mappedBy: prop.name,
                 pivotEntity: prop.pivotEntity,
                 pivotTable: prop.pivotTable,
@@ -533,55 +638,190 @@ export class MetadataDiscovery {
             };
             this.applyNamingStrategy(prop.targetMeta, inverseProp);
             this.initCustomType(prop.targetMeta, inverseProp);
-            this.initRelation(inverseProp);
             prop.targetMeta.properties[inverseName] = inverseProp;
         }
         if (pivotMeta) {
+            prop.pivotEntity = pivotMeta.class;
             this.ensureCorrectFKOrderInPivotEntity(pivotMeta, prop);
+            if (prop.polymorphic && prop.discriminatorValue) {
+                pivotMeta.polymorphicDiscriminatorMap ??= {};
+                pivotMeta.polymorphicDiscriminatorMap[prop.discriminatorValue] = meta.class;
+                // For composite PK entities sharing a polymorphic pivot table,
+                // we need to add columns for each entity type's PKs
+                this.addPolymorphicPivotColumns(pivotMeta, meta, prop);
+                // Add virtual M:1 relation for this polymorphic owner (for join loading)
+                const ownerRelationName = `${prop.discriminator}_${meta.tableName}`;
+                if (!pivotMeta.properties[ownerRelationName]) {
+                    pivotMeta.properties[ownerRelationName] = this.definePolymorphicOwnerRelation(prop, ownerRelationName, meta);
+                }
+            }
             return pivotMeta;
         }
-        const exists = this.metadata.find(prop.pivotTable);
-        if (exists) {
-            prop.pivotEntity = exists.className;
-            return exists;
-        }
         let tableName = prop.pivotTable;
         let schemaName;
         if (prop.pivotTable.includes('.')) {
             [schemaName, tableName] = prop.pivotTable.split('.');
         }
         schemaName ??= meta.schema;
-        const targetType = prop.targetMeta.className;
-        const data = new EntityMetadata({
+        const targetMeta = prop.targetMeta;
+        const targetType = targetMeta.className;
+        const pivotMeta2 = new EntityMetadata({
             name: prop.pivotTable,
             className: prop.pivotTable,
             collection: tableName,
             schema: schemaName,
             pivotTable: true,
         });
-        prop.pivotEntity = data.className;
+        prop.pivotEntity = pivotMeta2.class;
         if (prop.fixedOrder) {
-            const primaryProp = this.defineFixedOrderProperty(prop, targetType);
-            data.properties[primaryProp.name] = primaryProp;
+            const primaryProp = this.defineFixedOrderProperty(prop, targetMeta);
+            pivotMeta2.properties[primaryProp.name] = primaryProp;
         }
         else {
-            data.compositePK = true;
+            pivotMeta2.compositePK = true;
         }
         // handle self-referenced m:n with same default field names
         if (meta.className === targetType && prop.joinColumns.every((joinColumn, idx) => joinColumn === prop.inverseJoinColumns[idx])) {
-            prop.joinColumns = prop.referencedColumnNames.map(name => this.namingStrategy.joinKeyColumnName(meta.className + '_1', name, meta.compositePK));
-            prop.inverseJoinColumns = prop.referencedColumnNames.map(name => this.namingStrategy.joinKeyColumnName(meta.className + '_2', name, meta.compositePK));
+            // use tableName only when explicitly provided by user, otherwise use className for backwards compatibility
+            const baseName = this.isExplicitTableName(meta) ? meta.tableName : meta.className;
+            prop.joinColumns = prop.referencedColumnNames.map(name => this.namingStrategy.joinKeyColumnName(baseName + '_1', name, meta.compositePK));
+            prop.inverseJoinColumns = prop.referencedColumnNames.map(name => this.namingStrategy.joinKeyColumnName(baseName + '_2', name, meta.compositePK));
             if (prop.inversedBy) {
-                const prop2 = this.metadata.get(targetType).properties[prop.inversedBy];
+                const prop2 = targetMeta.properties[prop.inversedBy];
                 prop2.inverseJoinColumns = prop.joinColumns;
                 prop2.joinColumns = prop.inverseJoinColumns;
             }
+            // propagate updated joinColumns to all child entities that inherit this property (STI)
+            for (const childMeta of this.discovered.filter(m => m.root === meta && m !== meta)) {
+                const childProp = childMeta.properties[prop.name];
+                if (childProp) {
+                    childProp.joinColumns = prop.joinColumns;
+                    childProp.inverseJoinColumns = prop.inverseJoinColumns;
+                }
+            }
+        }
+        // For polymorphic M:N, create discriminator column and polymorphic FK
+        if (prop.polymorphic && prop.discriminatorColumn) {
+            this.definePolymorphicPivotProperties(pivotMeta2, meta, prop, targetMeta);
+        }
+        else {
+            pivotMeta2.properties[meta.name + '_owner'] = this.definePivotProperty(prop, meta.name + '_owner', meta.class, targetType + '_inverse', true, meta.className === targetType);
+            pivotMeta2.properties[targetType + '_inverse'] = this.definePivotProperty(prop, targetType + '_inverse', targetMeta.class, meta.name + '_owner', false, meta.className === targetType);
         }
-        data.properties[meta.name + '_owner'] = this.definePivotProperty(prop, meta.name + '_owner', meta.className, targetType + '_inverse', true, meta.className === targetType);
-        data.properties[targetType + '_inverse'] = this.definePivotProperty(prop, targetType + '_inverse', targetType, meta.name + '_owner', false, meta.className === targetType);
-        return this.metadata.set(data.className, EntitySchema.fromMetadata(data).init().meta);
+        return this.metadata.set(pivotMeta2.class, EntitySchema.fromMetadata(pivotMeta2).init().meta);
+    }
+    /**
+     * Create a scalar property for a pivot table column.
+     */
+    createPivotScalarProperty(name, columnTypes, fieldNames = [name], options = {}) {
+        return {
+            name,
+            fieldNames,
+            columnTypes,
+            type: options.type ?? 'number',
+            kind: ReferenceKind.SCALAR,
+            primary: options.primary ?? false,
+            nullable: options.nullable ?? true,
+            ...(options.persist !== undefined && { persist: options.persist }),
+        };
+    }
+    /**
+     * Get column types for an entity's primary keys, initializing them if needed.
+     */
+    getPrimaryKeyColumnTypes(meta) {
+        const columnTypes = [];
+        for (const pk of meta.primaryKeys) {
+            const pkProp = meta.properties[pk];
+            this.initCustomType(meta, pkProp);
+            this.initColumnType(pkProp);
+            columnTypes.push(...pkProp.columnTypes);
+        }
+        return columnTypes;
+    }
+    /**
+     * Add missing FK columns for a polymorphic entity to an existing pivot table.
+     */
+    addPolymorphicPivotColumns(pivotMeta, meta, prop) {
+        const existingFieldNames = new Set(Object.values(pivotMeta.properties).flatMap(p => p.fieldNames ?? []));
+        const columnTypes = this.getPrimaryKeyColumnTypes(meta);
+        for (let i = 0; i < prop.joinColumns.length; i++) {
+            const joinColumn = prop.joinColumns[i];
+            if (!existingFieldNames.has(joinColumn)) {
+                pivotMeta.properties[joinColumn] = this.createPivotScalarProperty(joinColumn, [columnTypes[i]]);
+            }
+        }
+    }
+    /**
+     * Define properties for a polymorphic pivot table.
+     */
+    definePolymorphicPivotProperties(pivotMeta, meta, prop, targetMeta) {
+        const discriminatorColumn = prop.discriminatorColumn;
+        const isCompositePK = meta.compositePK;
+        // For composite PK polymorphic M:N, we need fixedOrder (auto-increment PK)
+        if (isCompositePK && !prop.fixedOrder) {
+            prop.fixedOrder = true;
+            const primaryProp = this.defineFixedOrderProperty(prop, targetMeta);
+            pivotMeta.properties[primaryProp.name] = primaryProp;
+            pivotMeta.compositePK = false;
+        }
+        const discriminatorProp = this.createPivotScalarProperty(discriminatorColumn, [this.platform.getVarcharTypeDeclarationSQL(prop)], [discriminatorColumn], { type: 'string', primary: !isCompositePK, nullable: false });
+        this.initFieldName(discriminatorProp);
+        pivotMeta.properties[discriminatorColumn] = discriminatorProp;
+        const columnTypes = this.getPrimaryKeyColumnTypes(meta);
+        if (isCompositePK) {
+            // Create separate properties for each PK column (nullable for other entity types)
+            for (let i = 0; i < prop.joinColumns.length; i++) {
+                pivotMeta.properties[prop.joinColumns[i]] = this.createPivotScalarProperty(prop.joinColumns[i], [columnTypes[i]]);
+            }
+            // Virtual property combining all columns (for compatibility)
+            pivotMeta.properties[prop.discriminator] = this.createPivotScalarProperty(prop.discriminator, columnTypes, [...prop.joinColumns], { type: meta.className, persist: false });
+        }
+        else {
+            pivotMeta.properties[prop.discriminator] = this.createPivotScalarProperty(prop.discriminator, columnTypes, [...prop.joinColumns], { type: meta.className, primary: true, nullable: false });
+        }
+        pivotMeta.properties[targetMeta.className + '_inverse'] = this.definePivotProperty(prop, targetMeta.className + '_inverse', targetMeta.class, prop.discriminator, false, false);
+        // Create virtual M:1 relation to the polymorphic owner for single-query join loading
+        const ownerRelationName = `${prop.discriminator}_${meta.tableName}`;
+        pivotMeta.properties[ownerRelationName] = this.definePolymorphicOwnerRelation(prop, ownerRelationName, meta);
+        pivotMeta.polymorphicDiscriminatorMap ??= {};
+        pivotMeta.polymorphicDiscriminatorMap[prop.discriminatorValue] = meta.class;
+    }
+    /**
+     * Create a virtual M:1 relation from pivot to a polymorphic owner entity.
+     * This enables single-query join loading for inverse-side polymorphic M:N.
+     */
+    definePolymorphicOwnerRelation(prop, name, targetMeta) {
+        const ret = {
+            name,
+            type: targetMeta.className,
+            target: targetMeta.class,
+            kind: ReferenceKind.MANY_TO_ONE,
+            nullable: true,
+            owner: true,
+            primary: false,
+            createForeignKeyConstraint: false,
+            persist: false,
+            index: false,
+        };
+        ret.targetMeta = targetMeta;
+        ret.fieldNames = ret.joinColumns = ret.ownColumns = [...prop.joinColumns];
+        ret.referencedColumnNames = [];
+        ret.inverseJoinColumns = [];
+        for (const primaryKey of targetMeta.primaryKeys) {
+            const pkProp = targetMeta.properties[primaryKey];
+            ret.referencedColumnNames.push(...pkProp.fieldNames);
+            ret.inverseJoinColumns.push(...pkProp.fieldNames);
+            ret.length = pkProp.length;
+            ret.precision = pkProp.precision;
+            ret.scale = pkProp.scale;
+        }
+        const schema = targetMeta.schema ?? this.config.get('schema') ?? this.platform.getDefaultSchemaName();
+        ret.referencedTableName = schema && schema !== '*' ? schema + '.' + targetMeta.tableName : targetMeta.tableName;
+        this.initColumnType(ret);
+        this.initRelation(ret);
+        return ret;
     }
-    defineFixedOrderProperty(prop, targetType) {
+    defineFixedOrderProperty(prop, targetMeta) {
         const pk = prop.fixedOrderColumn || this.namingStrategy.referenceColumnName();
         const primaryProp = {
             name: pk,
@@ -595,7 +835,7 @@ export class MetadataDiscovery {
         this.initColumnType(primaryProp);
         prop.fixedOrderColumn = pk;
         if (prop.inversedBy) {
-            const prop2 = this.metadata.get(targetType).properties[prop.inversedBy];
+            const prop2 = targetMeta.properties[prop.inversedBy];
             prop2.fixedOrder = true;
             prop2.fixedOrderColumn = pk;
         }
@@ -604,7 +844,8 @@ export class MetadataDiscovery {
     definePivotProperty(prop, name, type, inverse, owner, selfReferencing) {
         const ret = {
             name,
-            type,
+            type: Utils.className(type),
+            target: type,
             kind: ReferenceKind.MANY_TO_ONE,
             cascade: [Cascade.ALL],
             fixedOrder: prop.fixedOrder,
@@ -616,10 +857,9 @@ export class MetadataDiscovery {
             deleteRule: prop.deleteRule,
             createForeignKeyConstraint: prop.createForeignKeyConstraint,
         };
-        if (selfReferencing && !this.platform.supportsMultipleCascadePaths()) {
-            ret.updateRule ??= 'no action';
-            ret.deleteRule ??= 'no action';
-        }
+        const defaultRule = selfReferencing && !this.platform.supportsMultipleCascadePaths() ? 'no action' : 'cascade';
+        ret.updateRule ??= defaultRule;
+        ret.deleteRule ??= defaultRule;
         const meta = this.metadata.get(type);
         ret.targetMeta = meta;
         ret.joinColumns = [];
@@ -662,7 +902,7 @@ export class MetadataDiscovery {
         Object.values(meta.properties)
             .filter(prop => prop.kind !== ReferenceKind.SCALAR && !prop.owner && prop.mappedBy)
             .forEach(prop => {
-            const meta2 = this.metadata.get(prop.type);
+            const meta2 = prop.targetMeta;
             const prop2 = meta2.properties[prop.mappedBy];
             if (prop2 && !prop2.inversedBy) {
                 prop2.inversedBy = prop.name;
@@ -670,7 +910,7 @@ export class MetadataDiscovery {
         });
     }
     defineBaseEntityProperties(meta) {
-        const base = meta.extends && this.metadata.get(Utils.className(meta.extends));
+        const base = meta.extends && this.metadata.get(meta.extends);
         if (!base || base === meta) { // make sure we do not fall into infinite loop
             return 0;
         }
@@ -760,6 +1000,54 @@ export class MetadataDiscovery {
             polymorphs.forEach(meta => meta.root = embeddable);
         }
     }
+    initPolymorphicRelation(meta, prop, discovered) {
+        if (!prop.discriminator && !prop.discriminatorColumn && !prop.discriminatorMap && !Array.isArray(prop.target)) {
+            return;
+        }
+        prop.polymorphic = true;
+        prop.discriminator ??= prop.name;
+        prop.discriminatorColumn ??= this.namingStrategy.discriminatorColumnName(prop.discriminator);
+        prop.createForeignKeyConstraint = false;
+        const isToOne = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind);
+        if (isToOne) {
+            const types = prop.type.split(/ ?\| ?/);
+            prop.polymorphTargets = discovered.filter(m => types.includes(m.className) && !m.embeddable);
+            prop.targetMeta = prop.polymorphTargets[0];
+            prop.referencedPKs = prop.targetMeta?.primaryKeys;
+        }
+        if (prop.discriminatorMap) {
+            const normalizedMap = {};
+            for (const [key, value] of Object.entries(prop.discriminatorMap)) {
+                const targetMeta = this.metadata.getByClassName(value, false);
+                if (!targetMeta) {
+                    throw MetadataError.fromUnknownEntity(value, `${meta.className}.${prop.name} discriminatorMap`);
+                }
+                normalizedMap[key] = targetMeta.class;
+                if (targetMeta.class === meta.class) {
+                    prop.discriminatorValue = key;
+                }
+            }
+            prop.discriminatorMap = normalizedMap;
+        }
+        else if (isToOne) {
+            prop.discriminatorMap = {};
+            const tableNameToTarget = new Map();
+            for (const target of prop.polymorphTargets) {
+                const existing = tableNameToTarget.get(target.tableName);
+                if (existing) {
+                    throw MetadataError.incompatiblePolymorphicTargets(meta, prop, existing, target, `both use table '${target.tableName}'. Use separate properties instead of a single polymorphic relation.`);
+                }
+                tableNameToTarget.set(target.tableName, target);
+                prop.discriminatorMap[target.tableName] = target.class;
+            }
+        }
+        else {
+            prop.discriminatorValue ??= meta.tableName;
+            if (!prop.discriminatorMap) {
+                prop.discriminatorMap = { [prop.discriminatorValue]: meta.class };
+            }
+        }
+    }
     initEmbeddables(meta, embeddedProp, visited = new Set()) {
         if (embeddedProp.kind !== ReferenceKind.EMBEDDED || visited.has(embeddedProp)) {
             return;
@@ -795,7 +1083,7 @@ export class MetadataDiscovery {
         const glue = object ? '~' : '_';
         for (const prop of Object.values(embeddable.properties)) {
             const name = (embeddedProp.embeddedPath?.join(glue) ?? embeddedProp.fieldNames[0] + glue) + prop.name;
-            meta.properties[name] = Utils.copy(prop, false);
+            meta.properties[name] = Utils.copy(prop);
             meta.properties[name].name = name;
             meta.properties[name].embedded = [embeddedProp.name, prop.name];
             meta.propertyOrder.set(name, (order += 0.01));
@@ -832,10 +1120,12 @@ export class MetadataDiscovery {
                     path = [embeddedProp.fieldNames[0]];
                 }
                 this.initFieldName(prop, true);
+                this.initRelation(prop);
                 path.push(prop.fieldNames[0]);
                 meta.properties[name].fieldNames = prop.fieldNames;
                 meta.properties[name].embeddedPath = path;
-                const fieldName = raw(this.platform.getSearchJsonPropertySQL(path.join('->'), prop.runtimeType ?? prop.type, true));
+                const targetProp = prop.targetMeta?.getPrimaryProp() ?? prop;
+                const fieldName = raw(this.platform.getSearchJsonPropertySQL(path.join('->'), targetProp.runtimeType ?? targetProp.type, true));
                 meta.properties[name].fieldNameRaw = fieldName.sql; // for querying in SQL drivers
                 meta.properties[name].persist = false; // only virtual as we store the whole object
                 meta.properties[name].userDefined = false; // mark this as a generated/internal property, so we can distinguish from user-defined non-persist properties
@@ -863,7 +1153,7 @@ export class MetadataDiscovery {
     }
     initSingleTableInheritance(meta, metadata) {
         if (meta.root !== meta && !meta.__processed) {
-            meta.root = metadata.find(m => m.className === meta.root.className);
+            meta.root = metadata.find(m => m.class === meta.root.class);
             meta.root.__processed = true;
         }
         else {
@@ -872,17 +1162,24 @@ export class MetadataDiscovery {
         if (!meta.root.discriminatorColumn) {
             return;
         }
-        if (!meta.root.discriminatorMap) {
+        meta.root.inheritanceType = 'sti';
+        if (meta.root.discriminatorMap) {
+            const map = meta.root.discriminatorMap;
+            Object.keys(map)
+                .filter(key => typeof map[key] === 'string')
+                .forEach(key => map[key] = this.metadata.getByClassName(map[key]).class);
+        }
+        else {
             meta.root.discriminatorMap = {};
             const children = metadata
-                .filter(m => m.root.className === meta.root.className && !m.abstract)
+                .filter(m => m.root.class === meta.root.class && !m.abstract)
                 .sort((a, b) => a.className.localeCompare(b.className));
             for (const m of children) {
                 const name = m.discriminatorValue ?? this.namingStrategy.classToTableName(m.className);
-                meta.root.discriminatorMap[name] = m.className;
+                meta.root.discriminatorMap[name] = m.class;
             }
         }
-        meta.discriminatorValue = Object.entries(meta.root.discriminatorMap).find(([, className]) => className === meta.className)?.[0];
+        meta.discriminatorValue = QueryHelper.findDiscriminatorValue(meta.root.discriminatorMap, meta.class);
         if (!meta.root.properties[meta.root.discriminatorColumn]) {
             this.createDiscriminatorProperty(meta.root);
         }
@@ -891,32 +1188,219 @@ export class MetadataDiscovery {
         if (meta.root === meta) {
             return;
         }
-        let i = 1;
         Object.values(meta.properties).forEach(prop => {
             const newProp = { ...prop };
-            if (meta.root.properties[prop.name] && meta.root.properties[prop.name].type !== prop.type) {
+            const rootProp = meta.root.properties[prop.name];
+            if (rootProp && (rootProp.type !== prop.type || (rootProp.fieldNames && prop.fieldNames && !compareArrays(rootProp.fieldNames, prop.fieldNames)))) {
                 const name = newProp.name;
                 this.initFieldName(newProp, newProp.object);
-                newProp.name = name + '_' + (i++);
+                newProp.renamedFrom = name;
+                newProp.name = `${name}_${meta._id}`;
                 meta.root.addProperty(newProp);
+                this.initFieldName(prop, prop.object);
+                // Track all field variants and map discriminator values to field names
+                if (!rootProp.stiFieldNames) {
+                    this.initFieldName(rootProp, rootProp.object);
+                    rootProp.stiFieldNames = [...rootProp.fieldNames];
+                    rootProp.stiFieldNameMap = {};
+                    // Find which discriminator owns the original fieldNames
+                    for (const [discValue, childClass] of Object.entries(meta.root.discriminatorMap)) {
+                        const childMeta = this.metadata.find(childClass);
+                        if (childMeta?.properties[prop.name]?.fieldNames && compareArrays(childMeta.properties[prop.name].fieldNames, rootProp.fieldNames)) {
+                            rootProp.stiFieldNameMap[discValue] = rootProp.fieldNames[0];
+                            break;
+                        }
+                    }
+                }
+                rootProp.stiFieldNameMap[meta.discriminatorValue] = prop.fieldNames[0];
+                rootProp.stiFieldNames.push(...prop.fieldNames);
                 newProp.nullable = true;
                 newProp.name = name;
                 newProp.hydrate = false;
                 newProp.inherited = true;
                 return;
             }
-            if (prop.enum && prop.items && meta.root.properties[prop.name]?.items) {
-                newProp.items = Utils.unique([...meta.root.properties[prop.name].items, ...prop.items]);
+            if (prop.enum && prop.items && rootProp?.items) {
+                newProp.items = Utils.unique([...rootProp.items, ...prop.items]);
             }
             newProp.nullable = true;
-            newProp.inherited = !meta.root.properties[prop.name];
+            newProp.inherited = !rootProp;
             meta.root.addProperty(newProp);
         });
-        meta.collection = meta.root.collection;
+        meta.tableName = meta.root.tableName;
         meta.root.indexes = Utils.unique([...meta.root.indexes, ...meta.indexes]);
         meta.root.uniques = Utils.unique([...meta.root.uniques, ...meta.uniques]);
         meta.root.checks = Utils.unique([...meta.root.checks, ...meta.checks]);
     }
+    /**
+     * First pass of TPT initialization: sets up hierarchy relationships
+     * (inheritanceType, tptParent, tptChildren) before properties have fieldNames.
+     */
+    initTPTRelationships(meta, metadata) {
+        if (meta.root !== meta) {
+            meta.root = metadata.find(m => m.class === meta.root.class);
+        }
+        const inheritance = meta.inheritance;
+        if (inheritance === 'tpt' && meta.root === meta) {
+            meta.inheritanceType = 'tpt';
+            meta.tptChildren = [];
+        }
+        if (meta.root.inheritanceType !== 'tpt') {
+            return;
+        }
+        const parent = this.getTPTParent(meta, metadata);
+        if (parent) {
+            meta.tptParent = parent;
+            meta.inheritanceType = 'tpt';
+            parent.tptChildren ??= [];
+            if (!parent.tptChildren.includes(meta)) {
+                parent.tptChildren.push(meta);
+            }
+        }
+    }
+    /**
+     * Second pass of TPT initialization: re-resolves metadata references after fieldNames
+     * are set, syncs to registry metadata, and sets up discriminators.
+     */
+    finalizeTPTInheritance(meta, metadata) {
+        if (meta.inheritanceType !== 'tpt') {
+            return;
+        }
+        if (meta.tptParent) {
+            meta.tptParent = metadata.find(m => m.class === meta.tptParent.class) ?? meta.tptParent;
+        }
+        if (meta.tptChildren) {
+            meta.tptChildren = meta.tptChildren.map(child => metadata.find(m => m.class === child.class) ?? child);
+        }
+        const registryMeta = this.metadata.get(meta.class);
+        if (registryMeta && registryMeta !== meta) {
+            registryMeta.inheritanceType = meta.inheritanceType;
+            registryMeta.tptParent = meta.tptParent ? this.metadata.get(meta.tptParent.class) : undefined;
+            registryMeta.tptChildren = meta.tptChildren?.map(child => this.metadata.get(child.class));
+        }
+        this.initTPTDiscriminator(meta, metadata);
+    }
+    /**
+     * Initialize TPT discriminator map and virtual discriminator property.
+     * Unlike STI where the discriminator is a persisted column, TPT discriminator is computed
+     * at query time using CASE WHEN expressions based on which child table has data.
+     */
+    initTPTDiscriminator(meta, metadata) {
+        const allDescendants = this.collectAllTPTDescendants(meta, metadata);
+        allDescendants.sort((a, b) => this.getTPTDepth(b) - this.getTPTDepth(a));
+        meta.allTPTDescendants = allDescendants;
+        if (meta.root !== meta) {
+            return;
+        }
+        meta.root.discriminatorMap = {};
+        for (const m of allDescendants) {
+            const name = this.namingStrategy.classToTableName(m.className);
+            meta.root.discriminatorMap[name] = m.class;
+            m.discriminatorValue = name;
+        }
+        if (!meta.abstract) {
+            const name = this.namingStrategy.classToTableName(meta.className);
+            meta.root.discriminatorMap[name] = meta.class;
+            meta.discriminatorValue = name;
+        }
+        // Virtual discriminator property - computed at query time via CASE WHEN, not persisted
+        const discriminatorColumn = '__tpt_type';
+        if (!meta.root.properties[discriminatorColumn]) {
+            meta.root.addProperty({
+                name: discriminatorColumn,
+                type: 'string',
+                kind: ReferenceKind.SCALAR,
+                persist: false,
+                userDefined: false,
+                hidden: true,
+            });
+        }
+        meta.root.tptDiscriminatorColumn = discriminatorColumn;
+    }
+    /**
+     * Recursively collect all TPT descendants (children, grandchildren, etc.)
+     */
+    collectAllTPTDescendants(meta, metadata) {
+        const descendants = [];
+        const collect = (parent) => {
+            for (const child of parent.tptChildren ?? []) {
+                const resolved = metadata.find(m => m.class === child.class) ?? child;
+                if (!resolved.abstract) {
+                    descendants.push(resolved);
+                }
+                collect(resolved);
+            }
+        };
+        collect(meta);
+        return descendants;
+    }
+    /**
+     * Computes ownProps for TPT entities - only properties defined in THIS entity,
+     * not inherited from parent. Also creates synthetic join properties for parent/child relationships.
+     *
+     * Called multiple times during discovery as metadata is progressively built.
+     * Each pass overwrites earlier results to reflect the final state of properties.
+     */
+    computeTPTOwnProps(meta) {
+        if (meta.inheritanceType !== 'tpt') {
+            return;
+        }
+        const belongsToTable = (prop) => prop.persist !== false || prop.primary;
+        // Use meta.properties (object) since meta.props (array) may not be populated yet
+        const allProps = Object.values(meta.properties);
+        if (!meta.tptParent) {
+            meta.ownProps = allProps.filter(belongsToTable);
+            return;
+        }
+        const parentPropNames = new Set(Object.values(meta.tptParent.properties).map(p => p.name));
+        meta.ownProps = allProps.filter(prop => !parentPropNames.has(prop.name) && belongsToTable(prop));
+        // Create synthetic join properties for the parent-child relationship
+        const childFieldNames = meta.getPrimaryProps().flatMap(p => p.fieldNames);
+        const parentFieldNames = meta.tptParent.getPrimaryProps().flatMap(p => p.fieldNames);
+        meta.tptParentProp = {
+            name: '[tpt:parent]',
+            kind: ReferenceKind.MANY_TO_ONE,
+            targetMeta: meta.tptParent,
+            fieldNames: childFieldNames,
+            referencedColumnNames: parentFieldNames,
+            persist: false,
+        };
+        meta.tptInverseProp = {
+            name: '[tpt:child]',
+            kind: ReferenceKind.ONE_TO_ONE,
+            owner: true,
+            targetMeta: meta,
+            fieldNames: parentFieldNames,
+            joinColumns: parentFieldNames,
+            referencedColumnNames: childFieldNames,
+            persist: false,
+        };
+    }
+    /** Returns the depth of a TPT entity in its hierarchy (0 for root). */
+    getTPTDepth(meta) {
+        let depth = 0;
+        let current = meta;
+        while (current.tptParent) {
+            depth++;
+            current = current.tptParent;
+        }
+        return depth;
+    }
+    /**
+     * Find the direct TPT parent entity for the given entity.
+     */
+    getTPTParent(meta, metadata) {
+        if (meta.root === meta) {
+            return undefined;
+        }
+        return metadata.find(m => {
+            const ext = meta.extends;
+            if (ext instanceof EntitySchema) {
+                return m.class === ext.meta.class || m.className === ext.meta.className;
+            }
+            return m.class === ext || m.className === Utils.className(ext);
+        });
+    }
     createDiscriminatorProperty(meta) {
         meta.addProperty({
             name: meta.discriminatorColumn,
@@ -933,13 +1417,23 @@ export class MetadataDiscovery {
             pks[0].autoincrement ??= true;
         }
     }
+    createSchemaTable(meta) {
+        const qualifiedName = meta.schema ? `${meta.schema}.${meta.tableName}` : meta.tableName;
+        return {
+            name: meta.tableName,
+            schema: meta.schema,
+            qualifiedName,
+            toString: () => qualifiedName,
+        };
+    }
     initCheckConstraints(meta) {
-        const map = meta.createColumnMappingObject();
+        const columns = meta.createSchemaColumnMappingObject();
+        const table = this.createSchemaTable(meta);
         for (const check of meta.checks) {
-            const columns = check.property ? meta.properties[check.property].fieldNames : [];
-            check.name ??= this.namingStrategy.indexName(meta.tableName, columns, 'check');
+            const fieldNames = check.property ? meta.properties[check.property].fieldNames : [];
+            check.name ??= this.namingStrategy.indexName(meta.tableName, fieldNames, 'check');
             if (check.expression instanceof Function) {
-                check.expression = check.expression(map);
+                check.expression = check.expression(columns, table);
             }
         }
         if (this.platform.usesEnumCheckConstraints() && !meta.embeddable) {
@@ -969,9 +1463,9 @@ export class MetadataDiscovery {
             }
             return;
         }
-        const map = meta.createColumnMappingObject();
         if (prop.generated instanceof Function) {
-            prop.generated = prop.generated(map);
+            const columns = meta.createSchemaColumnMappingObject();
+            prop.generated = prop.generated(columns, this.createSchemaTable(meta));
         }
     }
     getDefaultVersionValue(meta, prop) {
@@ -991,9 +1485,6 @@ export class MetadataDiscovery {
         return '1';
     }
     inferDefaultValue(meta, prop) {
-        if (!meta.class) {
-            return;
-        }
         try {
             // try to create two entity instances to detect the value is stable
             const now = Date.now();
@@ -1021,7 +1512,7 @@ export class MetadataDiscovery {
             return;
         }
         let val = prop.default;
-        const raw = RawQueryFragment.getKnownFragment(val);
+        const raw = Raw.getKnownFragment(val);
         if (raw) {
             prop.defaultRaw = this.platform.formatQuery(raw.sql, raw.params);
             return;
@@ -1149,9 +1640,9 @@ export class MetadataDiscovery {
         if (Type.isMappedType(prop.customType) && prop.kind === ReferenceKind.SCALAR && !isArray) {
             prop.type = prop.customType.name;
         }
-        if (!prop.customType && [ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind) && this.metadata.get(prop.type).compositePK) {
+        if (!prop.customType && [ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind) && !prop.polymorphic && prop.targetMeta.compositePK) {
             prop.customTypes = [];
-            for (const pk of this.metadata.get(prop.type).getPrimaryProps()) {
+            for (const pk of prop.targetMeta.getPrimaryProps()) {
                 if (pk.customType) {
                     prop.customTypes.push(pk.customType);
                     prop.hasConvertToJSValueSQL ||= !!pk.customType.convertToJSValueSQL && pk.customType.convertToJSValueSQL('', this.platform) !== '';
@@ -1178,22 +1669,36 @@ export class MetadataDiscovery {
         }
     }
     initRelation(prop) {
-        if (prop.kind === ReferenceKind.SCALAR) {
+        if (prop.kind === ReferenceKind.SCALAR || prop.polymorphTargets) {
             return;
         }
-        const meta2 = this.discovered.find(m => m.className === prop.type);
-        prop.referencedPKs = meta2.primaryKeys;
+        // when the target is a polymorphic embedded entity, `prop.target` is an array of classes, we need to get the metadata by the type name instead
+        const meta2 = this.metadata.find(prop.target) ?? this.metadata.getByClassName(prop.type);
+        // If targetKey is specified, use that property instead of PKs for referencedPKs
+        prop.referencedPKs = prop.targetKey ? [prop.targetKey] : meta2.primaryKeys;
         prop.targetMeta = meta2;
+        if (meta2.view) {
+            prop.createForeignKeyConstraint = false;
+        }
+        // Auto-generate formula for persist: false relations, but only for single-column FKs
+        // Composite FK relations need standard JOIN conditions, not formula-based
         if (!prop.formula && prop.persist === false && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && !prop.embedded) {
-            prop.formula = a => `${a}.${this.platform.quoteIdentifier(prop.fieldNames[0])}`;
+            this.initFieldName(prop);
+            if (prop.fieldNames?.length === 1) {
+                prop.formula = table => `${table}.${this.platform.quoteIdentifier(prop.fieldNames[0])}`;
+            }
         }
     }
     initColumnType(prop) {
         this.initUnsigned(prop);
-        this.metadata.find(prop.type)?.getPrimaryProps().map(pk => {
-            prop.length ??= pk.length;
-            prop.precision ??= pk.precision;
-            prop.scale ??= pk.scale;
+        // Get the target properties for FK relations - use targetKey property if specified, otherwise PKs
+        const targetProps = prop.targetMeta
+            ? (prop.targetKey ? [prop.targetMeta.properties[prop.targetKey]] : prop.targetMeta.getPrimaryProps())
+            : [];
+        targetProps.map(targetProp => {
+            prop.length ??= targetProp.length;
+            prop.precision ??= targetProp.precision;
+            prop.scale ??= targetProp.scale;
         });
         if (prop.kind === ReferenceKind.SCALAR && (prop.type == null || prop.type === 'object') && prop.columnTypes?.[0]) {
             delete prop.type;
@@ -1207,7 +1712,6 @@ export class MetadataDiscovery {
             const mappedType = this.getMappedType(prop);
             const SCALAR_TYPES = ['string', 'number', 'boolean', 'bigint', 'Date', 'Buffer', 'RegExp', 'any', 'unknown'];
             if (mappedType instanceof t.unknown
-                && !prop.columnTypes
                 // it could be a runtime type from reflect-metadata
                 && !SCALAR_TYPES.includes(prop.type)
                 // or it might be inferred via ts-morph to some generic type alias
@@ -1220,23 +1724,31 @@ export class MetadataDiscovery {
             }
             return;
         }
-        if (prop.kind === ReferenceKind.EMBEDDED && prop.object && !prop.columnTypes) {
+        /* v8 ignore next */
+        if (prop.kind === ReferenceKind.EMBEDDED && prop.object) {
             prop.columnTypes = [this.platform.getJsonDeclarationSQL()];
             return;
         }
-        const targetMeta = this.metadata.get(prop.type);
+        const targetMeta = prop.targetMeta;
         prop.columnTypes = [];
-        for (const pk of targetMeta.getPrimaryProps()) {
-            this.initCustomType(targetMeta, pk);
-            this.initColumnType(pk);
-            const mappedType = this.getMappedType(pk);
-            let columnTypes = pk.columnTypes;
-            if (pk.autoincrement) {
-                columnTypes = [mappedType.getColumnType({ ...pk, autoincrement: false }, this.platform)];
+        // Use targetKey property if specified, otherwise use primary key properties
+        const referencedProps = prop.targetKey
+            ? [targetMeta.properties[prop.targetKey]]
+            : targetMeta.getPrimaryProps();
+        if (prop.polymorphic && prop.polymorphTargets) {
+            prop.columnTypes.push(this.platform.getVarcharTypeDeclarationSQL(prop));
+        }
+        for (const referencedProp of referencedProps) {
+            this.initCustomType(targetMeta, referencedProp);
+            this.initColumnType(referencedProp);
+            const mappedType = this.getMappedType(referencedProp);
+            let columnTypes = referencedProp.columnTypes;
+            if (referencedProp.autoincrement) {
+                columnTypes = [mappedType.getColumnType({ ...referencedProp, autoincrement: false }, this.platform)];
             }
             prop.columnTypes.push(...columnTypes);
-            if (!targetMeta.compositePK) {
-                prop.customType = pk.customType;
+            if (!targetMeta.compositePK || prop.targetKey) {
+                prop.customType = referencedProp.customType;
             }
         }
     }
@@ -1274,8 +1786,7 @@ export class MetadataDiscovery {
             return;
         }
         if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
-            const meta2 = this.metadata.get(prop.type);
-            prop.unsigned = meta2.getPrimaryProps().some(pk => {
+            prop.unsigned = prop.targetMeta.getPrimaryProps().some(pk => {
                 this.initUnsigned(pk);
                 return pk.unsigned;
             });