mcp-db-analyzer 0.2.0

package/build/analyzers/connections.js

@@ -0,0 +1,183 @@
+/**
+ * Connection pool analyzer.
+ *
+ * Queries pg_stat_activity (PostgreSQL), performance_schema (MySQL),
+ * or returns unavailable for SQLite.
+ *
+ * Detects:
+ * - Connection pool utilization
+ * - Idle-in-transaction connections (holding locks)
+ * - Long-running queries
+ * - Blocked connections waiting on locks
+ */
+import { query, getDriverType } from "../db.js";
+export async function analyzeConnections() {
+    const driver = getDriverType();
+    if (driver === "sqlite") {
+        return "## Connection Analysis\n\nConnection analysis is not available for SQLite (single-process database).";
+    }
+    if (driver === "mysql") {
+        return analyzeMysqlConnections();
+    }
+    return analyzePostgresConnections();
+}
+async function analyzePostgresConnections() {
+    const lines = [`## Connection Analysis (PostgreSQL)\n`];
+    const summary = await query(`SELECT COALESCE(state, 'null') AS state, COUNT(*)::text AS count
+     FROM pg_stat_activity
+     WHERE backend_type = 'client backend'
+     GROUP BY state
+     ORDER BY COUNT(*) DESC`);
+    lines.push("### Connection States\n");
+    lines.push("| State | Count |");
+    lines.push("|-------|-------|");
+    let totalConnections = 0;
+    for (const row of summary.rows) {
+        lines.push(`| ${row.state} | ${row.count} |`);
+        totalConnections += parseInt(row.count, 10);
+    }
+    lines.push(`| **Total** | **${totalConnections}** |`);
+    lines.push("");
+    const maxConn = await query(`SELECT setting FROM pg_settings WHERE name = 'max_connections'`);
+    if (maxConn.rows.length > 0) {
+        const max = parseInt(maxConn.rows[0].setting, 10);
+        const utilization = totalConnections / max;
+        lines.push(`**Max connections**: ${max}`);
+        lines.push(`**Utilization**: ${(utilization * 100).toFixed(1)}%`);
+        if (utilization > 0.8) {
+            lines.push(`\n**WARNING**: Connection pool is ${(utilization * 100).toFixed(0)}% utilized. Consider increasing max_connections or using PgBouncer.`);
+        }
+        lines.push("");
+    }
+    const idleTxn = await query(`SELECT pid::text, usename, state,
+            (NOW() - state_change)::text AS duration,
+            LEFT(query, 100) AS query
+     FROM pg_stat_activity
+     WHERE state = 'idle in transaction'
+       AND backend_type = 'client backend'
+     ORDER BY state_change ASC
+     LIMIT 10`);
+    if (idleTxn.rows.length > 0) {
+        lines.push("### Idle-in-Transaction Connections\n");
+        lines.push("These connections hold locks and may block other operations.\n");
+        lines.push("| PID | User | Duration | Query |");
+        lines.push("|-----|------|----------|-------|");
+        for (const row of idleTxn.rows) {
+            lines.push(`| ${row.pid} | ${row.usename} | ${row.duration} | ${row.query} |`);
+        }
+        lines.push("");
+    }
+    const longQueries = await query(`SELECT pid::text, usename,
+            (NOW() - query_start)::text AS duration,
+            wait_event_type,
+            LEFT(query, 120) AS query
+     FROM pg_stat_activity
+     WHERE state = 'active'
+       AND backend_type = 'client backend'
+       AND query_start < NOW() - INTERVAL '30 seconds'
+       AND pid != pg_backend_pid()
+     ORDER BY query_start ASC
+     LIMIT 10`);
+    if (longQueries.rows.length > 0) {
+        lines.push("### Long-Running Queries (> 30s)\n");
+        lines.push("| PID | User | Duration | Wait | Query |");
+        lines.push("|-----|------|----------|------|-------|");
+        for (const row of longQueries.rows) {
+            lines.push(`| ${row.pid} | ${row.usename} | ${row.duration} | ${row.wait_event_type || "-"} | ${row.query} |`);
+        }
+        lines.push("");
+    }
+    const blocked = await query(`SELECT blocked.pid::text AS blocked_pid,
+            blocking.pid::text AS blocking_pid,
+            LEFT(blocked.query, 80) AS blocked_query,
+            LEFT(blocking.query, 80) AS blocking_query
+     FROM pg_stat_activity blocked
+     JOIN pg_locks bl ON bl.pid = blocked.pid AND NOT bl.granted
+     JOIN pg_locks gl ON gl.locktype = bl.locktype
+       AND gl.database IS NOT DISTINCT FROM bl.database
+       AND gl.relation IS NOT DISTINCT FROM bl.relation
+       AND gl.page IS NOT DISTINCT FROM bl.page
+       AND gl.tuple IS NOT DISTINCT FROM bl.tuple
+       AND gl.virtualxid IS NOT DISTINCT FROM bl.virtualxid
+       AND gl.transactionid IS NOT DISTINCT FROM bl.transactionid
+       AND gl.classid IS NOT DISTINCT FROM bl.classid
+       AND gl.objid IS NOT DISTINCT FROM bl.objid
+       AND gl.objsubid IS NOT DISTINCT FROM bl.objsubid
+       AND gl.pid != bl.pid
+       AND gl.granted
+     JOIN pg_stat_activity blocking ON blocking.pid = gl.pid
+     LIMIT 10`);
+    if (blocked.rows.length > 0) {
+        lines.push("### Blocked Connections\n");
+        lines.push("| Blocked PID | Blocking PID | Blocked Query | Blocking Query |");
+        lines.push("|-------------|--------------|---------------|----------------|");
+        for (const row of blocked.rows) {
+            lines.push(`| ${row.blocked_pid} | ${row.blocking_pid} | ${row.blocked_query} | ${row.blocking_query} |`);
+        }
+        lines.push("");
+    }
+    // Summary
+    const issues = [];
+    if (idleTxn.rows.length > 0)
+        issues.push(`${idleTxn.rows.length} idle-in-transaction connection(s) holding locks`);
+    if (longQueries.rows.length > 0)
+        issues.push(`${longQueries.rows.length} long-running query/queries (> 30s)`);
+    if (blocked.rows.length > 0)
+        issues.push(`${blocked.rows.length} blocked connection(s) waiting on locks`);
+    if (issues.length > 0) {
+        lines.push("### Issues\n");
+        for (const issue of issues) {
+            lines.push(`- ${issue}`);
+        }
+        lines.push("");
+        lines.push("### Recommendations\n");
+        if (idleTxn.rows.length > 0) {
+            lines.push("- Set `idle_in_transaction_session_timeout` to auto-kill stale transactions");
+        }
+        if (longQueries.rows.length > 0) {
+            lines.push("- Set `statement_timeout` to prevent runaway queries");
+        }
+        if (blocked.rows.length > 0) {
+            lines.push("- Investigate lock contention — consider `pg_terminate_backend()` for blocking PIDs");
+        }
+    }
+    else {
+        lines.push("### No connection issues detected.\n");
+    }
+    return lines.join("\n");
+}
+async function analyzeMysqlConnections() {
+    const lines = [`## Connection Analysis (MySQL)\n`];
+    const summary = await query(`SELECT COALESCE(COMMAND, 'Unknown') AS state, COUNT(*) AS count
+     FROM information_schema.PROCESSLIST
+     GROUP BY COMMAND
+     ORDER BY COUNT(*) DESC`);
+    lines.push("### Connection States\n");
+    lines.push("| State | Count |");
+    lines.push("|-------|-------|");
+    let total = 0;
+    for (const row of summary.rows) {
+        lines.push(`| ${row.state} | ${row.count} |`);
+        total += parseInt(row.count, 10);
+    }
+    lines.push(`| **Total** | **${total}** |`);
+    lines.push("");
+    const longQueries = await query(`SELECT ID AS id, USER AS user, TIME AS time, STATE AS state, LEFT(INFO, 100) AS info
+     FROM information_schema.PROCESSLIST
+     WHERE COMMAND = 'Query' AND TIME > 30
+     ORDER BY TIME DESC
+     LIMIT 10`);
+    if (longQueries.rows.length > 0) {
+        lines.push("### Long-Running Queries (> 30s)\n");
+        lines.push("| ID | User | Duration (s) | State | Query |");
+        lines.push("|-----|------|-------------|-------|-------|");
+        for (const row of longQueries.rows) {
+            lines.push(`| ${row.id} | ${row.user} | ${row.time} | ${row.state} | ${row.info} |`);
+        }
+        lines.push("");
+    }
+    if (longQueries.rows.length === 0) {
+        lines.push("### No connection issues detected.\n");
+    }
+    return lines.join("\n");
+}

package/build/analyzers/indexes.js

@@ -0,0 +1,251 @@
+import { query, getDriverType } from "../db.js";
+/**
+ * Analyze index usage and find unused indexes.
+ */
+export async function analyzeIndexUsage(schema = "public") {
+    const driver = getDriverType();
+    if (driver === "sqlite") {
+        return analyzeIndexUsageSqlite();
+    }
+    if (driver === "mysql") {
+        return analyzeIndexUsageMysql(schema);
+    }
+    const result = await query(`
+    SELECT
+      s.relname AS table_name,
+      s.indexrelname AS index_name,
+      pg_size_pretty(pg_relation_size(s.indexrelid)) AS index_size,
+      s.idx_scan::text,
+      s.idx_tup_read::text,
+      s.idx_tup_fetch::text,
+      i.indexdef AS index_def
+    FROM pg_stat_user_indexes s
+    JOIN pg_indexes i
+      ON s.schemaname = i.schemaname
+      AND s.relname = i.tablename
+      AND s.indexrelname = i.indexname
+    WHERE s.schemaname = $1
+    ORDER BY s.idx_scan ASC, pg_relation_size(s.indexrelid) DESC
+  `, [schema]);
+    return formatIndexUsage(result.rows, schema);
+}
+async function analyzeIndexUsageSqlite() {
+    // SQLite doesn't track index usage stats — list all indexes with their definitions
+    const result = await query(`
+    SELECT tbl_name, name, sql FROM sqlite_master
+    WHERE type = 'index' AND name NOT LIKE 'sqlite_%'
+    ORDER BY tbl_name, name
+  `);
+    if (result.rows.length === 0) {
+        return "No user-created indexes found. SQLite does not track index usage statistics.";
+    }
+    const lines = [`## Index Usage Analysis (SQLite)\n`];
+    lines.push("SQLite does not track index scan statistics. Listing all indexes:\n");
+    lines.push("| Table | Index | Definition |");
+    lines.push("|-------|-------|------------|");
+    for (const idx of result.rows) {
+        lines.push(`| ${idx.tbl_name} | ${idx.name} | \`${idx.sql || 'auto-index'}\` |`);
+    }
+    lines.push("\n**Tip**: Use `EXPLAIN QUERY PLAN` via the `explain_query` tool to check if indexes are being used.");
+    return lines.join("\n");
+}
+async function analyzeIndexUsageMysql(schema) {
+    try {
+        const result = await query(`
+      SELECT
+        s.OBJECT_NAME AS table_name,
+        s.INDEX_NAME AS index_name,
+        CONCAT(ROUND(stat.STAT_VALUE * @@innodb_page_size / 1024 / 1024, 2), ' MB') AS index_size,
+        CAST(s.COUNT_READ AS CHAR) AS idx_scan,
+        CAST(s.COUNT_FETCH AS CHAR) AS idx_tup_read,
+        CAST(s.COUNT_FETCH AS CHAR) AS idx_tup_fetch,
+        CONCAT('INDEX ', s.INDEX_NAME, ' ON ', s.OBJECT_NAME) AS index_def
+      FROM performance_schema.table_io_waits_summary_by_index_usage s
+      LEFT JOIN mysql.innodb_index_stats stat
+        ON stat.database_name = s.OBJECT_SCHEMA
+        AND stat.table_name = s.OBJECT_NAME
+        AND stat.index_name = s.INDEX_NAME
+        AND stat.stat_name = 'size'
+      WHERE s.OBJECT_SCHEMA = ?
+        AND s.INDEX_NAME IS NOT NULL
+      ORDER BY s.COUNT_READ ASC
+    `, [schema]);
+        return formatIndexUsage(result.rows, schema);
+    }
+    catch {
+        return `## Index Usage Analysis — schema '${schema}'\n\nUnable to query performance_schema. Ensure performance_schema is enabled (it is ON by default in MySQL 5.7+) and the user has SELECT privilege on performance_schema tables.`;
+    }
+}
+function formatIndexUsage(rows, schema) {
+    if (rows.length === 0) {
+        return `No indexes found in schema '${schema}'.`;
+    }
+    const lines = [`## Index Usage Analysis — schema '${schema}'\n`];
+    const unused = rows.filter((r) => r.idx_scan === "0");
+    if (unused.length > 0) {
+        lines.push(`### Unused Indexes (${unused.length} found)\n`);
+        lines.push("These indexes have **zero scans** since the last stats reset. Consider dropping them to save space and speed up writes.\n");
+        lines.push("| Table | Index | Size | Definition |");
+        lines.push("|-------|-------|------|------------|");
+        for (const idx of unused) {
+            lines.push(`| ${idx.table_name} | ${idx.index_name} | ${idx.index_size} | \`${idx.index_def}\` |`);
+        }
+        lines.push("");
+    }
+    else {
+        lines.push("### No unused indexes found.\n");
+    }
+    lines.push("### All Indexes by Scan Count\n");
+    lines.push("| Table | Index | Scans | Rows Read | Size |");
+    lines.push("|-------|-------|-------|-----------|------|");
+    for (const idx of rows) {
+        lines.push(`| ${idx.table_name} | ${idx.index_name} | ${idx.idx_scan} | ${idx.idx_tup_read} | ${idx.index_size} |`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Find tables that might need indexes based on sequential scan patterns.
+ */
+export async function findMissingIndexes(schema = "public") {
+    const driver = getDriverType();
+    if (driver === "sqlite") {
+        return "SQLite does not provide sequential scan statistics. Use `explain_query` to analyze specific queries.";
+    }
+    if (driver === "mysql") {
+        return findMissingIndexesMysql(schema);
+    }
+    const result = await query(`
+    SELECT
+      relname AS table_name,
+      seq_scan::text,
+      seq_tup_read::text,
+      COALESCE(idx_scan, 0)::text AS idx_scan,
+      n_live_tup::text,
+      pg_size_pretty(pg_table_size(quote_ident(schemaname) || '.' || quote_ident(relname))) AS table_size
+    FROM pg_stat_user_tables
+    WHERE schemaname = $1
+      AND n_live_tup > 1000
+      AND seq_scan > COALESCE(idx_scan, 0)
+    ORDER BY seq_tup_read DESC
+  `, [schema]);
+    const lines = formatMissingIndexes(result.rows, schema);
+    // PostgreSQL-specific: check for unindexed foreign keys
+    const fkResult = await query(`
+    SELECT
+      kcu.table_name,
+      kcu.column_name,
+      tc.constraint_name,
+      ccu.table_name AS foreign_table
+    FROM information_schema.table_constraints tc
+    JOIN information_schema.key_column_usage kcu
+      ON tc.constraint_name = kcu.constraint_name
+      AND tc.table_schema = kcu.table_schema
+    JOIN information_schema.constraint_column_usage ccu
+      ON tc.constraint_name = ccu.constraint_name
+      AND tc.table_schema = ccu.table_schema
+    WHERE tc.constraint_type = 'FOREIGN KEY'
+      AND tc.table_schema = $1
+      AND NOT EXISTS (
+        SELECT 1 FROM pg_indexes pi
+        WHERE pi.schemaname = tc.table_schema
+          AND pi.tablename = kcu.table_name
+          AND pi.indexdef ~ ('\\m' || kcu.column_name || '\\M')
+      )
+    ORDER BY kcu.table_name
+  `, [schema]);
+    if (fkResult.rows.length > 0) {
+        lines.push(`\n### Unindexed Foreign Keys (${fkResult.rows.length} found)\n`);
+        lines.push("Foreign key columns without indexes cause slow JOINs and cascading deletes.\n");
+        lines.push("| Table | Column | FK → | Constraint |");
+        lines.push("|-------|--------|------|------------|");
+        for (const fk of fkResult.rows) {
+            lines.push(`| ${fk.table_name} | ${fk.column_name} | ${fk.foreign_table} | ${fk.constraint_name} |`);
+        }
+        lines.push("\n**Fix**: Create an index on each column above:\n```sql\nCREATE INDEX idx_<table>_<column> ON <table> (<column>);\n```");
+    }
+    return lines.join("\n");
+}
+async function findMissingIndexesMysql(schema) {
+    try {
+        // MySQL: use information_schema + performance_schema for scan stats
+        const result = await query(`
+    SELECT
+      t.TABLE_NAME AS table_name,
+      CAST(COALESCE(tio.COUNT_READ, 0) AS CHAR) AS seq_scan,
+      CAST(COALESCE(tio.COUNT_FETCH, 0) AS CHAR) AS seq_tup_read,
+      CAST(COALESCE(idx.idx_reads, 0) AS CHAR) AS idx_scan,
+      CAST(t.TABLE_ROWS AS CHAR) AS n_live_tup,
+      CONCAT(ROUND(t.DATA_LENGTH / 1024 / 1024, 2), ' MB') AS table_size
+    FROM information_schema.TABLES t
+    LEFT JOIN performance_schema.table_io_waits_summary_by_table tio
+      ON tio.OBJECT_SCHEMA = t.TABLE_SCHEMA AND tio.OBJECT_NAME = t.TABLE_NAME
+    LEFT JOIN (
+      SELECT OBJECT_SCHEMA, OBJECT_NAME, SUM(COUNT_READ) AS idx_reads
+      FROM performance_schema.table_io_waits_summary_by_index_usage
+      WHERE INDEX_NAME IS NOT NULL
+      GROUP BY OBJECT_SCHEMA, OBJECT_NAME
+    ) idx ON idx.OBJECT_SCHEMA = t.TABLE_SCHEMA AND idx.OBJECT_NAME = t.TABLE_NAME
+    WHERE t.TABLE_SCHEMA = ?
+      AND t.TABLE_TYPE = 'BASE TABLE'
+      AND t.TABLE_ROWS > 1000
+    ORDER BY t.TABLE_ROWS DESC
+  `, [schema]);
+        const lines = formatMissingIndexes(result.rows, schema);
+        // MySQL: check for unindexed FK columns
+        const fkResult = await query(`
+    SELECT
+      kcu.TABLE_NAME AS table_name,
+      kcu.COLUMN_NAME AS column_name,
+      kcu.CONSTRAINT_NAME AS constraint_name,
+      kcu.REFERENCED_TABLE_NAME AS foreign_table
+    FROM information_schema.KEY_COLUMN_USAGE kcu
+    JOIN information_schema.TABLE_CONSTRAINTS tc
+      ON tc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME
+      AND tc.TABLE_SCHEMA = kcu.TABLE_SCHEMA
+      AND tc.TABLE_NAME = kcu.TABLE_NAME
+    WHERE tc.CONSTRAINT_TYPE = 'FOREIGN KEY'
+      AND kcu.TABLE_SCHEMA = ?
+      AND NOT EXISTS (
+        SELECT 1 FROM information_schema.STATISTICS s
+        WHERE s.TABLE_SCHEMA = kcu.TABLE_SCHEMA
+          AND s.TABLE_NAME = kcu.TABLE_NAME
+          AND s.COLUMN_NAME = kcu.COLUMN_NAME
+          AND s.INDEX_NAME != kcu.CONSTRAINT_NAME
+      )
+    ORDER BY kcu.TABLE_NAME
+  `, [schema]);
+        if (fkResult.rows.length > 0) {
+            lines.push(`\n### Unindexed Foreign Keys (${fkResult.rows.length} found)\n`);
+            lines.push("Foreign key columns without indexes cause slow JOINs and cascading deletes.\n");
+            lines.push("| Table | Column | FK → | Constraint |");
+            lines.push("|-------|--------|------|------------|");
+            for (const fk of fkResult.rows) {
+                lines.push(`| ${fk.table_name} | ${fk.column_name} | ${fk.foreign_table} | ${fk.constraint_name} |`);
+            }
+            lines.push("\n**Fix**: Create an index on each column above:\n```sql\nCREATE INDEX idx_<table>_<column> ON <table> (<column>);\n```");
+        }
+        return lines.join("\n");
+    }
+    catch {
+        return "## Missing Index Analysis\n\nUnable to query performance_schema. Ensure performance_schema is enabled (it is ON by default in MySQL 5.7+) and the user has SELECT privilege on performance_schema tables.";
+    }
+}
+function formatMissingIndexes(rows, schema) {
+    if (rows.length === 0) {
+        return [
+            "No tables with suspicious sequential scan patterns found. Either all tables are well-indexed or too small to matter.",
+        ];
+    }
+    const lines = [`## Potential Missing Indexes — schema '${schema}'\n`];
+    lines.push("Tables with more sequential scans than index scans (and >1000 rows).\n" +
+        "High seq_tup_read with low idx_scan suggests missing indexes on commonly queried columns.\n");
+    lines.push("| Table | Seq Scans | Seq Rows Read | Index Scans | Rows | Size |");
+    lines.push("|-------|-----------|---------------|-------------|------|------|");
+    for (const row of rows) {
+        lines.push(`| ${row.table_name} | ${row.seq_scan} | ${row.seq_tup_read} | ${row.idx_scan} | ${row.n_live_tup} | ${row.table_size} |`);
+    }
+    lines.push("\n### Recommendations\n");
+    lines.push("For each table above, check which columns are used in WHERE, JOIN, and ORDER BY clauses. " +
+        "Use the `explain_query` tool to analyze specific slow queries against these tables.");
+    return lines;
+}

package/build/analyzers/query.js

@@ -0,0 +1,241 @@
+import { queryUnsafe, getDriverType } from "../db.js";
+/**
+ * Run EXPLAIN on a query and return a formatted analysis.
+ */
+export async function explainQuery(sql, analyze = false) {
+    // Safety: in ANALYZE mode, only allow pure SELECT statements.
+    // EXPLAIN ANALYZE actually executes the query, so we must reject anything
+    // that could modify data — including CTEs with write operations.
+    if (analyze) {
+        const upperSql = sql.trim().toUpperCase();
+        const DML_KEYWORDS = ["INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "TRUNCATE", "CREATE", "GRANT", "REVOKE", "COPY"];
+        const containsDml = DML_KEYWORDS.some((kw) => upperSql.includes(kw + " ") || upperSql.includes(kw + "\n") || upperSql.includes(kw + "\t") || upperSql.endsWith(kw));
+        if (containsDml) {
+            return "**Error**: EXPLAIN ANALYZE is only allowed on pure SELECT statements. The query contains write operations that would be executed.";
+        }
+    }
+    const driver = getDriverType();
+    if (driver === "sqlite") {
+        return explainQuerySqlite(sql);
+    }
+    if (driver === "mysql") {
+        return explainQueryMysql(sql, analyze);
+    }
+    const explainPrefix = analyze
+        ? "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)"
+        : "EXPLAIN (FORMAT JSON)";
+    const result = await queryUnsafe(`${explainPrefix} ${sql}`);
+    const plan = result.rows[0]?.["QUERY PLAN"]?.[0];
+    if (!plan) {
+        return "Could not parse query plan.";
+    }
+    return formatPlan(plan, analyze);
+}
+async function explainQuerySqlite(sql) {
+    const result = await queryUnsafe(`EXPLAIN QUERY PLAN ${sql}`);
+    if (result.rows.length === 0) {
+        return "Could not parse query plan.";
+    }
+    const lines = ["## Query Plan Analysis (SQLite)\n"];
+    lines.push("```");
+    for (const row of result.rows) {
+        const indent = "  ".repeat(Math.max(0, row.id));
+        lines.push(`${indent}${row.detail}`);
+    }
+    lines.push("```\n");
+    // Check for warnings
+    const warnings = [];
+    for (const row of result.rows) {
+        if (row.detail.includes("SCAN")) {
+            const match = row.detail.match(/SCAN (\w+)/);
+            if (match) {
+                warnings.push(`**Full table scan** on \`${match[1]}\`. Consider adding an index on the filtered columns.`);
+            }
+        }
+    }
+    if (warnings.length > 0) {
+        lines.push("### Potential Issues\n");
+        for (const w of warnings) {
+            lines.push(`- ${w}`);
+        }
+    }
+    return lines.join("\n");
+}
+async function explainQueryMysql(sql, analyze) {
+    const prefix = analyze ? "EXPLAIN ANALYZE" : "EXPLAIN FORMAT=JSON";
+    if (analyze) {
+        // MySQL EXPLAIN ANALYZE returns a text tree, not JSON
+        const result = await queryUnsafe(`${prefix} ${sql}`);
+        const output = result.rows[0]?.EXPLAIN;
+        if (!output) {
+            return "Could not parse query plan.";
+        }
+        const lines = ["## Query Plan Analysis (MySQL EXPLAIN ANALYZE)\n"];
+        lines.push("```");
+        lines.push(output);
+        lines.push("```");
+        return lines.join("\n");
+    }
+    // MySQL EXPLAIN FORMAT=JSON returns a single-column result
+    const result = await queryUnsafe(`${prefix} ${sql}`);
+    const raw = result.rows[0]?.EXPLAIN;
+    if (!raw) {
+        return "Could not parse query plan.";
+    }
+    try {
+        const plan = JSON.parse(raw);
+        return formatMysqlPlan(plan);
+    }
+    catch {
+        return `## Query Plan (raw)\n\n\`\`\`json\n${raw}\n\`\`\``;
+    }
+}
+function formatMysqlPlan(plan) {
+    const lines = ["## Query Plan Analysis (MySQL)\n"];
+    const qb = plan.query_block;
+    if (!qb) {
+        lines.push("```json");
+        lines.push(JSON.stringify(plan, null, 2));
+        lines.push("```");
+        return lines.join("\n");
+    }
+    if (qb.cost_info) {
+        const cost = qb.cost_info;
+        lines.push(`- **Query Cost**: ${cost.query_cost}`);
+    }
+    lines.push("");
+    lines.push("### Plan Details\n");
+    lines.push("```json");
+    lines.push(JSON.stringify(plan, null, 2));
+    lines.push("```");
+    // Extract table info for warnings
+    const warnings = [];
+    extractMysqlWarnings(plan, warnings);
+    if (warnings.length > 0) {
+        lines.push("\n### Potential Issues\n");
+        for (const w of warnings) {
+            lines.push(`- ${w}`);
+        }
+    }
+    return lines.join("\n");
+}
+function extractMysqlWarnings(obj, warnings) {
+    if (obj.table) {
+        const table = obj.table;
+        const accessType = table.access_type;
+        const tableName = table.table_name;
+        const rowsExamined = table.rows_examined_per_scan;
+        if (accessType === "ALL" && rowsExamined && rowsExamined > 10000) {
+            warnings.push(`**Full table scan** on \`${tableName}\` (~${rowsExamined} rows). Consider adding an index.`);
+        }
+        if (table.attached_condition) {
+            const filtered = table.filtered;
+            if (filtered && filtered < 10) {
+                warnings.push(`**Low selectivity** on \`${tableName}\`: only ${filtered}% of rows match the filter. An index would help.`);
+            }
+        }
+    }
+    // Recurse into nested objects and arrays
+    for (const value of Object.values(obj)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item && typeof item === "object") {
+                    extractMysqlWarnings(item, warnings);
+                }
+            }
+        }
+        else if (value && typeof value === "object") {
+            extractMysqlWarnings(value, warnings);
+        }
+    }
+}
+function formatPlan(plan, analyzed) {
+    const lines = [];
+    lines.push("## Query Plan Analysis\n");
+    if (analyzed) {
+        lines.push(`- **Planning Time**: ${plan["Planning Time"]} ms`);
+        lines.push(`- **Execution Time**: ${plan["Execution Time"]} ms`);
+    }
+    lines.push(`- **Estimated Total Cost**: ${plan.Plan["Total Cost"]}`);
+    lines.push(`- **Estimated Rows**: ${plan.Plan["Plan Rows"]}`);
+    lines.push("");
+    lines.push("### Plan Tree\n");
+    lines.push("```");
+    formatNode(plan.Plan, lines, 0);
+    lines.push("```\n");
+    const warnings = collectWarnings(plan.Plan);
+    if (warnings.length > 0) {
+        lines.push("### Potential Issues\n");
+        for (const w of warnings) {
+            lines.push(`- ${w}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function formatNode(node, lines, depth) {
+    const indent = "  ".repeat(depth);
+    let line = `${indent}→ ${node["Node Type"]}`;
+    if (node["Relation Name"]) {
+        line += ` on ${node["Relation Name"]}`;
+        if (node["Alias"] && node["Alias"] !== node["Relation Name"]) {
+            line += ` (${node["Alias"]})`;
+        }
+    }
+    if (node["Index Name"]) {
+        line += ` using ${node["Index Name"]}`;
+    }
+    line += ` (cost=${node["Startup Cost"]}..${node["Total Cost"]} rows=${node["Plan Rows"]})`;
+    if (node["Actual Total Time"] !== undefined) {
+        line += ` (actual time=${node["Actual Startup Time"]}..${node["Actual Total Time"]} rows=${node["Actual Rows"]} loops=${node["Actual Loops"]})`;
+    }
+    lines.push(line);
+    if (node["Filter"]) {
+        lines.push(`${indent}  Filter: ${node["Filter"]}`);
+        if (node["Rows Removed by Filter"]) {
+            lines.push(`${indent}  Rows Removed by Filter: ${node["Rows Removed by Filter"]}`);
+        }
+    }
+    if (node["Index Cond"]) {
+        lines.push(`${indent}  Index Cond: ${node["Index Cond"]}`);
+    }
+    if (node["Hash Cond"]) {
+        lines.push(`${indent}  Hash Cond: ${node["Hash Cond"]}`);
+    }
+    if (node["Sort Key"]) {
+        lines.push(`${indent}  Sort Key: ${node["Sort Key"].join(", ")}`);
+    }
+    if (node["Shared Hit Blocks"] !== undefined || node["Shared Read Blocks"] !== undefined) {
+        lines.push(`${indent}  Buffers: shared hit=${node["Shared Hit Blocks"] ?? 0} read=${node["Shared Read Blocks"] ?? 0}`);
+    }
+    if (node.Plans) {
+        for (const child of node.Plans) {
+            formatNode(child, lines, depth + 1);
+        }
+    }
+}
+function collectWarnings(node) {
+    const warnings = [];
+    if (node["Node Type"] === "Seq Scan" && node["Plan Rows"] > 10000) {
+        warnings.push(`**Sequential Scan** on \`${node["Relation Name"]}\` (~${node["Plan Rows"]} rows). Consider adding an index on the filtered columns.`);
+    }
+    if (node["Rows Removed by Filter"] &&
+        node["Actual Rows"] !== undefined &&
+        node["Rows Removed by Filter"] > node["Actual Rows"] * 10) {
+        warnings.push(`**High filter ratio** on \`${node["Relation Name"] ?? node["Node Type"]}\`: ${node["Rows Removed by Filter"]} rows removed vs ${node["Actual Rows"]} kept. An index on the filter column would eliminate this.`);
+    }
+    if (node["Node Type"] === "Nested Loop" &&
+        node["Actual Rows"] !== undefined &&
+        node["Actual Rows"] > 10000) {
+        warnings.push(`**Nested Loop** producing ${node["Actual Rows"]} rows. Consider if a Hash Join or Merge Join would be more efficient.`);
+    }
+    if (node["Sort Method"] === "external merge") {
+        warnings.push(`**Disk sort** detected. Increase \`work_mem\` or add an index to avoid sorting.`);
+    }
+    if (node.Plans) {
+        for (const child of node.Plans) {
+            warnings.push(...collectWarnings(child));
+        }
+    }
+    return warnings;
+}