turbine-orm 0.55.0 → 0.56.0

package/dist/cjs/query/builder.js

@@ -1388,11 +1388,11 @@ class QueryInterface {
             const deferred = single
                 ? this.buildFindUnique(baseArgs)
                 : this.buildFindMany(baseArgs);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             const rows = deferred.transform(result);
             const entities = single ? (rows ? [rows] : []) : rows;
             if (entities.length > 0) {
-                await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii === true), entities, batchedWith, args.timeout);
+                await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii === true, args.forceCustomPlan === true), entities, batchedWith, args.timeout);
             }
             (0, batched_loader_js_1.stripFields)(entities, proj.strip);
             return single ? (entities[0] ?? null) : entities;
@@ -1408,7 +1408,7 @@ class QueryInterface {
      * and unlimited-warnings silenced, a relation load must fetch every matching
      * child, and the per-relation `limit` is applied client-side by the loader.
      */
-    batchedContext(timeout, skip, includePii) {
+    batchedContext(timeout, skip, includePii, forceCustomPlan = false) {
         const childOptions = {
             ...this.options,
             defaultLimit: undefined,
@@ -1418,7 +1418,11 @@ class QueryInterface {
             parentMeta: this.tableMeta,
             schema: this.schema,
             makeChild: (table) => new QueryInterface(this.pool, table, this.schema, [], childOptions),
-            exec: (sql, params, preparedName) => this.queryWithTimeout(sql, params, timeout, preparedName),
+            // The per-query `forceCustomPlan` opt-in covers the relation follow-ups
+            // too: a batched load re-issues the SAME tenant-shaped predicate one
+            // level down, so leaving those named would keep exactly the plan-cache
+            // exposure the caller asked to be rid of.
+            exec: (sql, params, preparedName) => this.queryWithTimeout(sql, params, timeout, this.preparedNameFor({ forceCustomPlan }, preparedName)),
             quote: (name) => this.q(name),
             buildInClause: (expr, paramRef, negated) => this.inClause(expr, paramRef, negated),
             inClauseParam: (values) => this.inParam(values),
@@ -1470,10 +1474,10 @@ class QueryInterface {
         const { baseArgs, strip } = this.prepareBatchedBase(args, withClause);
         // baseArgs.with is always undefined here; the cast just bridges the R generic.
         const deferred = this.buildFindMany(baseArgs);
-        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
         const entities = deferred.transform(result);
         if (entities.length > 0) {
-            await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii === true), entities, withClause, args.timeout);
+            await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, skip, args.includePii === true, args.forceCustomPlan === true), entities, withClause, args.timeout);
         }
         (0, batched_loader_js_1.stripFields)(entities, strip);
         return entities;
@@ -1629,6 +1633,69 @@ class QueryInterface {
             // Listener errors must never crash a query
         }
     }
+    /**
+     * Resolve the prepared-statement name a read should execute under, honouring
+     * the per-query {@link FindManyArgs.forceCustomPlan} opt-in.
+     *
+     * `forceCustomPlan: true` returns `undefined`, which sends the statement
+     * UNNAMED. The mechanism is NOT "PostgreSQL treats an unnamed statement as a
+     * one-shot plan that never enters the plan cache": the backend builds and
+     * saves a `CachedPlanSource` for the unnamed statement too. It works because
+     * node-postgres only skips Parse for a statement it has already parsed BY
+     * NAME (`Query.hasBeenParsed` is `this.name && connection.parsedStatements[this.name]`),
+     * so an unnamed statement is re-Parsed on every execution, each Parse
+     * replaces the unnamed cached plan source with a fresh one whose custom-plan
+     * counter is zero, and the five-execution threshold that precedes promotion
+     * is never reached. Every execution is therefore planned with the real
+     * parameter values.
+     *
+     * No GUC is set, no `SET LOCAL` is emitted, no transaction is opened, and no
+     * extra round trip is added, which is exactly why the opt-in can be per query
+     * while the client-level `planCacheMode` (a connection parameter) cannot be.
+     *
+     * The refusal is deliberately here, at the one seam every read execution
+     * passes through, rather than in each build method: the flag changes NOTHING
+     * about the SQL text, so a build-time check would have had to be repeated in
+     * every builder and could still be bypassed by a hand-executed
+     * `DeferredQuery`.
+     *
+     * Engines whose dialect does not report {@link Dialect.supportsPlanCacheMode}
+     * throw {@link UnsupportedFeatureError} (E017): the flag names a PostgreSQL
+     * plan-cache guarantee, and an engine with no such cache cannot make it.
+     * The same flag left unset (or `false`) is accepted everywhere.
+     *
+     * THE ONE COMBINATION THAT IS REFUSED RATHER THAN HONOURED. A client-level
+     * `planCacheMode: 'force_generic_plan'` DEFEATS this option, and that was
+     * MEASURED rather than reasoned about: on PostgreSQL 16.14, five executions
+     * of one unnamed statement read 19,107 buffers with that setting in force and
+     * 55 buffers with the same connection set back to `auto`, against 19,107 for
+     * the named statement. So the setting governs the unnamed statement too, and
+     * withholding the name buys nothing against it. Accepting the flag there
+     * would report a guarantee the very next execution breaks, so the
+     * contradiction throws {@link ValidationError} (E003) naming both settings.
+     * Turbine can only see the setting IT applied: a `plan_cache_mode` installed
+     * by the caller's own `SET`, by `ALTER ROLE`, or by a pooler is invisible
+     * here and is not refused.
+     */
+    preparedNameFor(args, name) {
+        if (args?.forceCustomPlan !== true)
+            return name;
+        if (this.dialect.supportsPlanCacheMode !== true) {
+            throw new errors_js_1.UnsupportedFeatureError('The forceCustomPlan query option', this.dialect.name, 'Forcing a per-query custom plan means keeping the statement out of the PostgreSQL plan cache, and this ' +
+                'engine has no such cache to keep it out of. Remove the option, or set it only on PostgreSQL queries.');
+        }
+        if (this.options?.planCacheMode === 'force_generic_plan') {
+            throw new errors_js_1.ValidationError('[turbine] forceCustomPlan: true cannot be honoured on a client configured with ' +
+                "planCacheMode: 'force_generic_plan'. That setting is a connection parameter and it governs UNNAMED " +
+                'statements as well as named ones, so the mechanism this option uses (withholding the ' +
+                'prepared-statement name, so the driver re-parses the statement on every execution and it is planned ' +
+                'with its real values) is ' +
+                'overridden by it and the query would be planned generically anyway. Leave the client on the default ' +
+                '(`planCacheMode` unset, or `auto`) and force the custom plan per query: that is the combination that ' +
+                'expresses "custom here, auto there".');
+        }
+        return undefined;
+    }
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
@@ -1777,7 +1844,7 @@ class QueryInterface {
                 }
             }
             const deferred = this.buildFindUnique(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -1798,11 +1865,11 @@ class QueryInterface {
         const proj = (0, batched_loader_js_1.includeKeysForBatching)(args.select, args.omit, needed, (0, batched_loader_js_1.defaultProjectionFields)(this.tableMeta, args.includePii));
         const baseArgs = { ...args, with: undefined, select: proj.select, omit: proj.omit };
         const deferred = this.buildFindUnique(baseArgs);
-        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+        const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
         const entity = deferred.transform(result);
         if (!entity)
             return null;
-        await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii === true), [entity], withClause, args.timeout);
+        await (0, batched_loader_js_1.loadRelationsBatched)(this.batchedContext(args.timeout, args.skipGlobalFilters, args.includePii === true, args.forceCustomPlan === true), [entity], withClause, args.timeout);
         (0, batched_loader_js_1.stripFields)([entity], proj.strip);
         return entity;
     }
@@ -1973,7 +2040,7 @@ class QueryInterface {
                 }
             }
             const deferred = this.buildFindMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2424,7 +2491,13 @@ class QueryInterface {
             limit: batchSize + 1,
         });
         this.currentAction = 'findManyStream';
-        const speculativeResult = await this.queryWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout);
+        // Streaming is ALREADY immune to the generic-plan cliff: the speculative
+        // fetch has never passed a prepared name, and the cursor path runs through
+        // DECLARE, so neither statement enters the plan cache. `preparedNameFor` is
+        // still called with no name so that `forceCustomPlan: true` is VALIDATED on
+        // an engine that cannot honour it here either, rather than being quietly
+        // satisfied by an accident of this code path.
+        const speculativeResult = await this.queryWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout, this.preparedNameFor(args, undefined));
         if (speculativeResult.rows.length <= batchSize) {
             // Small drain, yield all rows and return, no cursor needed
             for (const row of speculativeResult.rows) {
@@ -2487,7 +2560,7 @@ class QueryInterface {
                 }
             }
             const deferred = this.buildFindFirst(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2512,7 +2585,7 @@ class QueryInterface {
     async findFirstOrThrow(args) {
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
             const deferred = this.buildFindFirstOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2542,7 +2615,7 @@ class QueryInterface {
     async findUniqueOrThrow(args) {
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
             const deferred = this.buildFindUniqueOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2727,7 +2800,7 @@ class QueryInterface {
     async count(args) {
         return this.executeWithMiddleware('count', (args ?? {}), async () => {
             const deferred = this.buildCount(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2771,7 +2844,7 @@ class QueryInterface {
     async groupBy(args) {
         return this.executeWithMiddleware('groupBy', args, async () => {
             const deferred = this.buildGroupBy(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }
@@ -2790,7 +2863,7 @@ class QueryInterface {
     async aggregate(args) {
         return this.executeWithMiddleware('aggregate', args, async () => {
             const deferred = this.buildAggregate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
+            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, this.preparedNameFor(args, deferred.preparedName));
             return deferred.transform(result);
         });
     }

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

@@ -127,6 +127,15 @@ export interface QueryInterfaceOptions {
      * (serverless drivers may not support named statements).
      */
     preparedStatements?: boolean;
+    /**
+     * The client-level `plan_cache_mode` this interface's connections were opened
+     * with, forwarded from `TurbineConfig.planCacheMode` purely so the per-query
+     * `forceCustomPlan` option can REFUSE the one combination it cannot honour
+     * (`'force_generic_plan'`, see `preparedNameFor` in builder.ts). Nothing else
+     * reads it, and it is never emitted into SQL: the setting itself travels as a
+     * connection parameter, set by client.ts when it opens the pool.
+     */
+    planCacheMode?: 'auto' | 'force_custom_plan' | 'force_generic_plan';
     /**
      * Enable the SQL template cache. When true, repeated queries with the
      * same shape (same keys, operators, relations, different values) reuse

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

@@ -465,6 +465,8 @@ export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithCla
     skipGlobalFilters?: SkipGlobalFilters;
     /** Include PII-tagged columns in the result. See {@link FindManyArgs.includePii}. */
     includePii?: boolean;
+    /** Plan this query with its real parameter values. See {@link FindManyArgs.forceCustomPlan}. */
+    forceCustomPlan?: boolean;
 }
 export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     /** Row filter. Keys are checked against `T` and `R` (see {@link WhereClause}). */
@@ -518,6 +520,138 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
      * always allowed regardless of this flag (the reference is explicit).
      */
     includePii?: boolean;
+    /**
+     * Plan THIS query with its actual parameter values, every execution.
+     * PostgreSQL only (see the refusal below).
+     *
+     * WHY IT EXISTS. Turbine executes through a NAMED prepared statement, which
+     * enters the backend's plan cache, and from the sixth execution onward
+     * PostgreSQL may replace the per-execution plan with a single GENERIC plan
+     * (whenever the generic plan's estimated cost is not worse than the average
+     * custom cost). A generic plan substitutes a default for every value it
+     * cannot see: an unknown equality gets `rows / n_distinct`, an unknown range
+     * gets a third of the table, an unknown LIKE gets 0.5%, and an unknown LIMIT
+     * gets 10% of its child node's estimate. When one of those defaults lands on
+     * the other side of a plan boundary from the real value, the plan SHAPE
+     * flips, and the flip can be catastrophic. It fails in both directions: a
+     * default above the truth and a default below it are both capable of it, so
+     * "the tenant with few rows" is not the predictor.
+     *
+     * WHAT IT DOES, stated as the mechanism really is rather than as the tempting
+     * one-liner. `true` sends this one statement UNNAMED. It is NOT true that
+     * PostgreSQL treats an unnamed statement as a one-shot plan that never enters
+     * the plan cache: `exec_parse_message` builds a `CachedPlanSource` and calls
+     * `SaveCachedPlan` on it for the unnamed statement too (it is kept in
+     * `unnamed_stmt_psrc`). The reason the option works is one level up, in the
+     * DRIVER: node-postgres only skips Parse for a statement it has already
+     * parsed BY NAME (`Query.hasBeenParsed` is `this.name && ...`), so an unnamed
+     * statement is re-Parsed on every execution. Each Parse replaces the unnamed
+     * entry with a fresh `CachedPlanSource` whose custom-plan counter starts at
+     * zero, so the five-execution threshold that precedes promotion is never
+     * reached and every execution is planned with the real parameter values.
+     *
+     * That distinction matters in practice: the guarantee is a property of the
+     * driver's behaviour plus the backend's promotion rule, not a special
+     * one-shot plan class, which is exactly why a connection pinned to
+     * `force_generic_plan` still overrides it (see PRECEDENCE below).
+     *
+     * Nothing is set on the session, no `SET` is emitted, no transaction is
+     * opened, and no extra round trip is added.
+     *
+     * WHAT IT CANNOT DO, and why this is a boolean rather than the client-level
+     * three-value {@link TurbineConfig.planCacheMode}: the generic direction is
+     * NOT expressible per query. `force_generic_plan` is a property of a CACHED
+     * plan, and the only per-query lever here is keeping the statement out of the
+     * cache, which can only ever mean "custom". A per-query
+     * `planCacheMode: 'force_generic_plan'` would be a promise this mechanism
+     * cannot keep, so the option is named for the one thing it does.
+     *
+     * PRECEDENCE over the client-level `planCacheMode`, which is a connection
+     * parameter and cannot be unset for one query. Stated exactly, because one of
+     * these four is the opposite of what the mechanism suggests:
+     *   - Client on the default (`planCacheMode` unset) or `'auto'`: this is what
+     *     the option is FOR. `auto` is the only mode in which promotion to a
+     *     generic plan happens, and the re-Parse described above resets the
+     *     counter that promotion depends on before it can ever be reached.
+     *   - Client on `'force_custom_plan'`: redundant and harmless, both routes
+     *     plan with the real values.
+     *   - Client on `'force_generic_plan'`: REFUSED, with `ValidationError`
+     *     (E003). It does NOT win. That setting governs the unnamed statement's
+     *     cached plan source as well as a named one (measured on PostgreSQL 16.14: five executions
+     *     of the same unnamed statement read 19,107 buffers under the setting and
+     *     55 with the connection back on `auto`), so withholding the name buys
+     *     nothing against it and the query would be planned generically anyway.
+     *     Rather than report a guarantee it cannot keep, Turbine refuses the
+     *     combination and says which of the two settings to change. Only the
+     *     setting TURBINE applied is visible: a `plan_cache_mode` installed by a
+     *     caller's `SET`, `ALTER ROLE`, or a pooler cannot be seen or refused.
+     *   - `false` / omitted changes nothing. It does not opt back out of a
+     *     client-level setting, it simply leaves that setting in charge.
+     *   - With the client-level `preparedStatements: false`, every statement is
+     *     already unnamed, so this option is a no-op for plan choice.
+     *
+     * COST, and it has two halves.
+     *
+     * The first is planning. The statement is parsed and planned on every
+     * execution instead of once. On a flat read that is in the noise (an unnamed
+     * statement also skips the extra Parse/Describe round trip a named one needs
+     * on its first execution, so it can even come out ahead). It grows with the
+     * size of the statement: a deep `with` tree is a much larger plan, and
+     * re-planning it per execution is a measurable share of a fast query's
+     * latency. Turn it on where a plan flip is the risk, not everywhere.
+     *
+     * The second is the one nobody expects: A CUSTOM PLAN IS NOT ALWAYS THE
+     * BETTER PLAN. There are real shapes where the generic plan's ignorance is
+     * what saves it, and forcing a custom plan forecloses that. Reproduced on
+     * PostgreSQL 16.14, `synchronize_seqscans` off, parallel workers off:
+     *
+     * ```sql
+     * CREATE TABLE ev (id bigserial PRIMARY KEY, tenant_id int NOT NULL, pad text);
+     * -- 320,000 rows over 800 tenants, inserted in RANDOM physical order
+     * INSERT INTO ev (tenant_id, pad)
+     *   SELECT t, repeat('x', 60)
+     *   FROM (SELECT ((g % 800) + 1) AS t FROM generate_series(1, 320000) g
+     *         ORDER BY random()) s
+     *   WHERE t <> 400;
+     * -- then tenant 400's 80,000 rows LAST, so they all sit past everything above
+     * INSERT INTO ev (tenant_id, pad)
+     *   SELECT 400, repeat('x', 60) FROM generate_series(1, 80000) g;
+     * CREATE INDEX ev_tenant_idx ON ev (tenant_id);
+     * ANALYZE ev;   -- relpages 5334, n_distinct 800, correlation 0.004
+     *
+     * PREPARE q(int, int) AS SELECT * FROM ev WHERE tenant_id = $1 LIMIT $2;
+     * -- force_custom_plan : Seq Scan,          Buffers: shared hit=4262
+     * -- force_generic_plan: Bitmap Heap Scan,  Buffers: shared hit=71
+     * ```
+     *
+     * 60x, with no `ORDER BY` anywhere. The custom planner knows tenant 400 is
+     * 20% of the table, so with `LIMIT 20` it prices a sequential scan as
+     * essentially free on the assumption it will stop almost immediately. It is
+     * right about how MANY rows match and wrong about WHERE they are: they are
+     * all at the end of the heap, so it reads 319,600 non-matching rows first.
+     * The generic plan, unable to see the value, estimates 500 rows, takes the
+     * bitmap path, and touches one heap block. Re-insert the identical rows in
+     * random physical order and the effect vanishes and reverses (custom 2
+     * buffers, generic 66): physical CLUSTERING is the variable, not selectivity.
+     *
+     * Read that carefully before treating it as an argument against this option.
+     * On that shape `plan_cache_mode = auto` never promotes (the generic plan's
+     * ESTIMATED cost is far higher than the average custom cost, which is exactly
+     * the condition under which `auto` refuses), so the default already produces
+     * the 4,262-buffer plan and `forceCustomPlan` costs nothing against it. The
+     * honest statement is that a generic plan is 60x better there than either the
+     * default or this option, and only an explicit client-level
+     * `planCacheMode: 'force_generic_plan'` can reach it. The reason to scope
+     * this option per query is still real: it is a targeted remedy for a measured
+     * flip, not a setting to turn on globally.
+     *
+     * NON-POSTGRESQL ENGINES. `true` throws {@link UnsupportedFeatureError}
+     * (E017), the same refusal the client-level option gives: an engine with no
+     * PostgreSQL plan cache has no cached generic plan to keep this query out of,
+     * so silently accepting the flag would report a guarantee that was never
+     * made. Omitting it (or `false`) is accepted everywhere.
+     */
+    forceCustomPlan?: boolean;
 }
 export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> extends FindManyArgs<T, R, W, S, O> {
     /**
@@ -716,6 +850,8 @@ export interface CountArgs<T, R extends object = {}> {
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
+    /** Plan this query with its real parameter values. See {@link FindManyArgs.forceCustomPlan}. */
+    forceCustomPlan?: boolean;
 }
 /**
  * Comparison operators usable inside a `having` aggregate filter. A bare value
@@ -955,6 +1091,8 @@ export interface GroupByArgs<T, R extends object = {}> {
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
+    /** Plan this query with its real parameter values. See {@link FindManyArgs.forceCustomPlan}. */
+    forceCustomPlan?: boolean;
 }
 /** The by-key union of a groupBy args type (array element type of `by`). */
 type GroupByKeys<A> = A extends {
@@ -1055,6 +1193,8 @@ export interface AggregateArgs<T, R extends object = {}> {
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
     skipGlobalFilters?: SkipGlobalFilters;
+    /** Plan this query with its real parameter values. See {@link FindManyArgs.forceCustomPlan}. */
+    forceCustomPlan?: boolean;
 }
 /** Result type for aggregate queries */
 export interface AggregateResult<T> {

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

@@ -319,6 +319,20 @@ export declare function isDefaultTextParser(oid: number, parser: (text: string)
  * the origin of, and the resulting bug is order-dependent: which reading wins
  * depends on module evaluation order, which lazy route imports make unstable
  * between requests. So say it out loud, once.
+ *
+ * NOT DEV-ONLY. It used to go quiet under `NODE_ENV=production`, along with
+ * every other dev warning, and that was the wrong rule for THIS one, for the
+ * same reason the temporal-infinity warning (builder.ts `warnTemporalInfinity`)
+ * is not dev-only either. A parser overwrite is ORDER-DEPENDENT: which module
+ * calls `setTypeParser` last decides the reading, and evaluation order is
+ * exactly what differs between a dev process (eager imports, one route
+ * exercised at a time) and a production one (bundled or lazily imported routes,
+ * warmed in whatever order traffic arrives). So a process can be clean in dev
+ * and wrong in production purely from import order, which makes production the
+ * case that matters MOST, and it was the case that was silent. The cost is
+ * bounded to the point of irrelevance: once per OID per process, at client
+ * construction, and only when somebody else's non-default parser is actually
+ * being replaced.
  */
 export declare function warnParserOverwrite(oid: number, typeName: string): void;
 /**

package/dist/cjs/query/utils.js

@@ -598,10 +598,22 @@ function isDefaultTextParser(oid, parser) {
  * the origin of, and the resulting bug is order-dependent: which reading wins
  * depends on module evaluation order, which lazy route imports make unstable
  * between requests. So say it out loud, once.
+ *
+ * NOT DEV-ONLY. It used to go quiet under `NODE_ENV=production`, along with
+ * every other dev warning, and that was the wrong rule for THIS one, for the
+ * same reason the temporal-infinity warning (builder.ts `warnTemporalInfinity`)
+ * is not dev-only either. A parser overwrite is ORDER-DEPENDENT: which module
+ * calls `setTypeParser` last decides the reading, and evaluation order is
+ * exactly what differs between a dev process (eager imports, one route
+ * exercised at a time) and a production one (bundled or lazily imported routes,
+ * warmed in whatever order traffic arrives). So a process can be clean in dev
+ * and wrong in production purely from import order, which makes production the
+ * case that matters MOST, and it was the case that was silent. The cost is
+ * bounded to the point of irrelevance: once per OID per process, at client
+ * construction, and only when somebody else's non-default parser is actually
+ * being replaced.
  */
 function warnParserOverwrite(oid, typeName) {
-    if (process.env.NODE_ENV === 'production')
-        return;
     const getParser = pg_1.default.types.getTypeParser;
     const current = getParser(oid, 'text');
     // Turbine's own earlier registration is not a third party's expectation.
@@ -621,7 +633,9 @@ function warnParserOverwrite(oid, typeName) {
         'process, and Turbine is replacing it. `pg.types.setTypeParser` is process-global and takes effect ' +
         'immediately for EVERY pg.Pool in the process, including pools that already exist and are already ' +
         'querying, so whatever set that parser will now read this column differently. If yours should win, ' +
-        `register it AFTER constructing the client.${remedy} Dev-only: silent under \`NODE_ENV=production\`.`);
+        `register it AFTER constructing the client.${remedy} This warning fires under \`NODE_ENV=production\` ` +
+        'too: which parser wins depends on module evaluation order, so a process can be clean in dev and wrong ' +
+        'in production from import order alone.');
 }
 /**
  * Register the UTC readings of the four zone-less temporal OIDs on the pg

package/dist/cli/index.d.ts

@@ -14,7 +14,7 @@
  *   turbine migrate status       , Show migration status
  *   turbine seed                 , Run seed file
  *   turbine status               , Show schema summary
- *   turbine doctor                - Cost-aware missing-FK-index triage (--fix, --json, --no-concurrently, --unused, --audit)
+ *   turbine doctor                - Index + cached-plan triage (--fix, --json, --no-concurrently, --unused, --audit, --no-plan-divergence)
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
  *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
@@ -61,6 +61,8 @@ export interface CliArgs {
     minScans?: number;
     /** `doctor --metrics-url <url>`: read _turbine_metrics for the table-heat boost from a separate DB. */
     metricsUrl?: string;
+    /** `doctor --no-plan-divergence`: skip the cached-plan divergence section (and its pg_stats read). */
+    noPlanDivergence?: boolean;
     /** `init --yes`/`-y`: accept every step's default non-interactively. */
     yes?: boolean;
     /** `init --skip-schema`: don't scaffold the schema file. */