@indiekitai/pg-dash 0.3.4 → 0.3.5

package/README.md

@@ -186,6 +186,59 @@ PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 | `pg_dash_export` | Export full health report (JSON or Markdown) |
 | `pg_dash_diff` | Compare current health with last saved snapshot |
 
+## MCP Setup
+
+Connect pg-dash to Claude Desktop or Cursor for AI-assisted database management.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "pg-dash": {
+      "command": "npx",
+      "args": ["-y", "-p", "@indiekitai/pg-dash", "pg-dash-mcp", "postgresql://user:pass@host/db"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "pg-dash": {
+      "command": "npx",
+      "args": ["-y", "-p", "@indiekitai/pg-dash", "pg-dash-mcp", "postgresql://user:pass@host/db"]
+    }
+  }
+}
+```
+
+### Example Conversations
+
+Once connected, you can ask your AI assistant:
+
+**Diagnosis:**
+- "What's wrong with my database right now?"
+- "Why is my `users` table slow? Check for missing indexes."
+- "Show me the top 5 slowest queries this week."
+
+**Optimization:**
+- "Generate SQL to fix all missing FK indexes in one go."
+- "EXPLAIN this query for me: SELECT * FROM orders WHERE user_id = 123"
+- "Which tables are taking up the most space?"
+
+**Pre-migration check:**
+- "Run a health check and tell me if it's safe to deploy."
+- "What changed in the schema since last week?"
+- "Check if there are any idle connections blocking my migration."
+
 ## CI Integration
 
 ### GitHub Actions
@@ -212,17 +265,45 @@ Sample workflow (`.github/workflows/pg-check.yml`):
 name: Database Health Check
 on:
   push:
-    paths: ['migrations/**', 'prisma/**', 'drizzle/**']
+    paths: ['migrations/**', 'prisma/**', 'drizzle/**', 'supabase/migrations/**']
+  pull_request:
+    paths: ['migrations/**', 'prisma/**', 'drizzle/**', 'supabase/migrations/**']
   schedule:
-    - cron: '0 8 * * 1'  # Weekly Monday 8am
+    - cron: '0 8 * * 1'  # Weekly Monday 8am UTC
 jobs:
-  check:
+  db-health:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npx @indiekitai/pg-dash check ${{ secrets.DATABASE_URL }} --ci --diff --format md
+      # Cache snapshot across ephemeral runners for --diff to work
+      - name: Restore health snapshot
+        uses: actions/cache@v4
+        with:
+          path: .pg-dash-cache
+          key: pg-dash-snapshot-${{ github.ref }}
+          restore-keys: pg-dash-snapshot-
+      - name: Run pg-dash health check
+        id: pg-check
+        run: |
+          mkdir -p .pg-dash-cache
+          npx @indiekitai/pg-dash check ${{ secrets.DATABASE_URL }} \
+            --ci --diff --snapshot-path ./.pg-dash-cache/last-check.json \
+            --format md > pg-dash-report.md 2>&1
+          echo "exit_code=$?" >> $GITHUB_OUTPUT
+        continue-on-error: true
+      - name: Save health snapshot
+        uses: actions/cache/save@v4
+        if: always()
+        with:
+          path: .pg-dash-cache
+          key: pg-dash-snapshot-${{ github.ref }}-${{ github.run_id }}
+      - name: Fail if unhealthy
+        if: steps.pg-check.outputs.exit_code != '0'
+        run: exit 1
 ```
 
+See [`examples/github-actions-pg-check.yml`](examples/github-actions-pg-check.yml) for a full workflow with PR comments.
+
 ## Health Checks
 
 pg-dash runs 46+ automated checks:

package/README.zh-CN.md

@@ -186,6 +186,59 @@ PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 | `pg_dash_export` | 导出完整健康报告（JSON 或 Markdown） |
 | `pg_dash_diff` | 与上次快照对比当前健康状态 |
 
+## MCP 配置
+
+将 pg-dash 接入 Claude Desktop 或 Cursor，实现 AI 辅助的数据库管理。
+
+### Claude Desktop
+
+在 macOS 上编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`，Windows 上编辑 `%APPDATA%\Claude\claude_desktop_config.json`：
+
+```json
+{
+  "mcpServers": {
+    "pg-dash": {
+      "command": "npx",
+      "args": ["-y", "-p", "@indiekitai/pg-dash", "pg-dash-mcp", "postgresql://user:pass@host/db"]
+    }
+  }
+}
+```
+
+### Cursor
+
+在项目的 `.cursor/mcp.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "pg-dash": {
+      "command": "npx",
+      "args": ["-y", "-p", "@indiekitai/pg-dash", "pg-dash-mcp", "postgresql://user:pass@host/db"]
+    }
+  }
+}
+```
+
+### 示例对话
+
+连接后，你可以直接问 AI 助手：
+
+**诊断问题：**
+- "我的数据库现在有什么问题？"
+- "为什么我的 `users` 表这么慢？检查一下缺失的索引。"
+- "显示本周最慢的 5 条查询。"
+
+**性能优化：**
+- "一次性生成 SQL，修复所有缺失的外键索引。"
+- "帮我分析这条查询：SELECT * FROM orders WHERE user_id = 123"
+- "哪些表占用空间最多？"
+
+**迁移前检查：**
+- "跑一次健康检查，告诉我现在部署安不安全。"
+- "上周以来 schema 有哪些变化？"
+- "检查是否有空闲连接会阻塞我的迁移。"
+
 ## CI 集成
 
 ### GitHub Actions
@@ -212,17 +265,45 @@ pg-dash check postgres://... --ci --diff --format md
 name: Database Health Check
 on:
   push:
-    paths: ['migrations/**', 'prisma/**', 'drizzle/**']
+    paths: ['migrations/**', 'prisma/**', 'drizzle/**', 'supabase/migrations/**']
+  pull_request:
+    paths: ['migrations/**', 'prisma/**', 'drizzle/**', 'supabase/migrations/**']
   schedule:
-    - cron: '0 8 * * 1'  # 每周一早 8 点
+    - cron: '0 8 * * 1'  # 每周一 UTC 早 8 点
 jobs:
-  check:
+  db-health:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npx @indiekitai/pg-dash check ${{ secrets.DATABASE_URL }} --ci --diff --format md
+      # 缓存快照，解决 ephemeral runner 丢失 ~/.pg-dash 的问题
+      - name: Restore health snapshot
+        uses: actions/cache@v4
+        with:
+          path: .pg-dash-cache
+          key: pg-dash-snapshot-${{ github.ref }}
+          restore-keys: pg-dash-snapshot-
+      - name: Run pg-dash health check
+        id: pg-check
+        run: |
+          mkdir -p .pg-dash-cache
+          npx @indiekitai/pg-dash check ${{ secrets.DATABASE_URL }} \
+            --ci --diff --snapshot-path ./.pg-dash-cache/last-check.json \
+            --format md > pg-dash-report.md 2>&1
+          echo "exit_code=$?" >> $GITHUB_OUTPUT
+        continue-on-error: true
+      - name: Save health snapshot
+        uses: actions/cache/save@v4
+        if: always()
+        with:
+          path: .pg-dash-cache
+          key: pg-dash-snapshot-${{ github.ref }}-${{ github.run_id }}
+      - name: Fail if unhealthy
+        if: steps.pg-check.outputs.exit_code != '0'
+        run: exit 1
 ```
 
+完整工作流（包含 PR 评论）请参考 [`examples/github-actions-pg-check.yml`](examples/github-actions-pg-check.yml)。
+
 ## 健康检查
 
 pg-dash 运行 46+ 项自动化检查：

package/dist/cli.js

@@ -763,26 +763,28 @@ __export(snapshot_exports, {
 });
 import fs4 from "fs";
 import path4 from "path";
-function saveSnapshot(dataDir, result) {
-  fs4.mkdirSync(dataDir, { recursive: true });
+function normalizeIssueId(id) {
+  return id.replace(/-\d+$/, "");
+}
+function saveSnapshot(snapshotPath, result) {
+  fs4.mkdirSync(path4.dirname(snapshotPath), { recursive: true });
   const snapshot = { timestamp: (/* @__PURE__ */ new Date()).toISOString(), result };
-  fs4.writeFileSync(path4.join(dataDir, SNAPSHOT_FILE), JSON.stringify(snapshot, null, 2));
+  fs4.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));
 }
-function loadSnapshot(dataDir) {
-  const filePath = path4.join(dataDir, SNAPSHOT_FILE);
-  if (!fs4.existsSync(filePath)) return null;
+function loadSnapshot(snapshotPath) {
+  if (!fs4.existsSync(snapshotPath)) return null;
   try {
-    return JSON.parse(fs4.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs4.readFileSync(snapshotPath, "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));
+  const prevNormIds = new Set(prev.issues.map((i) => normalizeIssueId(i.id)));
+  const currNormIds = new Set(current.issues.map((i) => normalizeIssueId(i.id)));
+  const newIssues = current.issues.filter((i) => !prevNormIds.has(normalizeIssueId(i.id)));
+  const resolvedIssues = prev.issues.filter((i) => !currNormIds.has(normalizeIssueId(i.id)));
+  const unchanged = current.issues.filter((i) => prevNormIds.has(normalizeIssueId(i.id)));
   return {
     scoreDelta: current.score - prev.score,
     previousScore: prev.score,
@@ -794,11 +796,9 @@ function diffSnapshots2(prev, current) {
     unchanged
   };
 }
-var SNAPSHOT_FILE;
 var init_snapshot = __esm({
   "src/server/snapshot.ts"() {
     "use strict";
-    SNAPSHOT_FILE = "last-check.json";
   }
 });
 
@@ -2707,7 +2707,7 @@ import { WebSocketServer, WebSocket } from "ws";
 import http from "http";
 var __dirname = path3.dirname(fileURLToPath(import.meta.url));
 async function startServer(opts) {
-  const pool = new Pool({ connectionString: opts.connectionString });
+  const pool = new Pool({ connectionString: opts.connectionString, connectionTimeoutMillis: 1e4 });
   try {
     const client = await pool.connect();
     client.release();
@@ -3068,7 +3068,8 @@ var { values, positionals } = parseArgs({
     threshold: { type: "string" },
     format: { type: "string", short: "f" },
     ci: { type: "boolean", default: false },
-    diff: { type: "boolean", default: false }
+    diff: { type: "boolean", default: false },
+    "snapshot-path": { type: "string" }
   }
 });
 if (values.version) {
@@ -3115,7 +3116,8 @@ Options:
   --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)
+  --diff                 Compare with previous run (saves snapshot for next run)
+  --snapshot-path <path> Path to snapshot file for --diff (default: ~/.pg-dash/last-check.json)
   -v, --version          Show version
   -h, --help             Show this help
 
@@ -3152,18 +3154,19 @@ if (subcommand === "check") {
   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 pool = new Pool2({ connectionString, connectionTimeoutMillis: 1e4 });
   const checkDataDir = values["data-dir"] || path5.join(os4.homedir(), ".pg-dash");
+  const snapshotPath = values["snapshot-path"] || path5.join(checkDataDir, "last-check.json");
   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);
+      const prev = loadSnapshot2(snapshotPath);
       if (prev) {
         diff = diffSnapshots3(prev.result, report);
       }
-      saveSnapshot2(checkDataDir, report);
+      saveSnapshot2(snapshotPath, report);
     }
     if (format === "json") {
       const output = { ...report };