@indiekitai/pg-dash 0.3.3 → 0.3.4

package/README.md

@@ -2,22 +2,45 @@
 
 # pg-dash
 
-**Lightweight PostgreSQL monitoring dashboard.** One command to start, built-in web UI, actionable fix suggestions.
+**The AI-native PostgreSQL health checker.** One command to audit your database, 14 MCP tools for AI-assisted optimization, CI integration for automated checks.
 
-Think **pganalyze for indie devs** — no Grafana, no Prometheus, no Docker. Just `npx` and go.
+Not another monitoring dashboard — pg-dash is built to fit into your **AI coding workflow**:
+
+```
+Developer writes a migration → CI runs pg-dash check →
+Finds missing indexes → MCP tool suggests fix → PR comment
+```
 
 ```bash
-npx @indiekitai/pg-dash postgres://user:pass@host/db
+# One-shot health check
+npx @indiekitai/pg-dash check postgres://user:pass@host/db
+
+# AI assistant (Claude/Cursor) via MCP
+pg-dash-mcp postgres://user:pass@host/db
+
+# CI pipeline with diff
+npx @indiekitai/pg-dash check $DATABASE_URL --ci --diff --format md
 ```
 
-## Why?
+## Philosophy
 
-| Tool | Price | Setup | For |
-|------|-------|-------|-----|
-| pganalyze | $149+/mo | SaaS signup | Enterprises |
-| Grafana+Prometheus | Free | 3 services to configure | DevOps teams |
-| pgAdmin | Free | Complex UI | DBAs |
-| **pg-dash** | **Free** | **One command** | **Developers** |
+**Developer tools are use-and-go.** You don't stare at a PostgreSQL dashboard all day. You run a check, fix the issues, and move on. pg-dash embraces this:
+
+- **Health check** → Find problems, get actionable SQL fixes, done
+- **MCP tools** → Let your AI assistant query and fix your database directly (unique — pganalyze/pgwatch don't have this)
+- **CI integration** → Catch issues automatically on every migration, not when production is on fire
+- **Smart diff** → See what changed since last run, track your progress
+
+The Dashboard is there when you need it. But the real power is in the CLI, MCP, and CI.
+
+## Why pg-dash?
+
+| Tool | Price | Setup | AI-native | CI-ready |
+|------|-------|-------|-----------|----------|
+| pganalyze | $149+/mo | SaaS signup | ❌ | ❌ |
+| Grafana+Prometheus | Free | 3 services | ❌ | ❌ |
+| pgAdmin | Free | Complex UI | ❌ | ❌ |
+| **pg-dash** | **Free** | **One command** | **14 MCP tools** | **`--ci --diff`** |
 
 ## Features
 
@@ -144,7 +167,61 @@ pg-dash-mcp postgres://user:pass@host/db
 PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 ```
 
-Available tools: `pg_dash_overview`, `pg_dash_health`, `pg_dash_tables`, `pg_dash_table_detail`, `pg_dash_activity`, `pg_dash_schema_changes`, `pg_dash_fix`, `pg_dash_alerts`
+### Available Tools (14)
+
+| Tool | Description |
+|------|-------------|
+| `pg_dash_overview` | Database overview (version, uptime, size, connections) |
+| `pg_dash_health` | Health advisor report with score, grade, and issues |
+| `pg_dash_tables` | List all tables with sizes and row counts |
+| `pg_dash_table_detail` | Detailed info about a specific table |
+| `pg_dash_activity` | Current database activity (active queries, connections) |
+| `pg_dash_schema_changes` | Recent schema changes |
+| `pg_dash_fix` | Execute a safe fix (VACUUM, ANALYZE, REINDEX, etc.) |
+| `pg_dash_alerts` | Alert history |
+| `pg_dash_explain` | Run EXPLAIN ANALYZE on a SELECT query (read-only) |
+| `pg_dash_batch_fix` | Get batch fix SQL for issues, optionally filtered by category |
+| `pg_dash_slow_queries` | Top slow queries from pg_stat_statements |
+| `pg_dash_table_sizes` | Table sizes with data/index breakdown (top 30) |
+| `pg_dash_export` | Export full health report (JSON or Markdown) |
+| `pg_dash_diff` | Compare current health with last saved snapshot |
+
+## CI Integration
+
+### GitHub Actions
+
+Add `--ci` and `--diff` flags to integrate with CI pipelines:
+
+```bash
+# GitHub Actions annotations (::error::, ::warning::)
+pg-dash check postgres://... --ci
+
+# Markdown report for PR comments
+pg-dash check postgres://... --ci --format md
+
+# Compare with previous run
+pg-dash check postgres://... --diff
+
+# All together
+pg-dash check postgres://... --ci --diff --format md
+```
+
+Sample workflow (`.github/workflows/pg-check.yml`):
+
+```yaml
+name: Database Health Check
+on:
+  push:
+    paths: ['migrations/**', 'prisma/**', 'drizzle/**']
+  schedule:
+    - cron: '0 8 * * 1'  # Weekly Monday 8am
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx @indiekitai/pg-dash check ${{ secrets.DATABASE_URL }} --ci --diff --format md
+```
 
 ## Health Checks
 

package/README.zh-CN.md

@@ -2,22 +2,45 @@
 
 # pg-dash
 
-**轻量级 PostgreSQL 监控面板。** 一条命令启动，内置 Web UI，提供可操作的修复建议。
+**AI 原生的 PostgreSQL 健康检查工具。** 一条命令审计数据库，14 个 MCP 工具让 AI 帮你优化，CI 集成自动检查。
 
-可以理解为**给独立开发者的 pganalyze** —— 不需要 Grafana，不需要 Prometheus，不需要 Docker。只需 `npx` 即可运行。
+不是又一个监控面板 —— pg-dash 是为 **AI 编程工作流** 设计的：
+
+```
+开发者写了一个 migration → CI 跑 pg-dash check →
+发现缺失索引 → MCP 工具建议修复 → PR comment
+```
 
 ```bash
-npx @indiekitai/pg-dash postgres://user:pass@host/db
+# 一次性健康检查
+npx @indiekitai/pg-dash check postgres://user:pass@host/db
+
+# AI 助手（Claude/Cursor）通过 MCP 调用
+pg-dash-mcp postgres://user:pass@host/db
+
+# CI 流水线 + 差异对比
+npx @indiekitai/pg-dash check $DATABASE_URL --ci --diff --format md
 ```
 
+## 设计理念
+
+**开发者工具就是用完即走的。** 你不会整天盯着 PostgreSQL 监控面板。你跑一次检查，修掉问题，然后继续干活。pg-dash 就是为此设计的：
+
+- **健康检查** → 发现问题，拿到可执行的 SQL 修复建议，搞定
+- **MCP 工具** → 让 AI 助手直接查询和修复你的数据库（独一份 —— pganalyze/pgwatch 都没有）
+- **CI 集成** → 每次 migration 自动检查，不要等到生产环境出事
+- **智能 diff** → 看到上次以来的变化，追踪改进进度
+
+Dashboard 需要时可以用。但真正的核心能力在 CLI、MCP 和 CI。
+
 ## 为什么选 pg-dash？
 
-| 工具 | 价格 | 部署 | 适合 |
-|------|------|------|------|
-| pganalyze | $149+/月 | SaaS 注册 | 企业 |
-| Grafana+Prometheus | 免费 | 配置 3 个服务 | DevOps 团队 |
-| pgAdmin | 免费 | 界面复杂 | DBA |
-| **pg-dash** | **免费** | **一条命令** | **开发者** |
+| 工具 | 价格 | 部署 | AI 原生 | CI 就绪 |
+|------|------|------|---------|---------|
+| pganalyze | $149+/月 | SaaS 注册 | ❌ | ❌ |
+| Grafana+Prometheus | 免费 | 配置 3 个服务 | ❌ | ❌ |
+| pgAdmin | 免费 | 界面复杂 | ❌ | ❌ |
+| **pg-dash** | **免费** | **一条命令** | **14 个 MCP 工具** | **`--ci --diff`** |
 
 ## 功能
 
@@ -144,7 +167,61 @@ pg-dash-mcp postgres://user:pass@host/db
 PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 ```
 
-可用工具：`pg_dash_overview`、`pg_dash_health`、`pg_dash_tables`、`pg_dash_table_detail`、`pg_dash_activity`、`pg_dash_schema_changes`、`pg_dash_fix`、`pg_dash_alerts`
+### 可用工具（14 个）
+
+| 工具 | 描述 |
+|------|------|
+| `pg_dash_overview` | 数据库概览（版本、运行时间、大小、连接数） |
+| `pg_dash_health` | 健康报告（评分、等级、问题列表） |
+| `pg_dash_tables` | 所有表的大小和行数 |
+| `pg_dash_table_detail` | 单个表的详细信息 |
+| `pg_dash_activity` | 当前活动（查询、连接） |
+| `pg_dash_schema_changes` | 最近的 schema 变更 |
+| `pg_dash_fix` | 执行安全修复（VACUUM、ANALYZE、REINDEX 等） |
+| `pg_dash_alerts` | 告警历史 |
+| `pg_dash_explain` | 对 SELECT 查询运行 EXPLAIN ANALYZE（只读） |
+| `pg_dash_batch_fix` | 获取批量修复 SQL，可按类别过滤 |
+| `pg_dash_slow_queries` | pg_stat_statements 中的慢查询 |
+| `pg_dash_table_sizes` | 表大小（数据/索引拆分，前 30） |
+| `pg_dash_export` | 导出完整健康报告（JSON 或 Markdown） |
+| `pg_dash_diff` | 与上次快照对比当前健康状态 |
+
+## CI 集成
+
+### GitHub Actions
+
+使用 `--ci` 和 `--diff` 标志集成到 CI 流水线：
+
+```bash
+# GitHub Actions 注解（::error::、::warning::）
+pg-dash check postgres://... --ci
+
+# 适合 PR 评论的 Markdown 报告
+pg-dash check postgres://... --ci --format md
+
+# 与上次运行对比
+pg-dash check postgres://... --diff
+
+# 全部组合
+pg-dash check postgres://... --ci --diff --format md
+```
+
+示例工作流（`.github/workflows/pg-check.yml`）：
+
+```yaml
+name: Database Health Check
+on:
+  push:
+    paths: ['migrations/**', 'prisma/**', 'drizzle/**']
+  schedule:
+    - cron: '0 8 * * 1'  # 每周一早 8 点
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx @indiekitai/pg-dash check ${{ secrets.DATABASE_URL }} --ci --diff --format md
+```
 
 ## 健康检查
 

package/dist/cli.js

@@ -754,6 +754,54 @@ var init_advisor = __esm({
   }
 });
 
+// src/server/snapshot.ts
+var snapshot_exports = {};
+__export(snapshot_exports, {
+  diffSnapshots: () => diffSnapshots2,
+  loadSnapshot: () => loadSnapshot,
+  saveSnapshot: () => saveSnapshot
+});
+import fs4 from "fs";
+import path4 from "path";
+function saveSnapshot(dataDir, result) {
+  fs4.mkdirSync(dataDir, { recursive: true });
+  const snapshot = { timestamp: (/* @__PURE__ */ new Date()).toISOString(), result };
+  fs4.writeFileSync(path4.join(dataDir, SNAPSHOT_FILE), JSON.stringify(snapshot, null, 2));
+}
+function loadSnapshot(dataDir) {
+  const filePath = path4.join(dataDir, SNAPSHOT_FILE);
+  if (!fs4.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs4.readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function diffSnapshots2(prev, current) {
+  const prevIds = new Set(prev.issues.map((i) => i.id));
+  const currIds = new Set(current.issues.map((i) => i.id));
+  const newIssues = current.issues.filter((i) => !prevIds.has(i.id));
+  const resolvedIssues = prev.issues.filter((i) => !currIds.has(i.id));
+  const unchanged = current.issues.filter((i) => prevIds.has(i.id));
+  return {
+    scoreDelta: current.score - prev.score,
+    previousScore: prev.score,
+    currentScore: current.score,
+    previousGrade: prev.grade,
+    currentGrade: current.grade,
+    newIssues,
+    resolvedIssues,
+    unchanged
+  };
+}
+var SNAPSHOT_FILE;
+var init_snapshot = __esm({
+  "src/server/snapshot.ts"() {
+    "use strict";
+    SNAPSHOT_FILE = "last-check.json";
+  }
+});
+
 // src/cli.ts
 import { parseArgs } from "util";
 
@@ -2983,8 +3031,8 @@ async function startServer(opts) {
 }
 
 // src/cli.ts
-import fs4 from "fs";
-import path4 from "path";
+import fs5 from "fs";
+import path5 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 process.on("uncaughtException", (err) => {
   console.error("Uncaught exception:", err);
@@ -3018,13 +3066,15 @@ var { values, positionals } = parseArgs({
     help: { type: "boolean", short: "h" },
     version: { type: "boolean", short: "v" },
     threshold: { type: "string" },
-    format: { type: "string", short: "f" }
+    format: { type: "string", short: "f" },
+    ci: { type: "boolean", default: false },
+    diff: { type: "boolean", default: false }
   }
 });
 if (values.version) {
   try {
-    const __dirname2 = path4.dirname(fileURLToPath2(import.meta.url));
-    const pkg = JSON.parse(fs4.readFileSync(path4.resolve(__dirname2, "../package.json"), "utf-8"));
+    const __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
+    const pkg = JSON.parse(fs5.readFileSync(path5.resolve(__dirname2, "../package.json"), "utf-8"));
     console.log(`pg-dash v${pkg.version}`);
   } catch {
     console.log("pg-dash v0.1.0");
@@ -3064,6 +3114,8 @@ Options:
   --long-query-threshold <min> Long query threshold in minutes (default: 5)
   --threshold <score>    Health score threshold for check command (default: 70)
   -f, --format <fmt>     Output format: text|json|md (default: text)
+  --ci                   Output GitHub Actions compatible annotations
+  --diff                 Compare with previous run (saves to ~/.pg-dash/last-check.json)
   -v, --version          Show version
   -h, --help             Show this help
 
@@ -3094,50 +3146,120 @@ if (subcommand === "check") {
   const connectionString = resolveConnectionString(1);
   const threshold = parseInt(values.threshold || "70", 10);
   const format = values.format || "text";
+  const ci = values.ci || false;
+  const useDiff = values.diff || false;
   const { Pool: Pool2 } = await import("pg");
   const { getAdvisorReport: getAdvisorReport2 } = await Promise.resolve().then(() => (init_advisor(), advisor_exports));
+  const { saveSnapshot: saveSnapshot2, loadSnapshot: loadSnapshot2, diffSnapshots: diffSnapshots3 } = await Promise.resolve().then(() => (init_snapshot(), snapshot_exports));
+  const os4 = await import("os");
   const pool = new Pool2({ connectionString });
+  const checkDataDir = values["data-dir"] || path5.join(os4.homedir(), ".pg-dash");
   try {
     const lqt = parseInt(values["long-query-threshold"] || process.env.PG_DASH_LONG_QUERY_THRESHOLD || "5", 10);
     const report = await getAdvisorReport2(pool, lqt);
+    let diff = null;
+    if (useDiff) {
+      const prev = loadSnapshot2(checkDataDir);
+      if (prev) {
+        diff = diffSnapshots3(prev.result, report);
+      }
+      saveSnapshot2(checkDataDir, report);
+    }
     if (format === "json") {
-      console.log(JSON.stringify(report, null, 2));
-    } else if (format === "md") {
-      console.log(`# pg-dash Health Report
+      const output = { ...report };
+      if (diff) output.diff = diff;
+      console.log(JSON.stringify(output, null, 2));
+    } else if (format === "md" || ci && format !== "text") {
+      console.log(`## \u{1F3E5} pg-dash Health Report
 `);
-      console.log(`Generated: ${(/* @__PURE__ */ new Date()).toISOString()}
+      if (diff) {
+        const sign = diff.scoreDelta >= 0 ? "+" : "";
+        console.log(`**Score: ${diff.previousScore} \u2192 ${report.score} (${sign}${diff.scoreDelta})**
 `);
-      console.log(`## Health Score: ${report.score}/100 (Grade: ${report.grade})
+      } else {
+        console.log(`**Score: ${report.score}/100 (${report.grade})**
 `);
-      console.log(`| Category | Grade | Score | Issues |`);
+      }
+      console.log(`| Category | Score | Grade | Issues |`);
       console.log(`|----------|-------|-------|--------|`);
       for (const [cat, b] of Object.entries(report.breakdown)) {
-        console.log(`| ${cat} | ${b.grade} | ${b.score}/100 | ${b.count} |`);
+        console.log(`| ${cat} | ${b.score} | ${b.grade} | ${b.count} |`);
+      }
+      if (diff) {
+        if (diff.resolvedIssues.length > 0) {
+          console.log(`
+### \u2705 Resolved (${diff.resolvedIssues.length})`);
+          for (const i of diff.resolvedIssues) console.log(`- ~~${i.title}~~`);
+        }
+        if (diff.newIssues.length > 0) {
+          console.log(`
+### \u{1F195} New Issues (${diff.newIssues.length})`);
+          for (const i of diff.newIssues) {
+            const icon = i.severity === "critical" ? "\u{1F534}" : i.severity === "warning" ? "\u{1F7E1}" : "\u{1F535}";
+            console.log(`- ${icon} [${i.severity}] ${i.title}`);
+          }
+        }
       }
       if (report.issues.length > 0) {
         console.log(`
-### Issues (${report.issues.length})
+### \u26A0\uFE0F Issues (${report.issues.length})
 `);
         for (const issue of report.issues) {
-          const icon = issue.severity === "critical" ? "\u{1F534}" : issue.severity === "warning" ? "\u{1F7E1}" : "\u{1F535}";
-          console.log(`#### ${icon} [${issue.severity}] ${issue.title}
-`);
-          console.log(`${issue.description}
-`);
-          console.log(`**Fix**:
-\`\`\`sql
-${issue.fix}
-\`\`\`
-`);
+          const sev = issue.severity === "critical" ? "error" : issue.severity === "warning" ? "warning" : "notice";
+          console.log(`- [${sev}] ${issue.title}`);
         }
       } else {
         console.log(`
 \u2705 No issues found!`);
       }
-    } else {
+      if (report.batchFixes.length > 0) {
+        console.log(`
+### \u{1F527} Batch Fixes
+`);
+        console.log("```sql");
+        for (const fix of report.batchFixes) {
+          console.log(`-- ${fix.title}`);
+          console.log(fix.sql);
+        }
+        console.log("```");
+      }
+    } else if (ci) {
+      for (const issue of report.issues) {
+        const level = issue.severity === "critical" ? "error" : issue.severity === "warning" ? "warning" : "notice";
+        console.log(`::${level}::${issue.title}: ${issue.description}`);
+      }
       console.log(`
+Health Score: ${report.score}/100 (${report.grade})`);
+      for (const [cat, b] of Object.entries(report.breakdown)) {
+        console.log(`  ${cat.padEnd(14)} ${b.grade} (${b.score}/100) \u2014 ${b.count} issue${b.count !== 1 ? "s" : ""}`);
+      }
+      if (diff) {
+        const sign = diff.scoreDelta >= 0 ? "+" : "";
+        console.log(`
+Score: ${diff.previousScore} \u2192 ${report.score} (${sign}${diff.scoreDelta})`);
+        console.log(`Resolved: ${diff.resolvedIssues.length} issues`);
+        console.log(`New: ${diff.newIssues.length} issues`);
+      }
+    } else {
+      if (diff) {
+        const sign = diff.scoreDelta >= 0 ? "+" : "";
+        console.log(`
+  Score: ${diff.previousScore} \u2192 ${report.score} (${sign}${diff.scoreDelta})
+`);
+        if (diff.resolvedIssues.length > 0) {
+          console.log(`  \u2705 Resolved: ${diff.resolvedIssues.length} issues`);
+          for (const i of diff.resolvedIssues) console.log(`     - ${i.title}`);
+        }
+        if (diff.newIssues.length > 0) {
+          console.log(`  \u{1F195} New: ${diff.newIssues.length} issues`);
+          for (const i of diff.newIssues) console.log(`     - ${i.title}`);
+        }
+        console.log();
+      } else {
+        console.log(`
   Health Score: ${report.score}/100 (Grade: ${report.grade})
 `);
+      }
       for (const [cat, b] of Object.entries(report.breakdown)) {
         console.log(`  ${cat.padEnd(14)} ${b.grade} (${b.score}/100) \u2014 ${b.count} issue${b.count !== 1 ? "s" : ""}`);
       }
@@ -3161,9 +3283,9 @@ ${issue.fix}
   }
 } else if (subcommand === "schema-diff") {
   const connectionString = resolveConnectionString(1);
-  const dataDir = values["data-dir"] || path4.join((await import("os")).homedir(), ".pg-dash");
-  const schemaDbPath = path4.join(dataDir, "schema.db");
-  if (!fs4.existsSync(schemaDbPath)) {
+  const dataDir = values["data-dir"] || path5.join((await import("os")).homedir(), ".pg-dash");
+  const schemaDbPath = path5.join(dataDir, "schema.db");
+  if (!fs5.existsSync(schemaDbPath)) {
     console.error("No schema tracking data found. Run pg-dash server first to collect schema snapshots.");
     process.exit(1);
   }