@mikro-orm/core 7.1.0-dev.3 → 7.1.0-dev.30

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);
@@ -159,6 +164,7 @@ export class MetadataDiscovery {
         forEachProp((m, p) => this.initGeneratedColumn(m, p));
         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) => {
             this.initDefaultValue(p);
             this.inferTypeFromDefault(p);
@@ -479,17 +485,28 @@ export class MetadataDiscovery {
             prop.polymorphic = prop2.polymorphic;
             prop.discriminator = prop2.discriminator;
             prop.discriminatorColumn = prop2.discriminatorColumn;
-            prop.discriminatorValue = prop2.discriminatorValue;
+            // For a union-target pivot each inverse side sits on one specific target class, so its
+            // discriminator value is that class's tableName. For Rails-style, prop2 has a single fixed value.
+            prop.discriminatorValue = QueryHelper.isUnionTargetPolymorphic(prop2) ? meta.tableName : prop2.discriminatorValue;
         }
         prop.referencedColumnNames ??= Utils.flatten(meta.primaryKeys.map(primaryKey => meta.properties[primaryKey].fieldNames));
-        // For polymorphic M:N, use discriminator base name for FK column (e.g., taggable_id instead of post_id)
-        if (prop.polymorphic && prop.discriminator) {
+        // Union-target polymorphic M:N: owner side is fixed (real FK), target side uses discriminator-derived names.
+        const isUnionTargetMN = QueryHelper.isUnionTargetPolymorphic(prop);
+        if (prop.polymorphic && prop.discriminator && !isUnionTargetMN) {
+            // Rails-style: owner side is polymorphic, uses discriminator base name (e.g. taggable_id instead of post_id)
             prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.#namingStrategy.joinKeyColumnName(prop.discriminator, referencedColumnName, prop.referencedColumnNames.length > 1));
         }
         else {
             prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.#namingStrategy.joinKeyColumnName(meta.root.className, referencedColumnName, meta.compositePK));
         }
-        prop.inverseJoinColumns ??= this.initManyToOneFieldName(prop, meta2.root.className);
+        if (isUnionTargetMN) {
+            // Target side uses discriminator base name (e.g. attachable_id — shared across Image/Video)
+            const targetPkCols = Utils.flatten(meta2.primaryKeys.map(pk => meta2.properties[pk].fieldNames));
+            prop.inverseJoinColumns ??= targetPkCols.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.discriminator, fieldName, targetPkCols.length > 1));
+        }
+        else {
+            prop.inverseJoinColumns ??= this.initManyToOneFieldName(prop, meta2.root.className);
+        }
     }
     isExplicitTableName(meta) {
         return meta.tableName !== this.#namingStrategy.classToTableName(meta.className);
@@ -556,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);
@@ -583,6 +606,24 @@ export class MetadataDiscovery {
                 if (prop.inversedBy) {
                     prop.targetMeta.properties[prop.inversedBy].pivotEntity = pivotMeta.class;
                 }
+                // Propagate pivotEntity to ALL inverse collections using mappedBy pointing at this
+                // owner prop. Covers three cases:
+                //   - regular inverse (Tag.posts mappedBy Post.tags) — handled by inversedBy above
+                //   - union-target inverse (Image.posts mappedBy Post.attachments) — on each polymorph target
+                //   - merged inverse (Tag.owners mappedBy [Post,Video].tags) — union collection on the target
+                const inverseCandidates = QueryHelper.isUnionTargetPolymorphic(prop)
+                    ? prop.polymorphTargets
+                    : [prop.targetMeta];
+                for (const targetMeta of inverseCandidates) {
+                    for (const inverseProp of Object.values(targetMeta.properties)) {
+                        if (inverseProp.kind === ReferenceKind.MANY_TO_MANY &&
+                            inverseProp.mappedBy === prop.name &&
+                            !inverseProp.pivotEntity) {
+                            inverseProp.pivotEntity = pivotMeta.class;
+                            inverseProp.pivotTable = pivotMeta.tableName;
+                        }
+                    }
+                }
                 return pivotMeta;
             });
         }
@@ -721,8 +762,12 @@ export class MetadataDiscovery {
                 }
             }
         }
-        // For polymorphic M:N, create discriminator column and polymorphic FK
-        if (prop.polymorphic && prop.discriminatorColumn) {
+        // Union-target polymorphic M:N: discriminator + target FK share the pivot across multiple target types
+        if (prop.discriminatorColumn && QueryHelper.isUnionTargetPolymorphic(prop)) {
+            this.defineUnionTargetPolymorphicPivotProperties(pivotMeta2, meta, prop);
+        }
+        else if (prop.polymorphic && prop.discriminatorColumn) {
+            // Rails-style polymorphic M:N: multiple owners share the pivot, single target type
             this.definePolymorphicPivotProperties(pivotMeta2, meta, prop, targetMeta);
         }
         else {
@@ -809,6 +854,33 @@ export class MetadataDiscovery {
         pivotMeta.polymorphicDiscriminatorMap ??= {};
         pivotMeta.polymorphicDiscriminatorMap[prop.discriminatorValue] = meta.class;
     }
+    /**
+     * Mirror of definePolymorphicPivotProperties for union-target M:N
+     * (e.g. Post.attachments -> Image | Video via shared pivot with a target-side discriminator).
+     *
+     * Pivot shape:
+     *   (owner_fk..., discriminator_column, target_fk...)
+     *   - owner side is a normal M:1 to the single owner entity
+     *   - target side is a discriminator column + per-target-type virtual M:1 relations
+     */
+    defineUnionTargetPolymorphicPivotProperties(pivotMeta, meta, prop) {
+        const discriminatorColumn = prop.discriminatorColumn;
+        const targets = prop.polymorphTargets;
+        pivotMeta.properties[meta.name + '_owner'] = this.definePivotProperty(prop, meta.name + '_owner', meta.class, prop.discriminator, true, false);
+        const discriminatorProp = this.createPivotScalarProperty(discriminatorColumn, [this.#platform.getVarcharTypeDeclarationSQL(prop)], [discriminatorColumn], { type: 'string', primary: true, nullable: false });
+        this.initFieldName(discriminatorProp);
+        pivotMeta.properties[discriminatorColumn] = discriminatorProp;
+        const firstTargetColumnTypes = this.getPrimaryKeyColumnTypes(targets[0]);
+        pivotMeta.properties[prop.discriminator] = this.createPivotScalarProperty(prop.discriminator, firstTargetColumnTypes, [...prop.inverseJoinColumns], { type: targets[0].className, primary: true, nullable: false });
+        pivotMeta.polymorphicDiscriminatorMap ??= {};
+        for (const targetMeta of targets) {
+            const relationName = `${prop.discriminator}_${targetMeta.tableName}`;
+            const relation = this.definePolymorphicOwnerRelation(prop, relationName, targetMeta);
+            relation.joinColumns = relation.fieldNames = relation.ownColumns = [...prop.inverseJoinColumns];
+            pivotMeta.properties[relationName] = relation;
+            pivotMeta.polymorphicDiscriminatorMap[targetMeta.tableName] = targetMeta.class;
+        }
+    }
     /**
      * Create a virtual M:1 relation from pivot to a polymorphic owner entity.
      * This enables single-query join loading for inverse-side polymorphic M:N.
@@ -961,6 +1033,7 @@ export class MetadataDiscovery {
         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);
@@ -1045,11 +1118,15 @@ export class MetadataDiscovery {
         prop.discriminatorColumn ??= this.#namingStrategy.discriminatorColumnName(prop.discriminator);
         prop.createForeignKeyConstraint = false;
         const isToOne = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind);
-        if (isToOne) {
+        const isUnionTargetMN = prop.kind === ReferenceKind.MANY_TO_MANY && Array.isArray(prop.target);
+        if (isToOne || isUnionTargetMN) {
             const types = prop.type.split(/ ?\| ?/);
             prop.polymorphTargets = discovered.filter(m => types.includes(m.className) && !m.embeddable);
             prop.targetMeta = prop.polymorphTargets[0];
             prop.referencedPKs = prop.targetMeta?.primaryKeys;
+            if (isUnionTargetMN && prop.polymorphTargets.length < 2) {
+                throw new MetadataError(`${meta.className}.${prop.name} union-target polymorphic M:N requires at least two target entity types; use a regular M:N relation for a single target.`);
+            }
         }
         if (prop.discriminatorMap) {
             const normalizedMap = {};
@@ -1065,7 +1142,7 @@ export class MetadataDiscovery {
             }
             prop.discriminatorMap = normalizedMap;
         }
-        else if (isToOne) {
+        else if (isToOne || isUnionTargetMN) {
             prop.discriminatorMap = {};
             const tableNameToTarget = new Map();
             for (const target of prop.polymorphTargets) {
@@ -1187,6 +1264,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);
@@ -1227,12 +1317,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;
@@ -1281,6 +1383,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;
@@ -1296,10 +1412,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;
@@ -1520,6 +1636,27 @@ export class MetadataDiscovery {
             }
         }
     }
+    initTriggers(meta) {
+        if (meta.triggers.length === 0) {
+            return;
+        }
+        const columns = meta.createSchemaColumnMappingObject();
+        const table = this.createSchemaTable(meta);
+        for (const trigger of meta.triggers) {
+            if (trigger.body && trigger.expression) {
+                throw new MetadataError(`Trigger "${trigger.name ?? '(unnamed)'}" on entity ${meta.className} defines both 'body' and 'expression'. Use one or the other.`);
+            }
+            if (!trigger.body && !trigger.expression) {
+                throw new MetadataError(`Trigger "${trigger.name ?? '(unnamed)'}" on entity ${meta.className} must define either 'body' or 'expression'.`);
+            }
+            trigger.name ??= this.#namingStrategy.indexName(meta.tableName, trigger.events, 'trigger');
+            trigger.forEach ??= 'row';
+            if (trigger.body instanceof Function) {
+                trigger.body = trigger.body(columns, table);
+            }
+        }
+        meta.hasTriggers = true;
+    }
     initGeneratedColumn(meta, prop) {
         if (!prop.generated && prop.columnTypes) {
             const match = /(.*) generated always as (.*)/i.exec(prop.columnTypes[0]);
@@ -1646,7 +1783,14 @@ export class MetadataDiscovery {
                 return (!Type.getType(t[type]).ensureComparable(meta, prop) && (prop.type === t[type] || brand === type));
             });
             if (type) {
-                prop.type = type === 'datetime' ? 'Date' : type;
+                if (prop.array) {
+                    // built-in type + array: true — force-create instance for ArrayType wrapping
+                    prop.customType = new prop.type();
+                    prop.type = prop.customType.constructor.name;
+                }
+                else {
+                    prop.type = type === 'datetime' ? 'Date' : type;
+                }
             }
             else {
                 prop.customType = new prop.type();
@@ -1656,6 +1800,31 @@ export class MetadataDiscovery {
         if (simple) {
             return;
         }
+        if (prop.array &&
+            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;
+            innerType.meta = meta;
+            innerType.prop = prop;
+            if (!prop.columnTypes) {
+                const arrayDecl = this.#platform.getArrayDeclarationSQL();
+                if (arrayDecl.endsWith('[]')) {
+                    // native array support (e.g. postgres) — use inner type's column type with [] suffix
+                    prop.columnTypes = [innerType.getColumnType(prop, this.#platform) + '[]'];
+                }
+                else {
+                    // non-native (e.g. mysql, sqlite) — store as text/clob
+                    prop.columnTypes = [arrayDecl];
+                }
+            }
+            const platform = this.#platform;
+            prop.customType = new t.array(v => innerType.convertToJSValue(v, platform), v => innerType.convertToDatabaseValue(v, platform));
+            prop.type = prop.customType.constructor.name;
+        }
         if (!prop.customType && ['json', 'jsonb'].includes(prop.type?.toLowerCase())) {
             prop.customType = new t.json();
         }
@@ -1671,7 +1840,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

@@ -7,6 +7,30 @@ import type { MetadataStorage } from './MetadataStorage.js';
 export declare class MetadataValidator {
     validateEntityDefinition<T>(metadata: MetadataStorage, name: EntityName<T>, options: MetadataDiscoveryOptions): 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) {
@@ -111,6 +116,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 +348,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
@@ -171,6 +359,15 @@ export class MetadataValidator {
     }
     validatePolymorphicTargets(meta, prop) {
         const targets = prop.polymorphTargets;
+        // Union-target M:N stores one scalar target FK per pivot row, so composite-PK targets
+        // can't round-trip through this schema.
+        if (prop.kind === ReferenceKind.MANY_TO_MANY && targets.length > 1) {
+            for (const target of targets) {
+                if (target.compositePK) {
+                    throw MetadataError.incompatiblePolymorphicTargets(meta, prop, targets[0], target, `${target.className} has a composite primary key; union-target polymorphic M:N does not support composite-PK targets.`);
+                }
+            }
+        }
         // Validate targetKey exists and is compatible across all targets
         if (prop.targetKey) {
             for (const target of targets) {
@@ -349,6 +546,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');