@mikro-orm/sql 7.2.0-dev.13 → 7.2.0-dev.14

package/AbstractSqlDriver.d.ts

@@ -118,13 +118,6 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
     mergeJoinedResult<T extends object>(rawResults: EntityData<T>[], meta: EntityMetadata<T>, joinedProps: PopulateOptions<T>[]): EntityData<T>[];
     protected shouldHaveColumn<T, U>(meta: EntityMetadata<T>, prop: EntityProperty<U>, populate: readonly PopulateOptions<U>[], fields?: readonly InternalField<U>[], exclude?: readonly InternalField<U>[]): boolean;
     protected getFieldsForJoinedLoad<T extends object>(qb: AnyQueryBuilder<T>, meta: EntityMetadata<T>, options: FieldsForJoinedLoadOptions<T>): InternalField<T>[];
-    /**
-     * Walks the TPT inheritance chain of `leafMeta` and INNER JOINs each parent table.
-     * Registers the parent aliases in `qb.state.tptAlias` so column resolution finds them
-     * when filter conditions reference parent-table columns.
-     * @internal
-     */
-    protected addTPTParentJoinsForRelation<T extends object>(qb: AnyQueryBuilder<T>, leafMeta: EntityMetadata, leafAlias: string, basePath: string): void;
     /**
      * Adds LEFT JOINs and fields for TPT polymorphic loading when populating a relation to a TPT base class.
      * @internal

package/AbstractSqlDriver.js

@@ -915,7 +915,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (!options.upsert && options.unionWhere?.length) {
             where = (await this.applyUnionWhere(meta, where, options, true));
         }
-        if (Utils.hasObjectKeys(data)) {
+        if (options.upsert && meta.tptParent) {
+            res = await this.nativeUpdateMany(entityName, [where], [data], options);
+        }
+        else if (Utils.hasObjectKeys(data) || (meta.inheritanceType === 'tpt' && meta.ownsVersionProperty())) {
+            // a TPT table declaring the version property is bumped even when only other tables of the hierarchy changed
             const qb = this.createQueryBuilder(entityName, options.ctx, 'write', options.convertCustomTypes, options.loggerContext).withSchema(this.getSchemaName(meta, options));
             qb.setAbortOptions(pickAbortOptions(options));
             if (options.upsert) {
@@ -941,7 +945,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 qb.update(data).where(where);
                 // reload generated columns and version fields
                 const returning = [];
-                meta.props
+                this.getTableProps(meta)
                     .filter(prop => (prop.generated && !prop.primary) || prop.version)
                     .forEach(prop => returning.push(prop.name));
                 qb.returning(returning);
@@ -957,13 +961,38 @@ export class AbstractSqlDriver extends DatabaseDriver {
         options.convertCustomTypes ??= true;
         const meta = this.metadata.get(entityName);
         if (options.upsert) {
+            if (meta.tptParent) {
+                // TPT parent tables go first, the PK they provide is the conflict target of this table
+                await this.nativeUpdateMany(meta.tptParent.class, where, data, options);
+                for (const [i, row] of data.entries()) {
+                    if (meta.primaryKeys.some(pk => row[pk] == null)) {
+                        const found = await this.findOne(meta.tptParent.class, where[i], {
+                            fields: meta.primaryKeys,
+                            ctx: options.ctx,
+                            connectionType: 'write',
+                            schema: options.schema,
+                        });
+                        meta.primaryKeys.forEach(pk => (row[pk] = found?.[pk]));
+                    }
+                }
+                options = { ...options, onConflictFields: meta.primaryKeys, onConflictWhere: undefined };
+            }
             const uniqueFields = options.onConflictFields ??
                 (Utils.isPlainObject(where[0])
                     ? Object.keys(where[0]).flatMap(key => Utils.splitPrimaryKeys(key))
                     : meta.primaryKeys);
             const qb = this.createQueryBuilder(entityName, options.ctx, 'write', options.convertCustomTypes, options.loggerContext).withSchema(this.getSchemaName(meta, options));
             qb.setAbortOptions(pickAbortOptions(options));
-            const returning = getOnConflictReturningFields(meta, data[0], uniqueFields, options);
+            let returning = getOnConflictReturningFields(meta, data[0], uniqueFields, options);
+            if (meta.inheritanceType === 'tpt') {
+                // each TPT table only carries its own columns, the entity is reloaded instead of mapping the returned rows
+                const own = (key) => meta.primaryKeys.includes(key) ||
+                    this.getTableProps(meta).some(prop => prop.name === key.split('.')[0]);
+                data = data.map(row => Object.fromEntries(Object.entries(row).filter(([key]) => own(key))));
+                options.onConflictMergeFields = options.onConflictMergeFields?.filter(f => own(f));
+                options.onConflictExcludeFields = options.onConflictExcludeFields?.filter(f => own(f));
+                returning = [];
+            }
             qb.insert(data)
                 .onConflict(uniqueFields)
                 .returning(returning);
@@ -977,7 +1006,8 @@ export class AbstractSqlDriver extends DatabaseDriver {
             if (options.onConflictWhere) {
                 qb.where(options.onConflictWhere);
             }
-            return this.rethrow(qb.execute('run', false));
+            const res = await this.rethrow(qb.execute('run', false));
+            return meta.inheritanceType === 'tpt' ? { ...res, row: undefined, rows: [] } : res;
         }
         const collections = options.processCollections ? data.map(d => this.extractManyToMany(meta, d)) : [];
         const keys = new Set();
@@ -992,7 +1022,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
             }
         }
         // reload generated columns and version fields
-        meta.props.filter(prop => prop.generated || prop.version || prop.primary).forEach(prop => returning.add(prop.name));
+        meta.getPrimaryProps().forEach(prop => returning.add(prop.name));
+        this.getTableProps(meta)
+            .filter(prop => prop.generated || prop.version)
+            .forEach(prop => returning.add(prop.name));
         const pkCond = Utils.flatten(meta.primaryKeys.map(pk => meta.properties[pk].fieldNames))
             .map(pk => `${this.platform.quoteIdentifier(pk)} = ?`)
             .join(' and ');
@@ -1050,7 +1083,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 return sql;
             });
         }
-        if (meta.versionProperty) {
+        if (meta.ownsVersionProperty()) {
             const versionProperty = meta.properties[meta.versionProperty];
             const quotedFieldName = this.platform.quoteIdentifier(versionProperty.fieldNames[0]);
             sql += `${quotedFieldName} = `;
@@ -1063,7 +1096,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
             sql += `, `;
         }
         sql = sql.substring(0, sql.length - 2) + ' where ';
-        const pkProps = meta.primaryKeys.concat(...meta.concurrencyCheckKeys);
+        const pkProps = meta.primaryKeys.concat(...meta.getOwnConcurrencyCheckKeys());
         const pks = Utils.flatten(pkProps.map(pk => meta.properties[pk].fieldNames));
         const useTupleIn = pks.length <= 1 || this.platform.allowsComparingTuples();
         const condTemplate = useTupleIn
@@ -1649,6 +1682,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
             if (prop.kind === ReferenceKind.ONE_TO_ONE && prop.mapToPk && prop.owner) {
                 return false;
             }
+            // Polymorphic to-one flattened from an object embeddable lives inside a JSON column, so the join
+            // conditions would need JSON extraction for both the discriminator and the FK; fall back to SELECT_IN.
+            if (prop.polymorphic && prop.object && prop.embedded) {
+                return false;
+            }
             if (strategy !== LoadStrategy.JOINED) {
                 // force joined strategy for explicit 1:1 owner populate hint as it would require a join anyway
                 return prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner;
@@ -1779,7 +1817,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     // INNER JOINs get nested inside the polymorphic LEFT JOIN by processNestedJoins, which
                     // keeps the resulting query valid for rows pointing to other polymorphic targets.
                     if (targetMeta.inheritanceType === 'tpt' && targetMeta.tptParent) {
-                        this.addTPTParentJoinsForRelation(qb, targetMeta, tableAlias, targetPath);
+                        qb.addTPTParentJoins(targetMeta, tableAlias, targetPath);
                     }
                     // For polymorphic targets that are TPT base classes, also LEFT JOIN
                     // all descendant tables so child-specific fields can be selected.
@@ -1827,10 +1865,6 @@ export class AbstractSqlDriver extends DatabaseDriver {
                         : JoinType.leftJoin;
             const schema = prop.targetMeta.schema === '*' ? (options?.schema ?? this.config.get('schema')) : prop.targetMeta.schema;
             qb.join(field, tableAlias, {}, joinType, path, schema);
-            // For relations to TPT child entities, INNER JOIN parent tables (GH #7469)
-            if (meta2.inheritanceType === 'tpt' && meta2.tptParent) {
-                this.addTPTParentJoinsForRelation(qb, meta2, tableAlias, path);
-            }
             // For relations to TPT base classes, add LEFT JOINs for all child tables (polymorphic loading)
             if (meta2.inheritanceType === 'tpt' && meta2.tptChildren?.length && !ref) {
                 // Use the registry metadata to ensure allTPTDescendants is available
@@ -1877,25 +1911,6 @@ export class AbstractSqlDriver extends DatabaseDriver {
         }
         return fields;
     }
-    /**
-     * Walks the TPT inheritance chain of `leafMeta` and INNER JOINs each parent table.
-     * Registers the parent aliases in `qb.state.tptAlias` so column resolution finds them
-     * when filter conditions reference parent-table columns.
-     * @internal
-     */
-    addTPTParentJoinsForRelation(qb, leafMeta, leafAlias, basePath) {
-        let childAlias = leafAlias;
-        let childMeta = leafMeta;
-        while (childMeta.tptParent) {
-            const parentMeta = childMeta.tptParent;
-            const parentAlias = qb.getNextAlias(parentMeta.className);
-            qb.createAlias(parentMeta.class, parentAlias);
-            qb.state.tptAlias[`${leafAlias}:${parentMeta.className}`] = parentAlias;
-            qb.addPropertyJoin(childMeta.tptParentProp, childAlias, parentAlias, JoinType.innerJoin, `${basePath}.[tpt]${childMeta.className}`);
-            childAlias = parentAlias;
-            childMeta = parentMeta;
-        }
-    }
     /**
      * Adds LEFT JOINs and fields for TPT polymorphic loading when populating a relation to a TPT base class.
      * @internal

package/AbstractSqlPlatform.d.ts

@@ -28,7 +28,7 @@ export declare abstract class AbstractSqlPlatform extends Platform {
     getReleaseSavepointSQL(savepointName: string): string;
     quoteValue(value: any): string;
     getSearchJsonPropertySQL(path: string, type: string, aliased: boolean): string | RawQueryFragment;
-    getSearchJsonPropertyKey(path: string[], type: string, aliased: boolean, value?: unknown): string | RawQueryFragment;
+    getSearchJsonPropertyKey(path: string[], type: string, aliased: boolean | string, value?: unknown): string | RawQueryFragment;
     /**
      * Quotes a key for use inside a JSON path expression (e.g. `$.key`).
      * Simple alphanumeric keys are left unquoted; others are wrapped in double quotes

package/AbstractSqlPlatform.js

@@ -75,6 +75,9 @@ export class AbstractSqlPlatform extends Platform {
     getSearchJsonPropertyKey(path, type, aliased, value) {
         const [a, ...b] = path;
         const jsonPath = this.quoteValue(`$.${b.map(this.quoteJsonKey).join('.')}`);
+        if (typeof aliased === 'string') {
+            return raw(`json_extract(${this.quoteIdentifier(`${aliased}.${a}`)}, ${jsonPath})`);
+        }
         if (aliased) {
             return raw(alias => `json_extract(${this.quoteIdentifier(`${alias}.${a}`)}, ${jsonPath})`);
         }

package/SqlEntityManager.js

@@ -81,7 +81,9 @@ export class SqlEntityManager extends EntityManager {
         const { where: rawWhere, ...countOptions } = options;
         await em.tryFlush(entityName, options);
         const where = await em.processWhere(entityName, rawWhere ?? {}, options, 'read');
-        const qb = em.createQueryBuilder(meta.class);
+        // match `em.count()` semantics: an active transaction always wins over the requested connection type
+        const connectionType = em.getTransactionContext() ? 'write' : options.connectionType;
+        const qb = em.createQueryBuilder(meta.class, undefined, connectionType);
         qb
             .select([...fields, raw('count(*) as cnt')])
             .where(where)

package/dialects/postgresql/BasePostgreSqlPlatform.d.ts

@@ -88,7 +88,7 @@ export declare class BasePostgreSqlPlatform extends AbstractSqlPlatform {
     }): string;
     getBlobDeclarationSQL(): string;
     getJsonDeclarationSQL(): string;
-    getSearchJsonPropertyKey(path: string[], type: string | undefined | Type, aliased: boolean, value?: unknown): string | RawQueryFragment;
+    getSearchJsonPropertyKey(path: string[], type: string | undefined | Type, aliased: boolean | string, value?: unknown): string | RawQueryFragment;
     getJsonIndexDefinition(index: IndexDef): string[];
     quoteIdentifier(id: string | {
         toString: () => string;

package/dialects/postgresql/BasePostgreSqlPlatform.js

@@ -285,7 +285,8 @@ export class BasePostgreSqlPlatform extends AbstractSqlPlatform {
     getSearchJsonPropertyKey(path, type, aliased, value) {
         const first = path.shift();
         const last = path.pop();
-        const root = this.quoteIdentifier(aliased ? `${ALIAS_REPLACEMENT}.${first}` : first);
+        const alias = typeof aliased === 'string' ? aliased : ALIAS_REPLACEMENT;
+        const root = this.quoteIdentifier(aliased ? `${alias}.${first}` : first);
         type = typeof type === 'string' ? this.getMappedType(type).runtimeType : String(type);
         const cast = (key) => raw(type in this.#jsonTypeCasts ? `(${key})::${this.#jsonTypeCasts[type]}` : key);
         let lastOperator = '->>';

package/dialects/postgresql/PostgreSqlSchemaHelper.js

@@ -494,7 +494,7 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             // SchemaHelper.createCheck).
             const m = /^check \(\((.*)\)\)$/is.exec(check.expression);
             const single = m ? null : /^check \((.*)\)$/is.exec(check.expression);
-            const def = m ? m[1].replace(/\(([^()]*)\)::\w+/g, '$1') : single ? single[1] : check.expression;
+            const def = m ? m[1].replace(/\(([^()]*)\)::\w+(?:\[\])?/g, '$1') : single ? single[1] : check.expression;
             ret[key].push({
                 name: check.name,
                 columnName: check.column_name,

package/dialects/sqlite/SqliteSchemaHelper.js

@@ -489,7 +489,7 @@ export class SqliteSchemaHelper extends SchemaHelper {
      * Foreign key references can only point to tables in the same database.
      */
     getReferencedTableName(referencedTableName, schema) {
-        const [schemaName, tableName] = this.splitTableName(referencedTableName);
+        const [, tableName] = this.splitTableName(referencedTableName);
         // Strip any schema prefix - SQLite REFERENCES clause doesn't support it
         return tableName;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/sql",
-  "version": "7.2.0-dev.13",
+  "version": "7.2.0-dev.14",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",
@@ -50,10 +50,10 @@
     "kysely": "0.29.5"
   },
   "devDependencies": {
-    "@mikro-orm/core": "^7.1.11"
+    "@mikro-orm/core": "^7.1.15"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.2.0-dev.13"
+    "@mikro-orm/core": "7.2.0-dev.14"
   },
   "engines": {
     "node": ">= 22.17.0"

package/plugin/transformer.d.ts

@@ -1,5 +1,5 @@
 import { type EntityMetadata, type EntityProperty, type Type } from '@mikro-orm/core';
-import { type CommonTableExpressionNameNode, type DeleteQueryNode, type InsertQueryNode, type JoinNode, type MergeQueryNode, type OperationNode, type QueryId, type SelectQueryNode, type UpdateQueryNode, type WithNode, ColumnNode, IdentifierNode, OperationNodeTransformer, SelectionNode, TableNode, ValueNode } from 'kysely';
+import { type BinaryOperationNode, type CommonTableExpressionNameNode, type DeleteQueryNode, type InsertQueryNode, type JoinNode, type MergeQueryNode, type OperationNode, type QueryId, type SelectQueryNode, type UpdateQueryNode, type WithNode, ColumnNode, IdentifierNode, OperationNodeTransformer, SelectionNode, TableNode, ValueNode } from 'kysely';
 import type { MikroKyselyPluginOptions } from './index.js';
 import type { SqlEntityManager } from '../SqlEntityManager.js';
 export declare class MikroTransformer extends OperationNodeTransformer {
@@ -28,6 +28,12 @@ export declare class MikroTransformer extends OperationNodeTransformer {
     processOnUpdateHooks(node: UpdateQueryNode, meta: EntityMetadata): UpdateQueryNode;
     processInsertValues(node: InsertQueryNode, meta: EntityMetadata): InsertQueryNode;
     processUpdateValues(node: UpdateQueryNode, meta: EntityMetadata): UpdateQueryNode;
+    transformBinaryOperation(node: BinaryOperationNode, queryId: QueryId): BinaryOperationNode;
+    /** Resolve the entity property a comparison's left operand refers to, so its value operand can be converted. */
+    resolveOperandProperty(operand: OperationNode): {
+        prop: EntityProperty;
+        fieldName: string;
+    } | undefined;
     processInputValueNode(prop: EntityProperty | undefined, fieldName: string | undefined, valueNode: ValueNode): OperationNode;
     expandSelections(selections: readonly SelectionNode[]): readonly SelectionNode[];
     expandSelection(sel: SelectionNode): SelectionNode[] | null;

package/plugin/transformer.js

@@ -455,6 +455,60 @@ export class MikroTransformer extends OperationNodeTransformer {
             updates,
         };
     }
+    transformBinaryOperation(node, queryId) {
+        const transformed = super.transformBinaryOperation(node, queryId);
+        if (!this.#options.convertValues) {
+            return transformed;
+        }
+        const resolved = this.resolveOperandProperty(transformed.leftOperand);
+        if (!resolved) {
+            return transformed;
+        }
+        const { prop, fieldName } = resolved;
+        const right = transformed.rightOperand;
+        if (ValueNode.is(right)) {
+            const converted = this.processInputValueNode(prop, fieldName, right);
+            return converted === right ? transformed : { ...transformed, rightOperand: converted };
+        }
+        if (PrimitiveValueListNode.is(right)) {
+            // upgrade to ValueListNode when the type needs SQL-side wrapping, since
+            // PrimitiveValueListNode can only hold primitives
+            if (prop.hasConvertToDatabaseValueSQL) {
+                const values = right.values.map(value => this.processInputValueNode(prop, fieldName, ValueNode.create(value)));
+                return { ...transformed, rightOperand: ValueListNode.create(values) };
+            }
+            const values = right.values.map(value => this.prepareInputValue(prop, value, true));
+            return values.every((value, idx) => value === right.values[idx])
+                ? transformed
+                : { ...transformed, rightOperand: PrimitiveValueListNode.create(values) };
+        }
+        if (ValueListNode.is(right)) {
+            let changed = false;
+            const values = right.values.map(valueNode => {
+                if (!ValueNode.is(valueNode)) {
+                    return valueNode;
+                }
+                const converted = this.processInputValueNode(prop, fieldName, valueNode);
+                if (converted !== valueNode) {
+                    changed = true;
+                }
+                return converted;
+            });
+            return changed ? { ...transformed, rightOperand: ValueListNode.create(values) } : transformed;
+        }
+        return transformed;
+    }
+    /** Resolve the entity property a comparison's left operand refers to, so its value operand can be converted. */
+    resolveOperandProperty(operand) {
+        if (!ReferenceNode.is(operand) || !ColumnNode.is(operand.column)) {
+            return undefined;
+        }
+        const tableName = operand.table ? this.getTableName(operand.table) : undefined;
+        const meta = this.findOwnerMeta(tableName);
+        const fieldName = this.normalizeColumnName(operand.column.column);
+        const prop = this.findProperty(meta, fieldName);
+        return prop ? { prop, fieldName } : undefined;
+    }
     processInputValueNode(prop, fieldName, valueNode) {
         const converted = this.prepareInputValue(prop, valueNode.value, true);
         const newValueNode = converted === valueNode.value
@@ -543,8 +597,13 @@ export class MikroTransformer extends OperationNodeTransformer {
         if (name) {
             return this.lookupInContextStack(name) ?? this.#subqueryAliasMap.get(name) ?? this.findEntityMetadata(name);
         }
+        // the stack can be empty when transforming a raw root node with embedded expressions
+        const context = this.#contextStack[this.#contextStack.length - 1];
+        if (!context) {
+            return undefined;
+        }
         let single;
-        for (const meta of this.#contextStack[this.#contextStack.length - 1].values()) {
+        for (const meta of context.values()) {
             if (!meta) {
                 continue;
             }

package/query/CriteriaNodeFactory.js

@@ -57,6 +57,10 @@ export class CriteriaNodeFactory {
         if (isNotEmbedded && prop?.customType instanceof JsonType) {
             return this.createScalarNode(metadata, childEntity, val, node, key, validate);
         }
+        // operator payloads under an unresolvable alias-prefixed key (e.g. `a.meta`) are opaque values, not entity criteria
+        if (!prop && !rawField && Utils.isOperator(key, false) && String(node.key).includes('.')) {
+            return this.createScalarNode(metadata, entityName, val, node, key, validate);
+        }
         if (prop?.kind === ReferenceKind.SCALAR && val != null && Object.keys(val).some(f => f in GroupOperator)) {
             throw ValidationError.cannotUseGroupOperatorsInsideScalars(entityName, prop.name, payload);
         }

package/query/ObjectCriteriaNode.js

@@ -113,7 +113,8 @@ export class ObjectCriteriaNode extends CriteriaNode {
             }
             else if (isRawField) {
                 const rawField = RawQueryFragment.getKnownFragment(field);
-                o[raw(rawField.sql.replaceAll(ALIAS_REPLACEMENT, alias), rawField.params)] = payload;
+                qb.ensureTPTJoins();
+                o[raw(qb.helper.replaceAliases(rawField.sql, alias), rawField.params)] = payload;
             }
             else if (!childNode.validate && !childNode.prop && !field.includes('.') && !operator) {
                 // wrap unknown fields in raw() to prevent alias prefixing (e.g. raw SQL aliases in HAVING)

package/query/QueryBuilder.d.ts

@@ -439,7 +439,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      */
     join<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field, alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, type?: JoinType, path?: string, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>, RawAliases, Fields, CTEs>;
     /**
-     * Adds a JOIN clause to the query for a subquery.
+     * Adds a JOIN clause to the query for a subquery. Use `sql.ref('...')` to join a table or CTE by name.
      */
     join<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, type?: JoinType, path?: string, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, Fields, CTEs>;
     /**
@@ -447,7 +447,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      */
     innerJoin<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field, alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>, RawAliases, Fields, CTEs>;
     /**
-     * Adds an INNER JOIN clause to the query for a subquery.
+     * Adds an INNER JOIN clause to the query for a subquery. Use `sql.ref('...')` to join a table or CTE by name.
      */
     innerJoin<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, Fields, CTEs>;
     innerJoinLateral<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, Fields, CTEs>;
@@ -456,7 +456,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      */
     leftJoin<Field extends QBField<Entity, RootAlias, Context>, Alias extends string>(field: Field, alias: Alias, cond?: JoinCondition<JoinedEntityType<Entity, Context, Field & string>, Alias>, schema?: string): SelectQueryBuilder<Entity, RootAlias, ModifyHint<RootAlias, Context, Hint, Field> & {}, ModifyContext<Entity, Context, Field, Alias>, RawAliases, Fields, CTEs>;
     /**
-     * Adds a LEFT JOIN clause to the query for a subquery.
+     * Adds a LEFT JOIN clause to the query for a subquery. Use `sql.ref('...')` to join a table or CTE by name.
      */
     leftJoin<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, Fields, CTEs>;
     leftJoinLateral<Alias extends string>(field: RawQueryFragment | QueryBuilder<any>, alias: Alias, cond?: RawJoinCondition, schema?: string): SelectQueryBuilder<Entity, RootAlias, Hint, ModifyContext<Entity, Context, string, Alias>, RawAliases, Fields, CTEs>;
@@ -782,6 +782,8 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * @internal
      */
     getJoinForPath(path: string, options?: ICriteriaNodeProcessOptions): JoinOptions | undefined;
+    /** Branch-insensitive path matching still must not cross branches — segments with different explicit branch markers (e.g. `Mobile[0]` vs `Mobile[1]`) belong to sibling joins. */
+    private branchesConflict;
     /**
      * @internal
      */
@@ -948,6 +950,13 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      */
     addPropertyJoin(prop: EntityProperty, ownerAlias: string, alias: string, type: JoinType, path: string, schema?: string): string;
     private joinReference;
+    /**
+     * Walks the TPT inheritance chain of `leafMeta` and INNER JOINs each parent table.
+     * Registers the parent aliases in `state.tptAlias` so column resolution finds them
+     * when conditions reference parent-table columns.
+     * @internal
+     */
+    addTPTParentJoins(leafMeta: EntityMetadata, leafAlias: string, basePath: string): void;
     protected prepareFields<T>(fields: InternalField<T>[], type?: 'where' | 'groupBy' | 'sub-query', schema?: string): (string | RawQueryFragment)[];
     /**
      * Resolves nested paths like `a.books.title` to their actual field references.
@@ -994,6 +1003,20 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     processPopulateHint(): void;
     private processPopulateWhere;
     private mergeOnConditions;
+    /**
+     * `$or` branches can be moved to a join's `on` clause only when they all target that same join
+     * and stay flat — a partial `$or` in the `on` clause would drop rows matching a sibling branch,
+     * and nested operators cannot be preserved inside a distributed disjunction, as `mergeOnConditions`
+     * would flatten them into `and` conjuncts.
+     */
+    private canDistributeOrBranches;
+    private getOrBranchAliases;
+    /**
+     * An entity filter's `$or` that cannot be distributed is applied intact to the `on` clause of the
+     * outermost join common to all targeted joins, nesting the targeted joins under it so the clause
+     * can reference their aliases.
+     */
+    private mergeFilterOrCondition;
     /**
      * When adding an inner join on a left joined relation, we need to nest them,
      * otherwise the inner join could discard rows of the root table.

package/query/QueryBuilder.js

@@ -397,7 +397,10 @@ export class QueryBuilder {
      * @internal
      */
     scheduleFilterCheck(path) {
-        this.#state.autoJoinedPaths.push(path);
+        // deduplicate so filters forming a relation cycle cannot reschedule an already visited path forever
+        if (!this.#state.autoJoinedPaths.includes(path)) {
+            this.#state.autoJoinedPaths.push(path);
+        }
     }
     /**
      * @internal
@@ -492,7 +495,10 @@ export class QueryBuilder {
             return cond.some(c => this.condReferencesAlias(c, alias));
         }
         if (Utils.isPlainObject(cond)) {
-            return Object.entries(cond).some(([key, value]) => key.startsWith(`${alias}.`) || this.condReferencesAlias(value, alias));
+            return Object.entries(cond).some(([key, value]) => {
+                const [keyAlias, field] = this.helper.splitField(key);
+                return this.helper.getTPTAliasForProperty(field, keyAlias) === alias || this.condReferencesAlias(value, alias);
+            });
         }
         return false;
     }
@@ -901,6 +907,8 @@ export class QueryBuilder {
         if (this.type === QueryType.INSERT) {
             const returningProps = meta.hydrateProps
                 .filter(prop => prop.returning || (prop.persist !== false && ((prop.primary && prop.autoincrement) || prop.defaultRaw)))
+                // a TPT table can only return its own columns
+                .filter(prop => meta.inheritanceType !== 'tpt' || prop.primary || meta.ownProps.some(p => p.name === prop.name))
                 .filter(prop => !data || !(prop.name in data));
             if (returningProps.length > 0) {
                 qb.returning(Utils.flatten(returningProps.map(prop => prop.fieldNames)));
@@ -990,12 +998,13 @@ export class QueryBuilder {
         }
         if (!join && options?.ignoreBranching) {
             join = joins.find(j => {
-                return j.path?.replace(/\[\d+]/g, '') === path.replace(/\[\d+]/g, '');
+                return j.path?.replace(/\[\d+]/g, '') === path.replace(/\[\d+]/g, '') && !this.branchesConflict(j.path, path);
             });
         }
         if (!join && options?.matchPopulateJoins && options?.ignoreBranching) {
             join = joins.find(j => {
-                return j.path?.replace(/\[\d+]|\[populate]/g, '') === path.replace(/\[\d+]|\[populate]/g, '');
+                return (j.path?.replace(/\[\d+]|\[populate]/g, '') === path.replace(/\[\d+]|\[populate]/g, '') &&
+                    !this.branchesConflict(j.path, path));
             });
         }
         if (!join && options?.matchPopulateJoins) {
@@ -1005,6 +1014,12 @@ export class QueryBuilder {
         }
         return join;
     }
+    /** Branch-insensitive path matching still must not cross branches — segments with different explicit branch markers (e.g. `Mobile[0]` vs `Mobile[1]`) belong to sibling joins. */
+    branchesConflict(path1, path2) {
+        const markers = (path) => path.split('.').map(segment => /\[(\d+)]/.exec(segment)?.[1]);
+        const markers2 = markers(path2);
+        return markers(path1).some((m, idx) => m != null && markers2[idx] != null && m !== markers2[idx]);
+    }
     /**
      * @internal
      */
@@ -1410,19 +1425,19 @@ export class QueryBuilder {
                 prop.targetMeta = field.mainAlias.meta;
                 field = field.getNativeQuery();
             }
-            if (isRaw(field)) {
-                field = this.platform.formatQuery(field.sql, field.params);
-            }
             const key = `${this.alias}.${prop.name}#${alias}`;
-            this.#state.joins[key] = {
-                prop,
-                alias,
-                type,
-                cond,
-                schema,
-                subquery: field.toString(),
-                ownerAlias: this.alias,
-            };
+            const join = { prop, alias, type, cond, schema, ownerAlias: this.alias };
+            // `sql.ref('...')` is a bare table/CTE reference, join it by name instead of wrapping it as a sub-query
+            if (isRaw(field) && field.sql === '??' && field.params.length === 1) {
+                join.table = String(field.params[0]);
+            }
+            else {
+                if (isRaw(field)) {
+                    field = this.platform.formatQuery(field.sql, field.params);
+                }
+                join.subquery = field.toString();
+            }
+            this.#state.joins[key] = join;
             return { prop, key };
         }
         if (!subquery && type.includes('lateral')) {
@@ -1483,9 +1498,31 @@ export class QueryBuilder {
             this.#state.joins[aliasedName] = this.helper.joinManyToOneReference(prop, ownerAlias, alias, type, cond, schema);
             this.#state.joins[aliasedName].path ??= path;
         }
+        if (prop.targetMeta.inheritanceType === 'tpt' && prop.targetMeta.tptParent) {
+            this.addTPTParentJoins(prop.targetMeta, alias, path);
+        }
         this.nestReferencedJoins(this.#state.joins[aliasedName]);
         return { prop, key: aliasedName };
     }
+    /**
+     * Walks the TPT inheritance chain of `leafMeta` and INNER JOINs each parent table.
+     * Registers the parent aliases in `state.tptAlias` so column resolution finds them
+     * when conditions reference parent-table columns.
+     * @internal
+     */
+    addTPTParentJoins(leafMeta, leafAlias, basePath) {
+        let childAlias = leafAlias;
+        let childMeta = leafMeta;
+        while (childMeta.tptParent) {
+            const parentMeta = childMeta.tptParent;
+            const parentAlias = this.getNextAlias(parentMeta.className);
+            this.createAlias(parentMeta.class, parentAlias);
+            this.#state.tptAlias[`${leafAlias}:${parentMeta.className}`] = parentAlias;
+            this.addPropertyJoin(childMeta.tptParentProp, childAlias, parentAlias, JoinType.innerJoin, `${basePath}.[tpt]${childMeta.className}`);
+            childAlias = parentAlias;
+            childMeta = parentMeta;
+        }
+    }
     prepareFields(fields, type = 'where', schema) {
         const ret = [];
         const getFieldName = (name, customAlias) => {
@@ -2038,6 +2075,13 @@ export class QueryBuilder {
         for (const k of Object.keys(cond)) {
             if (Utils.isOperator(k)) {
                 if (Array.isArray(cond[k])) {
+                    if (k === '$or' && !this.canDistributeOrBranches(cond[k], joins)) {
+                        // entity filters have no other sink, so their `$or` is kept intact on the outermost targeted join instead
+                        if (filter) {
+                            this.mergeFilterOrCondition(cond[k], joins);
+                        }
+                        continue;
+                    }
                     cond[k].forEach((c) => this.mergeOnConditions(joins, c, filter, k));
                 }
                 /* v8 ignore next */
@@ -2068,8 +2112,66 @@ export class QueryBuilder {
                 else {
                     join.cond = { ...join.cond, [k]: cond[k] };
                 }
+                this.nestReferencedJoins(join);
+            }
+        }
+    }
+    /**
+     * `$or` branches can be moved to a join's `on` clause only when they all target that same join
+     * and stay flat — a partial `$or` in the `on` clause would drop rows matching a sibling branch,
+     * and nested operators cannot be preserved inside a distributed disjunction, as `mergeOnConditions`
+     * would flatten them into `and` conjuncts.
+     */
+    canDistributeOrBranches(branches, joins) {
+        const aliases = this.getOrBranchAliases(branches);
+        const targeted = joins.filter(j => aliases.has(j.alias));
+        const flat = branches.every(branch => Object.keys(branch).every(k => !Utils.isOperator(k)));
+        return aliases.size === 1 && targeted.length === 1 && flat;
+    }
+    getOrBranchAliases(branches) {
+        const aliases = new Set();
+        const collectAliases = (cond) => {
+            for (const k of Object.keys(cond)) {
+                if (Utils.isOperator(k)) {
+                    Utils.asArray(cond[k]).forEach((c) => collectAliases(c));
+                }
+                else {
+                    aliases.add(this.helper.splitField(k)[0]);
+                }
+            }
+        };
+        branches.forEach(collectAliases);
+        return aliases;
+    }
+    /**
+     * An entity filter's `$or` that cannot be distributed is applied intact to the `on` clause of the
+     * outermost join common to all targeted joins, nesting the targeted joins under it so the clause
+     * can reference their aliases.
+     */
+    mergeFilterOrCondition(branches, joins) {
+        const aliases = this.getOrBranchAliases(branches);
+        const chainOf = (join) => {
+            const parent = joins.find(j => j.alias === join.ownerAlias);
+            return parent ? [join, ...chainOf(parent)] : [join];
+        };
+        // chains go from each targeted join up to its root, so the first join present in all of them is the outermost common one
+        const chains = joins.filter(j => aliases.has(j.alias)).map(chainOf);
+        const anchor = chains[0]?.find(a => chains.every(chain => chain.includes(a)));
+        /* v8 ignore next 3 */
+        if (!anchor) {
+            return;
+        }
+        for (const chain of chains) {
+            // nest the chain below the anchor, so the anchor's `on` clause can reference the nested aliases
+            for (let i = 0; chain[i] !== anchor; i++) {
+                const nested = (chain[i + 1].nested ??= new Set());
+                if (!nested.has(chain[i])) {
+                    chain[i].type = chain[i].type === JoinType.innerJoin ? JoinType.nestedInnerJoin : JoinType.nestedLeftJoin;
+                    nested.add(chain[i]);
+                }
             }
         }
+        anchor.cond = anchor.cond.$or ? { $and: [anchor.cond, { $or: branches }] } : { ...anchor.cond, $or: branches };
     }
     /**
      * When adding an inner join on a left joined relation, we need to nest them,

package/query/QueryBuilderHelper.d.ts

@@ -14,6 +14,11 @@ export declare class QueryBuilderHelper {
      * Returns the main alias if not a TPT property or if the property belongs to the main entity.
      */
     getTPTAliasForProperty(propName: string, defaultAlias: string): string;
+    /**
+     * Replaces `ALIAS_REPLACEMENT` placeholders, resolving column-qualified ones via
+     * `getTPTAliasForProperty()` so TPT inherited columns map to their owning table.
+     */
+    replaceAliases(sql: string, alias?: string): string;
     mapper(field: string | Raw | RawQueryFragmentSymbol, type?: QueryType): string;
     mapper(field: string | Raw | RawQueryFragmentSymbol, type?: QueryType, value?: any, alias?: string | null, schema?: string): string;
     processData(data: Dictionary, convertCustomTypes: boolean, multi?: boolean): any;

package/query/QueryBuilderHelper.js

@@ -1,5 +1,7 @@
 import { ALIAS_REPLACEMENT, ALIAS_REPLACEMENT_RE, ArrayType, JsonType, inspect, isRaw, LockMode, OptimisticLockError, QueryOperator, QueryOrderNumeric, raw, Raw, QueryHelper, ReferenceKind, Utils, ValidationError, } from '@mikro-orm/core';
 import { EMBEDDABLE_ARRAY_OPS, JoinType, QueryType } from './enums.js';
+/** Captures the column name that follows the alias placeholder. */
+const QUALIFYING_ALIAS_RE = new RegExp(ALIAS_REPLACEMENT_RE + '(?=["\'`\\]]*\\.["\'`\\[]?([\\w$]+))', 'g');
 /**
  * @internal
  */
@@ -49,6 +51,15 @@ export class QueryBuilderHelper {
         // Property not found in hierarchy, return default alias
         return defaultAlias;
     }
+    /**
+     * Replaces `ALIAS_REPLACEMENT` placeholders, resolving column-qualified ones via
+     * `getTPTAliasForProperty()` so TPT inherited columns map to their owning table.
+     */
+    replaceAliases(sql, alias = this.#alias) {
+        return sql
+            .replace(QUALIFYING_ALIAS_RE, (_, column) => this.getTPTAliasForProperty(column, alias))
+            .replaceAll(ALIAS_REPLACEMENT, alias);
+    }
     mapper(field, type = QueryType.SELECT, value, alias, schema) {
         if (isRaw(field)) {
             return raw(field.sql, field.params);
@@ -97,7 +108,6 @@ export class QueryBuilderHelper {
         // Only apply TPT resolution when `a` is an actual table alias (in aliasMap),
         // not when it's an embedded property name like 'profile1.identity.links'
         const isTableAlias = !!this.#aliasMap[a];
-        const baseAlias = isTableAlias ? a : this.#alias;
         const resolvedAlias = isTableAlias ? this.getTPTAliasForProperty(prop?.name ?? f, a) : this.#alias;
         const aliasPrefix = isTableNameAliasRequired ? resolvedAlias + '.' : '';
         const fkIdx2 = prop?.fieldNames.findIndex(name => name === f) ?? -1;
@@ -249,7 +259,13 @@ export class QueryBuilderHelper {
         }[join.type] ?? join.type;
         const conditions = [];
         const params = [];
-        schema = join.schema === '*' ? schema : (join.schema ?? schemaOverride);
+        if (join.prop.name === '__subquery__') {
+            // bare table/CTE references (`sql.ref()` joins) keep their literal name, only an explicit schema applies
+            schema = join.schema === '*' ? undefined : join.schema;
+        }
+        else {
+            schema = join.schema === '*' ? schema : (join.schema ?? schemaOverride);
+        }
         if (schema && schema !== this.#platform.getDefaultSchemaName()) {
             table = `${schema}.${table}`;
         }
@@ -465,7 +481,7 @@ export class QueryBuilderHelper {
         const op = cond[key] === null ? 'is' : '=';
         if (Raw.isKnownFragmentSymbol(key)) {
             const raw = Raw.getKnownFragment(key);
-            const sql = raw.sql.replaceAll(ALIAS_REPLACEMENT, this.#alias);
+            const sql = this.replaceAliases(raw.sql);
             const value = Utils.asArray(cond[key]);
             params.push(...raw.params);
             if (value.length > 0) {
@@ -517,6 +533,11 @@ export class QueryBuilderHelper {
         const replacement = this.getOperatorReplacement(op, value);
         const rawField = Raw.isKnownFragmentSymbol(key);
         const fields = rawField ? [key] : Utils.splitPrimaryKeys(key);
+        // a raw key's arity is opaque, so the row-value form is detected from the payload instead
+        const rowValues = rawField &&
+            ['$in', '$nin'].includes(op) &&
+            Array.isArray(value[op]) &&
+            value[op].every((v) => Array.isArray(v));
         if (fields.length > 1 && Array.isArray(value[op])) {
             const singleTuple = !value[op].every((v) => Array.isArray(v));
             if (!this.#platform.allowsComparingTuples()) {
@@ -576,7 +597,7 @@ export class QueryBuilderHelper {
             if (opValueIsRaw || typeof opValue?.toRaw === 'function') {
                 const query = opValueIsRaw ? opValue : opValue.toRaw();
                 const mappedKey = this.mapper(key, type, query, null);
-                let sql = query.sql.replaceAll(ALIAS_REPLACEMENT, this.#alias);
+                let sql = this.replaceAliases(query.sql);
                 if (['$in', '$nin'].includes(op)) {
                     sql = `(${sql})`;
                 }
@@ -585,15 +606,15 @@ export class QueryBuilderHelper {
             }
             else {
                 const mappedKey = this.mapper(key, type, opValue, null);
-                const val = this.getValueReplacement(fields, opValue, params, op, prop);
+                const val = this.getValueReplacement(fields, opValue, params, op, prop, rowValues);
                 parts.push(`${this.#platform.quoteIdentifier(mappedKey)} ${replacement} ${val}`);
             }
         }
         return { sql: parts.join(' and '), params };
     }
-    getValueReplacement(fields, value, params, key, prop) {
+    getValueReplacement(fields, value, params, key, prop, rowValues = false) {
         if (Array.isArray(value)) {
-            if (fields.length > 1) {
+            if (fields.length > 1 || rowValues) {
                 const tmp = [];
                 for (const field of value) {
                     tmp.push(`(${field.map(() => '?').join(', ')})`);
@@ -742,7 +763,7 @@ export class QueryBuilderHelper {
     }
     updateVersionProperty(qb, data) {
         const meta = this.#metadata.find(this.#entityName);
-        if (!meta?.versionProperty || meta.versionProperty in data) {
+        if (!meta?.ownsVersionProperty() || meta.versionProperty in data) {
             return;
         }
         const versionProperty = meta.properties[meta.versionProperty];

package/schema/SchemaComparator.js

@@ -963,13 +963,13 @@ export class SchemaComparator {
     }
     diffTrigger(from, to) {
         // Raw DDL expression cannot be meaningfully compared to introspected
-        // trigger metadata, so skip diffing when the metadata side uses it.
-        if (to.expression) {
+        // trigger metadata, so it needs special handling when either side uses it.
+        if (from.expression || to.expression) {
             // Both sides have expression — compare the raw DDL directly
-            if (from.expression) {
+            if (from.expression && to.expression) {
                 return this.diffExpression(from.expression, to.expression);
             }
-            // Only metadata side has expression — the raw DDL cannot be compared to
+            // Only one side has expression — the raw DDL cannot be compared to
             // introspected metadata. Changes to the expression value won't be detected;
             // drop and recreate the trigger manually to apply expression changes.
             return false;

package/typings.d.ts

@@ -277,6 +277,8 @@ export interface IQueryBuilder<T> {
     with(name: string, query: AnyQueryBuilder | NativeQueryBuilder | RawQueryFragment, options?: CteOptions): this;
     withRecursive(name: string, query: AnyQueryBuilder | NativeQueryBuilder | RawQueryFragment, options?: CteOptions): this;
     scheduleFilterCheck(path: string): void;
+    /** @internal */
+    ensureTPTJoins(): void;
     withSchema(schema: string): this;
 }
 export interface ICriteriaNodeProcessOptions {