@indiekitai/pg-dash 0.3.6 → 0.3.7

package/README.md

@@ -2,19 +2,26 @@
 
 # pg-dash
 
-**The AI-native PostgreSQL health checker.** One command to audit your database, 14 MCP tools for AI-assisted optimization, CI integration for automated checks.
+**The AI-native PostgreSQL health checker.** One command to audit your database, 18 MCP tools for AI-assisted optimization, CI integration for automated checks.
 
 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
+Developer writes a migration → pg-dash check-migration (pre-flight) →
+CI runs pg-dash check → Finds missing indexes →
+MCP tool suggests fix → PR comment
 ```
 
 ```bash
 # One-shot health check
 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
+
+# Compare two environments (local vs staging)
+npx @indiekitai/pg-dash diff-env --source postgres://localhost/db --target postgres://staging/db
+
 # AI assistant (Claude/Cursor) via MCP
 pg-dash-mcp postgres://user:pass@host/db
 
@@ -40,7 +47,7 @@ The Dashboard is there when you need it. But the real power is in the CLI, MCP,
 | pganalyze | $149+/mo | SaaS signup | ❌ | ❌ |
 | Grafana+Prometheus | Free | 3 services | ❌ | ❌ |
 | pgAdmin | Free | Complex UI | ❌ | ❌ |
-| **pg-dash** | **Free** | **One command** | **14 MCP tools** | **`--ci --diff`** |
+| **pg-dash** | **Free** | **One command** | **18 MCP tools** | **`--ci --diff`** |
 
 ## Features
 
@@ -93,8 +100,25 @@ 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`
 
+### 🛡️ 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`, `DROP TABLE`, `TRUNCATE`, `DELETE`/`UPDATE` without `WHERE`
+- Dynamic checks: connects to DB to verify referenced tables exist, estimates lock time based on actual row counts
+- CI-ready: `--ci` flag emits `::error::` / `::warning::` GitHub Actions annotations
+
+### 🧠 Query Intelligence
+- `pg_dash_analyze_query` — runs `EXPLAIN ANALYZE`, detects Seq Scans on large tables, auto-generates `CREATE INDEX CONCURRENTLY` suggestions with benefit ratings
+- `pg_dash_query_regressions` — finds queries that got >50% slower vs historical baseline (requires `pg_stat_statements`)
+- EXPLAIN Modal in dashboard shows index suggestions inline
+
+### 🔄 Multi-Env Diff
+- Compare schema and health between two PostgreSQL environments (local vs staging, staging vs prod)
+- Detects: missing/extra tables, missing/extra columns, column type mismatches, missing/extra indexes
+- `--health` flag adds health score comparison and unique issues per environment
+- `pg_dash_compare_env` MCP tool: ask your AI "what's different between local and staging?"
+
 ### 🤖 MCP Server
-- 14 tools for AI agent integration
+- 18 tools for AI agent integration
 - `pg-dash-mcp postgres://...` — works with Claude, Cursor, etc.
 
 ### 🖥️ CLI
@@ -106,11 +130,16 @@ pg-dash postgres://user:pass@host/db
 pg-dash check postgres://user:pass@host/db
 pg-dash check postgres://... --format json --threshold 70
 
+# Migration safety check
+pg-dash check-migration ./migrations/015_add_index.sql
+pg-dash check-migration ./migrations/015_add_index.sql postgres://... --ci
+
+# Multi-env schema diff
+pg-dash diff-env --source postgres://localhost/db --target postgres://staging/db
+pg-dash diff-env --source postgres://... --target postgres://... --health --format md
+
 # Schema changes
 pg-dash schema-diff postgres://user:pass@host/db
-
-# JSON dump
-pg-dash postgres://... --json
 ```
 
 ## Quick Start
@@ -132,9 +161,11 @@ Opens your browser at `http://localhost:3480` with the full dashboard.
 ## CLI Options
 
 ```
-pg-dash <connection-string>          Start dashboard
-pg-dash check <connection-string>    Run health check and exit
-pg-dash schema-diff <connection-string>  Show schema changes
+pg-dash <connection-string>               Start dashboard
+pg-dash check <connection-string>         Run health check and exit
+pg-dash check-migration <file> [conn]     Analyze migration SQL for risks
+pg-dash diff-env --source <url> --target <url>  Compare two environments
+pg-dash schema-diff <connection-string>   Show schema changes
 
 Options:
   -p, --port <port>      Dashboard port (default: 3480)
@@ -152,6 +183,10 @@ Options:
   --query-stats-interval <min>  Query stats snapshot interval in minutes (default: 5)
   --slack-webhook <url>  Slack webhook URL for alert notifications
   --discord-webhook <url>  Discord webhook URL for alert notifications
+  --ci                   Output GitHub Actions annotations (check, check-migration, diff-env)
+  --diff                 Compare with last snapshot (check command)
+  --snapshot-path <path> Path to snapshot file for --diff
+  --health               Include health comparison (diff-env)
   -v, --version          Show version
 ```
 
@@ -167,7 +202,7 @@ pg-dash-mcp postgres://user:pass@host/db
 PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 ```
 
-### Available Tools (14)
+### Available Tools (18)
 
 | Tool | Description |
 |------|-------------|
@@ -185,6 +220,10 @@ PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 | `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 |
+| `pg_dash_check_migration` | Analyze migration SQL for lock risks, missing tables, destructive ops |
+| `pg_dash_analyze_query` | Deep EXPLAIN analysis with automatic index suggestions |
+| `pg_dash_query_regressions` | Detect queries that degraded >50% vs historical baseline |
+| `pg_dash_compare_env` | Compare schema and health between two database environments |
 
 ## MCP Setup
 

package/README.zh-CN.md

@@ -2,19 +2,26 @@
 
 # pg-dash
 
-**AI 原生的 PostgreSQL 健康检查工具。** 一条命令审计数据库，14 个 MCP 工具让 AI 帮你优化，CI 集成自动检查。
+**AI 原生的 PostgreSQL 健康检查工具。** 一条命令审计数据库，18 个 MCP 工具让 AI 帮你优化，CI 集成自动检查。
 
 不是又一个监控面板 —— pg-dash 是为 **AI 编程工作流** 设计的：
 
 ```
-开发者写了一个 migration → CI 跑 pg-dash check →
-发现缺失索引 → MCP 工具建议修复 → PR comment
+开发者写了一个 migration → pg-dash check-migration（执行前检查）→
+CI 跑 pg-dash check → 发现缺失索引 →
+MCP 工具建议修复 → PR comment
 ```
 
 ```bash
 # 一次性健康检查
 npx @indiekitai/pg-dash check postgres://user:pass@host/db
 
+# 执行 migration 前检查风险
+npx @indiekitai/pg-dash check-migration ./migrations/015_add_index.sql
+
+# 对比两个环境（本地 vs 预发）
+npx @indiekitai/pg-dash diff-env --source postgres://localhost/db --target postgres://staging/db
+
 # AI 助手（Claude/Cursor）通过 MCP 调用
 pg-dash-mcp postgres://user:pass@host/db
 
@@ -40,7 +47,7 @@ Dashboard 需要时可以用。但真正的核心能力在 CLI、MCP 和 CI。
 | pganalyze | $149+/月 | SaaS 注册 | ❌ | ❌ |
 | Grafana+Prometheus | 免费 | 配置 3 个服务 | ❌ | ❌ |
 | pgAdmin | 免费 | 界面复杂 | ❌ | ❌ |
-| **pg-dash** | **免费** | **一条命令** | **14 个 MCP 工具** | **`--ci --diff`** |
+| **pg-dash** | **免费** | **一条命令** | **18 个 MCP 工具** | **`--ci --diff`** |
 
 ## 功能
 
@@ -93,8 +100,25 @@ Dashboard 需要时可以用。但真正的核心能力在 CLI、MCP 和 CI。
 - 自动识别 Slack / Discord webhook URL
 - 通过 `--slack-webhook` 或 `--discord-webhook` 配置
 
+### 🛡️ Migration 安全检查
+- 执行迁移前分析 SQL 文件的风险
+- 检测：`CREATE INDEX`（无 `CONCURRENTLY` 会锁表）、`ADD COLUMN NOT NULL`（无 DEFAULT 会失败）、`DROP TABLE`、`TRUNCATE`、无 WHERE 的 `DELETE`/`UPDATE`
+- 动态检查：连接数据库验证被引用表是否存在，根据实际行数估算锁表时间
+- CI 友好：`--ci` 输出 `::error::` / `::warning::` GitHub Actions 注解
+
+### 🧠 查询智能诊断
+- `pg_dash_analyze_query` —— 运行 `EXPLAIN ANALYZE`，检测大表的 Seq Scan，自动生成带 benefit 评级的 `CREATE INDEX CONCURRENTLY` 建议
+- `pg_dash_query_regressions` —— 找出比历史基线慢超过 50% 的查询（需要 `pg_stat_statements`）
+- 面板 EXPLAIN 弹窗内联展示索引建议
+
+### 🔄 多环境对比
+- 对比两个 PostgreSQL 环境的 Schema 和健康状态（本地 vs 预发、预发 vs 生产）
+- 检测：缺失/多余的表、缺失/多余的列、列类型不匹配、缺失/多余的索引
+- `--health` 参数额外对比健康分和各环境独有的问题
+- `pg_dash_compare_env` MCP 工具：直接问 AI "本地和预发有什么差异？"
+
 ### 🤖 MCP Server
-- 8 个工具，支持 AI Agent 集成
+- 18 个工具，支持 AI Agent 集成
 - `pg-dash-mcp postgres://...` —— 可配合 Claude、Cursor 等使用
 
 ### 🖥️ CLI
@@ -106,11 +130,16 @@ pg-dash postgres://user:pass@host/db
 pg-dash check postgres://user:pass@host/db
 pg-dash check postgres://... --format json --threshold 70
 
+# Migration 安全检查
+pg-dash check-migration ./migrations/015_add_index.sql
+pg-dash check-migration ./migrations/015_add_index.sql postgres://... --ci
+
+# 多环境 Schema 对比
+pg-dash diff-env --source postgres://localhost/db --target postgres://staging/db
+pg-dash diff-env --source postgres://... --target postgres://... --health --format md
+
 # Schema 变更
 pg-dash schema-diff postgres://user:pass@host/db
-
-# JSON 输出
-pg-dash postgres://... --json
 ```
 
 ## 快速开始
@@ -132,9 +161,11 @@ pg-dash --host localhost --user postgres --db mydb --port 3480
 ## CLI 参数
 
 ```
-pg-dash <connection-string>          启动面板
-pg-dash check <connection-string>    运行健康检查并退出
-pg-dash schema-diff <connection-string>  显示 Schema 变更
+pg-dash <connection-string>                      启动面板
+pg-dash check <connection-string>                运行健康检查并退出
+pg-dash check-migration <file> [conn]            检查 migration SQL 的风险
+pg-dash diff-env --source <url> --target <url>   对比两个环境
+pg-dash schema-diff <connection-string>          显示 Schema 变更
 
 Options:
   -p, --port <port>      面板端口（默认：3480）
@@ -148,10 +179,14 @@ Options:
   --data-dir <dir>       数据目录（默认：~/.pg-dash）
   -i, --interval <sec>   采集间隔（默认：30）
   --threshold <score>    check 命令的分数阈值（默认：70）
-  -f, --format <fmt>     输出格式：text|json（默认：text）
+  -f, --format <fmt>     输出格式：text|json|md（默认：text）
   --query-stats-interval <min>  查询统计快照间隔，单位分钟（默认：5）
   --slack-webhook <url>  Slack webhook URL，用于告警通知
   --discord-webhook <url>  Discord webhook URL，用于告警通知
+  --ci                   输出 GitHub Actions 注解（check、check-migration、diff-env）
+  --diff                 与上次快照对比（check 命令）
+  --snapshot-path <path> --diff 使用的快照文件路径
+  --health               包含健康对比（diff-env）
   -v, --version          显示版本
 ```
 
@@ -167,7 +202,7 @@ pg-dash-mcp postgres://user:pass@host/db
 PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 ```
 
-### 可用工具（14 个）
+### 可用工具（18 个）
 
 | 工具 | 描述 |
 |------|------|
@@ -185,6 +220,10 @@ PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 | `pg_dash_table_sizes` | 表大小（数据/索引拆分，前 30） |
 | `pg_dash_export` | 导出完整健康报告（JSON 或 Markdown） |
 | `pg_dash_diff` | 与上次快照对比当前健康状态 |
+| `pg_dash_check_migration` | 分析 migration SQL 的锁表风险、缺失表、破坏性操作 |
+| `pg_dash_analyze_query` | 深度 EXPLAIN 分析，自动生成索引建议 |
+| `pg_dash_query_regressions` | 检测比历史基线慢超过 50% 的查询 |
+| `pg_dash_compare_env` | 对比两个数据库环境的 Schema 和健康状态 |
 
 ## MCP 配置
 

package/dist/cli.js

@@ -3814,10 +3814,11 @@ if (values.help) {
 pg-dash \u2014 Lightweight PostgreSQL Monitoring Dashboard
 
 Usage:
-  pg-dash <connection-string>
-  pg-dash check <connection-string>     Run health check and exit
-  pg-dash schema-diff <connection-string> Show latest schema changes
-  pg-dash diff-env --source <url> --target <url>  Compare two environments
+  pg-dash <connection-string>                           Start dashboard
+  pg-dash check <connection-string>                     Run health check and exit
+  pg-dash check-migration <file> [connection]           Analyze migration SQL for risks
+  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
 
 Options:
@@ -4102,6 +4103,7 @@ Migration check: ${filePath}`);
   }
 } else if (subcommand === "schema-diff") {
   const connectionString = resolveConnectionString(1);
+  const format = values.format || "text";
   const dataDir = values["data-dir"] || path5.join((await import("os")).homedir(), ".pg-dash");
   const schemaDbPath = path5.join(dataDir, "schema.db");
   if (!fs5.existsSync(schemaDbPath)) {
@@ -4112,18 +4114,29 @@ Migration check: ${filePath}`);
   const db = new Database4(schemaDbPath, { readonly: true });
   const changes = db.prepare("SELECT * FROM schema_changes ORDER BY timestamp DESC LIMIT 50").all();
   db.close();
-  if (changes.length === 0) {
-    console.log("No schema changes detected.");
+  if (format === "json") {
+    console.log(JSON.stringify(changes.map((c) => ({
+      type: c.change_type,
+      objectType: c.object_type,
+      objectName: c.object_name,
+      tableName: c.table_name,
+      detail: c.detail,
+      timestamp: c.timestamp
+    })), null, 2));
   } else {
-    console.log(`
+    if (changes.length === 0) {
+      console.log("No schema changes detected.");
+    } else {
+      console.log(`
   Schema Changes (${changes.length}):
 `);
-    for (const c of changes) {
-      const icon = c.change_type === "added" ? "\uFF0B" : c.change_type === "removed" ? "\u2212" : "~";
-      const color = c.change_type === "added" ? "\x1B[32m" : c.change_type === "removed" ? "\x1B[31m" : "\x1B[33m";
-      console.log(`  ${color}${icon}\x1B[0m ${c.detail}${c.table_name ? ` (${c.table_name})` : ""} \u2014 ${new Date(c.timestamp).toLocaleString()}`);
+      for (const c of changes) {
+        const icon = c.change_type === "added" ? "\uFF0B" : c.change_type === "removed" ? "\u2212" : "~";
+        const color = c.change_type === "added" ? "\x1B[32m" : c.change_type === "removed" ? "\x1B[31m" : "\x1B[33m";
+        console.log(`  ${color}${icon}\x1B[0m ${c.detail}${c.table_name ? ` (${c.table_name})` : ""} \u2014 ${new Date(c.timestamp).toLocaleString()}`);
+      }
+      console.log();
     }
-    console.log();
   }
   process.exit(0);
 } else if (subcommand === "diff-env") {