@mikro-orm/sql 7.2.0-dev.9 → 7.2.0

package/dialects/postgresql/PostgreSqlSchemaHelper.d.ts

@@ -1,7 +1,7 @@
 import { type Dictionary, type Transaction } from '@mikro-orm/core';
 import { SchemaHelper } from '../../schema/SchemaHelper.js';
 import type { AbstractSqlConnection } from '../../AbstractSqlConnection.js';
-import type { CheckDef, Column, ForeignKey, IndexDef, Table, TableDifference, TablePartitioning, SqlTriggerDef, SqlRoutineDef } from '../../typings.js';
+import type { CheckDef, Column, ForeignKey, IndexDef, Table, TableDifference, TablePartitioning, SqlPolicyDef, SqlTriggerDef, SqlRoutineDef } from '../../typings.js';
 import type { DatabaseSchema } from '../../schema/DatabaseSchema.js';
 import type { DatabaseTable } from '../../schema/DatabaseTable.js';
 export declare class PostgreSqlSchemaHelper extends SchemaHelper {
@@ -71,6 +71,17 @@ export declare class PostgreSqlSchemaHelper extends SchemaHelper {
     dropTrigger(table: DatabaseTable, trigger: SqlTriggerDef): string;
     /** Flattens `;\n` inside the dollar-quoted blocks of a raw DDL expression, which are not statement boundaries. */
     private flattenDollarQuotedBodies;
+    getRlsCreateSQL(table: DatabaseTable): string[];
+    getRlsDropSQL(diff: TableDifference, safe?: boolean): string[];
+    getRlsAlterSQL(diff: TableDifference, safe?: boolean): string[];
+    /**
+     * Quotes a policy or role name as a single identifier. Unlike `quote()`/`platform.quoteIdentifier`, which treat
+     * a dot as a schema qualifier, these names are never schema-qualified, so `my.role` must render as `"my.role"`.
+     */
+    private quoteUnqualified;
+    private createPolicy;
+    private dropPolicy;
+    private formatPolicyRoles;
     createRoutine(routine: SqlRoutineDef): string;
     dropRoutine(routine: SqlRoutineDef): string;
     getAllRoutines(connection: AbstractSqlConnection, schemas?: string[]): Promise<SqlRoutineDef[]>;
@@ -87,6 +98,12 @@ export declare class PostgreSqlSchemaHelper extends SchemaHelper {
     getDatabaseCollation(connection: AbstractSqlConnection, ctx?: Transaction): Promise<string | undefined>;
     getAllTriggers(connection: AbstractSqlConnection, tablesBySchemas: Map<string | undefined, Table[]>): Promise<Dictionary<SqlTriggerDef[]>>;
     private getTriggersSQL;
+    getAllPolicies(connection: AbstractSqlConnection, tablesBySchemas: Map<string | undefined, Table[]>, ctx?: Transaction): Promise<Dictionary<{
+        policies: SqlPolicyDef[];
+        enabled: boolean;
+        forced: boolean;
+    }>>;
+    private parsePgRoles;
     getAllForeignKeys(connection: AbstractSqlConnection, tablesBySchemas: Map<string | undefined, Table[]>, ctx?: Transaction): Promise<Dictionary<Dictionary<ForeignKey>>>;
     getNativeEnumDefinitions(connection: AbstractSqlConnection, schemas: string[], ctx?: Transaction): Promise<Dictionary<{
         name: string;

package/dialects/postgresql/PostgreSqlSchemaHelper.js

@@ -162,6 +162,7 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
         const fks = await this.getAllForeignKeys(connection, tablesBySchema, ctx);
         const partitionings = await this.getPartitions(connection, tablesBySchema, ctx);
         const triggers = await this.getAllTriggers(connection, tablesBySchema);
+        const policies = await this.getAllPolicies(connection, tablesBySchema, ctx);
         const dbCollation = await this.getDatabaseCollation(connection, ctx);
         for (const t of tables) {
             const key = this.getTableKey(t);
@@ -175,6 +176,12 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             if (triggers[key]) {
                 table.setTriggers(triggers[key]);
             }
+            const rls = policies[key];
+            if (rls) {
+                table.setPolicies(rls.policies);
+                table.rlsEnabled = rls.enabled;
+                table.rlsForced = rls.forced;
+            }
             table.setPartitioning(partitionings[key]);
         }
     }
@@ -494,7 +501,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,
@@ -540,6 +547,83 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
         })
             .join('');
     }
+    getRlsCreateSQL(table) {
+        const ret = [];
+        if (table.rlsEnabled) {
+            ret.push(`alter table ${table.getQuotedName()} enable row level security`);
+        }
+        if (table.rlsForced) {
+            ret.push(`alter table ${table.getQuotedName()} force row level security`);
+        }
+        for (const policy of table.getPolicies()) {
+            ret.push(this.createPolicy(table, policy));
+        }
+        return ret;
+    }
+    getRlsDropSQL(diff, safe) {
+        // a policy expression holds a dependency on the columns it references, so removed policies (including the
+        // old version of changed ones) must be dropped before the column drops emitted later in the diff;
+        // in safe mode only recreated policies (present in both removed + added) are dropped, so a policy that is
+        // merely removed is left untouched like removed triggers/columns
+        return Object.values(diff.removedPolicies)
+            .filter(policy => !safe || policy.name in diff.addedPolicies)
+            .map(policy => this.dropPolicy(diff.toTable, policy));
+    }
+    getRlsAlterSQL(diff, safe) {
+        const ret = [];
+        const table = diff.toTable;
+        if (diff.changedRlsEnabled === true) {
+            ret.push(`alter table ${table.getQuotedName()} enable row level security`);
+        }
+        if (diff.changedRlsForced === true) {
+            ret.push(`alter table ${table.getQuotedName()} force row level security`);
+        }
+        else if (!safe && diff.changedRlsForced === false) {
+            ret.push(`alter table ${table.getQuotedName()} no force row level security`);
+        }
+        for (const policy of Object.values(diff.addedPolicies)) {
+            ret.push(this.createPolicy(table, policy));
+        }
+        // disable only after its policies are gone (removed ones were dropped via `getRlsDropSQL`); skipped in
+        // safe mode so a safe run never lifts row level security off an existing table
+        if (!safe && diff.changedRlsEnabled === false) {
+            ret.push(`alter table ${table.getQuotedName()} disable row level security`);
+        }
+        return ret;
+    }
+    /**
+     * Quotes a policy or role name as a single identifier. Unlike `quote()`/`platform.quoteIdentifier`, which treat
+     * a dot as a schema qualifier, these names are never schema-qualified, so `my.role` must render as `"my.role"`.
+     */
+    quoteUnqualified(name) {
+        return `"${name.replaceAll('"', '""')}"`;
+    }
+    createPolicy(table, policy) {
+        const parts = [`create policy ${this.quoteUnqualified(policy.name)} on ${table.getQuotedName()}`];
+        if (policy.type === 'restrictive') {
+            parts.push('as restrictive');
+        }
+        if (policy.command !== 'all') {
+            parts.push(`for ${policy.command}`);
+        }
+        if (policy.roles.length > 0) {
+            parts.push(`to ${this.formatPolicyRoles(policy.roles)}`);
+        }
+        if (policy.using) {
+            parts.push(`using (${policy.using})`);
+        }
+        if (policy.check) {
+            parts.push(`with check (${policy.check})`);
+        }
+        return parts.join(' ');
+    }
+    dropPolicy(table, policy) {
+        return `drop policy ${this.quoteUnqualified(policy.name)} on ${table.getQuotedName()}`;
+    }
+    // `public` is a keyword and must stay unquoted; other roles are quoted like any identifier
+    formatPolicyRoles(roles) {
+        return roles.map(role => (role === 'public' ? 'public' : this.quoteUnqualified(role))).join(', ');
+    }
     createRoutine(routine) {
         if (routine.expression) {
             return this.flattenDollarQuotedBodies(routine.expression);
@@ -732,6 +816,56 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
     where (${conditions.join(' or ')})
     order by t.trigger_name, t.event_manipulation`;
     }
+    async getAllPolicies(connection, tablesBySchemas, ctx) {
+        const conditionsFor = (schemaColumn, tableColumn) => [...tablesBySchemas.entries()].map(([schema, tables]) => {
+            const names = tables.map(t => this.platform.quoteValue(t.table_name)).join(', ');
+            const schemaName = this.platform.quoteValue(schema ?? this.platform.getDefaultSchemaName());
+            return `(${schemaColumn} = ${schemaName} and ${tableColumn} in (${names}))`;
+        });
+        const flagConditions = conditionsFor('ns.nspname', 'cls.relname');
+        const policyConditions = conditionsFor('schemaname', 'tablename');
+        // pg_class carries the enable/force flags (a table can enable RLS with zero policies)
+        const flagRows = await connection.execute(`select cls.relname as table_name, ns.nspname as schema_name, cls.relrowsecurity as enabled, cls.relforcerowsecurity as forced
+        from pg_class cls
+        join pg_namespace ns on ns.oid = cls.relnamespace
+        where (${flagConditions.join(' or ')})`, [], 'all', ctx);
+        const policyRows = await connection.execute(`select tablename as table_name, schemaname as schema_name, policyname as name, permissive, roles, cmd, qual, with_check
+        from pg_policies
+        where (${policyConditions.join(' or ')})
+        order by policyname`, [], 'all', ctx);
+        const policiesByTable = {};
+        for (const row of policyRows) {
+            const key = this.getTableKey(row);
+            (policiesByTable[key] ??= []).push({
+                name: row.name,
+                command: row.cmd.toLowerCase(),
+                type: row.permissive === 'PERMISSIVE' ? 'permissive' : 'restrictive',
+                roles: this.parsePgRoles(row.roles),
+                using: row.qual ?? undefined,
+                check: row.with_check ?? undefined,
+            });
+        }
+        const ret = {};
+        for (const row of flagRows) {
+            const key = this.getTableKey(row);
+            ret[key] = { policies: policiesByTable[key] ?? [], enabled: row.enabled, forced: row.forced };
+        }
+        return ret;
+    }
+    // node-postgres returns `pg_policies.roles` as an unparsed array literal (`{public}`), pglite as an array
+    parsePgRoles(value) {
+        if (Array.isArray(value)) {
+            return value;
+        }
+        // tokenize the array literal instead of splitting on commas — quoted role names can contain
+        // commas, and quoted elements escape `"` and `\` with a backslash
+        const roles = [];
+        const re = /"((?:[^"\\]|\\.)*)"|[^,]+/g;
+        for (const match of value.replace(/^\{|\}$/g, '').matchAll(re)) {
+            roles.push(match[1] != null ? match[1].replace(/\\(.)/g, '$1') : match[0]);
+        }
+        return roles;
+    }
     async getAllForeignKeys(connection, tablesBySchemas, ctx) {
         const sql = `select nsp1.nspname schema_name, cls1.relname table_name, nsp2.nspname referenced_schema_name,
       cls2.relname referenced_table_name, a.attname column_name, af.attname referenced_column_name, conname constraint_name,
@@ -966,6 +1100,24 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             for (const { table: localTable, foreignKey } of inboundForeignKeys) {
                 this.append(ret, this.createForeignKey(localTable, foreignKey));
             }
+            // re-enable row level security and recreate the policies (createTable skips them during a rebuild);
+            // emitted after the data copy so `force row level security` can't block the owner's insert
+            this.append(ret, this.getRlsCreateSQL(table));
+            // with `ignorePolicies`, hand-written policies (and the RLS flags they imply) may exist only on the
+            // introspected side — recreate them verbatim, or the rebuild would silently strip them
+            if (this.options.ignorePolicies) {
+                if (diff.fromTable.rlsEnabled && !table.rlsEnabled) {
+                    ret.push(`alter table ${table.getQuotedName()} enable row level security`);
+                }
+                if (diff.fromTable.rlsForced && !table.rlsForced) {
+                    ret.push(`alter table ${table.getQuotedName()} force row level security`);
+                }
+                for (const policy of diff.fromTable.getPolicies()) {
+                    if (!table.hasPolicy(policy.name)) {
+                        ret.push(this.createPolicy(table, policy));
+                    }
+                }
+            }
         }
         if (safe) {
             ret.push(`-- safe mode: original tables kept in schema "${tmpSchema}"; drop that schema manually once the data is verified`);

package/dialects/sqlite/SqlitePlatform.d.ts

@@ -6,6 +6,8 @@ import { SqliteExceptionConverter } from './SqliteExceptionConverter.js';
 export declare class SqlitePlatform extends AbstractSqlPlatform {
     protected readonly schemaHelper: SqliteSchemaHelper;
     protected readonly exceptionConverter: SqliteExceptionConverter;
+    /** sqlite treats null as the lowest value when no placement is requested. */
+    sortsNullsLowest(): boolean;
     /** @internal */
     createNativeQueryBuilder(): SqliteNativeQueryBuilder;
     usesDefaultKeyword(): boolean;

package/dialects/sqlite/SqlitePlatform.js

@@ -5,6 +5,10 @@ import { SqliteExceptionConverter } from './SqliteExceptionConverter.js';
 export class SqlitePlatform extends AbstractSqlPlatform {
     schemaHelper = new SqliteSchemaHelper(this);
     exceptionConverter = new SqliteExceptionConverter();
+    /** sqlite treats null as the lowest value when no placement is requested. */
+    sortsNullsLowest() {
+        return true;
+    }
     /** @internal */
     createNativeQueryBuilder() {
         return new SqliteNativeQueryBuilder(this);

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.9",
+  "version": "7.2.0",
   "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.2.0"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.2.0-dev.9"
+    "@mikro-orm/core": "7.2.0"
   },
   "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.d.ts

@@ -13,6 +13,7 @@ export declare class ObjectCriteriaNode<T extends object> extends CriteriaNode<T
     private inlineArrayChildPayload;
     private inlineChildPayload;
     private inlineCondition;
+    private isCollectionOperator;
     private shouldAutoJoin;
     private autoJoin;
     private isPrefixed;

package/query/ObjectCriteriaNode.js

@@ -1,7 +1,7 @@
 import { ALIAS_REPLACEMENT, GroupOperator, QueryFlag, raw, RawQueryFragment, ReferenceKind, Utils, } from '@mikro-orm/core';
 import { CriteriaNode } from './CriteriaNode.js';
 import { JoinType, QueryType } from './enums.js';
-const COLLECTION_OPERATORS = ['$some', '$none', '$every', '$size'];
+const COLLECTION_OPERATORS = ['$some', '$none', '$every', '$size', '$all'];
 /**
  * @internal
  */
@@ -17,7 +17,7 @@ export class ObjectCriteriaNode extends CriteriaNode {
             alias = nestedAlias;
         }
         if (this.shouldAutoJoin(qb, nestedAlias)) {
-            if (keys.some(k => COLLECTION_OPERATORS.includes(k))) {
+            if (keys.some(k => this.isCollectionOperator(k))) {
                 if (![ReferenceKind.MANY_TO_MANY, ReferenceKind.ONE_TO_MANY].includes(this.prop.kind)) {
                     // ignore collection operators when used on a non-relational property - this can happen when they get into
                     // populateWhere via `infer` on m:n properties with select-in strategy
@@ -34,11 +34,24 @@ export class ObjectCriteriaNode extends CriteriaNode {
                 const primaryKeys = parentMeta.primaryKeys.map(pk => {
                     return [QueryType.SELECT, QueryType.COUNT].includes(qb.type) ? `${knownKey ? alias : ownerAlias}.${pk}` : pk;
                 });
+                const conditions = [];
+                let matchNothing = false;
                 for (const key of keys) {
                     if (typeof key !== 'string' || !COLLECTION_OPERATORS.includes(key)) {
                         throw new Error('Mixing collection operators with other filters is not allowed.');
                     }
                     const payload = this.payload[key].unwrap();
+                    // `$all` requires every listed item to be present, which is an intersection of `$some` conditions
+                    if (key === '$all') {
+                        // an empty `$all` matches nothing, same as in mongo
+                        matchNothing ||= payload.length === 0;
+                        conditions.push(...payload.map(item => ['$some', item]));
+                    }
+                    else {
+                        conditions.push([key, payload]);
+                    }
+                }
+                for (const [key, payload] of conditions) {
                     // entities with a fixed schema must resolve the `from` table's own schema in the subquery,
                     // otherwise a nested operator inherits the root entity's schema (GH #7894); for wildcard or
                     // schema-less entities the schema is resolved dynamically and needs to be carried over
@@ -70,6 +83,9 @@ export class ObjectCriteriaNode extends CriteriaNode {
                         [Utils.getPrimaryKeyHash(primaryKeys)]: { [op]: sub.getNativeQuery().toRaw() },
                     });
                 }
+                if (matchNothing) {
+                    $and.push({ [Utils.getPrimaryKeyHash(primaryKeys)]: { $in: [] } });
+                }
                 if ($and.length === 1) {
                     return $and[0];
                 }
@@ -113,7 +129,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)
@@ -153,7 +170,7 @@ export class ObjectCriteriaNode extends CriteriaNode {
             alias = nestedAlias;
         }
         if (this.shouldAutoJoin(qb, nestedAlias)) {
-            return !keys.some(k => COLLECTION_OPERATORS.includes(k));
+            return !keys.some(k => this.isCollectionOperator(k));
         }
         return keys.some(field => {
             const childNode = this.payload[field];
@@ -237,6 +254,14 @@ export class ObjectCriteriaNode extends CriteriaNode {
         delete o[key];
         o.$and = $and;
     }
+    isCollectionOperator(key) {
+        if (typeof key !== 'string' || !COLLECTION_OPERATORS.includes(key)) {
+            return false;
+        }
+        // `$all` is primarily a mongo array operator, in SQL it is supported only on collections
+        return (key !== '$all' ||
+            (!!this.prop && [ReferenceKind.MANY_TO_MANY, ReferenceKind.ONE_TO_MANY].includes(this.prop.kind)));
+    }
     shouldAutoJoin(qb, nestedAlias) {
         if (!this.prop || !this.parent) {
             return false;
@@ -245,7 +270,7 @@ export class ObjectCriteriaNode extends CriteriaNode {
         if (keys.every(k => typeof k === 'string' && k.includes('.') && k.startsWith(`${qb.alias}.`))) {
             return false;
         }
-        if (keys.some(k => COLLECTION_OPERATORS.includes(k))) {
+        if (keys.some(k => this.isCollectionOperator(k))) {
             return true;
         }
         const meta = this.metadata.find(this.entityName);

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.