@mikro-orm/core 7.2.0-dev.14 → 7.2.0-dev.15

package/EntityManager.d.ts

@@ -7,7 +7,7 @@ import { EntityLoader, type EntityLoaderOptions } from './entity/EntityLoader.js
 import { Reference } from './entity/Reference.js';
 import { UnitOfWork } from './unit-of-work/UnitOfWork.js';
 import type { CountByOptions, CountOptions, DeleteOptions, FilterOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, IDatabaseDriver, LockOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from './drivers/IDatabaseDriver.js';
-import type { AnyString, ArrayElement, AutoPath, ConnectionType, Dictionary, EntityClass, EntityData, EntityDictionary, EntityDTO, EntityKey, EntityMetadata, EntityName, FilterDef, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, MergeLoaded, MergeSelected, ObjectQuery, PopulateOptions, Primary, Ref, RequiredEntityData, RoutineArgs, RoutineReturn, UnboxArray, IndexFilterQuery, WithUsingOptions } from './typings.js';
+import type { AnyString, ArrayElement, AutoPath, ConnectionType, Dictionary, EntityClass, EntityData, EntityDictionary, EntityDTO, EntityKey, EntityMetadata, EntityName, FilterDef, FilterQuery, FromEntityType, GetRepository, IHydrator, IsSubset, Loaded, MergeLoaded, MergeSelected, ObjectQuery, PopulateOptions, Primary, Ref, RequiredEntityData, RoutineArgs, RoutineReturn, SessionContext, UnboxArray, IndexFilterQuery, WithUsingOptions } from './typings.js';
 import type { Routine } from './metadata/Routine.js';
 import { FlushMode, LockMode, PopulatePath, type TransactionOptions } from './enums.js';
 import type { MetadataStorage } from './metadata/MetadataStorage.js';
@@ -95,7 +95,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /**
      * Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).
      */
-    addFilter<T extends EntityName | readonly EntityName[]>(options: FilterDef<T>): void;
+    addFilter<T extends EntityName | readonly EntityName[]>(options: Omit<FilterDef<T>, 'rls'>): void;
     /**
      * Sets filter parameter values globally inside context defined by this entity manager.
      * If you want to set shared value for all contexts, be sure to use the root entity manager.
@@ -105,6 +105,32 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Returns filter parameters for given filter set in this context.
      */
     getFilterParams<T extends Dictionary = Dictionary>(name: string): T;
+    /**
+     * Sets the database session context (row level security) for this entity manager. Session variables are merged
+     * with any previously set ones, while the role is replaced when one is provided. The variables are applied via `set_config()` and are
+     * typically referenced by RLS policies through `current_setting()`.
+     */
+    setSessionContext(context: SessionContext): void;
+    private validateSessionContextStaging;
+    /** Merges into this exact instance — `fork()` must bypass context resolution to target the new fork. */
+    private mergeSessionContext;
+    /**
+     * Returns the database session context (row level security) set for this entity manager, or `undefined` if none.
+     */
+    getSessionContext(): SessionContext | undefined;
+    /**
+     * Clears the database session context, since `setSessionContext()` only ever merges variables and updates the role.
+     */
+    clearSessionContext(): void;
+    /** @internal session context to apply on `begin()` under the `'transaction'` strategy (`undefined` otherwise). */
+    getTransactionSessionContext(): SessionContext | undefined;
+    /**
+     * Wraps a driver call in a short implicit transaction when the session context needs to apply, so `set local`
+     * takes effect. Resolves to a plain call when already inside a transaction or when no session context is set.
+     *
+     * @internal
+     */
+    withSessionContext<T>(ctx: Transaction | undefined, cb: (ctx?: Transaction) => Promise<T>): Promise<T>;
     /**
      * Sets logger context for this entity manager.
      */
@@ -700,6 +726,8 @@ export interface ForkOptions {
     keepTransactionContext?: boolean;
     /** default schema to use for this fork */
     schema?: string;
+    /** database session context (row level security) for this fork; inherited from the parent when not set */
+    session?: SessionContext;
     /** default logger context, can be overridden via {@apilink FindOptions} */
     loggerContext?: Dictionary;
     /**

package/EntityManager.js

@@ -1,4 +1,5 @@
 import { getOnConflictReturningFields, getOnCreateGeneratedFields, getWhereCondition, resetUntouchedCollections, } from './utils/upsert-utils.js';
+import { computeRemovedRlsVariables, computeRlsFilterVariables, findRlsFilterDefs } from './utils/rls-utils.js';
 import { Utils } from './utils/Utils.js';
 import { Cursor } from './utils/Cursor.js';
 import { QueryHelper } from './utils/QueryHelper.js';
@@ -15,7 +16,7 @@ import { UnitOfWork } from './unit-of-work/UnitOfWork.js';
 import { EventType, FlushMode, LoadStrategy, LockMode, PopulateHint, PopulatePath, QueryFlag, ReferenceKind, SCALAR_TYPES, } from './enums.js';
 import { EventManager } from './events/EventManager.js';
 import { TransactionEventBroadcaster } from './events/TransactionEventBroadcaster.js';
-import { OptimisticLockError, ValidationError } from './errors.js';
+import { MetadataError, OptimisticLockError, ValidationError } from './errors.js';
 import { applyPopulateHints, getLoadingStrategy } from './entity/utils.js';
 import { TransactionManager } from './utils/TransactionManager.js';
 /**
@@ -44,6 +45,7 @@ export class EntityManager {
     #resultCache;
     #filters = {};
     #filterParams = {};
+    #sessionContext;
     loggerContext;
     #transactionContext;
     #disableTransactions;
@@ -199,6 +201,11 @@ export class EntityManager {
      */
     async *stream(entityName, options = {}) {
         const em = this.getContext();
+        // a stream never opens the implicit session-context transaction, so under the 'transaction' strategy the staged
+        // context would silently never apply outside an ambient transaction and other tenants' rows would leak — fail closed
+        if (!options.ctx && !em.#transactionContext && em.getTransactionSessionContext()) {
+            throw ValidationError.sessionContextStreamRequiresTransaction();
+        }
         options = em.prepareOptions(options);
         options.strategy = 'joined';
         await em.tryFlush(entityName, options);
@@ -262,6 +269,14 @@ export class EntityManager {
         if (options.entity) {
             options.entity = Utils.asArray(options.entity).map(n => Utils.classOrName(n));
         }
+        // runtime-registered filters are never part of entity metadata, so no policy can be generated for them — whether or
+        // not an `entity` was scoped, `rls` is only valid on filters declared in metadata via `@Filter()`. `rls` is excluded
+        // from the type above so TS users fail at compile time; the runtime guard still covers JS callers using `as any`
+        if (options.rls) {
+            throw options.entity
+                ? MetadataError.rlsFilterCannotBeRegisteredAtRuntime(options.name)
+                : MetadataError.rlsFilterMustBeEntityScoped(options.name);
+        }
         options.default ??= true;
         this.getContext(false).#filters[options.name] = options;
     }
@@ -270,7 +285,37 @@ export class EntityManager {
      * If you want to set shared value for all contexts, be sure to use the root entity manager.
      */
     setFilterParams(name, args) {
-        this.getContext().#filterParams[name] = args;
+        const em = this.getContext();
+        // `rls` filters mirror their params as session variables, so the matching DB policies see the same values;
+        // the same filter name can be declared on multiple entities, so stage the union across all `rls`-flagged defs
+        const filters = findRlsFilterDefs(em.metadata, name);
+        if (filters.length === 0) {
+            em.#filterParams[name] = args;
+            return;
+        }
+        // fail before storing the params and pruning stale variables below, so an invalid staging attempt leaves both
+        // the filter params and the session context untouched
+        em.validateSessionContextStaging();
+        const variables = computeRlsFilterVariables(filters, args);
+        const previousArgs = em.#filterParams[name];
+        em.#filterParams[name] = args;
+        // this call replaces the filter's params, so drop the exact variables a previous call for this filter staged but
+        // this one no longer sets (unless another filter's current params still stage them)
+        const staged = em.#sessionContext?.variables;
+        if (staged && previousArgs) {
+            for (const key of computeRemovedRlsVariables(em.metadata, name, filters, previousArgs, variables, em.#filterParams)) {
+                delete staged[key];
+            }
+            // pruning may have emptied the whole context — drop it, so it does not keep forcing the implicit
+            // transaction wrap (and a distinct cache key) while carrying no variables
+            if (Object.keys(staged).length === 0 && !em.#sessionContext.role) {
+                em.#sessionContext = undefined;
+            }
+        }
+        // an empty context would still switch on the implicit transaction wrapping
+        if (Object.keys(variables).length > 0) {
+            em.mergeSessionContext({ variables });
+        }
     }
     /**
      * Returns filter parameters for given filter set in this context.
@@ -278,6 +323,90 @@ export class EntityManager {
     getFilterParams(name) {
         return this.getContext().#filterParams[name];
     }
+    /**
+     * Sets the database session context (row level security) for this entity manager. Session variables are merged
+     * with any previously set ones, while the role is replaced when one is provided. The variables are applied via `set_config()` and are
+     * typically referenced by RLS policies through `current_setting()`.
+     */
+    setSessionContext(context) {
+        // validate the global context like `setFilterParams` — a tenant context set on the global EM
+        // would be silently inherited by every later fork
+        this.getContext().mergeSessionContext(context);
+    }
+    validateSessionContextStaging() {
+        if (!this.getPlatform().supportsRowLevelSecurity()) {
+            throw ValidationError.sessionContextNotSupported();
+        }
+        // staging inside an open transaction is inert under both strategies (the 'transaction' context is only emitted at
+        // top-level begin; the 'connection' context was applied when the pinned connection was reserved), while
+        // `getSessionContext()` would still claim it is set — fail closed regardless of strategy
+        if (this.#transactionContext) {
+            throw ValidationError.sessionContextInsideTransaction();
+        }
+        if (this.config.get('sessionContext') === 'transaction') {
+            // the context is applied on transaction begin, so without implicit transactions writes run untransacted and
+            // silently bypass the policies — fail closed instead of leaking a base-role write
+            if (this.config.get('implicitTransactions') === false) {
+                throw ValidationError.sessionContextRequiresImplicitTransactions();
+            }
+            // same rationale for disabled transactions (config or fork option): the UoW flush would run untransacted
+            // and skip the context while reads still get the per-statement wrap — fail closed on the asymmetry
+            if (this.#disableTransactions) {
+                throw ValidationError.sessionContextWithDisabledTransactions();
+            }
+        }
+    }
+    /** Merges into this exact instance — `fork()` must bypass context resolution to target the new fork. */
+    mergeSessionContext(context) {
+        this.validateSessionContextStaging();
+        const current = this.#sessionContext;
+        const merged = {
+            variables: { ...current?.variables, ...context.variables },
+            role: context.role ?? current?.role,
+        };
+        // normalize an empty context away — it would still force the implicit transaction wrap and a distinct cache key
+        this.#sessionContext = Object.keys(merged.variables).length > 0 || merged.role ? merged : undefined;
+    }
+    /**
+     * Returns the database session context (row level security) set for this entity manager, or `undefined` if none.
+     */
+    getSessionContext() {
+        return this.getContext(false).#sessionContext;
+    }
+    /**
+     * Clears the database session context, since `setSessionContext()` only ever merges variables and updates the role.
+     */
+    clearSessionContext() {
+        const em = this.getContext(false);
+        // clearing inside an open transaction would be as inert (and cache-poisoning) as staging there — fail closed too,
+        // under both strategies (the 'connection' pinned connection was already reserved with the previous context)
+        if (em.#sessionContext && em.#transactionContext) {
+            throw ValidationError.sessionContextInsideTransaction('clear');
+        }
+        em.#sessionContext = undefined;
+    }
+    /** @internal session context to apply on `begin()` under the `'transaction'` strategy (`undefined` otherwise). */
+    getTransactionSessionContext() {
+        const em = this.getContext(false);
+        if (!em.#sessionContext || em.config.get('sessionContext') !== 'transaction') {
+            return undefined;
+        }
+        return em.#sessionContext;
+    }
+    /**
+     * Wraps a driver call in a short implicit transaction when the session context needs to apply, so `set local`
+     * takes effect. Resolves to a plain call when already inside a transaction or when no session context is set.
+     *
+     * @internal
+     */
+    async withSessionContext(ctx, cb) {
+        const em = this.getContext(false);
+        const sessionContext = ctx ? undefined : em.getTransactionSessionContext();
+        if (!sessionContext) {
+            return cb(ctx);
+        }
+        return em.getConnection('write').transactional(trx => cb(trx), { sessionContext, loggerContext: em.loggerContext });
+    }
     /**
      * Sets logger context for this entity manager.
      */
@@ -836,12 +965,12 @@ export class EntityManager {
                 data = em.#comparator.prepareEntity(entity);
             }
         }
-        const ret = await em.driver.nativeUpdate(entityName, where, data, {
-            ctx: em.#transactionContext,
+        const ret = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.driver.nativeUpdate(entityName, where, data, {
             upsert: true,
             convertCustomTypes,
             ...options,
-        });
+            ctx,
+        }));
         em.#unitOfWork.getChangeSetPersister().mapReturnedValues(entity, data, ret.row, meta, true);
         entity ??= em.#entityFactory.create(entityName, data, {
             refresh: true,
@@ -873,13 +1002,13 @@ export class EntityManager {
                     where[meta.primaryKeys[0]] = ret.insertId;
                 }
             }
-            const data2 = await this.driver.findOne(meta.class, where, {
+            const data2 = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => this.driver.findOne(meta.class, where, {
                 fields: returning.concat(...(options.onConflictMergeFields ?? [])),
-                ctx: em.#transactionContext,
+                ctx,
                 convertCustomTypes: true,
                 connectionType: 'write',
                 schema: options.schema,
-            });
+            }));
             em.getHydrator().hydrate(entity, meta, data2, em.#entityFactory, 'full', false, true);
         }
         // recompute the data as there might be some values missing (e.g. those with db column defaults)
@@ -1023,12 +1152,12 @@ export class EntityManager {
                 allData[idx] = em.#comparator.prepareEntity(entity);
             }
         }
-        const res = await em.driver.nativeUpdateMany(entityName, allWhere, allData, {
-            ctx: em.#transactionContext,
+        const res = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.driver.nativeUpdateMany(entityName, allWhere, allData, {
             upsert: true,
             convertCustomTypes,
             ...options,
-        });
+            ctx,
+        }));
         entities.clear();
         entitiesByData.clear();
         const loadPK = new Map();
@@ -1071,16 +1200,16 @@ export class EntityManager {
                     where.$or[idx][prop] = item[prop];
                 });
             });
-            const data2 = await this.driver.find(meta.class, where, {
+            const data2 = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => this.driver.find(meta.class, where, {
                 fields: returning
                     .concat(...add)
                     .concat(...(Array.isArray(uniqueFields) ? uniqueFields : []))
                     .concat(...(options.onConflictMergeFields ?? [])),
-                ctx: em.#transactionContext,
+                ctx,
                 convertCustomTypes: true,
                 connectionType: 'write',
                 schema: options.schema,
-            });
+            }));
             for (const [entity, cond] of loadPK.entries()) {
                 const row = data2.find(row => {
                     const tmp = {};
@@ -1178,6 +1307,7 @@ export class EntityManager {
         }
         const em = this.getContext(false);
         em.#transactionContext = await em.getConnection('write').begin({
+            sessionContext: em.getTransactionSessionContext(),
             ...options,
             eventBroadcaster: new TransactionEventBroadcaster(em, { topLevelTransaction: !options.ctx }),
         });
@@ -1245,15 +1375,12 @@ export class EntityManager {
             const meta = helper(data).__meta;
             const payload = em.#comparator.prepareEntity(data);
             const cs = new ChangeSet(data, ChangeSetType.CREATE, payload, meta);
-            await em.#unitOfWork.getChangeSetPersister().executeInserts([cs], { ctx: em.#transactionContext, ...options });
+            await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.#unitOfWork.getChangeSetPersister().executeInserts([cs], { ...options, ctx }));
             return cs.getPrimaryKey();
         }
         data = QueryHelper.processObjectParams(data);
         validateParams(data, 'insert data');
-        const res = await em.driver.nativeInsert(entityName, data, {
-            ctx: em.#transactionContext,
-            ...options,
-        });
+        const res = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.driver.nativeInsert(entityName, data, { ...options, ctx }));
         return res.insertId;
     }
     /**
@@ -1295,10 +1422,7 @@ export class EntityManager {
         options ??= {};
         options = em.prepareOptions(options);
         const meta = em.metadata.get(entityName);
-        const res = await em.driver.nativeClone(entityName, where, overrides, {
-            ctx: em.#transactionContext,
-            ...options,
-        });
+        const res = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.driver.nativeClone(entityName, where, overrides, { ...options, ctx }));
         const pk = res.insertId ?? res.row?.[meta.primaryKeys[0]];
         return em.findOneOrFail(entityName, pk, {
             schema: options.schema,
@@ -1333,15 +1457,12 @@ export class EntityManager {
                 const payload = em.#comparator.prepareEntity(row);
                 return new ChangeSet(row, ChangeSetType.CREATE, payload, meta);
             });
-            await em.#unitOfWork.getChangeSetPersister().executeInserts(css, { ctx: em.#transactionContext, ...options });
+            await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.#unitOfWork.getChangeSetPersister().executeInserts(css, { ...options, ctx }));
             return css.map(cs => cs.getPrimaryKey());
         }
         data = data.map(row => QueryHelper.processObjectParams(row));
         data.forEach(row => validateParams(row, 'insert data'));
-        const res = await em.driver.nativeInsertMany(entityName, data, {
-            ctx: em.#transactionContext,
-            ...options,
-        });
+        const res = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.driver.nativeInsertMany(entityName, data, { ...options, ctx }));
         if (res.insertedIds) {
             return res.insertedIds;
         }
@@ -1358,11 +1479,11 @@ export class EntityManager {
         where = await em.processWhere(entityName, where, { ...options, convertCustomTypes: false }, 'update');
         validateParams(data, 'update data');
         validateParams(where, 'update condition');
-        const res = await em.driver.nativeUpdate(entityName, where, data, {
-            ctx: em.#transactionContext,
+        const res = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.driver.nativeUpdate(entityName, where, data, {
             em,
             ...options,
-        });
+            ctx,
+        }));
         return res.affectedRows;
     }
     /**
@@ -1394,7 +1515,7 @@ export class EntityManager {
             throw new Error(`Routine '${routine.name}' is not registered in the 'routines' config option.`);
         }
         const conn = em.driver.getConnection('write');
-        return conn.callRoutine(routine, args, em.#transactionContext);
+        return em.withSessionContext(em.#transactionContext, ctx => conn.callRoutine(routine, args, ctx));
     }
     /**
      * Fires native delete query. Calling this has no side effects on the context (identity map).
@@ -1405,11 +1526,11 @@ export class EntityManager {
         await em.processUnionWhere(entityName, options, 'delete');
         where = (await em.processWhere(entityName, where, options, 'delete'));
         validateParams(where, 'delete condition');
-        const res = await em.driver.nativeDelete(entityName, where, {
-            ctx: em.#transactionContext,
+        const res = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.driver.nativeDelete(entityName, where, {
             em,
             ...options,
-        });
+            ctx,
+        }));
         return res.affectedRows;
     }
     /**
@@ -1548,7 +1669,7 @@ export class EntityManager {
         if (cached?.data !== undefined) {
             return cached.data;
         }
-        const count = await em.driver.count(entityName, where, { ctx: em.#transactionContext, em, ...options });
+        const count = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.driver.count(entityName, where, { em, ...options, ctx }));
         await em.storeCache(options.cache, cached, () => +count);
         return +count;
     }
@@ -1713,6 +1834,18 @@ export class EntityManager {
         }
         fork.#filters = { ...em.#filters };
         fork.#filterParams = Utils.copy(em.#filterParams);
+        if (options.session) {
+            // the fork's session replaces the parent context, but the copied `rls` filter params must stay consistent with
+            // it — re-stage their variables underneath the explicit `session.variables`, which win on any conflict
+            const variables = {};
+            for (const name of Object.keys(fork.#filterParams)) {
+                Object.assign(variables, computeRlsFilterVariables(findRlsFilterDefs(fork.metadata, name), fork.#filterParams[name]));
+            }
+            fork.mergeSessionContext({ ...options.session, variables: { ...variables, ...options.session.variables } });
+        }
+        else if (em.#sessionContext) {
+            fork.#sessionContext = Utils.copy(em.#sessionContext);
+        }
         fork.loggerContext = Utils.merge({}, em.loggerContext, options.loggerContext);
         fork.#schema = options.schema ?? em.#schema;
         fork.signal = options.signal ?? em.signal;
@@ -2127,8 +2260,16 @@ export class EntityManager {
         // the table name (plus discriminator value for STI) is stable across builds and processes,
         // unlike class names, which minifiers can mangle to the same short name for two entities
         const meta = this.metadata.find(entityName);
-        const key = meta?.tableName ? [meta.schema, meta.tableName, meta.discriminatorValue] : Utils.className(entityName);
-        return [key, method, opts, where];
+        const entityKey = meta?.tableName
+            ? [meta.schema, meta.tableName, meta.discriminatorValue]
+            : Utils.className(entityName);
+        const key = [entityKey, method, opts, where];
+        // session context (row level security) scopes cached rows per tenant/role, avoiding cross-context serves
+        const sessionContext = this.getContext(false).#sessionContext;
+        if (sessionContext) {
+            key.push(sessionContext);
+        }
+        return key;
     }
     /**
      * @internal
@@ -2139,7 +2280,13 @@ export class EntityManager {
             return undefined;
         }
         const em = this.getContext();
-        const cacheKey = Array.isArray(config) ? config[0] : JSON.stringify(key);
+        // a named cache key (`config[0]`) discards the computed `key`, which already carries the session context — so
+        // scope it here too, otherwise a fork's rows would be served to another session context under the same name
+        const cacheKey = Array.isArray(config)
+            ? em.#sessionContext
+                ? `${config[0]}|${JSON.stringify(em.#sessionContext)}`
+                : config[0]
+            : JSON.stringify(key);
         const cached = await em.#resultCache.get(cacheKey);
         if (!cached) {
             return { key: cacheKey, data: cached };
@@ -2187,7 +2334,12 @@ export class EntityManager {
      * ```
      */
     async clearCache(cacheKey) {
-        await this.getContext().#resultCache.remove(cacheKey);
+        const em = this.getContext();
+        await em.#resultCache.remove(cacheKey);
+        // named keys are scoped by the session context (see `tryCache`), so clear this context's variant too
+        if (em.#sessionContext) {
+            await em.#resultCache.remove(`${cacheKey}|${JSON.stringify(em.#sessionContext)}`);
+        }
     }
     /**
      * Returns the default schema of this EntityManager. Respects the context, so global EM will give you the contextual schema

package/MikroORM.js

@@ -2,6 +2,7 @@ import { MetadataDiscovery } from './metadata/MetadataDiscovery.js';
 import { MetadataStorage } from './metadata/MetadataStorage.js';
 import { Configuration } from './utils/Configuration.js';
 import { loadEnvironmentVars } from './utils/env-vars.js';
+import { clearRlsFilterDefsCache } from './utils/rls-utils.js';
 import { Utils } from './utils/Utils.js';
 import { colors } from './logging/colors.js';
 async function tryRegisterExtension(name, pkg, extensions) {
@@ -195,6 +196,8 @@ export class MikroORM {
             meta.root = this.#metadata.get(meta.root.class);
         }
         this.#metadata.decorate(this.em);
+        // the newly discovered entities may declare `rls` filters the cached lookup was built without
+        clearRlsFilterDefsCache(this.#metadata);
     }
     /**
      * Gets the SchemaGenerator.

package/connections/Connection.d.ts

@@ -1,7 +1,7 @@
 import { type Configuration, type ConnectionOptions } from '../utils/Configuration.js';
 import type { LogContext, Logger } from '../logging/Logger.js';
 import type { MetadataStorage } from '../metadata/MetadataStorage.js';
-import type { ConnectionType, Dictionary, MaybePromise, Primary, RoutineProperty } from '../typings.js';
+import type { ConnectionType, Dictionary, MaybePromise, Primary, RoutineProperty, SessionContext } from '../typings.js';
 import type { Routine } from '../metadata/Routine.js';
 import type { Platform } from '../platforms/Platform.js';
 import type { Type } from '../types/Type.js';
@@ -66,6 +66,7 @@ export declare abstract class Connection {
         ctx?: Transaction;
         eventBroadcaster?: TransactionEventBroadcaster;
         loggerContext?: LogContext;
+        sessionContext?: SessionContext;
     }): Promise<T>;
     /** Begins a new database transaction and returns the transaction context. */
     begin(options?: {
@@ -74,6 +75,7 @@ export declare abstract class Connection {
         ctx?: Transaction;
         eventBroadcaster?: TransactionEventBroadcaster;
         loggerContext?: LogContext;
+        sessionContext?: SessionContext;
     }): Promise<Transaction>;
     /** Commits the given transaction. */
     commit(ctx: Transaction, eventBroadcaster?: TransactionEventBroadcaster, loggerContext?: LogContext): Promise<void>;

package/entity/Collection.js

@@ -117,9 +117,11 @@ export class Collection {
             opts.orderBy = QueryHelper.mergeOrderBy(opts.orderBy, this.property.orderBy, this.property.targetMeta?.orderBy);
             options.populate = (await em.preparePopulate(this.property.targetMeta.class, options));
             const cond = (await em.applyFilters(this.property.targetMeta.class, where, options.filters ?? {}, 'read'));
-            const map = await em
+            // fall back to the ambient transaction context, or `withSessionContext` would wrap the pivot load in a
+            // second concurrent transaction (a deadlock with a single-connection pool) instead of joining the open one
+            const map = await em.withSessionContext(ctx ?? em.getTransactionContext(), trx => em
                 .getDriver()
-                .loadFromPivotTable(this.property, [helper(this.owner).__primaryKeys], cond, opts.orderBy, ctx, options);
+                .loadFromPivotTable(this.property, [helper(this.owner).__primaryKeys], cond, opts.orderBy, trx, options));
             items = map[helper(this.owner).getSerializedPrimaryKey()].map((item) => em.merge(this.property.targetMeta.class, item, { convertCustomTypes: true }));
             await em.populate(items, options.populate, options);
         }

package/entity/EntityLoader.js

@@ -624,7 +624,7 @@ export class EntityLoader {
         if (!Utils.isEmpty(prop.where)) {
             where = { $and: [where, prop.where] };
         }
-        const map = await this.#driver.loadFromPivotTable(prop, ids, where, orderBy, this.#em.getTransactionContext(), options2, pivotJoin);
+        const map = await this.#em.withSessionContext(this.#em.getTransactionContext(), ctx => this.#driver.loadFromPivotTable(prop, ids, where, orderBy, ctx, options2, pivotJoin));
         const children = [];
         const isUnionTargetMN = QueryHelper.isUnionTargetPolymorphic(prop);
         for (let i = 0; i < filtered.length; i++) {

package/entity/defineEntity.d.ts

@@ -647,6 +647,9 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
         entity?: EntityName<any> | EntityName<any>[];
         args?: boolean;
         strict?: boolean;
+        rls?: boolean | {
+            setting?: string;
+        };
     }>;
     forceObject?: TForceObject;
     embeddable?: TEmbeddable;

package/enums.d.ts

@@ -1,4 +1,4 @@
-import type { EntityKey, ExpandProperty } from './typings.js';
+import type { EntityKey, ExpandProperty, SessionContext } from './typings.js';
 import type { InflightQueryAbortStrategy, Transaction } from './connections/Connection.js';
 import type { LogContext } from './logging/Logger.js';
 /** Controls when the `EntityManager` flushes pending changes to the database. */
@@ -307,6 +307,8 @@ export interface TransactionOptions {
     flushMode?: FlushMode | `${FlushMode}`;
     ignoreNestedTransactions?: boolean;
     loggerContext?: LogContext;
+    /** @internal database session context applied on `begin()` (set via `em.setSessionContext()`). */
+    sessionContext?: SessionContext;
     /**
      * `AbortSignal` cancelling every query within the transaction (including the implicit flush).
      * Cancelling mid-transaction triggers a rollback once the in-flight query settles.

package/errors.d.ts

@@ -25,6 +25,13 @@ export declare class ValidationError<T extends AnyEntity = AnyEntity> extends Er
     static invalidCompositeIdentifier(meta: EntityMetadata): ValidationError;
     static cannotCommit(): ValidationError;
     static cannotUseGlobalContext(): ValidationError;
+    static sessionContextNotSupported(): ValidationError;
+    static sessionContextRequiresImplicitTransactions(): ValidationError;
+    static sessionContextWithDisabledTransactions(): ValidationError;
+    static sessionContextInsideTransaction(action?: 'set' | 'clear'): ValidationError;
+    static cannotStageNonScalarSessionVariable(filterName: string, argName: string): ValidationError;
+    static sessionContextStreamRequiresTransaction(): ValidationError;
+    static connectionSessionContextNotSupported(): ValidationError;
     static cannotUseOperatorsInsideEmbeddables(entityName: EntityName, propName: string, payload: unknown): ValidationError;
     static cannotUseGroupOperatorsInsideScalars(entityName: EntityName, propName: string, payload: unknown): ValidationError;
     static invalidEmbeddableQuery(entityName: EntityName, propName: string, embeddableType: string): ValidationError;
@@ -77,6 +84,30 @@ export declare class MetadataError<T extends AnyEntity = AnyEntity> extends Vali
     static tptNotSupportedByDriver(meta: EntityMetadata): MetadataError;
     /** Thrown when database triggers are defined on an entity using a driver that does not support them. */
     static triggersNotSupportedByDriver(meta: EntityMetadata): MetadataError;
+    /** Thrown when row level security is declared on an entity using a driver that does not support it. */
+    static rowLevelSecurityNotSupportedByDriver(meta: EntityMetadata): MetadataError;
+    /** Thrown when row level security is declared on a non-root entity of an STI hierarchy. */
+    static rowLevelSecurityOnNonRootStiEntity(meta: EntityMetadata): MetadataError;
+    /** Thrown when two policies on the same entity are given the same explicit name. */
+    static duplicatePolicyName(meta: EntityMetadata, name: string): MetadataError;
+    /** Thrown when a filter flagged with `rls` is declared on a driver that does not support row level security. */
+    static rlsFilterNotSupportedByDriver(meta: EntityMetadata, filterName: string): MetadataError;
+    /** Thrown when a filter flagged with `rls` is declared on a non-root entity of an STI hierarchy. */
+    static rlsFilterOnNonRootStiEntity(meta: EntityMetadata, filterName: string): MetadataError;
+    /** Thrown when a global (config or EM registered) filter is flagged with `rls`; RLS filters must be entity scoped. */
+    static rlsFilterMustBeEntityScoped(filterName: string): MetadataError;
+    /** Thrown when an entity-scoped `rls` filter is registered at runtime via `em.addFilter()` instead of in metadata. */
+    static rlsFilterCannotBeRegisteredAtRuntime(filterName: string): MetadataError;
+    /** Thrown when a filter's custom `setting` is used with more than one argument. */
+    static rlsFilterMultiArgSetting(filterName: string, args: string[]): MetadataError;
+    /** Thrown when an `rls` filter's condition depends on runtime state and cannot be compiled to a static policy. */
+    static rlsFilterDependsOnRuntimeState(filterName: string): MetadataError;
+    /** Thrown when an `rls` filter compares against a column whose type has no automatic session-variable cast. */
+    static rlsFilterUncastableType(filterName: string, columnType: string): MetadataError;
+    /** Thrown when an `rls` filter references an argument outside of a direct comparison, which cannot be compiled. */
+    static rlsFilterUnsupportedCond(filterName: string): MetadataError;
+    /** Thrown when an `rls` filter compares against a column the schema generator does not manage. */
+    static rlsFilterUnmanagedColumn(filterName: string, column: string): MetadataError;
     private static fromMessage;
 }
 /** Error thrown when an entity lookup fails to find the expected result. */