turbine-orm 0.55.0 → 0.56.0

package/dist/plan-divergence.js

@@ -0,0 +1,438 @@
+/**
+ * Plan-divergence advisor, the third question doctor asks about a probe column.
+ *
+ * `index-advisor.ts` answers "which relation probes have no index" from pure
+ * topology. `index-stats.ts` answers "is adding that index worth it" from live
+ * statistics. This module answers the third question on the SAME columns: "this
+ * column IS indexed, and its value distribution makes a NAMED prepared
+ * statement's generic plan unsafe".
+ *
+ * THE MECHANISM. Postgres may promote a named prepared statement to a GENERIC
+ * plan from its sixth execution onward, and ONLY when the generic plan's
+ * estimated cost is not worse than the average custom cost. A generic plan
+ * cannot see any parameter value, so it substitutes a default for each one:
+ *
+ *   - an unknown equality `col = $1` is estimated as reltuples / n_distinct;
+ *   - an unknown `LIMIT $n` is estimated as 10% of the CHILD node's row estimate.
+ *
+ * THE ONE SHAPE THIS MODELS, stated narrowly on purpose. A read shaped
+ * `WHERE col = $1 ORDER BY <other indexed column> LIMIT $n`, where the generic
+ * estimate for `col = $1` sits ABOVE the plan boundary (so the generic plan
+ * keeps the ordered index scan and filters) while some real values sit far
+ * BELOW it (so for those values the ordered scan has to walk a large fraction
+ * of the table before it accumulates one page of matches, where the custom
+ * plan takes a bitmap scan over the value's own rows and sorts them).
+ *
+ * WHAT THIS DELIBERATELY DOES NOT MODEL, because it was tried and it did not
+ * work. An earlier revision carried a second rule for the opposite direction (a
+ * physically clustered column whose densest value is far ABOVE the generic
+ * estimate). Measured against live fixtures it was wrong more often than right,
+ * and twice it was wrong with the SIGN INVERTED: it predicted "at least 16,032x"
+ * and "at least 2,675x" on columns where the generic plan was in fact 10x and
+ * 105x BETTER than the custom one, so acting on the finding would have made
+ * those reads dramatically slower. The reason is structural, not a bad constant:
+ * whether that flip helps or hurts turns on WHERE in the heap the value's rows
+ * physically sit, and no pg_stats input carries that. `correlation` is a
+ * whole-column property and is identical whether the dominant band is at the
+ * head of the heap or its tail. The rule was removed rather than retuned.
+ *
+ * The same blind spot bounds what remains: this check can see how MANY rows a
+ * value has, not WHERE they are, so it under-reports (a rare value packed at the
+ * end of the heap is worse than modelled) and it cannot see the third-party
+ * shapes where a generic plan is the better one. A clean report is not evidence
+ * of immunity.
+ *
+ * EXPOSURE IS NOT AN INCIDENT. A finding says the DISTRIBUTION admits a
+ * damaging flip. It does NOT say the backend is choosing the bad plan today:
+ * `auto` promotes only when the generic plan's ESTIMATED cost is not worse than
+ * the average custom cost, and on a shape whose generic plan is estimated
+ * expensive it never promotes at all. That is why every finding ships a
+ * diagnostic that checks `pg_prepared_statements.generic_plans` BEFORE it
+ * compares the two plans: the counter is the only thing that establishes real
+ * exposure.
+ *
+ * TWO UNITS, and mixing them up is what made the removed rule wrong. The
+ * PLANNER costs the boundary in PAGES (an ordered index scan reads about
+ * limit / matching of the table's pages before it fills the limit), which is why
+ * {@link crossoverRows} is derived from relpages and why measured flip points
+ * track it. The DAMAGE a user feels is also read in pages here, deliberately
+ * conservatively; when the ordering index is not correlated with heap order,
+ * each row examined is a separate block access and the true buffer count is
+ * larger, sometimes by an order of magnitude.
+ *
+ * FRESHNESS GATE. The cost-tier half of doctor gates on `stats_reset` age,
+ * because it normalizes WRITE COUNTERS by it. Nothing here reads a counter: every
+ * input comes from pg_stats, which is refreshed by ANALYZE. This check therefore
+ * gates on ANALYZE freshness instead (a column with no pg_stats row, or an
+ * n_distinct of 0, is suppressed with a notice, and every finding carries the
+ * table's last_analyze). Reusing the counter gate would have silenced the check
+ * on every cluster whose `pg_stat_database.stats_reset` is NULL, which is the
+ * default state and has nothing to do with whether ANALYZE has ever run.
+ *
+ * Postgres-only (pg_stats + plan_cache_mode). Pure: no pg import, no EXPLAIN.
+ */
+import { EXPRESSION_COLUMN } from './index-stats.js';
+import { quoteIdent } from './query/utils.js';
+// ---------------------------------------------------------------------------
+// Thresholds
+// ---------------------------------------------------------------------------
+/**
+ * Gates behind a plan-divergence finding. Exported and printed with every
+ * finding so the reasoning is never a black box.
+ *
+ * Each one is either derived from the cost model and then checked against
+ * measurement, or fitted to a measured flip boundary; the comments record which.
+ */
+export const PLAN_DIVERGENCE_THRESHOLDS = {
+    /**
+     * The LIMIT the advisor assumes, because it cannot see the application's.
+     *
+     * It is NOT a conservative bound in either direction, and an earlier comment
+     * here claimed it was. The crossover grows as sqrt(limit), so raising the
+     * limit moves BOTH gates: `rarestBucket < crossover` gets easier to satisfy
+     * and `genericEstimate >= crossover` gets harder, and the second one can turn
+     * a finding off. 20 is simply a common first page. Every finding also reports
+     * the crossover at {@link wideLimit} so a caller paginating in thousands can
+     * see where their own limit lands.
+     */
+    assumedLimit: 20,
+    /** A second crossover reported alongside, for callers paginating in thousands. */
+    wideLimit: 1_000,
+    /**
+     * How many of the table's pages the WRONG plan must walk before this is worth
+     * a user's attention: ~400 KB of heap. Below it the flip cannot cost more than
+     * a millisecond or two however bad the ratio looks.
+     *
+     * This replaced a `relpages >= 1000` table-size floor, which was wrong and
+     * measurably so: a wrong plan on a SMALL table is not cheap, because an ordered
+     * index scan's cost is driven by how much of the table it walks, not by how big
+     * the table is. On a 285-page / 18,500-row fixture the generic plan read 336
+     * buffers against the custom plan's 7 (48x), and the old floor dropped that
+     * column without even counting it as considered.
+     */
+    minWalkPages: 50,
+    /**
+     * ...and it must walk at least this FRACTION of the table. The two gates are
+     * different questions (absolute cost, and how badly the plan is mismatched to
+     * the value), and a finding needs both.
+     */
+    minWalkFraction: 0.1,
+};
+// ---------------------------------------------------------------------------
+// Candidate enumeration (schema-only)
+// ---------------------------------------------------------------------------
+/** True when `column` is unique on its own, so `col = $1` always matches one row. */
+function isUniqueOnColumn(meta, column) {
+    if (meta.primaryKey.length === 1 && meta.primaryKey[0] === column)
+        return true;
+    return meta.uniqueColumns.some((cols) => cols.length === 1 && cols[0] === column);
+}
+/**
+ * Every column whose value distribution is worth reading: a column Turbine
+ * probes by equality (a relation FK) or that the schema already indexes as a
+ * leading key, minus the columns that are unique on their own (a unique
+ * equality matches one row, so both plans agree).
+ *
+ * Purely schema-derived, so the collector knows what to read BEFORE any stats
+ * exist. Whether the column is really served by a btree is decided later,
+ * against the live index list.
+ */
+export function collectDivergenceCandidateColumns(schema) {
+    const seen = new Set();
+    const out = [];
+    const add = (table, column) => {
+        const meta = schema.tables[table];
+        if (!meta)
+            return;
+        if (!meta.allColumns.includes(column))
+            return;
+        if (isUniqueOnColumn(meta, column))
+            return;
+        const key = `${table}.${column}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ table, column });
+    };
+    for (const meta of Object.values(schema.tables)) {
+        // Relation probe columns: the equality predicates Turbine itself emits.
+        for (const relDef of Object.values(meta.relations)) {
+            const target = schema.tables[relDef.to];
+            if (!target)
+                continue;
+            const keys = relDef.type === 'belongsTo' ? relDef.referenceKey : relDef.foreignKey;
+            const cols = Array.isArray(keys) ? keys : [keys];
+            // Only a SINGLE-column probe has a meaningful single-column distribution;
+            // a composite predicate multiplies selectivities and is not modelled here.
+            if (cols.length === 1 && cols[0] !== undefined)
+                add(relDef.to, cols[0]);
+            if (relDef.type === 'manyToMany' && relDef.through) {
+                const src = Array.isArray(relDef.through.sourceKey) ? relDef.through.sourceKey : [relDef.through.sourceKey];
+                if (src.length === 1 && src[0] !== undefined)
+                    add(relDef.through.table, src[0]);
+            }
+        }
+        // Leading index columns: whatever the application already filters on.
+        for (const idx of meta.indexes) {
+            if (idx.docPath)
+                continue;
+            const lead = idx.columns[0];
+            if (lead !== undefined && lead !== EXPRESSION_COLUMN)
+                add(meta.name, lead);
+        }
+    }
+    return out.sort((a, b) => a.table.localeCompare(b.table) || a.column.localeCompare(b.column));
+}
+// ---------------------------------------------------------------------------
+// Live index shape
+// ---------------------------------------------------------------------------
+/** A plain, valid btree with no expression column and no partial predicate. */
+function isPlainBtree(idx) {
+    if (!idx.isValid)
+        return false;
+    if (idx.accessMethod !== undefined && idx.accessMethod !== 'btree')
+        return false;
+    if (idx.hasExpressions === true)
+        return false;
+    if (idx.columns.includes(EXPRESSION_COLUMN))
+        return false;
+    return idx.predicate == null;
+}
+/**
+ * Whether a plain btree LEADS with `column` (so the planner has an index path
+ * for `column = $1`), and whether the table also has a DIFFERENT ordering index
+ * the generic plan can run away with (in practice the primary key).
+ *
+ * Both halves matter. With NO index on the filter column the two plans are
+ * identical and equally bad, which is the EXISTING missing-index finding, not
+ * this one. With no alternative ordering index there is no other plan to flip to.
+ */
+function indexShapeFor(snapshot, meta, column) {
+    let hasIdx = false;
+    let orderColumn = null;
+    const pk = meta.primaryKey.length > 0 ? meta.primaryKey[0] : undefined;
+    for (const idx of snapshot.indexes) {
+        if (idx.table !== meta.name)
+            continue;
+        if (!isPlainBtree(idx))
+            continue;
+        const lead = idx.columns[0];
+        if (lead === undefined)
+            continue;
+        if (lead === column) {
+            hasIdx = true;
+            continue;
+        }
+        // Prefer the primary key as the stated ordering column: it is the one a
+        // paginated read almost always orders by, and it is the plan the generic
+        // estimate actually chose in every measured case.
+        if (orderColumn === null || lead === pk)
+            orderColumn = lead;
+    }
+    return { hasIdx, orderColumn };
+}
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+/**
+ * The plan-boundary crossover: below this many truly matching rows, running
+ * `ORDER BY <other column> LIMIT n` as bitmap-scan + sort is cheaper than
+ * walking the ordering index and filtering.
+ *
+ * Derivation: an ordered index scan expects to read about (limit / matching) x
+ * pages before it accumulates `limit` matches; a bitmap scan reads about
+ * min(matching, pages). Those are equal at matching = sqrt(limit x pages).
+ * Measured flip points tracked this within 13 to 26% across two orders of
+ * magnitude of limit, which is why the size input is relpages rather than a
+ * row count.
+ *
+ * PREMISE, and it is the same blind spot the whole check has: both halves
+ * assume the matching rows are SCATTERED through the heap. On a clustered
+ * column a bitmap scan reads far fewer than min(matching, pages), so there is
+ * no flip at any limit and this crossover does not describe the table at all.
+ * pg_stats.correlation hints at it but does not settle it (a column can be
+ * uncorrelated overall and still have one value packed in the tail, which is
+ * exactly the counterexample fixture). Treat a crossover as a reason to run
+ * the diagnostic block, never as a measurement.
+ */
+export function crossoverRows(pages, limit) {
+    return Math.sqrt(Math.max(0, limit) * Math.max(0, pages));
+}
+/** Decode pg_stats.n_distinct: negative values are a fraction of the row count. */
+function decodeDistinct(nDistinct, rows) {
+    return nDistinct > 0 ? nDistinct : -nDistinct * rows;
+}
+/**
+ * The check that settles a finding. Three steps, in the order that makes them
+ * mean something:
+ *
+ *   1. Does `auto` actually promote this shape? `pg_prepared_statements`
+ *      reports `generic_plans` per cached statement, and until that counter
+ *      leaves 0 the backend is planning with the real values and there is
+ *      nothing to fix. This step comes FIRST because a finding describes
+ *      exposure, not an incident, and on many shapes the generic plan is
+ *      estimated expensive enough that `auto` never promotes at all.
+ *   2. What would the promoted plan cost? The two `plan_cache_mode` settings
+ *      make both plans reachable on demand.
+ *   3. Put the session back, so the paste does not leave `plan_cache_mode`
+ *      pinned for everything the user does next.
+ */
+function buildDiagnosticSql(table, column, orderColumn, columnType) {
+    const t = quoteIdent(table);
+    const c = quoteIdent(column);
+    const o = quoteIdent(orderColumn);
+    return [
+        'SET synchronize_seqscans = off;',
+        'SET max_parallel_workers_per_gather = 0;',
+        `PREPARE turbine_divergence(${columnType}, int) AS`,
+        `  SELECT * FROM ${t} WHERE ${c} = $1 ORDER BY ${o} LIMIT $2;`,
+        '-- 1. does this shape get promoted at all? run it six times, then look:',
+        'EXECUTE turbine_divergence(<your value>, 20);  -- x6',
+        "SELECT generic_plans, custom_plans FROM pg_prepared_statements WHERE name = 'turbine_divergence';",
+        '-- generic_plans still 0 means the planner is refusing the generic plan: no exposure.',
+        '-- 2. what the promoted plan would cost:',
+        'SET plan_cache_mode = force_custom_plan;',
+        'EXPLAIN (ANALYZE, BUFFERS) EXECUTE turbine_divergence(<your value>, 20);',
+        'SET plan_cache_mode = force_generic_plan;',
+        'EXPLAIN (ANALYZE, BUFFERS) EXECUTE turbine_divergence(<your value>, 20);',
+        '-- 3. put the session back:',
+        'RESET plan_cache_mode; RESET synchronize_seqscans; RESET max_parallel_workers_per_gather;',
+        'DEALLOCATE turbine_divergence;',
+    ].join('\n');
+}
+/**
+ * Score every candidate column against the snapshot and return the ones whose
+ * distribution admits a damaging generic-plan flip.
+ *
+ * ONE rule, for the direction that could be calibrated: the generic estimate
+ * sits ABOVE the plan boundary (so a promoted plan keeps the ordered index
+ * scan) while the table's rarest values sit below it, and the pages that
+ * ordered scan must walk for such a value are worth a user's attention both in
+ * absolute terms and as a fraction of the table.
+ *
+ * `correlation` is reported but no longer gates anything. It used to route
+ * clustered columns to a second rule; that rule is gone (see the module header),
+ * and routing on it also made the advisor STRUCTURALLY unable to report a real
+ * sparse-direction flip on any column that happened to be clustered, which was
+ * measured at 1,165x on one fixture.
+ */
+export function findPlanDivergence(schema, snapshot) {
+    const t = PLAN_DIVERGENCE_THRESHOLDS;
+    const findings = [];
+    const notices = [];
+    let candidatesConsidered = 0;
+    for (const candidate of collectDivergenceCandidateColumns(schema)) {
+        const meta = schema.tables[candidate.table];
+        if (!meta)
+            continue;
+        const stats = snapshot.tables[candidate.table];
+        if (!stats)
+            continue;
+        const rows = stats.reltuples;
+        const pages = stats.relpages;
+        // reltuples 0/-1 means never analyzed, and relpages is only read from
+        // pg_class: either being absent is an unknown, never a zero.
+        if (rows <= 0 || pages === undefined || pages <= 0)
+            continue;
+        const { hasIdx, orderColumn } = indexShapeFor(snapshot, meta, candidate.column);
+        // No btree leading with the column: both plans are equally bad and the
+        // existing missing-index finding already owns this case.
+        if (!hasIdx)
+            continue;
+        // No other ordering index: no alternative plan for the generic estimate to
+        // run away with.
+        if (orderColumn === null)
+            continue;
+        // Counted HERE, before any scored gate. Everything above is a SHAPE
+        // question (is there an index to flip between at all?); everything below is
+        // a verdict on live statistics. A user must be able to tell "considered and
+        // clean" from "never looked", and an earlier revision incremented this after
+        // a silent table-size floor, so the two were indistinguishable.
+        candidatesConsidered++;
+        const dist = snapshot.columnStats?.[`${candidate.table}.${candidate.column}`];
+        if (!dist) {
+            notices.push({
+                table: candidate.table,
+                column: candidate.column,
+                reason: 'no pg_stats row for this column (never analyzed, or the statistics read degraded): run ANALYZE',
+            });
+            continue;
+        }
+        if (dist.nDistinct === 0) {
+            notices.push({
+                table: candidate.table,
+                column: candidate.column,
+                reason: 'n_distinct is 0 (column never analyzed): run ANALYZE, then re-check',
+            });
+            continue;
+        }
+        if (dist.mostCommonFreqs === null || dist.mostCommonFreqs.length === 0) {
+            notices.push({
+                table: candidate.table,
+                column: candidate.column,
+                reason: 'pg_stats has no most_common_freqs for this column: the value distribution cannot be scored',
+            });
+            continue;
+        }
+        const distinctValues = decodeDistinct(dist.nDistinct, rows);
+        if (distinctValues < 2)
+            continue;
+        const freqs = dist.mostCommonFreqs;
+        const nmcv = dist.mcvCount > 0 ? dist.mcvCount : freqs.length;
+        const freqSum = freqs.reduce((a, b) => a + b, 0);
+        const densestBucket = Math.max(...freqs) * rows;
+        // The residual (non-MCV) bucket when the MCV list does not cover every value;
+        // when it does (the normal case for a tenant column, whose distinct count is
+        // below the default statistics target), the rarest MCV IS the rarest value.
+        const rarestBucket = nmcv < distinctValues ? (rows * Math.max(0, 1 - freqSum)) / (distinctValues - nmcv) : Math.min(...freqs) * rows;
+        const genericEstimate = rows / distinctValues;
+        const crossover = crossoverRows(pages, t.assumedLimit);
+        const correlation = dist.correlation ?? 0;
+        // Pages the ordered index scan the generic plan keeps must walk before it
+        // accumulates `assumedLimit` matches of the rarest value: limit / matching
+        // of the table, and the whole table once the value has fewer rows than the
+        // limit. The bitmap plan the custom planner takes instead reads about
+        // min(matching, pages).
+        const walkPages = rarestBucket > 0 ? Math.min(pages, (t.assumedLimit * pages) / rarestBucket) : pages;
+        const walkFraction = walkPages / pages;
+        const approxAmplification = walkPages / Math.max(1, Math.min(rarestBucket, pages));
+        const flips = genericEstimate >= crossover && rarestBucket < crossover;
+        if (!flips)
+            continue;
+        if (walkPages < t.minWalkPages || walkFraction < t.minWalkFraction)
+            continue;
+        let valuesBelowCrossover = freqs.filter((f) => f * rows < crossover).length;
+        if (nmcv < distinctValues && rarestBucket < crossover) {
+            valuesBelowCrossover += Math.round(distinctValues - nmcv);
+        }
+        const columnType = meta.pgTypes[candidate.column] ?? 'text';
+        findings.push({
+            table: candidate.table,
+            column: candidate.column,
+            rows,
+            pages,
+            distinctValues,
+            genericEstimate,
+            rarestBucket,
+            densestBucket,
+            correlation,
+            crossoverRows: crossover,
+            crossoverRowsWide: crossoverRows(pages, t.wideLimit),
+            assumedLimit: t.assumedLimit,
+            valuesBelowCrossover,
+            walkPages,
+            walkFraction,
+            approxAmplification,
+            orderColumn,
+            columnField: meta.reverseColumnMap[candidate.column] ?? candidate.column,
+            orderColumnField: meta.reverseColumnMap[orderColumn] ?? orderColumn,
+            lastAnalyze: stats.lastAnalyze ?? null,
+            diagnosticSql: buildDiagnosticSql(candidate.table, candidate.column, orderColumn, columnType),
+            thresholds: t,
+        });
+    }
+    findings.sort((a, b) => b.approxAmplification - a.approxAmplification ||
+        a.table.localeCompare(b.table) ||
+        a.column.localeCompare(b.column));
+    return { findings, notices, candidatesConsidered };
+}

package/dist/powql.d.ts

@@ -125,6 +125,17 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * callers short-circuit it, because PowDB's projection fast path returned ONE
      * row for `limit 0` below 0.20.
      */
+    /**
+     * Refuse the per-query `forceCustomPlan` read option.
+     *
+     * `FindManyArgs.forceCustomPlan` documents an `UnsupportedFeatureError` on any
+     * engine with no PostgreSQL plan cache, and PowDB is one: it is not a
+     * `Dialect` at all, so it never reaches the SQL builder's own refusal at
+     * `preparedNameFor`. Without this the flag would be silently ignored here,
+     * which is precisely the "reports a guarantee that was never made" failure the
+     * option's refusal exists to prevent.
+     */
+    private assertNoForceCustomPlan;
     private assertPagination;
     /** A predicate that is always false, the empty-`in` / contradiction sentinel. */
     private alwaysFalse;

package/dist/powql.js

@@ -292,6 +292,22 @@ export class PowqlInterface {
      * callers short-circuit it, because PowDB's projection fast path returned ONE
      * row for `limit 0` below 0.20.
      */
+    /**
+     * Refuse the per-query `forceCustomPlan` read option.
+     *
+     * `FindManyArgs.forceCustomPlan` documents an `UnsupportedFeatureError` on any
+     * engine with no PostgreSQL plan cache, and PowDB is one: it is not a
+     * `Dialect` at all, so it never reaches the SQL builder's own refusal at
+     * `preparedNameFor`. Without this the flag would be silently ignored here,
+     * which is precisely the "reports a guarantee that was never made" failure the
+     * option's refusal exists to prevent.
+     */
+    assertNoForceCustomPlan(args) {
+        if (args?.forceCustomPlan !== true)
+            return;
+        throw new UnsupportedFeatureError('The forceCustomPlan query option', 'powdb', 'Forcing a per-query custom plan means keeping the statement out of the PostgreSQL plan cache, and PowDB ' +
+            'has no such cache to keep it out of. Remove the option, or set it only on PostgreSQL queries.');
+    }
     assertPagination(limit, offset, context) {
         for (const [name, value] of [
             ['limit', limit],
@@ -1121,6 +1137,7 @@ export class PowqlInterface {
     // Reads
     // -------------------------------------------------------------------------
     async findMany(args = {}) {
+        this.assertNoForceCustomPlan(args);
         return this.withMiddleware('findMany', args, async () => {
             // `limit: 0` means "no rows" (SQL `LIMIT 0`), and answering it client-side
             // is correct on every engine version: PowDB's projection fast path returned
@@ -1260,6 +1277,7 @@ export class PowqlInterface {
             .filter((line) => line.length > 0);
     }
     async findUnique(args) {
+        this.assertNoForceCustomPlan(args);
         // Prisma compound-unique selector → column conjunction (engine parity with
         // the SQL findUnique family; pure metadata, so this is a one-line adoption).
         if (args.where) {
@@ -1282,6 +1300,7 @@ export class PowqlInterface {
         });
     }
     async findFirst(args = {}) {
+        this.assertNoForceCustomPlan(args);
         return this.withMiddleware('findFirst', args, async () => {
             const { rows, native, nestedPlans, linkPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
             if (!rows.length)
@@ -2488,6 +2507,7 @@ export class PowqlInterface {
     // Aggregates
     // -------------------------------------------------------------------------
     async count(args = {}) {
+        this.assertNoForceCustomPlan(args);
         return this.withMiddleware('count', (args ?? {}), async () => {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
@@ -2526,6 +2546,7 @@ export class PowqlInterface {
             '`_count` of a NOT NULL column are correct on every version and are never refused.');
     }
     async aggregate(args) {
+        this.assertNoForceCustomPlan(args);
         return this.withMiddleware('aggregate', args, async () => {
             // One scalar query per aggregate, PowDB's bare-projection aggregate is broken.
             const result = {};
@@ -2571,6 +2592,7 @@ export class PowqlInterface {
         });
     }
     async groupBy(args) {
+        this.assertNoForceCustomPlan(args);
         return this.withMiddleware('groupBy', args, async () => {
             // DISTINCT ON has no PowQL equivalent (no DISTINCT ON row source).
             if (args.distinctOn) {

package/dist/query/builder.d.ts

@@ -712,6 +712,51 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     resetUnlimitedWarnings(): void;
     private emitQueryEvent;
+    /**
+     * 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.
+     */
+    private preparedNameFor;
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.