@rog0x/mcp-database-tools 1.0.0

package/src/tools/sql-explainer.ts

@@ -0,0 +1,573 @@
+/**
+ * SQL Explainer — take a SQL query and explain what it does
+ * in plain English, step by step.
+ */
+
+interface ExplanationStep {
+  clause: string;
+  sql: string;
+  explanation: string;
+}
+
+interface ExplanationResult {
+  summary: string;
+  queryType: string;
+  steps: ExplanationStep[];
+  tables: string[];
+  columns: string[];
+  conditions: string[];
+  tips: string[];
+}
+
+function normalizeWhitespace(sql: string): string {
+  return sql.replace(/\s+/g, " ").trim();
+}
+
+function detectQueryType(sql: string): string {
+  const upper = sql.trim().toUpperCase();
+  if (upper.startsWith("SELECT")) return "SELECT";
+  if (upper.startsWith("INSERT")) return "INSERT";
+  if (upper.startsWith("UPDATE")) return "UPDATE";
+  if (upper.startsWith("DELETE")) return "DELETE";
+  if (upper.startsWith("CREATE TABLE")) return "CREATE TABLE";
+  if (upper.startsWith("ALTER TABLE")) return "ALTER TABLE";
+  if (upper.startsWith("DROP")) return "DROP";
+  if (upper.startsWith("WITH")) return "CTE (Common Table Expression)";
+  if (upper.startsWith("CREATE INDEX")) return "CREATE INDEX";
+  if (upper.startsWith("TRUNCATE")) return "TRUNCATE";
+  return "UNKNOWN";
+}
+
+function extractTables(sql: string): string[] {
+  const tables: Set<string> = new Set();
+  const upper = normalizeWhitespace(sql).toUpperCase();
+  const original = normalizeWhitespace(sql);
+
+  // FROM table
+  const fromRegex = /\bFROM\s+(\w+(?:\.\w+)?)/gi;
+  let match: RegExpExecArray | null;
+  while ((match = fromRegex.exec(original)) !== null) {
+    tables.add(match[1]);
+  }
+
+  // JOIN table
+  const joinRegex = /\bJOIN\s+(\w+(?:\.\w+)?)/gi;
+  while ((match = joinRegex.exec(original)) !== null) {
+    tables.add(match[1]);
+  }
+
+  // INSERT INTO table
+  const insertRegex = /\bINSERT\s+INTO\s+(\w+(?:\.\w+)?)/gi;
+  while ((match = insertRegex.exec(original)) !== null) {
+    tables.add(match[1]);
+  }
+
+  // UPDATE table
+  const updateRegex = /\bUPDATE\s+(\w+(?:\.\w+)?)/gi;
+  while ((match = updateRegex.exec(original)) !== null) {
+    tables.add(match[1]);
+  }
+
+  // DELETE FROM table
+  const deleteRegex = /\bDELETE\s+FROM\s+(\w+(?:\.\w+)?)/gi;
+  while ((match = deleteRegex.exec(original)) !== null) {
+    tables.add(match[1]);
+  }
+
+  // CREATE TABLE table
+  const createRegex = /\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+(?:\.\w+)?)/gi;
+  while ((match = createRegex.exec(original)) !== null) {
+    tables.add(match[1]);
+  }
+
+  // Ignore SQL keywords that might be captured
+  const ignore = new Set([
+    "SELECT", "SET", "WHERE", "VALUES", "DEFAULT", "NULL",
+    "NOT", "EXISTS", "TABLE", "INDEX", "VIEW",
+  ]);
+  return Array.from(tables).filter((t) => !ignore.has(t.toUpperCase()));
+}
+
+function extractColumns(sql: string): string[] {
+  const cols: Set<string> = new Set();
+  const norm = normalizeWhitespace(sql);
+
+  // SELECT columns FROM
+  const selectMatch = norm.match(/\bSELECT\s+([\s\S]*?)\s+FROM\b/i);
+  if (selectMatch) {
+    const colStr = selectMatch[1];
+    if (colStr.trim() !== "*") {
+      splitRespectingParens(colStr).forEach((c) => {
+        const cleaned = c.trim().replace(/\s+AS\s+\w+$/i, "").trim();
+        cols.add(cleaned);
+      });
+    } else {
+      cols.add("*");
+    }
+  }
+
+  return Array.from(cols);
+}
+
+function splitRespectingParens(text: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if (ch === "(") depth++;
+    if (ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+function extractConditions(sql: string): string[] {
+  const conditions: string[] = [];
+  const norm = normalizeWhitespace(sql);
+
+  // WHERE clause
+  const whereMatch = norm.match(
+    /\bWHERE\s+([\s\S]*?)(?:\bGROUP BY\b|\bORDER BY\b|\bLIMIT\b|\bHAVING\b|\bUNION\b|$)/i
+  );
+  if (whereMatch) {
+    conditions.push(`WHERE: ${whereMatch[1].trim()}`);
+  }
+
+  // HAVING clause
+  const havingMatch = norm.match(
+    /\bHAVING\s+([\s\S]*?)(?:\bORDER BY\b|\bLIMIT\b|\bUNION\b|$)/i
+  );
+  if (havingMatch) {
+    conditions.push(`HAVING: ${havingMatch[1].trim()}`);
+  }
+
+  // ON conditions from JOINs
+  const onRegex = /\bON\s+([\w.]+\s*=\s*[\w.]+)/gi;
+  let match: RegExpExecArray | null;
+  while ((match = onRegex.exec(norm)) !== null) {
+    conditions.push(`JOIN ON: ${match[1].trim()}`);
+  }
+
+  return conditions;
+}
+
+function explainSelect(sql: string): ExplanationStep[] {
+  const steps: ExplanationStep[] = [];
+  const norm = normalizeWhitespace(sql);
+
+  // WITH clause
+  const withMatch = norm.match(/^WITH\s+([\s\S]*?)\s+SELECT/i);
+  if (withMatch) {
+    const cteNames = withMatch[1].match(/(\w+)\s+AS\s*\(/gi) || [];
+    steps.push({
+      clause: "WITH (CTE)",
+      sql: `WITH ${withMatch[1].substring(0, 80)}...`,
+      explanation: `Defines ${cteNames.length} Common Table Expression(s) as temporary named result sets: ${cteNames.map((c) => c.replace(/\s+AS\s*\(/i, "")).join(", ")}`,
+    });
+  }
+
+  // SELECT
+  const selectMatch = norm.match(/\bSELECT\s+(DISTINCT\s+)?([\s\S]*?)\s+FROM\b/i);
+  if (selectMatch) {
+    const distinct = selectMatch[1] ? "unique " : "";
+    const cols = selectMatch[2].trim();
+    const colList = cols === "*" ? "all columns" : `specific columns: ${cols}`;
+    steps.push({
+      clause: "SELECT",
+      sql: `SELECT ${selectMatch[1] || ""}${cols}`,
+      explanation: `Retrieves ${distinct}${colList} from the data source`,
+    });
+  }
+
+  // FROM
+  const fromMatch = norm.match(/\bFROM\s+(\w+(?:\.\w+)?(?:\s+(?:AS\s+)?\w+)?)/i);
+  if (fromMatch) {
+    steps.push({
+      clause: "FROM",
+      sql: `FROM ${fromMatch[1]}`,
+      explanation: `Reads data from the "${fromMatch[1].split(/\s+/)[0]}" table`,
+    });
+  }
+
+  // JOINs
+  const joinRegex =
+    /\b((?:INNER|LEFT|RIGHT|FULL|CROSS)\s+(?:OUTER\s+)?)?JOIN\s+(\w+(?:\.\w+)?(?:\s+(?:AS\s+)?\w+)?)\s+ON\s+([\s\S]*?)(?=\b(?:INNER|LEFT|RIGHT|FULL|CROSS)?\s*JOIN\b|\bWHERE\b|\bGROUP\b|\bORDER\b|\bLIMIT\b|\bHAVING\b|$)/gi;
+  let jmatch: RegExpExecArray | null;
+  while ((jmatch = joinRegex.exec(norm)) !== null) {
+    const joinType = (jmatch[1] || "INNER").trim().toUpperCase();
+    const table = jmatch[2].split(/\s+/)[0];
+    const condition = jmatch[3].trim();
+    const joinDescriptions: Record<string, string> = {
+      INNER: "matching rows from both tables",
+      LEFT: "all rows from the left table and matching rows from the right",
+      "LEFT OUTER": "all rows from the left table and matching rows from the right",
+      RIGHT: "all rows from the right table and matching rows from the left",
+      "RIGHT OUTER": "all rows from the right table and matching rows from the left",
+      FULL: "all rows from both tables, with NULLs where there is no match",
+      "FULL OUTER": "all rows from both tables, with NULLs where there is no match",
+      CROSS: "every combination of rows from both tables (cartesian product)",
+    };
+    const desc = joinDescriptions[joinType] || "matching rows";
+    steps.push({
+      clause: `${joinType} JOIN`,
+      sql: `${joinType} JOIN ${jmatch[2]} ON ${condition}`,
+      explanation: `Combines with "${table}" table, keeping ${desc}, linked by ${condition}`,
+    });
+  }
+
+  // WHERE
+  const whereMatch = norm.match(
+    /\bWHERE\s+([\s\S]*?)(?=\bGROUP BY\b|\bORDER BY\b|\bLIMIT\b|\bHAVING\b|\bUNION\b|$)/i
+  );
+  if (whereMatch) {
+    steps.push({
+      clause: "WHERE",
+      sql: `WHERE ${whereMatch[1].trim()}`,
+      explanation: `Filters rows to only include those where: ${describeConditions(whereMatch[1].trim())}`,
+    });
+  }
+
+  // GROUP BY
+  const groupMatch = norm.match(
+    /\bGROUP BY\s+([\s\S]*?)(?=\bHAVING\b|\bORDER BY\b|\bLIMIT\b|\bUNION\b|$)/i
+  );
+  if (groupMatch) {
+    steps.push({
+      clause: "GROUP BY",
+      sql: `GROUP BY ${groupMatch[1].trim()}`,
+      explanation: `Groups rows together by ${groupMatch[1].trim()}, collapsing multiple rows into one per group`,
+    });
+  }
+
+  // HAVING
+  const havingMatch = norm.match(
+    /\bHAVING\s+([\s\S]*?)(?=\bORDER BY\b|\bLIMIT\b|\bUNION\b|$)/i
+  );
+  if (havingMatch) {
+    steps.push({
+      clause: "HAVING",
+      sql: `HAVING ${havingMatch[1].trim()}`,
+      explanation: `Filters the grouped results to only include groups where: ${havingMatch[1].trim()}`,
+    });
+  }
+
+  // ORDER BY
+  const orderMatch = norm.match(
+    /\bORDER BY\s+([\s\S]*?)(?=\bLIMIT\b|\bOFFSET\b|\bFETCH\b|\bUNION\b|$)/i
+  );
+  if (orderMatch) {
+    steps.push({
+      clause: "ORDER BY",
+      sql: `ORDER BY ${orderMatch[1].trim()}`,
+      explanation: `Sorts the results by ${orderMatch[1].trim()}`,
+    });
+  }
+
+  // LIMIT / OFFSET
+  const limitMatch = norm.match(/\bLIMIT\s+(\d+)/i);
+  const offsetMatch = norm.match(/\bOFFSET\s+(\d+)/i);
+  if (limitMatch) {
+    let desc = `Returns at most ${limitMatch[1]} row(s)`;
+    if (offsetMatch) {
+      desc += `, skipping the first ${offsetMatch[1]}`;
+    }
+    steps.push({
+      clause: "LIMIT",
+      sql: `LIMIT ${limitMatch[1]}${offsetMatch ? ` OFFSET ${offsetMatch[1]}` : ""}`,
+      explanation: desc,
+    });
+  }
+
+  return steps;
+}
+
+function describeConditions(cond: string): string {
+  // Simple heuristic descriptions
+  return cond
+    .replace(/\bAND\b/gi, " AND ")
+    .replace(/\bOR\b/gi, " OR ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function explainInsert(sql: string): ExplanationStep[] {
+  const steps: ExplanationStep[] = [];
+  const norm = normalizeWhitespace(sql);
+
+  const tableMatch = norm.match(/\bINSERT\s+INTO\s+(\w+(?:\.\w+)?)/i);
+  if (tableMatch) {
+    steps.push({
+      clause: "INSERT INTO",
+      sql: `INSERT INTO ${tableMatch[1]}`,
+      explanation: `Adds new row(s) to the "${tableMatch[1]}" table`,
+    });
+  }
+
+  const colsMatch = norm.match(/\bINSERT\s+INTO\s+\w+\s*\(([^)]+)\)/i);
+  if (colsMatch) {
+    steps.push({
+      clause: "COLUMNS",
+      sql: `(${colsMatch[1]})`,
+      explanation: `Specifying values for columns: ${colsMatch[1]}`,
+    });
+  }
+
+  if (/\bVALUES\b/i.test(norm)) {
+    const valuesCount = (norm.match(/\)\s*,\s*\(/g) || []).length + 1;
+    steps.push({
+      clause: "VALUES",
+      sql: "VALUES (...)",
+      explanation: `Inserting ${valuesCount} row(s) of literal values`,
+    });
+  }
+
+  if (/\bSELECT\b/i.test(norm) && /\bINSERT\b/i.test(norm)) {
+    steps.push({
+      clause: "SELECT (subquery)",
+      sql: "INSERT ... SELECT",
+      explanation: "Inserting rows from the result of a SELECT query",
+    });
+  }
+
+  const returningMatch = norm.match(/\bRETURNING\s+(.*)/i);
+  if (returningMatch) {
+    steps.push({
+      clause: "RETURNING",
+      sql: `RETURNING ${returningMatch[1]}`,
+      explanation: `Returns ${returningMatch[1]} from the newly inserted rows`,
+    });
+  }
+
+  return steps;
+}
+
+function explainUpdate(sql: string): ExplanationStep[] {
+  const steps: ExplanationStep[] = [];
+  const norm = normalizeWhitespace(sql);
+
+  const tableMatch = norm.match(/\bUPDATE\s+(\w+(?:\.\w+)?)/i);
+  if (tableMatch) {
+    steps.push({
+      clause: "UPDATE",
+      sql: `UPDATE ${tableMatch[1]}`,
+      explanation: `Modifies existing rows in the "${tableMatch[1]}" table`,
+    });
+  }
+
+  const setMatch = norm.match(/\bSET\s+([\s\S]*?)(?=\bWHERE\b|\bRETURNING\b|$)/i);
+  if (setMatch) {
+    const assignments = splitRespectingParens(setMatch[1]);
+    steps.push({
+      clause: "SET",
+      sql: `SET ${setMatch[1].trim()}`,
+      explanation: `Changes ${assignments.length} column(s): ${assignments.map((a) => a.split("=")[0].trim()).join(", ")}`,
+    });
+  }
+
+  const whereMatch = norm.match(/\bWHERE\s+([\s\S]*?)(?=\bRETURNING\b|$)/i);
+  if (whereMatch) {
+    steps.push({
+      clause: "WHERE",
+      sql: `WHERE ${whereMatch[1].trim()}`,
+      explanation: `Only updates rows where: ${whereMatch[1].trim()}`,
+    });
+  } else {
+    steps.push({
+      clause: "WARNING",
+      sql: "No WHERE clause",
+      explanation: "WARNING: This updates ALL rows in the table! Consider adding a WHERE clause.",
+    });
+  }
+
+  return steps;
+}
+
+function explainDelete(sql: string): ExplanationStep[] {
+  const steps: ExplanationStep[] = [];
+  const norm = normalizeWhitespace(sql);
+
+  const tableMatch = norm.match(/\bDELETE\s+FROM\s+(\w+(?:\.\w+)?)/i);
+  if (tableMatch) {
+    steps.push({
+      clause: "DELETE FROM",
+      sql: `DELETE FROM ${tableMatch[1]}`,
+      explanation: `Removes rows from the "${tableMatch[1]}" table`,
+    });
+  }
+
+  const whereMatch = norm.match(/\bWHERE\s+([\s\S]*?)(?=\bRETURNING\b|$)/i);
+  if (whereMatch) {
+    steps.push({
+      clause: "WHERE",
+      sql: `WHERE ${whereMatch[1].trim()}`,
+      explanation: `Only deletes rows where: ${whereMatch[1].trim()}`,
+    });
+  } else {
+    steps.push({
+      clause: "WARNING",
+      sql: "No WHERE clause",
+      explanation: "WARNING: This deletes ALL rows from the table!",
+    });
+  }
+
+  return steps;
+}
+
+function explainCreateTable(sql: string): ExplanationStep[] {
+  const steps: ExplanationStep[] = [];
+  const norm = normalizeWhitespace(sql);
+
+  const tableMatch = norm.match(
+    /\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+(?:\.\w+)?)/i
+  );
+  if (tableMatch) {
+    const ifNotExists = /IF\s+NOT\s+EXISTS/i.test(norm) ? " (only if it doesn't already exist)" : "";
+    steps.push({
+      clause: "CREATE TABLE",
+      sql: `CREATE TABLE ${tableMatch[1]}`,
+      explanation: `Creates a new table called "${tableMatch[1]}"${ifNotExists}`,
+    });
+  }
+
+  // Extract column definitions
+  const bodyMatch = norm.match(/\([\s\S]+\)/);
+  if (bodyMatch) {
+    const body = bodyMatch[0].slice(1, -1);
+    const defs = splitRespectingParens(body);
+    const columns = defs.filter(
+      (d) => !/^\s*(PRIMARY KEY|FOREIGN KEY|UNIQUE|CHECK|CONSTRAINT)/i.test(d)
+    );
+    const constraints = defs.filter((d) =>
+      /^\s*(PRIMARY KEY|FOREIGN KEY|UNIQUE|CHECK|CONSTRAINT)/i.test(d)
+    );
+
+    if (columns.length > 0) {
+      steps.push({
+        clause: "COLUMNS",
+        sql: columns.map((c) => c.trim()).join(", "),
+        explanation: `Defines ${columns.length} column(s): ${columns.map((c) => c.trim().split(/\s+/)[0]).join(", ")}`,
+      });
+    }
+    if (constraints.length > 0) {
+      steps.push({
+        clause: "CONSTRAINTS",
+        sql: constraints.map((c) => c.trim()).join(", "),
+        explanation: `Adds ${constraints.length} table-level constraint(s)`,
+      });
+    }
+  }
+
+  return steps;
+}
+
+function generateTips(sql: string, queryType: string): string[] {
+  const tips: string[] = [];
+  const upper = normalizeWhitespace(sql).toUpperCase();
+
+  if (queryType === "SELECT") {
+    if (upper.includes("SELECT *")) {
+      tips.push("Consider selecting specific columns instead of * for better performance and clarity");
+    }
+    if (!upper.includes("LIMIT") && !upper.includes("FETCH")) {
+      tips.push("Consider adding a LIMIT clause to prevent returning too many rows");
+    }
+    if (upper.includes("LIKE '%") || upper.includes("LIKE \"%")) {
+      tips.push("Leading wildcard in LIKE pattern prevents index usage — consider full-text search");
+    }
+    if ((upper.match(/JOIN/g) || []).length > 3) {
+      tips.push("Multiple JOINs detected — ensure proper indexes exist on join columns");
+    }
+  }
+
+  if (queryType === "UPDATE" && !upper.includes("WHERE")) {
+    tips.push("No WHERE clause means ALL rows will be updated — double-check this is intended");
+  }
+
+  if (queryType === "DELETE" && !upper.includes("WHERE")) {
+    tips.push("No WHERE clause means ALL rows will be deleted — consider TRUNCATE if intentional");
+  }
+
+  if (/\bIN\s*\(\s*SELECT\b/i.test(upper)) {
+    tips.push("Subquery in IN clause — consider using EXISTS or a JOIN for better performance");
+  }
+
+  return tips;
+}
+
+export function sqlExplainer(sql: string): ExplanationResult {
+  const queryType = detectQueryType(sql);
+  const tables = extractTables(sql);
+  const columns = extractColumns(sql);
+  const conditions = extractConditions(sql);
+
+  let steps: ExplanationStep[];
+
+  switch (queryType) {
+    case "SELECT":
+    case "CTE (Common Table Expression)":
+      steps = explainSelect(sql);
+      break;
+    case "INSERT":
+      steps = explainInsert(sql);
+      break;
+    case "UPDATE":
+      steps = explainUpdate(sql);
+      break;
+    case "DELETE":
+      steps = explainDelete(sql);
+      break;
+    case "CREATE TABLE":
+      steps = explainCreateTable(sql);
+      break;
+    default:
+      steps = [
+        {
+          clause: queryType,
+          sql: normalizeWhitespace(sql).substring(0, 100),
+          explanation: `This is a ${queryType} statement`,
+        },
+      ];
+  }
+
+  const tips = generateTips(sql, queryType);
+
+  // Build summary
+  let summary: string;
+  switch (queryType) {
+    case "SELECT":
+    case "CTE (Common Table Expression)":
+      summary = `Queries data from ${tables.length > 0 ? tables.join(", ") : "unknown table(s)"}`;
+      if (conditions.length > 0) summary += ` with filtering conditions`;
+      break;
+    case "INSERT":
+      summary = `Inserts data into ${tables[0] || "a table"}`;
+      break;
+    case "UPDATE":
+      summary = `Updates data in ${tables[0] || "a table"}`;
+      break;
+    case "DELETE":
+      summary = `Deletes data from ${tables[0] || "a table"}`;
+      break;
+    case "CREATE TABLE":
+      summary = `Creates the "${tables[0] || "unknown"}" table`;
+      break;
+    default:
+      summary = `Executes a ${queryType} operation`;
+  }
+
+  return {
+    summary,
+    queryType,
+    steps,
+    tables,
+    columns,
+    conditions,
+    tips,
+  };
+}