@indiekitai/pg-dash 0.4.5 → 0.5.0

package/dist/cli.js

@@ -300,30 +300,44 @@ SHOW shared_buffers;`,
     }
     try {
       const r = await client.query(`
-        SELECT pid, state, now() - state_change AS idle_duration,
+        SELECT pid,
           client_addr::text, application_name,
           extract(epoch from now() - state_change)::int AS idle_seconds
         FROM pg_stat_activity
-        WHERE state IN ('idle', 'idle in transaction')
+        WHERE state = 'idle in transaction'
           AND now() - state_change > $1 * interval '1 minute'
           AND pid != pg_backend_pid()
+        ORDER BY idle_seconds DESC
       `, [longQueryThreshold]);
-      for (const row of r.rows) {
-        const isIdleTx = row.state === "idle in transaction";
+      if (r.rows.length === 1) {
+        const row = r.rows[0];
         issues.push({
-          id: `maint-idle-${row.pid}`,
-          severity: isIdleTx ? "warning" : "info",
+          id: `maint-idle-tx-${row.pid}`,
+          severity: "warning",
           category: "maintenance",
-          title: `${isIdleTx ? "Idle in transaction" : "Idle connection"} (PID ${row.pid})`,
-          description: `PID ${row.pid} from ${row.client_addr || "local"} (${row.application_name || "unknown"}) has been ${row.state} for ${Math.round(row.idle_seconds / 60)} minutes.`,
+          title: `Idle-in-transaction connection (PID ${row.pid})`,
+          description: `PID ${row.pid} from ${row.client_addr || "local"} (${row.application_name || "unknown"}) has been idle in transaction for ${Math.round(row.idle_seconds / 60)} minutes. This holds locks and blocks VACUUM.`,
           fix: `SELECT pg_terminate_backend(${row.pid});`,
-          impact: isIdleTx ? "Idle-in-transaction connections hold locks and prevent VACUUM." : "Idle connections consume connection slots.",
+          impact: "Idle-in-transaction connections hold locks and prevent VACUUM.",
+          effort: "quick"
+        });
+      } else if (r.rows.length > 1) {
+        const pids = r.rows.map((row) => row.pid);
+        const maxMin = Math.round(r.rows[0].idle_seconds / 60);
+        issues.push({
+          id: `maint-idle-tx-multi`,
+          severity: "warning",
+          category: "maintenance",
+          title: `${r.rows.length} idle-in-transaction connections (longest: ${maxMin}m)`,
+          description: `${r.rows.length} connections have been idle in transaction for over ${longQueryThreshold} minutes. These hold locks and prevent VACUUM from running.`,
+          fix: `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle in transaction' AND now() - state_change > interval '${longQueryThreshold} minutes';`,
+          impact: "Idle-in-transaction connections hold locks and prevent VACUUM.",
           effort: "quick"
         });
       }
     } catch (err) {
-      console.error("[advisor] Error checking idle connections:", err.message);
-      skipped.push("idle connections: " + err.message);
+      console.error("[advisor] Error checking idle-in-transaction connections:", err.message);
+      skipped.push("idle-in-transaction: " + err.message);
     }
     try {
       const r = await client.query(`
@@ -2065,6 +2079,97 @@ var init_env_differ = __esm({
   }
 });
 
+// src/server/locks.ts
+var locks_exports = {};
+__export(locks_exports, {
+  formatDurationSecs: () => formatDurationSecs,
+  getLockReport: () => getLockReport
+});
+function formatDurationSecs(secs) {
+  const h = Math.floor(secs / 3600);
+  const m = Math.floor(secs % 3600 / 60);
+  const s = secs % 60;
+  return [
+    String(h).padStart(2, "0"),
+    String(m).padStart(2, "0"),
+    String(s).padStart(2, "0")
+  ].join(":");
+}
+async function getLockReport(pool) {
+  const [locksResult, longResult] = await Promise.all([
+    pool.query(`
+      SELECT
+        blocked.pid AS blocked_pid,
+        blocked.query AS blocked_query,
+        EXTRACT(EPOCH FROM (NOW() - blocked.query_start))::int AS blocked_secs,
+        blocking.pid AS blocking_pid,
+        blocking.query AS blocking_query,
+        EXTRACT(EPOCH FROM (NOW() - blocking.query_start))::int AS blocking_secs,
+        blocked_locks.relation::regclass::text AS table_name,
+        blocked_locks.locktype
+      FROM pg_catalog.pg_locks blocked_locks
+      JOIN pg_catalog.pg_stat_activity blocked ON blocked.pid = blocked_locks.pid
+      JOIN pg_catalog.pg_locks blocking_locks
+        ON blocking_locks.locktype = blocked_locks.locktype
+        AND blocking_locks.relation IS NOT DISTINCT FROM blocked_locks.relation
+        AND blocking_locks.pid != blocked_locks.pid
+        AND blocking_locks.granted = true
+      JOIN pg_catalog.pg_stat_activity blocking ON blocking.pid = blocking_locks.pid
+      WHERE NOT blocked_locks.granted
+    `),
+    pool.query(`
+      SELECT
+        pid,
+        EXTRACT(EPOCH FROM (NOW() - query_start))::int AS duration_secs,
+        query,
+        state,
+        wait_event_type
+      FROM pg_stat_activity
+      WHERE state != 'idle'
+        AND query_start IS NOT NULL
+        AND EXTRACT(EPOCH FROM (NOW() - query_start)) > 5
+        AND query NOT LIKE '%pg_stat_activity%'
+      ORDER BY duration_secs DESC
+      LIMIT 20
+    `)
+  ]);
+  const seen = /* @__PURE__ */ new Set();
+  const waitingLocks = [];
+  for (const row of locksResult.rows) {
+    const key = `${row.blocked_pid}:${row.blocking_pid}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      waitingLocks.push({
+        blockedPid: parseInt(row.blocked_pid, 10),
+        blockedQuery: row.blocked_query,
+        blockedDuration: formatDurationSecs(parseInt(row.blocked_secs, 10) || 0),
+        blockingPid: parseInt(row.blocking_pid, 10),
+        blockingQuery: row.blocking_query,
+        blockingDuration: formatDurationSecs(parseInt(row.blocking_secs, 10) || 0),
+        table: row.table_name ?? null,
+        lockType: row.locktype
+      });
+    }
+  }
+  const longRunningQueries = longResult.rows.map((row) => ({
+    pid: parseInt(row.pid, 10),
+    duration: formatDurationSecs(parseInt(row.duration_secs, 10) || 0),
+    query: row.query,
+    state: row.state,
+    waitEventType: row.wait_event_type ?? null
+  }));
+  return {
+    waitingLocks,
+    longRunningQueries,
+    checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var init_locks = __esm({
+  "src/server/locks.ts"() {
+    "use strict";
+  }
+});
+
 // src/cli.ts
 import { parseArgs } from "util";
 
@@ -4042,6 +4147,7 @@ var { values, positionals } = parseArgs({
     "slack-webhook": { type: "string" },
     "discord-webhook": { type: "string" },
     "no-open": { type: "boolean", default: false },
+    "no-analyze": { type: "boolean", default: false },
     json: { type: "boolean", default: false },
     host: { type: "string" },
     user: { type: "string", short: "u" },
@@ -4085,6 +4191,8 @@ Usage:
   pg-dash check <connection-string>                     Run health check and exit
   pg-dash health <connection-string>                    Alias for check
   pg-dash check-migration <file> [connection]           Analyze migration SQL for risks
+  pg-dash explain <query> <connection>                  EXPLAIN ANALYZE a query in the terminal
+  pg-dash watch-locks <connection>                      Real-time lock + long-query monitor
   pg-dash diff-env --source <url> --target <url>        Compare two environments
   pg-dash schema-diff <connection-string>               Show latest schema changes
   pg-dash --host localhost --user postgres --db mydb
@@ -4126,7 +4234,7 @@ Environment variables:
 `);
   process.exit(0);
 }
-var KNOWN_SUBCOMMANDS = ["check", "health", "check-migration", "schema-diff", "diff-env"];
+var KNOWN_SUBCOMMANDS = ["check", "health", "check-migration", "schema-diff", "diff-env", "explain", "watch-locks"];
 var subcommand = positionals[0];
 function isValidConnectionString(s) {
   return s.startsWith("postgresql://") || s.startsWith("postgres://") || s.includes("@") || // user@host shorthand
@@ -4483,6 +4591,166 @@ Migration check: ${filePath}`);
     console.error(`Error: ${err.message}`);
     process.exit(1);
   }
+} else if (subcommand === "explain") {
+  const query = positionals[1];
+  if (!query) {
+    console.error('Error: provide a SQL query.\n\nUsage: pg-dash explain "<query>" <connection>');
+    process.exit(1);
+  }
+  const connStr = positionals[2] || resolveConnectionString(2);
+  if (!connStr) {
+    console.error("Error: provide a connection string.");
+    process.exit(1);
+  }
+  const doAnalyze = !values["no-analyze"];
+  const fmt = values.json ? "json" : "text";
+  const { Pool: Pool3 } = await import("pg");
+  const pool = new Pool3({ connectionString: connStr, max: 1, connectionTimeoutMillis: 1e4 });
+  try {
+    let nodeColor = function(type, rows, analyzed) {
+      if (type.includes("Seq Scan")) return analyzed && rows >= 1e3 ? "\x1B[31m\x1B[1m" : "\x1B[31m";
+      if (type.includes("Index")) return "\x1B[32m";
+      if (type === "Hash Join" || type === "Hash") return "\x1B[33m";
+      if (type === "Sort") return "\x1B[35m";
+      return "\x1B[37m";
+    }, renderNode = function(node, indent = 0, isLast = true) {
+      const lines = [];
+      const prefix = indent === 0 ? "" : "  ".repeat(indent - 1) + (isLast ? "\u2514\u2500 " : "\u251C\u2500 ");
+      const analyzed = node["Actual Total Time"] !== void 0;
+      const rows = node["Actual Rows"] ?? node["Plan Rows"];
+      const color = nodeColor(node["Node Type"], rows, analyzed);
+      const rel = node["Relation Name"] ? ` on ${dim}${node["Alias"] || node["Relation Name"]}${reset}` : "";
+      const cost = `${dim}cost=${node["Startup Cost"].toFixed(2)}..${node["Total Cost"].toFixed(2)}${reset}`;
+      const timing = analyzed ? ` ${cyan}actual=${node["Actual Total Time"].toFixed(3)}ms${reset}` : "";
+      const rowStr = analyzed ? ` ${dim}rows=${node["Actual Rows"]}/${node["Plan Rows"]}${reset}` : ` ${dim}rows=${node["Plan Rows"]}${reset}`;
+      const idx = node["Index Name"] ? ` ${dim}idx=${node["Index Name"]}${reset}` : "";
+      const filter = node["Filter"] ? ` ${dim}filter=${String(node["Filter"]).slice(0, 40)}${reset}` : "";
+      lines.push(`${prefix}${color}${node["Node Type"]}${reset}${rel} ${cost}${timing}${rowStr}${idx}${filter}`);
+      if (node.Plans?.length) {
+        for (let i = 0; i < node.Plans.length; i++) {
+          lines.push(renderNode(node.Plans[i], indent + 1, i === node.Plans.length - 1));
+        }
+      }
+      return lines.join("\n");
+    }, collectNodes2 = function(n) {
+      return [n, ...n.Plans?.flatMap(collectNodes2) ?? []];
+    };
+    nodeColor2 = nodeColor, renderNode2 = renderNode, collectNodes3 = collectNodes2;
+    const explainSql = doAnalyze ? `EXPLAIN (ANALYZE, COSTS, VERBOSE, BUFFERS, FORMAT JSON) ${query}` : `EXPLAIN (COSTS, VERBOSE, FORMAT JSON) ${query}`;
+    const res = await pool.query(explainSql);
+    await pool.end();
+    const rawPlan = res.rows[0]["QUERY PLAN"];
+    const planObj = Array.isArray(rawPlan) ? rawPlan[0] : rawPlan;
+    const root = planObj.Plan;
+    const planningTime = planObj["Planning Time"];
+    const executionTime = planObj["Execution Time"];
+    const reset = "\x1B[0m";
+    const dim = "\x1B[2m";
+    const cyan = "\x1B[36m";
+    const allNodes = collectNodes2(root);
+    const seqScans = allNodes.filter((n) => n["Node Type"] === "Seq Scan" && n["Relation Name"]).map((n) => n["Relation Name"]);
+    const recs = [];
+    for (const n of allNodes) {
+      const rows = n["Actual Rows"] ?? n["Plan Rows"];
+      if (n["Node Type"] === "Seq Scan" && n["Relation Name"] && rows >= 1e3) {
+        recs.push(`\u26A0  Seq Scan on "${n["Relation Name"]}" (${rows} rows). Consider adding an index.`);
+      }
+      if (n["Node Type"] === "Sort") {
+        recs.push(`\u2139  Sort on [${(n["Sort Key"] ?? []).join(", ")}]. An index might eliminate this.`);
+      }
+      if (n["Hash Batches"] && n["Hash Batches"] > 1) {
+        recs.push(`\u26A0  Hash Join used ${n["Hash Batches"]} batches. Increase work_mem to avoid disk spilling.`);
+      }
+    }
+    if (fmt === "json") {
+      console.log(JSON.stringify({ query, planningTime, executionTime, seqScans, recommendations: recs }, null, 2));
+    } else {
+      if (query) console.log(`
+\x1B[1mQuery:\x1B[0m ${dim}${query.slice(0, 120)}${reset}`);
+      console.log("\n" + renderNode(root));
+      console.log(`
+${dim}\u2500\u2500\u2500 Summary ${"\u2500".repeat(36)}${reset}`);
+      if (executionTime !== void 0) console.log(`  Execution time:  ${cyan}${executionTime.toFixed(3)}ms${reset}`);
+      if (planningTime !== void 0) console.log(`  Planning time:   ${dim}${planningTime.toFixed(3)}ms${reset}`);
+      if (seqScans.length > 0) console.log(`  Seq Scans:       \x1B[31m${seqScans.join(", ")}${reset}`);
+      if (recs.length > 0) {
+        console.log(`
+${dim}\u2500\u2500\u2500 Recommendations ${"\u2500".repeat(28)}${reset}`);
+        for (const r of recs) console.log(`  ${r}`);
+      }
+      console.log();
+    }
+  } catch (err) {
+    await pool.end().catch(() => {
+    });
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+} else if (subcommand === "watch-locks") {
+  const connStr = positionals[1] || resolveConnectionString(1);
+  if (!connStr) {
+    console.error("Error: provide a connection string.\n\nUsage: pg-dash watch-locks <connection>");
+    process.exit(1);
+  }
+  const intervalSec = values.interval ? parseInt(values.interval, 10) : 3;
+  const { Pool: Pool3 } = await import("pg");
+  const pool = new Pool3({ connectionString: connStr, max: 2, connectionTimeoutMillis: 1e4 });
+  const { getLockReport: getLockReport2 } = await Promise.resolve().then(() => (init_locks(), locks_exports));
+  const reset = "\x1B[0m";
+  const dim = "\x1B[2m";
+  const red = "\x1B[31m";
+  const yellow = "\x1B[33m";
+  const cyan = "\x1B[36m";
+  const bold = "\x1B[1m";
+  process.stdout.write("\x1B[?25l");
+  const cleanup = () => {
+    process.stdout.write("\x1B[?25h");
+    pool.end();
+    process.exit(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  async function tick() {
+    try {
+      const report = await getLockReport2(pool);
+      console.clear();
+      const ts = (/* @__PURE__ */ new Date()).toLocaleTimeString();
+      console.log(`${bold}pg-dash watch-locks${reset}  ${dim}(Ctrl+C to exit \u2014 refresh every ${intervalSec}s \u2014 ${ts})${reset}
+`);
+      if (report.waitingLocks.length === 0) {
+        console.log(`  ${dim}No lock waits detected.${reset}`);
+      } else {
+        console.log(`${bold}${red}  Lock Waits (${report.waitingLocks.length})${reset}`);
+        for (const lw of report.waitingLocks) {
+          console.log(`
+  ${red}BLOCKED${reset} pid=${lw.blockedPid} waiting ${lw.blockedDuration}`);
+          console.log(`    Query: ${dim}${lw.blockedQuery.slice(0, 100)}${reset}`);
+          console.log(`    ${yellow}BLOCKING${reset} pid=${lw.blockingPid} running ${lw.blockingDuration}`);
+          console.log(`    Query: ${dim}${lw.blockingQuery.slice(0, 100)}${reset}`);
+          if (lw.table) console.log(`    Table: ${lw.table}  Lock: ${lw.lockType}`);
+        }
+      }
+      if (report.longRunningQueries.length > 0) {
+        console.log(`
+${bold}${yellow}  Long-running Queries (${report.longRunningQueries.length})${reset}`);
+        for (const q of report.longRunningQueries) {
+          console.log(`
+  pid=${q.pid}  duration=${q.duration}  state=${q.state}`);
+          console.log(`  ${dim}${q.query.slice(0, 120)}${reset}`);
+        }
+      }
+      if (report.waitingLocks.length === 0 && report.longRunningQueries.length === 0) {
+        console.log(`
+  ${dim}No long-running queries.${reset}`);
+      }
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+    }
+  }
+  await tick();
+  const timer = setInterval(tick, intervalSec * 1e3);
+  void timer;
 } else {
   if (subcommand && !isValidConnectionString(subcommand) && KNOWN_SUBCOMMANDS.indexOf(subcommand) === -1) {
     console.error(
@@ -4524,4 +4792,7 @@ Run pg-dash --help for usage.`
     webhook
   });
 }
+var nodeColor2;
+var renderNode2;
+var collectNodes3;
 //# sourceMappingURL=cli.js.map