pgexplain 0.2.0 → 0.3.0

package/dist/server.js

@@ -23,6 +23,9 @@ var AppError = class extends Error {
     if (cause !== void 0) this.cause = cause;
   }
 };
+function finding(code, severity, parts) {
+  return { code, domain: "plan", severity, ...parts };
+}
 var SEVERITY_RANK = { error: 0, warn: 1, info: 2 };
 function bySeverity(a, b) {
   return SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
@@ -37,7 +40,7 @@ function scrubCredentials(input) {
 
 // package.json
 var package_default = {
-  version: "0.2.0"};
+  version: "0.3.0"};
 
 // src/diagnostics/catalog.ts
 var DOCS = "https://www.postgresql.org/docs/current";
@@ -798,7 +801,9 @@ var DEFAULT_THRESHOLDS = {
   correlatedLoops: 1e3,
   jitPct: 25,
   triggerPct: 10,
-  lowCacheHitRatio: 0.9
+  lowCacheHitRatio: 0.9,
+  limitDiscardRows: 1e4,
+  staleStatsModRatio: 0.2
 };
 var DEFAULT_CONFIG = {
   thresholds: { ...DEFAULT_THRESHOLDS },
@@ -1214,6 +1219,10 @@ function normalizeNode(raw, nextId) {
     diskUsage: num(raw, "Disk Usage"),
     exactHeapBlocks: num(raw, "Exact Heap Blocks"),
     lossyHeapBlocks: num(raw, "Lossy Heap Blocks"),
+    cacheHits: num(raw, "Cache Hits"),
+    cacheMisses: num(raw, "Cache Misses"),
+    cacheEvictions: num(raw, "Cache Evictions"),
+    cacheOverflows: num(raw, "Cache Overflows"),
     sharedHitBlocks: num(raw, "Shared Hit Blocks"),
     sharedReadBlocks: num(raw, "Shared Read Blocks"),
     sharedDirtiedBlocks: num(raw, "Shared Dirtied Blocks"),
@@ -1561,8 +1570,11 @@ var cartesianProduct = {
   check(node, ctx) {
     if (node.nodeType !== "Nested Loop") return [];
     if (node.joinFilter) return [];
-    const inner = node.children[1];
+    let inner = node.children[1];
     if (!inner) return [];
+    while ((inner.nodeType === "Memoize" || inner.nodeType === "Materialize") && inner.children[0]) {
+      inner = inner.children[0];
+    }
     if (inner.indexCond || inner.recheckCond) return [];
     const outer = node.children[0];
     if (!outer) return [];
@@ -1881,6 +1893,47 @@ var indexOnlyHeapFetches = {
   }
 };
 
+// src/advisor/rules/limit-large-offset.ts
+var limitLargeOffset = {
+  id: "PGX_LIMIT_LARGE_OFFSET",
+  title: "LIMIT discards a large prefix (OFFSET pagination)",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Limit") return [];
+    const child = outerChild(node);
+    const emitted = node.metrics.totalRows;
+    const produced = child?.metrics.totalRows;
+    if (emitted === void 0 || produced === void 0) return [];
+    const discarded = produced - emitted;
+    if (discarded < ctx.thresholds.limitDiscardRows) return [];
+    const rel = child?.relationName ?? "the input";
+    return [
+      makeFinding(limitLargeOffset, ctx, node, {
+        title: `LIMIT discarded ${fmtInt(discarded)} rows before returning ${fmtInt(emitted)}`,
+        detail: `The plan produced ${fmtInt(produced)} rows from ${rel} but the Limit node returned only ${fmtInt(emitted)} \u2014 ${fmtInt(discarded)} rows were generated just to be skipped.`,
+        cause: "OFFSET-style pagination makes Postgres compute and discard every row before the requested page, so deep pages get progressively slower (page N costs O(N)).",
+        remediation: {
+          summary: "Switch to keyset (seek) pagination: filter on the last-seen sort key instead of skipping rows, and keep an index on the sort key so each page is a direct index seek.",
+          steps: [
+            "Order by a unique (or tie-broken) key, e.g. ORDER BY created_at, id.",
+            "Pass the last row's key from the previous page instead of an OFFSET.",
+            "Index the sort key so the WHERE clause seeks directly to the page start."
+          ],
+          commands: [
+            {
+              label: "Keyset pagination instead of OFFSET",
+              sql: "SELECT \u2026 FROM t WHERE (created_at, id) > ($last_created_at, $last_id) ORDER BY created_at, id LIMIT 50;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/queries-limit.html`,
+        meta: { discarded: Math.round(discarded), emitted: Math.round(emitted) }
+      })
+    ];
+  }
+};
+
 // src/advisor/rules/low-cache-hit.ts
 var MIN_READ_BLOCKS = 1e3;
 var lowCacheHit = {
@@ -1927,6 +1980,46 @@ var lowCacheHit = {
   }
 };
 
+// src/advisor/rules/memoize-evictions.ts
+var memoizeEvictions = {
+  id: "PGX_MEMOIZE_EVICTIONS",
+  title: "Memoize cache is thrashing",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Memoize") return [];
+    const hits = node.cacheHits ?? 0;
+    const evictions = node.cacheEvictions ?? 0;
+    const overflows = node.cacheOverflows ?? 0;
+    const thrashing = evictions > hits;
+    if (!thrashing && overflows === 0) return [];
+    return [
+      makeFinding(memoizeEvictions, ctx, node, {
+        title: overflows > 0 ? `Memoize cache overflowed ${fmtInt(overflows)} time(s)` : `Memoize evicted ${fmtInt(evictions)} entries against ${fmtInt(hits)} hits`,
+        detail: `The Memoize cache recorded ${fmtInt(hits)} hits, ${fmtInt(node.cacheMisses ?? 0)} misses, ${fmtInt(evictions)} evictions, and ${fmtInt(overflows)} overflows \u2014 entries are being thrown away before they can be reused.`,
+        cause: "The distinct key values do not fit in the memory Memoize is allowed (derived from work_mem \xD7 hash_mem_multiplier), so the cache churns and the node degenerates into a slower re-executing inner side.",
+        remediation: {
+          summary: "Give the session more cache memory (work_mem / hash_mem_multiplier) so the key space fits, or reduce the number of distinct keys flowing into the Memoize.",
+          steps: [
+            "Estimate the distinct keys: the planner sizes the cache from ndistinct of the join key.",
+            "Raise work_mem (or hash_mem_multiplier on PG 15+) for this workload and re-run.",
+            "If the key space is genuinely huge, an index on the inner side may beat Memoize \u2014 compare with enable_memoize = off."
+          ],
+          commands: [
+            { label: "More cache memory for this session", sql: "SET work_mem = '64MB';" },
+            {
+              label: "Compare the plan without Memoize",
+              sql: "SET enable_memoize = off; EXPLAIN ANALYZE <query>;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html`,
+        meta: { hits, evictions, overflows }
+      })
+    ];
+  }
+};
+
 // src/advisor/rules/nested-loop-large-outer.ts
 var nestedLoopLargeOuter = {
   id: "PGX_NESTED_LOOP_LARGE_OUTER",
@@ -2309,8 +2402,10 @@ var ALL_RULES = [
   seqScanLarge,
   nestedLoopLargeOuter,
   highFilterDiscard,
+  limitLargeOffset,
   sortSpillDisk,
   hashSpillDisk,
+  memoizeEvictions,
   correlatedSubplan,
   rowMisestimate,
   filterCouldBeIndexCond,
@@ -2338,7 +2433,7 @@ function runAdvisor(tree, config = DEFAULT_CONFIG) {
     if (rule.requiresAnalyze && !tree.hasAnalyze) continue;
     if (rule.requiresBuffers && !tree.hasBuffers) continue;
     for (const node of nodes) {
-      for (const finding of rule.check(node, ctx)) diagnostics.push(finding);
+      for (const finding2 of rule.check(node, ctx)) diagnostics.push(finding2);
     }
   }
   diagnostics.sort(bySeverity);
@@ -3235,35 +3330,6 @@ function diffAnalyses(before, after) {
   };
 }
 
-// src/locks/live.ts
-var SQL = `
-SELECT a.pid,
-       a.usename                                        AS "user",
-       a.state,
-       a.wait_event_type                                AS "waitEventType",
-       a.wait_event                                     AS "waitEvent",
-       EXTRACT(EPOCH FROM (now() - a.query_start))      AS "ageSeconds",
-       a.query,
-       pg_blocking_pids(a.pid)                          AS "blockedBy"
-FROM pg_stat_activity a
-WHERE a.backend_type = 'client backend' AND a.pid <> pg_backend_pid()
-ORDER BY cardinality(pg_blocking_pids(a.pid)) DESC, a.query_start NULLS LAST;
-`;
-async function liveLocks(connection, capturedAt) {
-  const rows = await queryReadOnly(connection, SQL);
-  const sessions = rows.map((r) => ({
-    pid: r.pid,
-    user: r.user,
-    state: r.state,
-    waitEventType: r.waitEventType,
-    waitEvent: r.waitEvent,
-    ageSeconds: r.ageSeconds == null ? null : Number(r.ageSeconds),
-    query: r.query,
-    blockedBy: r.blockedBy ?? []
-  }));
-  return { sessions, blocked: sessions.filter((s) => s.blockedBy.length > 0), capturedAt };
-}
-
 // src/server/schema.ts
 var CATALOG_SQL = `
 SELECT n.nspname                                   AS schema,
@@ -3284,7 +3350,7 @@ async function catalog(connection) {
   );
   return rows.map((r) => ({ schema: r.schema, name: r.name, columns: r.columns ?? [] }));
 }
-var SQL2 = `
+var SQL = `
 SELECT c.relname                                    AS relation,
        c.reltuples::bigint                          AS "estRows",
        pg_total_relation_size(c.oid)                AS "totalBytes",
@@ -3295,7 +3361,9 @@ SELECT c.relname                                    AS relation,
        s.last_vacuum                                AS "lastVacuum",
        s.last_autovacuum                            AS "lastAutovacuum",
        s.last_analyze                               AS "lastAnalyze",
-       s.last_autoanalyze                           AS "lastAutoanalyze"
+       s.last_autoanalyze                           AS "lastAutoanalyze",
+       s.n_mod_since_analyze                        AS "modSinceAnalyze",
+       s.n_live_tup                                 AS "liveTup"
 FROM pg_class c
 LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
 WHERE c.relkind IN ('r', 'p') AND c.relname = ANY($1);
@@ -3304,7 +3372,7 @@ var toNum = (v) => v == null ? null : Number(v);
 async function relationStats(connection, relations) {
   const names = [...new Set(relations.filter(Boolean))];
   if (names.length === 0) return [];
-  const rows = await queryReadOnly(connection, SQL2, [names]);
+  const rows = await queryReadOnly(connection, SQL, [names]);
   return rows.map((r) => ({
     relation: r.relation,
     estRows: toNum(r.estRows),
@@ -3314,9 +3382,106 @@ async function relationStats(connection, relations) {
     lastVacuum: r.lastVacuum,
     lastAutovacuum: r.lastAutovacuum,
     lastAnalyze: r.lastAnalyze,
-    lastAutoanalyze: r.lastAutoanalyze
+    lastAutoanalyze: r.lastAutoanalyze,
+    modSinceAnalyze: toNum(r.modSinceAnalyze),
+    liveTup: toNum(r.liveTup)
   }));
 }
+
+// src/diagnostics/stale-stats.ts
+var RULE_ID = "PGX_STALE_STATISTICS";
+var DOCS4 = "https://www.postgresql.org/docs/current/routine-vacuuming.html#VACUUM-FOR-STATISTICS";
+var MIN_ROWS = 1e3;
+function staleStatsFindings(stats, config) {
+  if (config.rules[RULE_ID]?.enabled === false) return [];
+  const severity = config.rules[RULE_ID]?.severity ?? "warn";
+  const ratioLimit = config.thresholds.staleStatsModRatio;
+  const out = [];
+  for (const s of stats) {
+    const rows = s.liveTup ?? s.estRows ?? 0;
+    if (rows < MIN_ROWS) continue;
+    const neverAnalyzed = !s.lastAnalyze && !s.lastAutoanalyze;
+    const modRatio = s.modSinceAnalyze != null && rows > 0 ? s.modSinceAnalyze / rows : 0;
+    if (!neverAnalyzed && modRatio < ratioLimit) continue;
+    out.push(
+      finding(RULE_ID, severity, {
+        title: neverAnalyzed ? `Table ${s.relation} has never been analyzed` : `Planner statistics on ${s.relation} are stale`,
+        detail: neverAnalyzed ? `${s.relation} (~${Math.round(rows).toLocaleString()} rows) has no planner statistics \u2014 pg_stat_user_tables shows no manual or auto ANALYZE.` : `${s.modSinceAnalyze?.toLocaleString()} rows of ${s.relation} changed since its last ANALYZE (${(modRatio * 100).toFixed(0)}% of ~${Math.round(rows).toLocaleString()} live rows).`,
+        cause: "The planner chooses plans from per-table statistics. When they are missing or stale, row estimates drift, which cascades into bad join orders, wrong scan types, and misestimates like PGX_ROW_MISESTIMATE.",
+        remediation: {
+          summary: `Run ANALYZE on ${s.relation}, and if it keeps going stale, lower its autovacuum analyze threshold.`,
+          steps: [
+            "ANALYZE the table now to refresh statistics.",
+            "If the table churns heavily, tune per-table autovacuum settings so auto-analyze keeps up."
+          ],
+          commands: [
+            { label: "Refresh statistics", sql: `ANALYZE ${s.relation};` },
+            {
+              label: "Analyze more eagerly on churny tables",
+              sql: `ALTER TABLE ${s.relation} SET (autovacuum_analyze_scale_factor = 0.02);`
+            }
+          ]
+        },
+        docsUrl: DOCS4,
+        meta: {
+          relation: s.relation,
+          modSinceAnalyze: s.modSinceAnalyze ?? 0,
+          liveTup: s.liveTup ?? 0
+        }
+      })
+    );
+  }
+  return out;
+}
+async function checkStaleStats(connection, result, config) {
+  try {
+    const relations = [
+      ...new Set(
+        flatten(result.tree.root).map((n) => n.relationName).filter((r) => !!r)
+      )
+    ];
+    if (!relations.length) return;
+    appendFindings(result, staleStatsFindings(await relationStats(connection, relations), config));
+  } catch {
+  }
+}
+function appendFindings(result, extra) {
+  if (!extra.length) return;
+  result.diagnostics = [...result.diagnostics, ...extra].sort(bySeverity);
+  result.worstSeverity = result.diagnostics.reduce(
+    (worst, d) => worst === null ? d.severity : maxSeverity(worst, d.severity),
+    null
+  );
+}
+
+// src/locks/live.ts
+var SQL2 = `
+SELECT a.pid,
+       a.usename                                        AS "user",
+       a.state,
+       a.wait_event_type                                AS "waitEventType",
+       a.wait_event                                     AS "waitEvent",
+       EXTRACT(EPOCH FROM (now() - a.query_start))      AS "ageSeconds",
+       a.query,
+       pg_blocking_pids(a.pid)                          AS "blockedBy"
+FROM pg_stat_activity a
+WHERE a.backend_type = 'client backend' AND a.pid <> pg_backend_pid()
+ORDER BY cardinality(pg_blocking_pids(a.pid)) DESC, a.query_start NULLS LAST;
+`;
+async function liveLocks(connection, capturedAt) {
+  const rows = await queryReadOnly(connection, SQL2);
+  const sessions = rows.map((r) => ({
+    pid: r.pid,
+    user: r.user,
+    state: r.state,
+    waitEventType: r.waitEventType,
+    waitEvent: r.waitEvent,
+    ageSeconds: r.ageSeconds == null ? null : Number(r.ageSeconds),
+    query: r.query,
+    blockedBy: r.blockedBy ?? []
+  }));
+  return { sessions, blocked: sessions.filter((s) => s.blockedBy.length > 0), capturedAt };
+}
 function dataDir() {
   return process.env.PGEXPLAIN_DATA_DIR ?? join(homedir(), ".pgexplain");
 }
@@ -3694,6 +3859,7 @@ function apiRoutes(store, config) {
       sql: statement,
       config: config.current
     });
+    await checkStaleStats(connection, result, config.current);
     const report = {
       ...buildReport(result),
       server: { major: exec.caps.major, omitted: exec.omitted }
@@ -3709,7 +3875,11 @@ function apiRoutes(store, config) {
     const afterPlan = body.afterPlan ?? planTextOf(store, body.afterId);
     const before = analyze(beforePlan, { redact: body.redact });
     const after = analyze(afterPlan, { redact: body.redact });
-    return c.json(diffAnalyses(before, after));
+    return c.json({
+      ...diffAnalyses(before, after),
+      beforePlan: serializeNode(before.tree.root),
+      afterPlan: serializeNode(after.tree.root)
+    });
   });
   api.post("/api/export", async (c) => {
     const body = validate(ExportBodySchema, await c.req.json().catch(() => ({})));