@mikro-orm/core 7.1.0-dev.8 → 7.1.0

package/entity/defineEntity.js

@@ -173,6 +173,16 @@ export class UniversalPropertyOptionsBuilder {
     ref() {
         return this.assignOptions({ ref: true });
     }
+    /**
+     * Mark a to-one relation (`m:1`/`1:1`) as a {@apilink LazyRef} — the runtime value stays a plain entity
+     * (no `Reference` wrapper) but the TypeScript type restricts access to the primary key until `Loaded<>`
+     * narrows it. Type-level only; does not set `ref: true`. Not compatible with `.ref()` or `.mapToPk()` —
+     * those chains are rejected in both directions at compile time.
+     */
+    lazyRef() {
+        // purely type-level — no runtime metadata change
+        return this;
+    }
     /**
      * Set to true to omit the property when {@link https://mikro-orm.io/docs/serializing Serializing}.
      */
@@ -306,6 +316,13 @@ export class UniversalPropertyOptionsBuilder {
     comment(comment) {
         return this.assignOptions({ comment });
     }
+    /**
+     * Specify column-level collation for {@link https://mikro-orm.io/docs/schema-generator Schema Generator}. (SQL only)
+     * Emits a `COLLATE` clause on the column definition; the accepted collation names are dialect-specific.
+     */
+    collation(collation) {
+        return this.assignOptions({ collation });
+    }
     /** mysql only */
     extra(extra) {
         return this.assignOptions({ extra });

package/entity/utils.js

@@ -94,11 +94,10 @@ export function applyPopulateHints(populate, hints) {
         if (!entry) {
             continue;
         }
-        if (hint.strategy != null) {
-            entry.strategy = hint.strategy;
-        }
-        if (hint.joinType != null) {
-            entry.joinType = hint.joinType;
+        for (const key of Object.keys(hint)) {
+            if (hint[key] != null) {
+                entry[key] = hint[key];
+            }
         }
     }
 }

package/enums.d.ts

@@ -1,5 +1,5 @@
 import type { EntityKey, ExpandProperty } from './typings.js';
-import type { Transaction } from './connections/Connection.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. */
 export declare enum FlushMode {
@@ -307,6 +307,13 @@ export interface TransactionOptions {
     flushMode?: FlushMode | `${FlushMode}`;
     ignoreNestedTransactions?: boolean;
     loggerContext?: LogContext;
+    /**
+     * `AbortSignal` cancelling every query within the transaction (including the implicit flush).
+     * Cancelling mid-transaction triggers a rollback once the in-flight query settles.
+     */
+    signal?: AbortSignal;
+    /** Cancellation strategy paired with {@link signal}. */
+    inflightQueryAbortStrategy?: InflightQueryAbortStrategy;
 }
 export declare abstract class PlainObject {
 }

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, IndexName, IndexColumns, WithUsingOptions, IMigrationRunner, IEntityGenerator, ISeedManager, SeederObject, IMigratorStorage, RequiredEntityData, CheckCallback, TriggerCallback, IndexCallback, FormulaCallback, FormulaTable, SchemaTable, SchemaColumns, SimpleColumnMeta, Rel, Ref, 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, 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, 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 * from './enums.js';
 export * from './errors.js';
 export * from './exceptions.js';

package/metadata/EntitySchema.js

@@ -85,6 +85,9 @@ export class EntitySchema {
         if (options.items instanceof Function) {
             options.items = Utils.extractEnumValues(options.items());
         }
+        else if (options.items && !Array.isArray(options.items) && typeof options.items === 'object') {
+            options.items = Utils.extractEnumValues(options.items);
+        }
         // enum arrays are simple numeric/string arrays, the constraint is enforced in the custom type only
         if (options.array && !options.type) {
             options.type = new EnumArrayType(`${this._meta.className}.${name}`, options.items);
@@ -251,6 +254,21 @@ export class EntitySchema {
             return this;
         }
         this.setClass(this._meta.class);
+        // `discriminator` is the property name on the entity / embeddable; `discriminatorColumn` is an
+        // optional column-name override on that property. For backward compat, when only
+        // `discriminatorColumn` is given (legacy), it is treated as the property name. Once normalized,
+        // `meta.discriminatorColumn` always holds the property name (so existing readers keep working),
+        // and `meta.discriminatorFieldName` carries the explicit column override (if any).
+        if (this._meta.discriminator &&
+            this._meta.discriminatorColumn &&
+            this._meta.discriminator !== this._meta.discriminatorColumn) {
+            this._meta.discriminatorFieldName = this._meta.discriminatorColumn;
+            this._meta.discriminatorColumn = this._meta.discriminator;
+        }
+        else {
+            this._meta.discriminatorColumn ??= this._meta.discriminator;
+            this._meta.discriminator ??= this._meta.discriminatorColumn;
+        }
         // Abstract TPT entities keep their name because they have their own table
         const isTPT = this._meta.inheritance === 'tpt' || this.isPartOfTPTHierarchy();
         if (this._meta.abstract && !this._meta.discriminatorColumn && !isTPT) {

package/metadata/MetadataDiscovery.d.ts

@@ -76,6 +76,7 @@ export declare class MetadataDiscovery {
     private initPolyEmbeddables;
     private initPolymorphicRelation;
     private initEmbeddables;
+    private sameRelationTargetRoot;
     private initSingleTableInheritance;
     /**
      * First pass of TPT initialization: sets up hierarchy relationships

package/metadata/MetadataDiscovery.js

@@ -114,7 +114,12 @@ export class MetadataDiscovery {
             }
             else {
                 const name = prop.name;
-                if (prop.kind === ReferenceKind.SCALAR || prop.kind === ReferenceKind.EMBEDDED) {
+                // For to-one relations, only swap to the accessor for the documented
+                // backing-field convention (a `_`-prefixed property like `_draft` paired
+                // with `accessor: 'draft'`). The non-prefixed sibling-helper pattern
+                // (`author` + `accessor: 'authorId'`) keeps the property name as the
+                // canonical FK column source, so this stays non-breaking.
+                if (prop.kind === ReferenceKind.SCALAR || prop.kind === ReferenceKind.EMBEDDED || name.startsWith('_')) {
                     prop.name = prop.accessor;
                 }
                 this.initRelation(prop);
@@ -568,6 +573,12 @@ export class MetadataDiscovery {
             }
         }
         meta.forceConstructor ??= this.shouldForceConstructorUsage(meta);
+        // Fail fast when the platform rejects the metadata, so users see the platform-specific
+        // error (e.g. "SqlitePlatform does not support partitioned tables") instead of a
+        // downstream core validator message that assumes partitioning is supported.
+        if (meta.partitionBy && !this.#platform.supportsPartitionedTables()) {
+            this.#platform.validateMetadata(meta);
+        }
         this.#validator.validateEntityDefinition(this.#metadata, meta.class, this.#config.get('discovery'));
         for (const prop of Object.values(meta.properties)) {
             this.initNullability(prop);
@@ -594,6 +605,10 @@ export class MetadataDiscovery {
                 prop.pivotEntity = pivotMeta.class;
                 if (prop.inversedBy) {
                     prop.targetMeta.properties[prop.inversedBy].pivotEntity = pivotMeta.class;
+                    const targetRoot = prop.targetMeta.root;
+                    if (targetRoot !== prop.targetMeta && targetRoot.properties[prop.inversedBy]) {
+                        targetRoot.properties[prop.inversedBy].pivotEntity = pivotMeta.class;
+                    }
                 }
                 // Propagate pivotEntity to ALL inverse collections using mappedBy pointing at this
                 // owner prop. Covers three cases:
@@ -1019,10 +1034,14 @@ export class MetadataDiscovery {
                 meta.propertyOrder.set(prop.name, (order += 0.01));
             });
         }
-        meta.indexes = Utils.unique([...base.indexes, ...meta.indexes]);
-        meta.uniques = Utils.unique([...base.uniques, ...meta.uniques]);
-        meta.checks = Utils.unique([...base.checks, ...meta.checks]);
-        meta.triggers = Utils.unique([...base.triggers, ...meta.triggers]);
+        // TPT children have their own tables that don't contain the parent's columns,
+        // so propagating parent indexes/uniques/checks/triggers would target missing columns.
+        if (meta.inheritanceType !== 'tpt' || !meta.tptParent) {
+            meta.indexes = Utils.unique([...base.indexes, ...meta.indexes]);
+            meta.uniques = Utils.unique([...base.uniques, ...meta.uniques]);
+            meta.checks = Utils.unique([...base.checks, ...meta.checks]);
+            meta.triggers = Utils.unique([...base.triggers, ...meta.triggers]);
+        }
         const pks = Object.values(meta.properties)
             .filter(p => p.primary)
             .map(p => p.name);
@@ -1253,6 +1272,19 @@ export class MetadataDiscovery {
             });
         }
     }
+    sameRelationTargetRoot(rootProp, prop) {
+        if (!rootProp || rootProp.kind !== prop.kind) {
+            return false;
+        }
+        if (prop.kind !== ReferenceKind.MANY_TO_ONE &&
+            prop.kind !== ReferenceKind.ONE_TO_ONE &&
+            prop.kind !== ReferenceKind.ONE_TO_MANY &&
+            prop.kind !== ReferenceKind.MANY_TO_MANY) {
+            return false;
+        }
+        const aRoot = this.#metadata.getByClassName(prop.type, false)?.root;
+        return aRoot != null && aRoot === this.#metadata.getByClassName(rootProp.type, false)?.root;
+    }
     initSingleTableInheritance(meta, metadata) {
         if (meta.root !== meta && !meta.__processed) {
             meta.root = metadata.find(m => m.class === meta.root.class);
@@ -1293,12 +1325,24 @@ export class MetadataDiscovery {
         Object.values(meta.properties).forEach(prop => {
             const newProp = { ...prop };
             const rootProp = meta.root.properties[prop.name];
+            // A child that narrows a relation to a subclass of the root's declared
+            // target (same STI hierarchy) shares the FK column with the root; treat
+            // that as matching so the rename branch below doesn't run (which would
+            // crash — `targetMeta` is only populated later, in `initRelation`).
+            const narrowedRelationOverride = rootProp != null && rootProp.type !== prop.type && this.sameRelationTargetRoot(rootProp, prop);
             // stiMerged is set during inlineProperties when a property was merged
             // from multiple polymorphic variants with different types. The flag is
             // cleared implicitly when the first child claims the root property via
             // addProperty below, so subsequent children correctly trigger renaming.
-            const typesMatch = rootProp?.type === prop.type || rootProp?.stiMerged === true;
+            const typesMatch = rootProp?.type === prop.type || rootProp?.stiMerged === true || narrowedRelationOverride;
+            // Inverse-side relations (1:m, inverse m:n) have no FK column on this
+            // entity, so the rename branch — which exists to disambiguate physical
+            // columns shared across STI children — doesn't apply. Skipping it also
+            // avoids crashing on `[...rootProp.fieldNames]` since fieldNames is
+            // never populated for inverse-side properties.
+            const isInverseSideRelation = prop.kind === ReferenceKind.ONE_TO_MANY || (prop.kind === ReferenceKind.MANY_TO_MANY && !prop.owner);
             if (rootProp &&
+                !isInverseSideRelation &&
                 (!typesMatch ||
                     (rootProp.fieldNames && prop.fieldNames && !compareArrays(rootProp.fieldNames, prop.fieldNames)))) {
                 const name = newProp.name;
@@ -1347,6 +1391,20 @@ export class MetadataDiscovery {
             }
             newProp.nullable = true;
             newProp.inherited = !rootProp;
+            // For narrowed relation overrides, keep the root's declaration intact so
+            // the full target union (e.g. `Food`) is preserved for populates from the
+            // abstract root — otherwise the last child processed would win.
+            if (narrowedRelationOverride) {
+                return;
+            }
+            // STI siblings can declare the same property name on inverse-side relations
+            // pointing to disjoint targets (e.g. `Dog.items → DogItem` and
+            // `Cat.items → CatItem` with no shared base). There's no physical column
+            // to manage at root, and propagating would clobber the first child's
+            // declaration; each child keeps its local typed property instead.
+            if (isInverseSideRelation && rootProp && rootProp.type !== prop.type) {
+                return;
+            }
             meta.root.addProperty(newProp);
         });
         meta.tableName = meta.root.tableName;
@@ -1362,10 +1420,10 @@ export class MetadataDiscovery {
         if (meta.root !== meta) {
             meta.root = metadata.find(m => m.class === meta.root.class);
         }
-        const inheritance = meta.inheritance;
-        if (inheritance === 'tpt' && meta.root === meta) {
-            meta.inheritanceType = 'tpt';
-            meta.tptChildren = [];
+        // init the root eagerly so children iterated before the root (e.g. alphabetical glob order) still get linked
+        if (meta.root.inheritance === 'tpt' && meta.root.inheritanceType !== 'tpt') {
+            meta.root.inheritanceType = 'tpt';
+            meta.root.tptChildren ??= [];
         }
         if (meta.root.inheritanceType !== 'tpt') {
             return;
@@ -1524,13 +1582,18 @@ export class MetadataDiscovery {
         });
     }
     createDiscriminatorProperty(meta) {
-        meta.addProperty({
+        const prop = {
             name: meta.discriminatorColumn,
             type: 'string',
             enum: true,
             kind: ReferenceKind.SCALAR,
             userDefined: false,
-        });
+        };
+        // honor the column-name override set via `discriminatorColumn` when `discriminator` is also given
+        if (meta.discriminatorFieldName) {
+            prop.fieldName = meta.discriminatorFieldName;
+        }
+        meta.addProperty(prop);
     }
     initAutoincrement(meta) {
         const pks = meta.getPrimaryProps();
@@ -1553,7 +1616,7 @@ export class MetadataDiscovery {
         const table = this.createSchemaTable(meta);
         for (const check of meta.checks) {
             const fieldNames = check.property ? meta.properties[check.property].fieldNames : [];
-            check.name ??= this.#namingStrategy.indexName(meta.tableName, fieldNames, 'check');
+            check.name ??= this.#platform.getIndexName(meta.tableName, fieldNames, 'check');
             if (check.expression instanceof Function) {
                 check.expression = check.expression(columns, table);
             }
@@ -1578,7 +1641,7 @@ export class MetadataDiscovery {
                 }
                 if (expression) {
                     meta.checks.push({
-                        name: this.#namingStrategy.indexName(meta.tableName, prop.fieldNames, 'check'),
+                        name: this.#platform.getIndexName(meta.tableName, prop.fieldNames, 'check'),
                         property: prop.name,
                         expression,
                     });
@@ -1754,6 +1817,7 @@ export class MetadataDiscovery {
             prop.customType &&
             !(prop.customType instanceof t.array) &&
             !(prop.customType instanceof t.enumArray) &&
+            !(prop.customType instanceof t.json) &&
             prop.kind === ReferenceKind.SCALAR) {
             const innerType = prop.customType;
             innerType.platform = this.#platform;
@@ -1789,7 +1853,7 @@ export class MetadataDiscovery {
         if (!prop.customType && prop.array && prop.items) {
             prop.customType = new t.enumArray(`${meta.className}.${prop.name}`, prop.items);
         }
-        const isArray = prop.type?.toLowerCase() === 'array' || prop.type?.toString().endsWith('[]');
+        const isArray = prop.array || prop.type?.toLowerCase() === 'array' || prop.type?.toString().endsWith('[]');
         if (objectEmbeddable && !prop.customType && isArray) {
             prop.customType = new t.json();
         }

package/metadata/MetadataValidator.d.ts

@@ -1,4 +1,5 @@
 import type { EntityMetadata, EntityName } from '../typings.js';
+import type { Routine } from './Routine.js';
 import { type MetadataDiscoveryOptions } from '../utils/Configuration.js';
 import type { MetadataStorage } from './MetadataStorage.js';
 /**
@@ -6,7 +7,32 @@ import type { MetadataStorage } from './MetadataStorage.js';
  */
 export declare class MetadataValidator {
     validateEntityDefinition<T>(metadata: MetadataStorage, name: EntityName<T>, options: MetadataDiscoveryOptions): void;
+    validateRoutineDefinition(routine: Routine): void;
     validateDiscovered(discovered: EntityMetadata[], options: MetadataDiscoveryOptions): void;
+    private validatePartitioning;
+    /**
+     * Find the first partition name whose normalized form (case-folded for unquoted segments,
+     * quoted segments preserved) has already been seen. Returns the offending name in its
+     * original form for the error message.
+     */
+    private findDuplicatePartitionName;
+    /**
+     * Partition names may be bare (`child`), schema-qualified (`schema.child`), or use quoted
+     * identifiers (`"my.schema"."child"`). Reject anything with more than one unquoted `.`.
+     */
+    private hasValidPartitionName;
+    private hasPartitionExpression;
+    private validatePartitionKeyConstraints;
+    /**
+     * Returns the list of physical field names that a partition expression references, or
+     * `undefined` when the expression is opaque (callback, or raw SQL like `date_trunc('day', x)`
+     * that we cannot statically parse). Opaque expressions intentionally bypass the primary-key /
+     * unique-constraint coverage checks — users are trusted to ensure the referenced columns are
+     * part of the partition key, since PostgreSQL will surface the violation at DDL execution.
+     */
+    private getPartitionKeyFields;
+    private resolvePartitionKeyField;
+    private getConstraintFields;
     private validateReference;
     private validateTargetKey;
     /**

package/metadata/MetadataValidator.js

@@ -1,4 +1,5 @@
 import { Utils } from '../utils/Utils.js';
+import { normalizePartitionNameForComparison, splitCommaSeparatedIdentifiers } from '../utils/partition-utils.js';
 import { MetadataError } from '../errors.js';
 import { ReferenceKind } from '../enums.js';
 /**
@@ -28,6 +29,9 @@ export class MetadataValidator {
         // Virtual entities (expression without view flag) have restrictions - no PKs, limited relation types
         // Note: meta.virtual is set later in sync(), so we check for expression && !view here
         if (meta.virtual || (meta.expression && !meta.view)) {
+            if (meta.partitionBy) {
+                throw new MetadataError(`Virtual entity ${meta.className} cannot define partitionBy`);
+            }
             for (const prop of Utils.values(meta.properties)) {
                 if (![ReferenceKind.SCALAR, ReferenceKind.EMBEDDED, ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
                     throw new MetadataError(`Only scalars, embedded properties and to-many relations are allowed inside virtual entity. Found '${prop.kind}' in ${meta.className}.${prop.name}`);
@@ -46,6 +50,7 @@ export class MetadataValidator {
         this.validateDuplicateFieldNames(meta, options);
         this.validateIndexes(meta, meta.indexes ?? [], 'index');
         this.validateIndexes(meta, meta.uniques ?? [], 'unique');
+        this.validatePartitioning(meta);
         this.validatePropertyNames(meta);
         for (const prop of Utils.values(meta.properties)) {
             if (prop.kind !== ReferenceKind.SCALAR) {
@@ -57,6 +62,41 @@ export class MetadataValidator {
             }
         }
     }
+    validateRoutineDefinition(routine) {
+        if (typeof routine.name !== 'string' || routine.name.trim() === '') {
+            throw new MetadataError(`Routine is missing the required 'name' option.`);
+        }
+        if (!routine.type) {
+            throw new MetadataError(`Routine ${routine.name} is missing the required 'type' option ('procedure' | 'function').`);
+        }
+        if (routine.body != null && routine.expression != null) {
+            throw new MetadataError(`Routine ${routine.name} defines both 'body' and 'expression'. Use one or the other.`);
+        }
+        if (routine.body == null && routine.expression == null && routine.bodyJs == null) {
+            throw new MetadataError(`Routine ${routine.name} must define a 'body', 'expression', or 'bodyJs'.`);
+        }
+        if (routine.type === 'function' && routine.returns == null) {
+            throw new MetadataError(`Function routine ${routine.name} must declare a 'returns' option.`);
+        }
+        if (routine.type === 'procedure' && routine.bodyJs != null) {
+            throw new MetadataError(`Routine ${routine.name} declares 'bodyJs' on a procedure. JS fallbacks are only supported for functions — SQLite has no analog for stored procedures.`);
+        }
+        for (const param of routine.params) {
+            const dir = param.direction;
+            if (dir !== 'in' && dir !== 'out' && dir !== 'inout') {
+                throw new MetadataError(`Routine ${routine.name}.${param.name} has invalid direction '${dir}'. Expected 'in', 'out', or 'inout'.`);
+            }
+            if ((dir === 'out' || dir === 'inout') && !param.ref) {
+                throw new MetadataError(`Routine ${routine.name}.${param.name} is declared as '${dir}' but missing 'ref: true'. OUT/INOUT parameters must be passed as ScalarReference.`);
+            }
+            if (dir === 'in' && param.ref) {
+                throw new MetadataError(`Routine ${routine.name}.${param.name} declares 'ref: true' on an IN parameter. ScalarReference wrapping is only meaningful for OUT/INOUT parameters.`);
+            }
+            if (routine.type === 'function' && dir !== 'in') {
+                throw new MetadataError(`Function routine ${routine.name}.${param.name} declares direction '${dir}'. Functions only support IN parameters — use a procedure for OUT/INOUT semantics.`);
+            }
+        }
+    }
     validateDiscovered(discovered, options) {
         if (discovered.length === 0 && options.warnWhenNoEntities) {
             throw MetadataError.noEntityDiscovered();
@@ -111,6 +151,189 @@ export class MetadataValidator {
             }
         });
     }
+    validatePartitioning(meta) {
+        if (!meta.partitionBy) {
+            return;
+        }
+        if (!this.hasPartitionExpression(meta.partitionBy.expression)) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: missing expression`);
+        }
+        // Inheritance (STI/TPT) and partitioning both drive table layout, so combining them would
+        // require non-trivial DDL coordination that the schema generator does not produce today.
+        const hasInheritance = !!meta.root.discriminatorColumn || meta.root.inheritanceType === 'tpt' || meta.root.inheritance === 'tpt';
+        if (hasInheritance) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: combining partitioning with inheritance is not supported`);
+        }
+        this.validatePartitionKeyConstraints(meta);
+        if (meta.partitionBy.type === 'hash') {
+            const { partitions } = meta.partitionBy;
+            if (Array.isArray(partitions)) {
+                if (partitions.length === 0) {
+                    throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: hash partition name list must not be empty`);
+                }
+                const blank = partitions.find(name => typeof name !== 'string' || !name.trim());
+                if (blank !== undefined) {
+                    throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: hash partition names must be non-empty strings`);
+                }
+                const ambiguous = partitions.find(name => !this.hasValidPartitionName(name));
+                if (ambiguous) {
+                    throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: partition name '${ambiguous}' contains more than one '.' — use at most one '.' to separate schema from table`);
+                }
+                const duplicate = this.findDuplicatePartitionName(partitions);
+                if (duplicate !== undefined) {
+                    throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: duplicate hash partition name '${duplicate}'`);
+                }
+                return;
+            }
+            if (typeof partitions !== 'number' || !Number.isInteger(partitions) || partitions < 1) {
+                throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: hash partition count must be a positive integer`);
+            }
+            return;
+        }
+        if (!Array.isArray(meta.partitionBy.partitions) || meta.partitionBy.partitions.length === 0) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: list/range partitions must be a non-empty array`);
+        }
+        if (meta.partitionBy.partitions.some(partition => !partition.values?.trim())) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: every partition must define values`);
+        }
+        const ambiguousName = meta.partitionBy.partitions.find(partition => partition.name != null && !this.hasValidPartitionName(partition.name));
+        if (ambiguousName) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: partition name '${ambiguousName.name}' contains more than one '.' — use at most one '.' to separate schema from table`);
+        }
+        // Include auto-generated default names (`${tableName}_${index}`, matching
+        // `createExplicitPartitions` in the sql package) so an explicit name that collides with
+        // an unnamed peer's default is caught here rather than at DDL execution time.
+        const resolvedNames = meta.partitionBy.partitions.map((partition, index) => partition.name ?? `${meta.tableName}_${index}`);
+        const duplicate = this.findDuplicatePartitionName(resolvedNames);
+        if (duplicate !== undefined) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: duplicate partition name '${duplicate}'`);
+        }
+    }
+    /**
+     * Find the first partition name whose normalized form (case-folded for unquoted segments,
+     * quoted segments preserved) has already been seen. Returns the offending name in its
+     * original form for the error message.
+     */
+    findDuplicatePartitionName(names) {
+        const seen = new Set();
+        for (const name of names) {
+            const normalized = normalizePartitionNameForComparison(name);
+            if (seen.has(normalized)) {
+                return name;
+            }
+            seen.add(normalized);
+        }
+        return undefined;
+    }
+    /**
+     * Partition names may be bare (`child`), schema-qualified (`schema.child`), or use quoted
+     * identifiers (`"my.schema"."child"`). Reject anything with more than one unquoted `.`.
+     */
+    hasValidPartitionName(name) {
+        let depth = 0;
+        let dots = 0;
+        for (let i = 0; i < name.length; i++) {
+            const ch = name[i];
+            if (ch === '"') {
+                if (name[i + 1] === '"') {
+                    i++;
+                    continue;
+                }
+                depth = depth === 0 ? 1 : 0;
+                continue;
+            }
+            if (ch === '.' && depth === 0) {
+                dots++;
+            }
+        }
+        return dots <= 1;
+    }
+    hasPartitionExpression(expression) {
+        if (expression == null) {
+            return false;
+        }
+        if (typeof expression === 'function') {
+            return true;
+        }
+        if (Array.isArray(expression)) {
+            return expression.length > 0 && expression.every(key => typeof key === 'string' && key.trim().length > 0);
+        }
+        return String(expression).trim().length > 0;
+    }
+    validatePartitionKeyConstraints(meta) {
+        const partitionFields = this.getPartitionKeyFields(meta);
+        if (!partitionFields?.length) {
+            return;
+        }
+        const primaryKeyFields = meta.root.getPrimaryProps().flatMap(prop => prop.fieldNames);
+        if (partitionFields.some(field => !primaryKeyFields.includes(field))) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: primary key must include partition key columns '${partitionFields.join("', '")}'`);
+        }
+        for (const prop of Object.values(meta.root.properties)) {
+            if (!prop.unique || !prop.fieldNames?.length) {
+                continue;
+            }
+            if (partitionFields.some(field => !prop.fieldNames.includes(field))) {
+                throw new MetadataError(`Entity ${meta.root.className} has invalid partitionBy option: unique property ${meta.root.className}.${prop.name} must include partition key columns '${partitionFields.join("', '")}'`);
+            }
+        }
+        for (const unique of meta.root.uniques ?? []) {
+            const fields = this.getConstraintFields(meta.root, unique.properties);
+            if (!fields?.length) {
+                continue;
+            }
+            if (partitionFields.some(field => !fields.includes(field))) {
+                const constraint = unique.name ? `unique constraint '${unique.name}'` : 'unique constraint';
+                throw new MetadataError(`Entity ${meta.root.className} has invalid partitionBy option: ${constraint} must include partition key columns '${partitionFields.join("', '")}'`);
+            }
+        }
+    }
+    /**
+     * Returns the list of physical field names that a partition expression references, or
+     * `undefined` when the expression is opaque (callback, or raw SQL like `date_trunc('day', x)`
+     * that we cannot statically parse). Opaque expressions intentionally bypass the primary-key /
+     * unique-constraint coverage checks — users are trusted to ensure the referenced columns are
+     * part of the partition key, since PostgreSQL will surface the violation at DDL execution.
+     */
+    getPartitionKeyFields(meta) {
+        const expression = meta.partitionBy?.expression;
+        if (!expression || typeof expression === 'function') {
+            return undefined;
+        }
+        if (Array.isArray(expression)) {
+            return expression.map(key => this.resolvePartitionKeyField(meta, key));
+        }
+        const keys = splitCommaSeparatedIdentifiers(String(expression).trim());
+        if (!keys) {
+            return undefined;
+        }
+        return keys.map(key => this.resolvePartitionKeyField(meta, key));
+    }
+    resolvePartitionKeyField(meta, key) {
+        const trimmed = key.trim().replaceAll('"', '');
+        if (!trimmed) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: empty partition key`);
+        }
+        const prop = meta.root.properties[trimmed] ??
+            Object.values(meta.root.properties).find(candidate => candidate.fieldNames?.length === 1 && candidate.fieldNames[0] === trimmed);
+        if (!prop) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: unknown partition key '${key.trim()}'`);
+        }
+        if (prop.fieldNames?.length !== 1) {
+            throw new MetadataError(`Entity ${meta.className} has invalid partitionBy option: partition key '${key.trim()}' maps to multiple columns ('${prop.fieldNames?.join("', '")}'); list them explicitly as partition keys`);
+        }
+        return prop.fieldNames[0];
+    }
+    getConstraintFields(meta, properties) {
+        if (!properties) {
+            return undefined;
+        }
+        const fields = Utils.asArray(properties).flatMap(propName => {
+            const prop = meta.root.properties[propName];
+            return prop?.fieldNames ?? [];
+        });
+        return fields.length > 0 ? fields : undefined;
+    }
     validateReference(meta, prop, options) {
         // references do have types
         if (!prop.type) {
@@ -160,7 +383,7 @@ export class MetadataValidator {
      * Composite unique constraints are not sufficient for targetKey.
      */
     isPropertyUnique(prop, meta) {
-        if (prop.unique) {
+        if (prop.unique || (prop.primary && meta.primaryKeys.length === 1)) {
             return true;
         }
         // Check for single-property unique constraint via @Unique decorator
@@ -358,6 +581,10 @@ export class MetadataValidator {
         if (!meta.expression) {
             throw MetadataError.viewEntityWithoutExpression(meta);
         }
+        // Views are not partitionable - reject explicitly instead of silently ignoring
+        if (meta.partitionBy) {
+            throw new MetadataError(`View entity ${meta.className} cannot define partitionBy`);
+        }
         // Validate indexes if present
         this.validateIndexes(meta, meta.indexes ?? [], 'index');
         this.validateIndexes(meta, meta.uniques ?? [], 'unique');