pgexplain 0.1.0 → 0.3.0

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,12 +439,316 @@ 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 },
   rules: {}
 };
+
+// src/core/parse-text.ts
+var cap = (w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase();
+var numeric = (v) => {
+  const t = v.trim();
+  return /^-?\d+(\.\d+)?$/.test(t) ? Number(t) : t;
+};
+function splitList(s) {
+  const out = [];
+  let depth = 0;
+  let cur = "";
+  for (const ch of s) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      if (cur.trim()) out.push(cur.trim());
+      cur = "";
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+function splitIntoLines(text) {
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  const count = (s, re) => (s.match(re) || []).length;
+  const closingFirst = (s) => {
+    const c = s.indexOf(")");
+    const o = s.indexOf("(");
+    return c !== -1 && c < o;
+  };
+  const sameIndent = (a, b) => a.search(/\S/) === b.search(/\S/);
+  for (const line of lines) {
+    const prev = out[out.length - 1];
+    if (prev && count(prev, /\)/g) !== count(prev, /\(/g)) {
+      out[out.length - 1] += line;
+    } else if (/^(?:Total\s+runtime|Planning(\s+time)?|Execution\s+time|Time|Filter|Output|JIT|Trigger|Settings|Serialization)/i.test(
+      line
+    )) {
+      out.push(line);
+    } else if (/^\S/.test(line) || /^\s*\(/.test(line) || closingFirst(line)) {
+      if (prev) out[out.length - 1] += line;
+      else out.push(line);
+    } else if (prev && /,\s*$/.test(prev) && !sameIndent(prev, line) && !/^\s*->/i.test(line)) {
+      out[out.length - 1] += line;
+    } else {
+      out.push(line);
+    }
+  }
+  return out;
+}
+var estimation = String.raw`\(cost=(\d+\.\d+)\.\.(\d+\.\d+)\s+rows=(\d+)\s+width=(\d+)\)`;
+var actual = String.raw`(?:actual(?:\stime=(\d+\.\d+)\.\.(\d+\.\d+))?\srows=(\d+(?:\.\d+)?)\sloops=(\d+)|(never\s+executed))`;
+var nodeRe = new RegExp(
+  String.raw`^(\s*->\s*|\s*)(Finalize|Simple|Partial)*\s*([^\r\n\t\f\v(]*?)\s*` + String.raw`(?:(?:${estimation}\s+\(${actual}\))|(?:${estimation})|(?:\(${actual}\)))\s*$`
+);
+var subRe = /^((?:Sub|Init)Plan)\s*(?:\d+\s*)?(?:\(returns.*\))?\s*$/;
+var cteRe = /^CTE\s+(\S+)\s*$/;
+var workerRe = /^Worker\s+(\d+):\s+(?:actual(?:\stime=(\d+\.\d+)\.\.(\d+\.\d+))?\srows=(\d+(?:\.\d+)?)\sloops=(\d+)|never\s+executed)(.*)$/;
+var triggerRe = /^Trigger\s+(.*):\s+time=(\d+\.\d+)\s+calls=(\d+)\s*$/;
+var headerRe = /^(QUERY PLAN|-{2,}|#|\(\d+ rows?\))/;
+function splitNodeType(text) {
+  let s = text.trim();
+  let indexName;
+  let relationName;
+  let schema;
+  let alias;
+  const using = s.match(/\susing (\S+)/);
+  if (using?.[1]) {
+    indexName = using[1];
+    s = s.replace(using[0] ?? "", "");
+  }
+  const on = s.match(/\son (\S+?)(?:\s+(\S+))?\s*$/);
+  if (on?.[1]) {
+    let rel = on[1];
+    alias = on[2];
+    const dot = rel.lastIndexOf(".");
+    if (dot !== -1) {
+      schema = rel.slice(0, dot);
+      rel = rel.slice(dot + 1);
+    }
+    relationName = rel;
+    s = s.slice(0, on.index).trim();
+  }
+  const nodeType = s.replace(/^Parallel\s+/, "").trim();
+  if (nodeType === "Bitmap Index Scan" && relationName && !indexName) {
+    indexName = relationName;
+    relationName = void 0;
+    schema = void 0;
+    alias = void 0;
+  }
+  const out = { "Node Type": nodeType };
+  if (relationName) out["Relation Name"] = relationName;
+  if (indexName) out["Index Name"] = indexName;
+  if (schema) out.Schema = schema;
+  if (alias && alias !== relationName) out.Alias = alias;
+  return out;
+}
+function parseSort(text, node) {
+  const m = text.match(/^Sort Method:\s+(.*?)\s+(Memory|Disk):\s+(\S+)kB\s*$/);
+  if (!m?.[1] || !m[2] || m[3] === void 0) return false;
+  node["Sort Method"] = m[1].trim();
+  node["Sort Space Type"] = m[2];
+  node["Sort Space Used"] = Number(m[3]);
+  return true;
+}
+function parseBuffers(text, node) {
+  const m = text.match(/^Buffers:\s+(.*)$/);
+  if (!m?.[1]) return false;
+  for (const group of m[1].split(/,\s+/)) {
+    const g = group.match(/^(shared|temp|local)\s+(.*)$/);
+    if (!g?.[1] || g[2] === void 0) continue;
+    const type = cap(g[1]);
+    for (const kv of g[2].trim().split(/\s+/)) {
+      const [method, value] = kv.split("=");
+      if (method && value !== void 0) node[`${type} ${cap(method)} Blocks`] = Number(value);
+    }
+  }
+  return true;
+}
+function parseWal(text, node) {
+  const m = text.match(/^WAL:\s+(.*)$/);
+  if (!m?.[1]) return false;
+  for (const kv of m[1].trim().split(/\s+/)) {
+    const [k, value] = kv.split("=");
+    if (!k || value === void 0) continue;
+    node[`WAL ${k === "fpi" ? "FPI" : cap(k)}`] = Number(value);
+  }
+  return true;
+}
+function parseIoTimings(text, node) {
+  const m = text.match(/^I\/O Timings:\s+(.*)$/);
+  if (!m?.[1]) return false;
+  const read = m[1].match(/(?:^|\s)read=(\d+(?:\.\d+)?)/);
+  const write = m[1].match(/(?:^|\s)write=(\d+(?:\.\d+)?)/);
+  if (read?.[1]) node["I/O Read Time"] = Number(read[1]);
+  if (write?.[1]) node["I/O Write Time"] = Number(write[1]);
+  return true;
+}
+function parseSettings(text) {
+  const out = {};
+  for (const pair of splitList(text)) {
+    const m = pair.match(/^(\S+)\s*=\s*(.*)$/);
+    if (m?.[1] && m[2] !== void 0) out[m[1]] = m[2].replace(/^'|'$/g, "");
+  }
+  return out;
+}
+var LIST_KEYS = /* @__PURE__ */ new Set(["Output", "Sort Key", "Presorted Key", "Group Key"]);
+function parseTextToStatements(input) {
+  const statements = [];
+  let stmt = null;
+  let stack = [];
+  let current = null;
+  let jit = null;
+  const finish = () => {
+    if (stmt?.Plan) statements.push(stmt);
+    stmt = null;
+    stack = [];
+    current = null;
+    jit = null;
+  };
+  for (let raw of splitIntoLines(input)) {
+    raw = raw.replace(/"\s*$/, "").replace(/^\s*"/, "").replace(/\t/g, "    ");
+    const depth = raw.match(/^\s*/)?.[0].length ?? 0;
+    const line = raw.slice(depth);
+    if (line === "" || headerRe.test(line)) {
+      if (line === "" && stmt?.Plan) finish();
+      continue;
+    }
+    const nodeM = nodeRe.exec(line);
+    const subM = subRe.exec(line);
+    const cteM = cteRe.exec(line);
+    if (nodeM && !subM && !cteM) {
+      if (!stmt) stmt = {};
+      jit = null;
+      const node = { ...splitNodeType(nodeM[3] ?? "") };
+      if (nodeM[2]) node["Partial Mode"] = nodeM[2];
+      const startup = nodeM[4] ?? nodeM[13];
+      const total = nodeM[5] ?? nodeM[14];
+      if (startup && total) {
+        node["Startup Cost"] = Number(startup);
+        node["Total Cost"] = Number(total);
+        node["Plan Rows"] = Number(nodeM[6] ?? nodeM[15]);
+        node["Plan Width"] = Number(nodeM[7] ?? nodeM[16]);
+      }
+      const st = nodeM[8] ?? nodeM[17];
+      const tt = nodeM[9] ?? nodeM[18];
+      if (st && tt) {
+        node["Actual Startup Time"] = Number(st);
+        node["Actual Total Time"] = Number(tt);
+      }
+      const rows = nodeM[10] ?? nodeM[19];
+      const loops = nodeM[11] ?? nodeM[20];
+      if (rows && loops) {
+        node["Actual Rows"] = Number(rows);
+        node["Actual Loops"] = Number(loops);
+      }
+      if (nodeM[12] ?? nodeM[21]) {
+        node["Actual Loops"] = 0;
+        node["Actual Rows"] = 0;
+      }
+      stack = stack.filter((f) => f.depth < depth);
+      const parent = stack[stack.length - 1];
+      if (!parent) {
+        stmt.Plan = node;
+      } else {
+        if (parent.rel) {
+          node["Parent Relationship"] = parent.rel;
+          if (parent.name) node["Subplan Name"] = parent.name;
+        }
+        const parentNode = parent.node;
+        if (!parentNode.Plans) parentNode.Plans = [];
+        parentNode.Plans.push(node);
+      }
+      stack.push({ depth, node });
+      current = node;
+      continue;
+    }
+    if (subM || cteM) {
+      stack = stack.filter((f) => f.depth < depth);
+      const parent = stack[stack.length - 1];
+      if (!parent) continue;
+      if (cteM?.[1])
+        stack.push({ depth, node: parent.node, rel: "InitPlan", name: `CTE ${cteM[1]}` });
+      else if (subM?.[1])
+        stack.push({
+          depth,
+          node: parent.node,
+          rel: subM[1],
+          name: (subM[0] ?? "").trim()
+        });
+      continue;
+    }
+    const workerM = workerRe.exec(line);
+    if (workerM && current) {
+      const worker = { "Worker Number": Number(workerM[1]) };
+      if (workerM[2] && workerM[3]) {
+        worker["Actual Startup Time"] = Number(workerM[2]);
+        worker["Actual Total Time"] = Number(workerM[3]);
+      }
+      if (workerM[4] && workerM[5]) {
+        worker["Actual Rows"] = Number(workerM[4]);
+        worker["Actual Loops"] = Number(workerM[5]);
+      }
+      if (!Array.isArray(current.Workers)) current.Workers = [];
+      current.Workers.push(worker);
+      continue;
+    }
+    const trigM = triggerRe.exec(line);
+    if (trigM && stmt) {
+      if (!Array.isArray(stmt.Triggers)) stmt.Triggers = [];
+      stmt.Triggers.push({
+        "Trigger Name": trigM[1],
+        Time: Number(trigM[2]),
+        Calls: Number(trigM[3])
+      });
+      continue;
+    }
+    const kv = line.match(/^([^:]+):\s*(.*)$/);
+    if (!kv?.[1]) continue;
+    const key = kv[1].trim();
+    const value = (kv[2] ?? "").trim();
+    if (key === "JIT") {
+      jit = {};
+      if (stmt) stmt.JIT = jit;
+      continue;
+    }
+    if (jit) {
+      if (key === "Functions") jit.Functions = Number(value);
+      else if (key === "Timing") {
+        const timing = {};
+        for (const part of value.split(/,\s*/)) {
+          const t = part.match(/^(\S+)\s+(\d+\.\d+)\s*ms/);
+          if (t?.[1]) timing[t[1]] = Number(t[2]);
+        }
+        jit.Timing = timing;
+      }
+      continue;
+    }
+    if (key === "Planning Time") {
+      if (stmt) stmt["Planning Time"] = parseFloat(value);
+      continue;
+    }
+    if (key === "Execution Time" || key === "Total runtime") {
+      if (stmt) stmt["Execution Time"] = parseFloat(value);
+      continue;
+    }
+    if (key === "Settings") {
+      if (stmt) stmt.Settings = parseSettings(value);
+      continue;
+    }
+    if (!current) continue;
+    if (parseSort(line, current) || parseBuffers(line, current) || parseWal(line, current) || parseIoTimings(line, current)) {
+      continue;
+    }
+    current[key] = LIST_KEYS.has(key) ? splitList(value) : numeric(value);
+  }
+  finish();
+  return statements;
+}
 var PlanNodeSchema = z.looseObject({
   "Node Type": z.string(),
   get Plans() {
@@ -550,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"),
@@ -561,8 +872,13 @@ function normalizeNode(raw, nextId) {
     ioReadTime: num(raw, "I/O Read Time"),
     ioWriteTime: num(raw, "I/O Write Time"),
     workersPlanned: num(raw, "Workers Planned"),
-    workersLaunched: num(raw, "Workers Launched")
+    workersLaunched: num(raw, "Workers Launched"),
+    walRecords: num(raw, "WAL Records"),
+    walBytes: num(raw, "WAL Bytes"),
+    walFpi: num(raw, "WAL FPI")
   });
+  const workers = parseWorkers(raw.Workers);
+  if (workers.length) node.workers = workers;
   const childPlans = raw.Plans;
   if (Array.isArray(childPlans)) {
     for (const child of childPlans) {
@@ -576,6 +892,24 @@ function assign(target, fields) {
     if (v !== void 0) target[k] = v;
   }
 }
+function parseWorkers(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const w of raw) {
+    const r = w;
+    const number = num(r, "Worker Number");
+    if (number === void 0) continue;
+    const stat = { number };
+    assign(stat, {
+      actualRows: num(r, "Actual Rows"),
+      actualLoops: num(r, "Actual Loops"),
+      actualStartupTime: num(r, "Actual Startup Time"),
+      actualTotalTime: num(r, "Actual Total Time")
+    });
+    out.push(stat);
+  }
+  return out;
+}
 function parseTriggers(raw) {
   if (!Array.isArray(raw)) return [];
   return raw.map((t) => {
@@ -609,6 +943,36 @@ function parseJit(raw) {
   }
   return jit;
 }
+function statementToTree(stmt) {
+  let id = 0;
+  const root = normalizeNode(stmt.Plan, () => id++);
+  const hasAnalyze = root.actualLoops !== void 0 || stmt["Execution Time"] !== void 0;
+  const hasBuffers = root.sharedHitBlocks !== void 0 || root.sharedReadBlocks !== void 0;
+  const tree = {
+    root,
+    triggers: parseTriggers(stmt.Triggers),
+    hasAnalyze,
+    hasBuffers,
+    raw: stmt.Plan
+  };
+  if (typeof stmt["Planning Time"] === "number") tree.planningTime = stmt["Planning Time"];
+  if (typeof stmt["Execution Time"] === "number") tree.executionTime = stmt["Execution Time"];
+  const serialization = stmt.Serialization;
+  if (serialization && typeof serialization === "object") {
+    const t = num(serialization, "Time");
+    if (t !== void 0) tree.serializationTime = t;
+  }
+  const jit = parseJit(stmt.JIT);
+  if (jit) tree.jit = jit;
+  if (stmt.Settings) tree.settings = stmt.Settings;
+  return tree;
+}
+function parseExplain(input) {
+  return /^\s*[[{]/.test(input) ? parseExplainJson(input) : parseExplainText(input);
+}
+function parseExplainText(input) {
+  return parseTextToStatements(input).map(statementToTree);
+}
 function parseExplainJson(input) {
   const json = parseJsonWithLocation(input);
   let candidate = json;
@@ -623,25 +987,7 @@ function parseExplainJson(input) {
       location: { kind: "input" }
     });
   }
-  return result.data.map((stmt) => {
-    let id = 0;
-    const root = normalizeNode(stmt.Plan, () => id++);
-    const hasAnalyze = root.actualLoops !== void 0 || stmt["Execution Time"] !== void 0;
-    const hasBuffers = root.sharedHitBlocks !== void 0 || root.sharedReadBlocks !== void 0;
-    const tree = {
-      root,
-      triggers: parseTriggers(stmt.Triggers),
-      hasAnalyze,
-      hasBuffers,
-      raw: stmt.Plan
-    };
-    if (stmt["Planning Time"] !== void 0) tree.planningTime = stmt["Planning Time"];
-    if (stmt["Execution Time"] !== void 0) tree.executionTime = stmt["Execution Time"];
-    const jit = parseJit(stmt.JIT);
-    if (jit) tree.jit = jit;
-    if (stmt.Settings) tree.settings = stmt.Settings;
-    return tree;
-  });
+  return result.data.map((stmt) => statementToTree(stmt));
 }
 function walk(node, visit) {
   visit(node);
@@ -706,6 +1052,31 @@ function executionMs(tree) {
 function bottlenecks(tree, n = 5) {
   return flatten(tree.root).filter((node) => node.metrics.selfMs !== void 0).sort((a, b) => (b.metrics.selfMs ?? 0) - (a.metrics.selfMs ?? 0)).slice(0, n);
 }
+function aggregateStats(tree) {
+  const total = executionMs(tree) ?? 0;
+  const groupBy = (keyOf) => {
+    const acc = /* @__PURE__ */ new Map();
+    for (const n of flatten(tree.root)) {
+      const key = keyOf(n);
+      if (!key) continue;
+      const e = acc.get(key) ?? { count: 0, selfMs: 0 };
+      e.count++;
+      e.selfMs += n.metrics.selfMs ?? 0;
+      acc.set(key, e);
+    }
+    return [...acc.entries()].map(([key, e]) => ({
+      key,
+      count: e.count,
+      selfMs: e.selfMs,
+      pctOfTotal: total > 0 ? 100 * e.selfMs / total : 0
+    })).sort((a, b) => b.selfMs - a.selfMs || b.count - a.count);
+  };
+  return {
+    byNodeType: groupBy((n) => n.nodeType),
+    byRelation: groupBy((n) => n.relationName),
+    byIndex: groupBy((n) => n.indexName)
+  };
+}
 function nodeLabel(node) {
   let label = node.nodeType;
   if (node.indexName && node.relationName)
@@ -837,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 [];
@@ -1157,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 = {
@@ -1203,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",
@@ -1290,8 +1745,8 @@ var rowMisestimate = {
     const target = rel ?? "the underlying table";
     const under = estimateDirection === "under";
     const direction = under ? "underestimate" : "overestimate";
-    const actual = totalRows ?? 0;
-    const detail = `Postgres estimated ${fmtInt(node.planRows)} rows but ${fmtInt(actual)} were produced \u2014 a ${fmtInt(factor)}x ${direction}${onRel}.`;
+    const actual2 = totalRows ?? 0;
+    const detail = `Postgres estimated ${fmtInt(node.planRows)} rows but ${fmtInt(actual2)} were produced \u2014 a ${fmtInt(factor)}x ${direction}${onRel}.`;
     return [
       makeFinding(rowMisestimate, ctx, node, {
         // Severity: underestimates are the dangerous ones (under-sized joins/memory).
@@ -1326,7 +1781,7 @@ ANALYZE ${rel ?? "<relation>"};`
         docsUrl: `${DOCS2}/planner-stats.html`,
         meta: {
           estimatedRows: Math.round(node.planRows),
-          actualRows: Math.round(actual),
+          actualRows: Math.round(actual2),
           factor,
           direction: estimateDirection
         }
@@ -1585,8 +2040,10 @@ var ALL_RULES = [
   seqScanLarge,
   nestedLoopLargeOuter,
   highFilterDiscard,
+  limitLargeOffset,
   sortSpillDisk,
   hashSpillDisk,
+  memoizeEvictions,
   correlatedSubplan,
   rowMisestimate,
   filterCouldBeIndexCond,
@@ -1671,6 +2128,138 @@ function redactPlanTree(tree) {
   walk(tree.root, redactNode);
 }
 
+// src/locks/advisor.ts
+var DOCS3 = "https://www.postgresql.org/docs/current";
+function analyzeLocks(sql, tree) {
+  const code = stripSql(sql);
+  const upper = code.toUpperCase();
+  const kw = (code.trim().split(/\s+/)[0] ?? "").toUpperCase();
+  const out = [];
+  const add = (id, severity, parts) => {
+    out.push({
+      code: id,
+      domain: "plan",
+      severity,
+      title: parts.title,
+      detail: parts.detail,
+      cause: parts.cause,
+      remediation: { summary: parts.fix, commands: parts.commands },
+      docsUrl: `${DOCS3}/explicit-locking.html`
+    });
+  };
+  if (/\bVACUUM\s+FULL\b/.test(upper) || /\bCLUSTER\b/.test(upper) || /\bALTER\s+TABLE\b[\s\S]*\b(TYPE|SET\s+DATA\s+TYPE)\b/.test(upper)) {
+    add("PGX_LOCK_TABLE_REWRITE", "error", {
+      title: "Operation rewrites the table under an ACCESS EXCLUSIVE lock",
+      detail: "VACUUM FULL / CLUSTER / a column-type change rewrites the whole table and holds ACCESS EXCLUSIVE for the duration.",
+      cause: "ACCESS EXCLUSIVE blocks every reader and writer until the rewrite finishes \u2014 an outage on a busy table.",
+      fix: "Avoid the full rewrite: use pg_repack for bloat instead of VACUUM FULL/CLUSTER; for type changes, add a new column, backfill in batches, and swap. Always do rewrites off-peak with a lock_timeout.",
+      commands: [{ label: "Bound the wait", sql: "SET lock_timeout = '3s';" }]
+    });
+  }
+  if (/\bCREATE\s+(UNIQUE\s+)?INDEX\b/.test(upper) && !/\bCONCURRENTLY\b/.test(upper)) {
+    add("PGX_DDL_NO_CONCURRENTLY", "warn", {
+      title: "CREATE INDEX without CONCURRENTLY blocks writes",
+      detail: "A plain CREATE INDEX takes a SHARE lock, blocking all writes to the table until the build completes.",
+      cause: "On a large or busy table the build can take minutes, during which inserts/updates/deletes are blocked.",
+      fix: "Build the index online with CONCURRENTLY (note: it cannot run inside a transaction and may leave an INVALID index on failure, which you then drop and recreate).",
+      commands: [{ label: "Build online", sql: "CREATE INDEX CONCURRENTLY ON <table> (<cols>);" }]
+    });
+  }
+  if (/\bDROP\s+INDEX\b/.test(upper) && !/\bCONCURRENTLY\b/.test(upper)) {
+    add("PGX_DROP_INDEX_NO_CONCURRENTLY", "warn", {
+      title: "DROP INDEX without CONCURRENTLY takes ACCESS EXCLUSIVE",
+      detail: "A plain DROP INDEX locks the table with ACCESS EXCLUSIVE.",
+      cause: "Readers and writers block until the drop completes.",
+      fix: "Use DROP INDEX CONCURRENTLY to avoid blocking.",
+      commands: [{ label: "Drop online", sql: "DROP INDEX CONCURRENTLY <index>;" }]
+    });
+  }
+  if (/\bTRUNCATE\b/.test(upper)) {
+    add("PGX_LOCK_TRUNCATE", "info", {
+      title: "TRUNCATE takes an ACCESS EXCLUSIVE lock",
+      detail: "TRUNCATE briefly locks the table with ACCESS EXCLUSIVE.",
+      cause: "It is fast (no row scan) but still blocks all access while it runs and is transactional.",
+      fix: "Fine for maintenance windows; on a hot table, set a lock_timeout so it fails fast instead of queueing behind/ahead of other transactions.",
+      commands: [{ label: "Bound the wait", sql: "SET lock_timeout = '3s';" }]
+    });
+  }
+  if (/\bLOCK\s+TABLE\b/.test(upper)) {
+    add("PGX_LOCK_TABLE_EXPLICIT", "info", {
+      title: "Explicit LOCK TABLE",
+      detail: "An explicit LOCK TABLE acquires the named lock mode for the rest of the transaction.",
+      cause: "Holding a strong lock longer than necessary blocks other sessions.",
+      fix: "Use the lowest lock mode that suffices and keep the transaction short."
+    });
+  }
+  if (/\bFOR\s+(UPDATE|SHARE|NO\s+KEY\s+UPDATE|KEY\s+SHARE)\b/.test(upper) && !/\bLIMIT\b/.test(upper)) {
+    add("PGX_SELECT_FOR_UPDATE_UNBOUNDED", "warn", {
+      title: "Row-locking SELECT without a LIMIT",
+      detail: "SELECT \u2026 FOR UPDATE/SHARE locks every row it matches, held until the transaction ends.",
+      cause: "Locking an unbounded set increases contention and deadlock risk with concurrent updaters.",
+      fix: "Bound the set with a deterministic ORDER BY + LIMIT (and process in batches); a consistent lock order also avoids deadlocks.",
+      commands: [{ label: "Bound + order", sql: "SELECT \u2026 ORDER BY id FOR UPDATE LIMIT 100;" }]
+    });
+  }
+  if (kw === "UPDATE" || kw === "DELETE") {
+    if (!/\bWHERE\b/.test(upper)) {
+      add("PGX_WRITE_NO_WHERE", "warn", {
+        title: `${kw} without a WHERE clause locks every row`,
+        detail: `This ${kw} touches the whole table, taking a row lock on every row until commit.`,
+        cause: "All rows are locked for the transaction's duration, blocking concurrent writers and bloating the table.",
+        fix: "Add a WHERE clause; for large rewrites, update in batches (e.g. by primary-key ranges) and commit between batches."
+      });
+    } else if (tree && hasSeqScanOnTarget(tree, targetTable(code, kw))) {
+      const rel = targetTable(code, kw);
+      add("PGX_UPDATE_UNINDEXED_PREDICATE", "warn", {
+        title: `${kw} scans ${rel ?? "the table"} sequentially to find rows`,
+        detail: `The plan uses a Seq Scan on ${rel ?? "the target table"}, so the ${kw} reads (and locks the touched rows of) the whole table.`,
+        cause: "An unindexed predicate means more rows scanned and locked, and the locks are held until commit.",
+        fix: `Index the ${kw}'s WHERE columns so it finds rows via an index and locks only what it changes.`,
+        commands: [
+          {
+            label: "Index the predicate",
+            sql: `CREATE INDEX ON ${rel ?? "<table>"} (<where columns>);`
+          }
+        ]
+      });
+    }
+  }
+  if (/^(ALTER|CREATE|DROP)\b/.test(kw) && !/\bCONCURRENTLY\b/.test(upper) && !/\bSET\s+LOCK_TIMEOUT\b/.test(upper)) {
+    add("PGX_DDL_NO_LOCK_TIMEOUT", "warn", {
+      title: "DDL without a lock_timeout can stall the whole table",
+      detail: "This DDL needs a strong lock; if it waits behind a long transaction, every query that arrives after it also queues behind the DDL.",
+      cause: "A blocked ACCESS EXCLUSIVE request sits at the head of the lock queue and blocks new readers/writers too.",
+      fix: "Set a short lock_timeout before the DDL and retry, so it fails fast instead of forming a queue.",
+      commands: [
+        {
+          label: "Fail fast, then retry",
+          sql: "SET lock_timeout = '3s';\n-- run the DDL; on timeout, retry later"
+        }
+      ]
+    });
+  }
+  return out;
+}
+function stripSql(sql) {
+  return sql.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\n]*/g, " ").replace(/'(?:[^']|'')*'/g, "''").replace(/"(?:[^"]|"")*"/g, '"x"');
+}
+function targetTable(code, kw) {
+  const re = kw === "DELETE" ? /\bDELETE\s+FROM\s+([A-Za-z_][\w.]*)/i : /\bUPDATE\s+(?:ONLY\s+)?([A-Za-z_][\w.]*)/i;
+  const m = re.exec(code);
+  return m?.[1];
+}
+function hasSeqScanOnTarget(tree, table) {
+  let found = false;
+  walk(tree.root, (n) => {
+    if (n.nodeType === "Seq Scan" && (!table || n.relationName === bareName(table))) found = true;
+  });
+  return found;
+}
+function bareName(qualified) {
+  const parts = qualified.split(".");
+  return parts[parts.length - 1] ?? qualified;
+}
+
 // src/report/tree.ts
 function treeLines(tree, glyphs) {
   const lines = [];
@@ -1711,21 +2300,28 @@ function nodeSummary(node) {
 // src/report/json.ts
 var JSON_SCHEMA_VERSION = 1;
 function renderJson(result, pretty = true) {
+  return JSON.stringify(buildReport(result), null, pretty ? 2 : 0);
+}
+function buildReport(result) {
   const { tree, diagnostics, bottlenecks: bottlenecks2 } = result;
   const counts = { error: 0, warn: 0, info: 0 };
   for (const d of diagnostics) counts[d.severity]++;
-  const report = {
+  return {
     schemaVersion: JSON_SCHEMA_VERSION,
     verdict: result.verdict,
     worstSeverity: result.worstSeverity,
     summary: {
       planningTimeMs: tree.planningTime ?? null,
       executionTimeMs: executionMs(tree) ?? null,
+      serializationTimeMs: tree.serializationTime ?? null,
       hasAnalyze: tree.hasAnalyze,
       hasBuffers: tree.hasBuffers,
       nodeCount: flatten(tree.root).length,
       findings: counts
     },
+    triggers: tree.triggers,
+    jit: tree.jit ?? null,
+    settings: tree.settings ?? null,
     diagnostics,
     bottlenecks: bottlenecks2.filter((n) => (n.metrics.selfMs ?? 0) > 0).map((n) => ({
       id: n.id,
@@ -1736,9 +2332,9 @@ function renderJson(result, pretty = true) {
       pctOfTotal: n.metrics.pctOfTotal ?? null,
       totalRows: n.metrics.totalRows ?? null
     })),
+    stats: aggregateStats(tree),
     plan: serializeNode(tree.root)
   };
-  return JSON.stringify(report, null, pretty ? 2 : 0);
 }
 function serializeNode(node) {
   const { children, metrics, raw, ...fields } = node;
@@ -2031,14 +2627,15 @@ function render(result, opts) {
 
 // src/index.ts
 function analyze(input, options = {}) {
-  const trees = parseExplainJson(input);
+  const trees = parseExplain(input);
   const tree = selectStatement(trees, options.statement);
   if (options.redact) redactPlanTree(tree);
   computeMetrics(tree);
   const result = runAdvisor(tree, options.config ?? DEFAULT_CONFIG);
-  const notices = planNotices(tree);
-  if (notices.length) {
-    result.diagnostics = [...result.diagnostics, ...notices].sort(bySeverity);
+  const extra = planNotices(tree);
+  if (options.sql) extra.push(...analyzeLocks(options.sql, tree));
+  if (extra.length) {
+    result.diagnostics = [...result.diagnostics, ...extra].sort(bySeverity);
     result.worstSeverity = result.diagnostics.reduce(
       (worst, d) => worst === null ? d.severity : maxSeverity(worst, d.severity),
       null
@@ -2070,6 +2667,6 @@ function planNotices(tree) {
   return notices;
 }
 
-export { AppError, DEFAULT_CONFIG, DEFAULT_THRESHOLDS, ExitCode, FORMATS, JSON_SCHEMA_VERSION, analyze, bottlenecks, computeMetrics, executionMs, flatten, isFormat, nodeLabel, 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