linkgress-orm 0.4.54 → 0.4.56

package/dist/entity/db-context.js

@@ -7,10 +7,11 @@ const entity_base_1 = require("./entity-base");
 const model_config_1 = require("./model-config");
 const conditions_1 = require("../query/conditions");
 const query_builder_1 = require("../query/query-builder");
+const sql_utils_1 = require("../query/sql-utils");
 const db_schema_manager_1 = require("../migration/db-schema-manager");
 const sequence_builder_1 = require("../schema/sequence-builder");
 const cte_root_query_1 = require("../query/cte-root-query");
-const sql_utils_1 = require("../query/sql-utils");
+const sql_utils_2 = require("../query/sql-utils");
 /**
  * Per-schema cache of the entity column mapping plan used by
  * DbEntityTable.mapResultToEntity. Schema objects come from the shared
@@ -539,9 +540,9 @@ class InsertBuilder {
             }
             valuePlaceholders.push(`(${rowPlaceholders.join(', ')})`);
         }
-        const columnNames = (0, sql_utils_1.buildColumnNamesList)(this.schema, columns);
-        const returningColumns = (0, sql_utils_1.buildReturningColumnList)(this.schema);
-        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
+        const columnNames = (0, sql_utils_2.buildColumnNamesList)(this.schema, columns);
+        const returningColumns = (0, sql_utils_2.buildReturningColumnList)(this.schema);
+        const qualifiedTableName = (0, sql_utils_2.getQualifiedTableName)(this.schema);
         let sql = `INSERT INTO ${qualifiedTableName} (${columnNames.join(', ')})`;
         // Add OVERRIDING SYSTEM VALUE if specified
         if (this.overridingSystemValue) {
@@ -753,8 +754,8 @@ class TableAccessor {
                 placeholders.push(`$${paramIndex++}`);
             }
         }
-        const returningColumns = (0, sql_utils_1.buildReturningColumnList)(this.schema);
-        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
+        const returningColumns = (0, sql_utils_2.buildReturningColumnList)(this.schema);
+        const qualifiedTableName = (0, sql_utils_2.getQualifiedTableName)(this.schema);
         const sql = `
       INSERT INTO ${qualifiedTableName} (${columns.join(', ')})
       VALUES (${placeholders.join(', ')})
@@ -775,7 +776,7 @@ class TableAccessor {
         }
         // Calculate chunk size based on max rows per batch
         const columnCount = Object.keys(dataArray[0]).length;
-        const chunkSize = (0, sql_utils_1.calculateOptimalChunkSize)(columnCount, insertConfig?.chunkSize);
+        const chunkSize = (0, sql_utils_2.calculateOptimalChunkSize)(columnCount, insertConfig?.chunkSize);
         // Check if we need to chunk
         if (dataArray.length > chunkSize) {
             const results = [];
@@ -798,15 +799,15 @@ class TableAccessor {
             return [];
         }
         // Extract all unique column names from all data objects
-        const columns = (0, sql_utils_1.extractUniqueColumnKeys)(dataArray, this.schema, insertConfig?.overridingSystemValue);
+        const columns = (0, sql_utils_2.extractUniqueColumnKeys)(dataArray, this.schema, insertConfig?.overridingSystemValue);
         if (columns.length === 0) {
             return [];
         }
-        const columnConfigs = (0, sql_utils_1.buildColumnConfigs)(this.schema, columns, insertConfig?.overridingSystemValue);
-        const { valueClauses, params } = (0, sql_utils_1.buildValuesClause)(dataArray, columnConfigs);
+        const columnConfigs = (0, sql_utils_2.buildColumnConfigs)(this.schema, columns, insertConfig?.overridingSystemValue);
+        const { valueClauses, params } = (0, sql_utils_2.buildValuesClause)(dataArray, columnConfigs);
         const columnNames = columnConfigs.map(c => `"${c.dbName}"`);
-        const returningColumns = (0, sql_utils_1.buildReturningColumnList)(this.schema);
-        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
+        const returningColumns = (0, sql_utils_2.buildReturningColumnList)(this.schema);
+        const qualifiedTableName = (0, sql_utils_2.getQualifiedTableName)(this.schema);
         let sql = `
       INSERT INTO ${qualifiedTableName} (${columnNames.join(', ')})`;
         // Add OVERRIDING SYSTEM VALUE if specified
@@ -838,10 +839,10 @@ class TableAccessor {
         // Determine primary keys
         const primaryKeys = config?.primaryKey
             ? (Array.isArray(config.primaryKey) ? config.primaryKey : [config.primaryKey])
-            : (0, sql_utils_1.detectPrimaryKeys)(this.schema);
+            : (0, sql_utils_2.detectPrimaryKeys)(this.schema);
         // Auto-detect overridingSystemValue
         const overridingSystemValue = config?.overridingSystemValue ??
-            (0, sql_utils_1.hasAutoIncrementPrimaryKey)(this.schema, Object.keys(referenceItem));
+            (0, sql_utils_2.hasAutoIncrementPrimaryKey)(this.schema, Object.keys(referenceItem));
         // Determine which columns to update
         let updateColumnFilter = config?.updateColumnFilter;
         if (updateColumnFilter == null && config?.updateColumns) {
@@ -853,7 +854,7 @@ class TableAccessor {
         }
         // Calculate chunk size based on max rows per batch
         const columnCount = Object.keys(values[0]).length;
-        const chunkSize = (0, sql_utils_1.calculateOptimalChunkSize)(columnCount, config?.chunkSize);
+        const chunkSize = (0, sql_utils_2.calculateOptimalChunkSize)(columnCount, config?.chunkSize);
         // Check if we need to chunk
         if (values.length > chunkSize) {
             const results = [];
@@ -935,7 +936,7 @@ class TableAccessor {
         const returningColumns = Object.entries(this.schema.columns)
             .map(([_, col]) => `"${col.build().name}"`)
             .join(', ');
-        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
+        const qualifiedTableName = (0, sql_utils_2.getQualifiedTableName)(this.schema);
         const sql = `
       UPDATE ${qualifiedTableName}
       SET ${setClauses.join(', ')}
@@ -963,7 +964,7 @@ class TableAccessor {
         if (!pkColumnName) {
             throw new Error(`Table ${this.schema.name} has no primary key`);
         }
-        const qualifiedTableName = (0, sql_utils_1.getQualifiedTableName)(this.schema);
+        const qualifiedTableName = (0, sql_utils_2.getQualifiedTableName)(this.schema);
         const sql = `DELETE FROM ${qualifiedTableName} WHERE "${pkColumnName}" = $1`;
         const result = this.executor
             ? await this.executor.query(sql, [id])
@@ -2022,14 +2023,297 @@ class DbEntityTable {
             }
         };
     }
+    /**
+     * Insert ONE parent row and its dependent CHILD rows as a SINGLE statement,
+     * optionally guarded by a NOT-EXISTS probe:
+     *
+     *   WITH "__iwc_parent__" AS (
+     *     INSERT INTO parent (cols) SELECT ... FROM (VALUES (...)) v
+     *     [WHERE NOT EXISTS (SELECT 1 FROM (<unlessExists>) "__iwc_guard__")]
+     *     RETURNING <parent cols>
+     *   ),
+     *   "__mutation__" AS (
+     *     INSERT INTO child (fk, cols)
+     *     SELECT p.pk, v.cols FROM "__iwc_parent__" p CROSS JOIN (VALUES (0, ...), (1, ...)) v("__iwc_ord", cols)
+     *     ORDER BY v."__iwc_ord"
+     *     RETURNING <child cols>
+     *   )
+     *   SELECT <child projection>, <parent cols> FROM "__mutation__" CROSS JOIN "__iwc_parent__" ...
+     *
+     * Guarantees:
+     *  - the child rows receive the freshly inserted parent's primary key via
+     *    `children.foreignKey`;
+     *  - the ordinal ORDER BY fixes the child sequence-allocation order, so
+     *    serial child ids ascend in INPUT-ROW order, and the returned `children`
+     *    array is sorted back into that order (deterministic even when the
+     *    outer navigation joins would otherwise shuffle rows);
+     *  - a matching `unlessExists` guard suppresses the WHOLE insert in the same
+     *    snapshot and resolves `{ parent: null, children: [] }` (callers race-
+     *    guarding concurrent creates still need their own serialization — two
+     *    concurrent statements cannot see each other's uncommitted rows);
+     *  - single-statement atomicity: any failing leg rolls back both inserts.
+     *
+     * Restrictions: single-column auto/serial parent primary key; the parent
+     * `returning` selector supports FLAT parent columns only; child rows must
+     * NOT carry the foreign-key property; `children.rows` must be non-empty and
+     * fit one statement (no chunking). The child `returning` selector supports
+     * the full navigation/collection projection surface of `.returning()`.
+     */
+    insertWithChildren(config) {
+        const { rows, foreignKey } = config.children;
+        if (rows.length === 0) {
+            throw new Error('insertWithChildren: children.rows must be non-empty — use a plain insert for a childless parent');
+        }
+        for (let i = 0; i < rows.length; i++) {
+            if (rows[i][foreignKey] !== undefined) {
+                throw new Error(`insertWithChildren: child row at index ${i} carries the foreign-key property "${foreignKey}" — it is sourced from the inserted parent`);
+            }
+        }
+        const columnCount = Math.max(1, Object.keys(rows[0]).length + 1);
+        const singleStatementLimit = Math.floor(Math.floor(65535 / columnCount) * 0.6);
+        if (rows.length > singleStatementLimit) {
+            throw new Error(`insertWithChildren: ${rows.length} child rows exceed the ~${singleStatementLimit}-row single-statement budget — insert them standalone (they need chunking)`);
+        }
+        return this.executeInsertWithChildren(config);
+    }
+    /** @internal Async body of {@link insertWithChildren} (validation stays synchronous). */
+    async executeInsertWithChildren(config) {
+        const parentSchema = this._getSchema();
+        const executor = this._getExecutor();
+        const client = this._getClient();
+        const childTable = config.children.table;
+        if (childTable._getClient() !== client || childTable._getExecutor() !== executor) {
+            throw new Error('insertWithChildren: the child table uses a different database client or transaction than the parent — both must share one connection context');
+        }
+        if (config.unlessExists) {
+            const guardFuture = config.unlessExists.future();
+            if (guardFuture._client !== client || guardFuture._executor !== executor) {
+                throw new Error('insertWithChildren: the unlessExists guard uses a different database client or transaction than the insert');
+            }
+        }
+        // Single-column parent primary key — the value the child FK column selects.
+        const pkEntries = Object.entries(parentSchema.columns).filter(([, colBuilder]) => colBuilder.build().primaryKey);
+        if (pkEntries.length !== 1) {
+            throw new Error('insertWithChildren requires a single-column parent primary key');
+        }
+        const parentPkDbName = pkEntries[0][1].build().name;
+        // ---- parent leg: INSERT ... SELECT FROM (VALUES ...) [WHERE NOT EXISTS] ----
+        const parentCompiled = this.compileValuesWithCasts(parentSchema, [config.row], null);
+        const parentColNames = parentCompiled.columns.map(c => `"${c.dbName}"`).join(', ');
+        const parentSelectCols = parentCompiled.columns.map(c => `v."${c.dbName}"`).join(', ');
+        const params = [...parentCompiled.params];
+        // Parent RETURNING: the selector's flat columns plus the pk (child FK source).
+        const parentMock = this.createMockEntity();
+        const parentSelection = config.returning.parent(parentMock);
+        const parentSelCols = [];
+        for (const [prop, field] of Object.entries(parentSelection)) {
+            const tableAlias = field?.__tableAlias;
+            const dbColumnName = field?.__dbColumnName;
+            if (dbColumnName == null || (tableAlias && tableAlias !== parentSchema.name)) {
+                throw new Error(`insertWithChildren: parent returning supports flat parent columns only — "${prop}" is not one`);
+            }
+            const colEntry = Object.entries(parentSchema.columns).find(([, colBuilder]) => colBuilder.build().name === dbColumnName);
+            parentSelCols.push({ prop, dbName: dbColumnName, mapper: colEntry ? colEntry[1].build().mapper : undefined });
+        }
+        let parentSql = `INSERT INTO ${this._getQualifiedTableName()} (${parentColNames})
+SELECT ${parentSelectCols} FROM (VALUES (${parentCompiled.valueRows[0]})) AS v(${parentColNames})`;
+        if (config.unlessExists) {
+            const guardFuture = config.unlessExists.future();
+            const guardSql = params.length === 0 ? guardFuture._sql : (0, sql_utils_1.renumberPlaceholders)(guardFuture._sql, params.length);
+            parentSql += `\nWHERE NOT EXISTS (SELECT 1 FROM (\n${guardSql}\n) "__iwc_guard__")`;
+            params.push(...guardFuture._params);
+        }
+        // RETURNING * so the CTE can stand in for the parent TABLE in child→parent
+        // navigation joins (the real table is snapshot-stale within this statement).
+        parentSql += '\nRETURNING *';
+        // ---- child leg: INSERT ... SELECT parent-pk + ordered VALUES ----
+        const childSchema = childTable._getSchema();
+        const fkColBuilder = childSchema.columns[config.children.foreignKey];
+        if (!fkColBuilder) {
+            throw new Error(`insertWithChildren: unknown child foreign-key property "${config.children.foreignKey}"`);
+        }
+        const fkDbName = fkColBuilder.build().name;
+        const childCompiled = childTable.compileValuesWithCasts(childSchema, config.children.rows, config.children.foreignKey);
+        const childColNames = childCompiled.columns.map(c => `"${c.dbName}"`).join(', ');
+        const childSelectCols = childCompiled.columns.map(c => `v."${c.dbName}"`).join(', ');
+        const childValuesRows = childCompiled.valueRows.map((row, ix) => `(${ix}, ${row})`);
+        const childOffset = params.length;
+        const childValueList = childValuesRows.join(', ');
+        let childSql = `INSERT INTO ${childTable._getQualifiedTableName()} ("${fkDbName}", ${childColNames})
+SELECT p."${parentPkDbName}", ${childSelectCols} FROM "__iwc_parent__" p CROSS JOIN (VALUES ${childValueList}) AS v("__iwc_ord", ${childColNames})
+ORDER BY v."__iwc_ord"`;
+        childSql = childOffset === 0 ? childSql : (0, sql_utils_1.renumberPlaceholders)(childSql, childOffset);
+        params.push(...childCompiled.params);
+        // ---- returning assembly ----
+        const childPkEntries = Object.entries(childSchema.columns).filter(([, colBuilder]) => colBuilder.build().primaryKey);
+        const childPkDbName = childPkEntries.length === 1 ? childPkEntries[0][1].build().name : null;
+        const prefixCtes = `"__iwc_parent__" AS (
+${parentSql}
+)`;
+        const extraJoins = ['CROSS JOIN "__iwc_parent__" AS "__iwc_parent_j__"'];
+        const extraSelects = parentSelCols.map(c => `"__iwc_parent_j__"."${c.dbName}" AS "__iwc_parent__.${c.prop}"`);
+        const navigationInfo = childTable.detectNavigationInReturning(config.returning.children);
+        let rawRows;
+        let mapChildren;
+        if (navigationInfo) {
+            const built = childTable.buildReturningWithNavigation(childSql, params, config.returning.children, navigationInfo, {
+                prefixCtes,
+                extraJoins,
+                extraSelects,
+                extraCteReturningCols: childPkDbName ? [childPkDbName] : [],
+                orderByCteColumn: childPkDbName ?? undefined,
+                joinTableOverrides: new Map([[
+                        parentSchema.name,
+                        '__iwc_parent__',
+                    ]]),
+            });
+            const result = executor ? await executor.query(built.sql, built.params) : await client.query(built.sql, built.params);
+            rawRows = result.rows;
+            mapChildren = stripped => childTable.mapReturningResultsWithNavigation(stripped, navigationInfo.navigationFields, built.nestedPaths);
+        }
+        else {
+            const returningClause = childTable.buildReturningClause(config.returning.children);
+            const pkExtra = childPkDbName ? `, "${childPkDbName}" AS "__iwc_child_pk__"` : '';
+            const orderBy = childPkDbName ? '\nORDER BY "__mutation__"."__iwc_child_pk__"' : '';
+            const sql = `WITH ${prefixCtes},
+"__mutation__" AS (
+${childSql}
+RETURNING ${returningClause.sql}${pkExtra}
+)
+SELECT "__mutation__".*, ${extraSelects.join(', ')}
+FROM "__mutation__"
+${extraJoins.join('\n')}${orderBy}`;
+            const result = executor ? await executor.query(sql, params) : await client.query(sql, params);
+            rawRows = result.rows;
+            mapChildren = stripped => childTable.mapReturningResults(stripped.map(({ __iwc_child_pk__: _pk, ...rest }) => rest), returningClause.aliasToProperty);
+        }
+        if (rawRows.length === 0) {
+            // Guard suppressed the insert (children.rows is non-empty, so an inserted
+            // parent always yields at least one row here).
+            return { parent: null, children: [] };
+        }
+        const parentRow = {};
+        for (const col of parentSelCols) {
+            const raw = rawRows[0][`__iwc_parent__.${col.prop}`];
+            parentRow[col.prop] = col.mapper ? col.mapper.fromDriver(raw) : raw;
+        }
+        const strippedRows = rawRows.map((row) => {
+            const clean = {};
+            for (const [key, value] of Object.entries(row)) {
+                if (!key.startsWith('__iwc_parent__.')) {
+                    clean[key] = value;
+                }
+            }
+            return clean;
+        });
+        return { parent: parentRow, children: mapChildren(strippedRows) };
+    }
+    /**
+     * Compile rows into a cast-annotated VALUES fragment (`$n::type` / `NULL::type`
+     * per cell — the bulkUpdate technique, so a bare `VALUES` source keeps correct
+     * column types) with the same column-selection rules as {@link insertBulkSingle}.
+     * @internal
+     */
+    compileValuesWithCasts(schema, data, excludeProp) {
+        const columns = [];
+        for (const [propName, colBuilder] of Object.entries(schema.columns)) {
+            if (propName === excludeProp) {
+                continue;
+            }
+            const colConfig = colBuilder.build();
+            if (colConfig.autoIncrement) {
+                continue;
+            }
+            const hasDefinedValue = data.some(record => record[propName] !== undefined);
+            if (!hasDefinedValue) {
+                if (colConfig.default !== undefined || colConfig.identity) {
+                    continue;
+                }
+                const isPresentInAnyRow = data.some(record => propName in record);
+                if (!isPresentInAnyRow) {
+                    continue;
+                }
+            }
+            columns.push({
+                propName,
+                dbName: colConfig.name,
+                pgType: DbEntityTable.PG_TYPE_MAP[colConfig.type] || colConfig.type,
+                mapper: colConfig.mapper,
+            });
+        }
+        if (columns.length === 0) {
+            throw new Error('insertWithChildren: rows resolve to zero insertable columns');
+        }
+        const valueRows = [];
+        const params = [];
+        let paramIndex = 1;
+        for (const record of data) {
+            const cells = [];
+            for (const col of columns) {
+                const rawValue = record[col.propName];
+                const normalized = rawValue === undefined ? null : rawValue;
+                const mapped = col.mapper ? col.mapper.toDriver(normalized) : normalized;
+                if (mapped === undefined || mapped === null) {
+                    cells.push(`NULL::${col.pgType}`);
+                }
+                else {
+                    cells.push(`$${paramIndex++}::${col.pgType}`);
+                    params.push(mapped);
+                }
+            }
+            valueRows.push(cells.join(', '));
+        }
+        return { columns, valueRows, params };
+    }
     /**
      * Execute a single bulk insert batch
      * @internal
      */
     async insertBulkSingle(data, returning, overridingSystemValue, onConflictDoNothing) {
-        const schema = this._getSchema();
         const executor = this._getExecutor();
         const client = this._getClient();
+        const built = this._buildInsertBulkStatement(data, overridingSystemValue, onConflictDoNothing);
+        if (!built) {
+            return returning === undefined ? undefined : [];
+        }
+        // Check if RETURNING uses navigation properties
+        const navigationInfo = returning && returning !== true && typeof returning === 'function'
+            ? this.detectNavigationInReturning(returning)
+            : null;
+        if (navigationInfo) {
+            // Use CTE-based approach for navigation properties
+            const { sql, params: queryParams, nestedPaths } = this.buildReturningWithNavigation(built.sql, built.params, returning, navigationInfo);
+            const result = executor
+                ? await executor.query(sql, queryParams)
+                : await client.query(sql, queryParams);
+            return this.mapReturningResultsWithNavigation(result.rows, navigationInfo.navigationFields, nestedPaths);
+        }
+        // Standard RETURNING (no navigation properties)
+        const returningClause = this.buildReturningClause(returning);
+        let sql = built.sql;
+        if (returningClause) {
+            sql += ` RETURNING ${returningClause.sql}`;
+        }
+        const result = executor
+            ? await executor.query(sql, built.params)
+            : await client.query(sql, built.params);
+        if (!returningClause) {
+            return undefined;
+        }
+        return this.mapReturningResults(result.rows, returningClause.aliasToProperty);
+    }
+    /**
+     * Builds the bare `INSERT ... VALUES` statement (no RETURNING clause) for ONE
+     * chunk of rows — exactly the SQL {@link insertBulkSingle} executes, exposed
+     * separately so `MutationBatch` can compose it as a data-modifying CTE leg.
+     * Returns null when the rows resolve to zero insertable columns (or no rows).
+     * @internal
+     */
+    _buildInsertBulkStatement(data, overridingSystemValue, onConflictDoNothing) {
+        if (data.length === 0) {
+            return null;
+        }
+        const schema = this._getSchema();
         const qualifiedTableName = this._getQualifiedTableName();
         // Get columns from all rows - a column is included if ANY row has a non-undefined value for it
         const columnConfigs = [];
@@ -2063,6 +2347,9 @@ class DbEntityTable {
                 mapper: config.mapper,
             });
         }
+        if (columnConfigs.length === 0) {
+            return null;
+        }
         // Build VALUES clauses
         const valuesClauses = [];
         const params = [];
@@ -2080,28 +2367,6 @@ class DbEntityTable {
             valuesClauses.push(`(${rowValues.join(', ')})`);
         }
         const columnList = columnConfigs.map(c => `"${c.dbName}"`).join(', ');
-        // Check if RETURNING uses navigation properties
-        const navigationInfo = returning && returning !== true && typeof returning === 'function'
-            ? this.detectNavigationInReturning(returning)
-            : null;
-        if (navigationInfo) {
-            // Use CTE-based approach for navigation properties
-            let insertSql = `INSERT INTO ${qualifiedTableName} (${columnList})`;
-            if (overridingSystemValue) {
-                insertSql += ' OVERRIDING SYSTEM VALUE';
-            }
-            insertSql += ` VALUES ${valuesClauses.join(', ')}`;
-            if (onConflictDoNothing) {
-                insertSql += ' ON CONFLICT DO NOTHING';
-            }
-            const { sql, params: queryParams, nestedPaths } = this.buildReturningWithNavigation(insertSql, params, returning, navigationInfo);
-            const result = executor
-                ? await executor.query(sql, queryParams)
-                : await client.query(sql, queryParams);
-            return this.mapReturningResultsWithNavigation(result.rows, navigationInfo.navigationFields, nestedPaths);
-        }
-        // Standard RETURNING (no navigation properties)
-        const returningClause = this.buildReturningClause(returning);
         let sql = `INSERT INTO ${qualifiedTableName} (${columnList})`;
         if (overridingSystemValue) {
             sql += ' OVERRIDING SYSTEM VALUE';
@@ -2110,16 +2375,7 @@ class DbEntityTable {
         if (onConflictDoNothing) {
             sql += ' ON CONFLICT DO NOTHING';
         }
-        if (returningClause) {
-            sql += ` RETURNING ${returningClause.sql}`;
-        }
-        const result = executor
-            ? await executor.query(sql, params)
-            : await client.query(sql, params);
-        if (!returningClause) {
-            return undefined;
-        }
-        return this.mapReturningResults(result.rows, returningClause.aliasToProperty);
+        return { sql, params };
     }
     /**
      * Upsert with advanced configuration
@@ -2825,32 +3081,7 @@ class DbEntityTable {
             if (data.length === 0) {
                 return returning === undefined ? undefined : [];
             }
-            const schema = table._getSchema();
-            // Determine primary keys
-            let primaryKeys = [];
-            if (config?.primaryKey) {
-                primaryKeys = Array.isArray(config.primaryKey) ? config.primaryKey : [config.primaryKey];
-            }
-            else {
-                // Auto-detect from schema
-                for (const [key, colBuilder] of Object.entries(schema.columns)) {
-                    const colConfig = colBuilder.build();
-                    if (colConfig.primaryKey) {
-                        primaryKeys.push(key);
-                    }
-                }
-            }
-            if (primaryKeys.length === 0) {
-                throw new Error('bulkUpdate requires at least one primary key column');
-            }
-            // Validate all records have primary keys
-            for (let i = 0; i < data.length; i++) {
-                for (const pk of primaryKeys) {
-                    if (data[i][pk] === undefined) {
-                        throw new Error(`Record at index ${i} is missing primary key "${pk}"`);
-                    }
-                }
-            }
+            const primaryKeys = table._resolveBulkUpdatePrimaryKeys(data, config);
             // Calculate chunk size
             let chunkSize = config?.chunkSize;
             if (chunkSize == null) {
@@ -2892,9 +3123,66 @@ class DbEntityTable {
      * @internal
      */
     async bulkUpdateSingle(data, primaryKeys, returning) {
-        const schema = this._getSchema();
         const executor = this._getExecutor();
         const client = this._getClient();
+        const built = this._buildBulkUpdateStatement(data, primaryKeys);
+        // Build RETURNING clause
+        const returningClause = this.buildReturningClause(returning, 't');
+        let sql = built.sql;
+        if (returningClause) {
+            sql += ` RETURNING ${returningClause.sql}`;
+        }
+        const result = executor
+            ? await executor.query(sql, built.params)
+            : await client.query(sql, built.params);
+        if (!returningClause) {
+            return undefined;
+        }
+        return this.mapReturningResults(result.rows, returningClause.aliasToProperty);
+    }
+    /**
+     * Resolves + validates the primary key columns a bulkUpdate matches rows on —
+     * shared by {@link bulkUpdate} and `MutationBatch`.
+     * @internal
+     */
+    _resolveBulkUpdatePrimaryKeys(data, config) {
+        const schema = this._getSchema();
+        // Determine primary keys
+        let primaryKeys = [];
+        if (config?.primaryKey) {
+            primaryKeys = Array.isArray(config.primaryKey) ? config.primaryKey : [config.primaryKey];
+        }
+        else {
+            // Auto-detect from schema
+            for (const [key, colBuilder] of Object.entries(schema.columns)) {
+                const colConfig = colBuilder.build();
+                if (colConfig.primaryKey) {
+                    primaryKeys.push(key);
+                }
+            }
+        }
+        if (primaryKeys.length === 0) {
+            throw new Error('bulkUpdate requires at least one primary key column');
+        }
+        // Validate all records have primary keys
+        for (let i = 0; i < data.length; i++) {
+            for (const pk of primaryKeys) {
+                if (data[i][pk] === undefined) {
+                    throw new Error(`Record at index ${i} is missing primary key "${pk}"`);
+                }
+            }
+        }
+        return primaryKeys;
+    }
+    /**
+     * Builds the bare `UPDATE ... FROM (VALUES ...)` statement (no RETURNING
+     * clause) for ONE chunk of rows — exactly the SQL {@link bulkUpdateSingle}
+     * executes (per-row `"col__provided"` CASE flags included), exposed
+     * separately so `MutationBatch` can compose it as a data-modifying CTE leg.
+     * @internal
+     */
+    _buildBulkUpdateStatement(data, primaryKeys) {
+        const schema = this._getSchema();
         const qualifiedTableName = this._getQualifiedTableName();
         const primaryKeySet = new Set(primaryKeys);
         // Single pass: collect columns and build column info simultaneously
@@ -2969,23 +3257,12 @@ class DbEntityTable {
             }
             valuesClauses.push(`(${rowValues.join(', ')})`);
         }
-        // Build RETURNING clause
-        const returningClause = this.buildReturningClause(returning, 't');
-        let sql = `
+        const sql = `
 UPDATE ${qualifiedTableName} AS t
 SET ${setClauses.join(', ')}
 FROM (VALUES ${valuesClauses.join(', ')}) AS v(${valueColumnList})
 WHERE ${whereClause}`.trim();
-        if (returningClause) {
-            sql += ` RETURNING ${returningClause.sql}`;
-        }
-        const result = executor
-            ? await executor.query(sql, params)
-            : await client.query(sql, params);
-        if (!returningClause) {
-            return undefined;
-        }
-        return this.mapReturningResults(result.rows, returningClause.aliasToProperty);
+        return { sql, params };
     }
     /**
      * Delete all records from the table
@@ -3339,7 +3616,14 @@ WHERE ${whereClause}`.trim();
      * Build RETURNING clause with navigation property support using CTE
      * @internal
      */
-    buildReturningWithNavigation(mutationSql, mutationParams, returning, navigationInfo) {
+    buildReturningWithNavigation(mutationSql, mutationParams, returning, navigationInfo, 
+    /**
+     * Composition hooks for `insertWithChildren`: CTEs prepended before
+     * "__mutation__" (whose SQL may reference them), extra joins/select parts
+     * on the outer statement, extra columns forced into the CTE's RETURNING
+     * list, and a deterministic outer ORDER BY on a CTE column.
+     */
+    options) {
         const schema = this._getSchema();
         const schemaRegistry = this._getSchemaRegistry();
         const mainTableColumns = new Set();
@@ -3472,6 +3756,10 @@ WHERE ${whereClause}`.trim();
             if (join.targetSchema) {
                 qualifiedJoinTable = `"${join.targetSchema}"."${join.targetTable}"`;
             }
+            const cteOverride = options?.joinTableOverrides?.get(join.targetTable);
+            if (cteOverride) {
+                qualifiedJoinTable = `"${cteOverride}"`;
+            }
             const joinConditions = [];
             for (let i = 0; i < join.foreignKeys.length; i++) {
                 const fk = join.foreignKeys[i];
@@ -3496,12 +3784,16 @@ WHERE ${whereClause}`.trim();
         for (const collection of collectionSubqueries) {
             joinClauses.push(collection.joinClause);
         }
-        const sql = `WITH "__mutation__" AS (
+        const prefixCtes = options?.prefixCtes ? `${options.prefixCtes},\n` : '';
+        const extraJoins = options?.extraJoins?.length ? `${options.extraJoins.join('\n')}\n` : '';
+        const extraSelects = options?.extraSelects?.length ? `, ${options.extraSelects.join(', ')}` : '';
+        const orderBy = options?.orderByCteColumn ? `\nORDER BY "__mutation__"."${options.orderByCteColumn}"` : '';
+        const sql = `WITH ${prefixCtes}"__mutation__" AS (
   ${mutationWithReturning}
 )
-SELECT ${selectParts.join(', ')}
+SELECT ${selectParts.join(', ')}${extraSelects}
 FROM "__mutation__"
-${joinClauses.join('\n')}`;
+${extraJoins}${joinClauses.join('\n')}${orderBy}`;
         return { sql, params: allParams, nestedPaths };
     }
     /**