turbine-orm 0.55.0 → 0.56.0

package/dist/cli/index.js

@@ -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)
@@ -32,6 +32,7 @@ import { generate, generatePrismaMap } from '../generate.js';
 import { buildCreateIndexSql, buildDropIndexSql, collectDoctorProbeIndexNames, collectRelationProbeColumns, findMissingRelationIndexes, } from '../index-advisor.js';
 import { auditDoctorIndexes, collectStatsSnapshot, collectTableHeat, findInvalidIndexes, findRedundantIndexes, findUnusedIndexes, formatBytes, isSnapshotUsable, STATS_THRESHOLDS, scoreMissingIndex, } from '../index-stats.js';
 import { introspect } from '../introspect.js';
+import { collectDivergenceCandidateColumns, findPlanDivergence, PLAN_DIVERGENCE_THRESHOLDS, } from '../plan-divergence.js';
 import { DestructivePushRefusal, schemaDiff, schemaPush } from '../schema-sql.js';
 import { configTemplate, DEFAULT_INIT_SEED_FILE, findConfigFile, loadConfigResult, looksLikeSchemaFilePath, resolveConfig, resolveSeedFile, unwrapModuleDefault, } from './config.js';
 import { DESTRUCTIVE_KIND_LABEL } from './destructive.js';
@@ -142,6 +143,9 @@ export function parseArgs(argv = process.argv.slice(2)) {
                 result.metricsUrl = next;
                 i++;
                 break;
+            case '--no-plan-divergence':
+                result.noPlanDivergence = true;
+                break;
             case '--zod':
                 result.zod = true;
                 break;
@@ -2259,20 +2263,27 @@ async function cmdDoctor(args, config) {
     const missing = findMissingRelationIndexes(schema);
     // Collect live statistics. The collector reads whole-schema indexes (for
     // invalid-index detection) plus per-table stats + probed-column null_frac.
-    const probedTables = [...new Set(missing.map((m) => m.table))];
     const probedColumns = [];
     for (const m of missing) {
         if (m.columns.length === 1 && m.columns[0] !== undefined) {
             probedColumns.push({ table: m.table, column: m.columns[0] });
         }
     }
+    // Plan-divergence candidates are the columns that ARE indexed, so their tables
+    // are usually disjoint from the missing-index set: both lists feed the same
+    // one-connection snapshot rather than opening a second read.
+    const divergenceOn = args.noPlanDivergence !== true;
+    const divergenceColumns = divergenceOn ? collectDivergenceCandidateColumns(schema) : [];
+    const probedTables = [...new Set(missing.map((m) => m.table))];
+    const statsTables = [...new Set([...probedTables, ...divergenceColumns.map((c) => c.table)])];
     let snapshot;
     try {
         snapshot = await collectStatsSnapshot({
             connectionString: url,
             schema: config.schema,
-            tables: probedTables,
+            tables: statsTables,
             columns: probedColumns,
+            distributionColumns: divergenceColumns,
         });
     }
     catch (err) {
@@ -2311,9 +2322,16 @@ async function cmdDoctor(args, config) {
         ? auditDoctorIndexes(snapshot, collectDoctorProbeIndexNames(schema), { minScans, relationProbes })
         : [];
     const subtract = { unusedRan, auditRan, minScans, unused, redundant, audit };
+    // Plan divergence has its OWN freshness gate. The cost tiers require a
+    // trustworthy stats_reset age because they normalize write counters by it;
+    // this check reads no counter, only pg_stats, whose freshness is ANALYZE. A
+    // cluster with a NULL stats_reset (the default) must still get the check.
+    const divergence = divergenceOn && snapshot.available
+        ? findPlanDivergence(schema, snapshot)
+        : { findings: [], notices: [], candidatesConsidered: 0 };
     if (jsonMode) {
         spinner?.stop();
-        console.log(JSON.stringify(buildDoctorJson({ schema, findings, invalid, snapshot, usable, heat, subtract, args }), null, 2));
+        console.log(JSON.stringify(buildDoctorJson({ schema, findings, invalid, snapshot, usable, heat, subtract, divergence, args }), null, 2));
         return;
     }
     await renderDoctorHuman({
@@ -2325,6 +2343,7 @@ async function cmdDoctor(args, config) {
         usable,
         heat,
         subtract,
+        divergence,
         args,
         config,
     });
@@ -2392,13 +2411,17 @@ function buildDoctorJson(ctx) {
     out.redundant = ctx.subtract.unusedRan ? ctx.subtract.redundant : [];
     out.audit = ctx.subtract.auditRan ? ctx.subtract.audit : [];
     out.invalid = ctx.invalid;
+    // Always an array, never absent: a consumer must not have to write `?? []`
+    // just because the section was skipped or found nothing.
+    out.planDivergence = ctx.divergence.findings;
+    out.planDivergenceNotices = ctx.divergence.notices;
     return out;
 }
 async function renderDoctorHuman(ctx) {
-    const { spinner, schema, findings, invalid, snapshot, usable, heat, subtract, args, config } = ctx;
+    const { spinner, schema, findings, invalid, snapshot, usable, heat, subtract, divergence, args, config } = ctx;
     spinner.succeed(`Scanned ${bold(String(Object.keys(schema.tables).length))} tables`);
     const subtractRan = subtract.unusedRan || subtract.auditRan;
-    const nothingToAdd = findings.length === 0 && invalid.length === 0;
+    const nothingToAdd = findings.length === 0 && invalid.length === 0 && divergence.findings.length === 0;
     const nothingToSubtract = subtract.unused.length === 0 && subtract.redundant.length === 0 && subtract.audit.length === 0;
     if (nothingToAdd && (!subtractRan || nothingToSubtract)) {
         if (subtractRan) {
@@ -2429,6 +2452,7 @@ async function renderDoctorHuman(ctx) {
         }
     }
     renderInvalidIndexes(invalid);
+    renderPlanDivergence(divergence);
     if (subtract.unusedRan) {
         renderUnusedIndexes(subtract.unused, subtract.minScans, snapshot);
         renderRedundantIndexes(subtract.redundant);
@@ -2594,6 +2618,92 @@ function renderInvalidIndexes(invalid) {
         newline();
     }
 }
+/** Round to a whole number and group it, for the divergence report's estimates. */
+function divInt(n) {
+    if (!Number.isFinite(n))
+        return 'unbounded';
+    return Math.round(n).toLocaleString('en-US');
+}
+/**
+ * The plan-divergence section: columns whose value distribution can flip a
+ * cached plan. Finding-only by design, there is no `--fix` for it: the fix is
+ * application code (scope the plan-cache mode to the affected reads), and the
+ * index that looks like a fix is measured NOT to be one.
+ */
+function renderPlanDivergence(divergence) {
+    const { findings, notices } = divergence;
+    if (findings.length === 0 && notices.length === 0)
+        return;
+    if (findings.length > 0) {
+        warn(`${bold(String(findings.length))} column(s) whose value distribution can flip a cached plan`);
+        newline();
+        console.log(`  ${dim('Postgres may promote a named prepared statement to a GENERIC plan from its sixth execution,')}`);
+        console.log(`  ${dim('but only when the generic plan is not ESTIMATED to cost more than the average custom')}`);
+        console.log(`  ${dim('plan. A generic plan cannot see your values: it estimates "col = $1" as rows /')}`);
+        console.log(`  ${dim('n_distinct and an unknown LIMIT as 10% of the child estimate. When those defaults')}`);
+        console.log(`  ${dim('land on the other side of a plan boundary from the real value, the plan flips.')}`);
+        newline();
+    }
+    for (const f of findings) {
+        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(`${f.table}.${f.column}`))}  ${gray('SPARSE-VALUE FLIP')}`);
+        console.log(`    ${dim(symbols.tee)} generic estimate ${bold(divInt(f.genericEstimate))} rows ${dim(`(${divInt(f.rows)} rows / ${divInt(f.distinctValues)} distinct values)`)}`);
+        console.log(`    ${dim(symbols.tee)} rarest value bucket ${bold(divInt(f.rarestBucket))} rows ${dim('(pg_stats most_common_freqs / residual bucket)')}`);
+        console.log(`    ${dim(symbols.tee)} crossover ${bold(divInt(f.crossoverRows))} rows ${dim(`(sqrt(limit ${f.assumedLimit} x ${divInt(f.pages)} pages); ${divInt(f.crossoverRowsWide)} at limit ${f.thresholds.wideLimit})`)}`);
+        const analyzed = f.lastAnalyze === null
+            ? 'last ANALYZE unknown'
+            : `last analyzed ${Math.max(0, Math.round((Date.now() - f.lastAnalyze.getTime()) / 86_400_000))}d ago`;
+        console.log(`    ${dim(symbols.tee)} ${dim(`values below the crossover: ${divInt(f.valuesBelowCrossover)} of ${divInt(f.distinctValues)}, correlation ${f.correlation.toFixed(2)}, ${analyzed}`)}`);
+        console.log(`    ${dim(symbols.tee)} for such a value the generic plan walks ~${bold(divInt(f.walkPages))} of ${divInt(f.pages)} pages ${dim(`(${Math.round(f.walkFraction * 100)}% of the table)`)}`);
+        console.log(`      ${dim(`for reads shaped WHERE ${f.column} = $1 ORDER BY ${f.orderColumn} LIMIT $n,`)}`);
+        console.log(`      ${dim("where the custom plan reads only that value's own rows.")}`);
+        console.log(`    ${dim(symbols.tee)} ${dim('No amplification figure is printed, deliberately. This models how many rows a')}`);
+        console.log(`      ${dim('value has, not WHERE they sit in the heap, and the second half can move the')}`);
+        console.log(`      ${dim('real cost by an order of magnitude. Measure it instead:')}`);
+        console.log(`    ${dim(symbols.teeEnd)} ${dim('confirm with YOUR values before changing anything:')}`);
+        for (const line of f.diagnosticSql.split('\n')) {
+            console.log(`      ${green(line)}`);
+        }
+        newline();
+    }
+    if (findings.length > 0) {
+        console.log(`  ${bold('What to do, in order:')}`);
+        console.log(`    1. Check that this shape is promoted AT ALL. Step 1 of the block above: while`);
+        console.log(`       ${dim('generic_plans is 0, Postgres is planning with your real values and there is nothing')}`);
+        console.log(`       ${dim('to fix. A finding is exposure, not an incident, and many shapes never promote.')}`);
+        console.log(`    2. If it does promote, compare the two plans. Both SETs matter: without them a`);
+        console.log(`       ${dim('repeated seq scan resumes where the last one stopped and a catastrophic case reads')}`);
+        console.log(`       ${dim('as harmless.')}`);
+        console.log(`    3. If the flip is real, scope the fix to those reads:`);
+        const first = findings[0];
+        console.log(`       ${cyan(`db.${first.table}.findMany({ where: { ${first.columnField}: value }, orderBy: { ${first.orderColumnField}: 'asc' },`)}`);
+        console.log(`       ${cyan(`                     limit: 20, forceCustomPlan: true })`)}`);
+        console.log(`       ${dim('That withholds the prepared-statement NAME for that one query, so the driver')}`);
+        console.log(`       ${dim('re-parses it every execution and it is always planned with the real values. No')}`);
+        console.log(`       ${dim('GUC, no SET LOCAL, no transaction, no extra round trip.')}`);
+        console.log(`    4. Do NOT set planCacheMode on the client to fix this. There are measured shapes`);
+        console.log(`       ${dim('where a generic plan is dramatically better (an unordered LIMIT over a value whose')}`);
+        console.log(`       ${dim('rows are packed at the end of the heap: 4,262 buffers custom vs 71 generic on a')}`);
+        console.log(`       ${dim('reproducible fixture). A custom plan is not automatically the better plan.')}`);
+        console.log(`    5. A composite index on (${first.column}, ${first.orderColumn}) makes the GOOD plan better. It`);
+        console.log(`       ${dim('does NOT stop the generic plan from choosing the other one, and it can widen the gap.')}`);
+        console.log(`       ${dim('Add it for the custom-plan win, not as a fix for this finding.')}`);
+        newline();
+        console.log(`  ${dim('This finding is derived from statistics, not from your traffic: it says the DISTRIBUTION')}`);
+        console.log(`  ${dim('admits a damaging flip, not that a query is running one today. It models ONE shape,')}`);
+        console.log(`  ${dim('the rare value that loses its bitmap plan. It cannot see where a value physically')}`);
+        console.log(`  ${dim('sits in the heap, so a clean report is not evidence of immunity.')}`);
+        console.log(`  ${dim(`Gates: the wrong plan must walk >= ${PLAN_DIVERGENCE_THRESHOLDS.minWalkPages} pages and >= ${Math.round(PLAN_DIVERGENCE_THRESHOLDS.minWalkFraction * 100)}% of the table, at an assumed`)}`);
+        console.log(`  ${dim(`LIMIT ${PLAN_DIVERGENCE_THRESHOLDS.assumedLimit}. ${divergence.candidatesConsidered} column(s) were scored. Skip this section with --no-plan-divergence.`)}`);
+        newline();
+    }
+    if (notices.length > 0) {
+        console.log(`  ${dim('Not scored for cached-plan divergence (statistics missing):')}`);
+        for (const n of notices) {
+            console.log(`    ${dim(`- ${n.table}.${n.column}: ${n.reason}`)}`);
+        }
+        newline();
+    }
+}
 /** Write the --fix migration (CONCURRENTLY + directive by default; plain with --no-concurrently). */
 function renderFixMigration(findings, config, args) {
     const concurrently = args.noConcurrently !== true;
@@ -3067,7 +3177,7 @@ function showHelp() {
     console.log(`      ${dim('status')}           Show applied/pending migrations`);
     console.log(`    ${cyan('seed')}               Run seed file`);
     console.log(`    ${cyan('status')} ${dim('| info')}      Show schema summary`);
-    console.log(`    ${cyan('doctor')}             Cost-aware missing-FK-index triage ${dim('(--fix, --json, --unused, --audit)')}`);
+    console.log(`    ${cyan('doctor')}             Index + cached-plan triage ${dim('(--fix, --json, --unused, --audit)')}`);
     console.log(`    ${cyan('studio')}             Launch local read-only web UI ${dim('(--write for writes, --demo for a sample DB)')}`);
     console.log(`    ${cyan('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);

package/dist/client.d.ts

@@ -295,7 +295,22 @@ export interface TurbineConfig {
      * Default `undefined`: Turbine issues NOTHING and the backend keeps its own
      * default (`auto`), byte-identical to not setting the option.
      *
-     * SESSION-LEVEL, NOT PER QUERY. It is applied as a connection parameter
+     * SESSION-LEVEL. THE PER-QUERY LEVER IS A DIFFERENT, NARROWER ONE. This
+     * option is a connection parameter and cannot be unset for a single query, so
+     * a client-wide value cannot express "custom here, `auto` there". The read
+     * option `forceCustomPlan: true` covers that case, and only that case: it
+     * withholds the prepared-statement NAME for one query, and because the driver
+     * re-parses an unnamed statement on every execution, the counter that
+     * promotion depends on is reset before it is ever reached. That
+     * mechanism can only ever mean custom, so there is deliberately no per-query
+     * `force_generic_plan`; that direction stays here, at the connection. The two
+     * do NOT compose in the other order either: `'force_generic_plan'` set here
+     * governs unnamed statements as well as named ones (measured), so a
+     * per-query `forceCustomPlan: true` cannot escape it and is REFUSED with
+     * `ValidationError` (E003) instead of silently doing nothing. Leave this
+     * option unset (or `'auto'`) if any query needs the per-query lever.
+     *
+     * IT IS APPLIED as a connection parameter
      * (`options=-c plan_cache_mode=...`) when the pool opens a connection, so it
      * is in force for that connection's very first statement and persists for its
      * whole life: every pooled checkout, `$transaction`, stream and pipeline on

package/dist/client.js

@@ -650,6 +650,10 @@ export class TurbineClient {
             jsonEncoding: config.jsonEncoding,
             globalFilters: config.globalFilters,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
+            // Forwarded so a per-query `forceCustomPlan` can refuse the combination
+            // this client's own connections would silently defeat, see the
+            // `planCacheMode` note on QueryInterfaceOptions.
+            planCacheMode,
             sqlCache: config.sqlCache ?? true,
             sqlCacheSize: config.sqlCacheSize,
             dialect: config.dialect,

package/dist/dialect.d.ts

@@ -375,6 +375,15 @@ export interface Dialect {
      * setting (`SET plan_cache_mode = auto | force_custom_plan |
      * force_generic_plan`). Gates the opt-in `planCacheMode` client option.
      *
+     * It ALSO gates the per-query `forceCustomPlan` read option, which uses a
+     * different mechanism (it withholds the prepared-statement name, so the
+     * driver re-parses the statement on every execution and the counter that
+     * generic-plan promotion depends on never reaches its threshold) but
+     * asks the identical capability question: does this engine have a PostgreSQL
+     * plan cache whose generic-plan promotion is worth pinning? An engine that
+     * answers no cannot honour either option, so both refuse on the same flag
+     * rather than on two flags that could never disagree.
+     *
      * A capability flag rather than a `dialect.name === 'postgresql'` test, for
      * the same reason every other refusal here is one: the setting is a property
      * of the PostgreSQL PLAN CACHE, not of the SQL string, so a

package/dist/index-stats.d.ts

@@ -86,6 +86,12 @@ export interface TableStats {
     table: string;
     /** pg_class.reltuples. 0 or -1 means never-analyzed → treated as UNKNOWN (null rows). */
     reltuples: number;
+    /**
+     * pg_class.relpages. The SIZE input the plan-divergence crossover is computed
+     * from (a plan boundary tracks pages relative to the LIMIT, not rows).
+     * Absent when the pg_class read degraded; 0 means never analyzed.
+     */
+    relpages?: number;
     /** pg_stat_user_tables.n_live_tup, a cross-check for reltuples. */
     nLiveTup?: number;
     nTupIns?: number;
@@ -100,6 +106,13 @@ export interface TableStats {
     tableSizeBytes?: number;
     /** Count of indexes already on the table (pg_index). */
     existingIndexCount?: number;
+    /**
+     * The later of pg_stat_user_tables.last_analyze / last_autoanalyze: when the
+     * planner's column statistics were last refreshed. This, NOT stats_reset, is
+     * the freshness that matters for anything read out of pg_stats. Null when
+     * never analyzed; absent when the pg_stat read degraded.
+     */
+    lastAnalyze?: Date | null;
 }
 /**
  * Placeholder for an index column that is an EXPRESSION, not a plain column
@@ -133,6 +146,27 @@ export interface IndexStat {
     /** pg_relation_size of the index heap, bytes. Size reclaimed by a drop. */
     sizeBytes?: number;
 }
+/**
+ * The value distribution of one column, read from pg_stats with
+ * `inherited = false`. Consumed by the plan-divergence advisor, which needs to
+ * reproduce the planner's OWN estimates rather than approximate them.
+ */
+export interface ColumnDistribution {
+    table: string;
+    column: string;
+    /**
+     * pg_stats.n_distinct, RAW: a positive value is a count, a negative value is a
+     * fraction of the row count. Kept undecoded so the consumer decodes it exactly
+     * the way the planner does. 0 means the column was never analyzed.
+     */
+    nDistinct: number;
+    /** pg_stats.correlation, signed. NULL for types with no ordering. */
+    correlation: number | null;
+    /** pg_stats.most_common_freqs, or null when the column has no MCV list. */
+    mostCommonFreqs: number[] | null;
+    /** cardinality(most_common_vals): how many values the MCV list actually covers. */
+    mcvCount: number;
+}
 /**
  * A point-in-time read of the statistics the triage needs. Every part is
  * optional at the field level so the pure scorer degrades honestly.
@@ -150,6 +184,13 @@ export interface StatsSnapshot {
     indexes: IndexStat[];
     /** null_frac per probed column, keyed `table.column`. */
     nullFrac: Record<string, number>;
+    /**
+     * Value distribution per candidate column, keyed `table.column`. Optional at
+     * the snapshot level: a caller that never asked for distribution statistics
+     * (or whose pg_stats read degraded) leaves it absent, and the plan-divergence
+     * advisor reports that as a suppressed candidate rather than scoring a guess.
+     */
+    columnStats?: Record<string, ColumnDistribution>;
     /** Per-signal degradation notices (privileges, catalog gaps, timeouts). */
     notices: string[];
 }
@@ -347,6 +388,11 @@ export interface CollectSnapshotOptions {
     tables: string[];
     /** Columns to read null_frac for (single-column probes). */
     columns: ProbedColumn[];
+    /**
+     * Columns to read the full value distribution for (n_distinct, correlation,
+     * MCV frequencies). One extra pg_stats query; empty skips it entirely.
+     */
+    distributionColumns?: ProbedColumn[];
     /** statement_timeout for each catalog read. Default 5000ms. */
     statementTimeoutMs?: number;
 }

package/dist/index-stats.js

@@ -102,6 +102,7 @@ export function emptyStatsSnapshot(notices = []) {
         tables: {},
         indexes: [],
         nullFrac: {},
+        columnStats: {},
         notices,
     };
 }
@@ -544,12 +545,14 @@ export async function collectStatsSnapshot(options) {
             }
         }
         // --- table stats (pg_stat_user_tables) ---------------------------------
-        const statRows = await run('pg_stat_user_tables', `SELECT relname, n_tup_ins, n_tup_upd, n_tup_del, n_tup_hot_upd, seq_scan, seq_tup_read, n_live_tup
+        const statRows = await run('pg_stat_user_tables', `SELECT relname, n_tup_ins, n_tup_upd, n_tup_del, n_tup_hot_upd, seq_scan, seq_tup_read, n_live_tup,
+              greatest(last_analyze, last_autoanalyze) AS last_analyze
          FROM pg_stat_user_tables
         WHERE schemaname = $1 AND relname = ANY($2)`, [options.schema, options.tables]);
         // --- class size + existing index count (pg_class) ----------------------
         const classRows = await run('pg_class size', `SELECT c.relname,
               c.reltuples::bigint::text AS reltuples,
+              c.relpages::bigint::text AS relpages,
               pg_total_relation_size(c.oid)::text AS total_size,
               pg_relation_size(c.oid)::text AS table_size,
               (SELECT count(*) FROM pg_index i WHERE i.indrelid = c.oid)::text AS index_count
@@ -572,6 +575,7 @@ export async function collectStatsSnapshot(options) {
             for (const row of classRows) {
                 const s = ensure(row.relname);
                 s.reltuples = Number(row.reltuples);
+                s.relpages = Number(row.relpages);
                 s.totalSizeBytes = Number(row.total_size);
                 s.tableSizeBytes = Number(row.table_size);
                 s.existingIndexCount = Number(row.index_count);
@@ -588,6 +592,7 @@ export async function collectStatsSnapshot(options) {
                 s.seqScan = Number(row.seq_scan);
                 s.seqTupRead = Number(row.seq_tup_read);
                 s.nLiveTup = Number(row.n_live_tup);
+                s.lastAnalyze = row.last_analyze == null ? null : new Date(row.last_analyze);
             }
         }
         // --- invalid + all indexes (whole schema, for invalid detection) -------
@@ -651,6 +656,42 @@ export async function collectStatsSnapshot(options) {
                 }
             }
         }
+        // --- value distribution for divergence candidates (pg_stats) -----------
+        const distCols = options.distributionColumns ?? [];
+        if (distCols.length > 0) {
+            // `inherited = false` is required: on a partitioned parent the inherited
+            // row describes the whole tree, and a per-partition plan is not chosen
+            // from it. most_common_vals is an anyarray, so its cardinality is read
+            // through a text[] cast (array_length on anyarray cannot resolve a type).
+            const distRows = await run('pg_stats.distribution', `SELECT s.tablename, s.attname,
+                s.n_distinct::text AS n_distinct,
+                s.correlation::text AS correlation,
+                s.most_common_freqs,
+                coalesce(array_length(s.most_common_vals::text::text[], 1), 0)::text AS mcv_count
+           FROM pg_stats s
+           JOIN unnest($2::text[], $3::text[]) AS probe(t, c)
+             ON probe.t = s.tablename AND probe.c = s.attname
+          WHERE s.schemaname = $1 AND s.inherited = false`, [options.schema, distCols.map((c) => c.table), distCols.map((c) => c.column)]);
+            if (distRows) {
+                const byKey = snapshot.columnStats ?? {};
+                for (const row of distRows) {
+                    byKey[`${row.tablename}.${row.attname}`] = {
+                        table: row.tablename,
+                        column: row.attname,
+                        nDistinct: Number(row.n_distinct),
+                        correlation: row.correlation == null ? null : Number(row.correlation),
+                        mostCommonFreqs: row.most_common_freqs == null ? null : row.most_common_freqs.map(Number),
+                        mcvCount: row.mcv_count == null ? 0 : Number(row.mcv_count),
+                    };
+                }
+                snapshot.columnStats = byKey;
+            }
+            else {
+                // The read failed (privileges, catalog gap). Leave columnStats absent so
+                // the advisor suppresses every candidate instead of scoring zeros.
+                snapshot.columnStats = undefined;
+            }
+        }
     }
     finally {
         try {