@mikro-orm/sql 7.0.0-rc.2 → 7.0.0

package/AbstractSqlDriver.js

@@ -37,7 +37,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
             throw new Error('Collation option for SQL drivers must be a string (collation name). Use a CollationOptions object only with MongoDB.');
         }
         if (options.indexHint != null && typeof options.indexHint !== 'string') {
-            throw new Error('indexHint for SQL drivers must be a string (e.g. \'force index(my_index)\'). Use an object only with MongoDB.');
+            throw new Error("indexHint for SQL drivers must be a string (e.g. 'force index(my_index)'). Use an object only with MongoDB.");
         }
     }
     createEntityManager(useContext) {
@@ -60,7 +60,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
         this.validateSqlOptions(options);
         const { first, last, before, after } = options;
         const isCursorPagination = [first, last, before, after].some(v => v != null);
-        qb.__populateWhere = options._populateWhere;
+        qb.state.resolvedPopulateWhere = options._populateWhere;
         qb.select(fields)
             // only add populateWhere if we are populate-joining, as this will be used to add `on` conditions
             .populate(populate, joinedProps.length > 0 ? populateWhere : undefined, joinedProps.length > 0 ? options.populateFilter : undefined)
@@ -95,6 +95,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (meta.virtual) {
             return this.findVirtual(entityName, where, options);
         }
+        if (options.unionWhere?.length) {
+            where = await this.applyUnionWhere(meta, where, options);
+        }
         const qb = await this.createQueryBuilderFromOptions(meta, where, options);
         const result = await this.rethrow(qb.execute('all'));
         if (options.last && !options.first) {
@@ -197,7 +200,8 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (type === QueryType.COUNT) {
             native.clear('select').clear('limit').clear('offset').count();
         }
-        native.from(raw(`(${expression}) as ${this.platform.quoteIdentifier(qb.alias)}`));
+        const asKeyword = this.platform.usesAsKeyword() ? ' as ' : ' ';
+        native.from(raw(`(${expression})${asKeyword}${this.platform.quoteIdentifier(qb.alias)}`));
         const query = native.compile();
         const res = await this.execute(query.sql, query.params, 'all', options.ctx);
         if (type === QueryType.COUNT) {
@@ -212,7 +216,8 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const qb = await this.createQueryBuilderFromOptions(meta, where, this.forceBalancedStrategy(options));
         qb.unsetFlag(QueryFlag.DISABLE_PAGINATE);
         const native = qb.getNativeQuery(false);
-        native.from(raw(`(${expression}) as ${this.platform.quoteIdentifier(qb.alias)}`));
+        const asKeyword = this.platform.usesAsKeyword() ? ' as ' : ' ';
+        native.from(raw(`(${expression})${asKeyword}${this.platform.quoteIdentifier(qb.alias)}`));
         const query = native.compile();
         const connectionType = this.resolveConnectionType({ ctx: options.ctx, connectionType: options.connectionType });
         const res = this.getConnection(connectionType).stream(query.sql, query.params, options.ctx, options.loggerContext);
@@ -265,7 +270,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
      * and need to be renamed back to `column_name` for the result mapper to work.
      */
     mapTPTColumns(result, meta, qb) {
-        const tptAliases = qb._tptAlias;
+        const tptAliases = qb.state.tptAlias;
         // Walk up the TPT hierarchy
         let parentMeta = meta.tptParent;
         while (parentMeta) {
@@ -297,7 +302,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
             }
             // Polymorphic to-one: iterate targets, find the matching one, build entity from its columns.
             // Skip :ref hints — no JOINs were created, so the FK reference is already set by the result mapper.
-            if (prop.polymorphic && prop.polymorphTargets?.length && !ref && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+            if (prop.polymorphic &&
+                prop.polymorphTargets?.length &&
+                !ref &&
+                [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
                 const basePath = parentJoinPath ? `${parentJoinPath}.${prop.name}` : `${meta.name}.${prop.name}`;
                 const pathPrefix = !parentJoinPath ? '[populate]' : '';
                 let matched = false;
@@ -306,16 +314,22 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     const relationAlias = qb.getAliasForJoinPath(targetPath, { matchPopulateJoins: true });
                     const meta2 = targetMeta;
                     const targetProps = meta2.props.filter(p => this.platform.shouldHaveColumn(p, hint.children || []));
-                    const hasPK = meta2.getPrimaryProps().every(pk => pk.fieldNames.every(name => root[`${relationAlias}__${name}`] != null));
+                    const hasPK = meta2
+                        .getPrimaryProps()
+                        .every(pk => pk.fieldNames.every(name => root[`${relationAlias}__${name}`] != null));
                     if (hasPK && !matched) {
                         matched = true;
-                        let relationPojo = {};
+                        const relationPojo = {};
                         const tz = this.platform.getTimezone();
                         for (const p of targetProps) {
                             this.mapJoinedProp(relationPojo, p, relationAlias, root, tz, meta2);
                         }
                         // Inject the entity class constructor so that the factory creates the correct type
-                        Object.defineProperty(relationPojo, 'constructor', { value: meta2.class, enumerable: false, configurable: true });
+                        Object.defineProperty(relationPojo, 'constructor', {
+                            value: meta2.class,
+                            enumerable: false,
+                            configurable: true,
+                        });
                         result[prop.name] = relationPojo;
                         const populateChildren = hint.children || [];
                         this.mapJoinedProps(relationPojo, meta2, populateChildren, qb, root, map, targetPath);
@@ -366,7 +380,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 return;
             }
             const mapToPk = !hint.dataOnly && !!(ref || prop.mapToPk);
-            const targetProps = mapToPk ? meta2.getPrimaryProps() : meta2.props.filter(prop => this.platform.shouldHaveColumn(prop, hint.children || []));
+            const targetProps = mapToPk
+                ? meta2.getPrimaryProps()
+                : meta2.props.filter(prop => this.platform.shouldHaveColumn(prop, hint.children || []));
             // If the primary key value for the relation is null, we know we haven't joined to anything
             // and therefore we don't return any record (since all values would be null)
             const hasPK = meta2.getPrimaryProps().every(pk => pk.fieldNames.every(name => {
@@ -459,7 +475,12 @@ export class AbstractSqlDriver extends DatabaseDriver {
         else if (prop.runtimeType === 'Date') {
             const alias = `${relationAlias}__${prop.fieldNames[0]}`;
             const value = root[alias];
-            if (tz && tz !== 'local' && typeof value === 'string' && !value.includes('+') && value.lastIndexOf('-') < 11 && !value.endsWith('Z')) {
+            if (tz &&
+                tz !== 'local' &&
+                typeof value === 'string' &&
+                !value.includes('+') &&
+                value.lastIndexOf('-') < 11 &&
+                !value.endsWith('Z')) {
                 relationPojo[prop.name] = this.platform.parseDate(value + tz);
             }
             else if (['string', 'number'].includes(typeof value)) {
@@ -475,10 +496,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
             if (prop.kind === ReferenceKind.EMBEDDED && (prop.object || meta.embeddable)) {
                 const item = parseJsonSafe(relationPojo[prop.name]);
                 if (Array.isArray(item)) {
-                    relationPojo[prop.name] = item.map(row => (row == null ? row : this.comparator.mapResult(prop.targetMeta, row)));
+                    relationPojo[prop.name] = item.map(row => row == null ? row : this.comparator.mapResult(prop.targetMeta, row));
                 }
                 else {
-                    relationPojo[prop.name] = item == null ? item : this.comparator.mapResult(prop.targetMeta, item);
+                    relationPojo[prop.name] =
+                        item == null ? item : this.comparator.mapResult(prop.targetMeta, item);
                 }
             }
         }
@@ -493,6 +515,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (meta.virtual) {
             return this.countVirtual(entityName, where, options);
         }
+        if (options.unionWhere?.length) {
+            where = await this.applyUnionWhere(meta, where, options);
+        }
         options = { populate: [], ...options };
         const populate = options.populate;
         const joinedProps = this.joinedProps(meta, populate, options);
@@ -503,7 +528,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
             this.buildFields(meta, populate, joinedProps, qb, qb.alias, options, schema);
         }
         this.validateSqlOptions(options);
-        qb.__populateWhere = options._populateWhere;
+        qb.state.resolvedPopulateWhere = options._populateWhere;
         qb.indexHint(options.indexHint)
             .collation(options.collation)
             .comment(options.comments)
@@ -533,7 +558,12 @@ export class AbstractSqlDriver extends DatabaseDriver {
         else {
             /* v8 ignore next */
             res.insertId = data[meta.primaryKeys[0]] ?? res.insertId ?? res.row[meta.primaryKeys[0]];
-            pk = [res.insertId];
+            if (options.convertCustomTypes && meta?.getPrimaryProp().customType) {
+                pk = [meta.getPrimaryProp().customType.convertToDatabaseValue(res.insertId, this.platform)];
+            }
+            else {
+                pk = [res.insertId];
+            }
         }
         await this.processManyToMany(meta, pk, collections, false, options);
         return res;
@@ -557,13 +587,19 @@ export class AbstractSqlDriver extends DatabaseDriver {
         }
         const tableName = this.getTableName(meta, options);
         let sql = `insert into ${tableName} `;
-        sql += fields.length > 0 ? '(' + fields.map(k => this.platform.quoteIdentifier(k)).join(', ') + ')' : `(${this.platform.quoteIdentifier(pks[0])})`;
+        sql +=
+            fields.length > 0
+                ? '(' + fields.map(k => this.platform.quoteIdentifier(k)).join(', ') + ')'
+                : `(${this.platform.quoteIdentifier(pks[0])})`;
         if (this.platform.usesOutputStatement()) {
             const returningProps = this.getTableProps(meta)
                 .filter(prop => (prop.persist !== false && prop.defaultRaw) || prop.autoincrement || prop.generated)
                 .filter(prop => !(prop.name in data[0]) || isRaw(data[0][prop.name]));
             const returningFields = Utils.flatten(returningProps.map(prop => prop.fieldNames));
-            sql += returningFields.length > 0 ? ` output ${returningFields.map(field => 'inserted.' + this.platform.quoteIdentifier(field)).join(', ')}` : '';
+            sql +=
+                returningFields.length > 0
+                    ? ` output ${returningFields.map(field => 'inserted.' + this.platform.quoteIdentifier(field)).join(', ')}`
+                    : '';
         }
         if (fields.length > 0 || this.platform.usesDefaultKeyword()) {
             sql += ' values ';
@@ -650,7 +686,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     else {
                         const field = prop.fieldNames[0];
                         if (!duplicates.includes(field) || !usedDups.includes(field)) {
-                            if (prop.customType && !prop.object && 'convertToDatabaseValueSQL' in prop.customType && row[prop.name] != null && !isRaw(row[prop.name])) {
+                            if (prop.customType &&
+                                !prop.object &&
+                                'convertToDatabaseValueSQL' in prop.customType &&
+                                row[prop.name] != null &&
+                                !isRaw(row[prop.name])) {
                                 keys.push(prop.customType.convertToDatabaseValueSQL('?', this.platform));
                             }
                             else {
@@ -671,7 +711,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 .filter(prop => !(prop.name in data[0]) || isRaw(data[0][prop.name]));
             const returningFields = Utils.flatten(returningProps.map(prop => prop.fieldNames));
             /* v8 ignore next */
-            sql += returningFields.length > 0 ? ` returning ${returningFields.map(field => this.platform.quoteIdentifier(field)).join(', ')}` : '';
+            sql +=
+                returningFields.length > 0
+                    ? ` returning ${returningFields.map(field => this.platform.quoteIdentifier(field)).join(', ')}`
+                    : '';
         }
         if (transform) {
             sql = transform(sql);
@@ -704,11 +747,15 @@ export class AbstractSqlDriver extends DatabaseDriver {
             /* v8 ignore next */
             where = { [meta.primaryKeys[0] ?? pks[0]]: where };
         }
+        if (!options.upsert && options.unionWhere?.length) {
+            where = (await this.applyUnionWhere(meta, where, options, true));
+        }
         if (Utils.hasObjectKeys(data)) {
             const qb = this.createQueryBuilder(entityName, options.ctx, 'write', options.convertCustomTypes, options.loggerContext).withSchema(this.getSchemaName(meta, options));
             if (options.upsert) {
                 /* v8 ignore next */
-                const uniqueFields = options.onConflictFields ?? (Utils.isPlainObject(where) ? Utils.keys(where) : meta.primaryKeys);
+                const uniqueFields = options.onConflictFields ??
+                    (Utils.isPlainObject(where) ? Utils.keys(where) : meta.primaryKeys);
                 const returning = getOnConflictReturningFields(meta, data, uniqueFields, options);
                 qb.insert(data)
                     .onConflict(uniqueFields)
@@ -728,7 +775,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 qb.update(data).where(where);
                 // reload generated columns and version fields
                 const returning = [];
-                meta.props.filter(prop => (prop.generated && !prop.primary) || prop.version).forEach(prop => returning.push(prop.name));
+                meta.props
+                    .filter(prop => (prop.generated && !prop.primary) || prop.version)
+                    .forEach(prop => returning.push(prop.name));
                 qb.returning(returning);
             }
             res = await this.rethrow(qb.execute('run', false));
@@ -738,13 +787,15 @@ export class AbstractSqlDriver extends DatabaseDriver {
         await this.processManyToMany(meta, pk, collections, true, options);
         return res;
     }
-    async nativeUpdateMany(entityName, where, data, options = {}) {
+    async nativeUpdateMany(entityName, where, data, options = {}, transform) {
         options.processCollections ??= true;
         options.convertCustomTypes ??= true;
         const meta = this.metadata.get(entityName);
         if (options.upsert) {
             const uniqueFields = options.onConflictFields ??
-                (Utils.isPlainObject(where[0]) ? Object.keys(where[0]).flatMap(key => Utils.splitPrimaryKeys(key)) : meta.primaryKeys);
+                (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));
             const returning = getOnConflictReturningFields(meta, data[0], uniqueFields, options);
             qb.insert(data)
@@ -815,7 +866,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     if (key in data[idx]) {
                         const pks = Utils.getOrderedPrimaryKeys(cond, meta);
                         sql += ` when (${pkCond}) then `;
-                        if (prop.customType && !prop.object && 'convertToDatabaseValueSQL' in prop.customType && data[idx][prop.name] != null && !isRaw(data[idx][key])) {
+                        if (prop.customType &&
+                            !prop.object &&
+                            'convertToDatabaseValueSQL' in prop.customType &&
+                            data[idx][prop.name] != null &&
+                            !isRaw(data[idx][key])) {
                             sql += prop.customType.convertToDatabaseValueSQL('?', this.platform);
                         }
                         else {
@@ -844,7 +899,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
         sql = sql.substring(0, sql.length - 2) + ' where ';
         const pkProps = meta.primaryKeys.concat(...meta.concurrencyCheckKeys);
         const pks = Utils.flatten(pkProps.map(pk => meta.properties[pk].fieldNames));
-        sql += pks.length > 1 ? `(${pks.map(pk => `${this.platform.quoteIdentifier(pk)}`).join(', ')})` : this.platform.quoteIdentifier(pks[0]);
+        sql +=
+            pks.length > 1
+                ? `(${pks.map(pk => this.platform.quoteIdentifier(pk)).join(', ')})`
+                : this.platform.quoteIdentifier(pks[0]);
         const conds = where.map(cond => {
             if (Utils.isPlainObject(cond) && Utils.getObjectKeysSize(cond) === 1) {
                 cond = Object.values(cond)[0];
@@ -867,7 +925,13 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (this.platform.usesReturningStatement() && returning.size > 0) {
             const returningFields = Utils.flatten([...returning].map(prop => meta.properties[prop].fieldNames));
             /* v8 ignore next */
-            sql += returningFields.length > 0 ? ` returning ${returningFields.map(field => this.platform.quoteIdentifier(field)).join(', ')}` : '';
+            sql +=
+                returningFields.length > 0
+                    ? ` returning ${returningFields.map(field => this.platform.quoteIdentifier(field)).join(', ')}`
+                    : '';
+        }
+        if (transform) {
+            sql = transform(sql, params);
         }
         const res = await this.rethrow(this.execute(sql, params, 'run', options.ctx, options.loggerContext));
         for (let i = 0; i < collections.length; i++) {
@@ -881,6 +945,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (Utils.isPrimaryKey(where) && pks.length === 1) {
             where = { [pks[0]]: where };
         }
+        if (options.unionWhere?.length) {
+            where = await this.applyUnionWhere(meta, where, options, true);
+        }
         const qb = this.createQueryBuilder(entityName, options.ctx, 'write', false, options.loggerContext)
             .delete(where)
             .withSchema(this.getSchemaName(meta, options));
@@ -935,7 +1002,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 const qb = this.createQueryBuilder(coll.property.targetMeta.class, options?.ctx, 'write').withSchema(this.getSchemaName(meta, options));
                 if (coll.getSnapshot() === undefined) {
                     if (coll.property.orphanRemoval) {
-                        const query = qb.delete({ [coll.property.mappedBy]: pks }).andWhere({ [cols.join(Utils.PK_SEPARATOR)]: { $nin: insertDiff } });
+                        const query = qb
+                            .delete({ [coll.property.mappedBy]: pks })
+                            .andWhere({ [cols.join(Utils.PK_SEPARATOR)]: { $nin: insertDiff } });
                         await this.rethrow(query.execute());
                         continue;
                     }
@@ -947,7 +1016,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     continue;
                 }
                 /* v8 ignore next */
-                const query = qb.update({ [coll.property.mappedBy]: pks }).where({ [cols.join(Utils.PK_SEPARATOR)]: { $in: insertDiff } });
+                const query = qb
+                    .update({ [coll.property.mappedBy]: pks })
+                    .where({ [cols.join(Utils.PK_SEPARATOR)]: { $in: insertDiff } });
                 await this.rethrow(query.execute());
                 continue;
             }
@@ -960,7 +1031,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 else {
                     const targetMeta = coll.property.targetMeta;
                     const targetSchema = (coll[0] ?? snap?.[0]) && helper(coll[0] ?? snap?.[0]).getSchema();
-                    schema = targetMeta.schema === '*' ? (options?.schema ?? targetSchema ?? this.config.get('schema')) : targetMeta.schema;
+                    schema =
+                        targetMeta.schema === '*'
+                            ? (options?.schema ?? targetSchema ?? this.config.get('schema'))
+                            : targetMeta.schema;
                 }
             }
             else if (schema == null) {
@@ -986,8 +1060,17 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const pivotProp1 = pivotMeta.relations[prop.owner ? 1 : 0];
         const pivotProp2 = pivotMeta.relations[prop.owner ? 0 : 1];
         const ownerMeta = pivotProp2.targetMeta;
+        // The pivot query builder doesn't convert custom types, so we need to manually
+        // convert owner PKs to DB format for the query and convert result FKs back to
+        // JS format for consistent key hashing in buildPivotResultMap.
+        const pkProp = ownerMeta.properties[ownerMeta.primaryKeys[0]];
+        const needsConversion = pkProp?.customType?.ensureComparable(ownerMeta, pkProp) && !ownerMeta.compositePK;
+        let ownerPks = ownerMeta.compositePK ? owners : owners.map(o => o[0]);
+        if (needsConversion) {
+            ownerPks = ownerPks.map(v => pkProp.customType.convertToDatabaseValue(v, this.platform, { mode: 'query' }));
+        }
         const cond = {
-            [pivotProp2.name]: { $in: ownerMeta.compositePK ? owners : owners.map(o => o[0]) },
+            [pivotProp2.name]: { $in: ownerPks },
         };
         if (!Utils.isEmpty(where)) {
             cond[pivotProp1.name] = { ...where };
@@ -997,7 +1080,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const populate = this.autoJoinOneToOneOwner(prop.targetMeta, options?.populate ?? [], options?.fields);
         const childFields = !Utils.isEmpty(options?.fields) ? options.fields.map(f => `${pivotProp1.name}.${f}`) : [];
         const childExclude = !Utils.isEmpty(options?.exclude) ? options.exclude.map(f => `${pivotProp1.name}.${f}`) : [];
-        const fields = pivotJoin ? [pivotProp1.name, pivotProp2.name] : [pivotProp1.name, pivotProp2.name, ...childFields];
+        const fields = pivotJoin
+            ? [pivotProp1.name, pivotProp2.name]
+            : [pivotProp1.name, pivotProp2.name, ...childFields];
         const res = await this.find(pivotMeta.class, where, {
             ctx,
             ...options,
@@ -1018,6 +1103,16 @@ export class AbstractSqlDriver extends DatabaseDriver {
             _populateWhere: 'infer',
             populateFilter: this.wrapPopulateFilter(options, pivotProp2.name),
         });
+        // Convert result FK values back to JS format so key hashing
+        // in buildPivotResultMap is consistent with the owner keys.
+        if (needsConversion) {
+            for (const item of res) {
+                const fk = item[pivotProp2.name];
+                if (fk != null) {
+                    item[pivotProp2.name] = pkProp.customType.convertToJSValue(fk, this.platform);
+                }
+            }
+        }
         return this.buildPivotResultMap(owners, res, pivotProp2.name, pivotProp1.name);
     }
     /**
@@ -1050,7 +1145,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const populateField = pivotJoin ? `${inverseProp.name}:ref` : inverseProp.name;
         const populate = this.autoJoinOneToOneOwner(targetMeta, options?.populate ?? [], options?.fields);
         const childFields = !Utils.isEmpty(options?.fields) ? options.fields.map(f => `${inverseProp.name}.${f}`) : [];
-        const childExclude = !Utils.isEmpty(options?.exclude) ? options.exclude.map(f => `${inverseProp.name}.${f}`) : [];
+        const childExclude = !Utils.isEmpty(options?.exclude)
+            ? options.exclude.map(f => `${inverseProp.name}.${f}`)
+            : [];
         const fields = pivotJoin
             ? [inverseProp.name, prop.discriminator, prop.discriminatorColumn]
             : [inverseProp.name, prop.discriminator, prop.discriminatorColumn, ...childFields];
@@ -1060,7 +1157,15 @@ export class AbstractSqlDriver extends DatabaseDriver {
             fields,
             exclude: childExclude,
             orderBy: this.getPivotOrderBy(prop, inverseProp, orderBy, options?.orderBy),
-            populate: [{ field: populateField, strategy: LoadStrategy.JOINED, joinType: JoinType.innerJoin, children: populate, dataOnly: inverseProp.mapToPk && !pivotJoin }],
+            populate: [
+                {
+                    field: populateField,
+                    strategy: LoadStrategy.JOINED,
+                    joinType: JoinType.innerJoin,
+                    children: populate,
+                    dataOnly: inverseProp.mapToPk && !pivotJoin,
+                },
+            ],
             populateWhere: undefined,
             // @ts-ignore
             _populateWhere: 'infer',
@@ -1092,7 +1197,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const populateField = ownerRelationName;
         const populate = this.autoJoinOneToOneOwner(targetMeta, options?.populate ?? [], options?.fields);
         const childFields = !Utils.isEmpty(options?.fields) ? options.fields.map(f => `${ownerRelationName}.${f}`) : [];
-        const childExclude = !Utils.isEmpty(options?.exclude) ? options.exclude.map(f => `${ownerRelationName}.${f}`) : [];
+        const childExclude = !Utils.isEmpty(options?.exclude)
+            ? options.exclude.map(f => `${ownerRelationName}.${f}`)
+            : [];
         const fields = [ownerRelationName, tagProp.name, prop.discriminatorColumn, ...childFields];
         const res = await this.find(pivotMeta.class, cond, {
             ctx,
@@ -1100,7 +1207,14 @@ export class AbstractSqlDriver extends DatabaseDriver {
             fields,
             exclude: childExclude,
             orderBy: this.getPivotOrderBy(prop, ownerProp, orderBy, options?.orderBy),
-            populate: [{ field: populateField, strategy: LoadStrategy.JOINED, joinType: JoinType.innerJoin, children: populate }],
+            populate: [
+                {
+                    field: populateField,
+                    strategy: LoadStrategy.JOINED,
+                    joinType: JoinType.innerJoin,
+                    children: populate,
+                },
+            ],
             populateWhere: undefined,
             // @ts-ignore
             _populateWhere: 'infer',
@@ -1179,7 +1293,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
         }
         const relationsToPopulate = populate.map(({ field }) => field.split(':')[0]);
         const toPopulate = meta.relations
-            .filter(prop => prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && !prop.lazy && !relationsToPopulate.includes(prop.name))
+            .filter(prop => prop.kind === ReferenceKind.ONE_TO_ONE &&
+            !prop.owner &&
+            !prop.lazy &&
+            !relationsToPopulate.includes(prop.name))
             .filter(prop => fields.length === 0 || fields.some(f => prop.name === f || prop.name.startsWith(`${String(f)}.`)))
             .map(prop => ({ field: `${prop.name}:ref`, strategy: LoadStrategy.JOINED }));
         return [...populate, ...toPopulate];
@@ -1295,8 +1412,13 @@ export class AbstractSqlDriver extends DatabaseDriver {
             const prop = meta.properties[propName];
             // Polymorphic to-one: create a LEFT JOIN per target type
             // Skip :ref hints — polymorphic to-one already has FK + discriminator in the row
-            if (prop.polymorphic && prop.polymorphTargets?.length && !ref && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
-                const basePath = options.parentJoinPath ? `${options.parentJoinPath}.${prop.name}` : `${meta.name}.${prop.name}`;
+            if (prop.polymorphic &&
+                prop.polymorphTargets?.length &&
+                !ref &&
+                [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+                const basePath = options.parentJoinPath
+                    ? `${options.parentJoinPath}.${prop.name}`
+                    : `${meta.name}.${prop.name}`;
                 const pathPrefix = !options.parentJoinPath && populateWhereAll && !basePath.startsWith('[populate]') ? '[populate]' : '';
                 for (const targetMeta of prop.polymorphTargets) {
                     const tableAlias = qb.getNextAlias(targetMeta.className);
@@ -1314,7 +1436,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 continue;
             }
             // ignore ref joins of known FKs unless it's a filter hint
-            if (ref && !hint.filter && (prop.kind === ReferenceKind.MANY_TO_ONE || (prop.kind === ReferenceKind.ONE_TO_ONE && prop.owner))) {
+            if (ref &&
+                !hint.filter &&
+                (prop.kind === ReferenceKind.MANY_TO_ONE || (prop.kind === ReferenceKind.ONE_TO_ONE && prop.owner))) {
                 continue;
             }
             const meta2 = prop.targetMeta;
@@ -1360,7 +1484,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     childExplicitFields.push(f.substring(prop.name.length + 1));
                 }
             });
-            const childExclude = options.exclude ? Utils.extractChildElements(options.exclude, prop.name) : options.exclude;
+            const childExclude = options.exclude
+                ? Utils.extractChildElements(options.exclude, prop.name)
+                : options.exclude;
             if (!ref && (!prop.mapToPk || hint.dataOnly)) {
                 fields.push(...this.getFieldsForJoinedLoad(qb, meta2, {
                     ...options,
@@ -1371,7 +1497,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                     parentJoinPath: path,
                 }));
             }
-            else if (hint.filter || (prop.mapToPk && !hint.dataOnly) || (ref && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind))) {
+            else if (hint.filter ||
+                (prop.mapToPk && !hint.dataOnly) ||
+                (ref && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind))) {
                 fields.push(...prop.referencedColumnNames.map(col => qb.helper.mapper(`${tableAlias}.${col}`, qb.type, undefined, `${tableAlias}__${col}`)));
             }
         }
@@ -1410,7 +1538,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
      * @internal
      */
     findTPTChildAlias(qb, childMeta) {
-        const joins = qb._joins;
+        const joins = qb.state.joins;
         for (const key of Object.keys(joins)) {
             if (joins[key].table === childMeta.tableName && key.includes('[tpt]')) {
                 return joins[key].alias;
@@ -1473,7 +1601,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
             if (childAlias) {
                 // Map fields using same filtering as joined loading, plus skip PKs
                 for (const prop of currentMeta.ownProps.filter(p => !p.primary && this.platform.shouldHaveColumn(p, []))) {
-                    this.mapJoinedProp(relationPojo, prop, childAlias, root, tz, currentMeta, { deleteFromRoot: true });
+                    this.mapJoinedProp(relationPojo, prop, childAlias, root, tz, currentMeta, {
+                        deleteFromRoot: true,
+                    });
                 }
             }
             currentMeta = currentMeta.tptParent;
@@ -1522,7 +1652,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
     /** @internal */
     createQueryBuilder(entityName, ctx, preferredConnectionType, convertCustomTypes, loggerContext, alias, em) {
         // do not compute the connectionType if EM is provided as it will be computed from it in the QB later on
-        const connectionType = em ? preferredConnectionType : this.resolveConnectionType({ ctx, connectionType: preferredConnectionType });
+        const connectionType = em
+            ? preferredConnectionType
+            : this.resolveConnectionType({ ctx, connectionType: preferredConnectionType });
         const qb = new QueryBuilder(entityName, this.metadata, this, ctx, alias, connectionType, em, loggerContext);
         if (!convertCustomTypes) {
             qb.unsetFlag(QueryFlag.CONVERT_CUSTOM_TYPES);
@@ -1598,6 +1730,47 @@ export class AbstractSqlDriver extends DatabaseDriver {
         /* v8 ignore next */
         return { $and: [options.populateWhere, where] };
     }
+    /**
+     * Builds a UNION ALL (or UNION) subquery from `unionWhere` branches and merges it
+     * into the main WHERE as `pk IN (branch_1 UNION ALL branch_2 ...)`.
+     * Each branch is planned independently by the database, enabling per-table index usage.
+     */
+    async applyUnionWhere(meta, where, options, forDml = false) {
+        const unionWhere = options.unionWhere;
+        const strategy = options.unionWhereStrategy ?? 'union-all';
+        const schema = this.getSchemaName(meta, options);
+        const connectionType = this.resolveConnectionType({
+            ctx: options.ctx,
+            connectionType: options.connectionType,
+        });
+        const branchQbs = [];
+        for (const branch of unionWhere) {
+            const qb = this.createQueryBuilder(meta.class, options.ctx, connectionType, false, options.logging).withSchema(schema);
+            const pkFields = meta.primaryKeys.map(pk => {
+                const prop = meta.properties[pk];
+                return `${qb.alias}.${prop.fieldNames[0]}`;
+            });
+            qb.select(pkFields).where(branch);
+            if (options.em) {
+                await qb.applyJoinedFilters(options.em, options.filters);
+            }
+            branchQbs.push(qb);
+        }
+        const [first, ...rest] = branchQbs;
+        const unionQb = strategy === 'union' ? first.union(...rest) : first.unionAll(...rest);
+        const pkHash = Utils.getPrimaryKeyHash(meta.primaryKeys);
+        // MySQL does not allow referencing the target table in a subquery
+        // for UPDATE/DELETE, so we wrap the union in a derived table.
+        if (forDml) {
+            const { sql, params } = unionQb.toQuery();
+            return {
+                $and: [where, { [pkHash]: { $in: raw(`select * from (${sql}) as __u`, params) } }],
+            };
+        }
+        return {
+            $and: [where, { [pkHash]: { $in: unionQb.toRaw() } }],
+        };
+    }
     buildOrderBy(qb, meta, populate, options) {
         const joinedProps = this.joinedProps(meta, populate, options);
         // `options._populateWhere` is a copy of the value provided by user with a fallback to the global config option
@@ -1628,7 +1801,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 let path = parentPath;
                 const meta2 = prop.targetMeta;
                 if (prop.kind !== ReferenceKind.SCALAR &&
-                    (![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) || !prop.owner || Utils.isPlainObject(childOrder))) {
+                    (![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) ||
+                        !prop.owner ||
+                        Utils.isPlainObject(childOrder))) {
                     path += `.${field}`;
                 }
                 if (prop.kind === ReferenceKind.MANY_TO_MANY && typeof childOrder !== 'object') {
@@ -1639,7 +1814,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 if (!join) {
                     continue;
                 }
-                if (join && ![ReferenceKind.SCALAR, ReferenceKind.EMBEDDED].includes(prop.kind) && typeof childOrder === 'object') {
+                if (join &&
+                    ![ReferenceKind.SCALAR, ReferenceKind.EMBEDDED].includes(prop.kind) &&
+                    typeof childOrder === 'object') {
                     const children = this.buildPopulateOrderBy(qb, meta2, Utils.asArray(childOrder), path, explicit, propAlias);
                     orderBy.push(...children);
                     continue;
@@ -1770,7 +1947,8 @@ export class AbstractSqlDriver extends DatabaseDriver {
             if (!options.fields.includes('*') && !options.fields.includes(`${qb.alias}.*`)) {
                 ret.unshift(...meta.primaryKeys.filter(pk => !options.fields.includes(pk)));
             }
-            if (meta.root.inheritanceType === 'sti' && !options.fields.includes(`${qb.alias}.${meta.root.discriminatorColumn}`)) {
+            if (meta.root.inheritanceType === 'sti' &&
+                !options.fields.includes(`${qb.alias}.${meta.root.discriminatorColumn}`)) {
                 ret.push(meta.root.discriminatorColumn);
             }
         }

package/AbstractSqlPlatform.d.ts

@@ -4,6 +4,7 @@ import { type SchemaHelper } from './schema/SchemaHelper.js';
 import type { IndexDef } from './typings.js';
 import { NativeQueryBuilder } from './query/NativeQueryBuilder.js';
 export declare abstract class AbstractSqlPlatform extends Platform {
+    #private;
     protected readonly schemaHelper?: SchemaHelper;
     usesPivotTable(): boolean;
     indexForeignKeys(): boolean;
@@ -26,7 +27,14 @@ export declare abstract class AbstractSqlPlatform extends Platform {
     quoteValue(value: any): string;
     getSearchJsonPropertySQL(path: string, type: string, aliased: boolean): string | RawQueryFragment;
     getSearchJsonPropertyKey(path: string[], type: string, aliased: boolean, 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.
+     * @internal
+     */
+    quoteJsonKey(key: string): string;
     getJsonIndexDefinition(index: IndexDef): string[];
+    supportsUnionWhere(): boolean;
     supportsSchemas(): boolean;
     /** @inheritDoc */
     generateCustomOrder(escapedColumn: string, values: unknown[]): string;
@@ -41,4 +49,31 @@ export declare abstract class AbstractSqlPlatform extends Platform {
     quoteCollation(collation: string): string;
     /** @internal */
     protected validateCollationName(collation: string): void;
+    /** @internal */
+    validateJsonPropertyName(name: string): void;
+    /**
+     * Returns FROM clause for JSON array iteration.
+     * @internal
+     */
+    getJsonArrayFromSQL(column: string, alias: string, _properties: {
+        name: string;
+        type: string;
+    }[]): string;
+    /**
+     * Returns SQL expression to access an element's property within a JSON array iteration.
+     * @internal
+     */
+    getJsonArrayElementPropertySQL(alias: string, property: string, _type: string): string;
+    /**
+     * Wraps JSON array FROM clause and WHERE condition into a full EXISTS condition.
+     * MySQL overrides this because `json_table` doesn't support correlated subqueries.
+     * @internal
+     */
+    getJsonArrayExistsSQL(from: string, where: string): string;
+    /**
+     * Maps a runtime type name (e.g. 'string', 'number') to a driver-specific bind type constant.
+     * Used by NativeQueryBuilder for output bindings.
+     * @internal
+     */
+    mapToBindType(type: string): unknown;
 }