@indiekitai/pg-dash 0.4.6 → 0.5.1

package/README.md

@@ -21,6 +21,12 @@ npx @indiekitai/pg-dash check postgres://user:pass@host/db
 # Check migration safety before running it
 npx @indiekitai/pg-dash check-migration ./migrations/015_add_index.sql
 
+# EXPLAIN ANALYZE a slow query in the terminal
+npx @indiekitai/pg-dash explain "SELECT * FROM orders WHERE user_id = 1" postgres://...
+
+# Real-time lock + long-query monitor (Ctrl+C to exit)
+npx @indiekitai/pg-dash watch-locks postgres://...
+
 # Compare two environments (local vs staging)
 npx @indiekitai/pg-dash diff-env --source postgres://localhost/db --target postgres://staging/db
 
@@ -102,6 +108,45 @@ The Dashboard is there when you need it. But the real power is in the CLI, MCP,
 - Auto-detects Slack vs Discord webhook URLs
 - Configure via `--slack-webhook` or `--discord-webhook`
 
+### 🔬 EXPLAIN ANALYZE CLI
+
+```bash
+pg-dash explain "SELECT * FROM orders WHERE user_id = 1" postgres://...
+```
+
+```
+Query: SELECT * FROM orders WHERE user_id = 1
+
+Limit cost=3.01..3.04 actual=0.060ms rows=10/10
+└─ Sort cost=3.01..3.09 actual=0.057ms rows=10/32
+  └─ Seq Scan on users cost=0.00..2.32 actual=0.023ms rows=32/32
+
+─── Summary ────────────────────────────────────
+  Execution time:  0.087ms
+  Planning time:   0.756ms
+  Seq Scans:       users
+
+─── Recommendations ────────────────────────────
+  ℹ  Sort on [created_at DESC]. An index might eliminate this.
+```
+
+- Color-coded node types: 🔴 Seq Scan, 🟢 Index Scan, 🟡 Hash Join, 🟣 Sort
+- Shows actual vs estimated rows — catches bad planner estimates
+- Flags Seq Scans > 1000 rows, Sort nodes, Hash Join memory spills
+- `--no-analyze` for dry EXPLAIN (no actual execution)
+- `--json` for scripting
+
+### 🔒 watch-locks
+
+```bash
+pg-dash watch-locks postgres://...
+```
+
+Real-time lock wait monitor — refreshes every 3 seconds. Shows:
+- Blocked queries with PID, wait time, and the blocking query
+- Long-running queries (configurable threshold via `--long-query-threshold`)
+- Table and lock type for each wait
+
 ### 🛡️ Migration Safety Check
 - Analyze a migration SQL file for risks before running it
 - Detects: `CREATE INDEX` without `CONCURRENTLY` (lock risk), `ADD COLUMN NOT NULL` without `DEFAULT`, `ALTER COLUMN TYPE` (full table rewrite), `DROP COLUMN` (app breakage risk), `ADD CONSTRAINT` without `NOT VALID` (full table scan), `CREATE INDEX CONCURRENTLY` inside a transaction (runtime failure), `DROP TABLE`, `TRUNCATE`, `DELETE`/`UPDATE` without `WHERE`

package/README.zh-CN.md

@@ -21,6 +21,12 @@ npx @indiekitai/pg-dash check postgres://user:pass@host/db
 # 执行 migration 前检查风险
 npx @indiekitai/pg-dash check-migration ./migrations/015_add_index.sql
 
+# 终端里分析慢查询（彩色树形输出 + 建议）
+npx @indiekitai/pg-dash explain "SELECT * FROM orders WHERE user_id = 1" postgres://...
+
+# 实时锁监控（Ctrl+C 退出）
+npx @indiekitai/pg-dash watch-locks postgres://...
+
 # 对比两个环境（本地 vs 预发）
 npx @indiekitai/pg-dash diff-env --source postgres://localhost/db --target postgres://staging/db
 
@@ -173,6 +179,8 @@ pg-dash --host localhost --user postgres --db mydb --port 3480
 pg-dash <connection-string>                      启动面板
 pg-dash check <connection-string>                运行健康检查并退出
 pg-dash check-migration <file> [conn]            检查 migration SQL 的风险
+pg-dash explain "<query>" <connection>           终端里 EXPLAIN ANALYZE 查询
+pg-dash watch-locks <connection>                 实时锁和长查询监控
 pg-dash diff-env --source <url> --target <url>   对比两个环境
 pg-dash schema-diff <connection-string>          显示 Schema 变更
 

package/dist/cli.js

@@ -2079,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";
 
@@ -4056,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" },
@@ -4099,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
@@ -4140,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
@@ -4497,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(
@@ -4538,4 +4792,7 @@ Run pg-dash --help for usage.`
     webhook
   });
 }
+var nodeColor2;
+var renderNode2;
+var collectNodes3;
 //# sourceMappingURL=cli.js.map