@indiekitai/pg-dash 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IndieKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+[English](README.md) | [中文](README.zh-CN.md)
+
+# pg-dash
+
+**Lightweight PostgreSQL monitoring dashboard.** One command to start, built-in web UI, actionable fix suggestions.
+
+Think **pganalyze for indie devs** — no Grafana, no Prometheus, no Docker. Just `npx` and go.
+
+```bash
+npx @indiekitai/pg-dash postgres://user:pass@host/db
+```
+
+## Why?
+
+| 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** |
+
+## Features
+
+### 📊 Real-time Monitoring
+- Live connection count, TPS, cache hit ratio, DB size
+- Time-series charts with range selector (5m → 7d)
+- WebSocket-powered auto-refresh
+- Active query list with cancel support
+
+### 🏥 Health Advisor
+- **46+ automated checks** across performance, maintenance, schema, and security
+- A-F health grade with category breakdown
+- **One-click fixes** — not just "here's what's wrong" but "click to fix it"
+- SQL allowlist (only safe operations: VACUUM, ANALYZE, REINDEX, etc.)
+
+### 📋 Schema Browser
+- Browse all tables, columns, indexes, constraints, foreign keys
+- Sample data preview
+- Index usage stats
+- Extension and enum type listing
+
+### 🔄 Schema Change Tracking
+- Automatic schema snapshots (every 6 hours)
+- Detects: tables added/removed, columns changed, indexes modified
+- Timeline view with diff comparison
+- The sticky feature — gets more valuable over time
+
+### 🔔 Alerts
+- 7 default alert rules (connection utilization, cache ratio, long queries, etc.)
+- Custom rules via API
+- Cooldown support (no alert spam)
+- Webhook notifications
+- Alert history
+
+### 🤖 MCP Server
+- 8 tools for AI agent integration
+- `pg-dash-mcp postgres://...` — works with Claude, Cursor, etc.
+
+### 🖥️ CLI
+```bash
+# Start dashboard
+pg-dash postgres://user:pass@host/db
+
+# Health check (great for CI/CD)
+pg-dash check postgres://user:pass@host/db
+pg-dash check postgres://... --format json --threshold 70
+
+# Schema changes
+pg-dash schema-diff postgres://user:pass@host/db
+
+# JSON dump
+pg-dash postgres://... --json
+```
+
+## Quick Start
+
+```bash
+# Using npx (no install needed)
+npx @indiekitai/pg-dash postgres://user:pass@localhost/mydb
+
+# Or install globally
+npm install -g @indiekitai/pg-dash
+pg-dash postgres://user:pass@localhost/mydb
+
+# With individual options
+pg-dash --host localhost --user postgres --db mydb --port 3480
+```
+
+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
+
+Options:
+  -p, --port <port>      Dashboard port (default: 3480)
+  --no-open              Don't auto-open browser
+  --json                 Dump health check as JSON and exit
+  --host <host>          PostgreSQL host
+  -u, --user <user>      PostgreSQL user
+  --password <pass>      PostgreSQL password
+  -d, --db <database>    PostgreSQL database
+  --pg-port <port>       PostgreSQL port (default: 5432)
+  --data-dir <dir>       Data directory (default: ~/.pg-dash)
+  -i, --interval <sec>   Collection interval (default: 30)
+  --threshold <score>    Score threshold for check command (default: 70)
+  -f, --format <fmt>     Output format: text|json (default: text)
+  -v, --version          Show version
+```
+
+## MCP Server
+
+For AI agent integration:
+
+```bash
+# Start MCP server
+pg-dash-mcp postgres://user:pass@host/db
+
+# Or with env var
+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`
+
+## Health Checks
+
+pg-dash runs 46+ automated checks:
+
+**Performance**
+- Missing indexes (high sequential scans on large tables)
+- Bloated indexes (index size vs table size)
+- Table bloat (dead tuple ratio)
+- Cache efficiency per table
+- Slow queries (from pg_stat_statements)
+
+**Maintenance**
+- VACUUM overdue
+- ANALYZE overdue
+- Transaction ID wraparound risk
+- Idle connection detection
+- Idle in transaction detection
+
+**Schema**
+- Missing primary keys
+- Unused indexes (0 scans, >1MB)
+- Duplicate indexes
+- Missing foreign key indexes
+
+**Security**
+- Remote superuser connections
+- SSL disabled
+- Trust authentication (no password)
+
+## CI/CD Integration
+
+```bash
+# Fail pipeline if health score < 70
+pg-dash check postgres://... --threshold 70 --format json
+
+# Example GitHub Actions
+- name: Database Health Check
+  run: npx @indiekitai/pg-dash check ${{ secrets.DATABASE_URL }} --threshold 70
+```
+
+## Data Storage
+
+pg-dash stores metrics locally in `~/.pg-dash/`:
+- `metrics.db` — Time-series metrics (7-day retention)
+- `schema.db` — Schema snapshots and change history
+- `alerts.db` — Alert rules and history
+
+All SQLite. No external dependencies. Delete the folder to reset.
+
+## Tech Stack
+
+- **Backend**: Hono + Node.js
+- **Frontend**: React + Tailwind CSS (bundled)
+- **Storage**: SQLite (better-sqlite3)
+- **Charts**: Recharts
+- **Zero external services required**
+
+## Requirements
+
+- Node.js 18+
+- PostgreSQL 12+ (some features require 15+)
+
+## License
+
+MIT
+
+---
+
+Built by [IndieKit](https://github.com/indiekitai) 🛠️

package/README.zh-CN.md

@@ -0,0 +1,196 @@
+[English](README.md) | [中文](README.zh-CN.md)
+
+# pg-dash
+
+**轻量级 PostgreSQL 监控面板。** 一条命令启动，内置 Web UI，提供可操作的修复建议。
+
+可以理解为**给独立开发者的 pganalyze** —— 不需要 Grafana，不需要 Prometheus，不需要 Docker。只需 `npx` 即可运行。
+
+```bash
+npx @indiekitai/pg-dash postgres://user:pass@host/db
+```
+
+## 为什么选 pg-dash？
+
+| 工具 | 价格 | 部署 | 适合 |
+|------|------|------|------|
+| pganalyze | $149+/月 | SaaS 注册 | 企业 |
+| Grafana+Prometheus | 免费 | 配置 3 个服务 | DevOps 团队 |
+| pgAdmin | 免费 | 界面复杂 | DBA |
+| **pg-dash** | **免费** | **一条命令** | **开发者** |
+
+## 功能
+
+### 📊 实时监控
+- 实时连接数、TPS、缓存命中率、数据库大小
+- 带范围选择器的时序图（5分钟 → 7天）
+- WebSocket 自动刷新
+- 活跃查询列表，支持取消操作
+
+### 🏥 健康顾问
+- **46+ 项自动化检查**，覆盖性能、维护、Schema、安全等维度
+- A-F 健康评级，按类别分项展示
+- **一键修复** —— 不只告诉你哪里有问题，还能直接修复
+- SQL 白名单（仅允许安全操作：VACUUM、ANALYZE、REINDEX 等）
+
+### 📋 Schema 浏览器
+- 浏览所有表、列、索引、约束、外键
+- 数据预览
+- 索引使用统计
+- Extension 和 Enum 类型列表
+
+### 🔄 Schema 变更追踪
+- 自动 Schema 快照（每 6 小时）
+- 检测：新增/删除表、列变更、索引修改
+- 时间线视图，支持 diff 对比
+- 越用越有价值的粘性功能
+
+### 🔔 告警
+- 7 条默认告警规则（连接使用率、缓存比率、长查询等）
+- 通过 API 自定义规则
+- 冷却机制（避免告警轰炸）
+- Webhook 通知
+- 告警历史
+
+### 🤖 MCP Server
+- 8 个工具，支持 AI Agent 集成
+- `pg-dash-mcp postgres://...` —— 可配合 Claude、Cursor 等使用
+
+### 🖥️ CLI
+```bash
+# 启动面板
+pg-dash postgres://user:pass@host/db
+
+# 健康检查（适合 CI/CD）
+pg-dash check postgres://user:pass@host/db
+pg-dash check postgres://... --format json --threshold 70
+
+# Schema 变更
+pg-dash schema-diff postgres://user:pass@host/db
+
+# JSON 输出
+pg-dash postgres://... --json
+```
+
+## 快速开始
+
+```bash
+# 使用 npx（无需安装）
+npx @indiekitai/pg-dash postgres://user:pass@localhost/mydb
+
+# 或全局安装
+npm install -g @indiekitai/pg-dash
+pg-dash postgres://user:pass@localhost/mydb
+
+# 使用独立参数
+pg-dash --host localhost --user postgres --db mydb --port 3480
+```
+
+浏览器将自动打开 `http://localhost:3480`，展示完整的监控面板。
+
+## CLI 参数
+
+```
+pg-dash <connection-string>          启动面板
+pg-dash check <connection-string>    运行健康检查并退出
+pg-dash schema-diff <connection-string>  显示 Schema 变更
+
+Options:
+  -p, --port <port>      面板端口（默认：3480）
+  --no-open              不自动打开浏览器
+  --json                 以 JSON 格式输出健康检查结果并退出
+  --host <host>          PostgreSQL 主机
+  -u, --user <user>      PostgreSQL 用户
+  --password <pass>      PostgreSQL 密码
+  -d, --db <database>    PostgreSQL 数据库
+  --pg-port <port>       PostgreSQL 端口（默认：5432）
+  --data-dir <dir>       数据目录（默认：~/.pg-dash）
+  -i, --interval <sec>   采集间隔（默认：30）
+  --threshold <score>    check 命令的分数阈值（默认：70）
+  -f, --format <fmt>     输出格式：text|json（默认：text）
+  -v, --version          显示版本
+```
+
+## MCP Server
+
+用于 AI Agent 集成：
+
+```bash
+# 启动 MCP server
+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`
+
+## 健康检查
+
+pg-dash 运行 46+ 项自动化检查：
+
+**性能**
+- 缺失索引（大表上的高频顺序扫描）
+- 膨胀索引（索引大小 vs 表大小）
+- 表膨胀（死元组比例）
+- 每张表的缓存效率
+- 慢查询（来自 pg_stat_statements）
+
+**维护**
+- VACUUM 过期
+- ANALYZE 过期
+- Transaction ID 回卷风险
+- 空闲连接检测
+- Idle in transaction 检测
+
+**Schema**
+- 缺失主键
+- 未使用的索引（0 次扫描，>1MB）
+- 重复索引
+- 缺失外键索引
+
+**安全**
+- 远程超级用户连接
+- SSL 未启用
+- Trust 认证（无密码）
+
+## CI/CD 集成
+
+```bash
+# 健康分低于 70 时让流水线失败
+pg-dash check postgres://... --threshold 70 --format json
+
+# GitHub Actions 示例
+- name: Database Health Check
+  run: npx @indiekitai/pg-dash check ${{ secrets.DATABASE_URL }} --threshold 70
+```
+
+## 数据存储
+
+pg-dash 将指标存储在本地 `~/.pg-dash/` 目录：
+- `metrics.db` —— 时序指标（保留 7 天）
+- `schema.db` —— Schema 快照和变更历史
+- `alerts.db` —— 告警规则和历史
+
+全部使用 SQLite，无外部依赖。删除该目录即可重置。
+
+## 技术栈
+
+- **后端**：Hono + Node.js
+- **前端**：React + Tailwind CSS（已打包）
+- **存储**：SQLite (better-sqlite3)
+- **图表**：Recharts
+- **无需任何外部服务**
+
+## 环境要求
+
+- Node.js 18+
+- PostgreSQL 12+（部分功能需要 15+）
+
+## 许可证
+
+MIT
+
+---
+
+由 [IndieKit](https://github.com/indiekitai) 构建 🛠️