mcp-db-analyzer 0.2.8 → 0.2.10

package/build/analyzers/relationships.js

@@ -99,6 +99,59 @@ async function analyzeSqliteRelationships() {
     }
     return formatRelationshipReport(tablesResult.rows.map(r => r.name), fks);
 }
+/**
+ * Detect cycles in the FK dependency graph using iterative DFS.
+ * Returns each unique cycle as an ordered list of table names with the
+ * first node repeated at the end to show closure (e.g. ["a","b","c","a"]).
+ */
+function findFkCycles(allTables, graph) {
+    const visited = new Set();
+    const onStack = new Set();
+    const stackPath = [];
+    const cycles = [];
+    const seenCycleKeys = new Set();
+    function dfs(node) {
+        visited.add(node);
+        onStack.add(node);
+        stackPath.push(node);
+        const nodeData = graph.get(node);
+        if (nodeData) {
+            for (const fk of nodeData.outgoing) {
+                const neighbor = fk.target_table;
+                if (onStack.has(neighbor)) {
+                    // Back edge found — extract the cycle
+                    const cycleStartIdx = stackPath.indexOf(neighbor);
+                    if (cycleStartIdx !== -1) {
+                        const cycleNodes = stackPath.slice(cycleStartIdx);
+                        // Normalize: rotate so lexicographically smallest node is first
+                        const minNode = cycleNodes.reduce((a, b) => (a < b ? a : b));
+                        const minIdx = cycleNodes.indexOf(minNode);
+                        const normalized = [
+                            ...cycleNodes.slice(minIdx),
+                            ...cycleNodes.slice(0, minIdx),
+                        ];
+                        const key = normalized.join("\0");
+                        if (!seenCycleKeys.has(key)) {
+                            seenCycleKeys.add(key);
+                            cycles.push([...normalized, normalized[0]]); // close the cycle
+                        }
+                    }
+                }
+                else if (!visited.has(neighbor)) {
+                    dfs(neighbor);
+                }
+            }
+        }
+        stackPath.pop();
+        onStack.delete(node);
+    }
+    for (const table of allTables) {
+        if (!visited.has(table)) {
+            dfs(table);
+        }
+    }
+    return cycles;
+}
 function formatRelationshipReport(allTables, foreignKeys) {
     const lines = [];
     lines.push("## Table Relationships\n");
@@ -161,30 +214,57 @@ function formatRelationshipReport(allTables, foreignKeys) {
         lines.push("*Orphan tables may be lookup tables, denormalized tables, or tables missing FK constraints.*");
         lines.push("");
     }
+    // Circular FK dependencies
+    const cycles = findFkCycles(allTables, graph);
+    if (cycles.length > 0) {
+        lines.push("### Circular FK Dependencies\n");
+        lines.push("These tables form circular foreign key references. Cycles complicate cascade operations, " +
+            "schema migrations, and may cause issues with certain ORMs and migration tools:\n");
+        for (const cycle of cycles) {
+            lines.push(`- ${cycle.join(" → ")}`);
+        }
+        lines.push("\n**Note**: Circular FKs are sometimes intentional (e.g., a 'current_record' pointer back to a parent). " +
+            "Review each cycle to confirm the design is correct.\n");
+    }
     // Cascading delete chains
     const cascadeDeletes = foreignKeys.filter(fk => fk.on_delete === "CASCADE");
     if (cascadeDeletes.length > 0) {
         lines.push("### Cascading Delete Chains\n");
         lines.push("Deleting a row from these parent tables will cascade-delete rows in child tables:\n");
-        // Group by target (parent) table
-        const cascadeByParent = new Map();
+        // Build parent→children map for cascade edges only
+        const cascadeChildren = new Map();
         for (const fk of cascadeDeletes) {
-            const existing = cascadeByParent.get(fk.target_table) || [];
-            existing.push(fk);
-            cascadeByParent.set(fk.target_table, existing);
+            const existing = cascadeChildren.get(fk.target_table) || [];
+            if (!existing.includes(fk.source_table))
+                existing.push(fk.source_table);
+            cascadeChildren.set(fk.target_table, existing);
         }
-        for (const [parent, fks] of cascadeByParent) {
-            const children = fks.map(f => f.source_table).join(", ");
-            lines.push(`- **${parent}** → cascades to: ${children}`);
-            // Check for deep chains (cascade through multiple levels)
-            for (const fk of fks) {
-                const grandchildren = cascadeDeletes.filter(gfk => gfk.target_table === fk.source_table);
-                if (grandchildren.length > 0) {
-                    const gcNames = grandchildren.map(g => g.source_table).join(", ");
-                    lines.push(`  - **${fk.source_table}** → further cascades to: ${gcNames}`);
+        // Identify root cascade tables: have cascade children but are not cascade children themselves
+        const allCascadeChildTables = new Set(cascadeDeletes.map(fk => fk.source_table));
+        const cascadeRoots = [...cascadeChildren.keys()].filter(t => !allCascadeChildTables.has(t));
+        // Fall back to all parents if every parent is also a child (full cycle)
+        const parentsToShow = cascadeRoots.length > 0 ? cascadeRoots : [...cascadeChildren.keys()];
+        // Recursively render the cascade chain under a given parent
+        function renderCascadeChain(parent, indent, visited) {
+            const children = cascadeChildren.get(parent) || [];
+            const prefix = "  ".repeat(indent);
+            for (const child of children) {
+                if (visited.has(child)) {
+                    lines.push(`${prefix}- **${child}** *(circular)*`);
+                }
+                else if (cascadeChildren.has(child)) {
+                    lines.push(`${prefix}- **${child}** →`);
+                    renderCascadeChain(child, indent + 1, new Set([...visited, child]));
+                }
+                else {
+                    lines.push(`${prefix}- **${child}**`);
                 }
             }
         }
+        for (const root of parentsToShow) {
+            lines.push(`- **${root}** → cascades to:`);
+            renderCascadeChain(root, 1, new Set([root]));
+        }
         lines.push("");
         lines.push("**WARNING**: Cascading deletes can cause unexpected data loss. Ensure all CASCADE rules are intentional.\n");
     }
@@ -200,6 +280,9 @@ function formatRelationshipReport(allTables, foreignKeys) {
     if (hubs.length > 0) {
         issues.push(`Hub tables (${hubs.map(h => h.name).join(", ")}) have 5+ FK connections — changes to these tables affect many others`);
     }
+    if (cycles.length > 0) {
+        issues.push(`${cycles.length} circular FK reference(s) detected — review for unintended schema design`);
+    }
     if (issues.length > 0) {
         lines.push("### Recommendations\n");
         for (const issue of issues) {

package/build/analyzers/schema.js

@@ -56,7 +56,10 @@ async function listTablesSqlite() {
     lines.push("|-------|-------------|------------|");
     for (const row of result.rows) {
         // SQLite doesn't have built-in row count or size — use count
-        const countResult = await query(`SELECT count(*) as cnt FROM "${row.name}"`);
+        // Escape embedded double-quote characters so table names like `weird"table` don't
+        // break the identifier quoting (same convention used in inspectTableSqlite).
+        const escapedName = row.name.replace(/"/g, '""');
+        const countResult = await query(`SELECT count(*) as cnt FROM "${escapedName}"`);
         const cnt = countResult.rows[0]?.cnt ?? 0;
         lines.push(`| ${row.name} | ${cnt} | - |`);
     }

package/build/analyzers/vacuum.js

@@ -35,15 +35,29 @@ export async function analyzeVacuum(schema = "public") {
     if (stats.rows.length === 0) {
         return `No user tables found in schema '${schema}'.`;
     }
-    // Get autovacuum settings
-    const settings = await query(`
-    SELECT name, setting
-    FROM pg_settings
-    WHERE name LIKE 'autovacuum%'
-    ORDER BY name
-  `);
-    const findings = analyzeFindings(stats.rows, settings.rows);
-    return formatVacuumReport(schema, stats.rows, settings.rows, findings);
+    // Get autovacuum settings. pg_settings requires superuser or pg_read_all_settings
+    // in some PostgreSQL configurations — don't let a permission error discard the
+    // table stats we already fetched.
+    let settingsRows = [];
+    let settingsUnavailable = false;
+    try {
+        const settings = await query(`
+      SELECT name, setting
+      FROM pg_settings
+      WHERE name LIKE 'autovacuum%'
+      ORDER BY name
+    `);
+        settingsRows = settings.rows;
+    }
+    catch {
+        settingsUnavailable = true;
+    }
+    const findings = analyzeFindings(stats.rows, settingsRows);
+    const report = formatVacuumReport(schema, stats.rows, settingsRows, findings);
+    if (settingsUnavailable) {
+        return report + "\n\n*Note: Autovacuum configuration could not be read — the database user may need pg_read_all_settings or superuser privileges.*";
+    }
+    return report;
 }
 export function analyzeFindings(tables, settings) {
     const findings = [];

package/build/index.js

@@ -220,7 +220,7 @@ server.tool("suggest_missing_indexes", "Find tables with high sequential scan co
     }
 });
 // --- Tool: analyze_slow_queries ---
-server.tool("analyze_slow_queries", "Find the slowest queries using pg_stat_statements (PostgreSQL) or performance_schema (MySQL). Shows execution times, call counts, and optimization recommendations.", {
+server.tool("analyze_slow_queries", "Find the slowest queries using pg_stat_statements (PostgreSQL) or performance_schema (MySQL). Shows execution times, call counts, and optimization recommendations. PostgreSQL requires the pg_stat_statements extension to be installed and listed in shared_preload_libraries — the tool returns setup instructions if the extension is missing. Not available for SQLite.", {
     schema: z
         .string()
         .default("public")
@@ -248,7 +248,7 @@ server.tool("analyze_slow_queries", "Find the slowest queries using pg_stat_stat
     }
 });
 // Tool 7: analyze_connections
-server.tool("analyze_connections", "Analyze active database connections. Detects idle-in-transaction sessions, long-running queries, lock contention, and connection pool utilization. PostgreSQL and MySQL only.", {
+server.tool("analyze_connections", "Analyze active database connections. Detects idle-in-transaction sessions (which hold locks and block other queries), long-running queries (flagged at >30 seconds), lock contention between sessions, and connection pool utilization. PostgreSQL and MySQL only.", {
     timeout_ms: timeoutParam,
 }, async ({ timeout_ms }) => {
     applyTimeout(timeout_ms);
@@ -268,7 +268,7 @@ server.tool("analyze_connections", "Analyze active database connections. Detects
     }
 });
 // Tool 8: analyze_table_relationships
-server.tool("analyze_table_relationships", "Analyze foreign key relationships between tables. Builds a dependency graph showing entity connectivity, orphan tables (no FKs), cascading delete chains, and hub entities. Useful for understanding schema design and impact analysis.", {
+server.tool("analyze_table_relationships", "Analyze foreign key relationships between tables. Builds a dependency graph showing entity connectivity, orphan tables (no FKs), cascading delete chains (shown at full depth), hub entities (tables with 5+ FK connections), and circular FK dependencies. Useful for understanding schema design, planning migrations, and impact analysis.", {
     schema: z
         .string()
         .default("public")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-db-analyzer",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "MCP server for PostgreSQL, MySQL, and SQLite schema analysis, index optimization, and query plan inspection",
   "mcpName": "io.github.dmitriusan/mcp-db-analyzer",
   "author": "Dmytro Lisnichenko",
@@ -44,7 +44,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "repository": {
     "type": "git",
@@ -59,14 +59,14 @@
     "better-sqlite3": "^12.6.2",
     "mysql2": "^3.19.0",
     "pg": "^8.13.0",
-    "zod": "^3.24.2"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/mysql": "^2.15.27",
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.5.0",
     "@types/pg": "^8.11.0",
-    "typescript": "^5.8.2",
-    "vitest": "^4.0.18"
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.0"
   }
 }