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

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;
@@ -66,6 +73,9 @@ export declare class MetadataError<T extends AnyEntity = AnyEntity> extends Vali
     static targetIsAbstract(meta: EntityMetadata, prop: EntityProperty): MetadataError;
     static nonPersistentCompositeProp(meta: EntityMetadata, prop: EntityProperty): MetadataError;
     static propertyTargetsEntityType(meta: EntityMetadata, prop: EntityProperty, target: EntityMetadata): MetadataError;
+    static throughRelationMissingProperty(meta: EntityMetadata, prop: EntityProperty, through: EntityMetadata, side: 'owner' | 'target'): MetadataError;
+    static throughRelationCompositeTarget(meta: EntityMetadata, prop: EntityProperty): MetadataError;
+    static throughRelationInvalidKind(meta: EntityMetadata, prop: EntityProperty): MetadataError;
     static fromMissingOption(meta: EntityMetadata, prop: EntityProperty, option: string): MetadataError;
     static targetKeyOnManyToMany(meta: EntityMetadata, prop: EntityProperty): MetadataError;
     static targetKeyNotUnique(meta: EntityMetadata, prop: EntityProperty, target?: EntityMetadata): MetadataError;
@@ -77,6 +87,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. */

package/errors.js

@@ -94,6 +94,30 @@ export class ValidationError extends Error {
     static cannotUseGlobalContext() {
         return new ValidationError("Using global EntityManager instance methods for context specific actions is disallowed. If you need to work with the global instance's identity map, use `allowGlobalContext` configuration option or `fork()` instead.");
     }
+    static sessionContextNotSupported() {
+        return new ValidationError('Database session context (row level security) is only supported by the PostgreSQL driver. To test a PostgreSQL app without a server, use the `@mikro-orm/pglite` driver instead of sqlite.');
+    }
+    static sessionContextRequiresImplicitTransactions() {
+        return new ValidationError("Cannot set a database session context (row level security) with the 'transaction' strategy while 'implicitTransactions' is disabled. The context is applied on transaction begin, but writes would run without a transaction and silently bypass the policies. Enable 'implicitTransactions', wrap the work in 'em.transactional()', or use the 'connection' session context strategy.");
+    }
+    static sessionContextWithDisabledTransactions() {
+        return new ValidationError("Cannot set a database session context (row level security) with the 'transaction' strategy while transactions are disabled via 'disableTransactions'. The context is applied on transaction begin, so flushes would run without it and silently bypass the policies. Enable transactions, or use the 'connection' session context strategy.");
+    }
+    static sessionContextInsideTransaction(action = 'set') {
+        const advice = action === 'set'
+            ? "Set the session context before starting the transaction (e.g. via 'em.fork({ session })')."
+            : 'Clear the session context outside the transaction.';
+        return new ValidationError(`Cannot ${action} a database session context (row level security) inside an active transaction. The context is applied when the transaction begins or the connection is reserved, so the change would never reach an already-open transaction (with the 'connection' strategy the pinned connection was reserved with the previous context). ${advice}`);
+    }
+    static cannotStageNonScalarSessionVariable(filterName, argName) {
+        return new ValidationError(`Cannot stage the '${argName}' argument of filter '${filterName}' as a session variable (row level security) — only scalar values (string, number, boolean, Date) can be mirrored to the database policy backing the filter.`);
+    }
+    static sessionContextStreamRequiresTransaction() {
+        return new ValidationError("Cannot stream under a database session context (row level security) with the 'transaction' strategy outside a transaction. Streaming never opens the implicit transaction that applies the context, so the streamed rows would not be scoped by it (other tenants' rows would leak). Wrap the stream in 'em.transactional()', or use the 'connection' session context strategy.");
+    }
+    static connectionSessionContextNotSupported() {
+        return new ValidationError("The 'connection' session context strategy requires a driver that supports per-acquire connection hooks (the `postgresql` driver). Use the default 'transaction' strategy instead.");
+    }
     static cannotUseOperatorsInsideEmbeddables(entityName, propName, payload) {
         return new ValidationError(`Using operators inside embeddables is not allowed, move the operator above. (property: ${Utils.className(entityName)}.${propName}, payload: ${inspect(payload)})`);
     }
@@ -217,6 +241,16 @@ export class MetadataError extends ValidationError {
         const suggestion = target.embeddable ? 'Embedded' : 'ManyToOne';
         return this.fromMessage(meta, prop, `is defined as scalar @Property(), but its type is a discovered entity ${target.className}. Maybe you want to use @${suggestion}() decorator instead?`);
     }
+    static throughRelationMissingProperty(meta, prop, through, side) {
+        const target = side === 'owner' ? meta.className : prop.targetMeta.className;
+        return this.fromMessage(meta, prop, `uses 'through' entity ${through.className} which has no ManyToOne property pointing to ${target}`);
+    }
+    static throughRelationCompositeTarget(meta, prop) {
+        return this.fromMessage(meta, prop, `uses 'through' option which is not supported for targets with composite primary key`);
+    }
+    static throughRelationInvalidKind(meta, prop) {
+        return this.fromMessage(meta, prop, `uses 'through' option which is only supported for ManyToOne and OneToOne relations`);
+    }
     static fromMissingOption(meta, prop, option) {
         return this.fromMessage(meta, prop, `is missing '${option}' option`);
     }
@@ -250,6 +284,54 @@ export class MetadataError extends ValidationError {
     static triggersNotSupportedByDriver(meta) {
         return new MetadataError(`Entity ${meta.className} defines database triggers which are not supported by the current driver. Triggers are only available with SQL drivers.`);
     }
+    /** Thrown when row level security is declared on an entity using a driver that does not support it. */
+    static rowLevelSecurityNotSupportedByDriver(meta) {
+        return new MetadataError(`Entity ${meta.className} declares row level security which is not supported by the current driver. Row level security is only available with the PostgreSQL driver. To test a PostgreSQL app without a server, use the \`@mikro-orm/pglite\` driver instead of sqlite.`);
+    }
+    /** Thrown when row level security is declared on a non-root entity of an STI hierarchy. */
+    static rowLevelSecurityOnNonRootStiEntity(meta) {
+        return new MetadataError(`Entity ${meta.className} declares row level security, but it is part of a single table inheritance hierarchy. Declare policies on the root entity ${meta.root.className} instead, as the whole hierarchy shares a single table.`);
+    }
+    /** Thrown when two policies on the same entity are given the same explicit name. */
+    static duplicatePolicyName(meta, name) {
+        return new MetadataError(`Entity ${meta.className} declares multiple row level security policies named '${name}'. Policy names must be unique per table; rename one of them or omit the name to use an auto-generated one.`);
+    }
+    /** Thrown when a filter flagged with `rls` is declared on a driver that does not support row level security. */
+    static rlsFilterNotSupportedByDriver(meta, filterName) {
+        return new MetadataError(`Filter '${filterName}' on entity ${meta.className} is flagged with 'rls', which is only supported by the PostgreSQL driver. To test a PostgreSQL app without a server, use the \`@mikro-orm/pglite\` driver instead of sqlite.`);
+    }
+    /** Thrown when a filter flagged with `rls` is declared on a non-root entity of an STI hierarchy. */
+    static rlsFilterOnNonRootStiEntity(meta, filterName) {
+        return new MetadataError(`Filter '${filterName}' on entity ${meta.className} is flagged with 'rls', but the entity is part of a single table inheritance hierarchy. Declare the filter on the root entity ${meta.root.className} instead, as the whole hierarchy shares a single table and the policy would never be created otherwise.`);
+    }
+    /** Thrown when a global (config or EM registered) filter is flagged with `rls`; RLS filters must be entity scoped. */
+    static rlsFilterMustBeEntityScoped(filterName) {
+        return new MetadataError(`Filter '${filterName}' is a global filter and cannot be flagged with 'rls'. RLS filters must be declared on an entity via @Filter() so a policy can be attached to its table.`);
+    }
+    /** Thrown when an entity-scoped `rls` filter is registered at runtime via `em.addFilter()` instead of in metadata. */
+    static rlsFilterCannotBeRegisteredAtRuntime(filterName) {
+        return new MetadataError(`Filter '${filterName}' cannot be flagged with 'rls' when registered at runtime via 'em.addFilter()'. RLS filters must be declared in entity metadata via the @Filter() decorator (or the entity 'filters' option) so a policy can be attached to the table.`);
+    }
+    /** Thrown when a filter's custom `setting` is used with more than one argument. */
+    static rlsFilterMultiArgSetting(filterName, args) {
+        return new MetadataError(`Filter '${filterName}' sets a custom 'setting' but references multiple arguments (${args.join(', ')}). A custom 'setting' is only allowed for single-argument RLS filters; remove it to use the default 'mikro.${filterName}.<arg>' names.`);
+    }
+    /** Thrown when an `rls` filter's condition depends on runtime state and cannot be compiled to a static policy. */
+    static rlsFilterDependsOnRuntimeState(filterName) {
+        return new MetadataError(`Filter '${filterName}' cannot be compiled to an RLS policy because its condition depends on runtime state (it accesses 'em', 'type', 'options' or 'entityName', or resolves asynchronously). Declare an explicit policy instead.`);
+    }
+    /** Thrown when an `rls` filter compares against a column whose type has no automatic session-variable cast. */
+    static rlsFilterUncastableType(filterName, columnType) {
+        return new MetadataError(`Filter '${filterName}' cannot be compiled to an RLS policy because the column type '${columnType}' has no automatic session-variable cast. Declare an explicit policy instead.`);
+    }
+    /** Thrown when an `rls` filter references an argument outside of a direct comparison, which cannot be compiled. */
+    static rlsFilterUnsupportedCond(filterName) {
+        return new MetadataError(`Filter '${filterName}' cannot be compiled to an RLS policy because it references an argument outside of a direct comparison (only expressions like { prop: args.x } are supported). Declare an explicit policy instead.`);
+    }
+    /** Thrown when an `rls` filter compares against a column the schema generator does not manage. */
+    static rlsFilterUnmanagedColumn(filterName, column) {
+        return new MetadataError(`Filter '${filterName}' cannot be compiled to an RLS policy because column '${column}' is not part of the managed schema (e.g. the property is marked 'persist: false' or the column is excluded via 'skipColumns'). Declare an explicit policy instead.`);
+    }
     static fromMessage(meta, prop, message) {
         return new MetadataError(`${meta.className}.${prop.name} ${message}`);
     }

package/exceptions.d.ts

@@ -102,3 +102,8 @@ export declare class TableNotFoundException extends DatabaseObjectNotFoundExcept
  */
 export declare class UniqueConstraintViolationException extends ConstraintViolationException {
 }
+/**
+ * Exception for a row-level security policy violation (failed `WITH CHECK`) detected in the driver.
+ */
+export declare class RowLevelSecurityViolationException extends ConstraintViolationException {
+}

package/exceptions.js

@@ -115,3 +115,8 @@ export class TableNotFoundException extends DatabaseObjectNotFoundException {
  */
 export class UniqueConstraintViolationException extends ConstraintViolationException {
 }
+/**
+ * Exception for a row-level security policy violation (failed `WITH CHECK`) detected in the driver.
+ */
+export class RowLevelSecurityViolationException extends ConstraintViolationException {
+}

package/index.d.ts

@@ -3,7 +3,7 @@
  * @module core
  */
 export { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config, EntityName, IndexHints, } from './typings.js';
-export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, InferEntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, EntityDTOFlat, EntityDTOProp, SerializeDTO, MigrationDiff, GenerateOptions, FilterObject, IndexFilterQuery, ExtractIndexHints, ExtractDefineEntityProperties, IndexName, IndexColumns, WithUsingOptions, IMigrationRunner, IEntityGenerator, ISeedManager, SeederObject, IMigratorStorage, RequiredEntityData, CheckCallback, TriggerCallback, IndexCallback, FormulaCallback, FormulaColumns, FormulaTable, SchemaTable, SchemaColumns, SchemaColumnRef, EntityDataPropValue, SimpleColumnMeta, Rel, Ref, LazyRef, ScalarRef, EntityRef, ISchemaGenerator, MigrationInfo, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, EntityType, FromEntityType, Selected, IsSubset, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, FilterValue, MergeLoaded, MergeSelected, TypeConfig, AnyString, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, RequiredNullable, DefineConfig, Opt, Hidden, EntitySchemaWithMeta, InferEntity, CheckConstraint, TriggerDef, RoutineReturns, RoutineBodyCallback, RoutineJsBody, RoutineIgnoreField, RoutineParamConfig, RoutineConfig, RoutineRuntimeType, RoutineArgs, RoutineReturn, GeneratedColumnCallback, FilterDef, EntityCtor, Subquery, PopulateHintOptions, Prefixes, } from './typings.js';
+export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, InferEntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, EntityDTOFlat, EntityDTOProp, SerializeDTO, MigrationDiff, GenerateOptions, FilterObject, IndexFilterQuery, ExtractIndexHints, ExtractDefineEntityProperties, IndexName, IndexColumns, WithUsingOptions, IMigrationRunner, IEntityGenerator, ISeedManager, SeederObject, IMigratorStorage, RequiredEntityData, CheckCallback, TriggerCallback, IndexCallback, FormulaCallback, FormulaColumns, FormulaTable, SchemaTable, SchemaColumns, SchemaColumnRef, EntityDataPropValue, SimpleColumnMeta, Rel, Ref, LazyRef, ScalarRef, EntityRef, ISchemaGenerator, MigrationInfo, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, EntityType, FromEntityType, Selected, IsSubset, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, FilterValue, MergeLoaded, MergeSelected, TypeConfig, AnyString, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, RequiredNullable, DefineConfig, Opt, Hidden, EntitySchemaWithMeta, InferEntity, CheckConstraint, TriggerDef, PolicyDef, PolicyCallback, SessionContext, RoutineReturns, RoutineBodyCallback, RoutineJsBody, RoutineIgnoreField, RoutineParamConfig, RoutineConfig, RoutineRuntimeType, RoutineArgs, RoutineReturn, GeneratedColumnCallback, FilterDef, EntityCtor, Subquery, PopulateHintOptions, Prefixes, } from './typings.js';
 export * from './enums.js';
 export * from './errors.js';
 export * from './exceptions.js';

package/metadata/MetadataDiscovery.d.ts

@@ -117,6 +117,7 @@ export declare class MetadataDiscovery {
     private createSchemaTable;
     private initCheckConstraints;
     private initTriggers;
+    private initPolicies;
     private initGeneratedColumn;
     private getDefaultVersionValue;
     private inferDefaultValue;
@@ -125,6 +126,8 @@ export declare class MetadataDiscovery {
     private initVersionProperty;
     private initCustomType;
     private initRelation;
+    /** Resolves the `through` option of a virtual to-one relation into a read-only formula property. */
+    private initThroughRelation;
     private initColumnType;
     private getMappedType;
     private getPrefix;

package/metadata/MetadataDiscovery.js

@@ -165,10 +165,14 @@ export class MetadataDiscovery {
         filtered.forEach(meta => this.initAutoincrement(meta)); // once again after we init custom types
         filtered.forEach(meta => this.initCheckConstraints(meta));
         filtered.forEach(meta => this.initTriggers(meta));
-        forEachProp((_m, p) => {
+        // filter names are load-bearing for RLS (policy and session variable names), backfill from the dictionary key
+        filtered.forEach(meta => Object.entries(meta.filters).forEach(([key, filter]) => (filter.name ??= key)));
+        filtered.forEach(meta => this.initPolicies(meta));
+        forEachProp((m, p) => {
             this.initDefaultValue(p);
             this.inferTypeFromDefault(p);
             this.initRelation(p);
+            this.initThroughRelation(m, p);
             this.initColumnType(p);
         });
         forEachProp((m, p) => this.initIndexes(m, p));
@@ -220,11 +224,9 @@ export class MetadataDiscovery {
         };
         const missing = [];
         this.#discovered.forEach(meta => Object.values(meta.properties).forEach(prop => {
-            if (prop.kind === ReferenceKind.MANY_TO_MANY && prop.pivotEntity) {
-                const pivotEntity = prop.pivotEntity;
-                const target = typeof pivotEntity === 'function' && !pivotEntity.prototype
-                    ? pivotEntity()
-                    : pivotEntity;
+            const indirect = (prop.kind === ReferenceKind.MANY_TO_MANY ? prop.pivotEntity : prop.through);
+            if (indirect) {
+                const target = typeof indirect === 'function' && !indirect.prototype ? indirect() : indirect;
                 if (!this.#discovered.find(m => m.className === Utils.className(target)) || !discoveredByIdentity(target)) {
                     missing.push(target);
                 }
@@ -1076,6 +1078,12 @@ export class MetadataDiscovery {
             meta.checks = Utils.unique([...base.checks, ...meta.checks], Utils.equals);
             meta.triggers = Utils.unique([...base.triggers, ...meta.triggers], Utils.equals);
         }
+        // Policies pass down only from inlined abstract bases; STI children share the root table
+        // and TPT children own their tables, so both declare policies directly on the root/child.
+        if (base.abstract && base.inheritanceType !== 'sti' && (meta.inheritanceType !== 'tpt' || !meta.tptParent)) {
+            meta.policies = Utils.unique([...base.policies, ...meta.policies]);
+            meta.rowLevelSecurity ??= base.rowLevelSecurity;
+        }
         const pks = Object.values(meta.properties)
             .filter(p => p.primary)
             .map(p => p.name);
@@ -1743,6 +1751,28 @@ export class MetadataDiscovery {
         }
         meta.hasTriggers = true;
     }
+    initPolicies(meta) {
+        if (meta.policies.length === 0) {
+            return;
+        }
+        const columns = meta.createSchemaColumnMappingObject();
+        const table = this.createSchemaTable(meta);
+        // resolve callbacks into a copy — the defs can be shared with siblings via an inlined abstract base,
+        // and resolving in place would bake the first child's table into every other child's policy
+        meta.policies = meta.policies.map(policy => {
+            if (!(policy.using instanceof Function) && !(policy.check instanceof Function)) {
+                return policy;
+            }
+            const resolved = { ...policy };
+            if (resolved.using instanceof Function) {
+                resolved.using = resolved.using(columns, table);
+            }
+            if (resolved.check instanceof Function) {
+                resolved.check = resolved.check(columns, table);
+            }
+            return resolved;
+        });
+    }
     initGeneratedColumn(meta, prop) {
         if (!prop.generated && prop.columnTypes) {
             const match = /(.*) generated always as (.*)/i.exec(prop.columnTypes[0]);
@@ -2047,6 +2077,58 @@ export class MetadataDiscovery {
             }
         }
     }
+    /** Resolves the `through` option of a virtual to-one relation into a read-only formula property. */
+    initThroughRelation(meta, prop) {
+        // already resolved, or not a through relation at all
+        if (prop.through?.ownerProperty || !prop.through) {
+            return;
+        }
+        if (![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+            throw MetadataError.throughRelationInvalidKind(meta, prop);
+        }
+        const targetMeta = prop.targetMeta;
+        // the subquery selects a single column
+        if (targetMeta.compositePK) {
+            throw MetadataError.throughRelationCompositeTarget(meta, prop);
+        }
+        const through = prop.through;
+        const throughMeta = this.#metadata.get(!through.prototype ? through() : through);
+        // a property is considered to point at an entity when it targets it or one of its parents
+        const pointsTo = (p, m) => {
+            const candidate = this.#metadata.find(p.target);
+            /* v8 ignore next 3 */
+            if (!candidate) {
+                return false;
+            }
+            return candidate.class === m.class || m.class.prototype instanceof candidate.class;
+        };
+        const fks = Object.values(throughMeta.properties).filter(p => p.kind === ReferenceKind.MANY_TO_ONE);
+        const ownerProp = fks.find(p => pointsTo(p, meta));
+        if (!ownerProp) {
+            throw MetadataError.throughRelationMissingProperty(meta, prop, throughMeta, 'owner');
+        }
+        let targetProperty;
+        const selectsTarget = throughMeta.class === targetMeta.class || throughMeta.class.prototype instanceof targetMeta.class;
+        if (!selectsTarget) {
+            const targetProp = fks.find(p => p !== ownerProp && pointsTo(p, targetMeta));
+            if (!targetProp) {
+                throw MetadataError.throughRelationMissingProperty(meta, prop, throughMeta, 'target');
+            }
+            targetProperty = targetProp.name;
+        }
+        prop.through = {
+            entity: throughMeta.class,
+            where: prop.where,
+            orderBy: prop.orderBy ? Utils.asArray(prop.orderBy) : undefined,
+            ownerProperty: ownerProp.name,
+            targetProperty,
+        };
+        // the condition and ordering apply to the `through` entity, not to the target, so they must not leak into the target joins
+        delete prop.where;
+        delete prop.orderBy;
+        prop.persist = false;
+        prop.formula = columns => this.#platform.getThroughRelationFormula(prop, columns);
+    }
     initColumnType(prop) {
         this.initUnsigned(prop);
         // Get the target properties for FK relations - use targetKey property if specified, otherwise PKs

package/metadata/types.d.ts

@@ -1,4 +1,4 @@
-import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw, SchemaColumns, TriggerDef } from '../typings.js';
+import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw, SchemaColumns, TriggerDef, PolicyDef } from '../typings.js';
 import type { Cascade, LoadStrategy, DeferMode, QueryOrderMap, EmbeddedPrefixMode } from '../enums.js';
 import type { Type, types } from '../types/index.js';
 import type { EntityManager } from '../EntityManager.js';
@@ -104,6 +104,10 @@ export type EntityOptions<T, E = T extends EntityClass<infer P> ? P : T> = {
     hasTriggers?: boolean;
     /** Database triggers to create for this entity's table. (SQL drivers only) */
     triggers?: TriggerDef<E>[];
+    /** PostgreSQL row level security policies for this entity's table. Declaring policies implicitly enables RLS. */
+    policies?: PolicyDef<E>[];
+    /** Enables PostgreSQL row level security on this entity's table. `'force'` also enforces it for the table owner. Set to `false` to keep declared policies staged while leaving RLS disabled. */
+    rowLevelSecurity?: boolean | 'force';
     /**
      * PostgreSQL partitioning definition for this table.
      *
@@ -427,9 +431,15 @@ interface PolymorphicOptions {
      */
     discriminatorMap?: Dictionary<string>;
 }
-export interface ManyToOneOptions<Owner, Target> extends ReferenceOptions<Owner, Target>, PolymorphicOptions {
+export interface ManyToOneOptions<Owner, Target, Through = Target> extends ReferenceOptions<Owner, Target>, PolymorphicOptions {
     /** Point to the inverse side property name. */
     inversedBy?: (string & keyof Target) | ((e: Target) => any);
+    /** Resolve this read-only relation via a subquery on another entity: a pivot entity with FKs to both sides, or the target itself to pick a single item out of a to-many relation (see {@doclink relationships#to-one-relations-through-another-entity | To-one relations through another entity}). */
+    through?: () => EntityName<Through>;
+    /** Condition applied on the `through` entity. */
+    where?: FilterQuery<Through>;
+    /** Ordering applied on the `through` entity, the first matching row is used. */
+    orderBy?: QueryOrderMap<Through> | QueryOrderMap<Through>[];
     /** Wrap the entity in {@apilink Reference} wrapper. */
     ref?: boolean;
     /** Use this relation as a primary key. */
@@ -481,9 +491,15 @@ export interface OneToManyOptions<Owner, Target> extends ReferenceOptions<Owner,
     /** Point to the owning side property name. */
     mappedBy: (string & keyof Target) | ((e: Target) => any);
 }
-export interface OneToOneOptions<Owner, Target> extends Partial<Omit<OneToManyOptions<Owner, Target>, 'orderBy'>>, PolymorphicOptions {
+export interface OneToOneOptions<Owner, Target, Through = Target> extends Partial<Omit<OneToManyOptions<Owner, Target>, 'orderBy' | 'where'>>, PolymorphicOptions {
     /** Set this side as owning. Owning side is where the foreign key is defined. This option is not required if you use `inversedBy` or `mappedBy` to distinguish owning and inverse side. */
     owner?: boolean;
+    /** Resolve this read-only relation via a subquery on another entity: a pivot entity with FKs to both sides, or the target itself to pick a single item out of a to-many relation (see {@doclink relationships#to-one-relations-through-another-entity | To-one relations through another entity}). */
+    through?: () => EntityName<Through>;
+    /** Condition for {@doclink collections#declarative-partial-loading | Declarative partial loading}, or the condition applied on the `through` entity. */
+    where?: FilterQuery<Through>;
+    /** Ordering applied on the `through` entity, the first matching row is used. */
+    orderBy?: QueryOrderMap<Through> | QueryOrderMap<Through>[];
     /** Point to the inverse side property name. */
     inversedBy?: (string & keyof Target) | ((e: Target) => any);
     /** Wrap the entity in {@apilink Reference} wrapper. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.2.0-dev.14",
+  "version": "7.2.0-dev.16",
   "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",

package/platforms/Platform.d.ts

@@ -1,6 +1,6 @@
 import { EntityRepository } from '../entity/EntityRepository.js';
 import { type NamingStrategy } from '../naming-strategy/NamingStrategy.js';
-import type { Constructor, EntityMetadata, EntityProperty, IPrimaryKey, ISchemaGenerator, PopulateOptions, Primary, SimpleColumnMeta, FilterQuery, EntityValue, EntityKey } from '../typings.js';
+import type { Constructor, EntityMetadata, EntityProperty, IPrimaryKey, ISchemaGenerator, PopulateOptions, Primary, SimpleColumnMeta, FilterQuery, EntityValue, EntityKey, FormulaColumns } from '../typings.js';
 import { ExceptionConverter } from './ExceptionConverter.js';
 import type { EntityManager } from '../EntityManager.js';
 import type { Configuration } from '../utils/Configuration.js';
@@ -275,6 +275,11 @@ export declare abstract class Platform {
     formatQuery(sql: string, params: readonly any[]): string;
     /** Deep-clones embeddable data and tags it for JSON serialization. */
     cloneEmbeddable<T>(data: T): T;
+    /**
+     * Builds the correlated subquery used as the formula of a virtual to-one relation defined via `through`.
+     * @internal
+     */
+    getThroughRelationFormula(prop: EntityProperty, columns: FormulaColumns<any>): string;
     /** Initializes the platform with the ORM configuration. */
     setConfig(config: Configuration): void;
     /** Returns the current ORM configuration. */
@@ -316,6 +321,15 @@ export declare abstract class Platform {
     supportsDownMigrations(): boolean;
     /** Whether the platform supports deferred unique constraints. */
     supportsDeferredUniqueConstraints(): boolean;
+    /** Whether the platform supports row level security (PostgreSQL). */
+    supportsRowLevelSecurity(): boolean;
+    /** Whether the driver can apply the session context on every pooled connection acquire (`sessionContext: 'connection'`). */
+    supportsConnectionSessionContext(): boolean;
+    /**
+     * SQL cast suffix (e.g. `'::uuid'`, or `''` when none is needed) applied when an RLS filter reads a session
+     * variable via `current_setting()` as the given column type, or `null` if the type has no automatic cast.
+     */
+    getCurrentSettingCast(mappedType: Type<unknown>): string | null;
     /** Platform-specific validation of entity metadata. */
     validateMetadata(meta: EntityMetadata): void;
     /**

package/platforms/Platform.js

@@ -616,6 +616,14 @@ export class Platform {
         Object.defineProperty(copy, JsonProperty, { enumerable: false, value: true });
         return copy;
     }
+    /**
+     * Builds the correlated subquery used as the formula of a virtual to-one relation defined via `through`.
+     * @internal
+     */
+    /* v8 ignore next 3 */
+    getThroughRelationFormula(prop, columns) {
+        throw new Error(`${this.constructor.name} does not support the 'through' option of ${prop.name}`);
+    }
     /** Initializes the platform with the ORM configuration. */
     setConfig(config) {
         this.config = config;
@@ -722,11 +730,51 @@ export class Platform {
     supportsDeferredUniqueConstraints() {
         return true;
     }
+    /** Whether the platform supports row level security (PostgreSQL). */
+    supportsRowLevelSecurity() {
+        return false;
+    }
+    /** Whether the driver can apply the session context on every pooled connection acquire (`sessionContext: 'connection'`). */
+    supportsConnectionSessionContext() {
+        return false;
+    }
+    /**
+     * SQL cast suffix (e.g. `'::uuid'`, or `''` when none is needed) applied when an RLS filter reads a session
+     * variable via `current_setting()` as the given column type, or `null` if the type has no automatic cast.
+     */
+    getCurrentSettingCast(mappedType) {
+        return null;
+    }
     /** Platform-specific validation of entity metadata. */
     validateMetadata(meta) {
         if (meta.partitionBy && !this.supportsPartitionedTables()) {
             throw new MetadataError(`Entity ${meta.className} uses partitionBy, but ${this.constructor.name} does not support partitioned tables`);
         }
+        const declaresRls = meta.policies.length > 0 || !!meta.rowLevelSecurity;
+        if (declaresRls && !this.supportsRowLevelSecurity()) {
+            throw MetadataError.rowLevelSecurityNotSupportedByDriver(meta);
+        }
+        // STI hierarchies share a single table, so only the root may declare policies; `root` is optional-chained
+        // as `validateMetadata` is public API and tolerates partially populated metadata
+        if (declaresRls && meta.root?.inheritanceType === 'sti' && meta.root !== meta) {
+            throw MetadataError.rowLevelSecurityOnNonRootStiEntity(meta);
+        }
+        if (meta.root?.inheritanceType === 'sti' && meta.root !== meta) {
+            for (const filter of Object.values(meta.filters)) {
+                // inherited root filters share the def object; only defs declared on the child itself are a problem,
+                // as non-root STI metas never reach the schema generator and the policy would silently not exist
+                if (filter.rls && meta.root.filters[filter.name] !== filter) {
+                    throw MetadataError.rlsFilterOnNonRootStiEntity(meta, filter.name);
+                }
+            }
+        }
+        if (!this.supportsRowLevelSecurity()) {
+            for (const filter of Object.values(meta.filters)) {
+                if (filter.rls) {
+                    throw MetadataError.rlsFilterNotSupportedByDriver(meta, filter.name);
+                }
+            }
+        }
     }
     /**
      * Generates a custom order by statement given a set of in order values, eg.

package/typings.d.ts

@@ -653,6 +653,16 @@ export type SerializeDTO<T, H extends string = never, E extends string = never,
 };
 type TargetKeys<T> = T extends EntityClass<infer P> ? keyof P : keyof T;
 type PropertyName<T> = IsUnknown<T> extends false ? TargetKeys<T> : string;
+/** Resolved `through` option of a virtual to-one relation, populated during discovery. */
+export interface ThroughRelation {
+    entity: EntityClass;
+    where?: FilterQuery<any>;
+    orderBy?: QueryOrderMap<any>[];
+    /** M:1 property on the `through` entity pointing back to the owner. */
+    ownerProperty: string;
+    /** M:1 property on the `through` entity pointing to the target, undefined when the target is selected directly. */
+    targetProperty?: string;
+}
 /** Table reference object passed to formula callbacks, including alias and schema information. */
 export type FormulaTable = {
     alias: string;
@@ -710,6 +720,8 @@ export type IndexCallback<T> = (columns: Record<PropertyName<T>, string>, table:
 export type FormulaCallback<T> = (columns: FormulaColumns<T>, table: FormulaTable) => string | Raw;
 /** Callback for CHECK constraint expressions. Receives column mappings and table info. */
 export type CheckCallback<T> = (columns: SchemaColumns<T>, table: SchemaTable) => string | Raw;
+/** Callback for row level security policy expressions. Receives column mappings and table info. */
+export type PolicyCallback<T> = (columns: SchemaColumns<T>, table: SchemaTable) => string | Raw;
 /** Callback for trigger body expressions. Receives column mappings and table info. */
 export type TriggerCallback<T> = (columns: Record<PropertyName<T>, string>, table: SchemaTable) => string | Raw;
 /**
@@ -724,6 +736,28 @@ export interface CheckConstraint<T = any> {
     property?: string;
     expression: string | Raw | CheckCallback<T>;
 }
+/** Definition of a PostgreSQL row level security policy on a table. */
+export interface PolicyDef<T = any> {
+    /** Policy name. Auto-generated if omitted. */
+    name?: string;
+    /** DML command the policy applies to. Defaults to `'all'`. */
+    command?: 'select' | 'insert' | 'update' | 'delete' | 'all';
+    /** Whether the policy is permissive (OR-combined) or restrictive (AND-combined). Defaults to `'permissive'`. */
+    type?: 'permissive' | 'restrictive';
+    /** Database roles the policy applies to. Defaults to `PUBLIC`. */
+    roles?: string[];
+    /** `USING` expression filtering visible rows. Can be a string, Raw query, or callback receiving column name mappings. */
+    using?: string | Raw | PolicyCallback<T>;
+    /** `WITH CHECK` expression validating written rows. Can be a string, Raw query, or callback receiving column name mappings. */
+    check?: string | Raw | PolicyCallback<T>;
+}
+/** Per-context database session state applied for row level security (session variables and role). */
+export interface SessionContext {
+    /** Session variables set via `set_config`, typically referenced by RLS policies through `current_setting()`. `Date` values are serialized to ISO 8601. */
+    variables?: Dictionary<string | number | boolean | Date>;
+    /** Database role to switch to for the duration of the context (`set local role` / `set role`). */
+    role?: string;
+}
 /** Definition of a database trigger on a table. */
 export interface TriggerDef<T = any> {
     /** Trigger name. Auto-generated if omitted. */
@@ -1019,6 +1053,7 @@ export interface EntityProperty<Owner = any, Target = any> {
     fixedOrderColumn?: string;
     pivotTable: string;
     pivotEntity: EntityClass<Target>;
+    through?: ThroughRelation;
     joinColumns: string[];
     ownColumns: string[];
     inverseJoinColumns: string[];
@@ -1171,6 +1206,9 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     }[];
     checks: CheckConstraint<Entity>[];
     triggers: TriggerDef<Entity>[];
+    policies: PolicyDef<Entity>[];
+    /** Enables row level security on the table. `'force'` also enables it for the table owner. Implied by non-empty `policies`, unless set to `false`, which keeps the policies staged but RLS disabled. */
+    rowLevelSecurity?: boolean | 'force';
     repositoryClass?: string;
     repository: () => EntityClass<EntityRepository<any>>;
     hooks: {
@@ -1498,6 +1536,15 @@ type FilterDefResolved<T extends object = any> = {
     entity?: EntityName<T> | EntityName<T>[];
     args?: boolean;
     strict?: boolean;
+    /**
+     * Also materializes this filter as a PostgreSQL row level security policy on the entity's table, and stages the
+     * matching session variables when its params are enabled via `em.setFilterParams()`. The `cond` must be compilable
+     * to a static expression (no access to `em`/`type`/`options`, not async). Each referenced argument maps to a session
+     * variable named `mikro.<filterName>.<argName>`; pass `{ setting }` to override that name for a single-argument filter.
+     */
+    rls?: boolean | {
+        setting?: string;
+    };
 };
 /** Definition of a query filter that can be registered globally or per-entity via `@Filter()`. */
 export type FilterDef<T extends EntityName | readonly EntityName[] = any> = FilterDefResolved<EntityFromInput<T>> & {

package/typings.js

@@ -49,6 +49,7 @@ export class EntityMetadata {
         this.uniques = [];
         this.checks = [];
         this.triggers = [];
+        this.policies = [];
         this.referencingProperties = [];
         this.concurrencyCheckKeys = new Set();
         Object.assign(this, meta);

package/unit-of-work/UnitOfWork.js

@@ -472,6 +472,7 @@ export class UnitOfWork {
                 const loggerContext = Utils.merge({ id: this.#em._id }, this.#em.getLoggerContext({ disableContextResolution: true }));
                 await this.#em.getConnection('write').transactional(trx => this.persistToDatabase(groups, trx), {
                     ctx: oldTx,
+                    sessionContext: this.#em.getTransactionSessionContext(),
                     eventBroadcaster: new TransactionEventBroadcaster(this.#em),
                     loggerContext,
                 });