turbine-orm 0.70.0 → 0.71.0

package/dist/cjs/connection-url.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * Connection-string inspection: pooler detection, and connection-time GUCs.
+ *
+ * A pure leaf. It imports nothing (not even `pg`), so every consumer, the CLI,
+ * the statistics collectors, and the tests, reads the same rules without
+ * dragging a driver in.
+ *
+ * ## Why this file exists
+ *
+ * A **transaction-pooling** proxy (PgBouncer, a Neon `-pooler` endpoint,
+ * Supabase's pooler) does not give a client its own server backend. It
+ * multiplexes many clients onto a few shared backends and hands a backend back
+ * to the pool at the end of each TRANSACTION, without running `DISCARD ALL`.
+ * Two consequences drive everything below:
+ *
+ *   1. A session-level `SET` issued outside an explicit transaction attaches to
+ *      whichever shared backend served that statement, and stays there for the
+ *      next client that gets it. A `SET statement_timeout` meant to bound one
+ *      tool's own reads becomes a setting imposed on an application's queries.
+ *      This is a production-incident class, not a theoretical one.
+ *   2. Session-scoped catalogs (`pg_prepared_statements` above all) describe
+ *      whichever backend answered, which through a pooler is not "your" session
+ *      in any useful sense.
+ *
+ * So there are two jobs here. {@link withStatementTimeoutOption} removes the
+ * need for the `SET` in (1) by moving the GUC into the connection's startup
+ * parameters, the same mechanism `TurbineClient` uses for `plan_cache_mode`.
+ * {@link detectPooler} lets a command that depends on session semantics refuse
+ * the endpoint outright rather than degrade silently.
+ *
+ * NEITHER is a substitute for the other. The connection parameter is what makes
+ * the collectors safe for any caller; the refusal is what keeps a diagnostic
+ * command from reporting confidently about a connection it cannot reason about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POOLER_PORTS = exports.POOLER_HOST_TOKENS = void 0;
+exports.parseConnectionTarget = parseConnectionTarget;
+exports.detectPooler = detectPooler;
+exports.poolerRefusalMessage = poolerRefusalMessage;
+exports.withStatementTimeoutOption = withStatementTimeoutOption;
+/**
+ * Host and port from a connection string, in either shape libpq accepts.
+ *
+ * URL form (`postgres://user:pw@host:5432/db`) goes through `URL`; the
+ * key/value DSN form (`host=db.example.com port=6543 dbname=app`) falls back to
+ * a scan. An unparseable string yields `{ host: null, port: null }`, which every
+ * caller here treats as "no evidence", never as "safe".
+ */
+function parseConnectionTarget(connectionString) {
+    const trimmed = connectionString.trim();
+    if (trimmed === '')
+        return { host: null, port: null };
+    try {
+        const url = new URL(trimmed);
+        // A `postgresql:///db?host=/var/run/postgresql` unix socket parses with an
+        // empty hostname. Report it as absent rather than as the empty string.
+        const host = url.hostname === '' ? null : url.hostname.toLowerCase();
+        const port = url.port === '' ? null : Number.parseInt(url.port, 10);
+        return { host, port: port !== null && Number.isInteger(port) ? port : null };
+    }
+    catch {
+        // Not a URL: try the key/value DSN form. Unquoted values only, which is
+        // what a host or a port is in practice.
+        const hostMatch = /(?:^|\s)host\s*=\s*([^\s'"]+)/i.exec(trimmed);
+        const portMatch = /(?:^|\s)port\s*=\s*(\d+)/i.exec(trimmed);
+        const host = hostMatch?.[1]?.toLowerCase() ?? null;
+        const port = portMatch?.[1] !== undefined ? Number.parseInt(portMatch[1], 10) : null;
+        return { host: host === '' ? null : host, port: port !== null && Number.isInteger(port) ? port : null };
+    }
+}
+// ---------------------------------------------------------------------------
+// Pooler detection
+// ---------------------------------------------------------------------------
+/**
+ * Hostname tokens that name a pooler.
+ *
+ * Matched as whole dot/dash/underscore-delimited TOKENS (with an optional
+ * trailing instance number), never as substrings of the connection string.
+ * Substring matching is what makes this class of check untrustworthy: a
+ * database named `poolers`, a role named `pooler_admin`, or a host called
+ * `spooler.internal` all contain the letters and none of them is a pooler, and
+ * a detector that cries wolf gets disabled by the first person it blocks.
+ */
+exports.POOLER_HOST_TOKENS = Object.freeze(['pooler', 'pgbouncer']);
+/**
+ * Ports that name a pooler on their own.
+ *
+ * 6543 is the transaction-pooling port of the hosted poolers people point a CLI
+ * at. 6432 is PgBouncer's own documented default `listen_port`, so anyone who
+ * ran PgBouncer without changing it is here.
+ *
+ * The counter-argument to 6432 is that it refuses someone running plain
+ * Postgres on a non-standard port. That is true and it is the right trade,
+ * because the two errors do not cost the same: a false positive costs one
+ * `--allow-pooler` flag on a command the user is running interactively and
+ * reading the output of, while a false negative is silently the exact hazard
+ * this gate exists to prevent. When a detector's errors are asymmetric, tune it
+ * toward the cheap one.
+ */
+exports.POOLER_PORTS = Object.freeze([6543, 6432]);
+/** The "nothing detected" result, so callers never build one by hand. */
+function noPooler(target) {
+    return { pooled: false, signal: null, host: target.host, port: target.port, matchedToken: null, directHost: null };
+}
+/**
+ * Whether a connection string points at a transaction-pooling proxy.
+ *
+ * Deliberately conservative: it answers from the endpoint's SHAPE (hostname
+ * tokens, port), because there is no way to ask a pooler what it is without
+ * connecting through it, and the whole point is to decide before connecting.
+ * A false negative leaves the caller where it already was; a false positive
+ * blocks a legitimate database, so precision wins and the caller is expected to
+ * offer an override.
+ */
+function detectPooler(connectionString) {
+    const target = parseConnectionTarget(connectionString);
+    if (target.host !== null) {
+        for (const label of target.host.split('.')) {
+            for (const token of label.split(/[-_]/)) {
+                // `pooler`, `pgbouncer`, and numbered instances of either (`pooler2`).
+                const base = /^([a-z]+)\d*$/.exec(token)?.[1] ?? token;
+                if (exports.POOLER_HOST_TOKENS.includes(base)) {
+                    return {
+                        pooled: true,
+                        signal: 'host',
+                        host: target.host,
+                        port: target.port,
+                        matchedToken: token,
+                        directHost: deriveDirectHost(target.host, token),
+                    };
+                }
+            }
+        }
+    }
+    if (target.port !== null && exports.POOLER_PORTS.includes(target.port)) {
+        return {
+            pooled: true,
+            signal: 'port',
+            host: target.host,
+            port: target.port,
+            matchedToken: null,
+            directHost: null,
+        };
+    }
+    return noPooler(target);
+}
+/**
+ * `host` with an in-label `-<token>` pooler suffix removed, or `null`.
+ *
+ * Only the suffix form is derivable, see {@link PoolerDetection.directHost}.
+ */
+function deriveDirectHost(host, token) {
+    const labels = host.split('.');
+    let changed = false;
+    const rewritten = labels.map((label) => {
+        if (changed)
+            return label;
+        // The token must be a trailing segment of a MULTI-segment label, so
+        // `pooler.supabase.com` (a whole label) is not rewritten.
+        const suffix = `-${token}`;
+        if (label.length > suffix.length && label.endsWith(suffix)) {
+            changed = true;
+            return label.slice(0, -suffix.length);
+        }
+        return label;
+    });
+    return changed ? rewritten.join('.') : null;
+}
+/**
+ * The lines a command prints when it refuses a pooler endpoint.
+ *
+ * Plain text, no colour and no `console` call, so it is assertable in a unit
+ * test and reusable by any command that grows the same gate.
+ */
+function poolerRefusalMessage(detection, options) {
+    const what = detection.signal === 'port'
+        ? `port ${detection.port} is a transaction-pooling port`
+        : `the hostname contains "${detection.matchedToken}"`;
+    const where = detection.host ?? '(host not stated)';
+    const lines = [
+        `${options.command} refuses to run through a connection pooler.`,
+        '',
+        `  Endpoint: ${where}${detection.port === null ? '' : `:${detection.port}`}`,
+        `  Detected: ${what}`,
+        '',
+        'A transaction pooler (PgBouncer, a Neon "-pooler" endpoint, Supabase\'s pooler) does not',
+        'give a client its own server backend. It multiplexes many clients onto a few shared',
+        'backends and reuses one as soon as a transaction ends, so:',
+        '',
+        '  1. Session state is not private. Anything this command sets on the session can be left',
+        '     behind for another client, and whatever an earlier client left behind can be in',
+        '     force for this one. That is how a "read-only guardrail" becomes an outage.',
+        '  2. Session-scoped views describe the wrong session. pg_prepared_statements, which this',
+        '     report tells you to read to confirm a cached plan, belongs to whichever backend',
+        '     answered, not to your application.',
+        '  3. The read bounds may not apply. This command asks for its statement_timeout as a',
+        '     connection parameter, and a pooler is free to drop or reject one.',
+        '',
+        'Use the DIRECT (non-pooled) endpoint for the same database instead.',
+    ];
+    if (detection.directHost !== null) {
+        lines.push('', `  ${detection.host}`, `  -> ${detection.directHost}`);
+        lines.push('', 'That is the same connection string with the pooler marker removed from the host.');
+    }
+    else {
+        lines.push('', 'On a managed provider that is the "direct" or "session" connection string in your', 'dashboard, not the pooled one. Self-hosted, it is the Postgres host itself rather', 'than the proxy in front of it.');
+    }
+    lines.push('', `If you are certain this endpoint is not a transaction pooler, re-run with ${options.allowFlag}.`);
+    return lines;
+}
+/**
+ * `config` with `statement_timeout` moved into the connection's **startup
+ * parameters** (`options=-c statement_timeout=<ms>`) instead of a `SET`.
+ *
+ * PostgreSQL applies the `options` startup parameter as the backend starts the
+ * session, so the bound is in force for the connection's very first statement
+ * and for its whole life, with no extra round trip and nothing to reset. The
+ * alternative, `SET statement_timeout = <ms>` on a fresh connection, is what
+ * this exists to remove: outside an explicit transaction it is exactly the
+ * session-state write that a transaction pooler leaves on a shared backend.
+ *
+ * `TurbineClient` uses the same mechanism for `plan_cache_mode`; see the note
+ * there for why a `pool.on('connect')` `SET` is not the alternative it looks
+ * like (it races the caller's first query through pg's deprecated same-client
+ * queueing).
+ *
+ * Nothing already set is discarded, in either place pg reads `options` from.
+ * pg's `ConnectionParameters` lets a value parsed out of the connection string
+ * OVERRIDE the explicit `options` field, so when the URL already carries
+ * `?options=...` the GUC is appended THERE; the explicit field itself falls back
+ * to `process.env.PGOPTIONS` only while unset, so setting it blind would drop a
+ * deployment's `PGOPTIONS`. Both are read first and appended to.
+ *
+ * THE INJECTION BOUNDARY: a GUC value cannot be a bind parameter, so the
+ * emitted text necessarily contains a literal. `statementTimeoutMs` is
+ * therefore narrowed to a non-negative safe INTEGER and rendered from the
+ * narrowed number; anything else (a float, a negative, `NaN`, a string that
+ * coerced) returns the config untouched rather than reaching the wire, because
+ * a value that can carry a space can carry a second `-c`.
+ */
+function withStatementTimeoutOption(config, statementTimeoutMs) {
+    if (!Number.isSafeInteger(statementTimeoutMs) || statementTimeoutMs < 0)
+        return config;
+    // No unit suffix: statement_timeout's default unit IS milliseconds, which is
+    // what `SET statement_timeout = <n>` meant before this replaced it.
+    const setting = `-c statement_timeout=${statementTimeoutMs}`;
+    const merged = mergeConnectionStringOptions(config.connectionString, setting);
+    if (merged !== null)
+        return { ...config, connectionString: merged };
+    const existing = config.options || (typeof process !== 'undefined' ? process.env?.PGOPTIONS : undefined);
+    return { ...config, options: existing ? `${existing} ${setting}` : setting };
+}
+/**
+ * `connectionString` with `setting` appended to an existing `options` query
+ * parameter, or `null` when it carries none (in which case the caller uses the
+ * `options` config field, which the connection string does not override).
+ *
+ * Only the query string is rewritten, never the userinfo or host, so a
+ * percent-encoded password cannot be mangled by a round trip through `URL`. The
+ * split is on the first `?`, which is also where pg's own parser puts the
+ * query-string boundary: a connection string with an unencoded `?` inside the
+ * password is not parseable by pg either, so there is no shape this handles
+ * differently from the driver.
+ *
+ * DELIBERATELY DUPLICATED with `TurbineClient.mergeConnectionStringOptions`,
+ * which needs the identical merge for `plan_cache_mode`. Collapsing the two
+ * onto this copy is the obviously correct refactor and it was tried; it is
+ * reverted, and the reason is worth writing down because the next person will
+ * try it too.
+ *
+ * Exporting it and importing it from `client.ts` adds an import edge from a
+ * module that ~100 test processes load. In each of those processes this file's
+ * top level runs and its functions do not, so c8 merges ~100 top-level-only
+ * entries against the one full entry from `pooler-guard.test.ts`, and the file
+ * reports 40% in the merged report while measuring 100% in isolation. Real
+ * coverage is unchanged either way, but the aggregate gate moved 75.48% ->
+ * 75.03% against a 75% floor, i.e. the refactor spent almost all the headroom
+ * on a reporting artifact.
+ *
+ * So: two copies, both small, both pure, neither reachable from the other. If
+ * you unify them, re-measure `npm run test:coverage` as a whole and not just
+ * this file, and raise the floor's headroom first. Keep this module
+ * import-free regardless.
+ */
+function mergeConnectionStringOptions(connectionString, setting) {
+    const q = connectionString.indexOf('?');
+    if (q === -1)
+        return null;
+    const params = new URLSearchParams(connectionString.slice(q + 1));
+    const existing = params.get('options');
+    if (existing === null)
+        return null;
+    params.set('options', `${existing} ${setting}`);
+    return connectionString.slice(0, q + 1) + params.toString();
+}

package/dist/cjs/index-stats.d.ts

@@ -12,7 +12,10 @@
  *
  * DESIGN: the file splits into two halves.
  *   - The COLLECTOR half (`collectStatsSnapshot`) reads pg catalogs. It uses a
- *     single one-connection pool, sets a statement_timeout, and treats every
+ *     single one-connection pool, bounds every read with a CONNECTION-TIME
+ *     statement_timeout rather than a session-level `SET` (see
+ *     `withStatementTimeoutOption` in connection-url.ts for why that
+ *     distinction is a safety property and not a style choice), and treats every
  *     catalog read as INDIVIDUALLY OPTIONAL: a read that fails (privileges,
  *     CockroachDB/YugabyteDB catalog gaps, missing view) degrades that one
  *     signal and records a notice rather than aborting the whole snapshot.

package/dist/cjs/index-stats.js

@@ -13,7 +13,10 @@
  *
  * DESIGN: the file splits into two halves.
  *   - The COLLECTOR half (`collectStatsSnapshot`) reads pg catalogs. It uses a
- *     single one-connection pool, sets a statement_timeout, and treats every
+ *     single one-connection pool, bounds every read with a CONNECTION-TIME
+ *     statement_timeout rather than a session-level `SET` (see
+ *     `withStatementTimeoutOption` in connection-url.ts for why that
+ *     distinction is a safety property and not a style choice), and treats every
  *     catalog read as INDIVIDUALLY OPTIONAL: a read that fails (privileges,
  *     CockroachDB/YugabyteDB catalog gaps, missing view) degrades that one
  *     signal and records a notice rather than aborting the whole snapshot.
@@ -71,6 +74,7 @@ exports.auditDoctorIndexes = auditDoctorIndexes;
 exports.isSnapshotUsable = isSnapshotUsable;
 exports.collectStatsSnapshot = collectStatsSnapshot;
 exports.collectTableHeat = collectTableHeat;
+const connection_url_js_1 = require("./connection-url.js");
 const index_advisor_js_1 = require("./index-advisor.js");
 // ---------------------------------------------------------------------------
 // Thresholds (exported + printed so a user can see exactly why a tier was chosen)
@@ -563,7 +567,20 @@ async function collectStatsSnapshot(options) {
     const notices = [];
     const snapshot = emptyStatsSnapshot(notices);
     const { Pool } = (await Promise.resolve().then(() => __importStar(require('pg')))).default;
-    const pool = new Pool({ connectionString: options.connectionString, max: 1 });
+    // statement_timeout travels as a CONNECTION PARAMETER, never as a `SET`. A
+    // bare `SET` on a fresh connection is a session-state write, and through a
+    // transaction-pooling proxy it attaches to a shared server backend that is
+    // then handed to somebody else's queries. The startup parameter is applied by
+    // the backend as it starts the session, so it bounds this collector's very
+    // first read, costs no round trip, and cannot outlive the connection. Nothing
+    // in the caller's `?options=` or `PGOPTIONS` is discarded; see
+    // withStatementTimeoutOption. (`turbine doctor` also refuses a pooler
+    // endpoint outright, but this collector is callable on its own, so it does
+    // not lean on that.)
+    const pool = new Pool({
+        ...(0, connection_url_js_1.withStatementTimeoutOption)({ connectionString: options.connectionString }, timeout),
+        max: 1,
+    });
     const run = async (label, text, values) => {
         try {
             const res = await pool.query(text, values);
@@ -575,8 +592,6 @@ async function collectStatsSnapshot(options) {
         }
     };
     try {
-        // statement_timeout is best-effort; if it fails the reads still run.
-        await run('statement_timeout', `SET statement_timeout = ${Number(timeout)}`);
         // --- stats_reset / age --------------------------------------------------
         const resetRows = await run('pg_stat_database.stats_reset', `SELECT stats_reset FROM pg_stat_database WHERE datname = current_database()`);
         if (resetRows && resetRows.length > 0) {
@@ -765,14 +780,15 @@ async function collectTableHeat(options) {
         return result;
     }
     const { Pool } = (await Promise.resolve().then(() => __importStar(require('pg')))).default;
-    const pool = new Pool({ connectionString: options.connectionString, max: 1 });
+    // As in collectStatsSnapshot: the bound is a connection parameter, not a
+    // `SET`. This collector points at whatever `--metrics-url` names, which is
+    // frequently a shared observability database, so leaving session state on a
+    // pooled backend there is if anything the worse version of the same bug.
+    const pool = new Pool({
+        ...(0, connection_url_js_1.withStatementTimeoutOption)({ connectionString: options.connectionString }, timeout),
+        max: 1,
+    });
     try {
-        try {
-            await pool.query(`SET statement_timeout = ${Number(timeout)}`);
-        }
-        catch {
-            /* best-effort */
-        }
         const exists = await pool
             .query(`SELECT to_regclass('_turbine_metrics')::text AS reg`)
             .then((r) => r.rows[0]?.reg ?? null)

package/dist/cjs/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 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 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 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/cjs/plan-flip-probe.js

@@ -264,11 +264,27 @@ async function probePlanFlips(options) {
     const client = new Client({ connectionString: options.connectionString });
     try {
         await client.connect();
-        await client.query(`SET statement_timeout = ${Number(options.statementTimeoutMs ?? 5000)}`);
         // READ ONLY is belt-and-braces: EXPLAIN without ANALYZE cannot write, and the
         // transaction is rolled back regardless. It costs nothing and makes the
         // read-only intent checkable from a server-side log.
         await client.query('BEGIN READ ONLY');
+        // statement_timeout is set INSIDE the transaction and transaction-locally.
+        // It used to be a session-level `SET` on the fresh connection, one statement
+        // earlier, and a dedicated `Client` does not make that safe: through a
+        // transaction-pooling proxy a bare `SET` outside a transaction attaches to a
+        // SHARED server backend, which the pooler then hands to another client
+        // without a DISCARD. Every statement this pass runs is inside this
+        // transaction, so a transaction-local bound covers exactly the same ground
+        // and provably cannot outlive the ROLLBACK below.
+        //
+        // `set_config(name, value, is_local => true)` rather than `SET LOCAL`:
+        // Postgres rejects a bind parameter in `SET LOCAL` (`SET LOCAL x = $1` is a
+        // syntax error), so this is the parameterizable form of the same thing. The
+        // value carries no unit because statement_timeout's default unit is
+        // milliseconds, which is what the previous statement meant.
+        await client.query(`SELECT set_config('statement_timeout', $1, true)`, [
+            String(Number(options.statementTimeoutMs ?? 5000)),
+        ]);
         result.available = true;
         for (let i = 0; i < targets.length; i++) {
             const finding = targets[i];

package/dist/cjs/powql.d.ts

@@ -821,6 +821,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     /** Resolve a groupBy order direction, refusing `nulls: 'first'` (E017); `nulls: 'last'` is a no-op. */
     private groupOrderDir;
     findManyStream(): AsyncGenerator<T>;
+    findManyStreamBatches(): AsyncGenerator<T[]>;
     /** Reselect a single row by its single-column primary key value. */
     private reselectByPk;
     /**

package/dist/cjs/powql.js

@@ -3178,6 +3178,15 @@ class PowqlInterface {
     async *findManyStream() {
         throw new errors_js_1.UnsupportedFeatureError('cursor streaming (findManyStream)', 'PowDB', 'PowDB has no server-side cursor; page with findMany({ limit, offset }) instead');
     }
+    // The batch-yielding sibling needs its OWN stub. `PowqlInterface` is a
+    // parallel implementation of QueryInterface's surface rather than a subclass,
+    // so a method that exists on one and not the other is not a type error here:
+    // it is `undefined` at runtime, and the caller gets `TypeError: not a
+    // function` instead of the typed E017 that tells them what to do instead.
+    // biome-ignore lint/correctness/useYield: intentionally throws before yielding, PowDB has no server cursor.
+    async *findManyStreamBatches() {
+        throw new errors_js_1.UnsupportedFeatureError('cursor streaming (findManyStreamBatches)', 'PowDB', 'PowDB has no server-side cursor; page with findMany({ limit, offset }) instead');
+    }
     // -------------------------------------------------------------------------
     // Reselect helper (upsert only, PowDB's upsert has no `returning`)
     // -------------------------------------------------------------------------

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

@@ -266,8 +266,31 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * is derived. See {@link autoToOneThreshold}.
      */
     private readonly autoRoundTripMs;
-    /** Nested-relation JSON encoding: 'object' (default) or 'positional'. */
+    /**
+     * The CLIENT-level nested-relation JSON encoding: what a query that names no
+     * `jsonEncoding` of its own gets. `'positional'` on PostgreSQL, `'object'`
+     * everywhere else (see {@link defaultJsonEncoding}).
+     *
+     * Read through {@link QueryInterface.currentJsonEncoding}, never directly, so
+     * a per-query override cannot be missed by one reader.
+     */
     private readonly jsonEncoding;
+    /**
+     * The encoding the query BEING BUILT resolved to, i.e. its own
+     * `jsonEncoding` or {@link QueryInterface.jsonEncoding}.
+     *
+     * Reassigned per `build*` call and exposed on the {@link BuilderCtx} as a live
+     * getter, exactly like {@link QueryInterface.currentSkip} and for the same
+     * reason: relations.ts reads the encoding from four places deep inside the
+     * SELECT walk, and threading it through every one of them as a parameter
+     * would be four chances to forget it.
+     *
+     * Safe because a build is SYNCHRONOUS from the assignment to the last read:
+     * `buildFindMany` / `buildFindUnique` return a fully-formed DeferredQuery
+     * whose parser closure already captured the shapes, so nothing reads this
+     * field after the build returns and no two builds can interleave on it.
+     */
+    private currentJsonEncoding;
     /**
      * `parseRow` decode plans, keyed by table plus the exact column list. Bounded
      * like the SQL template cache and for the same reason: the shapes come from
@@ -497,6 +520,24 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * the per-query arg wins, then the client-level default (off).
      */
     private resolveStableOrder;
+    /**
+     * Resolve one query's relation JSON encoding and PIN it for the build, so
+     * every reader inside relations.ts sees the same answer.
+     *
+     * Called at the TOP of each entry point that can emit or decode relation JSON
+     * (`buildFindMany`, `buildFindUnique`, `makeStreamRowParser`), before the
+     * cache key is assembled and before the flatten plan is consulted, because
+     * both of those depend on the answer.
+     *
+     * An unrecognized value THROWS (E003) rather than falling back. A per-query
+     * option that is silently ignored when misspelled is the exact failure this
+     * package has been bitten by before (see query/option-surface.ts), and here it
+     * would be invisible: the wrong encoding still returns correct rows, just
+     * without the saving the caller asked for, or with the flatten plan they were
+     * trying to re-enable still refused. Thrown before the SQL cache is consulted
+     * so a warm template can never serve a call the cold path would refuse.
+     */
+    private resolveJsonEncoding;
     /**
      * Fill a PK-ascending `orderBy` into every to-many `with` relation that has no
      * explicit one, recursing into nested `with`. Returns a CLONED clause (user
@@ -999,10 +1040,87 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private measureWithDepth;
     buildFindMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O>[]>;
+    /**
+     * Build the one row parser a whole drain uses.
+     *
+     * Shared by {@link findManyStream} and {@link findManyStreamBatches} so the
+     * two can never disagree about a row's SHAPE while agreeing about its
+     * contents: the flatten plan, the positional/object relation decode and the
+     * PII projection are all decided here, once, before a statement is issued.
+     *
+     * The plan is a pure function of the schema, the `with` shape and
+     * `includePii`, never of `limit`, so the batch-size override the speculative
+     * fetch applies cannot change it and the parser always matches the emitted
+     * SQL. Reading the raw `includePii` sentinel with `=== true` here would have
+     * quietly planned a no-PII parser over a with-PII statement, which is why it
+     * goes through `resolveUnsafeFlag` on every path, `with` clause or not.
+     */
+    private makeStreamRowParser;
+    /**
+     * Everything a stream does to the DATABASE, and nothing it does to a row.
+     *
+     * {@link findManyStream} and {@link findManyStreamBatches} are the same drain
+     * handed out at two granularities, so the statement they issue, when the
+     * cursor opens, and how the connection is released all live here once. Only
+     * the yielding differs, which is the entire point of having both.
+     *
+     * Parsing deliberately stays in the callers: they parse at different
+     * granularities, and the per-row method must keep parsing LAZILY, one row at
+     * a time, exactly as it always has. Hoisting the parse in here would make a
+     * consumer that breaks after the first row pay for the rest of its batch.
+     *
+     * `action` is the tag query events carry. It is a parameter rather than a
+     * constant so each public method reports its own name instead of the name of
+     * whichever one happens to be implemented over the other.
+     *
+     * An EMPTY batch is never yielded: the dialect's cursor loop breaks on a
+     * zero-row FETCH, and the speculative path below yields nothing at all when
+     * the result set is empty. Callers may therefore treat a yielded batch as
+     * non-empty.
+     */
+    private streamRaw;
+    /**
+     * Stream rows from a findMany query using PostgreSQL cursors, one BATCH of
+     * rows at a time.
+     *
+     * The same drain {@link findManyStream} performs, the same statements, the
+     * same cursor, the same rows in the same order, handed out as arrays instead
+     * of one row at a time. That is worth having because the per-row form costs
+     * one promise resolution and one microtask turn PER ROW: measured over 50,000
+     * rows on a local PostgreSQL, per-row yielding costs ~7 ms (~140 ns/row) that
+     * batch yielding does not, which is roughly half of the streaming overhead
+     * over a hand-written cursor loop. Nothing else about the two paths differs,
+     * so the entire saving is the yielding.
+     *
+     * Prefer this whenever the consumer can work on an array; keep
+     * {@link findManyStream} when a row at a time is what the code actually wants,
+     * since flattening a batch by hand costs exactly what it saves.
+     *
+     * A yielded batch is never empty, and its length is NOT a contract: it is at
+     * most `batchSize`, the final batch is usually shorter, and a result set that
+     * fits within one batch arrives as a single array from the speculative fetch
+     * with no cursor involved. Do not use batch boundaries to infer anything
+     * about the data.
+     *
+     * Every other streaming behaviour is shared and documented on
+     * {@link findManyStream}: the speculative fast path, the cursor path and its
+     * cleanup, the snapshot semantics, and early `break`.
+     *
+     * @example
+     * ```ts
+     * for await (const batch of db.users.findManyStreamBatches({ where: { orgId: 1 }, batchSize: 500 })) {
+     *   await sink.writeAll(batch);
+     * }
+     * ```
+     */
+    findManyStreamBatches<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyStreamArgs<T, R, W, S, O>): AsyncGenerator<QueryResult<T, R, W, S, O>[], void, undefined>;
     /**
      * Stream rows from a findMany query using PostgreSQL cursors.
      * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
      *
+     * See {@link findManyStreamBatches} for the same drain yielded a batch at a
+     * time, which is measurably cheaper when the consumer can take an array.
+     *
      * **Speculative fast-path:** Before opening a cursor, issues a single
      * `SELECT ... LIMIT batchSize+1`. If the result fits within `batchSize`,
      * all rows are yielded immediately with zero cursor overhead (no BEGIN /
@@ -1118,7 +1236,11 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * strategy, silently and byte-identically):
      *   - the resolved strategy is not `'flatten'`;
      *   - `jsonEncoding: 'positional'` (a flattened relation emits no JSON at all,
-     *     so the two encodings are not composed in this version);
+     *     so the two are not composed in this version). NOTE that this is the
+     *     PostgreSQL DEFAULT, so on Postgres `'flatten'` engages only when the
+     *     caller ALSO passes `jsonEncoding: 'object'`. The fallback is silent and
+     *     byte-identical, and `warnFlattenBlocked` names the encoding and the
+     *     escape hatch in dev;
      *   - the dialect owns relation-subquery generation
      *     (`dialect.buildRelationSubquery`, i.e. SQL Server's `FOR JSON PATH`);
      *   - `distinct` (the `DISTINCT ON` rewrite re-orders in an outer wrapper, and
@@ -1255,6 +1377,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Build the decode plan for one exact column list, and remember it as this
      * table's most recent shape so the next row of the same result set hits the
      * fast path in {@link parseRow}.
+     *
+     * The shape key's delimiter is NUL because it is the one byte a Postgres
+     * identifier cannot contain, even quoted, so no table or column name can
+     * forge a collision. It MUST be written as the six-character escape, never
+     * as a literal NUL byte: a raw NUL makes byte-oriented tools classify this
+     * file as binary, and `grep` then reports ZERO matches for a term that is
+     * present rather than saying it declined to look. This is the largest file
+     * in the repo, and that silent empty result has already sent more than one
+     * search down the wrong path.
      */
     private buildRowDecodePlan;
     /**