@indiekitai/pg-dash 0.3.4 → 0.3.6

package/dist/cli.js

@@ -763,26 +763,28 @@ __export(snapshot_exports, {
 });
 import fs4 from "fs";
 import path4 from "path";
-function saveSnapshot(dataDir, result) {
-  fs4.mkdirSync(dataDir, { recursive: true });
+function normalizeIssueId(id) {
+  return id.replace(/-\d+$/, "");
+}
+function saveSnapshot(snapshotPath, result) {
+  fs4.mkdirSync(path4.dirname(snapshotPath), { recursive: true });
   const snapshot = { timestamp: (/* @__PURE__ */ new Date()).toISOString(), result };
-  fs4.writeFileSync(path4.join(dataDir, SNAPSHOT_FILE), JSON.stringify(snapshot, null, 2));
+  fs4.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));
 }
-function loadSnapshot(dataDir) {
-  const filePath = path4.join(dataDir, SNAPSHOT_FILE);
-  if (!fs4.existsSync(filePath)) return null;
+function loadSnapshot(snapshotPath) {
+  if (!fs4.existsSync(snapshotPath)) return null;
   try {
-    return JSON.parse(fs4.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs4.readFileSync(snapshotPath, "utf-8"));
   } catch {
     return null;
   }
 }
 function diffSnapshots2(prev, current) {
-  const prevIds = new Set(prev.issues.map((i) => i.id));
-  const currIds = new Set(current.issues.map((i) => i.id));
-  const newIssues = current.issues.filter((i) => !prevIds.has(i.id));
-  const resolvedIssues = prev.issues.filter((i) => !currIds.has(i.id));
-  const unchanged = current.issues.filter((i) => prevIds.has(i.id));
+  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)));
+  const resolvedIssues = prev.issues.filter((i) => !currNormIds.has(normalizeIssueId(i.id)));
+  const unchanged = current.issues.filter((i) => prevNormIds.has(normalizeIssueId(i.id)));
   return {
     scoreDelta: current.score - prev.score,
     previousScore: prev.score,
@@ -794,11 +796,593 @@ function diffSnapshots2(prev, current) {
     unchanged
   };
 }
-var SNAPSHOT_FILE;
 var init_snapshot = __esm({
   "src/server/snapshot.ts"() {
     "use strict";
-    SNAPSHOT_FILE = "last-check.json";
+  }
+});
+
+// src/server/migration-checker.ts
+var migration_checker_exports = {};
+__export(migration_checker_exports, {
+  analyzeMigration: () => analyzeMigration
+});
+function stripComments(sql) {
+  let stripped = sql.replace(
+    /\/\*[\s\S]*?\*\//g,
+    (match) => match.replace(/[^\n]/g, " ")
+  );
+  stripped = stripped.replace(/--[^\n]*/g, (match) => " ".repeat(match.length));
+  return stripped;
+}
+function findLineNumber(sql, matchIndex) {
+  const before = sql.slice(0, matchIndex);
+  return before.split("\n").length;
+}
+function bareTable(name) {
+  return name.replace(/^public\./i, "").replace(/"/g, "").toLowerCase().trim();
+}
+function extractOperatedTables(sql) {
+  sql = stripComments(sql);
+  const indexTables = [];
+  const alterTables = [];
+  const dropTables = [];
+  const refTables = [];
+  const idxRe = /\bCREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?(?:\w+\s+)?ON\s+([\w."]+)/gi;
+  let m;
+  while ((m = idxRe.exec(sql)) !== null) indexTables.push(bareTable(m[1]));
+  const altRe = /\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?([\w."]+)/gi;
+  while ((m = altRe.exec(sql)) !== null) alterTables.push(bareTable(m[1]));
+  const dropRe = /\bDROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?([\w."]+)/gi;
+  while ((m = dropRe.exec(sql)) !== null) dropTables.push(bareTable(m[1]));
+  const refRe = /\bREFERENCES\s+([\w."]+)/gi;
+  while ((m = refRe.exec(sql)) !== null) refTables.push(bareTable(m[1]));
+  return { indexTables, alterTables, dropTables, refTables };
+}
+function staticCheck(sql) {
+  const issues = [];
+  sql = stripComments(sql);
+  const createdTablesRe = /\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([\w."]+)/gi;
+  const createdTables = /* @__PURE__ */ new Set();
+  let m;
+  while ((m = createdTablesRe.exec(sql)) !== null) createdTables.add(bareTable(m[1]));
+  const idxRe = /\bCREATE\s+(?:UNIQUE\s+)?INDEX\s+(?!CONCURRENTLY)((?:IF\s+NOT\s+EXISTS\s+)?(?:\w+\s+)?ON\s+([\w."]+))/gi;
+  while ((m = idxRe.exec(sql)) !== null) {
+    const table = bareTable(m[2]);
+    const lineNumber = findLineNumber(sql, m.index);
+    if (!createdTables.has(table)) {
+      issues.push({
+        severity: "warning",
+        code: "INDEX_WITHOUT_CONCURRENTLY",
+        message: `CREATE INDEX on existing table will lock writes. Use CREATE INDEX CONCURRENTLY to avoid downtime.`,
+        suggestion: "Replace CREATE INDEX with CREATE INDEX CONCURRENTLY",
+        lineNumber,
+        tableName: table
+      });
+    }
+  }
+  const idxConcRe = /\bCREATE\s+(?:UNIQUE\s+)?INDEX\s+CONCURRENTLY\b/gi;
+  while ((m = idxConcRe.exec(sql)) !== null) {
+    issues.push({
+      severity: "info",
+      code: "INDEX_CONCURRENTLY_OK",
+      message: "CREATE INDEX CONCURRENTLY \u2014 safe, no write lock",
+      lineNumber: findLineNumber(sql, m.index)
+    });
+  }
+  const addColRe = /\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?([\w."]+)\s+ADD\s+(?:COLUMN\s+)?(?:IF\s+NOT\s+EXISTS\s+)?[\w"]+\s+[\w\s()"',.[\]]+?(?=;|$)/gi;
+  while ((m = addColRe.exec(sql)) !== null) {
+    const fragment = m[0];
+    const table = bareTable(m[1]);
+    const lineNumber = findLineNumber(sql, m.index);
+    const fragUpper = fragment.toUpperCase();
+    const hasNotNull = /\bNOT\s+NULL\b/.test(fragUpper);
+    const hasDefault = /\bDEFAULT\b/.test(fragUpper);
+    if (hasNotNull && !hasDefault) {
+      issues.push({
+        severity: "error",
+        code: "ADD_COLUMN_NOT_NULL_NO_DEFAULT",
+        message: "ADD COLUMN NOT NULL without DEFAULT will fail if table has existing rows",
+        suggestion: "Add a DEFAULT value, then remove it after migration",
+        lineNumber,
+        tableName: table
+      });
+    } else if (hasNotNull && hasDefault) {
+      issues.push({
+        severity: "warning",
+        code: "ADD_COLUMN_REWRITES_TABLE",
+        message: "ADD COLUMN with NOT NULL DEFAULT may rewrite table on PostgreSQL < 11",
+        suggestion: "On PostgreSQL 11+ with a constant default this is safe. For older versions, add column nullable first.",
+        lineNumber,
+        tableName: table
+      });
+    }
+  }
+  const dropRe = /\bDROP\s+TABLE\b/gi;
+  while ((m = dropRe.exec(sql)) !== null) {
+    issues.push({
+      severity: "warning",
+      code: "DROP_TABLE",
+      message: "DROP TABLE is destructive. Ensure this is intentional and data is backed up.",
+      lineNumber: findLineNumber(sql, m.index)
+    });
+  }
+  const truncRe = /\bTRUNCATE\b/gi;
+  while ((m = truncRe.exec(sql)) !== null) {
+    issues.push({
+      severity: "warning",
+      code: "TRUNCATE_TABLE",
+      message: "TRUNCATE will delete all rows. Ensure this is intentional.",
+      lineNumber: findLineNumber(sql, m.index)
+    });
+  }
+  const delRe = /\bDELETE\s+FROM\s+[\w."]+\s*(?:;|$)/gi;
+  while ((m = delRe.exec(sql)) !== null) {
+    const stmt = m[0];
+    if (!/\bWHERE\b/i.test(stmt)) {
+      issues.push({
+        severity: "warning",
+        code: "DELETE_WITHOUT_WHERE",
+        message: "DELETE without WHERE clause will remove all rows.",
+        lineNumber: findLineNumber(sql, m.index)
+      });
+    }
+  }
+  const updRe = /\bUPDATE\s+[\w."]+\s+SET\b[^;]*(;|$)/gi;
+  while ((m = updRe.exec(sql)) !== null) {
+    const stmt = m[0];
+    if (!/\bWHERE\b/i.test(stmt)) {
+      issues.push({
+        severity: "warning",
+        code: "UPDATE_WITHOUT_WHERE",
+        message: "UPDATE without WHERE clause will modify all rows.",
+        lineNumber: findLineNumber(sql, m.index)
+      });
+    }
+  }
+  return issues;
+}
+async function dynamicCheck(sql, pool, staticIssues) {
+  const issues = [];
+  const { indexTables, alterTables, dropTables, refTables } = extractOperatedTables(sql);
+  const allTables = [.../* @__PURE__ */ new Set([...indexTables, ...alterTables, ...dropTables])];
+  const tableStats = /* @__PURE__ */ new Map();
+  if (allTables.length > 0) {
+    try {
+      const res = await pool.query(
+        `SELECT tablename,
+                n_live_tup,
+                pg_total_relation_size(schemaname||'.'||tablename) AS total_size
+         FROM pg_stat_user_tables
+         WHERE tablename = ANY($1)`,
+        [allTables]
+      );
+      for (const row of res.rows) {
+        tableStats.set(row.tablename, {
+          rowCount: parseInt(row.n_live_tup ?? "0", 10),
+          totalSize: parseInt(row.total_size ?? "0", 10)
+        });
+      }
+    } catch (_) {
+    }
+  }
+  for (const issue of staticIssues) {
+    if (issue.code === "INDEX_WITHOUT_CONCURRENTLY" && issue.tableName) {
+      const stats = tableStats.get(issue.tableName);
+      if (stats) {
+        const { rowCount } = stats;
+        const lockSecs = Math.round(rowCount / 5e4);
+        issue.estimatedRows = rowCount;
+        issue.estimatedLockSeconds = lockSecs;
+        if (rowCount > 1e6) {
+          issue.severity = "error";
+          issue.message = `CREATE INDEX on '${issue.tableName}' will lock writes for ~${lockSecs}s (${(rowCount / 1e6).toFixed(1)}M rows). CRITICAL \u2014 use CREATE INDEX CONCURRENTLY.`;
+        } else if (rowCount > 1e5) {
+          issue.message = `CREATE INDEX on '${issue.tableName}' will lock writes for ~${lockSecs}s (${(rowCount / 1e3).toFixed(0)}k rows).`;
+        }
+      }
+    }
+  }
+  const uniqueRefTables = [...new Set(refTables)];
+  for (const table of uniqueRefTables) {
+    try {
+      const res = await pool.query(
+        `SELECT tablename FROM pg_tables WHERE schemaname = 'public' AND tablename = $1`,
+        [table]
+      );
+      if (res.rows.length === 0) {
+        issues.push({
+          severity: "error",
+          code: "MISSING_TABLE",
+          message: `Table '${table}' referenced in migration does not exist`,
+          tableName: table
+        });
+      }
+    } catch (_) {
+    }
+  }
+  return issues;
+}
+async function analyzeMigration(sql, pool) {
+  const trimmed = sql.trim();
+  if (!trimmed) {
+    return {
+      safe: true,
+      issues: [],
+      summary: { errors: 0, warnings: 0, infos: 0 },
+      checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  const issues = staticCheck(trimmed);
+  if (pool) {
+    const dynamicIssues = await dynamicCheck(trimmed, pool, issues);
+    issues.push(...dynamicIssues);
+  }
+  const errors = issues.filter((i) => i.severity === "error").length;
+  const warnings = issues.filter((i) => i.severity === "warning").length;
+  const infos = issues.filter((i) => i.severity === "info").length;
+  return {
+    safe: errors === 0,
+    issues,
+    summary: { errors, warnings, infos },
+    checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var init_migration_checker = __esm({
+  "src/server/migration-checker.ts"() {
+    "use strict";
+  }
+});
+
+// src/server/env-differ.ts
+var env_differ_exports = {};
+__export(env_differ_exports, {
+  diffEnvironments: () => diffEnvironments,
+  formatMdDiff: () => formatMdDiff,
+  formatTextDiff: () => formatTextDiff
+});
+import { Pool as Pool2 } from "pg";
+async function fetchTables(pool) {
+  const res = await pool.query(`
+    SELECT table_name
+    FROM information_schema.tables
+    WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+    ORDER BY table_name
+  `);
+  return res.rows.map((r) => r.table_name);
+}
+async function fetchColumns(pool) {
+  const res = await pool.query(`
+    SELECT table_name, column_name, data_type, is_nullable, column_default
+    FROM information_schema.columns
+    WHERE table_schema = 'public'
+    ORDER BY table_name, ordinal_position
+  `);
+  return res.rows;
+}
+async function fetchIndexes(pool) {
+  const res = await pool.query(`
+    SELECT tablename, indexname
+    FROM pg_indexes
+    WHERE schemaname = 'public' AND indexname NOT LIKE '%_pkey'
+    ORDER BY tablename, indexname
+  `);
+  return res.rows;
+}
+function diffTables(sourceTables, targetTables) {
+  const sourceSet = new Set(sourceTables);
+  const targetSet = new Set(targetTables);
+  return {
+    missingTables: sourceTables.filter((t) => !targetSet.has(t)),
+    extraTables: targetTables.filter((t) => !sourceSet.has(t))
+  };
+}
+function groupColumnsByTable(columns) {
+  const map = /* @__PURE__ */ new Map();
+  for (const col of columns) {
+    if (!map.has(col.table_name)) map.set(col.table_name, /* @__PURE__ */ new Map());
+    const info = {
+      name: col.column_name,
+      type: col.data_type,
+      nullable: col.is_nullable === "YES"
+    };
+    if (col.column_default !== null && col.column_default !== void 0) {
+      info.default = col.column_default;
+    }
+    map.get(col.table_name).set(col.column_name, info);
+  }
+  return map;
+}
+function diffColumns(sourceCols, targetCols, commonTables) {
+  const sourceByTable = groupColumnsByTable(sourceCols);
+  const targetByTable = groupColumnsByTable(targetCols);
+  const diffs = [];
+  for (const table of commonTables) {
+    const srcMap = sourceByTable.get(table) ?? /* @__PURE__ */ new Map();
+    const tgtMap = targetByTable.get(table) ?? /* @__PURE__ */ new Map();
+    const missingColumns = [];
+    const extraColumns = [];
+    const typeDiffs = [];
+    for (const [colName, srcInfo] of srcMap) {
+      if (!tgtMap.has(colName)) {
+        missingColumns.push(srcInfo);
+      } else {
+        const tgtInfo = tgtMap.get(colName);
+        if (srcInfo.type !== tgtInfo.type) {
+          typeDiffs.push({ column: colName, sourceType: srcInfo.type, targetType: tgtInfo.type });
+        }
+      }
+    }
+    for (const [colName, tgtInfo] of tgtMap) {
+      if (!srcMap.has(colName)) {
+        extraColumns.push(tgtInfo);
+      }
+    }
+    if (missingColumns.length > 0 || extraColumns.length > 0 || typeDiffs.length > 0) {
+      diffs.push({ table, missingColumns, extraColumns, typeDiffs });
+    }
+  }
+  return diffs;
+}
+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);
+  }
+  return map;
+}
+function diffIndexes(sourceIdxs, targetIdxs, commonTables) {
+  const srcByTable = groupIndexesByTable(sourceIdxs);
+  const tgtByTable = groupIndexesByTable(targetIdxs);
+  const diffs = [];
+  const allTables = /* @__PURE__ */ new Set([
+    ...sourceIdxs.map((i) => i.tablename),
+    ...targetIdxs.map((i) => i.tablename)
+  ]);
+  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 });
+    }
+  }
+  return diffs;
+}
+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;
+  }
+  for (const id of schema.indexDiffs) {
+    n += id.missingIndexes.length + id.extraIndexes.length;
+  }
+  return n;
+}
+async function diffEnvironments(sourceConn, targetConn, options) {
+  const sourcePool = new Pool2({ connectionString: sourceConn, connectionTimeoutMillis: 1e4 });
+  const targetPool = new Pool2({ connectionString: targetConn, connectionTimeoutMillis: 1e4 });
+  try {
+    const [
+      sourceTables,
+      targetTables,
+      sourceCols,
+      targetCols,
+      sourceIdxs,
+      targetIdxs
+    ] = await Promise.all([
+      fetchTables(sourcePool),
+      fetchTables(targetPool),
+      fetchColumns(sourcePool),
+      fetchColumns(targetPool),
+      fetchIndexes(sourcePool),
+      fetchIndexes(targetPool)
+    ]);
+    const { missingTables, extraTables } = diffTables(sourceTables, targetTables);
+    const sourceSet = new Set(sourceTables);
+    const targetSet = new Set(targetTables);
+    const commonTables = sourceTables.filter((t) => targetSet.has(t));
+    const columnDiffs = diffColumns(sourceCols, targetCols, commonTables);
+    const indexDiffs = diffIndexes(sourceIdxs, targetIdxs, commonTables);
+    const schema = { missingTables, extraTables, columnDiffs, indexDiffs };
+    const schemaDrifts = countSchemaDrifts(schema);
+    let health;
+    if (options?.includeHealth) {
+      const longQueryThreshold = 5;
+      const [srcReport, tgtReport] = await Promise.all([
+        getAdvisorReport(sourcePool, longQueryThreshold),
+        getAdvisorReport(targetPool, longQueryThreshold)
+      ]);
+      const srcIssueKeys = new Set(srcReport.issues.map((i) => i.title));
+      const tgtIssueKeys = new Set(tgtReport.issues.map((i) => i.title));
+      const sourceOnlyIssues = srcReport.issues.filter((i) => !tgtIssueKeys.has(i.title)).map((i) => `${i.severity}: ${i.title}`);
+      const targetOnlyIssues = tgtReport.issues.filter((i) => !srcIssueKeys.has(i.title)).map((i) => `${i.severity}: ${i.title}`);
+      health = {
+        source: { score: srcReport.score, grade: srcReport.grade, url: maskConnectionString(sourceConn) },
+        target: { score: tgtReport.score, grade: tgtReport.grade, url: maskConnectionString(targetConn) },
+        sourceOnlyIssues,
+        targetOnlyIssues
+      };
+    }
+    return {
+      schema,
+      health,
+      checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      summary: {
+        schemaDrifts,
+        identical: schemaDrifts === 0
+      }
+    };
+  } finally {
+    await Promise.allSettled([sourcePool.end(), targetPool.end()]);
+  }
+}
+function maskConnectionString(connStr) {
+  try {
+    const url = new URL(connStr);
+    if (url.password) url.password = "***";
+    return url.toString();
+  } catch {
+    return "<redacted>";
+  }
+}
+function formatTextDiff(result) {
+  const lines = [];
+  const sep = "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550";
+  lines.push(`Environment Diff`);
+  lines.push(sep);
+  lines.push(``);
+  lines.push(`Schema Drift:`);
+  const { schema } = result;
+  if (schema.missingTables.length > 0) {
+    lines.push(`  \u2717 target missing tables: ${schema.missingTables.join(", ")}`);
+  }
+  if (schema.extraTables.length > 0) {
+    lines.push(`  \u26A0 target has extra tables: ${schema.extraTables.join(", ")}`);
+  }
+  const missingCols = [];
+  const extraCols = [];
+  const typeChanges = [];
+  for (const cd of schema.columnDiffs) {
+    for (const col of cd.missingColumns) {
+      missingCols.push(`      ${cd.table}: ${col.name} (${col.type})`);
+    }
+    for (const col of cd.extraColumns) {
+      extraCols.push(`      ${cd.table}: ${col.name} (${col.type})`);
+    }
+    for (const td of cd.typeDiffs) {
+      typeChanges.push(`      ${cd.table}.${td.column}: ${td.sourceType} \u2192 ${td.targetType}`);
+    }
+  }
+  if (missingCols.length > 0) {
+    lines.push(`  \u2717 target missing columns:`);
+    lines.push(...missingCols);
+  }
+  if (extraCols.length > 0) {
+    lines.push(`  \u26A0 target has extra columns:`);
+    lines.push(...extraCols);
+  }
+  if (typeChanges.length > 0) {
+    lines.push(`  ~ column type differences:`);
+    lines.push(...typeChanges);
+  }
+  const missingIdxs = [];
+  const extraIdxs = [];
+  for (const id of schema.indexDiffs) {
+    for (const idx of id.missingIndexes) {
+      missingIdxs.push(`      ${id.table}: ${idx}`);
+    }
+    for (const idx of id.extraIndexes) {
+      extraIdxs.push(`      ${id.table}: ${idx}`);
+    }
+  }
+  if (missingIdxs.length > 0) {
+    lines.push(`  \u2717 target missing indexes:`);
+    lines.push(...missingIdxs);
+  }
+  if (extraIdxs.length > 0) {
+    lines.push(`  \u26A0 target has extra indexes:`);
+    lines.push(...extraIdxs);
+  }
+  if (schema.missingTables.length === 0 && schema.extraTables.length === 0 && schema.columnDiffs.length === 0 && schema.indexDiffs.length === 0) {
+    lines.push(`  \u2713 Schemas are identical`);
+  }
+  if (result.health) {
+    const h = result.health;
+    lines.push(``);
+    lines.push(`Health Comparison:`);
+    lines.push(`  Source: ${h.source.score}/100 (${h.source.grade})  |  Target: ${h.target.score}/100 (${h.target.grade})`);
+    lines.push(`  Source-only issues: ${h.sourceOnlyIssues.length === 0 ? "(none)" : ""}`);
+    for (const iss of h.sourceOnlyIssues) lines.push(`    - ${iss}`);
+    lines.push(`  Target-only issues: ${h.targetOnlyIssues.length === 0 ? "(none)" : ""}`);
+    for (const iss of h.targetOnlyIssues) lines.push(`    - ${iss}`);
+  }
+  lines.push(``);
+  lines.push(sep);
+  const { schemaDrifts, identical } = result.summary;
+  lines.push(`Total: ${schemaDrifts} schema drift${schemaDrifts !== 1 ? "s" : ""} | Environments are ${identical ? "in sync \u2713" : "NOT in sync \u2717"}`);
+  return lines.join("\n");
+}
+function formatMdDiff(result) {
+  const lines = [];
+  lines.push(`## \u{1F504} Environment Diff`);
+  lines.push(``);
+  lines.push(`### Schema Drift`);
+  lines.push(``);
+  const { schema } = result;
+  const rows = [];
+  if (schema.missingTables.length > 0) {
+    rows.push([`\u274C Missing tables`, schema.missingTables.map((t) => `\`${t}\``).join(", ")]);
+  }
+  if (schema.extraTables.length > 0) {
+    rows.push([`\u26A0\uFE0F Extra tables`, schema.extraTables.map((t) => `\`${t}\``).join(", ")]);
+  }
+  const missingColItems = [];
+  const extraColItems = [];
+  const typeItems = [];
+  for (const cd of schema.columnDiffs) {
+    for (const col of cd.missingColumns) {
+      missingColItems.push(`\`${cd.table}.${col.name}\``);
+    }
+    for (const col of cd.extraColumns) {
+      extraColItems.push(`\`${cd.table}.${col.name}\``);
+    }
+    for (const td of cd.typeDiffs) {
+      typeItems.push(`\`${cd.table}.${td.column}\` (${td.sourceType}\u2192${td.targetType})`);
+    }
+  }
+  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 missingIdxItems = [];
+  const extraIdxItems = [];
+  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}\``);
+  }
+  if (missingIdxItems.length > 0) rows.push([`\u274C Missing indexes`, missingIdxItems.join(", ")]);
+  if (extraIdxItems.length > 0) rows.push([`\u26A0\uFE0F Extra indexes`, extraIdxItems.join(", ")]);
+  if (rows.length > 0) {
+    lines.push(`| Type | Details |`);
+    lines.push(`|------|---------|`);
+    for (const [type, details] of rows) {
+      lines.push(`| ${type} | ${details} |`);
+    }
+  } else {
+    lines.push(`\u2705 Schemas are identical`);
+  }
+  if (result.health) {
+    const h = result.health;
+    lines.push(``);
+    lines.push(`### Health Comparison`);
+    lines.push(``);
+    lines.push(`| | Score | Grade |`);
+    lines.push(`|--|-------|-------|`);
+    lines.push(`| Source | ${h.source.score}/100 | ${h.source.grade} |`);
+    lines.push(`| Target | ${h.target.score}/100 | ${h.target.grade} |`);
+    if (h.targetOnlyIssues.length > 0) {
+      lines.push(``);
+      lines.push(`**Target-only issues:**`);
+      for (const iss of h.targetOnlyIssues) lines.push(`- ${iss}`);
+    }
+    if (h.sourceOnlyIssues.length > 0) {
+      lines.push(``);
+      lines.push(`**Source-only issues:**`);
+      for (const iss of h.sourceOnlyIssues) lines.push(`- ${iss}`);
+    }
+  }
+  lines.push(``);
+  const { schemaDrifts, identical } = result.summary;
+  lines.push(`**Result: ${schemaDrifts} drift${schemaDrifts !== 1 ? "s" : ""} \u2014 environments are ${identical ? "in sync \u2713" : "NOT in sync"}**`);
+  return lines.join("\n");
+}
+var init_env_differ = __esm({
+  "src/server/env-differ.ts"() {
+    "use strict";
+    init_advisor();
   }
 });
 
@@ -2222,6 +2806,140 @@ function registerAlertsRoutes(app, alertManager) {
   });
 }
 
+// src/server/query-analyzer.ts
+function collectNodes(node, acc = []) {
+  if (!node || typeof node !== "object") return acc;
+  acc.push(node);
+  const plans = node["Plans"] ?? node["plans"];
+  if (Array.isArray(plans)) {
+    for (const child of plans) collectNodes(child, acc);
+  }
+  return acc;
+}
+function extractColumnsFromFilter(filter) {
+  const colPattern = /\(?"?([a-z_][a-z0-9_]*)"?\s*(?:=|<|>|<=|>=|<>|!=|IS\s+(?:NOT\s+)?NULL|~~|!~~)/gi;
+  const found = /* @__PURE__ */ new Set();
+  let m;
+  while ((m = colPattern.exec(filter)) !== null) {
+    const col = m[1].toLowerCase();
+    if (!["and", "or", "not", "true", "false", "null"].includes(col)) {
+      found.add(col);
+    }
+  }
+  return Array.from(found);
+}
+async function getExistingIndexColumns(pool, tableName) {
+  try {
+    const r = await pool.query(
+      `SELECT indexdef FROM pg_indexes WHERE tablename = $1`,
+      [tableName]
+    );
+    return r.rows.map((row) => {
+      const m = /\(([^)]+)\)/.exec(row.indexdef);
+      if (!m) return [];
+      return m[1].split(",").map((c) => c.trim().replace(/^"|"$/g, "").toLowerCase());
+    });
+  } catch {
+    return [];
+  }
+}
+function rateBenefit(rowCount) {
+  if (rowCount > 1e5) return "high";
+  if (rowCount >= 1e4) return "medium";
+  return "low";
+}
+function fmtRows(n) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(0)}K`;
+  return String(n);
+}
+async function analyzeExplainPlan(explainJson, pool) {
+  const result = {
+    planNodes: [],
+    seqScans: [],
+    missingIndexes: [],
+    costEstimate: { totalCost: 0 },
+    recommendations: []
+  };
+  if (!explainJson || !Array.isArray(explainJson) || explainJson.length === 0) {
+    return result;
+  }
+  const topLevel = explainJson[0];
+  const planRoot = topLevel?.["Plan"] ?? topLevel?.["plan"];
+  const planningTime = topLevel?.["Planning Time"] ?? void 0;
+  const executionTime = topLevel?.["Execution Time"] ?? void 0;
+  if (!planRoot) return result;
+  const allNodes = collectNodes(planRoot);
+  result.planNodes = allNodes.map((n) => {
+    const s = {
+      nodeType: n["Node Type"] ?? "Unknown",
+      totalCost: n["Total Cost"] ?? 0
+    };
+    if (n["Relation Name"]) s.table = n["Relation Name"];
+    if (n["Actual Rows"] !== void 0) s.actualRows = n["Actual Rows"];
+    if (n["Actual Total Time"] !== void 0) s.actualTime = n["Actual Total Time"];
+    if (n["Filter"]) s.filter = n["Filter"];
+    return s;
+  });
+  result.costEstimate = {
+    totalCost: planRoot["Total Cost"] ?? 0,
+    actualTime: executionTime,
+    planningTime
+  };
+  const seqScanNodes = allNodes.filter((n) => n["Node Type"] === "Seq Scan");
+  for (const node of seqScanNodes) {
+    const table = node["Relation Name"] ?? "unknown";
+    const rowCount = node["Plan Rows"] ?? node["Actual Rows"] ?? 0;
+    const filter = node["Filter"];
+    const info = { table, rowCount, filter };
+    if (rowCount > 1e4) {
+      info.suggestion = filter ? `Consider adding an index to support the filter on ${table}` : `Full table scan on large table ${table} \u2014 review query`;
+    }
+    result.seqScans.push(info);
+  }
+  for (const scan of result.seqScans) {
+    if (!scan.filter) continue;
+    const cols = extractColumnsFromFilter(scan.filter);
+    if (cols.length === 0) continue;
+    let existingIndexCols = [];
+    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 idxName = `idx_${scan.table}_${col}`;
+      const sql = `CREATE INDEX CONCURRENTLY ${idxName} ON ${scan.table} (${col})`;
+      result.missingIndexes.push({
+        table: scan.table,
+        columns: [col],
+        reason: `Seq Scan with Filter on ${col} (${fmtRows(scan.rowCount)} rows)`,
+        sql,
+        estimatedBenefit: benefit
+      });
+    }
+  }
+  for (const scan of result.seqScans) {
+    if (scan.rowCount > 1e4) {
+      const filterPart = scan.filter ? ` \u2014 consider adding index on ${extractColumnsFromFilter(scan.filter).join(", ") || "filter columns"}` : " \u2014 no filter; full scan may be intentional";
+      result.recommendations.push(
+        `Seq Scan on ${scan.table} (${fmtRows(scan.rowCount)} rows)${filterPart}`
+      );
+    }
+  }
+  if (planningTime !== void 0) {
+    const label = planningTime > 10 ? "high \u2014 check statistics" : "normal";
+    result.recommendations.push(`Planning time ${planningTime.toFixed(1)}ms \u2014 ${label}`);
+  }
+  if (result.missingIndexes.length === 0 && result.seqScans.length === 0) {
+    result.recommendations.push("No obvious sequential scans detected \u2014 query looks efficient");
+  }
+  return result;
+}
+
 // src/server/routes/explain.ts
 var DDL_PATTERN = /\b(CREATE|DROP|ALTER|TRUNCATE|GRANT|REVOKE)\b/i;
 function registerExplainRoutes(app, pool) {
@@ -2240,7 +2958,13 @@ function registerExplainRoutes(app, pool) {
           const r = await client.query(`EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ${query}`);
           await client.query("ROLLBACK");
           await client.query("RESET statement_timeout");
-          return c.json({ plan: r.rows[0]["QUERY PLAN"] });
+          const plan = r.rows[0]["QUERY PLAN"];
+          let analysis = null;
+          try {
+            analysis = await analyzeExplainPlan(plan, pool);
+          } catch {
+          }
+          return c.json({ plan, analysis });
         } catch (err) {
           await client.query("ROLLBACK").catch(() => {
           });
@@ -2707,7 +3431,7 @@ import { WebSocketServer, WebSocket } from "ws";
 import http from "http";
 var __dirname = path3.dirname(fileURLToPath(import.meta.url));
 async function startServer(opts) {
-  const pool = new Pool({ connectionString: opts.connectionString });
+  const pool = new Pool({ connectionString: opts.connectionString, connectionTimeoutMillis: 1e4 });
   try {
     const client = await pool.connect();
     client.release();
@@ -3068,7 +3792,11 @@ var { values, positionals } = parseArgs({
     threshold: { type: "string" },
     format: { type: "string", short: "f" },
     ci: { type: "boolean", default: false },
-    diff: { type: "boolean", default: false }
+    diff: { type: "boolean", default: false },
+    "snapshot-path": { type: "string" },
+    source: { type: "string" },
+    target: { type: "string" },
+    health: { type: "boolean", default: false }
   }
 });
 if (values.version) {
@@ -3089,6 +3817,7 @@ 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 --host localhost --user postgres --db mydb
 
 Options:
@@ -3115,7 +3844,11 @@ Options:
   --threshold <score>    Health score threshold for check command (default: 70)
   -f, --format <fmt>     Output format: text|json|md (default: text)
   --ci                   Output GitHub Actions compatible annotations
-  --diff                 Compare with previous run (saves to ~/.pg-dash/last-check.json)
+  --diff                 Compare with previous run (saves snapshot for next run)
+  --snapshot-path <path> Path to snapshot file for --diff (default: ~/.pg-dash/last-check.json)
+  --source <url>         Source database connection string (diff-env)
+  --target <url>         Target database connection string (diff-env)
+  --health               Also compare health scores and issues (diff-env)
   -v, --version          Show version
   -h, --help             Show this help
 
@@ -3148,22 +3881,23 @@ if (subcommand === "check") {
   const format = values.format || "text";
   const ci = values.ci || false;
   const useDiff = values.diff || false;
-  const { Pool: Pool2 } = await import("pg");
+  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 os4 = await import("os");
-  const pool = new Pool2({ connectionString });
+  const pool = new Pool3({ connectionString, connectionTimeoutMillis: 1e4 });
   const checkDataDir = values["data-dir"] || path5.join(os4.homedir(), ".pg-dash");
+  const snapshotPath = values["snapshot-path"] || path5.join(checkDataDir, "last-check.json");
   try {
     const lqt = parseInt(values["long-query-threshold"] || process.env.PG_DASH_LONG_QUERY_THRESHOLD || "5", 10);
     const report = await getAdvisorReport2(pool, lqt);
     let diff = null;
     if (useDiff) {
-      const prev = loadSnapshot2(checkDataDir);
+      const prev = loadSnapshot2(snapshotPath);
       if (prev) {
         diff = diffSnapshots3(prev.result, report);
       }
-      saveSnapshot2(checkDataDir, report);
+      saveSnapshot2(snapshotPath, report);
     }
     if (format === "json") {
       const output = { ...report };
@@ -3281,6 +4015,91 @@ Score: ${diff.previousScore} \u2192 ${report.score} (${sign}${diff.scoreDelta})`
     await pool.end();
     process.exit(1);
   }
+} else if (subcommand === "check-migration") {
+  const filePath = positionals[1];
+  if (!filePath) {
+    console.error("Error: provide a migration SQL file path.\n\nUsage: pg-dash check-migration <file> [connection]");
+    process.exit(1);
+  }
+  if (!fs5.existsSync(filePath)) {
+    console.error(`Error: File not found: ${filePath}`);
+    process.exit(1);
+  }
+  const sql = fs5.readFileSync(filePath, "utf-8");
+  const migrationConn = positionals[2];
+  const format = values.format || "text";
+  const ci = values.ci || false;
+  const { analyzeMigration: analyzeMigration2 } = await Promise.resolve().then(() => (init_migration_checker(), migration_checker_exports));
+  let pool;
+  if (migrationConn) {
+    const { Pool: Pool3 } = await import("pg");
+    pool = new Pool3({ connectionString: migrationConn, connectionTimeoutMillis: 1e4 });
+  }
+  try {
+    const result = await analyzeMigration2(sql, pool);
+    if (pool) await pool.end();
+    const sep = "\u2500".repeat(48);
+    if (format === "json") {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (format === "md") {
+      console.log("## \u{1F50D} Migration Safety Check\n");
+      console.log("| Severity | Code | Message |");
+      console.log("|----------|------|---------|");
+      for (const issue of result.issues) {
+        const sev = issue.severity === "error" ? "\u{1F534} ERROR" : issue.severity === "warning" ? "\u26A0\uFE0F WARNING" : "\u2139\uFE0F INFO";
+        console.log(`| ${sev} | ${issue.code} | ${issue.message} |`);
+      }
+      const { errors, warnings, infos } = result.summary;
+      const safeLabel = result.safe ? "\u2705 SAFE" : "\u274C UNSAFE";
+      console.log(`
+**Result: ${safeLabel} \u2014 ${errors} error${errors !== 1 ? "s" : ""}, ${warnings} warning${warnings !== 1 ? "s" : ""}, ${infos} info${infos !== 1 ? "s" : ""}**`);
+    } else {
+      console.log(`
+Migration check: ${filePath}`);
+      console.log(sep);
+      if (result.issues.length === 0) {
+        console.log("\n  \u2705 No issues found!\n");
+      } else {
+        for (const issue of result.issues) {
+          const icon = issue.severity === "error" ? "\u2717" : issue.severity === "warning" ? "\u26A0" : "\u2713";
+          const indent = "  ";
+          const parts = [`${indent}${icon}  ${issue.message}`];
+          if (issue.suggestion) parts.push(`${indent}   Suggestion: ${issue.suggestion}`);
+          if (issue.estimatedRows !== void 0) {
+            parts.push(
+              `${indent}   Est. rows: ${issue.estimatedRows.toLocaleString()}` + (issue.estimatedLockSeconds !== void 0 ? `, lock ~${issue.estimatedLockSeconds}s` : "")
+            );
+          }
+          if (issue.lineNumber !== void 0) parts.push(`${indent}   Line ${issue.lineNumber}`);
+          console.log(parts.join("\n") + "\n");
+        }
+      }
+      console.log(sep);
+      const { errors, warnings, infos } = result.summary;
+      const safeLabel = result.safe ? "SAFE" : "UNSAFE";
+      console.log(
+        `Result: ${safeLabel} \u2014 ${errors} error${errors !== 1 ? "s" : ""}, ${warnings} warning${warnings !== 1 ? "s" : ""}, ${infos} info${infos !== 1 ? "s" : ""}
+`
+      );
+      if (!migrationConn) {
+        console.log("Run with a connection string for more accurate row count estimates.\n");
+      }
+    }
+    if (ci) {
+      for (const issue of result.issues) {
+        const level = issue.severity === "error" ? "error" : issue.severity === "warning" ? "warning" : "notice";
+        const loc = issue.lineNumber ? `,line=${issue.lineNumber}` : "";
+        const file = `file=${filePath}${loc}`;
+        console.log(`::${level} ${file}::${issue.message}`);
+      }
+    }
+    process.exit(result.safe ? 0 : 1);
+  } catch (err) {
+    if (pool) await pool.end().catch(() => {
+    });
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
 } else if (subcommand === "schema-diff") {
   const connectionString = resolveConnectionString(1);
   const dataDir = values["data-dir"] || path5.join((await import("os")).homedir(), ".pg-dash");
@@ -3307,6 +4126,59 @@ Score: ${diff.previousScore} \u2192 ${report.score} (${sign}${diff.scoreDelta})`
     console.log();
   }
   process.exit(0);
+} else if (subcommand === "diff-env") {
+  const sourceUrl = values.source;
+  const targetUrl = values.target;
+  if (!sourceUrl || !targetUrl) {
+    console.error("Error: diff-env requires --source <url> and --target <url>");
+    process.exit(1);
+  }
+  const format = values.format || "text";
+  const includeHealth = values.health || false;
+  const ci = values.ci || false;
+  const { diffEnvironments: diffEnvironments2, formatTextDiff: formatTextDiff2, formatMdDiff: formatMdDiff2 } = await Promise.resolve().then(() => (init_env_differ(), env_differ_exports));
+  try {
+    const result = await diffEnvironments2(sourceUrl, targetUrl, { includeHealth });
+    if (format === "json") {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (format === "md") {
+      console.log(formatMdDiff2(result));
+    } else {
+      const text = formatTextDiff2(result);
+      console.log(text);
+      if (ci) {
+        for (const t of result.schema.missingTables) {
+          console.log(`::error::diff-env: target missing table: ${t}`);
+        }
+        for (const t of result.schema.extraTables) {
+          console.log(`::notice::diff-env: target has extra table: ${t}`);
+        }
+        for (const cd of result.schema.columnDiffs) {
+          for (const col of cd.missingColumns) {
+            console.log(`::error::diff-env: target missing column: ${cd.table}.${col.name} (${col.type})`);
+          }
+          for (const col of cd.extraColumns) {
+            console.log(`::notice::diff-env: target has extra column: ${cd.table}.${col.name} (${col.type})`);
+          }
+          for (const td of cd.typeDiffs) {
+            console.log(`::error::diff-env: type mismatch: ${cd.table}.${td.column} ${td.sourceType}\u2192${td.targetType}`);
+          }
+        }
+        for (const id of result.schema.indexDiffs) {
+          for (const idx of id.missingIndexes) {
+            console.log(`::warning::diff-env: target missing index: ${id.table}.${idx}`);
+          }
+          for (const idx of id.extraIndexes) {
+            console.log(`::notice::diff-env: target has extra index: ${id.table}.${idx}`);
+          }
+        }
+      }
+    }
+    process.exit(result.summary.identical ? 0 : 1);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
 } else {
   const connectionString = resolveConnectionString(0);
   const port = parseInt(values.port, 10);