turbine-orm 0.79.1 → 0.80.0

package/dist/powql.js

@@ -35,9 +35,10 @@
  * @module
  */
 import { randomUUID } from 'node:crypto';
+import { guardCheckout } from './connection-guard.js';
 import { NotFoundError, OptimisticLockError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
-import { ALL_POWDB_CAPABILITIES, baseTsType, coerceNativeValue, isJsonColumn, isPowdbDatetimeColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlDotted, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb-shared.js';
+import { ALL_POWDB_CAPABILITIES, atLeastVersion, baseTsType, coerceNativeValue, isJsonColumn, isPowdbDatetimeColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, parsePowdbSemver, powqlColumnType, quotePowqlDotted, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb-shared.js';
 import { assertAggregatePiiOptIn } from './query/aggregates.js';
 import { assertMutationWhereIdentifiesOneRow, assertWhereIdentifiesOneRow, expandCompoundUniqueWhere, } from './query/compound-unique.js';
 import { ARRAY_OPERATOR_KEYS, isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
@@ -1236,6 +1237,34 @@ export class PowqlInterface {
         }
         return entity;
     }
+    /**
+     * A single-row write's `select` / `omit`, resolved by {@link projectionPlan}
+     * so the rules and messages are the read path's, and the SQL engines' (an
+     * unknown name is E003, `select` must name something, the pair is refused).
+     * `undefined` for the default return shape. Resolved BEFORE the write is sent,
+     * so a bad projection writes nothing.
+     *
+     * The narrowing itself happens on the returned row ({@link shapeWriteRow}):
+     * PowQL's `returning` takes no column list (see {@link stripWritePii}), so
+     * unlike the SQL engines the unselected columns still cross the wire here.
+     * The RESULT is identical across engines; the byte saving is SQL-only.
+     */
+    writeReturnPlan(args) {
+        if (args.select === undefined && args.omit === undefined)
+            return undefined;
+        return this.projectionPlan(args.select, args.omit, false);
+    }
+    /** Apply a write's return plan to its row, or the default PII strip without one. */
+    shapeWriteRow(entity, plan) {
+        if (!entity || !plan)
+            return this.stripWritePii(entity);
+        const keep = new Set(plan.cols.filter((c) => !plan.forcedPk.includes(c)).map((c) => this.meta.reverseColumnMap[c] ?? c));
+        for (const key of Object.keys(entity)) {
+            if (!keep.has(key))
+                delete entity[key];
+        }
+        return entity;
+    }
     /** `{ .c1, .c2, … }` projection clause. */
     projection(cols) {
         return `{ ${cols.map((c) => this.colRefName(c)).join(', ')} }`;
@@ -2676,6 +2705,7 @@ export class PowqlInterface {
     }
     async create(args) {
         return this.withMiddleware('create', args, async () => {
+            const plan = this.writeReturnPlan(args);
             if (hasRelationFields(args.data, this.meta)) {
                 return this.nestedCreate(args);
             }
@@ -2687,7 +2717,7 @@ export class PowqlInterface {
                 .join(', ');
             // `returning` surfaces the inserted row (all columns, schema order) in one round-trip.
             const { rows, native } = await this.exec(`insert ${this.qt} { ${body} } returning`, params, args.timeout, 'create');
-            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
+            const row = rows.length ? this.shapeWriteRow(this.shape(rows, native)[0], plan) : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: data });
             return row;
@@ -2762,6 +2792,7 @@ export class PowqlInterface {
     }
     async update(args) {
         return this.withMiddleware('update', args, async () => {
+            const plan = this.writeReturnPlan(args);
             if (hasRelationFields(args.data, this.meta)) {
                 // The nested engine re-enters `update` / `findUnique` for the parent
                 // row before it writes anything, so the identity rule below still runs
@@ -2799,7 +2830,7 @@ export class PowqlInterface {
             }
             // `returning` hands back the post-update row(s); take the first (single-row contract).
             const { rows, native } = await this.exec(`${this.qt} filter ${where} update { ${setClause} } returning`, params, args.timeout, 'update');
-            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
+            const row = rows.length ? this.shapeWriteRow(this.shape(rows, native)[0], plan) : null;
             if (!row) {
                 if (lock) {
                     throw new OptimisticLockError({
@@ -2876,18 +2907,21 @@ export class PowqlInterface {
     }
     async nestedCreate(args) {
         const data = args.data;
+        // Applied by the nested engine's final read-back, as on the SQL engines.
+        const shape = { select: args.select, omit: args.omit };
         if (this.isTxScoped()) {
-            return executeNestedCreate(this.buildNestedCtx(), this.table, data);
+            return executeNestedCreate(this.buildNestedCtx(), this.table, data, 0, [], shape);
         }
-        return this.runInImplicitTx((ctx) => executeNestedCreate(ctx, this.table, data));
+        return this.runInImplicitTx((ctx) => executeNestedCreate(ctx, this.table, data, 0, [], shape));
     }
     async nestedUpdate(args) {
         const data = args.data;
         const where = args.where;
+        const shape = { select: args.select, omit: args.omit };
         if (this.isTxScoped()) {
-            return executeNestedUpdate(this.buildNestedCtx(), this.table, where, data);
+            return executeNestedUpdate(this.buildNestedCtx(), this.table, where, data, 0, [], shape);
         }
-        return this.runInImplicitTx((ctx) => executeNestedUpdate(ctx, this.table, where, data));
+        return this.runInImplicitTx((ctx) => executeNestedUpdate(ctx, this.table, where, data, 0, [], shape));
     }
     /** Open a flat PowDB transaction on a pinned connection and run `fn` inside it. */
     async runInImplicitTx(fn) {
@@ -2900,6 +2934,9 @@ export class PowqlInterface {
         // drifts from `powdbDialect`; falls back to the literal lowercase keywords.
         const d = this.options.dialect;
         const client = await this.pool.connect();
+        // A no-op today (PowDB checkouts have no event surface), kept so this path
+        // cannot become the one unguarded checkout if a transport ever emits 'error'.
+        const checkout = guardCheckout(client);
         let began = false;
         try {
             await client.query(d?.beginStatement?.() ?? 'begin');
@@ -2939,7 +2976,7 @@ export class PowqlInterface {
             throw err;
         }
         finally {
-            client.release();
+            checkout.release();
         }
     }
     /** Already inside a transaction: build a context whose table accessors reuse the pinned pool. */
@@ -2952,6 +2989,7 @@ export class PowqlInterface {
     }
     async delete(args) {
         return this.withMiddleware('delete', args, async () => {
+            const plan = this.writeReturnPlan(args);
             const allowFullTableScan = resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan');
             const userWhere = this.expandedWhere(args.where);
             const params = [];
@@ -2962,7 +3000,7 @@ export class PowqlInterface {
             where = this.applyGlobalFilter(where, params, args.skipGlobalFilters);
             // `returning` hands back the deleted row(s), no separate pre-image reselect needed.
             const { rows, native } = await this.exec(`${this.qt} filter ${where} delete returning`, params, args.timeout, 'delete');
-            const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
+            const row = rows.length ? this.shapeWriteRow(this.shape(rows, native)[0], plan) : null;
             if (!row)
                 throw new NotFoundError({ table: this.table, where: args.where });
             return row;
@@ -2988,13 +3026,45 @@ export class PowqlInterface {
             // disagreeing about whether a query is VALID, which is the failure class
             // 0.64.0 and 0.72.0 were both spent on. Before `applyPkDefault`, so a
             // refused upsert mints no client-side UUID and sends nothing.
-            this.assertMutationIdentifiesOneRow(this.expandedWhere(args.where), false, 'upsert');
+            const upsertWhere = (this.expandedWhere(args.where) ?? {});
+            this.assertMutationIdentifiesOneRow(upsertWhere, false, 'upsert');
+            const plan = this.writeReturnPlan(args);
             const createData = this.applyPkDefault(args.create);
             const pkCol = this.meta.primaryKey[0];
-            if (this.meta.primaryKey.length !== 1 || !pkCol) {
-                // PowQL's native `upsert … on .col` takes a single conflict column, so a
-                // composite PK falls back to an atomic reselect-or-write transaction.
-                return this.upsertComposite(createData, args.update);
+            // The conflict target is the columns `where` names, as on the SQL
+            // engines (`ON CONFLICT (<where keys>)`), with the conflicting VALUES
+            // taken from `create`. This path used to conflict on the primary key
+            // whatever `where` named, so an upsert keyed on another unique column
+            // (`where: { email }`) never found the existing row.
+            const conflictColumns = Object.keys(upsertWhere)
+                .filter((k) => upsertWhere[k] !== undefined)
+                .map((k) => this.column(k).name);
+            // PowQL's native `upsert … on .col` expresses exactly one shape: a single
+            // conflict column that is the primary key, with no predicate on its
+            // conflict branch. Everything else is an atomic reselect-or-write
+            // transaction.
+            //
+            // That includes a table under a global filter. The native statement's
+            // `on conflict` branch carries no predicate, so a tenant-scoped client
+            // whose `create` key matched ANOTHER tenant's row updated that row, and
+            // the tenant-filtered reselect then reported the write it had just made
+            // as a NotFoundError. The SQL engines guard the same branch with the
+            // filter (`DO UPDATE … WHERE tenant_id = $n`). The lookup-first path runs
+            // its find and its update through the filtered interface, so another
+            // tenant's row is invisible to it: the insert then collides on the key
+            // and fails, as it does on the SQL engines, and nothing is overwritten.
+            const filtered = this.applyGlobalFilter('', [], args.skipGlobalFilters) !== '';
+            const native = this.meta.primaryKey.length === 1 &&
+                pkCol !== undefined &&
+                conflictColumns.length === 1 &&
+                conflictColumns[0] === pkCol &&
+                !filtered;
+            if (!native) {
+                return this.upsertLookupFirst(createData, args.update, conflictColumns, {
+                    select: args.select,
+                    omit: args.omit,
+                    skipGlobalFilters: args.skipGlobalFilters,
+                });
             }
             const params = [];
             const createBody = this.scalarData(createData)
@@ -3007,40 +3077,61 @@ export class PowqlInterface {
             // reselect-by-PK fetch; create/update/delete all use `returning`.
             await this.exec(`upsert ${this.qt} on ${this.colRefName(pkCol)} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout, 'upsert');
             const pkField = this.meta.reverseColumnMap[pkCol] ?? pkCol;
-            // Either spelling, as `upsertComposite` already does below: reading the
+            // Either spelling, as `upsertLookupFirst` already does below: reading the
             // camelCase field alone reselected `undefined` for a snake-spelled PK and
             // reported a write that had SUCCEEDED as a NotFoundError.
-            const row = await this.reselectByPk(createData[pkField] ?? createData[pkCol], args.timeout);
+            // `args` carries skipGlobalFilters too: an upsert that opted out of the
+            // filter must not have its own write filtered out of the reselect.
+            const row = await this.reselectByPk(createData[pkField] ?? createData[pkCol], args.timeout, args);
             if (!row)
                 throw new NotFoundError({ table: this.table, where: createData });
-            return row;
+            // Without a plan the reselect's default projection already left PII out.
+            return plan ? this.shapeWriteRow(row, plan) : row;
         });
     }
     /**
-     * Composite-key upsert: PowQL's `upsert … on .col` only takes one conflict
-     * column, so reselect by the full composite PK and update-or-create inside one
-     * flat transaction (PowDB single-writer makes the read-then-write safe from
-     * concurrent writers; the transaction makes it atomic with the write).
-     */
-    async upsertComposite(createData, updateData) {
+     * Upsert as a reselect-or-write inside one flat transaction, for every shape
+     * the native `upsert … on .col` statement cannot express: a conflict target
+     * other than a single-column primary key (it takes one column and PowDB has
+     * no composite unique), and a table under a global filter (its conflict
+     * branch takes no predicate). PowDB's single writer makes the read-then-write
+     * safe from concurrent writers; the transaction makes it atomic with the
+     * write.
+     *
+     * The row is looked up by the conflict columns with `create`'s values for
+     * them, which is what `ON CONFLICT (<cols>)` compares on the SQL engines. The
+     * find and the update run through the transaction's table interface, so a
+     * configured global filter applies to both exactly as it does to any other
+     * read or write, and `skipGlobalFilters` is forwarded to both.
+     */
+    async upsertLookupFirst(createData, updateData, conflictColumns, shape) {
+        const { skipGlobalFilters, ...projection } = shape;
+        const skip = skipGlobalFilters === undefined ? {} : { skipGlobalFilters };
         // Accept either the camelCase field or the snake_case column in `create`
         // (create() resolves both), and key the where by field name.
-        const pkPairs = this.meta.primaryKey.map((pk) => {
-            const field = this.meta.reverseColumnMap[pk] ?? pk;
-            return { field, value: createData[field] ?? createData[pk] };
+        const keyPairs = conflictColumns.map((col) => {
+            const field = this.meta.reverseColumnMap[col] ?? col;
+            return { field, value: createData[field] ?? createData[col] };
         });
-        if (pkPairs.some((p) => p.value == null)) {
-            throw new ValidationError(`upsert on "${this.table}" needs every composite-PK field in \`create\` (${pkPairs
+        const keyless = keyPairs.some((p) => p.value == null);
+        const isCompositePk = keyPairs.length > 1 &&
+            keyPairs.length === this.meta.primaryKey.length &&
+            conflictColumns.every((c) => this.meta.primaryKey.includes(c));
+        if (keyless && isCompositePk) {
+            throw new ValidationError(`upsert on "${this.table}" needs every composite-PK field in \`create\` (${keyPairs
                 .map((p) => p.field)
                 .join(', ')}).`);
         }
-        const pkWhere = Object.fromEntries(pkPairs.map((p) => [p.field, p.value]));
+        const keyWhere = Object.fromEntries(keyPairs.map((p) => [p.field, p.value]));
         const run = async (ctx) => {
             const tbl = ctx.tx.table(this.table);
-            const existing = await tbl.findUnique({ where: pkWhere });
+            // A row whose `create` leaves a conflict column unset cannot collide on
+            // it (NULL never equals NULL in a unique index, and a server-assigned key
+            // is new), which is what `ON CONFLICT` concludes on the SQL engines too.
+            const existing = keyless ? null : await tbl.findUnique({ where: keyWhere, ...skip });
             return existing
-                ? (await tbl.update({ where: pkWhere, data: updateData }))
-                : (await tbl.create({ data: createData }));
+                ? (await tbl.update({ where: keyWhere, data: updateData, ...projection, ...skip }))
+                : (await tbl.create({ data: createData, ...projection }));
         };
         return this.isTxScoped() ? run(this.buildNestedCtx()) : this.runInImplicitTx(run);
     }
@@ -3087,33 +3178,64 @@ export class PowqlInterface {
             'every SQL engine exactly when the column is nullable. `_count: true` (a row count) and a per-field ' +
             '`_count` of a NOT NULL column are correct on every version and are never refused.');
     }
+    /**
+     * Can `aggregate()` compute several aggregates in ONE statement on this engine?
+     *
+     * PowQL refuses a bare multi-aggregate projection (`T { a: sum(.x), b: sum(.y) }`
+     * is "aggregate function in an unsupported position" on every engine version),
+     * so the only one-statement form is a grouping over a literal key,
+     * `T filter … group 1 { agg_0: sum(.x), agg_1: sum(.y) }`, which yields a
+     * single group holding every row the filter matched. Measured against the
+     * embedded addon at 0.7.1 through 0.28: below 0.13 a literal group key does not
+     * parse, from 0.13 to 0.19.1 the grouped per-field `count` disagrees with the
+     * scalar `count(T { .col })` on a nullable column, and from 0.20 every
+     * aggregate kind (count / sum / avg / min / max over int, float, str, an
+     * all-null column, and several filters) answers identically on both wires.
+     *
+     * Derived from the PROBED engine version rather than from a capability flag,
+     * so an unprobed pool (`engineVersion: null`, e.g. an injected pool carrying
+     * {@link ALL_POWDB_CAPABILITIES}) keeps the per-field statements: this changes
+     * the emitted PowQL, and an older engine would reject it outright, the same
+     * probe-only discipline `nestedProjections` follows.
+     */
+    get groupsAggregatesInOneStatement() {
+        const sem = parsePowdbSemver(this.capabilities.engineVersion);
+        return sem !== null && atLeastVersion(sem, 0, 20);
+    }
     async aggregate(args) {
         this.assertNoForceCustomPlan(args);
         return this.withMiddleware('aggregate', args, async () => {
-            // One scalar query per aggregate, PowDB's bare-projection aggregate is broken.
             const result = {};
             const filterParams = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
             let where = this.buildWhere(resolvedWhere, filterParams);
             where = this.applyGlobalFilter(where, filterParams, args.skipGlobalFilters);
             const filter = where ? ` filter ${where}` : '';
-            const scalar = async (expr) => {
-                const params = [...filterParams];
-                const { rows } = await this.exec(expr, params, args.timeout, 'aggregate');
-                const v = rows[0]?.value;
-                return v == null || v === 'null' ? null : Number(v);
-            };
+            const plan = [];
             if (args._count) {
                 if (args._count === true) {
-                    result._count = (await scalar(`count(${this.qt}${filter})`)) ?? 0;
+                    plan.push({
+                        scalar: `count(${this.qt}${filter})`,
+                        inner: 'count(*)',
+                        assign: (v) => {
+                            result._count = v ?? 0;
+                        },
+                    });
                 }
                 else {
                     const counts = {};
+                    result._count = counts;
                     for (const field of Object.keys(args._count).filter((f) => args._count[f])) {
                         this.assertProjectedCountSupported(field);
-                        counts[field] = (await scalar(`count(${this.qt}${filter} { ${this.ref(field)} })`)) ?? 0;
+                        const ref = this.ref(field);
+                        plan.push({
+                            scalar: `count(${this.qt}${filter} { ${ref} })`,
+                            inner: `count(${ref})`,
+                            assign: (v) => {
+                                counts[field] = v ?? 0;
+                            },
+                        });
                     }
-                    result._count = counts;
                 }
             }
             for (const fn of ['_sum', '_avg', '_min', '_max']) {
@@ -3121,15 +3243,44 @@ export class PowqlInterface {
                 if (!spec)
                     continue;
                 const acc = {};
+                result[fn] = acc;
+                const powfn = fn.slice(1); // sum/avg/min/max
                 for (const field of Object.keys(spec).filter((f) => spec[f])) {
-                    const powfn = fn.slice(1); // sum/avg/min/max
                     // Same PII contract as the SQL engines: _min/_max return a stored cell.
                     if (fn === '_min' || fn === '_max') {
                         assertAggregatePiiOptIn(this.table, this.meta, field, this.column(field).name, `aggregate ${fn}`, resolveUnsafeFlag(args.includePii, 'includePii'));
                     }
-                    acc[field] = await scalar(`${powfn}(${this.qt}${filter} { ${this.ref(field)} })`);
+                    const ref = this.ref(field);
+                    plan.push({
+                        scalar: `${powfn}(${this.qt}${filter} { ${ref} })`,
+                        inner: `${powfn}(${ref})`,
+                        assign: (v) => {
+                            acc[field] = v;
+                        },
+                    });
                 }
-                result[fn] = acc;
+            }
+            // A scalar cell and a grouped cell decode through the same wire decoder,
+            // so one coercion serves both forms.
+            const toNumber = (v) => (v == null || v === 'null' ? null : Number(v));
+            if (plan.length > 1 && this.groupsAggregatesInOneStatement) {
+                const proj = plan.map((p, i) => `agg_${i}: ${p.inner}`).join(', ');
+                const { rows } = await this.exec(`${this.qt}${filter} group 1 { ${proj} }`, [...filterParams], args.timeout, 'aggregate');
+                // Zero groups means the filter matched no row. The per-field statements
+                // below answer that case instead of a synthesized one, because what an
+                // aggregate over NO rows returns is engine-versioned (`sum` answered 0
+                // before PowDB 0.28 and null since), and the scalar form is the one
+                // whose answer this method has always returned.
+                const row = rows.length === 1 ? rows[0] : undefined;
+                if (row) {
+                    for (const [i, p] of plan.entries())
+                        p.assign(toNumber(row[`agg_${i}`]));
+                    return result;
+                }
+            }
+            for (const p of plan) {
+                const { rows } = await this.exec(p.scalar, [...filterParams], args.timeout, 'aggregate');
+                p.assign(toNumber(rows[0]?.value));
             }
             return result;
         });
@@ -3532,12 +3683,15 @@ export class PowqlInterface {
     // Reselect helper (upsert only, PowDB's upsert has no `returning`)
     // -------------------------------------------------------------------------
     /** Reselect a single row by its single-column primary key value. */
-    async reselectByPk(pkValue, timeout) {
+    async reselectByPk(pkValue, timeout, shape) {
         const pkField = this.meta.reverseColumnMap[this.meta.primaryKey[0]] ?? this.meta.primaryKey[0];
         const { rows, native } = await this.runFind({
             where: { [pkField]: pkValue },
             limit: 1,
             timeout,
+            select: shape?.select,
+            omit: shape?.omit,
+            ...(shape?.skipGlobalFilters === undefined ? {} : { skipGlobalFilters: shape.skipGlobalFilters }),
         });
         return rows.length ? this.shape(rows, native)[0] : null;
     }

package/dist/prisma-compat.js

@@ -968,6 +968,22 @@ function resolveWriteProjection(ctx, mm, op, args) {
     }
     return NO_WRITE_PROJECTION;
 }
+/**
+ * The same projection in core's spelling, for the write itself. Passed DOWN so
+ * the SQL engines narrow the RETURNING list rather than fetching the whole row
+ * for {@link applyWriteProjection} to trim afterwards, which on a table with a
+ * large JSON column was most of the bytes the write moved. The trim stays: it
+ * is what keeps the result Prisma-shaped on every path, including the
+ * lookup-first upsert and PowDB, whose `returning` takes no column list.
+ */
+function coreWriteProjection(mm, proj) {
+    const spell = (keys) => Object.fromEntries([...keys].map((k) => [renameField(mm, k), true]));
+    if (proj.pick)
+        return { select: spell(proj.pick) };
+    if (proj.omit)
+        return { omit: spell(proj.omit) };
+    return {};
+}
 /** Apply a {@link WriteProjection} to one already-reshaped write result row. */
 function applyWriteProjection(proj, row) {
     if (!isPlainObject(row))
@@ -1762,9 +1778,12 @@ function upsertKeysMatch(t) {
 /** Prisma upsert semantics: look up by where; update the found row, else insert create. */
 async function upsertLookupFirst(qi, t) {
     const existing = await qi.findUnique({ where: t.where });
+    // The projection rides along so both branches return what the native upsert
+    // path returns (an explicitly selected PII field included).
+    const shape = { select: t.select, omit: t.omit };
     if (existing)
-        return qi.update({ where: t.where, data: t.update });
-    return qi.create({ data: t.create });
+        return qi.update({ where: t.where, data: t.update, ...shape });
+    return qi.create({ data: t.create, ...shape });
 }
 /**
  * The row shapes a translated `createMany` has to insert, as contiguous runs
@@ -1872,7 +1891,10 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
             const shape = (raw) => applyWriteProjection(proj, reshapeRow(ctx, mm, raw));
             return defer('create', args, () => {
                 proj = resolveWriteProjection(ctx, mm, 'create', args);
-                const t = { data: translateWriteData(ctx, mm, applyCreateDefaults(mm, args.data)) };
+                const t = {
+                    data: translateWriteData(ctx, mm, applyCreateDefaults(mm, args.data)),
+                    ...coreWriteProjection(mm, proj),
+                };
                 applyNativeOptions(CREATE_OPTIONS, args, t);
                 return t;
             }, (qi, t) => qi.create(t).then(shape), {
@@ -1917,6 +1939,7 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
                 const t = {
                     where: translateWhere(ctx, mm, a.where),
                     data: translateWriteData(ctx, mm, applyUpdateTouch(mm, a.data)),
+                    ...coreWriteProjection(mm, proj),
                 };
                 applyNativeOptions(UPDATE_OPTIONS, a, t);
                 // `optimisticLock.field` is a FIELD NAME, so it is renamed rather than
@@ -1956,7 +1979,7 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
             return defer('delete', args, () => {
                 const a = requireWhere(args, 'delete');
                 proj = resolveWriteProjection(ctx, mm, 'delete', a);
-                const t = { where: translateWhere(ctx, mm, a.where) };
+                const t = { where: translateWhere(ctx, mm, a.where), ...coreWriteProjection(mm, proj) };
                 applyNativeOptions(DELETE_OPTIONS, a, t);
                 return t;
             }, (qi, t) => qi.delete(t).then(shape), { build: (qi, t) => qi.buildDelete(t), reshape: shape });
@@ -1981,6 +2004,7 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
                     where: translateWhere(ctx, mm, a.where),
                     create: translateWriteData(ctx, mm, applyCreateDefaults(mm, a.create)),
                     update: translateWriteData(ctx, mm, applyUpdateTouch(mm, a.update)),
+                    ...coreWriteProjection(mm, proj),
                 };
                 applyNativeOptions(UPSERT_OPTIONS, a, t);
                 return t;

package/dist/query/builder.d.ts

@@ -12,7 +12,7 @@
  */
 import type { PgCompatPool } from '../pg-types.js';
 import type { SchemaMetadata } from '../schema.js';
-import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, GroupByResult, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
+import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, GroupByResult, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
 /**
  * Discard the memoized cross-check environment so the next cache hit re-reads
  * `process.env`.
@@ -993,10 +993,34 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * here and is not refused.
      */
     private preparedNameFor;
+    /**
+     * {@link queryWithTimeout} for a statement that only READS, which makes it
+     * safe to send twice. Outside a transaction, a read that fails because the
+     * connection it went out on had already been closed by the server
+     * ({@link isStaleConnectionError}) is sent once more, after one event-loop
+     * turn, on whatever connection the pool hands out next.
+     *
+     * Reads only, and the distinction is the whole design. For a write, "the
+     * connection died" does not say whether the statement committed first: a
+     * connection can drop after the server commits and before the reply
+     * arrives, so resending an INSERT can insert it twice. A read has no such
+     * outcome. Nor inside a transaction, where the connection that died WAS the
+     * transaction and a retry on another one would run outside it.
+     *
+     * The loop turn is what makes a second attempt worth making: pg-pool evicts
+     * an idle connection whose close it has read, so after one poll phase every
+     * other connection that died alongside this one is gone from the idle list
+     * rather than lent out to the retry.
+     *
+     * Every read call site uses this and every write uses `queryWithTimeout`
+     * directly; `src/test/stale-connection-retry.test.ts` pins which is which.
+     */
+    private readWithTimeout;
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
      * pg driver errors are translated to typed Turbine errors via wrapPgError.
+     * `retryIfStale` is {@link readWithTimeout}'s; nothing else sets it.
      */
     private queryWithTimeout;
     /**
@@ -1013,11 +1037,18 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *     write and a follow-up SELECT; the SELECT's rows feed the transform.
      */
     private executeMutation;
-    buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
+    buildCreate<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateArgs<T, R, S, O>): DeferredQuery<FieldResult<T, S, O>>;
+    /**
+     * A single-row write's `select` / `omit`, resolved through the SAME
+     * `resolveProjection` reads use (see WriteProjection in writes.ts), or
+     * `undefined` for the default return shape. Resolved here rather than in
+     * writes.ts because relations.ts imports writes.ts.
+     */
+    private resolveWriteProjection;
     buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
-    buildUpdate(args: UpdateArgs<T>): DeferredQuery<T>;
-    buildDelete(args: DeleteArgs<T>): DeferredQuery<T>;
-    buildUpsert(args: UpsertArgs<T>): DeferredQuery<T>;
+    buildUpdate<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, R, S, O>): DeferredQuery<FieldResult<T, S, O>>;
+    buildDelete<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: DeleteArgs<T, R, S, O>): DeferredQuery<FieldResult<T, S, O>>;
+    buildUpsert<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpsertArgs<T, R, S, O>): DeferredQuery<FieldResult<T, S, O>>;
     buildUpdateMany(args: UpdateManyArgs<T>): DeferredQuery<{
         count: number;
     }>;
@@ -1235,34 +1266,23 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildFindFirstOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O>>;
     findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
     buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O>>;
-    create(args: CreateArgs<T, R>): Promise<T>;
+    create<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
-    update(args: UpdateArgs<T, R>): Promise<T>;
+    update<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
     private nestedCreate;
     private nestedUpdate;
     /**
-     * Check out a pooled connection, translating a driver failure into a typed
-     * Turbine error.
-     *
-     * `pool.connect()` is where the first-run failures land: wrong password
-     * (SQLSTATE 28P01), no such database (3D000), nothing listening
-     * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
-     * those surfaces from an ordinary `db.users.create({ data: { ...nested } })`
-     * as a raw pg `DatabaseError` whose `.code` is a SQLSTATE, on the same
-     * property Turbine puts `TURBINE_E0NN` in.
-     *
-     * client.ts has its own copy for `$transaction` / `connect()`; this one
-     * exists because `query/` must not import client.ts (circular dependency).
-     * The query paths need no equivalent: `pool.query()` opens the connection
-     * itself and rejects with the connect error, which the query boundary
-     * already wraps.
+     * Check out a guarded pooled connection, as a typed error when that fails.
+     * Shared with client.ts through checkout.ts (see there for why each part
+     * matters); the cursor stream holds it, and a nested write opens its
+     * implicit transaction on one through `openCheckout`.
      */
     private acquireConnection;
     private runInImplicitTx;
     private buildNestedCtx;
     private makeTxProxy;
-    delete(args: DeleteArgs<T, R>): Promise<T>;
-    upsert(args: UpsertArgs<T, R>): Promise<T>;
+    delete<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: DeleteArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
+    upsert<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpsertArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
     updateMany(args: UpdateManyArgs<T, R>): Promise<{
         count: number;
     }>;