mcp-db-analyzer 0.2.0

package/build/analyzers/suggestions.js

@@ -0,0 +1,166 @@
+import { query, getDriverType } from "../db.js";
+/**
+ * Suggest missing indexes by analyzing scan patterns,
+ * and cross-reference with unused indexes that waste resources.
+ */
+export async function suggestMissingIndexes(schema = "public") {
+    const driver = getDriverType();
+    if (driver === "sqlite") {
+        return suggestMissingIndexesSqlite();
+    }
+    if (driver === "mysql") {
+        return suggestMissingIndexesMysql(schema);
+    }
+    const needsIndex = await query(`
+    SELECT
+      relname AS table_name,
+      seq_scan::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 seq_scan > 1000
+      AND COALESCE(idx_scan, 0) = 0
+    ORDER BY seq_scan DESC
+  `, [schema]);
+    const unused = await query(`
+    SELECT
+      s.relname AS table_name,
+      s.indexrelname AS index_name,
+      pg_size_pretty(pg_relation_size(s.indexrelid)) AS index_size,
+      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
+      AND s.idx_scan = 0
+      AND s.indexrelname NOT LIKE '%_pkey'
+    ORDER BY pg_relation_size(s.indexrelid) DESC
+  `, [schema]);
+    return formatSuggestions(needsIndex.rows, unused.rows, schema);
+}
+async function suggestMissingIndexesSqlite() {
+    // Find tables with no indexes
+    const tables = await query(`
+    SELECT name FROM sqlite_master
+    WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+    ORDER BY name
+  `);
+    const tablesWithoutIndexes = [];
+    for (const table of tables.rows) {
+        const indexes = await query(`
+      SELECT name FROM sqlite_master
+      WHERE type = 'index' AND tbl_name = ? AND name NOT LIKE 'sqlite_%'
+    `, [table.name]);
+        if (indexes.rows.length === 0) {
+            const countResult = await query(`SELECT count(*) as cnt FROM "${table.name}"`);
+            const cnt = countResult.rows[0]?.cnt ?? 0;
+            if (cnt > 100) {
+                tablesWithoutIndexes.push({
+                    table_name: table.name,
+                    row_count: String(cnt),
+                });
+            }
+        }
+    }
+    const lines = [`## Index Suggestions (SQLite)\n`];
+    if (tablesWithoutIndexes.length > 0) {
+        lines.push(`### Tables Without Indexes (${tablesWithoutIndexes.length} found)\n`);
+        lines.push("| Table | Rows |");
+        lines.push("|-------|------|");
+        for (const t of tablesWithoutIndexes) {
+            lines.push(`| ${t.table_name} | ${t.row_count} |`);
+        }
+        lines.push("\n**Tip**: Use `explain_query` to check which queries do full table scans.");
+    }
+    else {
+        lines.push("All tables with >100 rows have at least one index.\n");
+    }
+    lines.push("\n**Note**: SQLite does not track scan statistics. Use `EXPLAIN QUERY PLAN` to identify slow queries.");
+    return lines.join("\n");
+}
+async function suggestMissingIndexesMysql(schema) {
+    try {
+        // Tables with no indexes beyond PRIMARY
+        const needsIndex = await query(`
+      SELECT
+        t.TABLE_NAME AS table_name,
+        CAST(COALESCE(tio.COUNT_READ, 0) AS CHAR) AS seq_scan,
+        '0' 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
+      WHERE t.TABLE_SCHEMA = ?
+        AND t.TABLE_TYPE = 'BASE TABLE'
+        AND t.TABLE_ROWS > 1000
+        AND NOT EXISTS (
+          SELECT 1 FROM information_schema.STATISTICS s
+          WHERE s.TABLE_SCHEMA = t.TABLE_SCHEMA
+            AND s.TABLE_NAME = t.TABLE_NAME
+            AND s.INDEX_NAME != 'PRIMARY'
+        )
+      ORDER BY t.TABLE_ROWS DESC
+    `, [schema]);
+        // Unused non-primary indexes
+        const unused = await query(`
+      SELECT
+        s.OBJECT_NAME AS table_name,
+        s.INDEX_NAME AS index_name,
+        CONCAT(ROUND(COALESCE(ist.STAT_VALUE, 0) * @@innodb_page_size / 1024 / 1024, 2), ' MB') AS index_size,
+        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 ist
+        ON ist.database_name = s.OBJECT_SCHEMA
+        AND ist.table_name = s.OBJECT_NAME
+        AND ist.index_name = s.INDEX_NAME
+        AND ist.stat_name = 'size'
+      WHERE s.OBJECT_SCHEMA = ?
+        AND s.INDEX_NAME IS NOT NULL
+        AND s.INDEX_NAME != 'PRIMARY'
+        AND (s.COUNT_READ = 0 OR s.COUNT_READ IS NULL)
+      ORDER BY COALESCE(ist.STAT_VALUE, 0) DESC
+    `, [schema]);
+        return formatSuggestions(needsIndex.rows, unused.rows, schema);
+    }
+    catch {
+        return "## Index Suggestions\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 formatSuggestions(needsIndex, unused, schema) {
+    const lines = [`## Index Suggestions — schema '${schema}'\n`];
+    if (needsIndex.length > 0) {
+        lines.push(`### Tables Missing Indexes (${needsIndex.length} found)\n`);
+        lines.push("These tables have high scan counts with no non-primary indexes. They may be full-table-scanned on every query.\n");
+        lines.push("| Table | Seq Scans | Index Scans | Rows | Size |");
+        lines.push("|-------|-----------|-------------|------|------|");
+        for (const row of needsIndex) {
+            lines.push(`| ${row.table_name} | ${row.seq_scan} | ${row.idx_scan} | ${row.n_live_tup} | ${row.table_size} |`);
+        }
+        lines.push("\n**Next step**: Use `explain_query` to analyze your most common queries against these tables, then create indexes on the columns used in WHERE and JOIN clauses.\n");
+    }
+    else {
+        lines.push("### No critically unindexed tables found.\n");
+    }
+    if (unused.length > 0) {
+        lines.push(`### Unused Indexes (${unused.length} found)\n`);
+        lines.push("These non-primary-key indexes have zero scans. They slow down writes and waste storage.\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("\n**Recommended**: Drop unused indexes after confirming with your team:\n");
+        for (const idx of unused) {
+            lines.push(`\`\`\`sql\nDROP INDEX ${idx.index_name} ON ${schema}.${idx.table_name};\n\`\`\``);
+        }
+    }
+    else {
+        lines.push("### No unused indexes found.\n");
+    }
+    return lines.join("\n");
+}

package/build/analyzers/vacuum.js

@@ -0,0 +1,187 @@
+import { query, getDriverType } from "../db.js";
+/**
+ * Analyze PostgreSQL VACUUM maintenance status.
+ *
+ * Checks dead tuple ratios, vacuum staleness, autovacuum configuration,
+ * and identifies tables that need manual VACUUM attention.
+ * PostgreSQL only — returns unsupported message for MySQL/SQLite.
+ */
+export async function analyzeVacuum(schema = "public") {
+    const driver = getDriverType();
+    if (driver === "sqlite") {
+        return "## VACUUM Analysis\n\nSQLite does not use autovacuum in the same way as PostgreSQL. Run `VACUUM` manually to defragment the database file.";
+    }
+    if (driver === "mysql") {
+        return "## VACUUM Analysis\n\nMySQL/InnoDB does not use VACUUM. Use `OPTIMIZE TABLE` to reclaim space from fragmented tables. See the `analyze_table_bloat` tool for fragmentation analysis.";
+    }
+    // Get table vacuum stats
+    const stats = await query(`
+    SELECT
+      relname AS table_name,
+      n_live_tup::text,
+      n_dead_tup::text,
+      last_vacuum::text,
+      last_autovacuum::text,
+      last_analyze::text,
+      last_autoanalyze::text,
+      vacuum_count::text,
+      autovacuum_count::text,
+      analyze_count::text,
+      autoanalyze_count::text
+    FROM pg_stat_user_tables
+    WHERE schemaname = $1
+    ORDER BY n_dead_tup DESC
+  `, [schema]);
+    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);
+}
+export function analyzeFindings(tables, settings) {
+    const findings = [];
+    // Check autovacuum enabled
+    const avEnabled = settings.find((s) => s.name === "autovacuum");
+    if (avEnabled && avEnabled.setting === "off") {
+        findings.push({
+            severity: "CRITICAL",
+            table: null,
+            message: "Autovacuum is DISABLED globally",
+            recommendation: "Enable autovacuum immediately: ALTER SYSTEM SET autovacuum = on; SELECT pg_reload_conf();",
+        });
+    }
+    for (const row of tables) {
+        const live = parseInt(row.n_live_tup, 10) || 0;
+        const dead = parseInt(row.n_dead_tup, 10) || 0;
+        const total = live + dead;
+        const deadRatio = total > 0 ? dead / total : 0;
+        // High dead tuple ratio (>20% = critical, >10% = warning)
+        if (deadRatio > 0.20 && dead > 100) {
+            findings.push({
+                severity: "CRITICAL",
+                table: row.table_name,
+                message: `${(deadRatio * 100).toFixed(1)}% dead tuples (${dead} dead / ${total} total)`,
+                recommendation: `Run: VACUUM ANALYZE ${row.table_name};`,
+            });
+        }
+        else if (deadRatio > 0.10 && dead > 50) {
+            findings.push({
+                severity: "WARNING",
+                table: row.table_name,
+                message: `${(deadRatio * 100).toFixed(1)}% dead tuples (${dead} dead / ${total} total)`,
+                recommendation: `Run: VACUUM ANALYZE ${row.table_name};`,
+            });
+        }
+        // Never vacuumed
+        const vacuumCount = parseInt(row.vacuum_count, 10) || 0;
+        const autovacuumCount = parseInt(row.autovacuum_count, 10) || 0;
+        if (vacuumCount === 0 && autovacuumCount === 0 && total > 0) {
+            findings.push({
+                severity: "WARNING",
+                table: row.table_name,
+                message: "Table has never been vacuumed (manual or auto)",
+                recommendation: `Run: VACUUM ANALYZE ${row.table_name};`,
+            });
+        }
+        // Never analyzed
+        const analyzeCount = parseInt(row.analyze_count, 10) || 0;
+        const autoanalyzeCount = parseInt(row.autoanalyze_count, 10) || 0;
+        if (analyzeCount === 0 && autoanalyzeCount === 0 && total > 0) {
+            findings.push({
+                severity: "INFO",
+                table: row.table_name,
+                message: "Table has never been analyzed — query planner statistics may be stale",
+                recommendation: `Run: ANALYZE ${row.table_name};`,
+            });
+        }
+    }
+    return findings;
+}
+export function formatVacuumReport(schema, tables, settings, findings) {
+    const lines = [`## VACUUM Analysis — schema '${schema}'\n`];
+    // Findings summary
+    const critical = findings.filter((f) => f.severity === "CRITICAL");
+    const warnings = findings.filter((f) => f.severity === "WARNING");
+    const info = findings.filter((f) => f.severity === "INFO");
+    if (findings.length === 0) {
+        lines.push("### All tables are well-maintained.\n");
+        lines.push("No vacuum issues detected. Autovacuum appears to be working correctly.\n");
+    }
+    else {
+        lines.push(`### Findings: ${critical.length} critical, ${warnings.length} warnings, ${info.length} info\n`);
+        if (critical.length > 0) {
+            lines.push("#### Critical Issues\n");
+            for (const f of critical) {
+                const prefix = f.table ? `**${f.table}**: ` : "";
+                lines.push(`- ${prefix}${f.message}`);
+                lines.push(`  > ${f.recommendation}\n`);
+            }
+        }
+        if (warnings.length > 0) {
+            lines.push("#### Warnings\n");
+            for (const f of warnings) {
+                const prefix = f.table ? `**${f.table}**: ` : "";
+                lines.push(`- ${prefix}${f.message}`);
+                lines.push(`  > ${f.recommendation}\n`);
+            }
+        }
+        if (info.length > 0) {
+            lines.push("#### Info\n");
+            for (const f of info) {
+                const prefix = f.table ? `**${f.table}**: ` : "";
+                lines.push(`- ${prefix}${f.message}`);
+                lines.push(`  > ${f.recommendation}\n`);
+            }
+        }
+    }
+    // Tables needing vacuum (>10% dead tuples)
+    const needsVacuum = tables.filter((t) => {
+        const live = parseInt(t.n_live_tup, 10) || 0;
+        const dead = parseInt(t.n_dead_tup, 10) || 0;
+        const total = live + dead;
+        return total > 0 && dead / total > 0.10;
+    });
+    if (needsVacuum.length > 0) {
+        lines.push(`### Tables Needing VACUUM (${needsVacuum.length})\n`);
+        lines.push("| Table | Dead Tuples | Dead % | Last Vacuum | Last Autovacuum |");
+        lines.push("|-------|-------------|--------|-------------|-----------------|");
+        for (const row of needsVacuum) {
+            const live = parseInt(row.n_live_tup, 10) || 0;
+            const dead = parseInt(row.n_dead_tup, 10) || 0;
+            const total = live + dead;
+            const deadPct = total > 0 ? ((dead / total) * 100).toFixed(1) : "0.0";
+            lines.push(`| ${row.table_name} | ${dead} | ${deadPct}% | ${row.last_vacuum || "Never"} | ${row.last_autovacuum || "Never"} |`);
+        }
+        lines.push("");
+    }
+    // All tables overview
+    lines.push("### All Tables\n");
+    lines.push("| Table | Live | Dead | Dead % | Vacuum Count | Autovacuum Count | Last Vacuum | Last Analyze |");
+    lines.push("|-------|------|------|--------|--------------|------------------|-------------|--------------|");
+    for (const row of tables) {
+        const live = parseInt(row.n_live_tup, 10) || 0;
+        const dead = parseInt(row.n_dead_tup, 10) || 0;
+        const total = live + dead;
+        const deadPct = total > 0 ? ((dead / total) * 100).toFixed(1) : "0.0";
+        const lastVac = row.last_vacuum || row.last_autovacuum || "Never";
+        const lastAn = row.last_analyze || row.last_autoanalyze || "Never";
+        lines.push(`| ${row.table_name} | ${live} | ${dead} | ${deadPct}% | ${row.vacuum_count} | ${row.autovacuum_count} | ${lastVac} | ${lastAn} |`);
+    }
+    // Autovacuum settings
+    if (settings.length > 0) {
+        lines.push("\n### Autovacuum Configuration\n");
+        lines.push("| Setting | Value |");
+        lines.push("|---------|-------|");
+        for (const s of settings) {
+            lines.push(`| ${s.name} | ${s.setting} |`);
+        }
+    }
+    return lines.join("\n");
+}

package/build/db-mysql.js

@@ -0,0 +1,80 @@
+import mysql from "mysql2/promise";
+function wrapConnectionError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const sanitized = msg.replace(/\/\/[^@]+@/g, "//****:****@");
+    return new Error(`Cannot connect to MySQL: ${sanitized}\n\n` +
+        `Configure connection using one of:\n` +
+        `  DATABASE_URL=mysql://user:pass@host:3306/dbname\n` +
+        `  or individual vars: MYSQL_HOST, MYSQL_PORT, MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD`);
+}
+export function createMysqlAdapter() {
+    let pool = null;
+    function getPool() {
+        if (!pool) {
+            const uri = process.env.DATABASE_URL;
+            if (uri) {
+                pool = mysql.createPool(uri);
+            }
+            else {
+                pool = mysql.createPool({
+                    host: process.env.MYSQL_HOST || process.env.DB_HOST || "localhost",
+                    port: parseInt(process.env.MYSQL_PORT || process.env.DB_PORT || "3306", 10),
+                    database: process.env.MYSQL_DATABASE || process.env.DB_NAME,
+                    user: process.env.MYSQL_USER || process.env.DB_USER,
+                    password: process.env.MYSQL_PASSWORD || process.env.DB_PASSWORD,
+                });
+            }
+        }
+        return pool;
+    }
+    return {
+        driver: "mysql",
+        async query(sql, params) {
+            let conn;
+            try {
+                conn = await getPool().getConnection();
+            }
+            catch (err) {
+                throw wrapConnectionError(err);
+            }
+            try {
+                await conn.query("SET SESSION TRANSACTION READ ONLY");
+                await conn.beginTransaction();
+                try {
+                    const [rows] = await conn.query(sql, params);
+                    await conn.rollback();
+                    return { rows: rows };
+                }
+                catch (err) {
+                    await conn.rollback();
+                    throw err;
+                }
+            }
+            finally {
+                conn.release();
+            }
+        },
+        async queryUnsafe(sql, params) {
+            let conn;
+            try {
+                conn = await getPool().getConnection();
+            }
+            catch (err) {
+                throw wrapConnectionError(err);
+            }
+            try {
+                const [rows] = await conn.query(sql, params);
+                return { rows: rows };
+            }
+            finally {
+                conn.release();
+            }
+        },
+        async close() {
+            if (pool) {
+                await pool.end();
+                pool = null;
+            }
+        },
+    };
+}

package/build/db-postgres.js

@@ -0,0 +1,73 @@
+import pg from "pg";
+const { Pool } = pg;
+function wrapConnectionError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const sanitized = msg.replace(/\/\/[^@]+@/g, "//****:****@");
+    return new Error(`Cannot connect to PostgreSQL: ${sanitized}\n\n` +
+        `Configure connection using one of:\n` +
+        `  DATABASE_URL=postgres://user:pass@host:5432/dbname\n` +
+        `  or individual vars: PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD`);
+}
+export function createPostgresAdapter() {
+    let pool = null;
+    function getPool() {
+        if (!pool) {
+            const connectionString = process.env.DATABASE_URL;
+            if (connectionString) {
+                pool = new Pool({ connectionString });
+            }
+            else {
+                pool = new Pool({
+                    host: process.env.PGHOST || "localhost",
+                    port: parseInt(process.env.PGPORT || "5432", 10),
+                    database: process.env.PGDATABASE || "postgres",
+                    user: process.env.PGUSER,
+                    password: process.env.PGPASSWORD,
+                });
+            }
+        }
+        return pool;
+    }
+    return {
+        driver: "postgres",
+        async query(sql, params) {
+            let client;
+            try {
+                client = await getPool().connect();
+            }
+            catch (err) {
+                throw wrapConnectionError(err);
+            }
+            try {
+                await client.query("SET TRANSACTION READ ONLY");
+                const result = await client.query(sql, params);
+                return { rows: result.rows };
+            }
+            finally {
+                client.release();
+            }
+        },
+        async queryUnsafe(sql, params) {
+            let client;
+            try {
+                client = await getPool().connect();
+            }
+            catch (err) {
+                throw wrapConnectionError(err);
+            }
+            try {
+                const result = await client.query(sql, params);
+                return { rows: result.rows };
+            }
+            finally {
+                client.release();
+            }
+        },
+        async close() {
+            if (pool) {
+                await pool.end();
+                pool = null;
+            }
+        },
+    };
+}

package/build/db-sqlite.js

@@ -0,0 +1,36 @@
+import Database from "better-sqlite3";
+export function createSqliteAdapter() {
+    let db = null;
+    function getDb() {
+        if (!db) {
+            const dbPath = process.env.DATABASE_URL ||
+                process.env.SQLITE_PATH ||
+                process.env.DB_PATH;
+            if (!dbPath) {
+                throw new Error("SQLite path not configured. Set DATABASE_URL, SQLITE_PATH, or DB_PATH.");
+            }
+            db = new Database(dbPath, { readonly: true });
+            db.pragma("journal_mode = WAL");
+        }
+        return db;
+    }
+    return {
+        driver: "sqlite",
+        async query(sql, params) {
+            const stmt = getDb().prepare(sql);
+            const rows = params ? stmt.all(...params) : stmt.all();
+            return { rows: rows };
+        },
+        async queryUnsafe(sql, params) {
+            const stmt = getDb().prepare(sql);
+            const rows = params ? stmt.all(...params) : stmt.all();
+            return { rows: rows };
+        },
+        async close() {
+            if (db) {
+                db.close();
+                db = null;
+            }
+        },
+    };
+}

package/build/db.js

@@ -0,0 +1,41 @@
+let adapter = null;
+let driverType = "postgres";
+export function getDriverType() {
+    return driverType;
+}
+export function setAdapter(a) {
+    adapter = a;
+    driverType = a.driver;
+}
+function getAdapter() {
+    if (!adapter) {
+        throw new Error("Database adapter not initialized. Call initDriver() first.");
+    }
+    return adapter;
+}
+export async function initDriver(driver) {
+    if (driver === "mysql") {
+        const { createMysqlAdapter } = await import("./db-mysql.js");
+        setAdapter(createMysqlAdapter());
+    }
+    else if (driver === "sqlite") {
+        const { createSqliteAdapter } = await import("./db-sqlite.js");
+        setAdapter(createSqliteAdapter());
+    }
+    else {
+        const { createPostgresAdapter } = await import("./db-postgres.js");
+        setAdapter(createPostgresAdapter());
+    }
+}
+export async function query(sql, params) {
+    return getAdapter().query(sql, params);
+}
+export async function queryUnsafe(sql, params) {
+    return getAdapter().queryUnsafe(sql, params);
+}
+export async function closePool() {
+    if (adapter) {
+        await adapter.close();
+        adapter = null;
+    }
+}

package/build/errors.js

@@ -0,0 +1,13 @@
+/**
+ * Format tool errors with connection-specific guidance when applicable.
+ * Sanitizes credentials from error messages.
+ */
+export function formatToolError(context, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const sanitized = msg.replace(/\/\/[^@]+@/g, "//****:****@");
+    const isConnectionError = /ECONNREFUSED|ENOTFOUND|ETIMEDOUT|EHOSTUNREACH|getaddrinfo|connect ECONNRESET|password authentication failed|Access denied|no pg_hba\.conf|connection refused|Connection lost|SQLITE_CANTOPEN/i.test(msg);
+    if (isConnectionError) {
+        return `Error ${context}: ${sanitized}\n\nThis looks like a database connection issue. Check your configuration:\n- Set DATABASE_URL environment variable with a valid connection string\n- Or use driver-specific variables (PGHOST, MYSQL_HOST, SQLITE_PATH)\n- Ensure the database server is running and accessible`;
+    }
+    return `Error ${context}: ${sanitized}`;
+}