@mikro-orm/core 7.0.0-dev.23 → 7.0.0-dev.231

package/metadata/MetadataDiscovery.js

@@ -1,22 +1,22 @@
-import { basename, extname } from 'node:path';
-import { glob } from 'tinyglobby';
 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 { ArrayType, BigIntType, BlobType, DateType, DecimalType, DoubleType, EnumArrayType, IntervalType, JsonType, t, Type, Uint8ArrayType, UnknownType, } from '../types/index.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;
     config;
     namingStrategy;
     metadataProvider;
-    cache;
     logger;
     schemaHelper;
     validator = new MetadataValidator();
@@ -27,13 +27,14 @@ export class MetadataDiscovery {
         this.config = config;
         this.namingStrategy = this.config.getNamingStrategy();
         this.metadataProvider = this.config.getMetadataProvider();
-        this.cache = this.config.getMetadataCacheAdapter();
         this.logger = this.config.getLogger();
         this.schemaHelper = this.platform.getSchemaHelper();
     }
     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,10 +48,13 @@ export class MetadataDiscovery {
         await this.config.get('discovery').afterDiscovered?.(storage, this.platform);
         return storage;
     }
-    discoverSync(preferTs = true) {
+    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`);
-        this.findEntities(preferTs, true);
+        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) {
             /* v8 ignore next */
             void this.config.get('discovery').onMetadata?.(meta, this.platform);
@@ -70,82 +74,120 @@ 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) {
+        for (const prop of Object.values(meta.properties)) {
+            if (!prop.accessor || meta.properties[prop.accessor]) {
+                continue;
+            }
+            const desc = Object.getOwnPropertyDescriptor(meta.prototype, prop.name);
+            if (desc?.get || desc?.set) {
+                this.initFieldName(prop);
+                const accessor = prop.name;
+                prop.name = typeof prop.accessor === 'string' ? prop.accessor : prop.name;
+                if (prop.accessor === true) {
+                    prop.getter = prop.setter = true;
+                }
+                else {
+                    prop.getter = prop.setter = false;
+                }
+                prop.accessor = accessor;
+                prop.serializedName ??= accessor;
+                Utils.renameKey(meta.properties, accessor, prop.name);
+            }
+            else {
+                const name = prop.name;
+                prop.name = prop.accessor;
+                this.initFieldName(prop);
+                prop.serializedName ??= prop.accessor;
+                prop.name = name;
+            }
+        }
+    }
     processDiscoveredEntities(discovered) {
         for (const meta of discovered) {
             let i = 1;
             Object.values(meta.properties).forEach(prop => meta.propertyOrder.set(prop.name, i++));
             Object.values(meta.properties).forEach(prop => this.initPolyEmbeddables(prop, discovered));
+            this.initAccessors(meta);
         }
         // ignore base entities (not annotated with @Entity)
         const filtered = discovered.filter(meta => meta.root.name);
         // 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);
-                // change tracking on scalars is used only for "auto" flushMode
-                if (this.config.get('flushMode') !== 'auto' && [ReferenceKind.SCALAR, ReferenceKind.EMBEDDED].includes(prop.kind)) {
-                    prop.trackChanges = false;
-                }
-            }
-        }
-        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));
-        const combinedCachePath = this.cache.combine?.();
-        // override the path in the options, so we can log it from the CLI in `cache:generate` command
-        if (combinedCachePath) {
-            this.config.get('metadataCache').combined = combinedCachePath;
-        }
+        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;
         });
     }
-    findEntities(preferTs, sync = false) {
-        this.discovered.length = 0;
-        const options = this.config.get('discovery');
-        const key = (preferTs && this.config.get('preferTs', Utils.detectTypeScriptSupport()) && this.config.get('entitiesTs').length > 0) ? 'entitiesTs' : 'entities';
-        const paths = this.config.get(key).filter(item => Utils.isString(item));
-        const refs = this.config.get(key).filter(item => !Utils.isString(item));
+    async findEntities(preferTs) {
+        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') {
+                paths.push(entity);
+            }
+            else {
+                processed.push(entity);
+            }
+        }
         if (paths.length > 0) {
-            if (sync || options.requireEntitiesArray) {
-                throw new Error(`[requireEntitiesArray] Explicit list of entities is required, please use the 'entities' option.`);
-            }
-            return this.discoverDirectories(paths).then(() => {
-                this.discoverReferences(refs);
-                this.discoverMissingTargets();
-                this.validator.validateDiscovered(this.discovered, options);
-                return this.discovered;
-            });
+            const { discoverEntities } = await import('@mikro-orm/core/file-discovery');
+            processed.push(...await discoverEntities(paths, { baseDir }));
         }
-        this.discoverReferences(refs);
-        this.discoverMissingTargets();
-        this.validator.validateDiscovered(this.discovered, options);
-        return this.discovered;
+        return this.discoverReferences(processed);
     }
     discoverMissingTargets() {
         const unwrap = (type) => type
@@ -154,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) {
@@ -173,123 +220,107 @@ export class MetadataDiscovery {
     }
     tryDiscoverTargets(targets) {
         for (const target of targets) {
-            if (typeof target === 'function' && target.name && !this.metadata.has(target.name)) {
-                this.discoverReferences([target]);
-                this.discoverMissingTargets();
-            }
-        }
-    }
-    async discoverDirectories(paths) {
-        paths = paths.map(path => Utils.normalizePath(path));
-        const files = await glob(paths, { cwd: Utils.normalizePath(this.config.get('baseDir')) });
-        this.logger.log('discovery', `- processing ${colors.cyan('' + files.length)} files`);
-        const found = [];
-        for (const filepath of files) {
-            const filename = basename(filepath);
-            if (!filename.match(/\.[cm]?[jt]s$/) ||
-                filename.endsWith('.js.map') ||
-                filename.match(/\.d\.[cm]?ts/) ||
-                filename.startsWith('.') ||
-                filename.match(/index\.[cm]?[jt]s$/)) {
-                this.logger.log('discovery', `- ignoring file ${filename}`);
-                continue;
-            }
-            const name = this.namingStrategy.getClassName(filename);
-            const path = Utils.normalizePath(this.config.get('baseDir'), filepath);
-            const targets = await this.getEntityClassOrSchema(path, name);
-            for (const target of targets) {
-                if (!(target instanceof Function) && !(target instanceof EntitySchema)) {
-                    this.logger.log('discovery', `- ignoring file ${filename}`);
-                    continue;
+            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();
                 }
-                const entity = this.prepare(target);
-                const schema = this.getSchema(entity, path);
-                const meta = schema.init().meta;
-                this.metadata.set(meta.className, meta);
-                found.push([schema, path]);
             }
         }
-        for (const [schema, path] of found) {
-            this.discoverEntity(schema, path);
-        }
     }
-    discoverReferences(refs) {
+    discoverReferences(refs, validate = true) {
         const found = [];
         for (const entity of refs) {
-            const schema = this.getSchema(this.prepare(entity));
+            if (typeof entity === 'string') {
+                throw new Error('Folder based discovery requires the async `MikroORM.init()` method.');
+            }
+            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)) {
-                this.discoverReferences([parent]);
+            if (parent instanceof EntitySchema && !this.metadata.has(parent.init().meta.class)) {
+                this.discoverReferences([parent], false);
             }
-            /* v8 ignore next 3 */
+            if (typeof parent === 'function' && parent.name && !this.metadata.has(parent)) {
+                this.discoverReferences([parent], false);
+            }
+            /* v8 ignore next */
             if (!meta.class) {
                 continue;
             }
             parent = Object.getPrototypeOf(meta.class);
-            if (parent.name !== '' && !this.metadata.has(parent.name)) {
-                this.discoverReferences([parent]);
+            // 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);
             }
         }
         for (const schema of found) {
             this.discoverEntity(schema);
         }
+        this.discoverMissingTargets();
+        if (validate) {
+            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);
         }
     }
-    prepare(entity) {
-        /* v8 ignore next 3 */
-        if ('schema' in entity && entity.schema instanceof EntitySchema) {
-            return entity.schema;
-        }
+    getSchema(entity) {
         if (EntitySchema.REGISTRY.has(entity)) {
-            return EntitySchema.REGISTRY.get(entity);
+            entity = EntitySchema.REGISTRY.get(entity);
         }
-        return entity;
-    }
-    getSchema(entity, filepath) {
         if (entity instanceof EntitySchema) {
-            if (filepath) {
-                // initialize global metadata for given entity
-                MetadataStorage.getMetadata(entity.meta.className, filepath);
-            }
             const meta = Utils.copy(entity.meta, false);
             return EntitySchema.fromMetadata(meta);
         }
         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;
     }
-    discoverEntity(schema, path) {
-        this.logger.log('discovery', `- processing entity ${colors.cyan(schema.meta.className)}${colors.grey(path ? ` (${path})` : '')}`);
+    getRootEntity(meta) {
+        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);
+        // 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;
+    }
+    discoverEntity(schema) {
         const meta = schema.meta;
-        const root = Utils.getRootEntity(this.metadata, meta);
-        schema.meta.path = Utils.relativePath(path || meta.path, this.config.get('baseDir'));
-        const cache = this.metadataProvider.useCache() && meta.path && this.cache.get(meta.className + extname(meta.path));
+        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 = meta.path;
+        const cache = this.metadataProvider.getCachedMetadata(meta, root);
         if (cache) {
             this.logger.log('discovery', `- using cached metadata for entity ${colors.cyan(meta.className)}`);
-            this.metadataProvider.loadFromCache(meta, cache);
-            meta.root = root;
             this.discovered.push(meta);
             return;
         }
@@ -298,50 +329,18 @@ export class MetadataDiscovery {
             this.inferDefaultValue(meta, prop);
         }
         // 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, meta.className);
-        if (!meta.collection && meta.name) {
+        this.metadataProvider.loadEntityMetadata(meta);
+        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);
         }
-        delete meta.root; // to allow caching (as root can contain cycles)
-        this.saveToCache(meta);
+        this.metadataProvider.saveToCache(meta);
         meta.root = root;
         this.discovered.push(meta);
     }
-    saveToCache(meta) {
-        if (!this.metadataProvider.useCache()) {
-            return;
-        }
-        const copy = Utils.copy(meta, false);
-        for (const prop of copy.props) {
-            if (Type.isMappedType(prop.type)) {
-                Reflect.deleteProperty(prop, 'type');
-                Reflect.deleteProperty(prop, 'customType');
-            }
-            if (prop.default) {
-                const raw = RawQueryFragment.getKnownFragment(prop.default);
-                if (raw) {
-                    prop.defaultRaw ??= this.platform.formatQuery(raw.sql, raw.params);
-                    Reflect.deleteProperty(prop, 'default');
-                }
-            }
-            Reflect.deleteProperty(prop, 'targetMeta');
-        }
-        [
-            'prototype', 'props', 'referencingProperties', 'propertyOrder', 'relations',
-            'concurrencyCheckKeys', 'checks',
-        ].forEach(key => delete copy[key]);
-        // base entity without properties might not have path, but nothing to cache there
-        if (meta.path) {
-            this.cache.set(meta.className + extname(meta.path), copy, meta.path);
-        }
-    }
     initNullability(prop) {
-        if (prop.kind === ReferenceKind.MANY_TO_ONE) {
-            return Utils.defaultValue(prop, 'nullable', prop.optional || prop.cascade.includes(Cascade.REMOVE) || prop.cascade.includes(Cascade.ALL));
-        }
         if (prop.kind === ReferenceKind.ONE_TO_ONE) {
-            return Utils.defaultValue(prop, 'nullable', prop.optional || !prop.owner || prop.cascade.includes(Cascade.REMOVE) || prop.cascade.includes(Cascade.ALL));
+            return Utils.defaultValue(prop, 'nullable', prop.optional || !prop.owner);
         }
         return Utils.defaultValue(prop, 'nullable', prop.optional);
     }
@@ -365,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)));
@@ -376,7 +381,7 @@ export class MetadataDiscovery {
             if (prop.joinColumns.length !== prop.columnTypes.length) {
                 prop.columnTypes = prop.joinColumns.flatMap(field => {
                     const matched = meta.props.find(p => p.fieldNames?.includes(field));
-                    /* v8 ignore next 3 */
+                    /* v8 ignore next */
                     if (!matched) {
                         throw MetadataError.fromWrongForeignKey(meta, prop, 'columnTypes');
                     }
@@ -395,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 ?? {});
@@ -439,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)];
         }
@@ -480,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);
@@ -498,15 +550,21 @@ export class MetadataDiscovery {
         }
         this.initOwnColumns(meta);
         meta.simplePK = pks.length === 1 && pks[0].kind === ReferenceKind.SCALAR && !pks[0].customType && pks[0].runtimeType !== 'Date';
-        meta.serializedPrimaryKey = this.platform.getSerializedPrimaryKeyField(meta.primaryKeys[0]);
-        const serializedPKProp = meta.properties[meta.serializedPrimaryKey];
-        if (serializedPKProp && meta.serializedPrimaryKey !== meta.primaryKeys[0]) {
-            serializedPKProp.persist = false;
+        meta.serializedPrimaryKey ??= meta.props.find(prop => prop.serializedPrimaryKey)?.name;
+        if (meta.serializedPrimaryKey && meta.serializedPrimaryKey !== meta.primaryKeys[0]) {
+            meta.properties[meta.serializedPrimaryKey].persist ??= false;
         }
         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 [];
     }
@@ -523,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);
                 }
@@ -540,9 +601,9 @@ export class MetadataDiscovery {
         }
         else if (fks.length >= 2) {
             [first, second] = fks;
-            /* v8 ignore next 3 */
         }
         else {
+            /* v8 ignore next */
             return [];
         }
         // wrong FK order, first FK needs to point to the owning side
@@ -556,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`;
@@ -565,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,
@@ -573,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;
+                }
+            }
         }
-        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);
+        // 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);
+        }
+        return this.metadata.set(pivotMeta2.class, EntitySchema.fromMetadata(pivotMeta2).init().meta);
     }
-    defineFixedOrderProperty(prop, targetType) {
+    /**
+     * 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, targetMeta) {
         const pk = prop.fixedOrderColumn || this.namingStrategy.referenceColumnName();
         const primaryProp = {
             name: pk,
@@ -635,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;
         }
@@ -644,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,
@@ -656,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 = [];
@@ -702,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;
@@ -710,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;
         }
@@ -741,12 +941,9 @@ export class MetadataDiscovery {
         Utils.keys(base.hooks).forEach(type => {
             meta.hooks[type] = Utils.unique([...base.hooks[type], ...(meta.hooks[type] || [])]);
         });
-        if (meta.constructorParams.length === 0 && base.constructorParams.length > 0) {
+        if ((meta.constructorParams?.length ?? 0) === 0 && (base.constructorParams?.length ?? 0) > 0) {
             meta.constructorParams = [...base.constructorParams];
         }
-        if (meta.toJsonParams.length === 0 && base.toJsonParams.length > 0) {
-            meta.toJsonParams = [...base.toJsonParams];
-        }
         return order;
     }
     initPolyEmbeddables(embeddedProp, discovered, visited = new Set()) {
@@ -803,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;
@@ -838,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));
@@ -875,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
@@ -906,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 {
@@ -915,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);
         }
@@ -934,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 = true;
+            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,
@@ -976,18 +1417,28 @@ 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) {
             for (const prop of meta.props) {
-                if (prop.enum && !prop.nativeEnumName && prop.items?.every(item => Utils.isString(item))) {
+                if (prop.enum && !prop.nativeEnumName && prop.items?.every(item => typeof item === 'string')) {
                     this.initFieldName(prop);
                     meta.checks.push({
                         name: this.namingStrategy.indexName(meta.tableName, prop.fieldNames, 'check'),
@@ -1012,16 +1463,16 @@ 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) {
         if (typeof prop.defaultRaw !== 'undefined') {
             return prop.defaultRaw;
         }
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (prop.default != null) {
             return '' + this.platform.quoteVersionValue(prop.default, prop);
         }
@@ -1034,10 +1485,6 @@ export class MetadataDiscovery {
         return '1';
     }
     inferDefaultValue(meta, prop) {
-        /* v8 ignore next 3 */
-        if (!meta.class) {
-            return;
-        }
         try {
             // try to create two entity instances to detect the value is stable
             const now = Date.now();
@@ -1065,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;
@@ -1112,51 +1559,61 @@ export class MetadataDiscovery {
         }
         // `prop.type` might also be custom type class (not instance), so `typeof MyType` will give us `function`, not `object`
         if (typeof prop.type === 'function' && Type.isMappedType(prop.type.prototype) && !prop.customType) {
-            prop.customType = new prop.type();
-            prop.type = prop.customType.constructor.name;
+            // if the type is an ORM defined mapped type without `ensureComparable: true`,
+            // we use just the type name, to have more performant hydration code
+            const type = Utils.keys(t).find(type => {
+                return !Type.getType(t[type]).ensureComparable(meta, prop) && prop.type === t[type];
+            });
+            if (type) {
+                prop.type = type === 'datetime' ? 'Date' : type;
+            }
+            else {
+                prop.customType = new prop.type();
+                prop.type = prop.customType.constructor.name;
+            }
         }
         if (simple) {
             return;
         }
         if (!prop.customType && ['json', 'jsonb'].includes(prop.type?.toLowerCase())) {
-            prop.customType = new JsonType();
+            prop.customType = new t.json();
         }
         if (prop.kind === ReferenceKind.SCALAR && !prop.customType && prop.columnTypes && ['json', 'jsonb'].includes(prop.columnTypes[0])) {
-            prop.customType = new JsonType();
+            prop.customType = new t.json();
         }
         if (prop.kind === ReferenceKind.EMBEDDED && !prop.customType && (prop.object || prop.array)) {
-            prop.customType = new JsonType();
+            prop.customType = new t.json();
         }
         if (!prop.customType && prop.array && prop.items) {
-            prop.customType = new EnumArrayType(`${meta.className}.${prop.name}`, prop.items);
+            prop.customType = new t.enumArray(`${meta.className}.${prop.name}`, prop.items);
         }
         const isArray = prop.type?.toLowerCase() === 'array' || prop.type?.toString().endsWith('[]');
         if (objectEmbeddable && !prop.customType && isArray) {
-            prop.customType = new JsonType();
+            prop.customType = new t.json();
         }
         // for number arrays we make sure to convert the items to numbers
         if (!prop.customType && prop.type === 'number[]') {
-            prop.customType = new ArrayType(i => +i);
+            prop.customType = new t.array(i => +i);
         }
         // `string[]` can be returned via ts-morph, while reflect metadata will give us just `array`
         if (!prop.customType && isArray) {
-            prop.customType = new ArrayType();
+            prop.customType = new t.array();
         }
         if (!prop.customType && prop.type?.toLowerCase() === 'buffer') {
-            prop.customType = new BlobType();
+            prop.customType = new t.blob();
         }
         if (!prop.customType && prop.type?.toLowerCase() === 'uint8array') {
-            prop.customType = new Uint8ArrayType();
+            prop.customType = new t.uint8array();
         }
         const mappedType = this.getMappedType(prop);
         if (prop.fieldNames?.length === 1 && !prop.customType) {
-            [BigIntType, DoubleType, DecimalType, IntervalType, DateType]
+            [t.bigint, t.double, t.decimal, t.interval, t.date]
                 .filter(type => mappedType instanceof type)
-                .forEach(type => prop.customType = new type());
+                .forEach((type) => prop.customType = new type());
         }
         if (prop.customType && !prop.columnTypes) {
             const mappedType = this.getMappedType({ columnTypes: [prop.customType.getColumnType(prop, this.platform)] });
-            if (prop.customType.compareAsType() === 'any' && ![JsonType].some(t => prop.customType instanceof t)) {
+            if (prop.customType.compareAsType() === 'any' && ![t.json].some(t => prop.customType instanceof t)) {
                 prop.runtimeType ??= mappedType.runtimeType;
             }
             else {
@@ -1176,16 +1633,16 @@ export class MetadataDiscovery {
             prop.columnTypes ??= [prop.customType.getColumnType(prop, this.platform)];
             prop.hasConvertToJSValueSQL = !!prop.customType.convertToJSValueSQL && prop.customType.convertToJSValueSQL('', this.platform) !== '';
             prop.hasConvertToDatabaseValueSQL = !!prop.customType.convertToDatabaseValueSQL && prop.customType.convertToDatabaseValueSQL('', this.platform) !== '';
-            if (prop.customType instanceof BigIntType && ['string', 'bigint', 'number'].includes(prop.runtimeType.toLowerCase())) {
+            if (prop.customType instanceof t.bigint && ['string', 'bigint', 'number'].includes(prop.runtimeType.toLowerCase())) {
                 prop.customType.mode = prop.runtimeType.toLowerCase();
             }
         }
         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) !== '';
@@ -1197,7 +1654,7 @@ export class MetadataDiscovery {
                 }
             }
         }
-        if (prop.kind === ReferenceKind.SCALAR && !(mappedType instanceof UnknownType)) {
+        if (prop.kind === ReferenceKind.SCALAR && !(mappedType instanceof t.unknown)) {
             if (!prop.columnTypes && prop.nativeEnumName && meta.schema !== this.platform.getDefaultSchemaName() && meta.schema && !prop.nativeEnumName.includes('.')) {
                 prop.columnTypes = [`${meta.schema}.${prop.nativeEnumName}`];
             }
@@ -1212,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;
@@ -1240,8 +1711,7 @@ export class MetadataDiscovery {
         if (prop.kind === ReferenceKind.SCALAR) {
             const mappedType = this.getMappedType(prop);
             const SCALAR_TYPES = ['string', 'number', 'boolean', 'bigint', 'Date', 'Buffer', 'RegExp', 'any', 'unknown'];
-            if (mappedType instanceof UnknownType
-                && !prop.columnTypes
+            if (mappedType instanceof t.unknown
                 // 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
@@ -1254,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;
             }
         }
     }
@@ -1284,7 +1762,7 @@ export class MetadataDiscovery {
             t = 'enum';
         }
         else if (prop.enum) {
-            t = prop.items?.every(item => Utils.isString(item)) ? 'enum' : 'tinyint';
+            t = prop.items?.every(item => typeof item === 'string') ? 'enum' : 'tinyint';
         }
         if (t === 'Date') {
             t = 'datetime';
@@ -1308,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;
             });
@@ -1323,30 +1800,6 @@ export class MetadataDiscovery {
             prop.index ??= true;
         }
     }
-    async getEntityClassOrSchema(path, name) {
-        const exports = await Utils.dynamicImport(path);
-        const targets = Object.values(exports)
-            .filter(item => item instanceof EntitySchema || (item instanceof Function && MetadataStorage.isKnownEntity(item.name)));
-        // ignore class implementations that are linked from an EntitySchema
-        for (const item of targets) {
-            if (item instanceof EntitySchema) {
-                targets.forEach((item2, idx) => {
-                    if (item.meta.class === item2) {
-                        targets.splice(idx, 1);
-                    }
-                });
-            }
-        }
-        if (targets.length > 0) {
-            return targets;
-        }
-        const target = exports.default ?? exports[name];
-        /* v8 ignore next 3 */
-        if (!target) {
-            throw MetadataError.entityNotFound(name, path.replace(this.config.get('baseDir'), '.'));
-        }
-        return [target];
-    }
     shouldForceConstructorUsage(meta) {
         const forceConstructor = this.config.get('forceEntityConstructor');
         if (Array.isArray(forceConstructor)) {