@deepsql/mcp 0.13.4 → 0.14.0

package/src/commands/index-recommendations.js

@@ -0,0 +1,426 @@
+"use strict";
+
+/**
+ * `deepsql index-recommendations` — surface DeepSQL's DBA-grade index
+ * advisor from the terminal. Mirrors the MCP tools (`get_index_recommendations`
+ * + `apply_index_recommendation`) so an on-call DBA gets the same workflow
+ * an AI coding agent does, without needing the IDE plumbing.
+ *
+ * Subcommands:
+ *   deepsql index-recommendations top    --connection <name> [--limit N] [--json]
+ *   deepsql index-recommendations list   --connection <name> [--json]
+ *   deepsql index-recommendations show   <id> [--json]
+ *   deepsql index-recommendations refresh --connection <name> [--json]
+ *   deepsql index-recommendations apply  <id> [--mode dry-run|apply|apply-and-measure]
+ *                                              [--confirm] [--concurrent|--no-concurrent]
+ *                                              [--json]
+ *   deepsql index-recommendations dismiss <id> [--json]
+ *
+ * Default output is a compact terminal-friendly table. `--json` passes the
+ * raw backend payload through, which is what callers from scripts / CI
+ * pipelines want.
+ *
+ * Apply is the one mutation. The contract matches the MCP tool: default
+ * mode is `dry-run` (HypoPG-based, no writes); the two write modes
+ * (`apply`, `apply-and-measure`) require `--confirm`. `--no-concurrent`
+ * opts out of CREATE INDEX CONCURRENTLY when the brief ACCESS EXCLUSIVE
+ * lock is acceptable (small dev tables, or after the DBA has drained the
+ * connection pool).
+ */
+
+const { ApiError, request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+const SUBCOMMANDS = {
+  top: cmdTop,
+  list: cmdList,
+  show: cmdShow,
+  refresh: cmdRefresh,
+  apply: cmdApply,
+  dismiss: cmdDismiss,
+};
+
+async function run(opts, io = {}) {
+  const sub = opts.positional[0];
+  if (!sub) {
+    throw new Error(
+      "Usage: deepsql index-recommendations <top|list|show|refresh|apply|dismiss> …"
+    );
+  }
+  const handler = SUBCOMMANDS[sub];
+  if (!handler) {
+    throw new Error(`Unknown index-recommendations subcommand: ${sub}.`);
+  }
+  return wrap(handler)(
+    { ...opts, positional: opts.positional.slice(1) },
+    io
+  );
+}
+
+function wrap(handler) {
+  return async (opts, io) => {
+    try {
+      return await handler(opts, io);
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 403) {
+        throw new Error(
+          "Access denied — index-recommendation operations require permissions on this connection."
+        );
+      }
+      if (err instanceof ApiError && err.status === 404) {
+        throw new Error(err.message || "Recommendation not found.");
+      }
+      throw err;
+    }
+  };
+}
+
+// ─── top ───────────────────────────────────────────────────────────────────
+
+async function cmdTop(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const limit = clampLimit(opts.limit, 5);
+  const result = await request(
+    session.baseUrl,
+    `/index-recommendations/${encodeURIComponent(connectionId)}/top`,
+    { token: session.token, query: { limit } }
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  const list = Array.isArray(result) ? result : [];
+  if (list.length === 0) {
+    stdout.write(
+      "No pending index recommendations. The 6-hour refresh scheduler may not have run yet, " +
+        "or the workload has none worth flagging. Try `deepsql index-recommendations refresh` " +
+        "to force a fresh accumulation cycle.\n"
+    );
+    return;
+  }
+
+  stdout.write(`Top ${list.length} pending index recommendation(s):\n\n`);
+  list.forEach((r, idx) => {
+    const action = r.kind === "DROP_INDEX" ? "DROP" : "CREATE";
+    const target =
+      r.kind === "DROP_INDEX"
+        ? `${r.tableName}.${r.indexName} (unused)`
+        : `${r.tableName}(${r.columnNames})`;
+
+    const meta = [
+      r.priority,
+      r.occurrenceCount != null ? `seen ${r.occurrenceCount}×` : null,
+      formatNet(r),
+      r.evidenceCount > 0 ? `${r.evidenceCount} ev` : null,
+    ]
+      .filter(Boolean)
+      .join(", ");
+
+    stdout.write(`${idx + 1}. [${action}] ${target} — ${meta}\n`);
+    stdout.write(`   id: ${r.id}\n`);
+    if (r.hypopgReductionPct != null) {
+      stdout.write(
+        `   HypoPG cost: ${formatCost(r.hypopgBeforeCost)} → ${formatCost(r.hypopgAfterCost)} ` +
+          `(${signedPct(r.hypopgReductionPct)})\n`
+      );
+    }
+    if (r.reason) {
+      stdout.write(`   ${truncate(r.reason, 200)}\n`);
+    }
+    if (Array.isArray(r.topEvidence) && r.topEvidence.length) {
+      const ev = r.topEvidence[0];
+      stdout.write(
+        `   top evidence: ${ev.calls} calls × ${formatMs(ev.meanExecTimeMs)}` +
+          ` mean = ${formatMs(ev.totalExecTimeMs)} total (${ev.role})\n`
+      );
+    }
+    stdout.write("\n");
+  });
+}
+
+// ─── list / show ───────────────────────────────────────────────────────────
+
+async function cmdList(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const result = await request(
+    session.baseUrl,
+    `/index-recommendations/pending/${encodeURIComponent(connectionId)}`,
+    { token: session.token }
+  );
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  const list = Array.isArray(result) ? result : [];
+  if (list.length === 0) {
+    stdout.write("No pending index recommendations.\n");
+    return;
+  }
+  stdout.write(`${list.length} pending recommendation(s):\n\n`);
+  list.forEach((r, idx) => {
+    const action = r.kind === "DROP_INDEX" ? "DROP" : "CREATE";
+    stdout.write(
+      `${idx + 1}. [${action}] ${r.tableName}(${r.columnNames || r.indexName}) — ${r.priority}, occ=${r.occurrenceCount}, id=${r.id}\n`
+    );
+  });
+}
+
+async function cmdShow(opts, { stdout = process.stdout } = {}) {
+  const id = opts.positional[0];
+  if (!id) throw new Error("Usage: deepsql index-recommendations show <id>");
+  const session = resolveSession(opts);
+  // No direct GET by id endpoint — use the connection's top with a wide
+  // limit and filter client-side. Cheap enough for inspection use.
+  const connectionId = opts.connection
+    ? await resolveConnectionId(session, opts.connection)
+    : null;
+  if (!connectionId) {
+    throw new Error(
+      "`show` needs --connection <name> to look up the recommendation (or pin one with `deepsql connections use`)."
+    );
+  }
+  const list = await request(
+    session.baseUrl,
+    `/index-recommendations/${encodeURIComponent(connectionId)}/top`,
+    { token: session.token, query: { limit: 50 } }
+  );
+  const found = (list || []).find((r) => r.id === id);
+  if (!found) {
+    throw new Error(`Recommendation ${id} not in the top-50 for this connection.`);
+  }
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(found, null, 2)}\n`);
+    return;
+  }
+  renderRecommendationDetail(stdout, found);
+}
+
+// ─── refresh ───────────────────────────────────────────────────────────────
+
+async function cmdRefresh(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  stderr.write(`Refreshing index recommendations on ${opts.connection || connectionId}…\n`);
+  const result = await request(
+    session.baseUrl,
+    `/index-recommendations/generate/${encodeURIComponent(connectionId)}`,
+    { method: "POST", token: session.token, timeoutMs: 600000 }
+  );
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  if (result && result.success) {
+    stdout.write(
+      `Refresh complete: ${result.count} candidate(s) merged. ` +
+        `Use \`deepsql index-recommendations top\` to see the top-N.\n`
+    );
+  } else {
+    stdout.write(`Refresh response: ${JSON.stringify(result)}\n`);
+  }
+}
+
+// ─── apply ─────────────────────────────────────────────────────────────────
+
+async function cmdApply(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const id = opts.positional[0];
+  if (!id) {
+    throw new Error(
+      "Usage: deepsql index-recommendations apply <id> [--mode dry-run|apply|apply-and-measure] [--confirm] [--no-concurrent]"
+    );
+  }
+
+  const mode = normalizeMode(opts.mode);
+  const isWriteMode = mode === "APPLY" || mode === "APPLY_AND_MEASURE";
+  if (isWriteMode && !opts.confirm) {
+    throw new Error(
+      `Mode ${mode} mutates the target database. Re-run with --confirm to proceed.`
+    );
+  }
+  // --concurrent defaults to true; --no-concurrent flips it off (parser
+  // surfaces noConcurrent boolean).
+  const concurrent = !opts.noConcurrent;
+
+  const session = resolveSession(opts);
+  if (isWriteMode) {
+    stderr.write(`Running ${mode} on recommendation ${id}…\n`);
+  }
+
+  const result = await request(
+    session.baseUrl,
+    `/index-recommendations/${encodeURIComponent(id)}/apply`,
+    {
+      method: "POST",
+      token: session.token,
+      timeoutMs: 600000,
+      query: { mode, confirm: opts.confirm === true, concurrent },
+    }
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  renderApplyResult(stdout, result);
+}
+
+// ─── dismiss ───────────────────────────────────────────────────────────────
+
+async function cmdDismiss(opts, { stdout = process.stdout } = {}) {
+  const id = opts.positional[0];
+  if (!id) throw new Error("Usage: deepsql index-recommendations dismiss <id>");
+  const session = resolveSession(opts);
+  const result = await request(
+    session.baseUrl,
+    `/index-recommendations/${encodeURIComponent(id)}/dismiss`,
+    { method: "PUT", token: session.token }
+  );
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  stdout.write(`Dismissed recommendation ${id}.\n`);
+}
+
+// ─── formatting helpers ────────────────────────────────────────────────────
+
+function renderRecommendationDetail(stdout, r) {
+  const action = r.kind === "DROP_INDEX" ? "DROP" : "CREATE";
+  stdout.write(`[${action}] ${r.tableName}(${r.columnNames || r.indexName})\n`);
+  stdout.write(`  id            : ${r.id}\n`);
+  stdout.write(`  priority      : ${r.priority}\n`);
+  stdout.write(`  status        : ${r.status || "PENDING"}\n`);
+  stdout.write(`  occurrenceCnt : ${r.occurrenceCount}\n`);
+  stdout.write(`  workloadScore : ${formatMs(r.workloadScoreMs)}\n`);
+  stdout.write(`  writeCost     : ${formatMs(r.writeCostScore)}\n`);
+  stdout.write(`  netBenefit    : ${formatMs(r.netBenefitMs)}\n`);
+  if (r.hypopgReductionPct != null) {
+    stdout.write(
+      `  HypoPG        : ${formatCost(r.hypopgBeforeCost)} → ${formatCost(r.hypopgAfterCost)} ` +
+        `(${signedPct(r.hypopgReductionPct)})\n`
+    );
+  }
+  stdout.write(`  DDL           : ${r.createStatement}\n`);
+  if (r.reason) stdout.write(`  reason        : ${r.reason}\n`);
+  if (Array.isArray(r.topEvidence) && r.topEvidence.length) {
+    stdout.write(`  contributing queries (${r.topEvidence.length}):\n`);
+    for (const ev of r.topEvidence) {
+      stdout.write(
+        `    - fp=${(ev.fingerprint || "?").slice(0, 12)} calls=${ev.calls} mean=${formatMs(ev.meanExecTimeMs)} total=${formatMs(ev.totalExecTimeMs)} role=${ev.role}\n`
+      );
+      if (ev.exampleSql) {
+        stdout.write(`      ${truncate(ev.exampleSql, 200)}\n`);
+      }
+    }
+  }
+}
+
+function renderApplyResult(stdout, r) {
+  if (!r || typeof r !== "object") {
+    stdout.write("Apply returned no body.\n");
+    return;
+  }
+  const status = r.status || "?";
+  if (status === "BLOCKED_NEEDS_CONFIRMATION") {
+    stdout.write(`[${r.mode}] blocked — pass --confirm to mutate the database.\n`);
+    return;
+  }
+  if (status === "NOT_FOUND") {
+    stdout.write(`[${r.mode}] recommendation not found: ${r.recommendationId}\n`);
+    return;
+  }
+  if (status === "NO_USABLE_SAMPLES") {
+    stdout.write(
+      `[${r.mode}] no literal-bearing contributing queries available; cannot measure.\n`
+    );
+    return;
+  }
+  if (status === "FAILED") {
+    stdout.write(`[${r.mode}] failed: ${r.message || "(no message)"}\n`);
+    return;
+  }
+
+  stdout.write(`[${r.mode}] ${status}\n`);
+  stdout.write(`  DDL: ${r.executedDdl}\n`);
+  if (r.beforeCost != null && r.afterCost != null) {
+    stdout.write(
+      `  planner cost: ${formatCost(r.beforeCost)} → ${formatCost(r.afterCost)} ` +
+        `(${signedPct(r.costReductionPct)})\n`
+    );
+  }
+  if (r.beforeWallTimeMs != null && r.afterWallTimeMs != null) {
+    stdout.write(
+      `  wall time: ${formatMs(r.beforeWallTimeMs)} → ${formatMs(r.afterWallTimeMs)} ` +
+        `(${signedPct(r.wallTimeImprovementPct)})\n`
+    );
+  }
+  if (Array.isArray(r.samples) && r.samples.length) {
+    stdout.write(`  ${r.samples.length} contributing query sample(s):\n`);
+    for (const s of r.samples.slice(0, 5)) {
+      stdout.write(
+        `    fp=${(s.fingerprint || "?").slice(0, 12)} cost ${formatCost(s.beforeCost)} → ${formatCost(s.afterCost)}` +
+          (s.error ? ` (error: ${s.error})` : "") +
+          "\n"
+      );
+    }
+  }
+  if (r.message) stdout.write(`  ${r.message}\n`);
+}
+
+function clampLimit(raw, fallback) {
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(50, Math.max(1, n));
+}
+
+function normalizeMode(raw) {
+  if (!raw) return "DRY_RUN";
+  // Accept dash-form (CLI convention) and underscore-form (API enum).
+  const m = String(raw).toUpperCase().replace(/-/g, "_");
+  if (!["DRY_RUN", "APPLY", "APPLY_AND_MEASURE"].includes(m)) {
+    throw new Error(`Unknown mode: ${raw}. Expected dry-run, apply, or apply-and-measure.`);
+  }
+  return m;
+}
+
+function formatMs(ms) {
+  if (ms == null || !Number.isFinite(Number(ms))) return "—";
+  const n = Number(ms);
+  if (n <= 0) return "0ms";
+  if (n >= 86_400_000) return `${(n / 86_400_000).toFixed(1)}d`;
+  if (n >= 3_600_000) return `${(n / 3_600_000).toFixed(1)}h`;
+  if (n >= 60_000) return `${(n / 60_000).toFixed(1)}m`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}s`;
+  return `${n.toFixed(n >= 10 ? 0 : 1)}ms`;
+}
+
+function formatCost(c) {
+  if (c == null || !Number.isFinite(Number(c))) return "—";
+  return Number(c).toFixed(0);
+}
+
+function signedPct(pct) {
+  if (pct == null || !Number.isFinite(Number(pct))) return "—";
+  const sign = pct >= 0 ? "−" : "+";
+  return `${sign}${Math.abs(pct).toFixed(1)}%`;
+}
+
+function formatNet(r) {
+  if (r.netBenefitMs != null && r.netBenefitMs > 0) {
+    return `net=${formatMs(r.netBenefitMs)} saved`;
+  }
+  if (r.estimatedImpact != null) return `impact ${r.estimatedImpact}`;
+  return null;
+}
+
+function truncate(s, max) {
+  if (!s) return s;
+  return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
+
+module.exports = { run };