turbine-orm 0.77.1 → 0.78.0

package/dist/generate.js

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { ValidationError } from './errors.js';
+import { assertDistinctColumnFields } from './introspect.js';
 import { pgTypeToTs, singularize, snakeToPascal, timeOfDayKind, withDbFieldNames, } from './schema.js';
 /** Get the TypeScript type name for a table (singularized PascalCase) */
 function entityName(tableName) {
@@ -388,6 +389,11 @@ export function assertEmittableSchema(schema) {
     for (const table of Object.values(schema.tables)) {
         requireEmittable(entityName(table.name), `table "${table.name}"`, 'the generated entity type name');
         requireEmittable(snakeToCamelStr(table.name), `table "${table.name}"`, 'the generated client accessor');
+        // Two columns on one field would emit a duplicate interface member (TS2300
+        // in the consumer's build) and a `columnMap` missing a column. The rule is
+        // introspect.ts's; re-asserting it here covers a hand-built or
+        // engine-introspected schema that never went through that path.
+        assertDistinctColumnFields(table.name, table.columns);
         // Only the relations that reach the TYPE layer: a relation shadowing a
         // column field is already dropped from types.ts, so refusing on its name
         // would refuse a schema that generates fine.
@@ -458,18 +464,24 @@ export function generateTypes(schema, options) {
         lines.push('}');
         lines.push('');
         // --- Create input type ---
-        // Required: non-nullable columns without defaults (except PK)
-        // Optional: nullable columns (default to NULL) or columns with explicit defaults
+        // Optional: server-generated columns (serial / identity), columns with a
+        // default, and nullable columns (default to NULL). Everything else is
+        // required, PRIMARY KEY MEMBERSHIP INCLUDED. A text natural key, a
+        // client-supplied uuid with no default, or a composite key of plain
+        // integers must be supplied, and the database rejects the row otherwise
+        // (E010). Marking every PK column optional let `create({ data: {} })` on
+        // a junction table typecheck and fail at runtime, which is the opposite of
+        // what a generated type is for.
         lines.push(`/** Input type for creating a row in \`${docSafe(table.name)}\` */`);
         lines.push(`export type ${typeName}Create = {`);
         for (const col of table.columns) {
             // STORED generated columns are computed by the database, never writable.
             if (col.isGeneratedStored)
                 continue;
-            const isPk = table.primaryKey.includes(col.name);
-            const isOptional = col.hasDefault || col.nullable || isPk;
+            const isGenerated = col.isGenerated === true;
+            const isOptional = isGenerated || col.hasDefault || col.nullable;
             if (isOptional) {
-                const reason = isPk ? 'auto-generated' : col.hasDefault ? 'has default' : 'nullable';
+                const reason = isGenerated ? 'auto-generated' : col.hasDefault ? 'has default' : 'nullable';
                 lines.push(`  /** Optional: ${reason} */`);
                 lines.push(`  ${quoteIfNeeded(col.field)}?: ${writeColumnTsType(col, schema.enums)};`);
             }
@@ -756,18 +768,18 @@ export function generateZod(schema, options) {
         }
         lines.push('});');
         lines.push('');
-        // Create schema, STORED generated columns can never be written; PK,
-        // defaulted, and nullable columns are optional.
+        // Create schema, STORED generated columns can never be written;
+        // server-generated, defaulted, and nullable columns are optional, the same
+        // rule as the `*Create` type (a PK with none of those is required).
         lines.push(`/** Zod schema for creating a \`${docSafe(table.name)}\` row */`);
         lines.push(`export const ${typeName}CreateSchema = z.object({`);
         for (const col of table.columns) {
             if (col.isGeneratedStored)
                 continue;
-            const isPk = table.primaryKey.includes(col.name);
             let expr = zodBaseType(col, schema.enums, true);
             if (col.nullable)
                 expr += '.nullable()';
-            if (col.hasDefault || col.nullable || isPk)
+            if (col.isGenerated === true || col.hasDefault || col.nullable)
                 expr += '.optional()';
             lines.push(`  ${quoteIfNeeded(col.field)}: ${expr},`);
         }
@@ -796,6 +808,11 @@ export function generateZod(schema, options) {
 // metadata.ts generator
 // ---------------------------------------------------------------------------
 export function generateMetadata(schema, options) {
+    // metadata.ts is where a field collision does its runtime damage: the
+    // emitted `columnMap` keeps whichever column was written last, so refuse it
+    // here as well as in the type emitters (see assertEmittableSchema).
+    for (const table of Object.values(schema.tables))
+        assertDistinctColumnFields(table.name, table.columns);
     const lines = [
         ...generatedFileHeader(options),
         "import type { SchemaMetadata } from 'turbine-orm';",
@@ -1011,15 +1028,21 @@ export function generateIndex(schema, options) {
     lines.push('  }');
     lines.push('}');
     lines.push('');
-    // Augment TurbineClient via interface merging with a typed $transaction
-    // overload. The callback parameter is narrowed to `TypedTransactionClient`
-    // so users get autocomplete on `tx.users`, `tx.posts`, etc.
+    // Augment TurbineClient via interface merging with typed $transaction and
+    // $withSession overloads. The callback parameter is narrowed to
+    // `TypedTransactionClient` so users get autocomplete on `tx.users`,
+    // `tx.posts`, etc. $withSession is the RLS shorthand for
+    // `$transaction(fn, { sessionContext })`; it used to be left out, so its
+    // callback stayed the untyped base `TransactionClient` and the documented
+    // `tx.<table>.findMany()` did not compile on a generated client.
     //
-    // IMPORTANT: the merged member must be compatible with the base class's
-    // $transaction ON ITS OWN (TS2415), since v0.26 the base method also has a
+    // IMPORTANT: each merged member must be compatible with the base class's
+    // member ON ITS OWN (TS2415), since v0.26 the base $transaction also has a
     // batch-array overload (`$transaction([...queries])`), so the merged
     // interface must redeclare BOTH signatures. Emitting only the callback form
-    // makes every generated client fail `tsc` with "incorrectly extends".
+    // makes every generated client fail `tsc` with "incorrectly extends". The
+    // $withSession overload mirrors the base parameter list exactly for the same
+    // reason; src/test/generate-typecheck.test.ts compiles the result.
     lines.push('export interface TurbineClient {');
     lines.push('  /**');
     lines.push('   * Run a callback inside a transaction. The callback receives a typed');
@@ -1036,6 +1059,15 @@ export function generateIndex(schema, options) {
     lines.push('  $transaction<T extends readonly DeferredQuery<unknown>[]>(');
     lines.push('    queries: readonly [...T],');
     lines.push('  ): Promise<PipelineResults<T>>;');
+    lines.push('  /**');
+    lines.push('   * Run a callback inside a transaction with the given session GUCs applied');
+    lines.push('   * via `set_config(..., true)` (the RLS / multi-tenant shorthand). The');
+    lines.push('   * callback receives a typed `TypedTransactionClient`, same as `$transaction`.');
+    lines.push('   */');
+    lines.push('  $withSession<R>(');
+    lines.push('    context: Record<string, string | number | boolean>,');
+    lines.push('    fn: (tx: TypedTransactionClient) => Promise<R>,');
+    lines.push('  ): Promise<R>;');
     lines.push('}');
     lines.push('');
     // Factory function with JSDoc

package/dist/index.d.ts

@@ -44,7 +44,7 @@ export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type Neste
 export { HttpJsonSink, type HttpJsonSinkOptions, type MetricsFlushBatch, type MetricsFlushRow, type ObserveConfig, type ObserveHandle, type ObserveSink, PgMetricsSink, type PgMetricsSinkOptions, } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
 export { fingerprintPrismaSchema } from './prisma-schema-fingerprint.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonEncoding, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderDirection, type PrivilegeOption, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TemporalInfinityReading, type TextSearchFilter, type TypedWithClause, UNSAFE, type Unsafe, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonEncoding, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderBySpec, type OrderDirection, type PrivilegeOption, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationOrderBy, type RelationOrderByChain, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TemporalInfinityReading, type TextSearchFilter, type TypedWithClause, UNSAFE, type Unsafe, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, PrismaCompatMap, PrismaModelMap, PrismaRelationMap, PrismaSchemaSource, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, withDbFieldNames, } from './schema.js';

package/dist/introspect.d.ts

@@ -91,6 +91,18 @@ export interface IntrospectOptions {
      * {@link detectUniqueForeignKeySets}.
      */
     legacyToManyUniques?: boolean;
+    /**
+     * Use the raw database column name as each column's TypeScript field
+     * (`user_id` stays `user_id`) instead of the camelCase default (`userId`).
+     * The same identity mapping `withDbFieldNames` applies at generate time, so
+     * a schema introspected with this flag is byte-identical after that
+     * transform; declaring it here as well is what makes it the escape from the
+     * field-collision refusal (see {@link assertDistinctColumnFields}): a table
+     * carrying both `"createdAt"` and `created_at` has two distinct raw names and
+     * one shared camelCase name, and only the flag can tell introspection which
+     * of those two facts to build the field from.
+     */
+    keepColumnNames?: boolean;
     /**
      * Called with any {@link DEFAULT_EXCLUDED_TABLES} that were present in the
      * database but dropped from this run (F12), so the CLI can print a
@@ -145,6 +157,27 @@ export declare function introspect(options: IntrospectOptions): Promise<SchemaMe
  * means the call sites it was supposed to fix break at runtime instead.
  */
 export declare function applyRelationRenames(schema: SchemaMetadata, renames: Record<string, Record<string, string>>): SchemaMetadata;
+/**
+ * THE field-collision rule: two columns of one table may never resolve to the
+ * same TypeScript field.
+ *
+ * Fields are derived with `snakeToCamel`, so a table carrying both a quoted
+ * `"createdAt"` and a `created_at` column (a Prisma-era column beside a
+ * hand-written one is the common way to get there) yields two `createdAt`
+ * fields. Nothing used to refuse that, and every consumer keyed by field then
+ * lost a column silently: `columnMap` kept whichever column was written last,
+ * reads folded both columns into one property, a write to the field reached
+ * only one of them, and `types.ts` carried a duplicate member that failed the
+ * consumer's `tsc` (TS2300) while `turbine generate` exited 0.
+ *
+ * A thrown error names the table, every colliding column and the fix. There is
+ * no per-column rename option, so the fix is `keepColumnNames` (the field is
+ * then the raw column name, and two distinct columns cannot collide) or a
+ * rename in the database. Applied once per table right after the catalog's
+ * columns are grouped, and again by the generate.ts emitters so a schema that
+ * never went through introspection is refused at the same boundary.
+ */
+export declare function assertDistinctColumnFields(tableName: string, columns: readonly ColumnMetadata[]): void;
 /**
  * PostgreSQL catalog introspector: reads information_schema + pg_catalog and
  * produces {@link SchemaMetadata}. This is the implementation wrapped by

package/dist/introspect.js

@@ -461,6 +461,50 @@ export function applyRelationRenames(schema, renames) {
     }
     return { ...schema, tables };
 }
+/**
+ * THE field-collision rule: two columns of one table may never resolve to the
+ * same TypeScript field.
+ *
+ * Fields are derived with `snakeToCamel`, so a table carrying both a quoted
+ * `"createdAt"` and a `created_at` column (a Prisma-era column beside a
+ * hand-written one is the common way to get there) yields two `createdAt`
+ * fields. Nothing used to refuse that, and every consumer keyed by field then
+ * lost a column silently: `columnMap` kept whichever column was written last,
+ * reads folded both columns into one property, a write to the field reached
+ * only one of them, and `types.ts` carried a duplicate member that failed the
+ * consumer's `tsc` (TS2300) while `turbine generate` exited 0.
+ *
+ * A thrown error names the table, every colliding column and the fix. There is
+ * no per-column rename option, so the fix is `keepColumnNames` (the field is
+ * then the raw column name, and two distinct columns cannot collide) or a
+ * rename in the database. Applied once per table right after the catalog's
+ * columns are grouped, and again by the generate.ts emitters so a schema that
+ * never went through introspection is refused at the same boundary.
+ */
+export function assertDistinctColumnFields(tableName, columns) {
+    const columnsByField = new Map();
+    for (const col of columns) {
+        const names = columnsByField.get(col.field);
+        if (names)
+            names.push(col.name);
+        else
+            columnsByField.set(col.field, [col.name]);
+    }
+    const collisions = [];
+    for (const [field, names] of columnsByField) {
+        if (names.length < 2)
+            continue;
+        const quoted = names.map((n) => `"${n}"`);
+        const list = `${quoted.slice(0, -1).join(', ')} and ${quoted[quoted.length - 1]}`;
+        collisions.push(`columns ${list} ${names.length === 2 ? 'both' : 'all'} resolve to the field "${field}"`);
+    }
+    if (collisions.length === 0)
+        return;
+    throw new ValidationError(`Field collision on table "${tableName}": ${collisions.join('; ')}. A client addresses one column per field, ` +
+        'so reads would fold the colliding columns into one property and a write to that field would reach only ' +
+        'one of them. Rename one of the columns, or set `keepColumnNames: true` in turbine.config.ts ' +
+        '(`turbine generate --keep-column-names`) so every field is its raw column name.');
+}
 /**
  * PostgreSQL catalog introspector: reads information_schema + pg_catalog and
  * produces {@link SchemaMetadata}. This is the implementation wrapped by
@@ -532,7 +576,9 @@ export async function introspectPostgresCatalog(options) {
             const arrayType = dialect.arrayType?.(baseType) ?? 'text[]';
             const col = {
                 name: row.column_name,
-                field: snakeToCamel(row.column_name),
+                // Under keepColumnNames the field IS the column name, which is why two
+                // distinct columns can never collide there (see assertDistinctColumnFields).
+                field: options.keepColumnNames ? row.column_name : snakeToCamel(row.column_name),
                 dialectType,
                 pgType: dialectType,
                 tsType: dialect.typeToTypeScript?.(isArray ? dialectType : baseType, isNullable) ??
@@ -566,6 +612,12 @@ export async function introspectPostgresCatalog(options) {
                 columnsByTable.set(tableName, []);
             columnsByTable.get(tableName).push(col);
         }
+        // Every consumer below keys the table by FIELD (columnMap, the relation
+        // derivation's shadow check, the generated interface), so the field set
+        // must be sound before any of them runs. THE one place the rule is applied
+        // to a live catalog; generate.ts re-asserts it for schemas built elsewhere.
+        for (const [tableName, cols] of columnsByTable)
+            assertDistinctColumnFields(tableName, cols);
         // ----- Group primary keys by table -----
         const pkByTable = new Map();
         for (const row of pkResult.rows) {

package/dist/mssql.js

@@ -1047,6 +1047,26 @@ function buildForJsonManyToMany(dialect, ctx, h) {
         `FOR JSON PATH, INCLUDE_NULL_VALUES), '[]')`);
 }
 const num = (v) => (typeof v === 'string' ? Number(v) : (v ?? 0));
+/**
+ * A `bit` column, as the driver actually delivers it.
+ *
+ * tedious parses TDS `BITTYPE` with `!!value`, so `sys.indexes.is_unique`
+ * arrives as a JavaScript BOOLEAN, never as 1. Reading it through {@link num}
+ * and comparing to 1 therefore answered `false` for EVERY unique index on SQL
+ * Server, which emptied `uniqueColumns` on every introspected table and set
+ * `IndexMetadata.unique` to false on every unique index. The visible cost was a
+ * `findUnique` (and, once it carried the same rule, an `upsert`) on a genuinely
+ * unique non-PK column being refused as not identifying one row, on the one
+ * engine where the metadata could not say otherwise.
+ *
+ * The unit test could not see it: its mock built index rows with `1` and `0`
+ * because the helper's parameter was typed `number`, so the fixture chose the
+ * shape the code already handled. Only the live SQL Server leg produces the
+ * boolean. Written to accept all three spellings rather than the one this
+ * driver happens to send, because another `mssql` transport is free to send a
+ * number or the string `'1'` and this is metadata, not a hot path.
+ */
+const bitIsTrue = (v) => v === true || v === 1 || v === '1' || v === 'true';
 /**
  * Derive relations from the FK list via the SHARED introspection pipeline
  * (`deriveEngineRelations` → `buildRelationsFromForeignKeys` +
@@ -1182,7 +1202,7 @@ export async function introspectMssqlWith(exec, schema = 'dbo', options = {}) {
         const key = `${t}.${name}`;
         let g = indexGroups.get(key);
         if (!g) {
-            g = { table: t, name, unique: num(r.IS_UNIQUE) === 1, columns: [] };
+            g = { table: t, name, unique: bitIsTrue(r.IS_UNIQUE), columns: [] };
             indexGroups.set(key, g);
         }
         g.columns.push(String(r.COLUMN_NAME));

package/dist/nested-write.js

@@ -12,6 +12,7 @@
  * `NestedWriteContext`.
  */
 import { CircularRelationError, describeTargetForMessage, NotFoundError, RelationError, UnsupportedFeatureError, ValidationError, } from './errors.js';
+import { markInternalRowSelector } from './query/compound-unique.js';
 import { markInternalCombinator, resolveColumnName } from './query/utils.js';
 import { normalizeKeyColumns } from './schema.js';
 const MAX_DEPTH = 10;
@@ -222,6 +223,65 @@ function validateOps(relationName, ops, isUpdate) {
         }
     }
 }
+/**
+ * The `with` clause that reads back the tree a nested write just wrote.
+ *
+ * Built from the DATA, recursively: a relation whose payload itself contains
+ * relation writes is requested as `{ rel: { with: { ... } } }` rather than
+ * `{ rel: true }`. It used to be the top-level keys alone, so a depth-3 create
+ * wrote all three levels and returned an object whose grandchildren were
+ * missing entirely, which a caller reads as "there are none".
+ *
+ * Only relations that were actually WRITTEN are requested, so a create with no
+ * nested data still reads back exactly what it did before. The walk is capped
+ * at {@link MAX_DEPTH}, the cap the write walk itself uses, and the builder's
+ * own relation-depth guard is the backstop below that.
+ */
+function readBackWith(schema, tableName, relations, depth = 0) {
+    const tableMeta = schema.tables[tableName];
+    if (!tableMeta || depth >= MAX_DEPTH)
+        return undefined;
+    const clause = {};
+    for (const [relName, ops] of Object.entries(relations)) {
+        const rel = tableMeta.relations[relName];
+        if (!rel)
+            continue;
+        // Every payload this relation was written with: `create` / `update` /
+        // `upsert` take objects (or arrays of them) whose own keys may name
+        // relations of the TARGET table. `connect` / `disconnect` / `set` name
+        // existing rows and write no nested data, so they contribute nothing here.
+        const nested = {};
+        for (const key of ['create', 'update', 'upsert']) {
+            const payload = ops[key];
+            if (payload === undefined)
+                continue;
+            for (const item of toArray(payload)) {
+                // `{ where, data }` (nested update) and `{ where, create, update }`
+                // (nested upsert) carry their written fields one level in.
+                const bodies = isPlainRecord(item) && ('data' in item || 'create' in item || 'update' in item)
+                    ? [item.data, item.create, item.update]
+                    : [item];
+                for (const body of bodies) {
+                    if (!isPlainRecord(body))
+                        continue;
+                    const child = schema.tables[rel.to];
+                    if (!child)
+                        continue;
+                    for (const [k, v] of Object.entries(extractRelationFields(body, child).relations)) {
+                        nested[k] = { ...(nested[k] ?? {}), ...v };
+                    }
+                }
+            }
+        }
+        const deeper = Object.keys(nested).length > 0 ? readBackWith(schema, rel.to, nested, depth + 1) : undefined;
+        clause[relName] = deeper ? { with: deeper } : true;
+    }
+    return Object.keys(clause).length > 0 ? clause : undefined;
+}
+/** A plain object (not an array, Date or null), the shape nested payloads take. */
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date);
+}
 /**
  * Build a PK-based where clause from a parent row and its table metadata.
  */
@@ -308,7 +368,20 @@ function belongsToCorrelationWhere(ctx, rel, parentRow, parentTable) {
  * field itself, the two are combined with `AND` instead, so neither predicate
  * can silently overwrite the other.
  */
-function scopeWhereToParent(target, correlation) {
+function scopeWhereToParent(
+// `true` is the to-one "the single related row" spelling, the only non-object
+// value assertTargetSelectsSomething lets through.
+target, correlation) {
+    // `disconnect: true` / `delete: true` on a to-one relation (the only place
+    // `true` gets past assertTargetSelectsSomething) leaves the caller with no
+    // selector at all: the predicate below is the correlation and nothing else,
+    // written entirely by the engine. Branded so the single-row write rule reads
+    // the relation's declared cardinality as the uniqueness source, since a
+    // `hasOne` FK is frequently not ALSO declared unique in metadata and the
+    // rule would otherwise refuse the write with "Name a unique key" against a
+    // call that never named one. See markInternalRowSelector.
+    if (target === true)
+        return markInternalRowSelector({ ...correlation });
     for (const key of Object.keys(correlation)) {
         // Branded as Turbine's own: this `AND` has a FIXED arity of two, chosen
         // here rather than reachable from a request body, so it must not cost the
@@ -822,15 +895,13 @@ export async function executeNestedCreate(ctx, tableName, data, depth = 0, path
             await processManyToMany(ctx, rel, relName, ops, parentRow);
         }
     }
-    // Build the `with` clause for the final read to return the full tree
-    const withClause = {};
-    for (const relName of Object.keys(relations)) {
-        withClause[relName] = true;
-    }
+    // The `with` clause for the final read: the whole tree that was written, at
+    // every depth (see readBackWith), not only its top level.
+    const withClause = readBackWith(ctx.schema, tableName, relations);
     // Final read using existing json_agg machinery
     const fullRow = await ctx.tx.table(tableName).findUnique({
         where: pkWhere(tableMeta, parentRow),
-        with: Object.keys(withClause).length > 0 ? withClause : undefined,
+        with: withClause,
     });
     return (fullRow ?? parentRow);
 }
@@ -933,14 +1004,10 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
             await processManyToMany(ctx, rel, relName, ops, parentRow);
         }
     }
-    // Final read with all touched relations
-    const withClause = {};
-    for (const relName of Object.keys(relations)) {
-        withClause[relName] = true;
-    }
+    // Final read with all touched relations, to the depth they were written.
     const fullRow = await ctx.tx.table(tableName).findUnique({
         where: pkWhere(tableMeta, parentRow),
-        with: Object.keys(withClause).length > 0 ? withClause : undefined,
+        with: readBackWith(ctx.schema, tableName, relations),
     });
     return (fullRow ?? parentRow);
 }
@@ -1330,7 +1397,11 @@ async function processBelongsToUpdate(ctx, rel, updateArg, parentRow, parentTabl
     // shared correlation helper (like every sibling operation) so a NULL parent
     // FK reports not-found instead of compiling to `refField IS NULL` and
     // updating EVERY row of the related table with a null reference key.
-    const where = belongsToCorrelationWhere(ctx, rel, parentRow, parentTable);
+    // No caller `where` exists on this shape (`update: { data }`), so the
+    // predicate is entirely the engine's: branded for the single-row write rule
+    // exactly as the to-one disconnect/delete correlation is.
+    const correlationWhere = belongsToCorrelationWhere(ctx, rel, parentRow, parentTable);
+    const where = correlationWhere && markInternalRowSelector(correlationWhere);
     if (!where) {
         // Parent FK is NULL: it points at nothing, so nothing is in scope to update.
         const nullFk = Object.fromEntries(normalizeKeyColumns(rel.foreignKey).map((c) => [c, null]));

package/dist/pipeline-submittable.d.ts

@@ -58,6 +58,8 @@ export interface PgPoolClient {
     _types?: unknown;
     release(err?: Error | boolean): void;
 }
+/** Did {@link runPipelined} leave this client unusable? See {@link PIPELINE_DISCARD}. */
+export declare function pipelineClientNeedsDiscard(client: unknown): boolean;
 export interface PipelineRunOptions {
     /**
      * Whether to wrap the pipeline in BEGIN/COMMIT (default: true).

package/dist/pipeline-submittable.js

@@ -19,6 +19,22 @@
 import Result from 'pg/lib/result';
 import { prepareValue } from 'pg/lib/utils';
 import { PipelineError, TimeoutError, wrapPgError } from './errors.js';
+/**
+ * Marks a client this module could not hand back in a reusable state, so the
+ * caller releases it WITH an error and the pool drops it instead of lending it
+ * out again.
+ *
+ * A symbol, and `Symbol.for` so an ESM and a CJS copy of this module agree on
+ * it (the same reason the internal-combinator brand uses one). Set only when
+ * the backend still reports an open or aborted transaction after this module
+ * has done what it can, which after {@link runPipelined}'s rollback means the
+ * rollback itself did not take.
+ */
+const PIPELINE_DISCARD = Symbol.for('turbine.pipeline.discardClient');
+/** Did {@link runPipelined} leave this client unusable? See {@link PIPELINE_DISCARD}. */
+export function pipelineClientNeedsDiscard(client) {
+    return (typeof client === 'object' && client !== null && client[PIPELINE_DISCARD] === true);
+}
 // ---------------------------------------------------------------------------
 // Event names we intercept
 // ---------------------------------------------------------------------------
@@ -120,6 +136,10 @@ export async function runPipelined(client, queries, options = {}) {
         let timeoutHandle;
         // Whether cleanup has already been performed
         let cleaned = false;
+        /** Transaction status reported by the most recent ReadyForQuery. */
+        let txStatus;
+        /** Whether the recovery ROLLBACK has already been sent (it is sent at most once). */
+        let rollbackSent = false;
         /**
          * Map commandComplete index to the corresponding results[] index.
          * In transactional mode: index 0 = BEGIN, 1..N = queries, N+1 = COMMIT
@@ -158,6 +178,62 @@ export async function runPipelined(client, queries, options = {}) {
         // -----------------------------------------------------------------------
         // Finalize: called on final readyForQuery
         // -----------------------------------------------------------------------
+        /**
+         * Return the connection to the pool in a state the next borrower can use.
+         *
+         * The hazard this exists for: a transactional batch is `BEGIN` + queries +
+         * `COMMIT` + ONE `Sync`, so a query error makes the backend skip everything
+         * up to that Sync, the `COMMIT` included, and the connection goes back to
+         * the pool `idle in transaction (aborted)`. The next borrower's first
+         * statement then failed with `25P02`, a `$transaction` that landed on it
+         * lost its write, and a non-transactional pipeline failed every slot and
+         * released it still aborted, so the poisoning survived indefinitely.
+         *
+         * The recovery is one `ROLLBACK` on the same connection, sent AFTER the
+         * ReadyForQuery that says the backend will accept a new statement, and
+         * waited for: its own ReadyForQuery brings us back here with `I`. That
+         * keeps the connection, which matters at small pool sizes where discarding
+         * is a reconnect on the caller's next query.
+         *
+         * Returns true when the caller should finalize now, false when a rollback
+         * is in flight and the next ReadyForQuery will finish the job.
+         */
+        function settleTransactionState() {
+            // `I` (idle) is the ordinary case and needs nothing, and neither does a
+            // batch that had no error: transactional mode's COMMIT closed the
+            // transaction, non-transactional mode never opened one. That keeps the
+            // happy path at exactly one round trip, which a `ROLLBACK`-on-unknown
+            // would have cost an extra Sync (caught by the cork/uncork test). A real
+            // backend always sends the status byte; an emitter without one is only
+            // ever a test double.
+            if (txStatus === 'I')
+                return true;
+            if (txStatus === undefined && !(transactional && pipelineError))
+                return true;
+            if (!transactional || rollbackSent) {
+                // Either nothing to roll back (non-transactional mode opens no
+                // transaction of its own), or the rollback already ran and did not
+                // clear the status. Hand the client back marked for disposal.
+                if (txStatus === 'E' || txStatus === 'T') {
+                    Object.defineProperty(client, PIPELINE_DISCARD, { value: true, enumerable: false, configurable: true });
+                }
+                return true;
+            }
+            rollbackSent = true;
+            try {
+                connection.parse({ text: 'ROLLBACK', name: '' });
+                connection.bind({ portal: '', statement: '', values: [], valueMapper: prepareValue });
+                connection.execute({ portal: '', rows: 0 });
+                connection.sync();
+                return false;
+            }
+            catch {
+                // The socket would not take the rollback, so this connection cannot be
+                // repaired from here. Mark it and let the caller drop it.
+                Object.defineProperty(client, PIPELINE_DISCARD, { value: true, enumerable: false, configurable: true });
+                return true;
+            }
+        }
         function finalize() {
             cleanup();
             if (transactional && pipelineError) {
@@ -284,11 +360,19 @@ export async function runPipelined(client, queries, options = {}) {
         function onPortalSuspended() {
             // We don't use row-limited portals
         }
-        function onReadyForQuery() {
-            rfqCount++;
-            if (rfqCount >= expectedRfq) {
+        function onReadyForQuery(msg) {
+            txStatus = msg?.status;
+            // The recovery ROLLBACK's own ReadyForQuery is not one of the batch's, so
+            // it must not advance the counter that decides when the batch is done.
+            if (rollbackSent) {
                 finalize();
+                return;
             }
+            rfqCount++;
+            if (rfqCount < expectedRfq)
+                return;
+            if (settleTransactionState())
+                finalize();
         }
         // -----------------------------------------------------------------------
         // Attach our listeners

package/dist/pipeline.js

@@ -20,7 +20,7 @@
  */
 import { postgresDialect } from './dialect.js';
 import { PipelineError, TurbineError, wrapPgError } from './errors.js';
-import { runPipelined, supportsExtendedPipeline } from './pipeline-submittable.js';
+import { pipelineClientNeedsDiscard, runPipelined, supportsExtendedPipeline, } from './pipeline-submittable.js';
 /**
  * Execute queries sequentially on an already-acquired connection.
  * This is the fallback path for clients that don't support the extended-query
@@ -227,7 +227,19 @@ export async function executePipeline(pool, queries, options) {
         throw wrapPgError(err);
     }
     finally {
-        client.release();
+        // A client the pipeline could not return to a clean state is released WITH
+        // an error, which is how pg-pool is told to drop it rather than lend it
+        // out again. `runPipelined` rolls back its own aborted transaction, so this
+        // is the residue: a rollback that did not take, or a backend left in a
+        // transaction by something other than this module. Releasing such a client
+        // normally is what turned one failed batch into `25P02` on somebody else's
+        // query.
+        if (pipelineClientNeedsDiscard(client)) {
+            client.release(new Error('turbine: pipeline connection left an open transaction and was discarded'));
+        }
+        else {
+            client.release();
+        }
     }
 }
 /**

package/dist/powdb-introspect.d.ts

@@ -40,7 +40,11 @@
  *     yields `primaryKey: []` and a warning; single-row ops on it fail loudly.
  *   - `isGenerated` is always `false`: `describe` does not expose PowDB's `auto`
  *     modifier, so an introspected int PK is treated as client-supplied unless
- *     the caller hand-edits the metadata.
+ *     the caller hand-edits the metadata. Since 0.78.0 that costs more than it
+ *     did: the generated `*Create` type marks a primary key optional only when
+ *     it is server-generated, defaulted or nullable, so codegen driven from
+ *     THIS metadata makes an `auto` id REQUIRED on create. `defineSchema` is
+ *     the path that knows, and remains the recommended one.
  *   - Doc-field expression indexes are INVISIBLE to `describe`, so they never
  *     round-trip; only plain `unique`/`index` columns appear in `indexes`.
  *   - `datetime` / `uuid` / `bytes` columns map to read-oriented TS types

package/dist/powdb-introspect.js

@@ -40,7 +40,11 @@
  *     yields `primaryKey: []` and a warning; single-row ops on it fail loudly.
  *   - `isGenerated` is always `false`: `describe` does not expose PowDB's `auto`
  *     modifier, so an introspected int PK is treated as client-supplied unless
- *     the caller hand-edits the metadata.
+ *     the caller hand-edits the metadata. Since 0.78.0 that costs more than it
+ *     did: the generated `*Create` type marks a primary key optional only when
+ *     it is server-generated, defaulted or nullable, so codegen driven from
+ *     THIS metadata makes an `auto` id REQUIRED on create. `defineSchema` is
+ *     the path that knows, and remains the recommended one.
  *   - Doc-field expression indexes are INVISIBLE to `describe`, so they never
  *     round-trip; only plain `unique`/`index` columns appear in `indexes`.
  *   - `datetime` / `uuid` / `bytes` columns map to read-oriented TS types