linkgress-orm 0.4.55 → 0.4.57

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,475 @@ 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) };
+    }
+    /**
+     * Bulk sibling of {@link insertWithChildren}: N parent rows plus their child rows in
+     * ONE statement (a task-DAG persist — N task rows + one audit row each — used to
+     * cost two). Parent identity mapping rides the SAME serial-ascend guarantee the
+     * single-parent variant documents: the parent leg inserts `ORDER BY` an input
+     * ordinal, so generated serial ids ascend in input-row order, and a
+     * `row_number() OVER (ORDER BY pk)` CTE recovers each parent's input index for the
+     * child join:
+     *
+     *   WITH "__ibwc_parent__" AS (
+     *     INSERT INTO parent (cols)
+     *     SELECT cols FROM (VALUES (0, ...), (1, ...)) v("__ibwc_ord", cols)
+     *     ORDER BY v."__ibwc_ord" RETURNING *
+     *   ), "__ibwc_pord__" AS (
+     *     SELECT p.*, row_number() OVER (ORDER BY p."pk") - 1 AS "__ibwc_ord"
+     *     FROM "__ibwc_parent__" p
+     *   ), "__mutation__" AS (
+     *     INSERT INTO child ("fk", cols)
+     *     SELECT p."pk", v.cols
+     *     FROM (VALUES (0, pix, ...), ...) v("__ibwc_cord", "__ibwc_pix", cols)
+     *     JOIN "__ibwc_pord__" p ON p."__ibwc_ord" = v."__ibwc_pix"
+     *     ORDER BY v."__ibwc_cord" RETURNING <child cols>, "childPk"
+     *   )
+     *   SELECT "__mutation__".*, <parent cols + ordinal via the fk join>
+     *   FROM "__mutation__" JOIN "__ibwc_pord__" ON fk = pk ORDER BY child pk
+     *
+     * Single-statement atomicity: a failing leg rolls back both inserts. Parents come
+     * back in input order; children in child-input order.
+     *
+     * v1 restrictions: FLAT returning selectors on BOTH sides (no navigation
+     * projections); single-column auto/serial primary keys on both tables; no
+     * `unlessExists` guard; child rows must NOT carry the foreign-key property; EVERY
+     * parent must be referenced by at least one child (parents are returned through
+     * the child join — a childless parent would insert but vanish from the result, so
+     * it is rejected up front; use plain `insertBulk` for childless rows); the whole
+     * shape must fit one statement (no chunking).
+     */
+    insertBulkWithChildren(config) {
+        const { rows: childRows, foreignKey } = config.children;
+        if (config.rows.length === 0) {
+            throw new Error('insertBulkWithChildren: rows must be non-empty');
+        }
+        if (childRows.length === 0) {
+            throw new Error('insertBulkWithChildren: children.rows must be non-empty — use insertBulk for childless parents');
+        }
+        const referenced = new Set();
+        for (let i = 0; i < childRows.length; i++) {
+            const { parentIndex, row } = childRows[i];
+            if (!Number.isInteger(parentIndex) || parentIndex < 0 || parentIndex >= config.rows.length) {
+                throw new Error(`insertBulkWithChildren: child row at index ${i} has parentIndex ${parentIndex} outside 0..${config.rows.length - 1}`);
+            }
+            if (row[foreignKey] !== undefined) {
+                throw new Error(`insertBulkWithChildren: child row at index ${i} carries the foreign-key property "${foreignKey}" — it is sourced from its inserted parent`);
+            }
+            referenced.add(parentIndex);
+        }
+        for (let i = 0; i < config.rows.length; i++) {
+            if (!referenced.has(i)) {
+                throw new Error(`insertBulkWithChildren: parent at index ${i} has no child row — parents return through the child join (v1); insert childless rows via insertBulk`);
+            }
+        }
+        const columnCount = Math.max(1, Object.keys(childRows[0].row).length + 2);
+        const singleStatementLimit = Math.floor(Math.floor(65535 / columnCount) * 0.6);
+        if (childRows.length + config.rows.length > singleStatementLimit) {
+            throw new Error(`insertBulkWithChildren: ${config.rows.length} parents + ${childRows.length} children exceed the ~${singleStatementLimit}-row single-statement budget`);
+        }
+        return this.executeInsertBulkWithChildren(config);
+    }
+    /** @internal Async body of {@link insertBulkWithChildren} (validation stays synchronous). */
+    async executeInsertBulkWithChildren(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('insertBulkWithChildren: the child table uses a different database client or transaction than the parent — both must share one connection context');
+        }
+        const pkEntries = Object.entries(parentSchema.columns).filter(([, colBuilder]) => colBuilder.build().primaryKey);
+        if (pkEntries.length !== 1) {
+            throw new Error('insertBulkWithChildren requires a single-column parent primary key');
+        }
+        const parentPkDbName = pkEntries[0][1].build().name;
+        // ---- parent leg: ordinal-ordered VALUES so serial ids ascend in input order ----
+        const parentCompiled = this.compileValuesWithCasts(parentSchema, config.rows, null);
+        const parentColNames = parentCompiled.columns.map(c => `"${c.dbName}"`).join(', ');
+        const parentSelectCols = parentCompiled.columns.map(c => `v."${c.dbName}"`).join(', ');
+        const parentValueRows = parentCompiled.valueRows.map((row, ix) => `(${ix}, ${row})`).join(', ');
+        const params = [...parentCompiled.params];
+        const parentMock = this.createMockEntity();
+        const parentSelection = config.returning.parents(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(`insertBulkWithChildren: parents 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 });
+        }
+        const parentSql = `INSERT INTO ${this._getQualifiedTableName()} (${parentColNames})
+SELECT ${parentSelectCols} FROM (VALUES ${parentValueRows}) AS v("__ibwc_ord", ${parentColNames})
+ORDER BY v."__ibwc_ord"
+RETURNING *`;
+        // ---- child leg: (childOrd, parentIx, cells) VALUES joined to the ordinal CTE ----
+        const childSchema = childTable._getSchema();
+        const fkColBuilder = childSchema.columns[config.children.foreignKey];
+        if (!fkColBuilder) {
+            throw new Error(`insertBulkWithChildren: unknown child foreign-key property "${config.children.foreignKey}"`);
+        }
+        const fkDbName = fkColBuilder.build().name;
+        const childCompiled = childTable.compileValuesWithCasts(childSchema, config.children.rows.map(r => r.row), config.children.foreignKey);
+        const childColNames = childCompiled.columns.map(c => `"${c.dbName}"`).join(', ');
+        const childSelectCols = childCompiled.columns.map(c => `v."${c.dbName}"`).join(', ');
+        const childValueRows = childCompiled.valueRows.map((row, ix) => `(${ix}, ${config.children.rows[ix].parentIndex}, ${row})`).join(', ');
+        const childOffset = params.length;
+        let childSql = `INSERT INTO ${childTable._getQualifiedTableName()} ("${fkDbName}", ${childColNames})
+SELECT p."${parentPkDbName}", ${childSelectCols}
+FROM (VALUES ${childValueRows}) AS v("__ibwc_cord", "__ibwc_pix", ${childColNames})
+JOIN "__ibwc_pord__" p ON p."__ibwc_ord" = v."__ibwc_pix"
+ORDER BY v."__ibwc_cord"`;
+        childSql = childOffset === 0 ? childSql : (0, sql_utils_1.renumberPlaceholders)(childSql, childOffset);
+        params.push(...childCompiled.params);
+        // ---- assembly: flat child returning + parent cols through the fk join ----
+        if (childTable.detectNavigationInReturning(config.returning.children)) {
+            throw new Error('insertBulkWithChildren: children returning supports flat child columns only (v1)');
+        }
+        const childPkEntries = Object.entries(childSchema.columns).filter(([, colBuilder]) => colBuilder.build().primaryKey);
+        if (childPkEntries.length !== 1) {
+            throw new Error('insertBulkWithChildren requires a single-column child primary key');
+        }
+        const childPkDbName = childPkEntries[0][1].build().name;
+        const returningClause = childTable.buildReturningClause(config.returning.children);
+        const parentJoinSelects = [
+            `"__ibwc_pj__"."__ibwc_ord" AS "__ibwc_parent__.__ord"`,
+            ...parentSelCols.map(c => `"__ibwc_pj__"."${c.dbName}" AS "__ibwc_parent__.${c.prop}"`),
+        ];
+        const sql = `WITH "__ibwc_parent__" AS (
+${parentSql}
+),
+"__ibwc_pord__" AS (
+  SELECT p.*, row_number() OVER (ORDER BY p."${parentPkDbName}") - 1 AS "__ibwc_ord"
+  FROM "__ibwc_parent__" p
+),
+"__mutation__" AS (
+${childSql}
+RETURNING ${returningClause.sql}, "${fkDbName}" AS "__ibwc_child_fk__", "${childPkDbName}" AS "__ibwc_child_pk__"
+)
+SELECT "__mutation__".*, ${parentJoinSelects.join(', ')}
+FROM "__mutation__"
+JOIN "__ibwc_pord__" "__ibwc_pj__" ON "__ibwc_pj__"."${parentPkDbName}" = "__mutation__"."__ibwc_child_fk__"
+ORDER BY "__mutation__"."__ibwc_child_pk__"`;
+        const result = executor ? await executor.query(sql, params) : await client.query(sql, params);
+        const rawRows = result.rows;
+        const parentsByOrd = new Map();
+        const strippedRows = [];
+        for (const row of rawRows) {
+            const ord = Number(row['__ibwc_parent__.__ord']);
+            if (!parentsByOrd.has(ord)) {
+                const parentRow = {};
+                for (const col of parentSelCols) {
+                    const raw = row[`__ibwc_parent__.${col.prop}`];
+                    parentRow[col.prop] = col.mapper ? col.mapper.fromDriver(raw) : raw;
+                }
+                parentsByOrd.set(ord, parentRow);
+            }
+            const clean = {};
+            for (const [key, value] of Object.entries(row)) {
+                if (!key.startsWith('__ibwc_parent__.') && key !== '__ibwc_child_fk__' && key !== '__ibwc_child_pk__') {
+                    clean[key] = value;
+                }
+            }
+            strippedRows.push(clean);
+        }
+        const parents = [...parentsByOrd.entries()].sort((a, b) => a[0] - b[0]).map(([, parentRow]) => parentRow);
+        const children = childTable.mapReturningResults(strippedRows, returningClause.aliasToProperty);
+        return { parents, children };
+    }
+    /**
+     * 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 +2525,9 @@ class DbEntityTable {
                 mapper: config.mapper,
             });
         }
+        if (columnConfigs.length === 0) {
+            return null;
+        }
         // Build VALUES clauses
         const valuesClauses = [];
         const params = [];
@@ -2080,28 +2545,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 +2553,33 @@ class DbEntityTable {
         if (onConflictDoNothing) {
             sql += ' ON CONFLICT DO NOTHING';
         }
-        if (returningClause) {
-            sql += ` RETURNING ${returningClause.sql}`;
+        return { sql, params };
+    }
+    /**
+     * Builds a bare `DELETE FROM t WHERE "col" IN ($1, …)` statement (no
+     * RETURNING clause) so `MutationBatch` can compose it as a data-modifying
+     * CTE leg. Each value runs through the column's toDriver mapper — the same
+     * fidelity rule the insert/update legs follow. Returns null for an empty
+     * values array (mirroring the other leg builders' empty-input semantics);
+     * an unknown column property throws at build time.
+     * @internal
+     */
+    _buildDeleteWhereInStatement(field, values) {
+        if (values.length === 0) {
+            return null;
         }
-        const result = executor
-            ? await executor.query(sql, params)
-            : await client.query(sql, params);
-        if (!returningClause) {
-            return undefined;
+        const schema = this._getSchema();
+        const colBuilder = schema.columns[field];
+        if (!colBuilder) {
+            throw new Error(`deleteWhereIn: unknown column property "${field}" on entity "${schema.name}"`);
         }
-        return this.mapReturningResults(result.rows, returningClause.aliasToProperty);
+        const config = colBuilder.build();
+        const params = values.map(value => (config.mapper ? config.mapper.toDriver(value) : value));
+        const placeholders = params.map((_, ix) => `$${ix + 1}`).join(', ');
+        return {
+            sql: `DELETE FROM ${this._getQualifiedTableName()} WHERE "${config.name}" IN (${placeholders})`,
+            params,
+        };
     }
     /**
      * Upsert with advanced configuration
@@ -2238,13 +2698,13 @@ class DbEntityTable {
         };
     }
     /**
-     * Execute a single upsert batch
+     * The bare `INSERT .. ON CONFLICT` assembly (no RETURNING) shared by
+     * {@link upsertBulkSingle} and the MutationBatch upsert-leg compile —
+     * one definition so the two can never drift.
      * @internal
      */
-    async upsertBulkSingle(values, primaryKeys, updateColumns, updateColumnFilter, overridingSystemValue, targetWhere, setWhere, returning) {
+    buildUpsertStatementCore(values, primaryKeys, updateColumns, updateColumnFilter, overridingSystemValue, targetWhere, setWhere) {
         const schema = this._getSchema();
-        const executor = this._getExecutor();
-        const client = this._getClient();
         const qualifiedTableName = this._getQualifiedTableName();
         // Extract all unique column names from all data objects
         const columnConfigs = [];
@@ -2349,6 +2809,123 @@ class DbEntityTable {
                 sql += ` WHERE ${setWhere}`;
             }
         }
+        return { sql, params };
+    }
+    /**
+     * Builds a bare `UPDATE t SET .. WHERE "col" IN ($1, …)` statement (no
+     * RETURNING) so `MutationBatch.addUpdateWhereIn` can compose it as a
+     * data-modifying-CTE leg. SET semantics mirror the fluent `update()`:
+     * plain values run through column mappers, `SqlFragment` values inline
+     * with their params merged, and the lambda form resolves column refs
+     * against this table's mock row. Returns null for an empty values array.
+     * @internal
+     */
+    _buildUpdateWhereInStatement(field, values, set) {
+        if (values.length === 0) {
+            return null;
+        }
+        const schema = this._getSchema();
+        const whereColBuilder = schema.columns[field];
+        if (!whereColBuilder) {
+            throw new Error(`updateWhereIn: unknown column property "${field}" on entity "${schema.name}"`);
+        }
+        const whereConfig = whereColBuilder.build();
+        const resolvedSet = typeof set === 'function' ? set(this.createMockEntity()) : set;
+        const setClauses = [];
+        const params = [];
+        let paramIndex = 1;
+        for (const [key, value] of Object.entries(resolvedSet)) {
+            const column = schema.columns[key];
+            if (!column) {
+                continue;
+            }
+            const config = column.build();
+            if (value instanceof conditions_1.SqlFragment) {
+                const sqlBuildContext = {
+                    paramCounter: paramIndex,
+                    params,
+                };
+                const fragmentSql = value.buildSql(sqlBuildContext);
+                paramIndex = sqlBuildContext.paramCounter;
+                setClauses.push(`"${config.name}" = ${fragmentSql}`);
+                continue;
+            }
+            setClauses.push(`"${config.name}" = $${paramIndex++}`);
+            params.push(config.mapper ? config.mapper.toDriver(value) : value);
+        }
+        if (setClauses.length === 0) {
+            throw new Error(`updateWhereIn: no valid columns to update on entity "${schema.name}"`);
+        }
+        const whereParams = values.map(value => (whereConfig.mapper ? whereConfig.mapper.toDriver(value) : value));
+        const placeholders = whereParams.map(() => `$${paramIndex++}`).join(', ');
+        params.push(...whereParams);
+        return {
+            sql: `UPDATE ${this._getQualifiedTableName()} SET ${setClauses.join(', ')} WHERE "${whereConfig.name}" IN (${placeholders})`,
+            params,
+        };
+    }
+    /**
+     * Bare `INSERT .. ON CONFLICT` compile (no RETURNING) for the MutationBatch
+     * upsert leg — the {@link buildUpsertStatementCore} assembly with a narrow
+     * plain config (prop-name primaryKey + updateColumns; no chunking, no
+     * targetWhere/setWhere/system-value overrides in v1).
+     * @internal
+     */
+    _buildUpsertBulkStatement(values, config) {
+        if (values.length === 0) {
+            return null;
+        }
+        const primaryKeys = Array.isArray(config.primaryKey) ? config.primaryKey : [config.primaryKey];
+        return this.buildUpsertStatementCore(values, primaryKeys, config.updateColumns, undefined, false, undefined, undefined);
+    }
+    /**
+     * Bare `INSERT INTO t (..) SELECT <cells> FROM "__MB_PARENT__" WHERE
+     * "__MB_PARENT__"."<col>" <> $n` compile for the MutationBatch dependent
+     * leg — a single row inserted iff the parent leg's exposed column differs
+     * from the sentinel (the conditional-audit-log shape). Cells reuse the
+     * insertWithChildren `$n::type` cast technique so types survive without a
+     * VALUES-derived table; the `__MB_PARENT__` token is rewritten to the
+     * parent's actual CTE name at batch assembly.
+     * @internal
+     */
+    _buildDependentInsertSelectStatement(row, whereColumnAlias, whereNotEquals) {
+        const schema = this._getSchema();
+        const compiled = this.compileValuesWithCasts(schema, [row], null);
+        const columnList = compiled.columns.map(c => `"${c.dbName}"`).join(', ');
+        const params = [...compiled.params];
+        const sentinelIndex = params.length + 1;
+        params.push(whereNotEquals);
+        return {
+            sql: `INSERT INTO ${this._getQualifiedTableName()} (${columnList}) SELECT ${compiled.valueRows[0]} FROM "__MB_PARENT__" WHERE "__MB_PARENT__"."${whereColumnAlias}" <> $${sentinelIndex}`,
+            params,
+        };
+    }
+    /**
+     * Resolves entity property names to their DB column names (throws on an
+     * unknown property) — the MutationBatch expose/returning lists come in as
+     * prop names and compile to quoted DB identifiers.
+     * @internal
+     */
+    _resolveColumnDbNames(props) {
+        const schema = this._getSchema();
+        return props.map((prop) => {
+            const colBuilder = schema.columns[prop];
+            if (!colBuilder) {
+                throw new Error(`Unknown column property "${prop}" on entity "${schema.name}"`);
+            }
+            return { prop, dbName: colBuilder.build().name };
+        });
+    }
+    /**
+     * Execute a single upsert batch
+     * @internal
+     */
+    async upsertBulkSingle(values, primaryKeys, updateColumns, updateColumnFilter, overridingSystemValue, targetWhere, setWhere, returning) {
+        const executor = this._getExecutor();
+        const client = this._getClient();
+        const built = this.buildUpsertStatementCore(values, primaryKeys, updateColumns, updateColumnFilter, overridingSystemValue, targetWhere, setWhere);
+        let sql = built.sql;
+        const params = built.params;
         // Check if RETURNING uses navigation properties
         const navigationInfo = returning && returning !== true && typeof returning === 'function'
             ? this.detectNavigationInReturning(returning)
@@ -2825,32 +3402,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 +3444,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 +3578,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 +3937,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 +4077,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 +4105,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 };
     }
     /**