@mikro-orm/core 7.1.0-dev.15 → 7.1.0-dev.16

package/metadata/MetadataDiscovery.js

@@ -568,6 +568,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);

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) {
@@ -358,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');

package/metadata/types.d.ts

@@ -1,9 +1,52 @@
-import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw, TriggerDef } from '../typings.js';
+import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw, SchemaColumns, TriggerDef } 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';
 import type { FilterOptions, FindOptions } from '../drivers/IDatabaseDriver.js';
 import type { SerializeOptions } from '../serialization/EntitySerializer.js';
+/** Supported PostgreSQL partitioning strategies. */
+export type EntityPartitionType = 'hash' | 'list' | 'range';
+/**
+ * Partition key expression for PostgreSQL partitioned tables.
+ *
+ * You can use:
+ * - a property name, e.g. `'type'`
+ * - a list of property names for composite expressions, e.g. `['tenant', 'createdAt']`
+ * - a raw SQL expression string, e.g. `"date_trunc('month', created_at)"`
+ * - a callback that receives schema column mappings and returns SQL
+ */
+export type EntityPartitionExpression<E = AnyEntity> = (keyof E & string) | readonly (keyof E & string)[] | AnyString | ((columns: SchemaColumns<E>) => string);
+/** Explicit child partition definition for PostgreSQL `list` and `range` partitioning. */
+export interface EntityPartition<E = AnyEntity> {
+    /**
+     * Optional child table name. Defaults to `<tableName>_<index>`. A single `.` is treated as a
+     * `schema.table` separator; names with more than one `.` are rejected to avoid ambiguity.
+     */
+    name?: string;
+    /** Partition bound clause, either as `for values ...` or the trailing part such as `in (...)`, `from ... to ...`, or `default`. */
+    values: string;
+}
+/**
+ * PostgreSQL table partitioning definition.
+ *
+ * - `hash` partitions generate child tables automatically from the partition count
+ * - `list` and `range` partitions require explicit child partition definitions
+ */
+export type EntityPartitionBy<E = AnyEntity> = {
+    type: Extract<EntityPartitionType, 'hash'>;
+    expression: EntityPartitionExpression<E>;
+    /**
+     * Hash partition fan-out: either a number (auto-named as `${tableName}_N`) or an array of
+     * explicit partition names in remainder order. Names may be `schema.name` to create the
+     * child in a non-default schema.
+     */
+    partitions: number | readonly string[];
+} | {
+    type: Exclude<EntityPartitionType, 'hash'>;
+    expression: EntityPartitionExpression<E>;
+    /** Explicit child partitions created in the order provided. */
+    partitions: EntityPartition<E>[];
+};
 export type EntityOptions<T, E = T extends EntityClass<infer P> ? P : T> = {
     /** Override default collection/table name. Alias for `collection`. */
     tableName?: string;
@@ -59,6 +102,13 @@ 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 partitioning definition for this table.
+     *
+     * Partitioned tables are tracked by the schema generator and introspected back from PostgreSQL.
+     * Changing an existing partition layout still requires a manual migration.
+     */
+    partitionBy?: EntityPartitionBy<E>;
     /** SQL query that maps to a {@doclink virtual-entities | virtual entity}, or for view entities, the view definition. */
     expression?: string | ((em: any, where: ObjectQuery<E>, options: FindOptions<E, any, any, any>, stream?: boolean) => object);
     /** Set {@doclink repositories#custom-repository | custom repository class}. */

package/package.json

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

@@ -43,6 +43,8 @@ export declare abstract class Platform {
     getEnumArrayCheckConstraintExpression(column: string, items: string[]): string | null;
     /** Whether this platform supports materialized views. */
     supportsMaterializedViews(): boolean;
+    /** Whether this platform supports declarative table partitioning in schema generation. */
+    supportsPartitionedTables(): boolean;
     /** Returns the schema helper instance for this platform, or undefined if not supported. */
     getSchemaHelper(): unknown;
     /** Whether the platform automatically creates indexes on foreign key columns. */

package/platforms/Platform.js

@@ -2,6 +2,7 @@ import { clone } from '../utils/clone.js';
 import { EntityRepository } from '../entity/EntityRepository.js';
 import { UnderscoreNamingStrategy } from '../naming-strategy/UnderscoreNamingStrategy.js';
 import { ExceptionConverter } from './ExceptionConverter.js';
+import { MetadataError } from '../errors.js';
 import { ArrayType, BigIntType, BlobType, BooleanType, CharacterType, DateTimeType, DateType, DecimalType, DoubleType, EnumType, FloatType, IntegerType, IntervalType, JsonType, MediumIntType, SmallIntType, StringType, TextType, TimeType, TinyIntType, Type, Uint8ArrayType, UnknownType, UuidType, } from '../types/index.js';
 import { parseJsonSafe, Utils } from '../utils/Utils.js';
 import { ReferenceKind } from '../enums.js';
@@ -62,6 +63,10 @@ export class Platform {
     supportsMaterializedViews() {
         return false;
     }
+    /** Whether this platform supports declarative table partitioning in schema generation. */
+    supportsPartitionedTables() {
+        return false;
+    }
     /** Returns the schema helper instance for this platform, or undefined if not supported. */
     getSchemaHelper() {
         return undefined;
@@ -658,7 +663,9 @@ export class Platform {
     }
     /** Platform-specific validation of entity metadata. */
     validateMetadata(meta) {
-        return;
+        if (meta.partitionBy && !this.supportsPartitionedTables()) {
+            throw new MetadataError(`Entity ${meta.className} uses partitionBy, but ${this.constructor.name} does not support partitioned tables`);
+        }
     }
     /**
      * Generates a custom order by statement given a set of in order values, eg.

package/typings.d.ts

@@ -11,7 +11,7 @@ import type { SerializationContext } from './serialization/SerializationContext.
 import type { SerializeOptions } from './serialization/EntitySerializer.js';
 import type { MetadataStorage } from './metadata/MetadataStorage.js';
 import type { EntitySchema } from './metadata/EntitySchema.js';
-import type { IndexColumnOptions } from './metadata/types.js';
+import type { EntityPartitionBy, IndexColumnOptions } from './metadata/types.js';
 import type { Type, types } from './types/index.js';
 import type { Platform } from './platforms/Platform.js';
 import type { Configuration } from './utils/Configuration.js';
@@ -874,6 +874,8 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     materialized?: boolean;
     /** For materialized views, whether data is populated on creation. Defaults to true. */
     withData?: boolean;
+    /** PostgreSQL partitioning definition for this table. */
+    partitionBy?: EntityPartitionBy<Entity>;
     expression?: string | ((em: any, where: ObjectQuery<Entity>, options: FindOptions<Entity, any, any, any>, stream?: boolean) => MaybePromise<Raw | object | string>);
     discriminatorColumn?: EntityKey<Entity> | AnyString;
     discriminatorValue?: number | string;
@@ -954,6 +956,8 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     polymorphicDiscriminatorMap?: Dictionary<EntityClass>;
     /** Inheritance type: 'sti' (Single Table Inheritance) or 'tpt' (Table-Per-Type). Only set on root entities. */
     inheritanceType?: 'sti' | 'tpt';
+    /** Legacy alias populated from `EntityOptions.inheritance`; mirrored to `inheritanceType` during discovery. */
+    inheritance?: 'tpt';
     /** For TPT: direct parent entity metadata (the entity this one extends). */
     tptParent?: EntityMetadata;
     /** For TPT: direct child entities (entities that extend this one). */

package/utils/Utils.js

@@ -141,7 +141,7 @@ export function parseJsonSafe(value) {
 /** Collection of general-purpose utility methods used throughout the ORM. */
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.1.0-dev.15';
+    static #ORM_VERSION = '7.1.0-dev.16';
     /**
      * Checks if the argument is instance of `Object`. Returns false for arrays.
      */

package/utils/index.d.ts

@@ -10,3 +10,4 @@ export * from './EntityComparator.js';
 export * from './RawQueryFragment.js';
 export * from './env-vars.js';
 export * from './upsert-utils.js';
+export * from './partition-utils.js';

package/utils/index.js

@@ -10,3 +10,4 @@ export * from './EntityComparator.js';
 export * from './RawQueryFragment.js';
 export * from './env-vars.js';
 export * from './upsert-utils.js';
+export * from './partition-utils.js';

package/utils/partition-utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalize a partition name for collision detection. Mirrors PostgreSQL identifier
+ * resolution: unquoted segments fold to lower case, quoted segments preserve case and
+ * un-escape embedded `""`. Returns a canonical `schema.name` form so both schema-qualified
+ * and bare names compare consistently (`.name` vs `schema.name` stay distinguishable).
+ *
+ * `Part_1`, `part_1`, and `"part_1"` all normalize to the same value, catching collisions
+ * that would otherwise only surface as runtime PG "relation already exists" errors.
+ */
+export declare function normalizePartitionNameForComparison(name: string): string;
+/**
+ * Split a comma-list of identifiers, respecting double-quoted identifiers (which may contain
+ * commas and use `""` to escape embedded quotes). Returns `null` when the input is not a clean
+ * comma-list of identifiers (e.g. contains function calls or literals), so callers treat it
+ * as an opaque expression.
+ */
+export declare function splitCommaSeparatedIdentifiers(value: string): string[] | null;

package/utils/partition-utils.js

@@ -0,0 +1,79 @@
+function normalizeIdentifierSegment(segment) {
+    const trimmed = segment.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1).replaceAll('""', '"');
+    }
+    return trimmed.toLowerCase();
+}
+/**
+ * Normalize a partition name for collision detection. Mirrors PostgreSQL identifier
+ * resolution: unquoted segments fold to lower case, quoted segments preserve case and
+ * un-escape embedded `""`. Returns a canonical `schema.name` form so both schema-qualified
+ * and bare names compare consistently (`.name` vs `schema.name` stay distinguishable).
+ *
+ * `Part_1`, `part_1`, and `"part_1"` all normalize to the same value, catching collisions
+ * that would otherwise only surface as runtime PG "relation already exists" errors.
+ */
+export function normalizePartitionNameForComparison(name) {
+    const trimmed = name.trim();
+    let depth = 0;
+    for (let i = 0; i < trimmed.length; i++) {
+        const ch = trimmed[i];
+        if (ch === '"') {
+            if (trimmed[i + 1] === '"') {
+                i++;
+                continue;
+            }
+            depth = depth === 0 ? 1 : 0;
+            continue;
+        }
+        if (ch === '.' && depth === 0) {
+            return `${normalizeIdentifierSegment(trimmed.slice(0, i))}.${normalizeIdentifierSegment(trimmed.slice(i + 1))}`;
+        }
+    }
+    return `.${normalizeIdentifierSegment(trimmed)}`;
+}
+/**
+ * Split a comma-list of identifiers, respecting double-quoted identifiers (which may contain
+ * commas and use `""` to escape embedded quotes). Returns `null` when the input is not a clean
+ * comma-list of identifiers (e.g. contains function calls or literals), so callers treat it
+ * as an opaque expression.
+ */
+export function splitCommaSeparatedIdentifiers(value) {
+    const segments = [];
+    let buffer = '';
+    let inQuote = false;
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (ch === '"') {
+            if (inQuote && value[i + 1] === '"') {
+                buffer += '""';
+                i++;
+                continue;
+            }
+            inQuote = !inQuote;
+            buffer += ch;
+            continue;
+        }
+        if (!inQuote) {
+            if (ch === ',') {
+                segments.push(buffer);
+                buffer = '';
+                continue;
+            }
+            if (!/[\w.\s]/.test(ch)) {
+                return null;
+            }
+        }
+        buffer += ch;
+    }
+    if (inQuote) {
+        return null;
+    }
+    segments.push(buffer);
+    const trimmed = segments.map(s => s.trim());
+    if (trimmed.some(s => s === '')) {
+        return null;
+    }
+    return trimmed;
+}