turbine-orm 0.79.1 → 0.80.0

package/dist/query/builder.js

@@ -10,8 +10,10 @@
  * Schema-driven: all column names, types, and relations come from introspected
  * metadata, nothing is hardcoded.
  */
+import { acquireConnection, openCheckout } from '../checkout.js';
+import { settleEventLoop } from '../connection-guard.js';
 import { postgresDialect } from '../dialect.js';
-import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError } from '../errors.js';
+import { explainConnectionLoss, isStaleConnectionError, NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from '../errors.js';
 import { missingIndexForRelation, schemaHasIndexInfo } from '../index-advisor.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
 import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
@@ -1677,7 +1679,7 @@ export class QueryInterface {
             const deferred = single
                 ? this.buildFindUnique(baseArgs)
                 : this.buildFindMany(baseArgs);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
+            const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             const rows = deferred.transform(result);
             const entities = single ? (rows ? [rows] : []) : rows;
             // Unconditionally, even for zero rows: with no parents the loader is a
@@ -1718,7 +1720,7 @@ export class QueryInterface {
             // too: a batched load re-issues the SAME tenant-shaped predicate one
             // level down, so leaving those named would keep exactly the plan-cache
             // exposure the caller asked to be rid of.
-            exec: (sql, params, preparedName) => this.queryWithTimeout(sql, params, timeout, this.preparedNameFor({ forceCustomPlan }, preparedName)),
+            exec: (sql, params, preparedName) => this.readWithTimeout(sql, params, timeout, this.preparedNameFor({ forceCustomPlan }, preparedName)),
             quote: (name) => this.q(name),
             buildInClause: (expr, paramRef, negated) => this.inClause(expr, paramRef, negated),
             inClauseParam: (values) => this.inParam(values),
@@ -1831,7 +1833,7 @@ export class QueryInterface {
         const { baseArgs, strip } = this.prepareBatchedBase(args, withClause);
         // baseArgs.with is always undefined here; the cast just bridges the R generic.
         const deferred = this.buildFindMany(baseArgs);
-        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
+        const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
         const entities = deferred.transform(result);
         // Unconditionally, even for zero rows: see the 'auto' path above, the
         // loader doubles as the compile-time validation walk of the `with` tree.
@@ -1994,7 +1996,7 @@ export class QueryInterface {
     resetUnlimitedWarnings() {
         this.warnedTables.clear();
     }
-    emitQueryEvent(sql, params, duration, action, rows, error) {
+    emitQueryEvent(sql, params, duration, action, rows, error, retried) {
         const onQuery = this.options?._onQuery;
         if (!onQuery)
             return;
@@ -2009,6 +2011,7 @@ export class QueryInterface {
                 timestamp: new Date(),
                 error,
                 strategy: this.currentStrategyTag,
+                ...(retried ? { retried: true } : {}),
             });
         }
         catch {
@@ -2078,13 +2081,39 @@ export class QueryInterface {
         }
         return undefined;
     }
+    /**
+     * {@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.
+     */
+    readWithTimeout(sql, params, timeout, preparedName) {
+        return this.queryWithTimeout(sql, params, timeout, preparedName, true);
+    }
     /**
      * 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.
      */
-    async queryWithTimeout(sql, params, timeout, preparedName) {
-        const start = performance.now();
+    async queryWithTimeout(sql, params, timeout, preparedName, retryIfStale = false) {
+        let start = performance.now();
         const action = this.currentAction;
         // Build the query argument, use object form with `name` for prepared
         // statements, or the plain (text, values) form otherwise.
@@ -2094,13 +2123,33 @@ export class QueryInterface {
         // cast. Guarded at runtime by `preparedStatementsEnabled`, which only the
         // drivers that accept it turn on.
         const usePrepared = preparedName && this.preparedStatementsEnabled;
-        const exec = usePrepared
+        const send = () => usePrepared
             ? this.pool.query({
                 name: preparedName,
                 text: sql,
                 values: params,
             })
             : this.pool.query(sql, params);
+        let exec = send();
+        // Set when the caller's timeout has already answered, so a first attempt
+        // that fails AFTER that does not send a retry nobody is waiting for.
+        let abandoned = false;
+        if (retryIfStale && !this.txScoped) {
+            exec = exec.catch(async (err) => {
+                if (abandoned || !isStaleConnectionError(err))
+                    throw err;
+                // The failed attempt is reported as its own event, marked `retried`,
+                // so a listener counting errors sees it and one alerting on failed
+                // CALLS can skip it. The final event below times the retry alone.
+                const wrapped = wrapPgError(err);
+                this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined, true);
+                await settleEventLoop();
+                if (abandoned)
+                    throw err;
+                start = performance.now();
+                return send();
+            });
+        }
         if (!timeout) {
             try {
                 const result = await exec;
@@ -2115,7 +2164,10 @@ export class QueryInterface {
         }
         let timer;
         const timeoutPromise = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new TimeoutError(timeout)), timeout);
+            timer = setTimeout(() => {
+                abandoned = true;
+                reject(new TimeoutError(timeout));
+            }, timeout);
         });
         try {
             const result = await Promise.race([exec, timeoutPromise]);
@@ -2157,19 +2209,37 @@ export class QueryInterface {
     // Write compilation (extracted to writes.ts).
     // ---------------------------------------------------------------------------
     buildCreate(args) {
-        return writesMod.buildCreate(this.ctx, args);
+        return writesMod.buildCreate(this.ctx, args, this.resolveWriteProjection(args));
+    }
+    /**
+     * 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.
+     */
+    resolveWriteProjection(args) {
+        if (args.select === undefined && args.omit === undefined)
+            return undefined;
+        const columns = relationsMod.resolveProjection(this.ctx, this.table, this.tableMeta, args.select, args.omit, false);
+        if (!columns || columns.length === 0) {
+            // Only an `omit` naming every column gets here (an empty `select` is
+            // refused inside resolveProjection): a write must return SOMETHING, and
+            // an empty RETURNING list is a syntax error on every engine.
+            throw new ValidationError(`\`omit\` on a write to "${this.table}" leaves no column to return. Name the fields to keep with \`select\` instead.`);
+        }
+        return { columns };
     }
     buildCreateMany(args) {
         return writesMod.buildCreateMany(this.ctx, args);
     }
     buildUpdate(args) {
-        return writesMod.buildUpdate(this.ctx, args);
+        return writesMod.buildUpdate(this.ctx, args, this.resolveWriteProjection(args));
     }
     buildDelete(args) {
-        return writesMod.buildDelete(this.ctx, args);
+        return writesMod.buildDelete(this.ctx, args, this.resolveWriteProjection(args));
     }
     buildUpsert(args) {
-        return writesMod.buildUpsert(this.ctx, args);
+        return writesMod.buildUpsert(this.ctx, args, this.resolveWriteProjection(args));
     }
     buildUpdateMany(args) {
         return writesMod.buildUpdateMany(this.ctx, args);
@@ -2250,7 +2320,7 @@ export class QueryInterface {
                 }
             }
             const deferred = this.buildFindUnique(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
+            const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2274,7 +2344,7 @@ export class QueryInterface {
         const proj = includeKeysForBatching(this.tableMeta, args.select, args.omit, needed, defaultProjectionFields(this.tableMeta, resolveUnsafeFlag(args.includePii, 'includePii')));
         const baseArgs = { ...args, with: undefined, select: proj.select, omit: proj.omit };
         const deferred = this.buildFindUnique(baseArgs);
-        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
+        const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
         const entity = deferred.transform(result);
         // A miss still walks the `with` tree (compile-only child builds), so the
         // same args throw or pass identically whether or not the row exists,
@@ -2508,7 +2578,7 @@ export class QueryInterface {
                 }
             }
             const deferred = this.buildFindMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
+            const result = await this.readWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -3146,7 +3216,7 @@ export class QueryInterface {
                 ...args,
                 limit: batchSize + 1,
             });
-            const speculativeResult = await this.queryWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout, streamPreparedName);
+            const speculativeResult = await this.readWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout, streamPreparedName);
             if (speculativeResult.rows.length <= batchSize) {
                 // Small drain, hand over the whole result and return, no cursor needed.
                 if (speculativeResult.rows.length > 0)
@@ -3166,7 +3236,8 @@ export class QueryInterface {
         // connection, so `pool.query` already IS that connection. The stream rides
         // on it, is never released here, and the dialect is told to emit no
         // transaction control of its own (`ambientTransaction`).
-        const client = this.txScoped ? null : await this.acquireConnection();
+        const held = this.txScoped ? null : await this.acquireConnection();
+        const client = held?.client ?? null;
         const conn = client ?? {
             query: async (text, values) => (await this.pool.query(text, values)),
         };
@@ -3177,10 +3248,10 @@ export class QueryInterface {
         }
         catch (err) {
             // Wrap pg constraint errors so streaming surfaces typed errors like the rest of the API
-            throw wrapPgError(err);
+            throw explainConnectionLoss(wrapPgError(err), held?.checkout.lostWith);
         }
         finally {
-            client?.release();
+            held?.checkout.release();
         }
     }
     /**
@@ -3305,7 +3376,7 @@ export class QueryInterface {
                 }
             }
             const deferred = this.buildFindFirst(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
+            const result = await this.readWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -3329,7 +3400,7 @@ export class QueryInterface {
     async findFirstOrThrow(args) {
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
             const deferred = this.buildFindFirstOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
+            const result = await this.readWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -3358,7 +3429,7 @@ export class QueryInterface {
     async findUniqueOrThrow(args) {
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
             const deferred = this.buildFindUniqueOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
+            const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -3420,58 +3491,50 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     async nestedCreate(args) {
         const data = args.data;
+        // Validated up front, before any row is written, and then applied by the
+        // nested engine's final read-back, which already speaks select/omit.
+        this.resolveWriteProjection(args);
+        const shape = { select: args.select, omit: args.omit };
         if (this.txScoped) {
             const ctx = this.buildNestedCtx();
-            return executeNestedCreate(ctx, this.table, data);
+            return executeNestedCreate(ctx, this.table, data, 0, [], shape);
         }
         return this.runInImplicitTx(async (ctx) => {
-            const result = await executeNestedCreate(ctx, this.table, data);
+            const result = await executeNestedCreate(ctx, this.table, data, 0, [], shape);
             return result;
         });
     }
     async nestedUpdate(args) {
         const data = args.data;
         const where = args.where;
+        this.resolveWriteProjection(args);
+        const shape = { select: args.select, omit: args.omit };
         if (this.txScoped) {
             const ctx = this.buildNestedCtx();
-            return executeNestedUpdate(ctx, this.table, where, data);
+            return executeNestedUpdate(ctx, this.table, where, data, 0, [], shape);
         }
         return this.runInImplicitTx(async (ctx) => {
-            const result = await executeNestedUpdate(ctx, this.table, where, data);
+            const result = await executeNestedUpdate(ctx, this.table, where, data, 0, [], shape);
             return result;
         });
     }
     /**
-     * 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`.
      */
-    async acquireConnection() {
-        try {
-            return await this.pool.connect();
-        }
-        catch (err) {
-            throw wrapPgError(err);
-        }
+    acquireConnection() {
+        return acquireConnection(this.pool);
     }
     async runInImplicitTx(fn) {
-        const client = await this.acquireConnection();
-        let began = false;
+        // BEGIN runs inside openCheckout, which sends it once more on a fresh
+        // connection when the first one turns out to be dead and releases the
+        // connection itself when BEGIN fails for good. The catch below therefore
+        // only sees a transaction that began, and never emits a stray ROLLBACK on
+        // a connection that opened none.
+        const { client, checkout } = await openCheckout(this.pool, (c) => c.query(this.dialect.beginStatement()));
         try {
-            await client.query(this.dialect.beginStatement());
-            began = true;
             const { TransactionClient } = await import('../client.js');
             const tx = new TransactionClient(
             // biome-ignore lint/suspicious/noExplicitAny: MiddlewareFn and Middleware are structurally identical
@@ -3495,20 +3558,16 @@ export class QueryInterface {
             return result;
         }
         catch (err) {
-            // Only roll back a transaction we actually opened: a failed BEGIN must
-            // not emit a stray ROLLBACK on a connection that never began one.
-            if (began) {
-                try {
-                    await client.query(this.dialect.rollbackStatement());
-                }
-                catch {
-                    // Best-effort rollback: connection may have died.
-                }
+            try {
+                await client.query(this.dialect.rollbackStatement());
+            }
+            catch {
+                // Best-effort rollback: connection may have died.
             }
-            throw err;
+            throw explainConnectionLoss(err, checkout.lostWith);
         }
         finally {
-            client.release();
+            checkout.release();
         }
     }
     buildNestedCtx() {
@@ -3571,7 +3630,7 @@ export class QueryInterface {
     async count(args) {
         return this.executeWithMiddleware('count', (args ?? {}), async () => {
             const deferred = this.buildCount(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
+            const result = await this.readWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -3615,7 +3674,7 @@ export class QueryInterface {
     async groupBy(args) {
         return this.executeWithMiddleware('groupBy', args, async () => {
             const deferred = this.buildGroupBy(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
+            const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -3634,7 +3693,7 @@ export class QueryInterface {
     async aggregate(args) {
         return this.executeWithMiddleware('aggregate', args, async () => {
             const deferred = this.buildAggregate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
+            const result = await this.readWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }

package/dist/query/deferred.d.ts

@@ -108,6 +108,15 @@ export interface QueryEvent {
      * batch statements are timed individually. Absent for everything else.
      */
     batch?: 'pipeline' | 'transaction';
+    /**
+     * Set on a READ that failed because its connection had already been closed
+     * by the server, and that Turbine therefore sent once more on a fresh one.
+     * This event carries that first attempt's `error`; the retry reports its own
+     * event, so a failed read that was then answered shows as two events and a
+     * listener alerting on failed calls can skip the ones marked here. Writes
+     * and statements inside a transaction are never retried.
+     */
+    retried?: true;
 }
 export type QueryEventListener = (event: QueryEvent) => void;
 /** Options passed from TurbineClient to QueryInterface */

package/dist/query/option-surface.js

@@ -114,6 +114,9 @@ export const FIND_MANY_STREAM_OPTIONS = {
 };
 export const CREATE_OPTIONS = {
     data: 'prisma',
+    // Field names, so hand-translated; prisma-compat narrows write results itself.
+    select: 'prisma',
+    omit: 'prisma',
     timeout: 'native',
 };
 export const CREATE_MANY_OPTIONS = {
@@ -124,6 +127,9 @@ export const CREATE_MANY_OPTIONS = {
 export const UPDATE_OPTIONS = {
     where: 'prisma',
     data: 'prisma',
+    // Field names, so hand-translated; prisma-compat narrows write results itself.
+    select: 'prisma',
+    omit: 'prisma',
     // `{ field, expected }`, and `field` is a FIELD NAME, so it has to be renamed
     // into turbine's naming space rather than copied. See THE ONE RULE above.
     optimisticLock: 'prisma',
@@ -140,6 +146,9 @@ export const UPDATE_MANY_OPTIONS = {
 };
 export const DELETE_OPTIONS = {
     where: 'prisma',
+    // Field names, so hand-translated; prisma-compat narrows write results itself.
+    select: 'prisma',
+    omit: 'prisma',
     timeout: 'native',
     allowFullTableScan: 'native',
     skipGlobalFilters: 'native',
@@ -152,6 +161,9 @@ export const DELETE_MANY_OPTIONS = {
 };
 export const UPSERT_OPTIONS = {
     where: 'prisma',
+    // Field names, so hand-translated; prisma-compat narrows write results itself.
+    select: 'prisma',
+    omit: 'prisma',
     create: 'prisma',
     update: 'prisma',
     timeout: 'native',

package/dist/query/types.d.ts

@@ -870,12 +870,28 @@ export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWit
      */
     batchSize?: number;
 }
-export interface CreateArgs<T, R extends object = {}> {
+export interface CreateArgs<T, R extends object = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     /**
      * Row data. On typed clients, relation names additionally accept nested
      * write ops ({@link NestedCreateOp}): `create` / `connect` / `connectOrCreate`.
      */
     data: CreateDataInput<T, R>;
+    /**
+     * Return only these fields of the written row, instead of the whole row.
+     * Keys are checked against `T` (see {@link FieldFlags}) and follow the read
+     * rules: an unknown name throws E003, a `select` must name at least one field,
+     * and it cannot be combined with `omit`. Narrows the `RETURNING` list itself,
+     * so the unselected columns never cross the wire, which is the point on a
+     * table with a large JSON or text column. Naming a PII-tagged column here is
+     * the explicit opt-in that returns it, exactly as on a read.
+     */
+    select?: S & FieldFlags<T, S>;
+    /**
+     * Return the written row without these fields. Same rules as `select`;
+     * PII-tagged columns stay excluded, as they are from every default write
+     * return.
+     */
+    omit?: O & FieldFlags<T, O>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
@@ -916,7 +932,7 @@ export type UpdateOperatorInput<V> = {
 export type UpdateInput<T> = {
     [K in keyof T]?: T[K] | UpdateOperatorInput<T[K]>;
 };
-export interface UpdateArgs<T, R extends object = {}> {
+export interface UpdateArgs<T, R extends object = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     /** Row selector. Keys are checked against `T` and `R` (see {@link WhereClause}). */
     where: WhereClause<T, R>;
     /**
@@ -925,6 +941,22 @@ export interface UpdateArgs<T, R extends object = {}> {
      * / `disconnect` / `set` / `delete` / `update` / `upsert`.
      */
     data: UpdateDataInput<T, R>;
+    /**
+     * Return only these fields of the updated row, instead of the whole row.
+     * Keys are checked against `T` (see {@link FieldFlags}) and follow the read
+     * rules: an unknown name throws E003, a `select` must name at least one field,
+     * and it cannot be combined with `omit`. Narrows the `RETURNING` list itself,
+     * so the unselected columns never cross the wire, which is the point on a
+     * table with a large JSON or text column. Naming a PII-tagged column here is
+     * the explicit opt-in that returns it, exactly as on a read.
+     */
+    select?: S & FieldFlags<T, S>;
+    /**
+     * Return the updated row without these fields. Same rules as `select`;
+     * PII-tagged columns stay excluded, as they are from every default write
+     * return.
+     */
+    omit?: O & FieldFlags<T, O>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /**
@@ -974,8 +1006,24 @@ export interface UpdateManyArgs<T, R extends object = {}> {
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
-export interface DeleteArgs<T, R extends object = {}> {
+export interface DeleteArgs<T, R extends object = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     where: WhereClause<T, R>;
+    /**
+     * Return only these fields of the deleted row, instead of the whole row.
+     * Keys are checked against `T` (see {@link FieldFlags}) and follow the read
+     * rules: an unknown name throws E003, a `select` must name at least one field,
+     * and it cannot be combined with `omit`. Narrows the `RETURNING` list itself,
+     * so the unselected columns never cross the wire, which is the point on a
+     * table with a large JSON or text column. Naming a PII-tagged column here is
+     * the explicit opt-in that returns it, exactly as on a read.
+     */
+    select?: S & FieldFlags<T, S>;
+    /**
+     * Return the deleted row without these fields. Same rules as `select`;
+     * PII-tagged columns stay excluded, as they are from every default write
+     * return.
+     */
+    omit?: O & FieldFlags<T, O>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
@@ -992,8 +1040,24 @@ export interface DeleteManyArgs<T, R extends object = {}> {
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
 }
-export interface UpsertArgs<T, R extends object = {}> {
+export interface UpsertArgs<T, R extends object = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     where: WhereClause<T, R>;
+    /**
+     * Return only these fields of the inserted or updated row, instead of the whole row.
+     * Keys are checked against `T` (see {@link FieldFlags}) and follow the read
+     * rules: an unknown name throws E003, a `select` must name at least one field,
+     * and it cannot be combined with `omit`. Narrows the `RETURNING` list itself,
+     * so the unselected columns never cross the wire, which is the point on a
+     * table with a large JSON or text column. Naming a PII-tagged column here is
+     * the explicit opt-in that returns it, exactly as on a read.
+     */
+    select?: S & FieldFlags<T, S>;
+    /**
+     * Return the inserted or updated row without these fields. Same rules as `select`;
+     * PII-tagged columns stay excluded, as they are from every default write
+     * return.
+     */
+    omit?: O & FieldFlags<T, O>;
     /** The row to insert when `where` matches nothing. Plain values only: there is no stored value to operate on yet. */
     create: Partial<T>;
     /**