turbine-orm 0.90.1 → 0.90.2-next.91484a2

package/dist/cjs/client.d.ts

@@ -579,7 +579,9 @@ export interface TurbineConfig {
      * connection, so a statement named on one is missing (or already present) on
      * the next, unless the pooler tracks prepared statements (PgBouncer 1.21+
      * with `max_prepared_statements` above 0). Set `true` on such a pooler only
-     * when it does; Turbine warns once in development when you do.
+     * when it does. Turbine warns once (`prepared-statements-on-pooler`) when you
+     * set `true` and the connection settings name a pooler: Turbine's own, or
+     * the `options` of a `pg.Pool` you pass as `pool` (since 0.90.2).
      *
      * Override with `TURBINE_DISABLE_PREPARED=1` env var.
      *
@@ -1132,6 +1134,17 @@ export declare class TurbineClient {
      * the target leaves unset is `PGHOST` / `PGPORT`.
      */
     private static poolerEndpoint;
+    /**
+     * The pooler a pool the CALLER supplied connects to, read from the settings
+     * node-postgres keeps on the pool (`pool.options`, which `pg.Pool` and the
+     * drivers built on it expose), the way {@link poolerEndpoint} reads Turbine's
+     * own: the connection string wins over `host` / `port`, and an unset host or
+     * port is `PGHOST` / `PGPORT`. `undefined` for a pool that exposes no
+     * settings (another driver) or names no pooler.
+     */
+    private static suppliedPoolEndpoint;
+    /** The first of `targets` that names a pooler, as `host:port`, after filling unset parts from the environment. */
+    private static firstPooledTarget;
     /** Always on: named statements behind a transaction pooler fail in production first. */
     private static warnPreparedOnPooler;
     /**

package/dist/cjs/client.js

@@ -40,6 +40,7 @@ const logger_js_1 = require("./logger.js");
 const nested_write_js_1 = require("./nested-write.js");
 const observe_js_1 = require("./observe.js");
 const pipeline_js_1 = require("./pipeline.js");
+const builder_js_1 = require("./query/builder.js");
 const index_js_1 = require("./query/index.js");
 const row_lock_js_1 = require("./query/row-lock.js");
 const sql_comment_js_1 = require("./query/sql-comment.js");
@@ -814,7 +815,7 @@ class TransactionClient {
             // Create a QueryInterface that uses the transaction client as its "pool"
             // We use a proxy pool that routes queries through the transaction client
             const txPool = this.createTxPool();
-            const txOpts = { ...this.queryOptions, _txScoped: true };
+            const txOpts = (0, builder_js_1.txQueryOptions)(this.queryOptions);
             qi = txOpts.queryInterfaceFactory
                 ? (0, table_client_js_1.asQueryInterface)(txOpts.queryInterfaceFactory(txPool, name, this.schema, this.middlewares, txOpts))
                 : new index_js_1.QueryInterface(txPool, name, this.schema, this.middlewares, txOpts);
@@ -1360,8 +1361,12 @@ class TurbineClient {
         // Respect env var kill switch
         const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
         const pooler = config.pool ? undefined : TurbineClient.poolerEndpoint(config);
-        if (config.preparedStatements === true && pooler !== undefined) {
-            TurbineClient.warnPreparedOnPooler(pooler, logger);
+        // A supplied pool defaults to unnamed statements, so its endpoint is read
+        // only to warn when they are turned on behind a pooler.
+        if (config.preparedStatements === true) {
+            const endpoint = config.pool ? TurbineClient.suppliedPoolEndpoint(config.pool) : pooler;
+            if (endpoint !== undefined)
+                TurbineClient.warnPreparedOnPooler(endpoint, logger);
         }
         this.errorMessageMode = config.errorMessages ?? 'safe';
         this.errorMessagesSafe = this.errorMessageMode === 'safe';
@@ -1732,6 +1737,43 @@ class TurbineClient {
             if (typeof replica === 'string' && replica)
                 targets.push((0, connection_url_js_1.parseConnectionTarget)(replica));
         }
+        return TurbineClient.firstPooledTarget(targets);
+    }
+    /**
+     * The pooler a pool the CALLER supplied connects to, read from the settings
+     * node-postgres keeps on the pool (`pool.options`, which `pg.Pool` and the
+     * drivers built on it expose), the way {@link poolerEndpoint} reads Turbine's
+     * own: the connection string wins over `host` / `port`, and an unset host or
+     * port is `PGHOST` / `PGPORT`. `undefined` for a pool that exposes no
+     * settings (another driver) or names no pooler.
+     */
+    static suppliedPoolEndpoint(pool) {
+        // A diagnostic: a pool whose settings cannot be read is simply not checked,
+        // and nothing here may fail the constructor.
+        let target;
+        try {
+            const options = pool.options;
+            if (options === null || typeof options !== 'object')
+                return undefined;
+            const { connectionString, host, port } = options;
+            if (typeof connectionString === 'string' && connectionString) {
+                target = (0, connection_url_js_1.parseConnectionTarget)(connectionString);
+            }
+            else {
+                const portNumber = typeof port === 'string' ? Number.parseInt(port, 10) : port;
+                target = {
+                    host: typeof host === 'string' && host ? host.toLowerCase() : null,
+                    port: typeof portNumber === 'number' && Number.isInteger(portNumber) ? portNumber : null,
+                };
+            }
+        }
+        catch {
+            return undefined;
+        }
+        return TurbineClient.firstPooledTarget([target]);
+    }
+    /** The first of `targets` that names a pooler, as `host:port`, after filling unset parts from the environment. */
+    static firstPooledTarget(targets) {
         const environment = { host: pgEnv('PGHOST'), port: pgEnv('PGPORT') };
         for (const target of targets) {
             const found = (0, connection_url_js_1.detectPoolerTarget)((0, connection_url_js_1.fillTargetFromEnvironment)(target, environment));

package/dist/cjs/query/aggregates.js

@@ -212,6 +212,10 @@ function buildGroupBy(qi, args) {
         }
         else {
             const col = resolveJsonPathTarget(qi, 'group key', entry.field, entry.path);
+            // The alias below is caller text (`alias`, else the last path segment),
+            // written into the statement, so the statement goes unnamed: a key
+            // chosen per request would otherwise claim a prepared name per value.
+            qi.markVariableArity();
             assertAggregatePiiOptIn(qi.table, meta, entry.field, col, 'groupBy JSON `by` key', includePii);
             params.push(whereMod.jsonPathParam(qi, entry.path));
             const extract = qi.dialect.buildJsonPathExtract(qi.q(col), qi.p(params.length));
@@ -295,6 +299,8 @@ function buildGroupBy(qi, args) {
                 continue;
             }
             const col = resolveJsonPathTarget(qi, `${aggKey} target "${key}"`, target.field, target.path);
+            // `key` is a caller-chosen label written into the alias: unnamed, as above.
+            qi.markVariableArity();
             if (aggKey === '_min' || aggKey === '_max') {
                 assertAggregatePiiOptIn(qi.table, meta, target.field, col, `groupBy ${aggKey} JSON target`, includePii);
             }

package/dist/cjs/query/builder.d.ts

@@ -177,6 +177,7 @@ export declare const AUTO_COUNT_BATCH_MIN_PARENT_ROWS = 2;
 export declare function unlockNestedWriteTx<X extends {
     table(name: string): Record<string, unknown>;
 }>(tx: X): X;
+export declare function txQueryOptions(options: QueryInterfaceOptions | undefined): QueryInterfaceOptions;
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, TemporalInfinityReading, } from './deferred.js';
 import type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './deferred.js';
 export declare class QueryInterface<T extends object, R extends object = {}, M extends TableInputTypes = DefaultInputTypes<T, R>> {
@@ -904,8 +905,11 @@ export declare class QueryInterface<T extends object, R extends object = {}, M e
      */
     private prepareBatchedBase;
     /**
-     * Return cache hit/miss statistics for this QueryInterface instance.
-     * Useful for monitoring and benchmarking.
+     * SQL template cache statistics. `hits`, `misses` and `hitRate` count this
+     * accessor's own lookups. `size` is the entries in the cache it reads, which
+     * since 0.90.2 is shared with every accessor built from the same client
+     * options for this table: a client's primary and replica accessors share
+     * one, and all of its transactions share another (see `templateCacheFor`).
      */
     cacheStats(): {
         hits: number;
@@ -951,6 +955,19 @@ export declare class QueryInterface<T extends object, R extends object = {}, M e
      * variable-arity and the measured reason it must not be named.
      */
     private buildCacheEntry;
+    /**
+     * The prepared-statement name for `sql`: empty (sent unnamed) for a
+     * variable-arity shape, else derived from the text.
+     */
+    private preparedNameOf;
+    /**
+     * Name a statement the SQL template cache does not hold (`aggregate`,
+     * `groupBy`): the build runs between a reset and a read of the
+     * variable-arity flag, exactly as in {@link buildCacheEntry}, so the same
+     * shapes stay unnamed. These used to be sent unnamed always, so with
+     * prepared statements on the server re-parsed every `aggregate`.
+     */
+    private withPreparedName;
     /**
      * The SQL-cache lockstep checks (see the comment above `CACHE_MISMATCH_WARN_NS`).
      *

package/dist/cjs/query/builder.js

@@ -47,6 +47,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryInterface = exports.AUTO_COUNT_BATCH_MIN_PARENT_ROWS = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.AUTO_JOIN_PENALTY_MS_PER_ROW = void 0;
 exports.unlockNestedWriteTx = unlockNestedWriteTx;
+exports.txQueryOptions = txQueryOptions;
 const checkout_js_1 = require("../checkout.js");
 const connection_guard_js_1 = require("../connection-guard.js");
 const diagnostics_js_1 = require("../diagnostics.js");
@@ -539,6 +540,69 @@ const JSON_ENCODINGS = Object.freeze(['object', 'positional']);
 function defaultJsonEncoding(dialect) {
     return dialect.capabilities.positionalJson ? 'positional' : 'object';
 }
+/**
+ * SQL template caches shared by every QueryInterface built from ONE options
+ * object, for one schema and one table.
+ *
+ * A transaction builds its own QueryInterface per table, so before this each
+ * `$transaction` started with an empty cache and rebuilt the SQL of every
+ * statement it sent. TransactionClient now hands every transaction of a client
+ * the same options object (`txQueryOptions` in client.ts), so they share one
+ * cache per table and a statement is built once per process, as it is outside
+ * a transaction.
+ *
+ * THE KEY IS THE OPTIONS OBJECT'S IDENTITY, deliberately, not a fingerprint of
+ * its fields. Options change the SQL (`defaultLimit`, `jsonEncoding`,
+ * `globalFilters`, the dialect, ...), and a cache key does not carry them,
+ * because one QueryInterface never sees two values. A copy that changes any
+ * field is a new object and so gets its own caches: the batched loader's
+ * children (`defaultLimit: undefined`) can never be served the parent's SQL,
+ * and no list of SQL-affecting options exists to fall out of date. Nothing
+ * mutates an options object after construction.
+ */
+const sharedTemplateCaches = new WeakMap();
+/**
+ * The options a transaction's query interfaces are built with: `options` plus
+ * `_txScoped`. ONE object per options object, so every transaction of a client
+ * (and every nested write inside one) builds its query interfaces from the same
+ * object and shares their template caches (see {@link templateCacheFor}). A
+ * fresh copy per transaction gave each `$transaction` an empty cache, so every
+ * statement in it rebuilt its SQL. Options that are already transaction-scoped
+ * are returned as they are.
+ */
+const txOptionsCache = new WeakMap();
+function txQueryOptions(options) {
+    if (options === undefined)
+        return { _txScoped: true };
+    if (options._txScoped === true)
+        return options;
+    let tx = txOptionsCache.get(options);
+    if (tx === undefined) {
+        tx = { ...options, _txScoped: true };
+        txOptionsCache.set(options, tx);
+    }
+    return tx;
+}
+function templateCacheFor(options, schema, table, capacity) {
+    if (options === undefined)
+        return new utils_js_1.LRUCache(capacity);
+    let bySchema = sharedTemplateCaches.get(options);
+    if (bySchema === undefined) {
+        bySchema = new WeakMap();
+        sharedTemplateCaches.set(options, bySchema);
+    }
+    let byTable = bySchema.get(schema);
+    if (byTable === undefined) {
+        byTable = new Map();
+        bySchema.set(schema, byTable);
+    }
+    let cache = byTable.get(table);
+    if (cache === undefined) {
+        cache = new utils_js_1.LRUCache(capacity);
+        byTable.set(table, cache);
+    }
+    return cache;
+}
 class QueryInterface {
     pool;
     table;
@@ -832,7 +896,7 @@ class QueryInterface {
         // treated as the default rather than throwing.
         const sqlCacheSize = options?.sqlCacheSize;
         this.sqlCacheEnabled = options?.sqlCache !== false && sqlCacheSize !== 0;
-        this.sqlTemplateCache = new utils_js_1.LRUCache(sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
+        this.sqlTemplateCache = templateCacheFor(options, schema, table, sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
         this.dialect = options?.dialect ?? dialect_js_1.postgresDialect;
         (0, dialect_js_1.assertDialectCapabilities)(this.dialect);
         this.sqlCommenter =
@@ -2221,8 +2285,11 @@ class QueryInterface {
         return { baseArgs, strip: proj.strip };
     }
     /**
-     * Return cache hit/miss statistics for this QueryInterface instance.
-     * Useful for monitoring and benchmarking.
+     * SQL template cache statistics. `hits`, `misses` and `hitRate` count this
+     * accessor's own lookups. `size` is the entries in the cache it reads, which
+     * since 0.90.2 is shared with every accessor built from the same client
+     * options for this table: a client's primary and replica accessors share
+     * one, and all of its transactions share another (see `templateCacheFor`).
      */
     cacheStats() {
         const total = this.cacheHits + this.cacheMisses;
@@ -2295,15 +2362,33 @@ class QueryInterface {
         this.variableArityShape = false;
         this.cacheMisses++;
         this.lastMissParams = built;
+        return { sql, name: this.preparedNameOf(sql, variableArity), paramCount: built.length };
+    }
+    /**
+     * The prepared-statement name for `sql`: empty (sent unnamed) for a
+     * variable-arity shape, else derived from the text.
+     */
+    preparedNameOf(sql, variableArity) {
+        if (variableArity)
+            return '';
         // With `sqlComment` putting a comment on every statement, the template's own
         // name is never sent (the execute seam sends a `c_` name derived from it),
         // so it is not claimed from the budget: only names that reach the wire do.
-        const name = variableArity
-            ? ''
-            : this.sqlCommenter?.alwaysComments
-                ? (0, utils_js_1.sqlToPreparedName)(sql)
-                : (0, utils_js_1.boundedPreparedName)(sql);
-        return { sql, name, paramCount: built.length };
+        return this.sqlCommenter?.alwaysComments ? (0, utils_js_1.sqlToPreparedName)(sql) : (0, utils_js_1.boundedPreparedName)(sql);
+    }
+    /**
+     * Name a statement the SQL template cache does not hold (`aggregate`,
+     * `groupBy`): the build runs between a reset and a read of the
+     * variable-arity flag, exactly as in {@link buildCacheEntry}, so the same
+     * shapes stay unnamed. These used to be sent unnamed always, so with
+     * prepared statements on the server re-parsed every `aggregate`.
+     */
+    withPreparedName(build) {
+        this.variableArityShape = false;
+        const deferred = build();
+        const variableArity = this.variableArityShape;
+        this.variableArityShape = false;
+        return { ...deferred, preparedName: this.preparedNameOf(deferred.sql, variableArity) };
     }
     /**
      * The SQL-cache lockstep checks (see the comment above `CACHE_MISMATCH_WARN_NS`).
@@ -4264,6 +4349,8 @@ class QueryInterface {
                 return rows.length > 0 ? rows[0] : null;
             },
             tag: `${this.table}.findFirst`,
+            // findMany's name: the same statement, so the same prepared statement.
+            ...(deferred.preparedName !== undefined ? { preparedName: deferred.preparedName } : {}),
             ...(deferred.rowLock ? { rowLock: true } : {}),
         };
     }
@@ -4297,6 +4384,7 @@ class QueryInterface {
                 return row;
             },
             tag: `${this.table}.findFirstOrThrow`,
+            ...(inner.preparedName !== undefined ? { preparedName: inner.preparedName } : {}),
             ...(inner.rowLock ? { rowLock: true } : {}),
         };
     }
@@ -4330,6 +4418,7 @@ class QueryInterface {
                 return row;
             },
             tag: `${this.table}.findUniqueOrThrow`,
+            ...(inner.preparedName !== undefined ? { preparedName: inner.preparedName } : {}),
             ...(inner.rowLock ? { rowLock: true } : {}),
         };
     }
@@ -4499,7 +4588,10 @@ class QueryInterface {
         const pool = this.pool;
         const schema = this.schema;
         const middlewares = this.middlewares;
-        const opts = { ...this.options, _txScoped: true };
+        // The client's transaction options object, not a copy per call: the SQL
+        // template cache is shared by options-object identity, so a fresh copy
+        // rebuilt the SQL of every child statement of every nested write.
+        const opts = txQueryOptions(this.options);
         return {
             schema,
             tx: unlockNestedWriteTx(this.makeTxProxy(pool, schema, middlewares, opts)),
@@ -4690,10 +4782,12 @@ class QueryInterface {
     // Aggregate / groupBy compilation (extracted to aggregates.ts).
     // ---------------------------------------------------------------------------
     buildGroupBy(args) {
-        return aggMod.buildGroupBy(this.ctx, this.normalizeArgs(args));
+        const normalized = this.normalizeArgs(args);
+        return this.withPreparedName(() => aggMod.buildGroupBy(this.ctx, normalized));
     }
     buildAggregate(args) {
-        return aggMod.buildAggregate(this.ctx, this.normalizeArgs(args));
+        const normalized = this.normalizeArgs(args);
+        return this.withPreparedName(() => aggMod.buildAggregate(this.ctx, normalized));
     }
     // -------------------------------------------------------------------------
     // aggregate, standalone aggregation without groupBy

package/dist/cjs/query/writes.js

@@ -75,7 +75,6 @@ exports.fingerprintSet = fingerprintSet;
 exports.collectSetParams = collectSetParams;
 const dialect_js_1 = require("../dialect.js");
 const errors_js_1 = require("../errors.js");
-const schema_js_1 = require("../schema.js");
 const column_ref_js_1 = require("./column-ref.js");
 const compound_unique_js_1 = require("./compound-unique.js");
 const expr_js_1 = require("./expr.js");
@@ -818,6 +817,10 @@ function definedKeys(qi, row) {
 function assertUniformCreateManyRows(qi, rows, firstKeys) {
     const expected = new Set(firstKeys);
     for (let i = 1; i < rows.length; i++) {
+        // The common case, decided without ordering the row's keys: as many
+        // defined keys as the first row, each one of its keys.
+        if (namesExactly(rows[i], expected))
+            continue;
         const rowKeys = definedKeys(qi, rows[i]);
         const unexpected = rowKeys.filter((k) => !expected.has(k));
         // No stranger and the same count means the same set (object keys are unique).
@@ -838,6 +841,18 @@ function assertUniformCreateManyRows(qi, rows, firstKeys) {
             'row shape.');
     }
 }
+/** Whether `row`'s defined keys are exactly `keys` (object keys are unique, so count plus membership decides it). */
+function namesExactly(row, keys) {
+    let count = 0;
+    for (const key in row) {
+        if (!Object.hasOwn(row, key) || row[key] === undefined)
+            continue;
+        if (!keys.has(key))
+            return false;
+        count++;
+    }
+    return count === keys.size;
+}
 /** `a, b` → `"a", "b"`, for the field lists in {@link assertUniformCreateManyRows}. */
 function quoteList(fields) {
     return fields.map((f) => `"${f}"`).join(', ');
@@ -920,8 +935,15 @@ function prepareCreateMany(qi, args, projection) {
         };
     }
     assertWritable(qi, 'createMany');
-    for (const row of args.data) {
-        assertNoGeneratedColumns(qi, row, 'createMany');
+    args.data.forEach((row, i) => {
+        if (row === null || typeof row !== 'object') {
+            throw new errors_js_1.ValidationError(`createMany on "${qi.table}": row ${i} is ${row === null ? 'null' : `a ${typeof row}`}, not an object of fields.`);
+        }
+    });
+    const generated = generatedStoredColumns(qi);
+    if (generated !== null) {
+        for (const row of args.data)
+            assertNoGeneratedKeys(qi, generated, row, 'createMany');
     }
     const keys = definedKeys(qi, args.data[0]);
     assertUniformCreateManyRows(qi, args.data, keys);
@@ -1117,11 +1139,13 @@ function describeConflictTargets(qi) {
 }
 /** The conflict-UPDATE's data: the field-list shorthand becomes `{ f: expr.excluded(f) }`. */
 function resolveConflictUpdate(qi, raw) {
-    const empty = new errors_js_1.ValidationError(`createMany on "${qi.table}": onConflict.update is empty; use onConflict: { target, ignore: true } to skip ` +
+    // A function, not an error built up front: constructing one captures a
+    // stack trace, and this runs on every onConflict call.
+    const empty = () => new errors_js_1.ValidationError(`createMany on "${qi.table}": onConflict.update is empty; use onConflict: { target, ignore: true } to skip ` +
         'conflicting rows.');
     if (Array.isArray(raw)) {
         if (raw.length === 0)
-            throw empty;
+            throw empty();
         const update = {};
         for (const field of raw) {
             if (typeof field !== 'string') {
@@ -1138,7 +1162,7 @@ function resolveConflictUpdate(qi, raw) {
         throw new errors_js_1.ValidationError(`createMany on "${qi.table}": onConflict.update takes a list of field names or a { field: value } object.`);
     }
     if (!Object.values(raw).some((v) => v !== undefined))
-        throw empty;
+        throw empty();
     assertNoGeneratedColumns(qi, raw, 'createMany');
     return raw;
 }
@@ -1194,12 +1218,15 @@ function keyToken(value) {
 function assertNoDuplicateKeys(qi, conflict, columns, rowValues) {
     const at = conflict.target.map((c) => columns.indexOf(c));
     const seen = new Map();
-    for (let i = 0; i < rowValues.length; i++) {
+    rows: for (let i = 0; i < rowValues.length; i++) {
         const row = rowValues[i];
-        const parts = at.map((j) => row[j]);
-        if (parts.some((v) => v === null || v === undefined))
-            continue;
-        const key = parts.map(keyToken).join('|');
+        let key = '';
+        for (let k = 0; k < at.length; k++) {
+            const value = row[at[k]];
+            if (value === null || value === undefined)
+                continue rows;
+            key += k === 0 ? keyToken(value) : `|${keyToken(value)}`;
+        }
         const first = seen.get(key);
         if (first !== undefined) {
             throw new errors_js_1.ValidationError(`createMany onConflict on "${qi.table}": rows ${first} and ${i} share the conflict key ` +
@@ -2164,11 +2191,34 @@ function assertWritable(qi, operation) {
  * (they're stripped from the statement anyway).
  */
 function assertNoGeneratedColumns(qi, data, operation) {
-    for (const [key, value] of Object.entries(data)) {
-        if (value === undefined)
+    const generated = generatedStoredColumns(qi);
+    if (generated !== null)
+        assertNoGeneratedKeys(qi, generated, data, operation);
+}
+/**
+ * The table's generated stored columns, or `null` when it has none (most
+ * tables, and then a write checks nothing). Read once per call, so
+ * `createMany` checks every row against one answer: it used to search the
+ * column list, with a `camelToSnake` per comparison, for every field of every
+ * row, which was most of a 150-row upsert's build time.
+ */
+function generatedStoredColumns(qi) {
+    let columns = null;
+    for (const c of qi.tableMeta.columns) {
+        if (!c.isGeneratedStored)
             continue;
-        const col = qi.tableMeta.columns.find((c) => c.field === key || c.name === key || c.name === (0, schema_js_1.camelToSnake)(key));
-        if (col?.isGeneratedStored) {
+        columns ??= new Set();
+        columns.add(c.name);
+    }
+    return columns;
+}
+/** Refuse a key of `data` that names one of `generated` (by THE key rule, {@link resolveColumnName}). */
+function assertNoGeneratedKeys(qi, generated, data, operation) {
+    for (const key in data) {
+        if (!Object.hasOwn(data, key) || data[key] === undefined)
+            continue;
+        const column = (0, utils_js_1.resolveColumnName)(qi.tableMeta, key);
+        if (column !== undefined && generated.has(column)) {
             throw new errors_js_1.ValidationError(`Cannot ${operation} "${qi.table}": column "${key}" is a GENERATED ALWAYS AS (…) STORED ` +
                 'column whose value the database computes, remove it from your data.');
         }

package/dist/client.d.ts

@@ -579,7 +579,9 @@ export interface TurbineConfig {
      * connection, so a statement named on one is missing (or already present) on
      * the next, unless the pooler tracks prepared statements (PgBouncer 1.21+
      * with `max_prepared_statements` above 0). Set `true` on such a pooler only
-     * when it does; Turbine warns once in development when you do.
+     * when it does. Turbine warns once (`prepared-statements-on-pooler`) when you
+     * set `true` and the connection settings name a pooler: Turbine's own, or
+     * the `options` of a `pg.Pool` you pass as `pool` (since 0.90.2).
      *
      * Override with `TURBINE_DISABLE_PREPARED=1` env var.
      *
@@ -1132,6 +1134,17 @@ export declare class TurbineClient {
      * the target leaves unset is `PGHOST` / `PGPORT`.
      */
     private static poolerEndpoint;
+    /**
+     * The pooler a pool the CALLER supplied connects to, read from the settings
+     * node-postgres keeps on the pool (`pool.options`, which `pg.Pool` and the
+     * drivers built on it expose), the way {@link poolerEndpoint} reads Turbine's
+     * own: the connection string wins over `host` / `port`, and an unset host or
+     * port is `PGHOST` / `PGPORT`. `undefined` for a pool that exposes no
+     * settings (another driver) or names no pooler.
+     */
+    private static suppliedPoolEndpoint;
+    /** The first of `targets` that names a pooler, as `host:port`, after filling unset parts from the environment. */
+    private static firstPooledTarget;
     /** Always on: named statements behind a transaction pooler fail in production first. */
     private static warnPreparedOnPooler;
     /**

package/dist/client.js

@@ -33,6 +33,7 @@ import { CLIENT_LOG_CONTEXT, logTo, resolveLogger } from './logger.js';
 import { hasRelationFields } from './nested-write.js';
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
+import { txQueryOptions } from './query/builder.js';
 import { QueryInterface, } from './query/index.js';
 import { assertNoLockInAutocommitPipeline } from './query/row-lock.js';
 import { commentDeferred, resolveSqlComment } from './query/sql-comment.js';
@@ -807,7 +808,7 @@ export class TransactionClient {
             // Create a QueryInterface that uses the transaction client as its "pool"
             // We use a proxy pool that routes queries through the transaction client
             const txPool = this.createTxPool();
-            const txOpts = { ...this.queryOptions, _txScoped: true };
+            const txOpts = txQueryOptions(this.queryOptions);
             qi = txOpts.queryInterfaceFactory
                 ? asQueryInterface(txOpts.queryInterfaceFactory(txPool, name, this.schema, this.middlewares, txOpts))
                 : new QueryInterface(txPool, name, this.schema, this.middlewares, txOpts);
@@ -1352,8 +1353,12 @@ export class TurbineClient {
         // Respect env var kill switch
         const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
         const pooler = config.pool ? undefined : TurbineClient.poolerEndpoint(config);
-        if (config.preparedStatements === true && pooler !== undefined) {
-            TurbineClient.warnPreparedOnPooler(pooler, logger);
+        // A supplied pool defaults to unnamed statements, so its endpoint is read
+        // only to warn when they are turned on behind a pooler.
+        if (config.preparedStatements === true) {
+            const endpoint = config.pool ? TurbineClient.suppliedPoolEndpoint(config.pool) : pooler;
+            if (endpoint !== undefined)
+                TurbineClient.warnPreparedOnPooler(endpoint, logger);
         }
         this.errorMessageMode = config.errorMessages ?? 'safe';
         this.errorMessagesSafe = this.errorMessageMode === 'safe';
@@ -1724,6 +1729,43 @@ export class TurbineClient {
             if (typeof replica === 'string' && replica)
                 targets.push(parseConnectionTarget(replica));
         }
+        return TurbineClient.firstPooledTarget(targets);
+    }
+    /**
+     * The pooler a pool the CALLER supplied connects to, read from the settings
+     * node-postgres keeps on the pool (`pool.options`, which `pg.Pool` and the
+     * drivers built on it expose), the way {@link poolerEndpoint} reads Turbine's
+     * own: the connection string wins over `host` / `port`, and an unset host or
+     * port is `PGHOST` / `PGPORT`. `undefined` for a pool that exposes no
+     * settings (another driver) or names no pooler.
+     */
+    static suppliedPoolEndpoint(pool) {
+        // A diagnostic: a pool whose settings cannot be read is simply not checked,
+        // and nothing here may fail the constructor.
+        let target;
+        try {
+            const options = pool.options;
+            if (options === null || typeof options !== 'object')
+                return undefined;
+            const { connectionString, host, port } = options;
+            if (typeof connectionString === 'string' && connectionString) {
+                target = parseConnectionTarget(connectionString);
+            }
+            else {
+                const portNumber = typeof port === 'string' ? Number.parseInt(port, 10) : port;
+                target = {
+                    host: typeof host === 'string' && host ? host.toLowerCase() : null,
+                    port: typeof portNumber === 'number' && Number.isInteger(portNumber) ? portNumber : null,
+                };
+            }
+        }
+        catch {
+            return undefined;
+        }
+        return TurbineClient.firstPooledTarget([target]);
+    }
+    /** The first of `targets` that names a pooler, as `host:port`, after filling unset parts from the environment. */
+    static firstPooledTarget(targets) {
         const environment = { host: pgEnv('PGHOST'), port: pgEnv('PGPORT') };
         for (const target of targets) {
             const found = detectPoolerTarget(fillTargetFromEnvironment(target, environment));

package/dist/query/aggregates.js

@@ -168,6 +168,10 @@ export function buildGroupBy(qi, args) {
         }
         else {
             const col = resolveJsonPathTarget(qi, 'group key', entry.field, entry.path);
+            // The alias below is caller text (`alias`, else the last path segment),
+            // written into the statement, so the statement goes unnamed: a key
+            // chosen per request would otherwise claim a prepared name per value.
+            qi.markVariableArity();
             assertAggregatePiiOptIn(qi.table, meta, entry.field, col, 'groupBy JSON `by` key', includePii);
             params.push(whereMod.jsonPathParam(qi, entry.path));
             const extract = qi.dialect.buildJsonPathExtract(qi.q(col), qi.p(params.length));
@@ -251,6 +255,8 @@ export function buildGroupBy(qi, args) {
                 continue;
             }
             const col = resolveJsonPathTarget(qi, `${aggKey} target "${key}"`, target.field, target.path);
+            // `key` is a caller-chosen label written into the alias: unnamed, as above.
+            qi.markVariableArity();
             if (aggKey === '_min' || aggKey === '_max') {
                 assertAggregatePiiOptIn(qi.table, meta, target.field, col, `groupBy ${aggKey} JSON target`, includePii);
             }

package/dist/query/builder.d.ts

@@ -177,6 +177,7 @@ export declare const AUTO_COUNT_BATCH_MIN_PARENT_ROWS = 2;
 export declare function unlockNestedWriteTx<X extends {
     table(name: string): Record<string, unknown>;
 }>(tx: X): X;
+export declare function txQueryOptions(options: QueryInterfaceOptions | undefined): QueryInterfaceOptions;
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, TemporalInfinityReading, } from './deferred.js';
 import type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './deferred.js';
 export declare class QueryInterface<T extends object, R extends object = {}, M extends TableInputTypes = DefaultInputTypes<T, R>> {
@@ -904,8 +905,11 @@ export declare class QueryInterface<T extends object, R extends object = {}, M e
      */
     private prepareBatchedBase;
     /**
-     * Return cache hit/miss statistics for this QueryInterface instance.
-     * Useful for monitoring and benchmarking.
+     * SQL template cache statistics. `hits`, `misses` and `hitRate` count this
+     * accessor's own lookups. `size` is the entries in the cache it reads, which
+     * since 0.90.2 is shared with every accessor built from the same client
+     * options for this table: a client's primary and replica accessors share
+     * one, and all of its transactions share another (see `templateCacheFor`).
      */
     cacheStats(): {
         hits: number;
@@ -951,6 +955,19 @@ export declare class QueryInterface<T extends object, R extends object = {}, M e
      * variable-arity and the measured reason it must not be named.
      */
     private buildCacheEntry;
+    /**
+     * The prepared-statement name for `sql`: empty (sent unnamed) for a
+     * variable-arity shape, else derived from the text.
+     */
+    private preparedNameOf;
+    /**
+     * Name a statement the SQL template cache does not hold (`aggregate`,
+     * `groupBy`): the build runs between a reset and a read of the
+     * variable-arity flag, exactly as in {@link buildCacheEntry}, so the same
+     * shapes stay unnamed. These used to be sent unnamed always, so with
+     * prepared statements on the server re-parsed every `aggregate`.
+     */
+    private withPreparedName;
     /**
      * The SQL-cache lockstep checks (see the comment above `CACHE_MISMATCH_WARN_NS`).
      *

package/dist/query/builder.js

@@ -502,6 +502,69 @@ const JSON_ENCODINGS = Object.freeze(['object', 'positional']);
 function defaultJsonEncoding(dialect) {
     return dialect.capabilities.positionalJson ? 'positional' : 'object';
 }
+/**
+ * SQL template caches shared by every QueryInterface built from ONE options
+ * object, for one schema and one table.
+ *
+ * A transaction builds its own QueryInterface per table, so before this each
+ * `$transaction` started with an empty cache and rebuilt the SQL of every
+ * statement it sent. TransactionClient now hands every transaction of a client
+ * the same options object (`txQueryOptions` in client.ts), so they share one
+ * cache per table and a statement is built once per process, as it is outside
+ * a transaction.
+ *
+ * THE KEY IS THE OPTIONS OBJECT'S IDENTITY, deliberately, not a fingerprint of
+ * its fields. Options change the SQL (`defaultLimit`, `jsonEncoding`,
+ * `globalFilters`, the dialect, ...), and a cache key does not carry them,
+ * because one QueryInterface never sees two values. A copy that changes any
+ * field is a new object and so gets its own caches: the batched loader's
+ * children (`defaultLimit: undefined`) can never be served the parent's SQL,
+ * and no list of SQL-affecting options exists to fall out of date. Nothing
+ * mutates an options object after construction.
+ */
+const sharedTemplateCaches = new WeakMap();
+/**
+ * The options a transaction's query interfaces are built with: `options` plus
+ * `_txScoped`. ONE object per options object, so every transaction of a client
+ * (and every nested write inside one) builds its query interfaces from the same
+ * object and shares their template caches (see {@link templateCacheFor}). A
+ * fresh copy per transaction gave each `$transaction` an empty cache, so every
+ * statement in it rebuilt its SQL. Options that are already transaction-scoped
+ * are returned as they are.
+ */
+const txOptionsCache = new WeakMap();
+export function txQueryOptions(options) {
+    if (options === undefined)
+        return { _txScoped: true };
+    if (options._txScoped === true)
+        return options;
+    let tx = txOptionsCache.get(options);
+    if (tx === undefined) {
+        tx = { ...options, _txScoped: true };
+        txOptionsCache.set(options, tx);
+    }
+    return tx;
+}
+function templateCacheFor(options, schema, table, capacity) {
+    if (options === undefined)
+        return new LRUCache(capacity);
+    let bySchema = sharedTemplateCaches.get(options);
+    if (bySchema === undefined) {
+        bySchema = new WeakMap();
+        sharedTemplateCaches.set(options, bySchema);
+    }
+    let byTable = bySchema.get(schema);
+    if (byTable === undefined) {
+        byTable = new Map();
+        bySchema.set(schema, byTable);
+    }
+    let cache = byTable.get(table);
+    if (cache === undefined) {
+        cache = new LRUCache(capacity);
+        byTable.set(table, cache);
+    }
+    return cache;
+}
 export class QueryInterface {
     pool;
     table;
@@ -795,7 +858,7 @@ export class QueryInterface {
         // treated as the default rather than throwing.
         const sqlCacheSize = options?.sqlCacheSize;
         this.sqlCacheEnabled = options?.sqlCache !== false && sqlCacheSize !== 0;
-        this.sqlTemplateCache = new LRUCache(sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
+        this.sqlTemplateCache = templateCacheFor(options, schema, table, sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
         this.dialect = options?.dialect ?? postgresDialect;
         assertDialectCapabilities(this.dialect);
         this.sqlCommenter =
@@ -2184,8 +2247,11 @@ export class QueryInterface {
         return { baseArgs, strip: proj.strip };
     }
     /**
-     * Return cache hit/miss statistics for this QueryInterface instance.
-     * Useful for monitoring and benchmarking.
+     * SQL template cache statistics. `hits`, `misses` and `hitRate` count this
+     * accessor's own lookups. `size` is the entries in the cache it reads, which
+     * since 0.90.2 is shared with every accessor built from the same client
+     * options for this table: a client's primary and replica accessors share
+     * one, and all of its transactions share another (see `templateCacheFor`).
      */
     cacheStats() {
         const total = this.cacheHits + this.cacheMisses;
@@ -2258,15 +2324,33 @@ export class QueryInterface {
         this.variableArityShape = false;
         this.cacheMisses++;
         this.lastMissParams = built;
+        return { sql, name: this.preparedNameOf(sql, variableArity), paramCount: built.length };
+    }
+    /**
+     * The prepared-statement name for `sql`: empty (sent unnamed) for a
+     * variable-arity shape, else derived from the text.
+     */
+    preparedNameOf(sql, variableArity) {
+        if (variableArity)
+            return '';
         // With `sqlComment` putting a comment on every statement, the template's own
         // name is never sent (the execute seam sends a `c_` name derived from it),
         // so it is not claimed from the budget: only names that reach the wire do.
-        const name = variableArity
-            ? ''
-            : this.sqlCommenter?.alwaysComments
-                ? sqlToPreparedName(sql)
-                : boundedPreparedName(sql);
-        return { sql, name, paramCount: built.length };
+        return this.sqlCommenter?.alwaysComments ? sqlToPreparedName(sql) : boundedPreparedName(sql);
+    }
+    /**
+     * Name a statement the SQL template cache does not hold (`aggregate`,
+     * `groupBy`): the build runs between a reset and a read of the
+     * variable-arity flag, exactly as in {@link buildCacheEntry}, so the same
+     * shapes stay unnamed. These used to be sent unnamed always, so with
+     * prepared statements on the server re-parsed every `aggregate`.
+     */
+    withPreparedName(build) {
+        this.variableArityShape = false;
+        const deferred = build();
+        const variableArity = this.variableArityShape;
+        this.variableArityShape = false;
+        return { ...deferred, preparedName: this.preparedNameOf(deferred.sql, variableArity) };
     }
     /**
      * The SQL-cache lockstep checks (see the comment above `CACHE_MISMATCH_WARN_NS`).
@@ -4227,6 +4311,8 @@ export class QueryInterface {
                 return rows.length > 0 ? rows[0] : null;
             },
             tag: `${this.table}.findFirst`,
+            // findMany's name: the same statement, so the same prepared statement.
+            ...(deferred.preparedName !== undefined ? { preparedName: deferred.preparedName } : {}),
             ...(deferred.rowLock ? { rowLock: true } : {}),
         };
     }
@@ -4260,6 +4346,7 @@ export class QueryInterface {
                 return row;
             },
             tag: `${this.table}.findFirstOrThrow`,
+            ...(inner.preparedName !== undefined ? { preparedName: inner.preparedName } : {}),
             ...(inner.rowLock ? { rowLock: true } : {}),
         };
     }
@@ -4293,6 +4380,7 @@ export class QueryInterface {
                 return row;
             },
             tag: `${this.table}.findUniqueOrThrow`,
+            ...(inner.preparedName !== undefined ? { preparedName: inner.preparedName } : {}),
             ...(inner.rowLock ? { rowLock: true } : {}),
         };
     }
@@ -4462,7 +4550,10 @@ export class QueryInterface {
         const pool = this.pool;
         const schema = this.schema;
         const middlewares = this.middlewares;
-        const opts = { ...this.options, _txScoped: true };
+        // The client's transaction options object, not a copy per call: the SQL
+        // template cache is shared by options-object identity, so a fresh copy
+        // rebuilt the SQL of every child statement of every nested write.
+        const opts = txQueryOptions(this.options);
         return {
             schema,
             tx: unlockNestedWriteTx(this.makeTxProxy(pool, schema, middlewares, opts)),
@@ -4653,10 +4744,12 @@ export class QueryInterface {
     // Aggregate / groupBy compilation (extracted to aggregates.ts).
     // ---------------------------------------------------------------------------
     buildGroupBy(args) {
-        return aggMod.buildGroupBy(this.ctx, this.normalizeArgs(args));
+        const normalized = this.normalizeArgs(args);
+        return this.withPreparedName(() => aggMod.buildGroupBy(this.ctx, normalized));
     }
     buildAggregate(args) {
-        return aggMod.buildAggregate(this.ctx, this.normalizeArgs(args));
+        const normalized = this.normalizeArgs(args);
+        return this.withPreparedName(() => aggMod.buildAggregate(this.ctx, normalized));
     }
     // -------------------------------------------------------------------------
     // aggregate, standalone aggregation without groupBy

package/dist/query/writes.js

@@ -12,7 +12,6 @@
  */
 import { maxBindParameters, } from '../dialect.js';
 import { NotFoundError, OptimisticLockError, UnsupportedFeatureError, ValidationError } from '../errors.js';
-import { camelToSnake } from '../schema.js';
 import { isColumnRef } from './column-ref.js';
 import { assertMutationWhereIdentifiesOneRow, expandCompoundUniqueWhere, otherCollidingUniqueKey, uniqueKeyNames, upsertCreateCollidingKey, upsertWhereMatchesCreate, } from './compound-unique.js';
 import { compileSetExpr, expr as exprBuilders, exprNotAllowedMessage, isPlainExprShape, isSqlExpr, plainExprShapeMessage, resolveExcludedFromCreate, } from './expr.js';
@@ -755,6 +754,10 @@ function definedKeys(qi, row) {
 function assertUniformCreateManyRows(qi, rows, firstKeys) {
     const expected = new Set(firstKeys);
     for (let i = 1; i < rows.length; i++) {
+        // The common case, decided without ordering the row's keys: as many
+        // defined keys as the first row, each one of its keys.
+        if (namesExactly(rows[i], expected))
+            continue;
         const rowKeys = definedKeys(qi, rows[i]);
         const unexpected = rowKeys.filter((k) => !expected.has(k));
         // No stranger and the same count means the same set (object keys are unique).
@@ -775,6 +778,18 @@ function assertUniformCreateManyRows(qi, rows, firstKeys) {
             'row shape.');
     }
 }
+/** Whether `row`'s defined keys are exactly `keys` (object keys are unique, so count plus membership decides it). */
+function namesExactly(row, keys) {
+    let count = 0;
+    for (const key in row) {
+        if (!Object.hasOwn(row, key) || row[key] === undefined)
+            continue;
+        if (!keys.has(key))
+            return false;
+        count++;
+    }
+    return count === keys.size;
+}
 /** `a, b` → `"a", "b"`, for the field lists in {@link assertUniformCreateManyRows}. */
 function quoteList(fields) {
     return fields.map((f) => `"${f}"`).join(', ');
@@ -857,8 +872,15 @@ function prepareCreateMany(qi, args, projection) {
         };
     }
     assertWritable(qi, 'createMany');
-    for (const row of args.data) {
-        assertNoGeneratedColumns(qi, row, 'createMany');
+    args.data.forEach((row, i) => {
+        if (row === null || typeof row !== 'object') {
+            throw new ValidationError(`createMany on "${qi.table}": row ${i} is ${row === null ? 'null' : `a ${typeof row}`}, not an object of fields.`);
+        }
+    });
+    const generated = generatedStoredColumns(qi);
+    if (generated !== null) {
+        for (const row of args.data)
+            assertNoGeneratedKeys(qi, generated, row, 'createMany');
     }
     const keys = definedKeys(qi, args.data[0]);
     assertUniformCreateManyRows(qi, args.data, keys);
@@ -1054,11 +1076,13 @@ function describeConflictTargets(qi) {
 }
 /** The conflict-UPDATE's data: the field-list shorthand becomes `{ f: expr.excluded(f) }`. */
 function resolveConflictUpdate(qi, raw) {
-    const empty = new ValidationError(`createMany on "${qi.table}": onConflict.update is empty; use onConflict: { target, ignore: true } to skip ` +
+    // A function, not an error built up front: constructing one captures a
+    // stack trace, and this runs on every onConflict call.
+    const empty = () => new ValidationError(`createMany on "${qi.table}": onConflict.update is empty; use onConflict: { target, ignore: true } to skip ` +
         'conflicting rows.');
     if (Array.isArray(raw)) {
         if (raw.length === 0)
-            throw empty;
+            throw empty();
         const update = {};
         for (const field of raw) {
             if (typeof field !== 'string') {
@@ -1075,7 +1099,7 @@ function resolveConflictUpdate(qi, raw) {
         throw new ValidationError(`createMany on "${qi.table}": onConflict.update takes a list of field names or a { field: value } object.`);
     }
     if (!Object.values(raw).some((v) => v !== undefined))
-        throw empty;
+        throw empty();
     assertNoGeneratedColumns(qi, raw, 'createMany');
     return raw;
 }
@@ -1131,12 +1155,15 @@ function keyToken(value) {
 function assertNoDuplicateKeys(qi, conflict, columns, rowValues) {
     const at = conflict.target.map((c) => columns.indexOf(c));
     const seen = new Map();
-    for (let i = 0; i < rowValues.length; i++) {
+    rows: for (let i = 0; i < rowValues.length; i++) {
         const row = rowValues[i];
-        const parts = at.map((j) => row[j]);
-        if (parts.some((v) => v === null || v === undefined))
-            continue;
-        const key = parts.map(keyToken).join('|');
+        let key = '';
+        for (let k = 0; k < at.length; k++) {
+            const value = row[at[k]];
+            if (value === null || value === undefined)
+                continue rows;
+            key += k === 0 ? keyToken(value) : `|${keyToken(value)}`;
+        }
         const first = seen.get(key);
         if (first !== undefined) {
             throw new ValidationError(`createMany onConflict on "${qi.table}": rows ${first} and ${i} share the conflict key ` +
@@ -2101,11 +2128,34 @@ export function assertWritable(qi, operation) {
  * (they're stripped from the statement anyway).
  */
 export function assertNoGeneratedColumns(qi, data, operation) {
-    for (const [key, value] of Object.entries(data)) {
-        if (value === undefined)
+    const generated = generatedStoredColumns(qi);
+    if (generated !== null)
+        assertNoGeneratedKeys(qi, generated, data, operation);
+}
+/**
+ * The table's generated stored columns, or `null` when it has none (most
+ * tables, and then a write checks nothing). Read once per call, so
+ * `createMany` checks every row against one answer: it used to search the
+ * column list, with a `camelToSnake` per comparison, for every field of every
+ * row, which was most of a 150-row upsert's build time.
+ */
+function generatedStoredColumns(qi) {
+    let columns = null;
+    for (const c of qi.tableMeta.columns) {
+        if (!c.isGeneratedStored)
             continue;
-        const col = qi.tableMeta.columns.find((c) => c.field === key || c.name === key || c.name === camelToSnake(key));
-        if (col?.isGeneratedStored) {
+        columns ??= new Set();
+        columns.add(c.name);
+    }
+    return columns;
+}
+/** Refuse a key of `data` that names one of `generated` (by THE key rule, {@link resolveColumnName}). */
+function assertNoGeneratedKeys(qi, generated, data, operation) {
+    for (const key in data) {
+        if (!Object.hasOwn(data, key) || data[key] === undefined)
+            continue;
+        const column = resolveColumnName(qi.tableMeta, key);
+        if (column !== undefined && generated.has(column)) {
             throw new ValidationError(`Cannot ${operation} "${qi.table}": column "${key}" is a GENERATED ALWAYS AS (…) STORED ` +
                 'column whose value the database computes, remove it from your data.');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.90.1",
+  "version": "0.90.2-next.91484a2",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",