@mikro-orm/core 7.1.16-dev.1 → 7.1.16-dev.11

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.
      */
@@ -375,12 +401,10 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      */
     nativeDelete<Entity extends object>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, options?: DeleteOptions<Entity>): Promise<number>;
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
-    map<Entity extends object>(entityName: EntityName<Entity>, result: EntityDictionary<Entity>, options?: {
-        schema?: string;
-        mapped?: boolean;
-    }): Entity;
+    map<Entity extends object>(entityName: EntityName<Entity>, result: EntityDictionary<Entity>, options?: MapOptions): Entity;
     /**
      * Merges given entity to this EntityManager so it becomes managed. You can force refreshing of existing entities
      * via second parameter. By default, it will return already loaded entities without modifying them.
@@ -667,6 +691,14 @@ export interface CreateOptions<Convert extends boolean> {
      */
     processOnCreateHooksEarly?: boolean;
 }
+export interface MapOptions {
+    /** schema to use when mapping the entity */
+    schema?: string;
+    /** set to true when the result is already mapped to entity property names */
+    mapped?: boolean;
+    /** map the entity in an isolated context without adding it to the identity map */
+    disableIdentityMap?: boolean;
+}
 export interface MergeOptions {
     refresh?: boolean;
     convertCustomTypes?: boolean;
@@ -694,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.
      */
@@ -383,6 +512,7 @@ export class EntityManager {
                 filters,
                 populate: hint.children,
                 populateWhere: PopulateHint.ALL,
+                populateFilter: undefined,
             });
             if (Utils.hasObjectKeys(where)) {
                 ret[field] = ret[field] ? { $and: [where, ret[field]] } : where;
@@ -836,12 +966,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 +1003,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 +1153,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 +1201,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 +1308,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 +1376,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 +1423,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 +1458,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 +1480,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 +1516,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,18 +1527,26 @@ 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;
     }
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
     map(entityName, result, options = {}) {
-        const { mapped, ...rest } = options;
+        if (options.disableIdentityMap ?? this.config.get('disableIdentityMap')) {
+            const em = this.getContext(false);
+            const fork = em.fork({ keepTransactionContext: true });
+            const ret = fork.map(entityName, result, { ...options, disableIdentityMap: false });
+            fork.clear();
+            return ret;
+        }
+        const { mapped, disableIdentityMap, ...rest } = options;
         const meta = this.metadata.get(entityName);
         const data = (mapped ? result : this.driver.mapResult(result, meta));
         for (const k of Object.keys(data)) {
@@ -1540,7 +1670,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;
     }
@@ -1705,6 +1835,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;
@@ -2119,8 +2261,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
@@ -2131,7 +2281,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 };
@@ -2179,7 +2335,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.d.ts

@@ -82,6 +82,10 @@ export declare class MikroORM<Driver extends IDatabaseDriver = IDatabaseDriver,
      * Closes the database connection.
      */
     close(force?: boolean): Promise<void>;
+    /**
+     * Closes the database connection, allows using the ORM instance with `await using`.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Gets the `MetadataStorage`.
      */

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) {
@@ -159,6 +160,12 @@ export class MikroORM {
         await this.config.getMetadataCacheAdapter()?.close?.();
         await this.config.getResultCacheAdapter()?.close?.();
     }
+    /**
+     * Closes the database connection, allows using the ORM instance with `await using`.
+     */
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
     /**
      * Gets the `MetadataStorage` (without parameters) or `EntityMetadata` instance when provided with the `entityName` parameter.
      */
@@ -189,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/README.md

@@ -24,6 +24,7 @@ npm install @mikro-orm/mysql        # MySQL
 npm install @mikro-orm/mariadb      # MariaDB
 npm install @mikro-orm/sqlite       # SQLite
 npm install @mikro-orm/libsql       # libSQL / Turso
+npm install @mikro-orm/sql-js       # sql.js (in-memory SQLite in WASM)
 npm install @mikro-orm/mongodb      # MongoDB
 npm install @mikro-orm/mssql        # MS SQL Server
 npm install @mikro-orm/oracledb     # Oracle

package/cache/FileCacheAdapter.js

@@ -76,7 +76,7 @@ export class FileCacheAdapter {
         let path = typeof this.#options.combined === 'string' ? this.#options.combined : './metadata.json';
         path = fs.normalizePath(this.#options.cacheDir, path);
         this.#options.combined = path; // override in the options, so we can log it from the CLI in `cache:generate` command
-        writeFileSync(path, JSON.stringify(this.#cache, null, this.#pretty ? 2 : undefined));
+        writeFileSync(path, JSON.stringify(this.#cache, null, this.#pretty ? 2 : undefined), { flush: true });
         return path;
     }
     path(name) {

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';
@@ -51,6 +51,13 @@ export declare abstract class Connection {
      * This method doesn't support transactions, as opposed to `orm.schema.execute()`, which is used internally.
      */
     executeDump(dump: string): Promise<void>;
+    /**
+     * Returns the underlying database client the connection drives — e.g. the `pg` pool, the
+     * `better-sqlite3` database, or the `PGlite` instance — for vendor APIs MikroORM does not wrap.
+     * Each driver narrows the return type to its own client. Its lifecycle belongs to the ORM, so
+     * leave closing it to `orm.close()` unless you supplied the client yourself via `driverOptions`.
+     */
+    getNativeClient(): Promise<unknown>;
     protected onConnect(): Promise<void>;
     /** Executes a callback inside a transaction, committing on success and rolling back on failure. */
     transactional<T>(cb: (trx: Transaction) => Promise<T>, options?: {
@@ -59,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?: {
@@ -67,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/connections/Connection.js

@@ -65,6 +65,15 @@ export class Connection {
     async executeDump(dump) {
         throw new Error(`Executing SQL dumps is not supported by current driver`);
     }
+    /**
+     * Returns the underlying database client the connection drives — e.g. the `pg` pool, the
+     * `better-sqlite3` database, or the `PGlite` instance — for vendor APIs MikroORM does not wrap.
+     * Each driver narrows the return type to its own client. Its lifecycle belongs to the ORM, so
+     * leave closing it to `orm.close()` unless you supplied the client yourself via `driverOptions`.
+     */
+    async getNativeClient() {
+        throw new Error(`Accessing the native client is not supported by current driver`);
+    }
     async onConnect() {
         const schemaGenerator = this.config.getExtension('@mikro-orm/schema-generator');
         if (this.type === 'write' && schemaGenerator) {