@indiekitai/pg-dash 0.7.0 → 0.8.0

package/README.md

@@ -27,6 +27,9 @@ npx @indiekitai/pg-dash explain "SELECT * FROM orders WHERE user_id = 1" postgre
 # Real-time lock + long-query monitor (Ctrl+C to exit)
 npx @indiekitai/pg-dash watch-locks postgres://...
 
+# Analyze slow queries from pg_stat_statements
+npx @indiekitai/pg-dash slow-queries postgres://... --limit 20 --min-calls 5
+
 # Compare two environments (local vs staging)
 npx @indiekitai/pg-dash diff-env --source postgres://localhost/db --target postgres://staging/db
 

package/README.zh-CN.md

@@ -27,6 +27,9 @@ npx @indiekitai/pg-dash explain "SELECT * FROM orders WHERE user_id = 1" postgre
 # 实时锁监控（Ctrl+C 退出）
 npx @indiekitai/pg-dash watch-locks postgres://...
 
+# 慢查询分析（基于 pg_stat_statements）
+npx @indiekitai/pg-dash slow-queries postgres://... --limit 20 --min-calls 5
+
 # 对比两个环境（本地 vs 预发）
 npx @indiekitai/pg-dash diff-env --source postgres://localhost/db --target postgres://staging/db
 

package/dist/cli.js

@@ -125,11 +125,13 @@ CREATE INDEX CONCURRENTLY idx_${row.relname}_<column> ON ${row.schemaname}.${row
     try {
       const r = await client.query(`
         SELECT schemaname, relname, n_dead_tup, n_live_tup,
-          CASE WHEN n_live_tup > 0 THEN round(n_dead_tup::numeric / n_live_tup * 100, 1) ELSE 0 END AS dead_pct,
+          CASE WHEN (n_live_tup + n_dead_tup) > 0
+            THEN round(n_dead_tup::numeric / (n_live_tup + n_dead_tup) * 100, 1) ELSE 0 END AS dead_pct,
           pg_size_pretty(pg_total_relation_size(relid)) AS size
         FROM pg_stat_user_tables
-        WHERE n_live_tup > 1000 AND n_dead_tup::float / GREATEST(n_live_tup, 1) > 0.1
-        ORDER BY n_dead_tup DESC LIMIT 10
+        WHERE (n_live_tup + n_dead_tup) > 0
+          AND n_dead_tup::float / GREATEST(n_live_tup + n_dead_tup, 1) > 0.1
+        ORDER BY n_dead_tup::float / GREATEST(n_live_tup + n_dead_tup, 1) DESC LIMIT 20
       `);
       for (const row of r.rows) {
         const pct = parseFloat(row.dead_pct);
@@ -138,7 +140,7 @@ CREATE INDEX CONCURRENTLY idx_${row.relname}_<column> ON ${row.schemaname}.${row
           severity: pct > 30 ? "critical" : "warning",
           category: "performance",
           title: `Table bloat on ${row.relname} (${row.dead_pct}% dead)`,
-          description: `${row.schemaname}.${row.relname} has ${Number(row.n_dead_tup).toLocaleString()} dead tuples (${row.dead_pct}% of ${Number(row.n_live_tup).toLocaleString()} live rows). Size: ${row.size}.`,
+          description: `${row.schemaname}.${row.relname} has ${Number(row.n_dead_tup).toLocaleString()} dead tuples (${row.dead_pct}% of ${(Number(row.n_live_tup) + Number(row.n_dead_tup)).toLocaleString()} total rows). Size: ${row.size}.`,
           fix: `VACUUM FULL ${row.schemaname}.${row.relname};`,
           impact: "Dead tuples waste storage and degrade scan performance.",
           effort: pct > 30 ? "moderate" : "quick"
@@ -202,6 +204,18 @@ SHOW shared_buffers;`,
             effort: "moderate"
           });
         }
+      } else {
+        issues.push({
+          id: `perf-no-pg-stat-statements`,
+          severity: "warning",
+          category: "performance",
+          title: `pg_stat_statements extension not installed`,
+          description: `The pg_stat_statements extension is not installed. Without it, slow query detection, query regression analysis, and query performance trending are all unavailable.`,
+          fix: `CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+-- Also add to shared_preload_libraries in postgresql.conf and restart`,
+          impact: "No visibility into slow queries, query regressions, or performance trends. You are flying blind on query performance.",
+          effort: "moderate"
+        });
       }
     } catch (err) {
       console.error("[advisor] Error checking slow queries:", err.message);
@@ -373,8 +387,8 @@ SHOW shared_buffers;`,
         FROM pg_stat_user_indexes
         WHERE idx_scan = 0
           AND indexrelname NOT LIKE '%_pkey'
-          AND pg_relation_size(indexrelid) > 1048576
-        ORDER BY pg_relation_size(indexrelid) DESC LIMIT 10
+          AND pg_relation_size(indexrelid) > 8192
+        ORDER BY pg_relation_size(indexrelid) DESC LIMIT 20
       `);
       for (const row of r.rows) {
         issues.push({
@@ -555,6 +569,35 @@ SELECT pg_reload_conf();`,
       console.error("[advisor] Error checking autovacuum:", err.message);
       skipped.push("autovacuum: " + err.message);
     }
+    try {
+      const r = await client.query(`
+        SELECT schemaname, relname, n_live_tup, n_dead_tup,
+          last_autovacuum, last_vacuum
+        FROM pg_stat_user_tables
+        WHERE n_live_tup < 50
+          AND n_dead_tup > 0
+          AND last_autovacuum IS NULL
+          AND last_vacuum IS NULL
+      `);
+      if (r.rows.length >= 5) {
+        const tables = r.rows.map((row) => row.relname);
+        const totalDead = r.rows.reduce((sum, row) => sum + parseInt(row.n_dead_tup, 10), 0);
+        issues.push({
+          id: `maint-autovacuum-small-tables`,
+          severity: "warning",
+          category: "maintenance",
+          title: `${r.rows.length} small tables never autovacuumed (default threshold=50 too high)`,
+          description: `${r.rows.length} tables with fewer than 50 live rows have never been autovacuumed because the default autovacuum_vacuum_threshold (50) exceeds their row count. Total dead tuples: ${totalDead}. Tables: ${tables.slice(0, 10).join(", ")}${tables.length > 10 ? `, ... and ${tables.length - 10} more` : ""}.`,
+          fix: `-- Lower per-table threshold for small tables:
+${tables.slice(0, 5).map((t) => `ALTER TABLE ${t} SET (autovacuum_vacuum_threshold = 5, autovacuum_vacuum_scale_factor = 0.1);`).join("\n")}`,
+          impact: "Dead tuples accumulate on small tables indefinitely, causing bloat.",
+          effort: "moderate"
+        });
+      }
+    } catch (err) {
+      console.error("[advisor] Error checking autovacuum small tables:", err.message);
+      skipped.push("autovacuum small tables: " + err.message);
+    }
     try {
       const sbRes = await client.query(`SELECT setting, unit FROM pg_settings WHERE name = 'shared_buffers'`);
       const memRes = await client.query(`
@@ -737,12 +780,7 @@ function unignoreIssue(issueId) {
   const db = getIgnoredDb();
   db.prepare("DELETE FROM ignored_issues WHERE issue_id = ?").run(issueId);
 }
-function isSafeFix(sql) {
-  const trimmed = sql.trim();
-  if (!trimmed) return false;
-  const statements = trimmed.replace(/;\s*$/, "").split(";").map((s) => s.trim()).filter(Boolean);
-  if (statements.length !== 1) return false;
-  const upper = statements[0].toUpperCase();
+function isSafeSingleStatement(upper) {
   if (upper.startsWith("EXPLAIN ANALYZE")) {
     const afterExplain = upper.replace(/^EXPLAIN\s+ANALYZE\s+/, "").trimStart();
     return afterExplain.startsWith("SELECT");
@@ -756,8 +794,18 @@ function isSafeFix(sql) {
     "SELECT PG_TERMINATE_BACKEND(",
     "SELECT PG_CANCEL_BACKEND("
   ];
+  if (upper.startsWith("ALTER TABLE")) {
+    return /^ALTER TABLE\s+\S+\s+SET\s*\(/i.test(upper);
+  }
   return ALLOWED_PREFIXES.some((p) => upper.startsWith(p));
 }
+function isSafeFix(sql) {
+  const trimmed = sql.trim();
+  if (!trimmed) return false;
+  const statements = trimmed.replace(/;\s*$/, "").split(";").map((s) => s.trim()).filter(Boolean);
+  if (statements.length === 0) return false;
+  return statements.every((stmt) => isSafeSingleStatement(stmt.toUpperCase()));
+}
 var SEVERITY_WEIGHT, MAX_DEDUCTION, _ignoredDb;
 var init_advisor = __esm({
   "src/server/advisor.ts"() {
@@ -4748,6 +4796,8 @@ var { values, positionals } = parseArgs({
     "snapshot-interval": { type: "string" },
     "query-stats-interval": { type: "string" },
     "long-query-threshold": { type: "string" },
+    limit: { type: "string" },
+    "min-calls": { type: "string" },
     help: { type: "boolean", short: "h" },
     version: { type: "boolean", short: "v" },
     threshold: { type: "string" },
@@ -4787,6 +4837,8 @@ Usage:
   pg-dash schema-diff <connection-string>               Show latest schema changes
   pg-dash query-stats export <connection>               Export query statistics (PG 18+)
   pg-dash query-stats import <file> <connection>       Import query statistics (PG 18+)
+  pg-dash slow-queries <connection>                    Analyze slow queries from pg_stat_statements
+  pg-dash slow-queries <connection> --limit 20 --min-calls 5
   pg-dash --host localhost --user postgres --db mydb
 
 Options:
@@ -4828,7 +4880,7 @@ Environment variables:
 `);
   process.exit(0);
 }
-var KNOWN_SUBCOMMANDS = ["check", "health", "check-migration", "schema-diff", "diff-env", "explain", "watch-locks", "query-stats"];
+var KNOWN_SUBCOMMANDS = ["check", "health", "check-migration", "schema-diff", "diff-env", "explain", "watch-locks", "query-stats", "slow-queries"];
 var subcommand = positionals[0];
 function isValidConnectionString(s) {
   return s.startsWith("postgresql://") || s.startsWith("postgres://") || s.includes("@") || // user@host shorthand
@@ -5537,6 +5589,93 @@ ${bold}${yellow}  Long-running Queries (${report.longRunningQueries.length})${re
     console.error("Error: specify 'export' or 'import'.\n\nUsage:\n  pg-dash query-stats export <connection> [--file output.json]\n  pg-dash query-stats import <file> <connection>");
     process.exit(1);
   }
+} else if (subcommand === "slow-queries") {
+  const connStr = positionals[1] || resolveConnectionString(1);
+  if (!connStr) {
+    console.error("Error: provide a connection string.\n\nUsage: pg-dash slow-queries <connection> [--limit 20] [--sort total|time|calls] [--min-calls 5] [--json]");
+    process.exit(1);
+  }
+  const limit = parseInt(values.limit || values.threshold || "20", 10);
+  const sortBy = values.format || "total";
+  const minCalls = parseInt(values["min-calls"] || values["long-query-threshold"] || "5", 10);
+  const outputJson = values.json || false;
+  const { Pool: Pool3 } = await import("pg");
+  const pool = new Pool3({ connectionString: connStr, connectionTimeoutMillis: 1e4 });
+  try {
+    let fmtTime = function(ms) {
+      if (ms < 1) return `${ms.toFixed(2)}ms`;
+      if (ms < 1e3) return `${ms.toFixed(1)}ms`;
+      if (ms < 6e4) return `${(ms / 1e3).toFixed(1)}s`;
+      return `${(ms / 6e4).toFixed(1)}m`;
+    }, fmtNum = function(n) {
+      return n.toLocaleString();
+    }, truncateQuery = function(q, maxLen = 120) {
+      const cleaned = q.replace(/\s+/g, " ").trim();
+      return cleaned.length <= maxLen ? cleaned : cleaned.slice(0, maxLen) + "...";
+    };
+    fmtTime2 = fmtTime, fmtNum2 = fmtNum, truncateQuery2 = truncateQuery;
+    const extCheck = await pool.query(`SELECT 1 FROM pg_extension WHERE extname = 'pg_stat_statements'`);
+    if (extCheck.rows.length === 0) {
+      console.error("Error: pg_stat_statements extension is not installed.");
+      console.error("  Run: CREATE EXTENSION pg_stat_statements;");
+      process.exit(1);
+    }
+    let orderCol = "total_exec_time";
+    if (sortBy === "time") orderCol = "mean_exec_time";
+    else if (sortBy === "calls") orderCol = "calls";
+    const res = await pool.query(`
+      SELECT query, calls, total_exec_time, mean_exec_time, stddev_exec_time, rows,
+             shared_blks_hit, shared_blks_read, shared_blks_dirtied, shared_blks_written,
+             temp_blks_read, temp_blks_written
+      FROM pg_stat_statements
+      WHERE calls >= $1
+      ORDER BY ${orderCol} DESC
+      LIMIT $2
+    `, [minCalls, limit]);
+    const totalTimeRes = await pool.query(`SELECT SUM(total_exec_time) as total FROM pg_stat_statements WHERE calls >= $1`, [minCalls]);
+    const totalTime = totalTimeRes.rows[0]?.total || 0;
+    if (outputJson) {
+      console.log(JSON.stringify({
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        sortBy,
+        minCalls,
+        limit,
+        totalQueryTime: totalTime,
+        queries: res.rows.map((r) => ({
+          query: r.query,
+          calls: Number(r.calls),
+          totalTimeMs: Math.round(r.total_exec_time),
+          meanTimeMs: Math.round(r.mean_exec_time),
+          rows: Number(r.rows),
+          cacheHitRatio: r.shared_blks_hit + r.shared_blks_read > 0 ? Math.round(100 * r.shared_blks_hit / (r.shared_blks_hit + r.shared_blks_read)) : null
+        }))
+      }, null, 2));
+    } else {
+      console.log(`
+pg-dash slow-queries (sorted by: ${sortBy}, min calls: ${minCalls})
+`);
+      console.log("\u2550".repeat(100));
+      for (let i = 0; i < res.rows.length; i++) {
+        const r = res.rows[i];
+        const pct = totalTime > 0 ? (r.total_exec_time / totalTime * 100).toFixed(1) : "0.0";
+        const cacheHit = r.shared_blks_hit + r.shared_blks_read > 0 ? (100 * r.shared_blks_hit / (r.shared_blks_hit + r.shared_blks_read)).toFixed(1) : "N/A";
+        console.log(`
+#${i + 1} (${pct}% of total time)`);
+        console.log(`  Calls: ${fmtNum(r.calls)} | Total: ${fmtTime(r.total_exec_time)} | Mean: ${fmtTime(r.mean_exec_time)}`);
+        console.log(`  Rows: ${fmtNum(r.rows)} | Cache hit: ${cacheHit}%`);
+        console.log(`  Query: ${truncateQuery(r.query)}`);
+      }
+      console.log("\n" + "\u2550".repeat(100));
+      console.log(`
+Tip: CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+`);
+    }
+    await pool.end();
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    await pool.end();
+    process.exit(1);
+  }
 } else {
   if (subcommand && !isValidConnectionString(subcommand) && KNOWN_SUBCOMMANDS.indexOf(subcommand) === -1) {
     console.error(
@@ -5581,4 +5720,7 @@ Run pg-dash --help for usage.`
 var nodeColor2;
 var renderNode2;
 var collectNodes3;
+var fmtTime2;
+var fmtNum2;
+var truncateQuery2;
 //# sourceMappingURL=cli.js.map