@indiekitai/pg-dash 0.4.1 → 0.4.3

package/README.md

@@ -4,6 +4,8 @@
 
 **The AI-native PostgreSQL health checker.** One command to audit your database, 23 MCP tools for AI-assisted optimization, CI integration for automated checks.
 
+📖 **[Read the full writeup on Dev.to](https://dev.to/fan_yang_670d82db29664c9e/i-built-a-free-postgresql-health-checker-with-23-mcp-tools-and-ci-integration-2abc)**
+
 Not another monitoring dashboard — pg-dash is built to fit into your **AI coding workflow**:
 
 ```
@@ -165,6 +167,13 @@ pg-dash --host localhost --user postgres --db mydb --port 3480
 
 Opens your browser at `http://localhost:3480` with the full dashboard.
 
+## Documentation
+
+- [Real-world example](docs/real-world-example.md) — pg-dash running against a production database
+- [Migration safety guide](docs/migration-safety.md) — catching lock risks before they hit production
+- [MCP setup guide](docs/mcp-setup.md) — connecting to Claude Desktop and Cursor
+- [CI integration guide](docs/ci-integration.md) — automated checks in GitHub Actions
+
 ## CLI Options
 
 ```

package/README.zh-CN.md

@@ -4,6 +4,8 @@
 
 **AI 原生的 PostgreSQL 健康检查工具。** 一条命令审计数据库，23 个 MCP 工具让 AI 帮你优化，CI 集成自动检查。
 
+📖 **[在 Dev.to 阅读完整介绍](https://dev.to/fan_yang_670d82db29664c9e/i-built-a-free-postgresql-health-checker-with-23-mcp-tools-and-ci-integration-2abc)**
+
 不是又一个监控面板 —— pg-dash 是为 **AI 编程工作流** 设计的：
 
 ```

package/dist/cli.js

@@ -970,7 +970,7 @@ var init_schema = __esm({
 });
 
 // src/server/schema-diff.ts
-function diffSnapshots(oldSnap, newSnap) {
+function diffSchemaSnapshots(oldSnap, newSnap) {
   const changes = [];
   const oldTableMap = new Map(oldSnap.tables.map((t) => [`${t.schema}.${t.name}`, t]));
   const newTableMap = new Map(newSnap.tables.map((t) => [`${t.schema}.${t.name}`, t]));
@@ -1105,12 +1105,13 @@ async function buildLiveSnapshot(pool) {
     enums: enums.map((e) => ({ name: e.name, schema: e.schema, values: e.values }))
   };
 }
-var SchemaTracker;
+var SNAPSHOT_RETENTION, SchemaTracker;
 var init_schema_tracker = __esm({
   "src/server/schema-tracker.ts"() {
     "use strict";
     init_schema();
     init_schema_diff();
+    SNAPSHOT_RETENTION = 50;
     SchemaTracker = class {
       db;
       pool;
@@ -1147,11 +1148,19 @@ var init_schema_tracker = __esm({
         const json = JSON.stringify(snapshot);
         const info = this.db.prepare("INSERT INTO schema_snapshots (timestamp, snapshot) VALUES (?, ?)").run(now, json);
         const snapshotId = Number(info.lastInsertRowid);
+        this.db.prepare(`
+      DELETE FROM schema_snapshots
+      WHERE id NOT IN (
+        SELECT id FROM schema_snapshots
+        ORDER BY timestamp DESC
+        LIMIT ?
+      )
+    `).run(SNAPSHOT_RETENTION);
         const prev = this.db.prepare("SELECT snapshot FROM schema_snapshots WHERE id < ? ORDER BY id DESC LIMIT 1").get(snapshotId);
         let changes = [];
         if (prev) {
           const oldSnap = JSON.parse(prev.snapshot);
-          changes = diffSnapshots(oldSnap, snapshot);
+          changes = diffSchemaSnapshots(oldSnap, snapshot);
           if (changes.length > 0) {
             const insert = this.db.prepare("INSERT INTO schema_changes (snapshot_id, timestamp, change_type, object_type, table_name, detail) VALUES (?, ?, ?, ?, ?, ?)");
             const tx = this.db.transaction((chs) => {
@@ -1198,7 +1207,7 @@ var init_schema_tracker = __esm({
         const from = this.db.prepare("SELECT snapshot FROM schema_snapshots WHERE id = ?").get(fromId);
         const to = this.db.prepare("SELECT snapshot FROM schema_snapshots WHERE id = ?").get(toId);
         if (!from || !to) return null;
-        return diffSnapshots(JSON.parse(from.snapshot), JSON.parse(to.snapshot));
+        return diffSchemaSnapshots(JSON.parse(from.snapshot), JSON.parse(to.snapshot));
       }
     };
   }
@@ -1207,7 +1216,7 @@ var init_schema_tracker = __esm({
 // src/server/snapshot.ts
 var snapshot_exports = {};
 __export(snapshot_exports, {
-  diffSnapshots: () => diffSnapshots2,
+  diffSnapshots: () => diffSnapshots,
   loadSnapshot: () => loadSnapshot,
   saveSnapshot: () => saveSnapshot
 });
@@ -1229,7 +1238,7 @@ function loadSnapshot(snapshotPath) {
     return null;
   }
 }
-function diffSnapshots2(prev, current) {
+function diffSnapshots(prev, current) {
   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)));
@@ -1739,7 +1748,7 @@ async function diffEnvironments(sourceConn, targetConn, options) {
     const constraintDiffs = [];
     const enumDiffs = [];
     if (sourceSnap && targetSnap) {
-      const snapChanges = diffSnapshots(sourceSnap, targetSnap);
+      const snapChanges = diffSchemaSnapshots(sourceSnap, targetSnap);
       for (const c of snapChanges) {
         if (c.object_type === "constraint") {
           constraintDiffs.push({
@@ -2417,9 +2426,14 @@ var SEVERITY_COLORS = {
   info: { hex: "#3498db", decimal: 3447003, emoji: "\u{1F535}" }
 };
 function detectWebhookType(url) {
-  if (url.includes("hooks.slack.com")) return "slack";
-  if (url.includes("discord.com/api/webhooks") || url.includes("discordapp.com")) return "discord";
-  return "generic";
+  try {
+    const { hostname } = new URL(url);
+    if (hostname.endsWith("hooks.slack.com")) return "slack";
+    if (hostname.endsWith("discord.com") || hostname.endsWith("discordapp.com")) return "discord";
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
 }
 function formatSlackMessage(alert, rule) {
   const colors = SEVERITY_COLORS[rule.severity] || SEVERITY_COLORS.info;
@@ -3895,40 +3909,32 @@ async function startServer(opts) {
     if (Object.keys(snapshot).length > 0) {
       try {
         const alertMetrics = {};
-        if (snapshot.connections_total !== void 0) {
-          const client = await pool.connect();
-          try {
-            const r = await client.query("SELECT setting::int AS max FROM pg_settings WHERE name = 'max_connections'");
+        const alertClient = await pool.connect();
+        try {
+          if (snapshot.connections_total !== void 0) {
+            const r = await alertClient.query("SELECT setting::int AS max FROM pg_settings WHERE name = 'max_connections'");
             const max = r.rows[0]?.max || 100;
             alertMetrics.connection_util = snapshot.connections_total / max * 100;
-          } finally {
-            client.release();
-          }
-        }
-        if (snapshot.cache_hit_ratio !== void 0) {
-          alertMetrics.cache_hit_pct = snapshot.cache_hit_ratio * 100;
-        }
-        try {
-          const client = await pool.connect();
-          try {
-            const r = await client.query(`SELECT count(*)::int AS c FROM pg_stat_activity WHERE state = 'active' AND now() - query_start > $1 * interval '1 minute' AND pid != pg_backend_pid()`, [longQueryThreshold]);
-            alertMetrics.long_query_count = r.rows[0]?.c || 0;
-          } finally {
-            client.release();
           }
-        } catch (err) {
-          console.error("[alerts] Error checking long queries:", err.message);
-        }
-        try {
-          const client = await pool.connect();
-          try {
-            const r = await client.query(`SELECT count(*)::int AS c FROM pg_stat_activity WHERE state = 'idle in transaction' AND now() - state_change > $1 * interval '1 minute'`, [longQueryThreshold]);
-            alertMetrics.idle_in_tx_count = r.rows[0]?.c || 0;
-          } finally {
-            client.release();
+          if (snapshot.cache_hit_ratio !== void 0) {
+            alertMetrics.cache_hit_pct = snapshot.cache_hit_ratio * 100;
           }
+          const [longQueriesResult, idleInTxResult] = await Promise.all([
+            alertClient.query(
+              `SELECT count(*)::int AS c FROM pg_stat_activity WHERE state = 'active' AND now() - query_start > $1 * interval '1 minute' AND pid != pg_backend_pid()`,
+              [longQueryThreshold]
+            ),
+            alertClient.query(
+              `SELECT count(*)::int AS c FROM pg_stat_activity WHERE state = 'idle in transaction' AND now() - state_change > $1 * interval '1 minute'`,
+              [longQueryThreshold]
+            )
+          ]);
+          alertMetrics.long_query_count = longQueriesResult.rows[0]?.c || 0;
+          alertMetrics.idle_in_tx_count = idleInTxResult.rows[0]?.c || 0;
         } catch (err) {
-          console.error("[alerts] Error checking idle-in-tx:", err.message);
+          console.error("[alerts] Error collecting alert metrics:", err.message);
+        } finally {
+          alertClient.release();
         }
         collectCycleCount++;
         if (collectCycleCount % 10 === 0) {
@@ -4114,7 +4120,12 @@ Environment variables:
 `);
   process.exit(0);
 }
+var KNOWN_SUBCOMMANDS = ["check", "check-migration", "schema-diff", "diff-env"];
 var subcommand = positionals[0];
+function isValidConnectionString(s) {
+  return s.startsWith("postgresql://") || s.startsWith("postgres://") || s.includes("@") || // user@host shorthand
+  s.includes("=");
+}
 function resolveConnectionString(startIdx = 0) {
   let connStr = positionals[startIdx];
   if (!connStr) {
@@ -4130,6 +4141,16 @@ function resolveConnectionString(startIdx = 0) {
       process.exit(1);
     }
   }
+  if (!isValidConnectionString(connStr)) {
+    console.error(
+      `Error: "${connStr}" doesn't look like a valid connection string.
+  Expected: postgresql://user:pass@host:5432/db
+
+Known subcommands: ${KNOWN_SUBCOMMANDS.join(", ")}
+Run pg-dash --help for usage.`
+    );
+    process.exit(1);
+  }
   return connStr;
 }
 if (subcommand === "check") {
@@ -4140,7 +4161,7 @@ if (subcommand === "check") {
   const useDiff = values.diff || false;
   const { Pool: Pool3 } = await import("pg");
   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 { saveSnapshot: saveSnapshot2, loadSnapshot: loadSnapshot2, diffSnapshots: diffSnapshots2 } = await Promise.resolve().then(() => (init_snapshot(), snapshot_exports));
   const os4 = await import("os");
   const pool = new Pool3({ connectionString, connectionTimeoutMillis: 1e4 });
   const checkDataDir = values["data-dir"] || path5.join(os4.homedir(), ".pg-dash");
@@ -4152,7 +4173,7 @@ if (subcommand === "check") {
     if (useDiff) {
       const prev = loadSnapshot2(snapshotPath);
       if (prev) {
-        diff = diffSnapshots3(prev.result, report);
+        diff = diffSnapshots2(prev.result, report);
       }
       saveSnapshot2(snapshotPath, report);
     }
@@ -4457,6 +4478,15 @@ Migration check: ${filePath}`);
     process.exit(1);
   }
 } else {
+  if (subcommand && !isValidConnectionString(subcommand) && KNOWN_SUBCOMMANDS.indexOf(subcommand) === -1) {
+    console.error(
+      `Error: Unknown subcommand "${subcommand}".
+
+Known subcommands: ${KNOWN_SUBCOMMANDS.join(", ")}
+Run pg-dash --help for usage.`
+    );
+    process.exit(1);
+  }
   const connectionString = resolveConnectionString(0);
   const port = parseInt(values.port, 10);
   const bind = values.bind || process.env.PG_DASH_BIND || "127.0.0.1";