@indiekitai/pg-dash 0.3.8 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 # pg-dash
 
-**The AI-native PostgreSQL health checker.** One command to audit your database, 18 MCP tools for AI-assisted optimization, CI integration for automated checks.
+**The AI-native PostgreSQL health checker.** One command to audit your database, 23 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**:
 
@@ -47,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** | **18 MCP tools** | **`--ci --diff`** |
+| **pg-dash** | **Free** | **One command** | **23 MCP tools** | **`--ci --diff`** |
 
 ## Features
 
@@ -102,7 +102,7 @@ The Dashboard is there when you need it. But the real power is in the CLI, MCP,
 
 ### 🛡️ 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`
+- Detects: `CREATE INDEX` without `CONCURRENTLY` (lock risk), `ADD COLUMN NOT NULL` without `DEFAULT`, `ALTER COLUMN TYPE` (full table rewrite), `DROP COLUMN` (app breakage risk), `ADD CONSTRAINT` without `NOT VALID` (full table scan), `CREATE INDEX CONCURRENTLY` inside a transaction (runtime failure), `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
 
@@ -113,12 +113,12 @@ The Dashboard is there when you need it. But the real power is in the CLI, MCP,
 
 ### 🔄 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
+- Detects: missing/extra tables, missing/extra columns, column type mismatches, missing/extra indexes, **foreign key and CHECK constraints**, **enum type differences**
 - `--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
-- 18 tools for AI agent integration
+- 23 tools for AI agent integration
 - `pg-dash-mcp postgres://...` — works with Claude, Cursor, etc.
 
 ### 🖥️ CLI
@@ -202,7 +202,7 @@ pg-dash-mcp postgres://user:pass@host/db
 PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 ```
 
-### Available Tools (18)
+### Available Tools (23)
 
 | Tool | Description |
 |------|-------------|
@@ -224,6 +224,11 @@ PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 | `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 |
+| `pg_dash_unused_indexes` | Find unused indexes that waste space and slow down writes |
+| `pg_dash_bloat` | Detect table bloat (dead tuples) that slow down queries |
+| `pg_dash_autovacuum` | Check autovacuum health — which tables are stale or never vacuumed |
+| `pg_dash_locks` | Show active lock waits and long-running blocking queries |
+| `pg_dash_config_check` | Audit PostgreSQL configuration and get tuning recommendations |
 
 ## MCP Setup
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 # pg-dash
 
-**AI 原生的 PostgreSQL 健康检查工具。** 一条命令审计数据库，18 个 MCP 工具让 AI 帮你优化，CI 集成自动检查。
+**AI 原生的 PostgreSQL 健康检查工具。** 一条命令审计数据库，23 个 MCP 工具让 AI 帮你优化，CI 集成自动检查。
 
 不是又一个监控面板 —— pg-dash 是为 **AI 编程工作流** 设计的：
 
@@ -47,7 +47,7 @@ Dashboard 需要时可以用。但真正的核心能力在 CLI、MCP 和 CI。
 | pganalyze | $149+/月 | SaaS 注册 | ❌ | ❌ |
 | Grafana+Prometheus | 免费 | 配置 3 个服务 | ❌ | ❌ |
 | pgAdmin | 免费 | 界面复杂 | ❌ | ❌ |
-| **pg-dash** | **免费** | **一条命令** | **18 个 MCP 工具** | **`--ci --diff`** |
+| **pg-dash** | **免费** | **一条命令** | **23 个 MCP 工具** | **`--ci --diff`** |
 
 ## 功能
 
@@ -102,7 +102,7 @@ Dashboard 需要时可以用。但真正的核心能力在 CLI、MCP 和 CI。
 
 ### 🛡️ Migration 安全检查
 - 执行迁移前分析 SQL 文件的风险
-- 检测：`CREATE INDEX`（无 `CONCURRENTLY` 会锁表）、`ADD COLUMN NOT NULL`（无 DEFAULT 会失败）、`DROP TABLE`、`TRUNCATE`、无 WHERE 的 `DELETE`/`UPDATE`
+- 检测：`CREATE INDEX`（无 `CONCURRENTLY` 会锁表）、`ADD COLUMN NOT NULL`（无 DEFAULT 会失败）、`ALTER COLUMN TYPE`（全表重写）、`DROP COLUMN`（可能 break 代码）、`ADD CONSTRAINT` 无 `NOT VALID`（全表扫描验证）、`CREATE INDEX CONCURRENTLY` 在事务内（运行时必然失败）、`DROP TABLE`、`TRUNCATE`、无 WHERE 的 `DELETE`/`UPDATE`
 - 动态检查：连接数据库验证被引用表是否存在，根据实际行数估算锁表时间
 - CI 友好：`--ci` 输出 `::error::` / `::warning::` GitHub Actions 注解
 
@@ -113,12 +113,12 @@ Dashboard 需要时可以用。但真正的核心能力在 CLI、MCP 和 CI。
 
 ### 🔄 多环境对比
 - 对比两个 PostgreSQL 环境的 Schema 和健康状态（本地 vs 预发、预发 vs 生产）
-- 检测：缺失/多余的表、缺失/多余的列、列类型不匹配、缺失/多余的索引
+- 检测：缺失/多余的表、缺失/多余的列、列类型不匹配、缺失/多余的索引、**外键和 CHECK 约束差异**、**枚举类型差异**
 - `--health` 参数额外对比健康分和各环境独有的问题
 - `pg_dash_compare_env` MCP 工具：直接问 AI "本地和预发有什么差异？"
 
 ### 🤖 MCP Server
-- 18 个工具，支持 AI Agent 集成
+- 23 个工具，支持 AI Agent 集成
 - `pg-dash-mcp postgres://...` —— 可配合 Claude、Cursor 等使用
 
 ### 🖥️ CLI
@@ -202,7 +202,7 @@ pg-dash-mcp postgres://user:pass@host/db
 PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 ```
 
-### 可用工具（18 个）
+### 可用工具（23 个）
 
 | 工具 | 描述 |
 |------|------|
@@ -224,6 +224,11 @@ PG_DASH_CONNECTION_STRING=postgres://... pg-dash-mcp
 | `pg_dash_analyze_query` | 深度 EXPLAIN 分析，自动生成索引建议 |
 | `pg_dash_query_regressions` | 检测比历史基线慢超过 50% 的查询 |
 | `pg_dash_compare_env` | 对比两个数据库环境的 Schema 和健康状态 |
+| `pg_dash_unused_indexes` | 发现从未被使用的索引（浪费空间、拖慢写入） |
+| `pg_dash_bloat` | 检测表膨胀（dead tuples 过多） |
+| `pg_dash_autovacuum` | Autovacuum 健康状态——哪些表长期未 vacuum |
+| `pg_dash_locks` | 显示活跃锁等待链和长时间阻塞的查询 |
+| `pg_dash_config_check` | 审计 PostgreSQL 配置，给出调优建议 |
 
 ## MCP 配置
 

package/dist/cli.js

@@ -1381,6 +1381,33 @@ function staticCheck(sql) {
       tableName: table
     });
   }
+  const renameTableRe = /ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(\w+)\s+RENAME\s+TO\s+(\w+)/gi;
+  while ((m = renameTableRe.exec(sql)) !== null) {
+    const oldName = m[1];
+    const newName = m[2];
+    issues.push({
+      severity: "warning",
+      code: "RENAME_TABLE",
+      message: `Renaming table "${oldName}" to "${newName}" breaks application code referencing the old name`,
+      suggestion: "Deploy application code that handles both names before renaming, or use a view with the old name after renaming.",
+      lineNumber: findLineNumber(sql, m.index),
+      tableName: oldName
+    });
+  }
+  const renameColumnRe = /ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(\w+)\s+RENAME\s+COLUMN\s+(\w+)\s+TO\s+(\w+)/gi;
+  while ((m = renameColumnRe.exec(sql)) !== null) {
+    const table = m[1];
+    const oldCol = m[2];
+    const newCol = m[3];
+    issues.push({
+      severity: "warning",
+      code: "RENAME_COLUMN",
+      message: `Renaming column "${oldCol}" to "${newCol}" on table "${table}" breaks application code referencing the old column name`,
+      suggestion: "Add new column, backfill data, update application to use new column, then drop old column (expand/contract pattern).",
+      lineNumber: findLineNumber(sql, m.index),
+      tableName: table
+    });
+  }
   const addConRe = /\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?([\w."]+)\s+ADD\s+CONSTRAINT\b[^;]*(;|$)/gi;
   while ((m = addConRe.exec(sql)) !== null) {
     const fragment = m[0];
@@ -1562,7 +1589,7 @@ async function fetchColumns(pool) {
 }
 async function fetchIndexes(pool) {
   const res = await pool.query(`
-    SELECT tablename, indexname
+    SELECT tablename, indexname, indexdef
     FROM pg_indexes
     WHERE schemaname = 'public' AND indexname NOT LIKE '%_pkey'
     ORDER BY tablename, indexname
@@ -1603,6 +1630,8 @@ function diffColumns(sourceCols, targetCols, commonTables) {
     const missingColumns = [];
     const extraColumns = [];
     const typeDiffs = [];
+    const nullableDiffs = [];
+    const defaultDiffs = [];
     for (const [colName, srcInfo] of srcMap) {
       if (!tgtMap.has(colName)) {
         missingColumns.push(srcInfo);
@@ -1611,6 +1640,12 @@ function diffColumns(sourceCols, targetCols, commonTables) {
         if (srcInfo.type !== tgtInfo.type) {
           typeDiffs.push({ column: colName, sourceType: srcInfo.type, targetType: tgtInfo.type });
         }
+        if (srcInfo.nullable !== tgtInfo.nullable) {
+          nullableDiffs.push({ column: colName, sourceNullable: srcInfo.nullable, targetNullable: tgtInfo.nullable });
+        }
+        if ((srcInfo.default ?? null) !== (tgtInfo.default ?? null)) {
+          defaultDiffs.push({ column: colName, sourceDefault: srcInfo.default ?? null, targetDefault: tgtInfo.default ?? null });
+        }
       }
     }
     for (const [colName, tgtInfo] of tgtMap) {
@@ -1618,8 +1653,8 @@ function diffColumns(sourceCols, targetCols, commonTables) {
         extraColumns.push(tgtInfo);
       }
     }
-    if (missingColumns.length > 0 || extraColumns.length > 0 || typeDiffs.length > 0) {
-      diffs.push({ table, missingColumns, extraColumns, typeDiffs });
+    if (missingColumns.length > 0 || extraColumns.length > 0 || typeDiffs.length > 0 || nullableDiffs.length > 0 || defaultDiffs.length > 0) {
+      diffs.push({ table, missingColumns, extraColumns, typeDiffs, nullableDiffs, defaultDiffs });
     }
   }
   return diffs;
@@ -1627,8 +1662,8 @@ function diffColumns(sourceCols, targetCols, commonTables) {
 function groupIndexesByTable(indexes) {
   const map = /* @__PURE__ */ new Map();
   for (const idx of indexes) {
-    if (!map.has(idx.tablename)) map.set(idx.tablename, /* @__PURE__ */ new Set());
-    map.get(idx.tablename).add(idx.indexname);
+    if (!map.has(idx.tablename)) map.set(idx.tablename, /* @__PURE__ */ new Map());
+    map.get(idx.tablename).set(idx.indexname, idx.indexdef);
   }
   return map;
 }
@@ -1642,12 +1677,21 @@ function diffIndexes(sourceIdxs, targetIdxs, commonTables) {
   ]);
   for (const table of allTables) {
     if (!commonTables.includes(table)) continue;
-    const srcSet = srcByTable.get(table) ?? /* @__PURE__ */ new Set();
-    const tgtSet = tgtByTable.get(table) ?? /* @__PURE__ */ new Set();
-    const missingIndexes = [...srcSet].filter((i) => !tgtSet.has(i));
-    const extraIndexes = [...tgtSet].filter((i) => !srcSet.has(i));
-    if (missingIndexes.length > 0 || extraIndexes.length > 0) {
-      diffs.push({ table, missingIndexes, extraIndexes });
+    const srcMap = srcByTable.get(table) ?? /* @__PURE__ */ new Map();
+    const tgtMap = tgtByTable.get(table) ?? /* @__PURE__ */ new Map();
+    const missingIndexes = [...srcMap.keys()].filter((i) => !tgtMap.has(i));
+    const extraIndexes = [...tgtMap.keys()].filter((i) => !srcMap.has(i));
+    const modifiedIndexes = [];
+    for (const [name, srcDef] of srcMap) {
+      if (tgtMap.has(name)) {
+        const tgtDef = tgtMap.get(name);
+        if (srcDef !== tgtDef) {
+          modifiedIndexes.push({ name, sourceDef: srcDef, targetDef: tgtDef });
+        }
+      }
+    }
+    if (missingIndexes.length > 0 || extraIndexes.length > 0 || modifiedIndexes.length > 0) {
+      diffs.push({ table, missingIndexes, extraIndexes, modifiedIndexes });
     }
   }
   return diffs;
@@ -1655,10 +1699,10 @@ function diffIndexes(sourceIdxs, targetIdxs, commonTables) {
 function countSchemaDrifts(schema) {
   let n = schema.missingTables.length + schema.extraTables.length;
   for (const cd of schema.columnDiffs) {
-    n += cd.missingColumns.length + cd.extraColumns.length + cd.typeDiffs.length;
+    n += cd.missingColumns.length + cd.extraColumns.length + cd.typeDiffs.length + cd.nullableDiffs.length + cd.defaultDiffs.length;
   }
   for (const id of schema.indexDiffs) {
-    n += id.missingIndexes.length + id.extraIndexes.length;
+    n += id.missingIndexes.length + id.extraIndexes.length + id.modifiedIndexes.length;
   }
   n += (schema.constraintDiffs ?? []).length;
   n += (schema.enumDiffs ?? []).length;
@@ -1795,8 +1839,31 @@ function formatTextDiff(result) {
     lines.push(`  ~ column type differences:`);
     lines.push(...typeChanges);
   }
+  const nullableChanges = [];
+  const defaultChanges = [];
+  for (const cd of schema.columnDiffs) {
+    for (const nd of cd.nullableDiffs) {
+      const src = nd.sourceNullable ? "nullable" : "NOT NULL";
+      const tgt = nd.targetNullable ? "nullable" : "NOT NULL";
+      nullableChanges.push(`      ${cd.table}.${nd.column}: source=${src} \u2192 target=${tgt}`);
+    }
+    for (const dd of cd.defaultDiffs) {
+      const src = dd.sourceDefault ?? "(none)";
+      const tgt = dd.targetDefault ?? "(none)";
+      defaultChanges.push(`      ${cd.table}.${dd.column}: source=${src} \u2192 target=${tgt}`);
+    }
+  }
+  if (nullableChanges.length > 0) {
+    lines.push(`  ~ nullable differences:`);
+    lines.push(...nullableChanges);
+  }
+  if (defaultChanges.length > 0) {
+    lines.push(`  ~ default differences:`);
+    lines.push(...defaultChanges);
+  }
   const missingIdxs = [];
   const extraIdxs = [];
+  const modifiedIdxs = [];
   for (const id of schema.indexDiffs) {
     for (const idx of id.missingIndexes) {
       missingIdxs.push(`      ${id.table}: ${idx}`);
@@ -1804,6 +1871,9 @@ function formatTextDiff(result) {
     for (const idx of id.extraIndexes) {
       extraIdxs.push(`      ${id.table}: ${idx}`);
     }
+    for (const mi of id.modifiedIndexes) {
+      modifiedIdxs.push(`      ${id.table}: ${mi.name} source="${mi.sourceDef}" \u2192 target="${mi.targetDef}"`);
+    }
   }
   if (missingIdxs.length > 0) {
     lines.push(`  \u2717 target missing indexes:`);
@@ -1813,6 +1883,10 @@ function formatTextDiff(result) {
     lines.push(`  \u26A0 target has extra indexes:`);
     lines.push(...extraIdxs);
   }
+  if (modifiedIdxs.length > 0) {
+    lines.push(`  ~ index definition differences:`);
+    lines.push(...modifiedIdxs);
+  }
   const missingConstraints = (schema.constraintDiffs ?? []).filter((c) => c.type === "missing");
   const extraConstraints = (schema.constraintDiffs ?? []).filter((c) => c.type === "extra");
   const modifiedConstraints = (schema.constraintDiffs ?? []).filter((c) => c.type === "modified");
@@ -1849,7 +1923,7 @@ function formatTextDiff(result) {
     lines.push(`  ~ enum differences:`);
     for (const e of modifiedEnums) lines.push(`      ${e.detail}`);
   }
-  const noSchemaChanges = schema.missingTables.length === 0 && schema.extraTables.length === 0 && schema.columnDiffs.length === 0 && schema.indexDiffs.length === 0 && (schema.constraintDiffs ?? []).length === 0 && (schema.enumDiffs ?? []).length === 0;
+  const noSchemaChanges = schema.missingTables.length === 0 && schema.extraTables.length === 0 && schema.columnDiffs.length === 0 && schema.indexDiffs.length === 0 && (schema.constraintDiffs ?? []).length === 0 && (schema.enumDiffs ?? []).length === 0 && nullableChanges.length === 0 && defaultChanges.length === 0 && modifiedIdxs.length === 0;
   if (noSchemaChanges) {
     lines.push(`  \u2713 Schemas are identical`);
   }
@@ -1900,14 +1974,33 @@ function formatMdDiff(result) {
   if (missingColItems.length > 0) rows.push([`\u274C Missing columns`, missingColItems.join(", ")]);
   if (extraColItems.length > 0) rows.push([`\u26A0\uFE0F Extra columns`, extraColItems.join(", ")]);
   if (typeItems.length > 0) rows.push([`~ Type differences`, typeItems.join(", ")]);
+  const nullableItems = [];
+  const defaultItems = [];
+  for (const cd of schema.columnDiffs) {
+    for (const nd of cd.nullableDiffs) {
+      const src = nd.sourceNullable ? "nullable" : "NOT NULL";
+      const tgt = nd.targetNullable ? "nullable" : "NOT NULL";
+      nullableItems.push(`\`${cd.table}.${nd.column}\` (${src}\u2192${tgt})`);
+    }
+    for (const dd of cd.defaultDiffs) {
+      const src = dd.sourceDefault ?? "(none)";
+      const tgt = dd.targetDefault ?? "(none)";
+      defaultItems.push(`\`${cd.table}.${dd.column}\` (${src}\u2192${tgt})`);
+    }
+  }
+  if (nullableItems.length > 0) rows.push([`~ Nullable differences`, nullableItems.join(", ")]);
+  if (defaultItems.length > 0) rows.push([`~ Default differences`, defaultItems.join(", ")]);
   const missingIdxItems = [];
   const extraIdxItems = [];
+  const modifiedIdxItems = [];
   for (const id of schema.indexDiffs) {
     for (const idx of id.missingIndexes) missingIdxItems.push(`\`${id.table}.${idx}\``);
     for (const idx of id.extraIndexes) extraIdxItems.push(`\`${id.table}.${idx}\``);
+    for (const mi of id.modifiedIndexes) modifiedIdxItems.push(`\`${id.table}.${mi.name}\``);
   }
   if (missingIdxItems.length > 0) rows.push([`\u274C Missing indexes`, missingIdxItems.join(", ")]);
   if (extraIdxItems.length > 0) rows.push([`\u26A0\uFE0F Extra indexes`, extraIdxItems.join(", ")]);
+  if (modifiedIdxItems.length > 0) rows.push([`~ Modified indexes`, modifiedIdxItems.join(", ")]);
   const missingConItems = (schema.constraintDiffs ?? []).filter((c) => c.type === "missing").map((c) => c.detail);
   const extraConItems = (schema.constraintDiffs ?? []).filter((c) => c.type === "extra").map((c) => c.detail);
   const modConItems = (schema.constraintDiffs ?? []).filter((c) => c.type === "modified").map((c) => c.detail);
@@ -3057,12 +3150,23 @@ async function analyzeExplainPlan(explainJson, pool) {
     if (pool) {
       existingIndexCols = await getExistingIndexColumns(pool, scan.table);
     }
-    for (const col of cols) {
-      const alreadyCovered = existingIndexCols.some(
-        (idxCols) => idxCols.length > 0 && idxCols[0] === col
-      );
-      if (alreadyCovered) continue;
-      const benefit = rateBenefit(scan.rowCount);
+    const uncoveredCols = cols.filter(
+      (col) => !existingIndexCols.some((idxCols) => idxCols.length > 0 && idxCols[0] === col)
+    );
+    if (uncoveredCols.length === 0) continue;
+    const benefit = rateBenefit(scan.rowCount);
+    if (uncoveredCols.length >= 2) {
+      const idxName = `idx_${scan.table}_${uncoveredCols.join("_")}`;
+      const sql = `CREATE INDEX CONCURRENTLY ${idxName} ON ${scan.table} (${uncoveredCols.join(", ")})`;
+      result.missingIndexes.push({
+        table: scan.table,
+        columns: uncoveredCols,
+        reason: `Seq Scan with multi-column filter (${uncoveredCols.join(", ")}) on ${fmtRows(scan.rowCount)} rows \u2014 composite index preferred`,
+        sql,
+        estimatedBenefit: benefit
+      });
+    } else {
+      const col = uncoveredCols[0];
       const idxName = `idx_${scan.table}_${col}`;
       const sql = `CREATE INDEX CONCURRENTLY ${idxName} ON ${scan.table} (${col})`;
       result.missingIndexes.push({