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

package/dialects/postgresql/BasePostgreSqlPlatform.d.ts

@@ -15,6 +15,7 @@ export declare class BasePostgreSqlPlatform extends AbstractSqlPlatform {
     usesEnumCheckConstraints(): boolean;
     getEnumArrayCheckConstraintExpression(column: string, items: string[]): string;
     supportsMaterializedViews(): boolean;
+    supportsPartitionedTables(): boolean;
     supportsCustomPrimaryKeyNames(): boolean;
     getCurrentTimestampSQL(length: number): string;
     getDateTimeTypeDeclarationSQL(column: {

package/dialects/postgresql/BasePostgreSqlPlatform.js

@@ -30,6 +30,9 @@ export class BasePostgreSqlPlatform extends AbstractSqlPlatform {
     supportsMaterializedViews() {
         return true;
     }
+    supportsPartitionedTables() {
+        return true;
+    }
     supportsCustomPrimaryKeyNames() {
         return true;
     }

package/dialects/postgresql/PostgreSqlSchemaHelper.d.ts

@@ -1,7 +1,7 @@
 import { type Dictionary, type Transaction } from '@mikro-orm/core';
 import { SchemaHelper } from '../../schema/SchemaHelper.js';
 import type { AbstractSqlConnection } from '../../AbstractSqlConnection.js';
-import type { CheckDef, Column, ForeignKey, IndexDef, Table, TableDifference, SqlTriggerDef } from '../../typings.js';
+import type { CheckDef, Column, ForeignKey, IndexDef, Table, TableDifference, TablePartitioning, SqlTriggerDef } from '../../typings.js';
 import type { DatabaseSchema } from '../../schema/DatabaseSchema.js';
 import type { DatabaseTable } from '../../schema/DatabaseTable.js';
 export declare class PostgreSqlSchemaHelper extends SchemaHelper {
@@ -25,11 +25,22 @@ export declare class PostgreSqlSchemaHelper extends SchemaHelper {
     getListMaterializedViewsSQL(): string;
     loadMaterializedViews(schema: DatabaseSchema, connection: AbstractSqlConnection, schemaName?: string, ctx?: Transaction): Promise<void>;
     createMaterializedView(name: string, schema: string | undefined, definition: string, withData?: boolean): string;
+    createTable(table: DatabaseTable, alter?: boolean): string[];
     dropMaterializedViewIfExists(name: string, schema?: string): string;
     refreshMaterializedView(name: string, schema?: string, concurrently?: boolean): string;
     getNamespaces(connection: AbstractSqlConnection, ctx?: Transaction): Promise<string[]>;
     private getIgnoredNamespacesConditionSQL;
     loadInformationSchema(schema: DatabaseSchema, connection: AbstractSqlConnection, tables: Table[], schemas?: string[], ctx?: Transaction): Promise<void>;
+    /**
+     * Introspects direct partitions only: the `pg_inherits` join surfaces a parent's children but
+     * does not recurse into sub-partitioning (e.g. hash-of-range). Declarative `partitionBy`
+     * metadata does not express multi-level partitioning either, so grandchildren are intentionally
+     * invisible to schema diffing.
+     *
+     * Entries with an undefined schema bucket are resolved against `current_schema()` so they do
+     * not match same-named tables in unrelated schemas.
+     */
+    getPartitions(connection: AbstractSqlConnection, tablesBySchemas: Map<string | undefined, Table[]>, ctx?: Transaction): Promise<Dictionary<TablePartitioning>>;
     getAllIndexes(connection: AbstractSqlConnection, tables: Table[], ctx?: Transaction): Promise<Dictionary<IndexDef[]>>;
     /**
      * Parses column definitions from the full CREATE INDEX expression.

package/dialects/postgresql/PostgreSqlSchemaHelper.js

@@ -1,5 +1,6 @@
 import { DeferMode, EnumType, Type, Utils, } from '@mikro-orm/core';
 import { SchemaHelper } from '../../schema/SchemaHelper.js';
+import { normalizePartitionBound, normalizePartitionDefinition } from '../../schema/partitioning.js';
 /** PostGIS system views that should be automatically ignored */
 const POSTGIS_VIEWS = ['geography_columns', 'geometry_columns'];
 export class PostgreSqlSchemaHelper extends SchemaHelper {
@@ -24,13 +25,22 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
         return `create database ${this.quote(name)}`;
     }
     getListTablesSQL() {
+        // The `pg_inherits` anti-join compares on (schema, table) pairs so cross-schema child
+        // partitions are excluded even when their schema is not on the session `search_path`
+        // (in which case `inhrelid::regclass::text` renders as `schema.name` rather than bare `name`,
+        // breaking a plain `table_name not in (...)` predicate).
         return (`select table_name, table_schema as schema_name, ` +
             `(select pg_catalog.obj_description(c.oid) from pg_catalog.pg_class c
           where c.oid = (select ('"' || table_schema || '"."' || table_name || '"')::regclass::oid) and c.relname = table_name) as table_comment ` +
-            `from information_schema.tables ` +
+            `from information_schema.tables t ` +
             `where ${this.getIgnoredNamespacesConditionSQL('table_schema')} ` +
             `and table_name != 'geometry_columns' and table_name != 'spatial_ref_sys' and table_type != 'VIEW' ` +
-            `and table_name not in (select inhrelid::regclass::text from pg_inherits) ` +
+            `and not exists (` +
+            `select 1 from pg_inherits i ` +
+            `join pg_class c on c.oid = i.inhrelid ` +
+            `join pg_namespace n on n.oid = c.relnamespace ` +
+            `where c.relname = t.table_name and n.nspname = t.table_schema` +
+            `) ` +
             `order by table_name`);
     }
     getIgnoredViewsCondition() {
@@ -81,6 +91,23 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
         const dataClause = withData ? ' with data' : ' with no data';
         return `create materialized view ${viewName} as ${definition}${dataClause}`;
     }
+    createTable(table, alter) {
+        const partitioning = table.getPartitioning();
+        if (!partitioning) {
+            return super.createTable(table, alter);
+        }
+        const [createTable, ...rest] = super.createTable(table, alter);
+        const partitions = partitioning.partitions.map(partition => {
+            const partitionName = this.quote(this.getTableName(partition.name, partition.schema ?? table.schema));
+            return `create table ${partitionName} partition of ${table.getQuotedName()} ${partition.bound}`;
+        });
+        // SchemaHelper.append() always terminates the CREATE TABLE with `;`; we rely on that to splice
+        // the `partition by ...` clause in before the terminator. Use slice instead of replace() so that
+        // regex replacement tokens like `$$`, `$&`, or `$1` inside user-supplied expressions (e.g., a
+        // callback that returns a dollar-quoted literal) are not interpreted as back-references.
+        const spliced = `${createTable.slice(0, -1)} partition by ${partitioning.definition};`;
+        return [spliced, ...rest, ...partitions];
+    }
     dropMaterializedViewIfExists(name, schema) {
         return `drop materialized view if exists ${this.quote(this.getTableName(name, schema))} cascade`;
     }
@@ -120,6 +147,7 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
         const indexes = await this.getAllIndexes(connection, tables, ctx);
         const checks = await this.getAllChecks(connection, tablesBySchema, ctx);
         const fks = await this.getAllForeignKeys(connection, tablesBySchema, ctx);
+        const partitionings = await this.getPartitions(connection, tablesBySchema, ctx);
         const triggers = await this.getAllTriggers(connection, tablesBySchema);
         for (const t of tables) {
             const key = this.getTableKey(t);
@@ -132,8 +160,61 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             if (triggers[key]) {
                 table.setTriggers(triggers[key]);
             }
+            table.setPartitioning(partitionings[key]);
         }
     }
+    /**
+     * Introspects direct partitions only: the `pg_inherits` join surfaces a parent's children but
+     * does not recurse into sub-partitioning (e.g. hash-of-range). Declarative `partitionBy`
+     * metadata does not express multi-level partitioning either, so grandchildren are intentionally
+     * invisible to schema diffing.
+     *
+     * Entries with an undefined schema bucket are resolved against `current_schema()` so they do
+     * not match same-named tables in unrelated schemas.
+     */
+    async getPartitions(connection, tablesBySchemas, ctx) {
+        // Collapse every (schema, table) pair into a single `values (...)` relation and join against
+        // the catalog, instead of building an OR-tree of per-schema `in (...)` predicates. This keeps
+        // the query size O(pairs) rather than O(schemas × predicate_overhead) and stays sargable when
+        // many schemas are in play.
+        const pairs = [...tablesBySchemas.entries()].flatMap(([schema, tables]) => tables.map(t => {
+            const schemaLiteral = schema == null ? 'null::text' : `${this.platform.quoteValue(schema)}::text`;
+            return `(${schemaLiteral}, ${this.platform.quoteValue(t.table_name)})`;
+        }));
+        if (pairs.length === 0) {
+            return {};
+        }
+        const sql = `with targets(schema_name, table_name) as (values ${pairs.join(', ')})
+      select parent_ns.nspname as schema_name,
+      parent.relname as table_name,
+      pg_get_partkeydef(parent.oid) as partition_definition,
+      child_ns.nspname as partition_schema_name,
+      child.relname as partition_name,
+      pg_get_expr(child.relpartbound, child.oid) as partition_bound
+      from targets
+      join pg_class parent on parent.relname = targets.table_name
+      join pg_namespace parent_ns on parent_ns.oid = parent.relnamespace
+        and parent_ns.nspname = coalesce(targets.schema_name, current_schema())
+      join pg_partitioned_table partitioned on partitioned.partrelid = parent.oid
+      left join pg_inherits inherits on inherits.inhparent = parent.oid
+      left join pg_class child on child.oid = inherits.inhrelid
+      left join pg_namespace child_ns on child_ns.oid = child.relnamespace
+      order by parent_ns.nspname, parent.relname, child_ns.nspname, child.relname`;
+        const rows = await connection.execute(sql, [], 'all', ctx);
+        const ret = {};
+        for (const row of rows) {
+            const key = this.getTableKey(row);
+            ret[key] ??= { definition: normalizePartitionDefinition(row.partition_definition), partitions: [] };
+            if (row.partition_name && row.partition_bound) {
+                ret[key].partitions.push({
+                    name: row.partition_name,
+                    schema: row.partition_schema_name,
+                    bound: normalizePartitionBound(row.partition_bound),
+                });
+            }
+        }
+        return ret;
+    }
     async getAllIndexes(connection, tables, ctx) {
         const sql = this.getIndexesSQL(tables);
         const unquote = (str) => str.replace(/['"`]/g, '');
@@ -656,6 +737,12 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
         return col.join(' ');
     }
     getPreAlterTable(tableDiff, safe) {
+        if (tableDiff.changedPartitioning) {
+            const from = tableDiff.changedPartitioning.from?.definition;
+            const to = tableDiff.changedPartitioning.to?.definition;
+            const action = !from ? 'Adding' : !to ? 'Removing' : 'Changing';
+            throw new Error(`${action} partition definitions for existing PostgreSQL tables is not supported automatically (${tableDiff.name}: '${from ?? '<none>'}' -> '${to ?? '<none>'}'); create a manual migration instead`);
+        }
         const ret = [];
         const parts = tableDiff.name.split('.');
         const tableName = parts.pop();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/sql",
-  "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",
@@ -53,7 +53,7 @@
     "@mikro-orm/core": "^7.0.11"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.1.0-dev.15"
+    "@mikro-orm/core": "7.1.0-dev.16"
   },
   "engines": {
     "node": ">= 22.17.0"

package/schema/DatabaseSchema.js

@@ -1,5 +1,6 @@
 import { ReferenceKind, isRaw, } from '@mikro-orm/core';
 import { DatabaseTable } from './DatabaseTable.js';
+import { getTablePartitioning } from './partitioning.js';
 /**
  * @internal
  */
@@ -173,6 +174,9 @@ export class DatabaseSchema {
             }
             const table = schema.addTable(meta.collection, this.getSchemaName(meta, config, schemaName));
             table.comment = meta.comment;
+            if (meta.partitionBy) {
+                table.setPartitioning(getTablePartitioning(meta, this.getSchemaName(meta, config, schemaName), id => platform.quoteIdentifier(id)));
+            }
             // For TPT child entities, only use ownProps (properties defined in this entity only)
             // For all other entities (including TPT root), use all props
             const propsToProcess = meta.inheritanceType === 'tpt' && meta.tptParent && meta.ownProps ? meta.ownProps : meta.props;

package/schema/DatabaseTable.d.ts

@@ -1,6 +1,6 @@
 import { type Configuration, type DeferMode, type Dictionary, type EntityMetadata, type EntityProperty, type IndexCallback, type NamingStrategy } from '@mikro-orm/core';
 import type { SchemaHelper } from './SchemaHelper.js';
-import type { CheckDef, Column, ForeignKey, IndexDef, SqlTriggerDef } from '../typings.js';
+import type { CheckDef, Column, ForeignKey, IndexDef, TablePartitioning, SqlTriggerDef } from '../typings.js';
 import type { AbstractSqlPlatform } from '../AbstractSqlPlatform.js';
 /**
  * @internal
@@ -15,6 +15,7 @@ export declare class DatabaseTable {
         items: string[];
     }>;
     comment?: string;
+    partitioning?: TablePartitioning;
     constructor(platform: AbstractSqlPlatform, name: string, schema?: string | undefined);
     getQuotedName(): string;
     getColumns(): Column[];
@@ -22,6 +23,9 @@ export declare class DatabaseTable {
     removeColumn(name: string): void;
     getIndexes(): IndexDef[];
     getChecks(): CheckDef[];
+    getPartitioning(): TablePartitioning | undefined;
+    /** @internal */
+    setPartitioning(partitioning?: TablePartitioning): void;
     getTriggers(): SqlTriggerDef[];
     /** @internal */
     setIndexes(indexes: IndexDef[]): void;

package/schema/DatabaseTable.js

@@ -1,4 +1,5 @@
 import { DecimalType, EntitySchema, isRaw, ReferenceKind, t, Type, UnknownType, Utils, } from '@mikro-orm/core';
+import { toEntityPartitionBy } from './partitioning.js';
 /**
  * @internal
  */
@@ -13,6 +14,7 @@ export class DatabaseTable {
     #platform;
     nativeEnums = {}; // for postgres
     comment;
+    partitioning;
     constructor(platform, name, schema) {
         this.name = name;
         this.schema = schema;
@@ -36,6 +38,13 @@ export class DatabaseTable {
     getChecks() {
         return this.#checks;
     }
+    getPartitioning() {
+        return this.partitioning;
+    }
+    /** @internal */
+    setPartitioning(partitioning) {
+        this.partitioning = partitioning;
+    }
     getTriggers() {
         return this.#triggers;
     }
@@ -185,6 +194,7 @@ export class DatabaseTable {
         const { fksOnColumnProps, fksOnStandaloneProps, columnFks, fkIndexes, nullableForeignKeys, skippedColumnNames } = this.foreignKeysToProps(namingStrategy, scalarPropertiesForRelations);
         const name = namingStrategy.getEntityName(this.name, this.schema);
         const schema = new EntitySchema({ name, collection: this.name, schema: this.schema, comment: this.comment });
+        schema.meta.partitionBy = toEntityPartitionBy(this.partitioning, this.name, this.schema);
         const compositeFkIndexes = {};
         const compositeFkUniques = {};
         const potentiallyUnmappedIndexes = this.#indexes.filter(index => !index.primary && // Skip primary index. Whether it's in use by scalar column or FK, it's already mapped.

package/schema/SchemaComparator.js

@@ -1,5 +1,6 @@
 import { ArrayType, BooleanType, DateTimeType, inspect, JsonType, parseJsonSafe, Utils, } from '@mikro-orm/core';
 import { DatabaseTable } from './DatabaseTable.js';
+import { diffPartitioning } from './partitioning.js';
 /**
  * Compares two Schemas and return an instance of SchemaDifference.
  */
@@ -200,6 +201,17 @@ export class SchemaComparator {
             });
             changes++;
         }
+        if (diffPartitioning(fromTable.getPartitioning(), toTable.getPartitioning(), this.#platform.getDefaultSchemaName())) {
+            tableDifferences.changedPartitioning = {
+                from: fromTable.getPartitioning(),
+                to: toTable.getPartitioning(),
+            };
+            this.log(`table partitioning changed for ${tableDifferences.name}`, {
+                fromPartitioning: fromTable.getPartitioning(),
+                toPartitioning: toTable.getPartitioning(),
+            });
+            changes++;
+        }
         const fromTableColumns = fromTable.getColumns();
         const toTableColumns = toTable.getColumns();
         // See if all the columns in "from" table exist in "to" table

package/schema/partitioning.d.ts

@@ -0,0 +1,13 @@
+import { splitCommaSeparatedIdentifiers, type EntityMetadata, type EntityPartitionBy } from '@mikro-orm/core';
+import type { TablePartitioning } from '../typings.js';
+export { splitCommaSeparatedIdentifiers };
+/** @internal */
+export declare function normalizePartitionDefinition(value: string): string;
+/** @internal */
+export declare function normalizePartitionBound(value: string): string;
+/** @internal */
+export declare const getTablePartitioning: (meta: EntityMetadata, tableSchema: string | undefined, quoteIdentifier?: (id: string) => string) => TablePartitioning | undefined;
+/** @internal */
+export declare const diffPartitioning: (from: TablePartitioning | undefined, to: TablePartitioning | undefined, defaultSchema: string | undefined) => boolean;
+/** @internal */
+export declare const toEntityPartitionBy: (partitioning: TablePartitioning | undefined, parentTableName?: string, parentSchema?: string) => EntityPartitionBy | undefined;

package/schema/partitioning.js

@@ -0,0 +1,326 @@
+import { splitCommaSeparatedIdentifiers } from '@mikro-orm/core';
+export { splitCommaSeparatedIdentifiers };
+const skipQuotedLiteral = (value, start) => {
+    let i = start + 1;
+    while (i < value.length) {
+        if (value[i] === "'") {
+            if (value[i + 1] === "'") {
+                i += 2;
+                continue;
+            }
+            return i;
+        }
+        i++;
+    }
+    // Unterminated literal — point past the end so callers' `slice(start, end + 1)` includes
+    // the full remaining tail instead of dropping its last character.
+    return value.length;
+};
+/**
+ * Apply `transform` only to segments of `value` that lie outside single-quoted
+ * SQL literals, leaving literal content (including escaped `''`) untouched.
+ */
+const mapOutsideLiterals = (value, transform) => {
+    let ret = '';
+    let buffer = '';
+    let i = 0;
+    while (i < value.length) {
+        if (value[i] === "'") {
+            ret += transform(buffer);
+            buffer = '';
+            const end = skipQuotedLiteral(value, i);
+            ret += value.slice(i, end + 1);
+            i = end + 1;
+            continue;
+        }
+        buffer += value[i];
+        i++;
+    }
+    return ret + transform(buffer);
+};
+const collapseWhitespace = (value) => value.replace(/\s+/g, ' ');
+const normalizeWhitespace = (value) => mapOutsideLiterals(value, collapseWhitespace).trim();
+const stripDoubleQuotes = (value) => mapOutsideLiterals(value, s => s.replaceAll('"', ''));
+const normalizeQuotedIdentifiers = (value) => stripDoubleQuotes(normalizeWhitespace(value));
+const findMatchingParenthesis = (value, start) => {
+    let depth = 0;
+    for (let i = start; i < value.length; i++) {
+        if (value[i] === "'") {
+            i = skipQuotedLiteral(value, i);
+            continue;
+        }
+        if (value[i] === '(') {
+            depth++;
+            continue;
+        }
+        if (value[i] === ')') {
+            depth--;
+            if (depth === 0) {
+                return i;
+            }
+        }
+    }
+    return -1;
+};
+const normalizePartitionLiterals = (value) => value
+    // PG pg_get_expr output often tacks `::text` onto string literals inside expressions; drop it
+    // so the catalog shape matches user-provided bounds. This applies symmetrically to both
+    // user metadata and catalog reads, so diffing converges. If a user intentionally writes a
+    // `::text` cast in a bound literal it will be stripped on both sides as well.
+    .replace(/('(?:[^']|'')*')::text\b/gi, '$1')
+    // Strip the `00:00:00` time component so catalog round-trips (timestamp[tz] bounds formatted
+    // via the session TimeZone) match user metadata that omitted the time part. Only collapse
+    // when we can confidently attribute the literal to a timestamp column: either a numeric
+    // offset is present (timestamptz catalog output) or an explicit `::timestamp[tz]` cast
+    // follows the literal. Bare `'YYYY-MM-DD 00:00:00'` without offset/cast could just as easily
+    // be a text/varchar list-partition value, and collapsing it would produce false-negative
+    // diffs.
+    .replace(/'(\d{4}-\d{2}-\d{2}) 00:00:00[+-]\d{2}(?::\d{2})?'/g, "'$1'")
+    .replace(/'(\d{4}-\d{2}-\d{2}) 00:00:00'(?=\s*::\s*timestamp(?:tz)?(?:\s+(?:with|without)\s+time\s+zone)?\b)/gi, "'$1'");
+const unwrapOuterParentheses = (value) => {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('(') || !trimmed.endsWith(')')) {
+        return trimmed;
+    }
+    if (findMatchingParenthesis(trimmed, 0) !== trimmed.length - 1) {
+        return trimmed;
+    }
+    return trimmed.slice(1, -1).trim();
+};
+const unwrapAllOuterParentheses = (value) => {
+    let current = value.trim();
+    while (current.startsWith('(')) {
+        const unwrapped = unwrapOuterParentheses(current);
+        if (unwrapped === current) {
+            break;
+        }
+        current = unwrapped;
+    }
+    return current;
+};
+const normalizePartitionSqlFragment = (value) => {
+    const normalized = stripDoubleQuotes(normalizeWhitespace(normalizePartitionLiterals(value)));
+    let ret = '';
+    for (let i = 0; i < normalized.length; i++) {
+        if (normalized[i] === "'") {
+            const end = skipQuotedLiteral(normalized, i);
+            ret += normalized.slice(i, end + 1);
+            i = end;
+            continue;
+        }
+        if (normalized[i] === '(') {
+            const end = findMatchingParenthesis(normalized, i);
+            if (end === -1) {
+                ret += normalized.slice(i);
+                break;
+            }
+            const inner = unwrapAllOuterParentheses(normalizePartitionSqlFragment(normalized.slice(i + 1, end)));
+            ret += `(${inner})`;
+            i = end;
+            continue;
+        }
+        ret += normalized[i];
+    }
+    return normalizeWhitespace(unwrapAllOuterParentheses(ret));
+};
+const unquoteIdentifier = (value) => {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1).replaceAll('""', '"');
+    }
+    return trimmed;
+};
+/**
+ * Split a user-supplied partition name into `{ schema, name }`. Supports bare (`child`),
+ * schema-qualified (`schema.child`), and quoted (`"my.schema"."child"`) forms. Dots inside
+ * double-quoted identifiers are part of the identifier and do not split.
+ */
+const splitPartitionName = (name) => {
+    let depth = 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) {
+            return {
+                schema: unquoteIdentifier(name.slice(0, i)),
+                name: unquoteIdentifier(name.slice(i + 1)),
+            };
+        }
+    }
+    return { name: unquoteIdentifier(name) };
+};
+const resolvePartitionKey = (meta, key, quoteIdentifier) => {
+    const trimmed = key.trim().replaceAll('"', '');
+    if (!trimmed) {
+        throw new Error(`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 Error(`Entity ${meta.className} has invalid partitionBy option: unknown partition key '${key.trim()}'`);
+    }
+    if (prop.fieldNames?.length !== 1) {
+        throw new Error(`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 quoteIdentifier(prop.fieldNames[0]);
+};
+/**
+ * Resolve the partition expression to a SQL fragment. Column-reference forms (array of keys
+ * or a clean comma-list of identifiers) are rewritten to the backing `fieldNames` and passed
+ * through `quoteIdentifier`. The callback form and the raw-SQL fallback (anything that isn't
+ * a clean identifier list, e.g. `date_trunc('day', created_at)`) are emitted verbatim — the
+ * user owns identifier quoting inside a raw expression.
+ */
+const resolvePartitionExpression = (meta, expression, quoteIdentifier) => {
+    if (typeof expression === 'function') {
+        return normalizeWhitespace(expression(meta.createSchemaColumnMappingObject()));
+    }
+    if (Array.isArray(expression)) {
+        return expression.map(key => resolvePartitionKey(meta, key, quoteIdentifier)).join(', ');
+    }
+    const trimmed = expression.trim();
+    const keys = splitCommaSeparatedIdentifiers(trimmed);
+    if (keys) {
+        return keys.map(key => resolvePartitionKey(meta, key, quoteIdentifier)).join(', ');
+    }
+    return trimmed;
+};
+const createPartitionDefinition = (type, expression) => `${type.toLowerCase()} (${normalizeWhitespace(expression)})`;
+/** @internal */
+export function normalizePartitionDefinition(value) {
+    const normalized = normalizeWhitespace(value);
+    const match = /^(\w+)\s*(.*)$/.exec(normalized);
+    const rawType = match ? match[1] : normalized;
+    const type = rawType.toLowerCase();
+    const expression = match ? match[2].trim() : '';
+    if (!expression) {
+        return type;
+    }
+    if (!expression.startsWith('(')) {
+        return `${type} ${normalizePartitionSqlFragment(expression)}`;
+    }
+    return `${type} (${normalizePartitionSqlFragment(unwrapAllOuterParentheses(expression))})`;
+}
+const PARTITION_BOUND_KEYWORDS = /\b(for values|with|in|from|to|minvalue|maxvalue|null)\b/gi;
+/** @internal */
+export function normalizePartitionBound(value) {
+    const normalized = normalizeWhitespace(value);
+    if (!normalized) {
+        return '';
+    }
+    if (/^default$/i.test(normalized)) {
+        return 'default';
+    }
+    // Prepend `for values` if the caller passed a bare `with/in/from … to …` clause, then lowercase
+    // PG bound keywords outside quoted literals (so `FROM (MINVALUE) TO ('hello TO world')` becomes
+    // `from (minvalue) to ('hello TO world')` with the inner TO inside the literal preserved).
+    // PG's `pg_get_expr` emits `MINVALUE`/`MAXVALUE`/`NULL` in uppercase, so case-folding them here
+    // prevents a perpetual diff against user-supplied lowercase bounds.
+    const prefixed = /^for values\b/i.test(normalized) ? normalized : `for values ${normalized}`;
+    const lowered = mapOutsideLiterals(prefixed, segment => segment.replace(PARTITION_BOUND_KEYWORDS, match => match.toLowerCase()));
+    return normalizePartitionSqlFragment(lowered);
+}
+const createPartitionBound = (value) => normalizePartitionBound(value);
+const createHashPartitions = (tableName, tableSchema, partitions) => {
+    const count = typeof partitions === 'number' ? partitions : partitions.length;
+    return Array.from({ length: count }, (_, remainder) => {
+        const bound = normalizePartitionBound(`with (modulus ${count}, remainder ${remainder})`);
+        if (typeof partitions === 'number') {
+            return { name: `${tableName}_${remainder}`, schema: tableSchema, bound };
+        }
+        const { name, schema } = splitPartitionName(partitions[remainder]);
+        return { name, schema: schema ?? tableSchema, bound };
+    });
+};
+const createExplicitPartitions = (tableName, tableSchema, partitions) => partitions.map((partition, index) => {
+    const resolvedName = partition.name ?? `${tableName}_${index}`;
+    const { name, schema } = splitPartitionName(resolvedName);
+    return {
+        name,
+        schema: schema ?? tableSchema,
+        bound: createPartitionBound(partition.values),
+    };
+});
+/** @internal */
+export const getTablePartitioning = (meta, tableSchema, quoteIdentifier = id => id) => {
+    if (!meta.partitionBy) {
+        return undefined;
+    }
+    const definition = createPartitionDefinition(meta.partitionBy.type, resolvePartitionExpression(meta, meta.partitionBy.expression, quoteIdentifier));
+    const partitions = meta.partitionBy.type === 'hash'
+        ? createHashPartitions(meta.tableName, tableSchema, meta.partitionBy.partitions)
+        : createExplicitPartitions(meta.tableName, tableSchema, meta.partitionBy.partitions);
+    return { definition, partitions };
+};
+/** @internal */
+export const diffPartitioning = (from, to, defaultSchema) => {
+    if (!from && !to) {
+        return false;
+    }
+    if (!from || !to) {
+        return true;
+    }
+    if (normalizeQuotedIdentifiers(normalizePartitionDefinition(from.definition)) !==
+        normalizeQuotedIdentifiers(normalizePartitionDefinition(to.definition))) {
+        return true;
+    }
+    if (from.partitions.length !== to.partitions.length) {
+        return true;
+    }
+    const normalizeSchema = (schema) => (schema && schema !== defaultSchema ? schema : '');
+    const serializePartition = (partition) => `${normalizeSchema(partition.schema)}.${partition.name}:${normalizeQuotedIdentifiers(normalizePartitionBound(partition.bound))}`;
+    const fromPartitions = from.partitions.map(serializePartition).sort();
+    const toPartitions = to.partitions.map(serializePartition).sort();
+    return fromPartitions.some((partition, index) => partition !== toPartitions[index]);
+};
+const SUPPORTED_PARTITION_TYPES = ['hash', 'list', 'range'];
+const isSupportedPartitionType = (value) => SUPPORTED_PARTITION_TYPES.includes(value);
+/** @internal */
+export const toEntityPartitionBy = (partitioning, parentTableName, parentSchema) => {
+    if (!partitioning) {
+        return undefined;
+    }
+    const normalizedDefinition = normalizePartitionDefinition(partitioning.definition);
+    const normalizedPartitions = partitioning.partitions.map(partition => ({
+        ...partition,
+        bound: normalizePartitionBound(partition.bound),
+    }));
+    // Split the leading type keyword off of the definition without using `split(' ')`, which would
+    // shatter quoted literals containing spaces. Match a bareword prefix followed by whitespace.
+    const [, rawType = normalizedDefinition, rawExpression = ''] = /^(\S+)(?:\s+([\s\S]*))?$/.exec(normalizeWhitespace(normalizedDefinition)) ?? [];
+    const type = rawType.toLowerCase();
+    if (!isSupportedPartitionType(type)) {
+        throw new Error(`Unsupported partition type '${rawType}' in definition '${partitioning.definition}'`);
+    }
+    const expression = unwrapOuterParentheses(rawExpression);
+    const qualify = (partition) => partition.schema && partition.schema !== parentSchema ? `${partition.schema}.${partition.name}` : partition.name;
+    if (type === 'hash') {
+        // Collapse to a bare count when catalog names follow the default
+        // `${parentTableName}_${remainder}` pattern and live in the parent's schema, or when we have
+        // no parent context to compare against (backwards-compatible behavior for callers that pass
+        // just the `TablePartitioning`). Otherwise preserve the explicit name array so the next DDL
+        // generation reproduces the same children.
+        const usesDefaultShape = parentTableName == null ||
+            normalizedPartitions.every((p, i) => p.name === `${parentTableName}_${i}` && (!p.schema || p.schema === parentSchema));
+        return {
+            type,
+            expression,
+            partitions: usesDefaultShape ? normalizedPartitions.length : normalizedPartitions.map(qualify),
+        };
+    }
+    return {
+        type,
+        expression,
+        partitions: normalizedPartitions.map(partition => ({
+            name: qualify(partition),
+            values: partition.bound === 'default' ? 'default' : partition.bound.replace(/^for values\s+/i, ''),
+        })),
+    };
+};

package/typings.d.ts

@@ -123,6 +123,15 @@ export interface SqlTriggerDef {
     when?: string;
     expression?: string;
 }
+export interface TablePartition {
+    name: string;
+    schema?: string;
+    bound: string;
+}
+export interface TablePartitioning {
+    definition: string;
+    partitions: TablePartition[];
+}
 export interface ColumnDifference {
     oldColumnName: string;
     column: Column;
@@ -132,6 +141,10 @@ export interface ColumnDifference {
 export interface TableDifference {
     name: string;
     changedComment?: string;
+    changedPartitioning?: {
+        from?: TablePartitioning;
+        to?: TablePartitioning;
+    };
     fromTable: DatabaseTable;
     toTable: DatabaseTable;
     addedColumns: Dictionary<Column>;