@mikro-orm/core 7.0.0-dev.19 → 7.0.0-dev.190

package/metadata/MetadataDiscovery.js

@@ -1,22 +1,21 @@
-import { basename, extname } from 'node:path';
-import globby from 'globby';
 import { EntityMetadata, } from '../typings.js';
-import { Utils } from '../utils/Utils.js';
+import { compareArrays, Utils } from '../utils/Utils.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 +26,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 +47,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,15 +73,48 @@ 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);
+        }
         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);
@@ -86,66 +122,61 @@ export class MetadataDiscovery {
         filtered.sort((a, b) => !a.embeddable === !b.embeddable ? 0 : (a.embeddable ? 1 : -1));
         filtered.forEach(meta => this.initSingleTableInheritance(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.initRelation(p));
+        forEachProp((m, p) => this.initEmbeddables(m, p));
+        forEachProp((_m, p) => this.initFieldName(p));
+        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);
             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));
-        if (paths.length > 0) {
-            if (sync || options.requireEntitiesArray) {
-                throw new Error(`[requireEntitiesArray] Explicit list of entities is required, please use the 'entities' option.`);
+    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);
             }
-            return this.discoverDirectories(paths).then(() => {
-                this.discoverReferences(refs);
-                this.discoverMissingTargets();
-                this.validator.validateDiscovered(this.discovered, options);
-                return this.discovered;
-            });
         }
-        this.discoverReferences(refs);
-        this.discoverMissingTargets();
-        this.validator.validateDiscovered(this.discovered, options);
-        return this.discovered;
+        if (paths.length > 0) {
+            const { discoverEntities } = await import('@mikro-orm/core/file-discovery');
+            processed.push(...await discoverEntities(paths, { baseDir }));
+        }
+        return this.discoverReferences(processed);
     }
     discoverMissingTargets() {
         const unwrap = (type) => type
@@ -154,17 +185,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.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 && !unwrap(prop.type).split(/ ?\| ?/).every(type => this.discovered.find(m => m.className === type))) {
-                const target = typeof prop.entity === 'function'
+            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 +209,105 @@ 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 globby(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);
+            }
+            if (typeof parent === 'function' && parent.name && !this.metadata.has(parent)) {
+                this.discoverReferences([parent], false);
             }
-            /* v8 ignore next 3 */
+            /* 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);
+        if (root.discriminatorColumn) {
+            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 +316,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);
     }
@@ -376,7 +362,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');
                     }
@@ -402,23 +388,23 @@ export class MetadataDiscovery {
             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 +425,58 @@ 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.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);
+        const ownerTableName = this.isExplicitTableName(meta.root) ? meta.root.tableName : undefined;
+        const inverseTableName = this.isExplicitTableName(meta2.root) ? meta2.root.tableName : undefined;
+        prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.namingStrategy.joinKeyColumnName(meta.root.className, referencedColumnName, meta.compositePK, ownerTableName));
+        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);
+        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 +489,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 +512,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 +543,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 +563,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 +579,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 +590,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 +600,61 @@ 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);
             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, data);
+        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) {
+    defineFixedOrderProperty(prop, targetMeta) {
         const pk = prop.fixedOrderColumn || this.namingStrategy.referenceColumnName();
         const primaryProp = {
             name: pk,
@@ -635,7 +668,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 +677,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,
@@ -654,11 +688,11 @@ export class MetadataDiscovery {
             autoincrement: false,
             updateRule: prop.updateRule,
             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 = [];
@@ -701,7 +735,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;
@@ -709,7 +743,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;
         }
@@ -740,12 +774,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()) {
@@ -821,22 +852,30 @@ export class MetadataDiscovery {
             }
             return prop.embedded ? isParentObject(meta.properties[prop.embedded[0]]) : false;
         };
+        const isParentArray = (prop) => {
+            if (prop.array) {
+                return true;
+            }
+            return prop.embedded ? isParentArray(meta.properties[prop.embedded[0]]) : false;
+        };
         const rootProperty = getRootProperty(embeddedProp);
         const parentProperty = meta.properties[embeddedProp.embedded?.[0] ?? ''];
         const object = isParentObject(embeddedProp);
+        const array = isParentArray(embeddedProp);
         this.initFieldName(embeddedProp, rootProperty !== embeddedProp && object);
         // the prefix of the parent cannot be a boolean; it already passed here
         const prefix = this.getPrefix(embeddedProp, parentProperty);
         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));
             embeddedProp.embeddedProps[prop.name] = meta.properties[name];
             meta.properties[name].persist ??= embeddedProp.persist;
-            if (embeddedProp.nullable) {
+            const refInArray = array && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && prop.owner;
+            if (embeddedProp.nullable || refInArray) {
                 meta.properties[name].nullable = true;
             }
             if (meta.properties[name].fieldNames) {
@@ -866,14 +905,17 @@ 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
                 meta.properties[name].object = true;
+                this.initCustomType(meta, meta.properties[name], false, true);
             }
             this.initEmbeddables(meta, meta.properties[name], visited);
         }
@@ -896,7 +938,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 {
@@ -905,17 +947,23 @@ export class MetadataDiscovery {
         if (!meta.root.discriminatorColumn) {
             return;
         }
-        if (!meta.root.discriminatorMap) {
+        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 = Object.entries(meta.root.discriminatorMap).find(([, cls]) => cls === meta.class)?.[0];
         if (!meta.root.properties[meta.root.discriminatorColumn]) {
             this.createDiscriminatorProperty(meta.root);
         }
@@ -924,28 +972,46 @@ 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]);
@@ -967,7 +1033,7 @@ export class MetadataDiscovery {
         }
     }
     initCheckConstraints(meta) {
-        const map = this.createColumnMappingObject(meta);
+        const map = meta.createColumnMappingObject();
         for (const check of meta.checks) {
             const columns = check.property ? meta.properties[check.property].fieldNames : [];
             check.name ??= this.namingStrategy.indexName(meta.tableName, columns, 'check');
@@ -977,7 +1043,7 @@ export class MetadataDiscovery {
         }
         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'),
@@ -1002,38 +1068,28 @@ export class MetadataDiscovery {
             }
             return;
         }
-        const map = this.createColumnMappingObject(meta);
+        const map = meta.createColumnMappingObject();
         if (prop.generated instanceof Function) {
             prop.generated = prop.generated(map);
         }
     }
-    createColumnMappingObject(meta) {
-        return Object.values(meta.properties).reduce((o, prop) => {
-            if (prop.fieldNames) {
-                o[prop.name] = prop.fieldNames[0];
-            }
-            return o;
-        }, {});
-    }
-    getDefaultVersionValue(prop) {
+    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);
         }
-        if (prop.type.toLowerCase() === 'date') {
+        this.initCustomType(meta, prop, true);
+        const type = prop.customType?.runtimeType ?? prop.runtimeType ?? prop.type;
+        if (type === 'Date') {
             prop.length ??= this.platform.getDefaultVersionLength();
             return this.platform.getCurrentTimestampSQL(prop.length);
         }
         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();
@@ -1061,12 +1117,12 @@ 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;
         }
-        if (prop.customType instanceof ArrayType && Array.isArray(prop.default)) {
+        if (Array.isArray(prop.default) && prop.customType) {
             val = prop.customType.convertToDatabaseValue(prop.default, this.platform);
         }
         prop.defaultRaw = typeof val === 'string' ? `'${val}'` : '' + val;
@@ -1094,13 +1150,13 @@ export class MetadataDiscovery {
         if (prop.version) {
             this.initDefaultValue(prop);
             meta.versionProperty = prop.name;
-            prop.defaultRaw = this.getDefaultVersionValue(prop);
+            prop.defaultRaw = this.getDefaultVersionValue(meta, prop);
         }
         if (prop.concurrencyCheck && !prop.primary) {
             meta.concurrencyCheckKeys.add(prop.name);
         }
     }
-    initCustomType(meta, prop) {
+    initCustomType(meta, prop, simple = false, objectEmbeddable = false) {
         // `prop.type` might be actually instance of custom type class
         if (Type.isMappedType(prop.type) && !prop.customType) {
             prop.customType = prop.type;
@@ -1108,41 +1164,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 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 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 && (prop.type?.toLowerCase() === 'array' || prop.type?.toString().endsWith('[]'))) {
-            prop.customType = new ArrayType();
+        if (!prop.customType && isArray) {
+            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 {
@@ -1162,16 +1238,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 && !prop.type?.toString().endsWith('[]')) {
+        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.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) !== '';
@@ -1183,7 +1259,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}`];
             }
@@ -1201,19 +1277,28 @@ export class MetadataDiscovery {
         if (prop.kind === ReferenceKind.SCALAR) {
             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;
+        }
         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])}`;
+            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;
@@ -1226,8 +1311,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
@@ -1240,23 +1324,28 @@ 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();
+        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;
             }
         }
     }
@@ -1270,7 +1359,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';
@@ -1294,7 +1383,7 @@ export class MetadataDiscovery {
             return;
         }
         if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
-            const meta2 = this.metadata.get(prop.type);
+            const meta2 = prop.targetMeta;
             prop.unsigned = meta2.getPrimaryProps().some(pk => {
                 this.initUnsigned(pk);
                 return pk.unsigned;
@@ -1309,30 +1398,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)) {