pgexplain 0.1.0 → 0.2.0

package/dist/cli.js

@@ -4,10 +4,12 @@ import { readFile, writeFile, stat, readdir } from 'fs/promises';
 import { join } from 'path';
 import { z } from 'zod';
 import pc from 'picocolors';
+import { tmpdir } from 'os';
+import { spawn } from 'child_process';
 
 // package.json
 var package_default = {
-  version: "0.1.0"};
+  version: "0.2.0"};
 
 // src/diagnostics/diagnostic.ts
 var AppError = class extends Error {
@@ -482,6 +484,308 @@ async function loadConfig(explicitPath, cwd = process.cwd()) {
   }
   return { ...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 write2 = m[1].match(/(?:^|\s)write=(\d+(?:\.\d+)?)/);
+  if (read?.[1]) node["I/O Read Time"] = Number(read[1]);
+  if (write2?.[1]) node["I/O Write Time"] = Number(write2[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() {
@@ -601,8 +905,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) {
@@ -616,6 +925,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 stat2 = { number };
+    assign(stat2, {
+      actualRows: num(r, "Actual Rows"),
+      actualLoops: num(r, "Actual Loops"),
+      actualStartupTime: num(r, "Actual Startup Time"),
+      actualTotalTime: num(r, "Actual Total Time")
+    });
+    out.push(stat2);
+  }
+  return out;
+}
 function parseTriggers(raw) {
   if (!Array.isArray(raw)) return [];
   return raw.map((t) => {
@@ -649,6 +976,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;
@@ -663,25 +1020,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);
@@ -746,6 +1085,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)
@@ -1330,8 +1694,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).
@@ -1366,7 +1730,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
         }
@@ -1711,6 +2075,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 = [];
@@ -1751,21 +2247,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,
@@ -1776,9 +2279,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;
@@ -2074,14 +2577,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
@@ -2163,6 +2667,50 @@ async function resolvePlanInput(file) {
   if (!text.trim()) throw opError("PGX_EMPTY_INPUT");
   return text;
 }
+
+// src/util/log.ts
+var level = "normal";
+function setLogLevel(l) {
+  level = l;
+}
+function isDebug() {
+  return level === "debug";
+}
+function write(msg) {
+  process.stderr.write(`${msg}
+`);
+}
+function logInfo(msg) {
+  if (level !== "quiet") write(msg);
+}
+function logVerbose(msg) {
+  if (level === "verbose" || level === "debug") write(msg);
+}
+function logError(msg) {
+  write(msg);
+}
+function browserCommand(platform) {
+  if (platform === "darwin") return "open";
+  if (platform === "win32") return "start";
+  return "xdg-open";
+}
+function openInBrowser(target, platform = process.platform) {
+  const cmd = browserCommand(platform);
+  try {
+    const child = spawn(cmd, [target], {
+      stdio: "ignore",
+      detached: true,
+      shell: platform === "win32"
+      // `start` is a shell builtin
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+
+// src/commands/emit.ts
 async function emit(result, opts) {
   configureColor(opts.format === "terminal" ? opts.color : "never");
   const text = render(result, {
@@ -2173,6 +2721,12 @@ async function emit(result, opts) {
   });
   if (opts.output) {
     await writeFile(opts.output, text);
+    if (opts.format === "html" && opts.openHtml) openInBrowser(opts.output);
+  } else if (opts.format === "html" && opts.openHtml) {
+    const file = join(tmpdir(), `pg-explain-${Date.now()}.html`);
+    await writeFile(file, text);
+    logInfo(`Opened HTML report: ${file}`);
+    openInBrowser(file);
   } else {
     process.stdout.write(text.endsWith("\n") ? text : `${text}
 `);
@@ -2499,28 +3053,6 @@ async function readPlan(path) {
   }
 }
 
-// src/util/log.ts
-var level = "normal";
-function setLogLevel(l) {
-  level = l;
-}
-function isDebug() {
-  return level === "debug";
-}
-function write(msg) {
-  process.stderr.write(`${msg}
-`);
-}
-function logInfo(msg) {
-  if (level !== "quiet") write(msg);
-}
-function logVerbose(msg) {
-  if (level === "verbose" || level === "debug") write(msg);
-}
-function logError(msg) {
-  write(msg);
-}
-
 // src/db/version.ts
 function capabilities(versionNum) {
   const major = Math.floor(versionNum / 1e4);
@@ -2742,6 +3274,67 @@ async function runExplain(opts) {
 function msInt(ms) {
   return Math.max(0, Math.floor(ms));
 }
+async function explainScript(connection, units, opts) {
+  const ca = connection.sslrootcert ? await readFile(connection.sslrootcert, "utf8").catch(() => void 0) : void 0;
+  const client = await newClient(buildClientConfig(connection, ca));
+  try {
+    await client.connect();
+  } catch (err) {
+    throw mapConnectError(err);
+  }
+  try {
+    const caps = capabilities(await fetchVersionNum(client));
+    await client.query("BEGIN");
+    const results = [];
+    try {
+      await client.query(`SET LOCAL statement_timeout = ${msInt(opts.statementTimeoutMs)}`);
+      await client.query(`SET LOCAL lock_timeout = ${msInt(opts.lockTimeoutMs)}`);
+      await client.query("SET LOCAL transaction_read_only = on");
+      for (const unit of units) {
+        const flags = {
+          analyze: false,
+          // never execute
+          buffers: false,
+          // BUFFERS requires ANALYZE pre-16
+          verbose: opts.verbose ?? false,
+          settings: opts.settings ?? false,
+          wal: false,
+          timing: false,
+          costs: true,
+          summary: false,
+          genericPlan: caps.genericPlan && /\$\d+/.test(unit.sql),
+          compat: true
+          // auto-omit anything the server is too old for
+        };
+        try {
+          const { prefix } = buildExplain(flags, caps);
+          const res = await client.query(`${prefix} ${unit.sql}`);
+          const r = { label: unit.label, planJson: extractPlanJson(res.rows) };
+          if (unit.loopNote) r.loopNote = unit.loopNote;
+          results.push(r);
+        } catch (err) {
+          const diag = err instanceof AppError ? err.diagnostic : mapQueryError(err).diagnostic;
+          const r = { label: unit.label, error: diag };
+          if (unit.loopNote) r.loopNote = unit.loopNote;
+          results.push(r);
+          await client.query("ROLLBACK").catch(() => {
+          });
+          await client.query("BEGIN").catch(() => {
+          });
+          await client.query("SET LOCAL transaction_read_only = on").catch(() => {
+          });
+        }
+      }
+      return { units: results, caps };
+    } finally {
+      await client.query("ROLLBACK").catch(() => {
+      });
+    }
+  } finally {
+    await client.end().catch(() => {
+    });
+  }
+}
 async function fetchVersionNum(client) {
   try {
     const res = await client.query("SHOW server_version_num");
@@ -2791,7 +3384,9 @@ function mapQueryError(err) {
   if (err instanceof AppError) return err;
   const e = asPgError(err);
   const msg = e.message ?? "";
-  const meta = e.code ? { sqlState: e.code } : void 0;
+  const meta = {};
+  if (e.code) meta.sqlState = e.code;
+  if (e.position) meta.position = Number(e.position);
   switch (e.code) {
     case "57014":
       return /statement timeout/i.test(msg) ? opError("PGX_STATEMENT_TIMEOUT", { detail: msg, meta }, err) : opError("PGX_QUERY_CANCELED", { detail: msg, meta }, err);
@@ -2811,34 +3406,326 @@ function mapQueryError(err) {
   }
 }
 
+// src/sql/extract.ts
+var DML = /* @__PURE__ */ new Set(["SELECT", "INSERT", "UPDATE", "DELETE", "MERGE", "VALUES", "TABLE", "WITH"]);
+function classifyStatement(sql) {
+  const kw = firstKeyword(sql);
+  if (!kw) return "empty";
+  if (kw === "DO") return "do-block";
+  if (DML.has(kw) || kw === "EXECUTE") return "explainable";
+  return "utility";
+}
+function extractAnalyzableUnits(sql) {
+  const units = [];
+  for (const stmt of splitStatements(sql)) {
+    const cls = classifyStatement(stmt);
+    if (cls === "empty") continue;
+    if (cls === "explainable") {
+      units.push({ kind: "explainable", label: unitLabel(stmt), sql: stmt });
+    } else if (cls === "do-block") {
+      units.push(...extractFromDo(stmt));
+    } else {
+      const kw = firstKeyword(stmt);
+      units.push({
+        kind: "skipped",
+        label: `${kw} \u2026`,
+        reason: `EXPLAIN cannot analyze a ${kw} statement (it is a utility/transaction-control command, not an optimizable query).`
+      });
+    }
+  }
+  return units;
+}
+function extractFromDo(doSql) {
+  const body = dollarBody(doSql);
+  if (body === null) {
+    return [
+      { kind: "skipped", label: "DO block", reason: "Could not find the block body ($$ \u2026 $$)." }
+    ];
+  }
+  const out = [];
+  for (const frag of splitStatements(body)) {
+    const stripped = stripControl(frag);
+    if (!stripped) continue;
+    const kw = firstKeyword(stripped.sql);
+    if (kw === "EXECUTE") {
+      out.push({
+        kind: "skipped",
+        label: `${stripped.context}EXECUTE (dynamic SQL)`,
+        reason: "Dynamic SQL built at runtime \u2014 the statement text isn't known statically, so it can't be analyzed."
+      });
+      continue;
+    }
+    if (DML.has(kw)) {
+      const unit = {
+        kind: "explainable",
+        label: stripped.context + unitLabel(stripped.sql),
+        sql: stripped.sql
+      };
+      if (stripped.loop) unit.loopNote = "runs once per loop iteration in the block";
+      out.push(unit);
+    }
+  }
+  if (out.length === 0) {
+    out.push({
+      kind: "skipped",
+      label: "DO block",
+      reason: "No top-level DML statements found to analyze."
+    });
+  }
+  return out;
+}
+function stripControl(frag) {
+  let rest = frag;
+  let context = "";
+  let loop = false;
+  for (let guard = 0; guard < 8; guard++) {
+    rest = rest.replace(/^\s+/, "");
+    const masked = maskNonCode(rest);
+    const kw2 = (/^[A-Za-z_]+/.exec(masked)?.[0] ?? "").toUpperCase();
+    if (kw2 === "IF" || kw2 === "ELSIF") {
+      const then = /\bTHEN\b/i.exec(masked);
+      if (!then) break;
+      context += kw2 === "IF" ? "IF-branch \u203A " : "ELSIF-branch \u203A ";
+      rest = rest.slice(then.index + 4);
+    } else if (kw2 === "ELSE") {
+      context += "ELSE-branch \u203A ";
+      rest = rest.replace(/^\s*ELSE\b/i, "");
+    } else if (kw2 === "FOR" || kw2 === "WHILE") {
+      const lp = /\bLOOP\b/i.exec(masked);
+      if (!lp) break;
+      loop = true;
+      context += "loop \u203A ";
+      rest = rest.slice(lp.index + 4);
+    } else if (kw2 === "LOOP") {
+      loop = true;
+      context += "loop \u203A ";
+      rest = rest.replace(/^\s*LOOP\b/i, "");
+    } else if (kw2 === "BEGIN" || kw2 === "THEN") {
+      rest = rest.replace(/^\s*(BEGIN|THEN)\b/i, "");
+    } else {
+      break;
+    }
+  }
+  rest = rest.replace(/^\s+/, "").replace(/;\s*$/, "").trim();
+  if (!rest) return null;
+  const kw = firstKeyword(rest);
+  if (kw === "PERFORM") return { context, sql: rest.replace(/^\s*PERFORM\b/i, "SELECT"), loop };
+  if (DML.has(kw) || kw === "EXECUTE") return { context, sql: rest, loop };
+  return null;
+}
+function firstKeyword(sql) {
+  const m = /^[A-Za-z_]+/.exec(maskNonCode(sql).trim());
+  return m ? m[0].toUpperCase() : "";
+}
+function unitLabel(stmt) {
+  const kw = firstKeyword(stmt);
+  const t = targetTable2(stmt, kw);
+  return t ? `${kw} ${t}` : kw || "statement";
+}
+function targetTable2(stmt, kw) {
+  const re = kw === "DELETE" ? /\bDELETE\s+FROM\s+([A-Za-z_][\w.]*)/i : kw === "INSERT" ? /\bINSERT\s+INTO\s+([A-Za-z_][\w.]*)/i : kw === "UPDATE" ? /\bUPDATE\s+(?:ONLY\s+)?([A-Za-z_][\w.]*)/i : void 0;
+  return re ? re.exec(stmt)?.[1] ?? void 0 : void 0;
+}
+function dollarBody(doSql) {
+  const m = /\$([A-Za-z_]*)\$/.exec(doSql);
+  if (!m) return null;
+  const tag = m[0];
+  const start = m.index + tag.length;
+  const end = doSql.indexOf(tag, start);
+  return end < 0 ? null : doSql.slice(start, end);
+}
+function maskNonCode(sql) {
+  const out = sql.split("");
+  const n = sql.length;
+  let i = 0;
+  const blank = (a, b) => {
+    for (let k = a; k < b && k < n; k++) if (out[k] !== "\n") out[k] = " ";
+  };
+  while (i < n) {
+    const two = sql.slice(i, i + 2);
+    if (two === "--") {
+      let j = sql.indexOf("\n", i);
+      if (j < 0) j = n;
+      blank(i, j);
+      i = j;
+    } else if (two === "/*") {
+      let j = sql.indexOf("*/", i + 2);
+      j = j < 0 ? n : j + 2;
+      blank(i, j);
+      i = j;
+    } else if (sql[i] === "'" || sql[i] === '"') {
+      const q = sql[i];
+      let j = i + 1;
+      while (j < n) {
+        if (sql[j] === q) {
+          if (sql[j + 1] === q) j += 2;
+          else {
+            j++;
+            break;
+          }
+        } else j++;
+      }
+      blank(i, j);
+      i = j;
+    } else if (sql[i] === "$") {
+      const m = /^\$[A-Za-z_]*\$/.exec(sql.slice(i));
+      if (m) {
+        const tag = m[0];
+        let j = sql.indexOf(tag, i + tag.length);
+        j = j < 0 ? n : j + tag.length;
+        blank(i, j);
+        i = j;
+      } else i++;
+    } else i++;
+  }
+  return out.join("");
+}
+async function analyzeScript(connection, sql, opts) {
+  const units = extractAnalyzableUnits(sql);
+  const explainable = units.filter((u) => u.kind === "explainable");
+  const exec = explainable.length ? await explainScript(
+    connection,
+    explainable.map((u) => ({
+      label: u.label,
+      sql: u.sql,
+      ...u.loopNote ? { loopNote: u.loopNote } : {}
+    })),
+    {
+      statementTimeoutMs: opts.statementTimeoutMs,
+      lockTimeoutMs: opts.lockTimeoutMs,
+      verbose: opts.verbose,
+      settings: opts.settings
+    }
+  ) : null;
+  let ei = 0;
+  const out = units.map((u) => {
+    if (u.kind === "skipped") return { label: u.label, status: "skipped", reason: u.reason };
+    const r = exec?.units[ei++];
+    if (!r) return { label: u.label, status: "skipped", reason: "not analyzed" };
+    if (r.error) {
+      return {
+        label: u.label,
+        status: "error",
+        reason: r.error.detail,
+        errorCode: r.error.code,
+        ...r.loopNote ? { loopNote: r.loopNote } : {}
+      };
+    }
+    const result = analyze(r.planJson, {
+      sql: u.sql,
+      config: opts.config,
+      redact: opts.redact
+    });
+    return {
+      label: u.label,
+      status: "analyzed",
+      result,
+      report: buildReport(result),
+      ...r.loopNote ? { loopNote: r.loopNote } : {}
+    };
+  });
+  return { executed: false, units: out, ...exec ? { serverMajor: exec.caps.major } : {} };
+}
+async function emitScript(analysis, opts) {
+  configureColor(opts.format === "terminal" ? opts.color : "never");
+  const text = opts.format === "json" ? renderJsonScript(analysis, opts.pretty ?? true) : renderTextScript(analysis, opts);
+  if (opts.output) await writeFile(opts.output, text);
+  else process.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+  if (opts.failOn) {
+    for (const u of analysis.units) {
+      if (u.result?.worstSeverity && severityAtLeast(u.result.worstSeverity, opts.failOn))
+        return 1 /* CiGate */;
+    }
+  }
+  return 0 /* Success */;
+}
+function renderJsonScript(analysis, pretty) {
+  const units = analysis.units.map((u) => ({
+    label: u.label,
+    status: u.status,
+    loopNote: u.loopNote ?? null,
+    report: u.report ?? null,
+    reason: u.reason ?? null,
+    errorCode: u.errorCode ?? null
+  }));
+  return JSON.stringify(
+    { executed: false, serverMajor: analysis.serverMajor ?? null, units },
+    null,
+    pretty ? 2 : 0
+  );
+}
+function renderTextScript(analysis, opts) {
+  const c = colors();
+  const analyzed = analysis.units.filter((u) => u.status === "analyzed").length;
+  const skipped = analysis.units.length - analyzed;
+  const out = [];
+  out.push(
+    c.bold("Cost-only analysis \u2014 nothing was executed.") + c.dim(` ${analyzed} analyzed, ${skipped} skipped/failed.`)
+  );
+  out.push("");
+  for (const u of analysis.units) {
+    out.push(c.bold(`\u25B8 ${u.label}`) + (u.loopNote ? c.dim(`  (${u.loopNote})`) : ""));
+    if (u.status === "analyzed" && u.result) {
+      out.push(render(u.result, { format: opts.format, tldr: opts.tldr, ascii: opts.ascii }));
+    } else {
+      const tag = u.status === "error" ? c.yellow("could not analyze") : c.dim("skipped");
+      out.push(
+        `  ${tag}: ${u.reason ?? "(no detail)"}${u.errorCode ? c.dim(` [${u.errorCode}]`) : ""}`
+      );
+    }
+    out.push("");
+  }
+  return out.join("\n").trimEnd();
+}
+
 // src/commands/run.ts
 async function runRun(args) {
-  const sql = await resolveSql(args);
-  const statements = splitStatements(sql);
-  const statement = selectStatement2(statements, args.statementIndex);
-  if (args.flags.analyze && !args.flags.genericPlan && !isReadOnlyStatement(statement) && !args.forceWrite) {
-    const verb = statement.trim().split(/\s+/)[0]?.toUpperCase() ?? "statement";
-    throw opError("PGX_NON_SELECT_REFUSED", {
-      detail: `Refusing to ANALYZE a non-SELECT (${verb}) \u2014 it would modify data.`
+  const fullSql = await resolveSql(args);
+  const sql = args.statementIndex !== void 0 ? selectStatement2(splitStatements(fullSql), args.statementIndex) : fullSql;
+  const units = extractAnalyzableUnits(sql);
+  const single = units.length === 1 && units[0]?.kind === "explainable" ? units[0] : null;
+  const measured = single?.kind === "explainable" && args.flags.analyze && !args.flags.genericPlan && (isReadOnlyStatement(single.sql) || args.forceWrite);
+  if (measured && single) {
+    const result = await runExplain({
+      connection: args.connection,
+      statement: single.sql,
+      params: args.params,
+      flags: args.flags,
+      statementTimeoutMs: args.statementTimeoutMs,
+      lockTimeoutMs: args.lockTimeoutMs,
+      forceWrite: args.forceWrite,
+      rollback: args.rollback
+    });
+    if (result.omitted.length) {
+      logInfo(
+        `Note: server is PostgreSQL ${result.caps.major}; skipped unsupported option(s): ${result.omitted.join(", ")}.`
+      );
+    }
+    const analysis2 = analyze(result.json, {
+      config: args.config,
+      redact: args.redact,
+      sql: single.sql
     });
+    return emit(analysis2, args);
   }
-  const result = await runExplain({
-    connection: args.connection,
-    statement,
-    params: args.params,
-    flags: args.flags,
+  const analysis = await analyzeScript(args.connection, sql, {
+    config: args.config,
+    redact: args.redact,
     statementTimeoutMs: args.statementTimeoutMs,
     lockTimeoutMs: args.lockTimeoutMs,
-    forceWrite: args.forceWrite,
-    rollback: args.rollback
+    verbose: args.flags.verbose,
+    settings: args.flags.settings
+  });
+  return emitScript(analysis, {
+    format: args.format,
+    output: args.output,
+    color: args.color,
+    ascii: args.ascii,
+    tldr: args.tldr,
+    pretty: args.pretty,
+    failOn: args.failOn
   });
-  if (result.omitted.length) {
-    logInfo(
-      `Note: server is PostgreSQL ${result.caps.major}; skipped unsupported option(s): ${result.omitted.join(", ")}.`
-    );
-  }
-  const analysis = analyze(result.json, { config: args.config, redact: args.redact });
-  return emit(analysis, args);
 }
 async function resolveSql(args) {
   if (args.query) return args.query;
@@ -2880,6 +3767,35 @@ function selectStatement2(statements, index) {
   return statements[0];
 }
 
+// src/commands/studio.ts
+async function runStudio(args) {
+  const loopback = args.host === "127.0.0.1" || args.host === "localhost" || args.host === "::1";
+  if (!loopback && !args.unsafeHost) {
+    logInfo(
+      `Refusing to bind ${args.host}: the studio can connect to arbitrary databases, so exposing it off-loopback is an SSRF/credential risk. Pass --unsafe-host to override.`
+    );
+    return 2 /* Usage */;
+  }
+  const mod = await import(new URL("./server.js", import.meta.url).href);
+  const server = await mod.startStudio({ host: args.host, port: args.port });
+  logInfo(`
+  pgexplain studio  ${server.url}
+  Press Ctrl-C to stop.
+`);
+  if (args.open) openInBrowser(server.url);
+  process.removeAllListeners("SIGINT");
+  process.removeAllListeners("SIGTERM");
+  await new Promise((resolve) => {
+    const stop = () => {
+      logInfo("\nShutting down\u2026");
+      server.close().finally(resolve);
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  return 0 /* Success */;
+}
+
 // src/diagnostics/print.ts
 function formatDiagnostic(d) {
   const c = colors();
@@ -2915,6 +3831,11 @@ var outputArgs = {
   },
   tldr: { type: "boolean", description: "Summary + findings only (no plan tree)" },
   redact: { type: "boolean", description: "Strip literal values from expressions (safe to share)" },
+  open: {
+    type: "boolean",
+    description: "Open the HTML report in your browser (default: on when interactive)"
+  },
+  "no-open": { type: "boolean", description: "Never open the HTML report in the browser" },
   ascii: { type: "boolean", description: "Use ASCII tree glyphs instead of Unicode" },
   color: { type: "string", default: "auto", description: "auto | always | never" },
   "no-color": { type: "boolean", description: "Disable color (same as --color never)" },
@@ -2948,6 +3869,7 @@ function emitOptionsFrom(args) {
   if (args.output) opts.output = args.output;
   const failOn = resolveFailOn(args);
   if (failOn) opts.failOn = failOn;
+  opts.openHtml = args["no-open"] ? false : args.open ? true : Boolean(process.stdout.isTTY) && !process.env.CI;
   return opts;
 }
 function resolveFormat(value) {
@@ -3157,6 +4079,40 @@ var diffCmd = defineCommand({
     }
   }
 });
+var studioCmd = defineCommand({
+  meta: { name: "studio", description: "Launch the local pgexplain Studio web app." },
+  args: {
+    port: { type: "string", default: "5177", description: "Port to listen on" },
+    host: {
+      type: "string",
+      default: "127.0.0.1",
+      description: "Host to bind (loopback only unless --unsafe-host)"
+    },
+    "no-open": { type: "boolean", description: "Do not open the browser automatically" },
+    "unsafe-host": {
+      type: "boolean",
+      description: "Allow binding a non-loopback host (SSRF/credential risk)"
+    },
+    debug: { type: "boolean", description: "Print stack traces on internal errors" }
+  },
+  async run({ args }) {
+    try {
+      applyGlobalFlags(args);
+      const port = Number(args.port);
+      if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw usageError(`Invalid --port '${args.port}'`, "Use a port between 0 and 65535.");
+      }
+      process.exitCode = await runStudio({
+        host: args.host,
+        port,
+        open: !args["no-open"],
+        unsafeHost: !!args["unsafe-host"]
+      });
+    } catch (err) {
+      process.exitCode = handleFatal(err);
+    }
+  }
+});
 var main = defineCommand({
   meta: {
     name: "pg-explain",
@@ -3196,7 +4152,7 @@ var argv = process.argv.slice(2);
 if (argv[0] === "completion") {
   process.exitCode = runCompletion(argv[1]);
 } else {
-  const started = argv[0] === "run" ? runMain(runCmd, { rawArgs: argv.slice(1) }) : argv[0] === "diff" ? runMain(diffCmd, { rawArgs: argv.slice(1) }) : runMain(main, { rawArgs: argv });
+  const started = argv[0] === "run" ? runMain(runCmd, { rawArgs: argv.slice(1) }) : argv[0] === "diff" ? runMain(diffCmd, { rawArgs: argv.slice(1) }) : argv[0] === "studio" ? runMain(studioCmd, { rawArgs: argv.slice(1) }) : runMain(main, { rawArgs: argv });
   started.catch((err) => {
     process.exitCode = handleFatal(err);
   });