@indiekitai/pg-dash 0.3.2 → 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
+```
 
 ## 健康检查