pgexplain 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -125,6 +125,10 @@ interface PlanNode {
     diskUsage?: number;
     exactHeapBlocks?: number;
     lossyHeapBlocks?: number;
+    cacheHits?: number;
+    cacheMisses?: number;
+    cacheEvictions?: number;
+    cacheOverflows?: number;
     sharedHitBlocks?: number;
     sharedReadBlocks?: number;
     sharedDirtiedBlocks?: number;
@@ -198,6 +202,8 @@ interface Thresholds {
     jitPct: number;
     triggerPct: number;
     lowCacheHitRatio: number;
+    limitDiscardRows: number;
+    staleStatsModRatio: number;
 }
 interface AnalysisContext {
     tree: PlanTree;
@@ -313,6 +319,8 @@ declare class AppError extends Error {
     readonly exitCode: ExitCode;
     constructor(diagnostic: Diagnostic, exitCode: ExitCode, cause?: unknown);
 }
+/** True when `s` is at least as severe as `threshold` (error ≥ warn ≥ info). */
+declare function severityAtLeast(s: Severity, threshold: Severity): boolean;
 /**
  * Remove secrets from any string before it is logged, shown, or written.
  * Targets:
@@ -360,4 +368,4 @@ interface AnalyzeOptions {
 /** Parse → (redact) → compute metrics → run advisor (+lock advisor) → attach notices. */
 declare function analyze(input: string, options?: AnalyzeOptions): AnalysisResult;
 
-export { type AnalysisContext, type AnalysisResult, type AnalyzeOptions, AppError, DEFAULT_CONFIG, DEFAULT_THRESHOLDS, type Diagnostic, type DiagnosticLocation, type Domain, ExitCode, FORMATS, type Format, JSON_SCHEMA_VERSION, type JitInfo, type NodeMetrics, type PgExplainConfig, type PlanNode, type PlanTree, type RawPlan, type Remediation, type RemediationCommand, type RenderOptions, type Rule, type Severity, type Thresholds, type TriggerInfo, type WorkerStat, analyze, analyzeLocks, bottlenecks, computeMetrics, executionMs, flatten, isFormat, nodeLabel, parseExplain, parseExplainJson, render, runAdvisor, scrubCredentials, walk };
+export { type AnalysisContext, type AnalysisResult, type AnalyzeOptions, AppError, DEFAULT_CONFIG, DEFAULT_THRESHOLDS, type Diagnostic, type DiagnosticLocation, type Domain, ExitCode, FORMATS, type Format, JSON_SCHEMA_VERSION, type JitInfo, type NodeMetrics, type PgExplainConfig, type PlanNode, type PlanTree, type RawPlan, type Remediation, type RemediationCommand, type RenderOptions, type Rule, type Severity, type Thresholds, type TriggerInfo, type WorkerStat, analyze, analyzeLocks, bottlenecks, computeMetrics, executionMs, flatten, isFormat, nodeLabel, parseExplain, parseExplainJson, render, runAdvisor, scrubCredentials, severityAtLeast, walk };

package/dist/index.js

@@ -37,6 +37,9 @@ function bySeverity(a, b) {
 function maxSeverity(a, b) {
   return SEVERITY_RANK[a] <= SEVERITY_RANK[b] ? a : b;
 }
+function severityAtLeast(s, threshold) {
+  return SEVERITY_RANK[s] <= SEVERITY_RANK[threshold];
+}
 function scrubCredentials(input) {
   if (!input) return input;
   return input.replace(/(\b[a-z][a-z0-9+.-]*:\/\/[^:/?#@\s]+:)([^@\s]+)(@)/gi, "$1***$3").replace(/\bpassword\s*=\s*'[^']*'/gi, "password='***'").replace(/(\bpassword\s*=\s*)([^\s&'"]+)/gi, "$1***").replace(/(\bPGPASSWORD\s*=\s*)([^\s&'"]+)/gi, "$1***");
@@ -436,7 +439,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 },
@@ -852,6 +857,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"),
@@ -1199,8 +1208,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 [];
@@ -1519,6 +1531,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 = {
@@ -1565,6 +1618,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",
@@ -1947,8 +2040,10 @@ var ALL_RULES = [
   seqScanLarge,
   nestedLoopLargeOuter,
   highFilterDiscard,
+  limitLargeOffset,
   sortSpillDisk,
   hashSpillDisk,
+  memoizeEvictions,
   correlatedSubplan,
   rowMisestimate,
   filterCouldBeIndexCond,
@@ -2572,6 +2667,6 @@ function planNotices(tree) {
   return notices;
 }
 
-export { AppError, DEFAULT_CONFIG, DEFAULT_THRESHOLDS, ExitCode, FORMATS, JSON_SCHEMA_VERSION, analyze, analyzeLocks, bottlenecks, computeMetrics, executionMs, flatten, isFormat, nodeLabel, parseExplain, parseExplainJson, render, runAdvisor, scrubCredentials, walk };
+export { AppError, DEFAULT_CONFIG, DEFAULT_THRESHOLDS, ExitCode, FORMATS, JSON_SCHEMA_VERSION, analyze, analyzeLocks, bottlenecks, computeMetrics, executionMs, flatten, isFormat, nodeLabel, parseExplain, parseExplainJson, render, runAdvisor, scrubCredentials, severityAtLeast, walk };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map