@deepsql/mcp 0.16.0 → 0.18.0

package/skills/SKILL_BODY.md

@@ -2,7 +2,7 @@
 
 You have two DeepSQL surfaces available:
 
-1. **MCP tools** — JSON-RPC tools loaded into your session (10 of them).
+1. **MCP tools** — JSON-RPC tools loaded into your session (21 of them).
    Use these for in-session retrieval and SQL execution.
 
 2. **`deepsql` CLI** — a shell binary on the user's PATH (~19 commands).
@@ -87,6 +87,15 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 | `get_relationships(connectionId)` | Foreign keys (declared + inferred-with-confidence). |
 | `get_anti_patterns(connectionId, kind="table"\|"query")` | Patterns to avoid in this DB. |
 | `analyze_slow_queries(connectionId, thresholdMs?, limit?)` | Snapshot of slow queries from live stats. |
+| `get_slow_query_timeline(connectionId, fingerprint)` | Day-by-day timeline for one fingerprint: call count, mean/max time, regression factor per day. Answers "is this query getting slower". |
+| `get_query_regressions(connectionId, minFactor?)` | Slow queries that got slower on the latest daily analysis run, ranked by slowdown factor. |
+| `list_tracked_queries(connectionId)` | All fingerprints in the 30-day analytics store. Browse first, then drill into one with `get_slow_query_timeline` / `get_query_samples`. |
+| `get_slow_query_customers(connectionId)` | Tenants ranked by total slow-query time — answers "which customer is driving the load?" |
+| `get_query_samples(connectionId, fingerprint)` | Literal SQL samples with bind values for a fingerprint, slowest-first. Use to reproduce an execution or run a real EXPLAIN. |
+| `get_slow_query_insights(connectionId, kind?, window?, limit?)` | Pre-computed AI insights — `hotspots`, `remediation`, `tail-risk`, `plan-drift`, `skew`, or `all` (default). |
+| `optimize_slow_query(connectionId, queryText, avgExecutionTimeMs?)` | AI optimization recommendations for a specific SQL — index suggestions, query rewrites, estimated impact. |
+| `get_table_growth(connectionId, tableName?, days?)` | Persistent stats history: per-table size/row time series + headline rollups. Use to answer "which tables are growing fastest?" or "how much has X grown in the last month?" without scanning the live DB. |
+| `get_growth_anomalies(connectionId, tableName?, unacknowledgedOnly?, days?)` | DeepSQL-flagged sudden growth spikes with severity (CRITICAL/WARNING/INFO), anomaly type, before/after sizes, confidence score. Check this BEFORE walking the user through a slow-query plan — a recent growth anomaly is often the real root cause. |
 | `execute_sql(connectionId, query, ...)` | Run any SQL — SELECT for everyone, DML/DDL for admins (two-step confirm). |
 | `analyze_query_plan(connectionId, query, useAnalyze=false)` | AI-enriched plan analysis (issues + index recs + summary). |
 
@@ -128,8 +137,9 @@ deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 | `deepsql relationships --connection <c>` | Inferred + validated FKs | `get_relationships` |
 | `deepsql anti-patterns --connection <c> [--kind table\|query]` | Anti-patterns | `get_anti_patterns` |
 | `deepsql digest [N]\|list\|show <id>` | **CLI-only**: daily digest of slow queries + AI commentary | none |
+| `deepsql growth trends\|history\|anomalies\|ack\|capture\|config` | Table growth analytics (size/row trends, detected anomalies, alert thresholds) | partial: `get_table_growth`, `get_growth_anomalies` |
 | `deepsql indexes list\|missing\|health\|unused\|duplicates\|usage <table>` | **CLI-only**: index recommendations and usage stats | none |
-| `deepsql slow-queries latest\|history\|analyze\|optimize\|delete` | Slow-query analyses; `optimize` streams AI optimization steps live (SSE) | partial: `analyze_slow_queries` |
+| `deepsql slow-queries latest\|history\|analyze\|optimize\|delete\|trends\|regressions\|timeline\|customers\|samples\|insights\|trigger` | Full slow-query toolkit. `optimize` streams AI optimization steps live (SSE); `customers` / `samples` / `insights` mirror the analytics MCP tools; `trigger` runs an immediate daily analysis. | mostly mirrored in MCP — use CLI for streaming optimize and one-shot triggers |
 | `deepsql users list\|get\|add\|set-role\|lock\|unlock\|disable\|resend-invite\|reset-password\|delete` | **Admin-only, CLI-only**: workspace user management | none |
 | `deepsql access list\|grant\|revoke\|policy <user> <conn>` | **Admin-only, CLI-only**: per-connection access grants + chat policy editing in $EDITOR | none |
 | `deepsql permissions list\|override\|reset` | **Admin-only, CLI-only**: role-based permission overrides | none |
@@ -147,12 +157,20 @@ shell-out (with `--caller-agent`) or tell the user the exact command:
 | User asks for | Run / suggest |
 |---|---|
 | "What changed in the database recently?" / "Today's report" | `deepsql digest` (most recent) or `deepsql digest 7` (last week) |
+| "Which tables are growing fastest?" / "How big is `<table>` now vs a month ago?" | MCP: `get_table_growth(connectionId, days=30)`. CLI: `deepsql growth trends --connection <c>` (or `--table <name> --days 30`) |
+| "Did any table spike in size recently?" / "Anything weird in growth?" | MCP: `get_growth_anomalies(connectionId, unacknowledgedOnly=true)`. CLI: `deepsql growth anomalies --connection <c> --unack` |
+| "Force a fresh stats snapshot" (admin) | `deepsql growth capture --connection <c>` |
+| "Set / view growth alert thresholds" (admin) | `deepsql growth config show --connection <c>` / `set --file <p>` |
 | "What indexes are we missing?" / "Index advice" | `deepsql indexes missing --connection <c>` |
 | "Are any indexes unused?" / "Index bloat" | `deepsql indexes unused --connection <c>` |
 | "Duplicate indexes?" | `deepsql indexes duplicates --connection <c>` |
 | "Index health on this connection" | `deepsql indexes health --connection <c>` |
 | "Indexes on `<table>` and how often they're used" | `deepsql indexes usage <table> --connection <c>` |
-| "Optimize this slow query with AI" / "Stream me a fix" | `deepsql slow-queries optimize --connection <c> --query-id <id>` |
+| "Optimize this slow query with AI" / "Stream me a fix" | `deepsql slow-queries optimize --connection <c> --query-id <id>` (streamed) — or MCP `optimize_slow_query(connectionId, queryText)` for a one-shot JSON response |
+| "Which customer is driving the most slow queries?" | MCP: `get_slow_query_customers(connectionId)`. CLI: `deepsql slow-queries customers --connection <c>` |
+| "Show me the actual SQL run for this fingerprint" | MCP: `get_query_samples(connectionId, fingerprint)`. CLI: `deepsql slow-queries samples <fingerprint> --connection <c>` |
+| "What slow-query insights / hotspots / tail-risk has DeepSQL found?" | MCP: `get_slow_query_insights(connectionId, kind?, window?)`. CLI: `deepsql slow-queries insights --connection <c> [--kind hotspots]` |
+| "Trigger slow-query analysis now" / "Re-run the daily analysis" | CLI: `deepsql slow-queries trigger --connection <c>` |
 | "Add a new database connection" | `deepsql connections add` (interactive) or `--from-file <path>` |
 | "Test a connection without saving" | `deepsql connections test --from-file <path>` |
 | "Trigger brain re-initialization for this connection" | `deepsql connections init <name> --wait` |

package/src/auth/store.js

@@ -30,18 +30,18 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const os = require("node:os");
+const { userHome } = require("../user-home");
 
 function configDir() {
   const override = process.env.DEEPSQL_CONFIG_DIR;
   if (override) return override;
   if (process.platform === "win32") {
-    const base = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    const base = process.env.APPDATA || path.join(userHome(), "AppData", "Roaming");
     return path.join(base, "deepsql");
   }
   const xdg = process.env.XDG_CONFIG_HOME;
   if (xdg) return path.join(xdg, "deepsql");
-  return path.join(os.homedir(), ".config", "deepsql");
+  return path.join(userHome(), ".config", "deepsql");
 }
 
 function authFilePath() {

package/src/cli.js

@@ -31,6 +31,7 @@ const COMMANDS = {
   relationships: () => require("./commands/relationships"),
   "anti-patterns": () => require("./commands/anti-patterns"),
   digest: () => require("./commands/digest"),
+  growth: () => require("./commands/growth"),
   indexes: () => require("./commands/indexes"),
   users: () => require("./commands/users"),
   access: () => require("./commands/access"),
@@ -55,6 +56,7 @@ const COMMAND_LIST = [
   ["analyze",        false, "AI-enriched query plan analysis (use --analyze for EXPLAIN ANALYZE)"],
   ["schema",         false, "Dump connection schema or DB objects as JSON"],
   ["digest",         true,  "Show DeepSQL daily digests"],
+  ["growth",         true,  "Table growth analytics — trends, history, anomalies, alert config"],
   ["brain-context",  false, "Retrieve embedding-ranked context for a question"],
   ["business-rules", false, "List active business rules and SQL guardrails"],
   ["relationships",  false, "List inferred and validated FK relationships"],
@@ -224,6 +226,29 @@ const COMMAND_HELP = {
     ],
   },
 
+  growth: {
+    description: "Table growth analytics — size/row trends, detected anomalies, alert thresholds.",
+    usage: "deepsql growth <subcommand> [options]",
+    subcommands: [
+      ["trends    [--table <t>] [--days N=30]",     "Per-table growth headline over the last N days (default)"],
+      ["history   [--table <t>] [--days N=7]",      "Raw snapshot history rows"],
+      ["anomalies [--table <t>] [--unack] [--days N=30]", "Sudden growth spikes flagged by severity"],
+      ["ack       <anomalyId>",                     "Acknowledge an anomaly"],
+      ["capture",                                   "Trigger a fresh stats snapshot (admin; async)"],
+      ["config    show [--table <t>]",              "Show alert thresholds for the connection"],
+      ["config    set --file <path>",               "POST a GrowthAlertConfiguration JSON (admin)"],
+    ],
+    options: [
+      ["--connection <name>",  "Connection to inspect"],
+      ["--table <name>",       "Filter to one table"],
+      ["--days <N>",           "Lookback window in days (max 365)"],
+      ["--unack",              "anomalies: only unacknowledged ones"],
+      ["--file <path>",        "config set: path to GrowthAlertConfiguration JSON"],
+      ["--json",               "Raw JSON output"],
+    ],
+    notes: "`capture` and `config set` are the only mutations; both are admin-level but neither writes user data. Trends + anomalies are the agent-facing subcommands and are also exposed via the MCP tools `get_table_growth` and `get_growth_anomalies`.",
+  },
+
   "brain-context": {
     description: "Retrieve embedding-ranked tables/columns/FKs, training docs, and business rules for a question.",
     usage: 'deepsql brain-context "<question>" --connection <name> [options]',
@@ -565,6 +590,11 @@ function buildOpts(parsed) {
     // Indexes
     all: !!f.all,
     status: f.status || null,
+    // Growth analytics (also re-used wherever a per-table / lookback filter
+    // is useful — kept generic on purpose)
+    table: f.table || null,
+    days: f.days || null,
+    unack: !!f.unack,
     // mcp config installer
     install: !!f.install,
     print: !!f.print,

package/src/commands/growth.js

@@ -0,0 +1,458 @@
+"use strict";
+
+/**
+ * `deepsql growth` — table growth analytics.
+ *
+ * Backend has a full `/growth-monitoring/*` controller with size/row time
+ * series, anomaly detection (sudden growth spikes flagged by severity),
+ * predictions, and per-table alert configs. Until this command shipped,
+ * none of that was reachable from the CLI or the MCP — the agent and
+ * terminal users could only get to it by hand-rolling SQL against
+ * `table_stats_history`. Now they can ask DeepSQL directly.
+ *
+ *   trends    [--connection <c>] [--table <t>] [--days N=30]    GET    /growth-monitoring/trends/{cid}
+ *   history   [--connection <c>] [--table <t>] [--days N=7]     GET    /growth-monitoring/history/{cid}
+ *   anomalies [--connection <c>] [--table <t>] [--unack] [--days N=30]  GET /growth-monitoring/anomalies/{cid}
+ *   ack       <anomalyId>                                       POST   /growth-monitoring/anomalies/{id}/acknowledge
+ *   capture   [--connection <c>]                                POST   /growth-monitoring/capture/{cid}  (admin)
+ *   config    show [--connection <c>] [--table <t>]             GET    /growth-monitoring/config/{cid}
+ *   config    set --file <path>                                 POST   /growth-monitoring/config       (admin)
+ *
+ * `capture` and `config set` are the only mutations; both are admin-level
+ * but neither writes user data, so we don't gate them behind --confirm.
+ * The other subcommands are pure reads.
+ */
+
+const fs = require("node:fs");
+const { ApiError, request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+const SUBCOMMANDS = {
+  trends: cmdTrends,
+  history: cmdHistory,
+  anomalies: cmdAnomalies,
+  ack: cmdAck,
+  capture: cmdCapture,
+  config: cmdConfig,
+};
+
+async function run(opts, io = {}) {
+  const sub = opts.positional[0] || "trends";
+  const handler = SUBCOMMANDS[sub];
+  if (!handler) {
+    throw new Error(
+      `Unknown growth subcommand: ${sub}. ` +
+        `Try one of: trends, history, anomalies, ack <id>, capture, config show|set.`,
+    );
+  }
+  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 — growth-monitoring requires permissions on this connection.",
+        );
+      }
+      if (err instanceof ApiError && err.status === 404) {
+        throw new Error(err.message || "Resource not found.");
+      }
+      throw err;
+    }
+  };
+}
+
+// ─── trends ────────────────────────────────────────────────────────────────
+//
+// The most agent-friendly subcommand: rolls up the time series into per-
+// table headlines ("orders: +18% / 30d, 240MB → 285MB"). Default subcommand
+// because "what's growing?" is the most common question.
+
+async function cmdTrends(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const days = clampDays(opts.days, 30);
+
+  const response = await request(
+    session.baseUrl,
+    `/growth-monitoring/trends/${encodeURIComponent(connectionId)}`,
+    {
+      token: session.token,
+      query: { tableName: opts.table || null, days },
+    },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  const trends = response?.trends || {};
+  const sizeOverTime = Array.isArray(trends.sizeOverTime) ? trends.sizeOverTime : [];
+  if (sizeOverTime.length === 0) {
+    stdout.write(
+      `No growth data for this connection in the last ${days} day(s). ` +
+        `Run \`deepsql growth capture --connection <c>\` to take a fresh ` +
+        `snapshot if monitoring is enabled, or wait for the scheduled cycle.\n`,
+    );
+    return;
+  }
+
+  // Group by table and compute first / last snapshot per table.
+  const byTable = new Map();
+  for (const point of sizeOverTime) {
+    const t = point.table || "(unknown)";
+    if (!byTable.has(t)) byTable.set(t, []);
+    byTable.get(t).push(point);
+  }
+
+  // Sort tables by absolute growth (largest first) so the most-changed
+  // tables sit at the top of the output — what an agent or operator
+  // actually needs to see first.
+  const rows = [];
+  for (const [table, points] of byTable.entries()) {
+    points.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+    const first = points[0];
+    const last = points[points.length - 1];
+    const firstBytes = first?.sizeBytes ?? 0;
+    const lastBytes = last?.sizeBytes ?? 0;
+    const deltaBytes = lastBytes - firstBytes;
+    const deltaPct = firstBytes > 0 ? (deltaBytes / firstBytes) * 100 : null;
+    rows.push({
+      table,
+      firstBytes,
+      lastBytes,
+      deltaBytes,
+      deltaPct,
+      snapshots: points.length,
+    });
+  }
+  rows.sort((a, b) => Math.abs(b.deltaBytes) - Math.abs(a.deltaBytes));
+
+  stdout.write(
+    `${rows.length} table${rows.length === 1 ? "" : "s"} with growth data ` +
+      `over the last ${days} day(s):\n\n`,
+  );
+  for (const r of rows) {
+    const arrow = r.deltaBytes >= 0 ? "↑" : "↓";
+    const pct = r.deltaPct != null ? signedPct(r.deltaPct) : "n/a";
+    stdout.write(
+      `  ${arrow} ${r.table.padEnd(40)} ` +
+        `${formatBytes(r.firstBytes)} → ${formatBytes(r.lastBytes)} ` +
+        `(${pct}, ${formatBytes(Math.abs(r.deltaBytes))} ${arrow === "↑" ? "added" : "freed"}, ` +
+        `${r.snapshots} snapshots)\n`,
+    );
+  }
+  stdout.write(
+    `\nUse \`deepsql growth history --table <name>\` for per-snapshot detail, ` +
+      `or \`deepsql growth anomalies\` for sudden spikes.\n`,
+  );
+}
+
+// ─── history ───────────────────────────────────────────────────────────────
+
+async function cmdHistory(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const days = clampDays(opts.days, 7);
+
+  const response = await request(
+    session.baseUrl,
+    `/growth-monitoring/history/${encodeURIComponent(connectionId)}`,
+    {
+      token: session.token,
+      query: { tableName: opts.table || null, days },
+    },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  const history = Array.isArray(response?.history) ? response.history : [];
+  if (history.length === 0) {
+    stdout.write(`No history rows in the last ${days} day(s).\n`);
+    return;
+  }
+
+  stdout.write(`${history.length} snapshot${history.length === 1 ? "" : "s"} ` +
+    `over ${days} day(s):\n\n`);
+  for (const h of history) {
+    const ts = (h.snapshotTimestamp || "").substring(0, 19).replace("T", " ");
+    const sz = formatBytes(h.sizeBytes);
+    const rows = h.rowCount != null ? `${formatNumber(h.rowCount)} rows` : "rows: n/a";
+    const growth = h.sizeGrowthPercent != null
+      ? ` Δ ${signedPct(h.sizeGrowthPercent)}`
+      : "";
+    const bloat = h.bloatPercent != null && h.bloatPercent > 0
+      ? `, bloat ${h.bloatPercent.toFixed(1)}%`
+      : "";
+    stdout.write(`  ${ts}  ${h.tableName.padEnd(36)} ${sz.padStart(10)}  ${rows.padStart(16)}${growth}${bloat}\n`);
+  }
+}
+
+// ─── anomalies ─────────────────────────────────────────────────────────────
+
+async function cmdAnomalies(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const days = clampDays(opts.days, 30);
+
+  const response = await request(
+    session.baseUrl,
+    `/growth-monitoring/anomalies/${encodeURIComponent(connectionId)}`,
+    {
+      token: session.token,
+      query: {
+        tableName: opts.table || null,
+        unacknowledgedOnly: opts.unack ? "true" : null,
+        days,
+      },
+    },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  const anomalies = Array.isArray(response?.anomalies) ? response.anomalies : [];
+  const stats = response?.statistics || {};
+
+  if (anomalies.length === 0) {
+    const scope = opts.unack ? "unacknowledged " : "";
+    stdout.write(`No ${scope}anomalies in the last ${days} day(s).\n`);
+    return;
+  }
+
+  const total = stats.total ?? anomalies.length;
+  const crit = stats.critical ?? 0;
+  const warn = stats.warning ?? 0;
+  const unack = stats.unacknowledged ?? 0;
+  stdout.write(`${total} anomal${total === 1 ? "y" : "ies"} ` +
+    `(${crit} critical, ${warn} warning, ${unack} unacknowledged) ` +
+    `over ${days} day(s):\n\n`);
+
+  for (const a of anomalies) {
+    const sev = (a.severity || "INFO").padEnd(8);
+    const marker = sev.startsWith("CRITICAL") ? "✗" : sev.startsWith("WARNING") ? "⚠" : "ℹ";
+    const ts = (a.detectionTimestamp || "").substring(0, 19).replace("T", " ");
+    const type = a.anomalyType || "?";
+    const sizeStr = a.previousSizeBytes != null && a.currentSizeBytes != null
+      ? `${formatBytes(a.previousSizeBytes)} → ${formatBytes(a.currentSizeBytes)}`
+      : "";
+    const pct = a.sizeGrowthPercent != null ? ` (${signedPct(a.sizeGrowthPercent)})` : "";
+    const ackMark = a.acknowledged ? " [acked]" : "";
+    stdout.write(`  ${marker} [${sev.trim()}] ${ts}  ${a.tableName}  ${type}${ackMark}\n`);
+    if (sizeStr) stdout.write(`      size: ${sizeStr}${pct}\n`);
+    if (a.description) stdout.write(`      ${a.description}\n`);
+    stdout.write(`      id: ${a.id}\n\n`);
+  }
+
+  if (unack > 0) {
+    stdout.write(`Use \`deepsql growth ack <id>\` to acknowledge an anomaly.\n`);
+  }
+}
+
+// ─── ack ───────────────────────────────────────────────────────────────────
+
+async function cmdAck(opts, { stdout = process.stdout } = {}) {
+  const anomalyId = opts.positional[0];
+  if (!anomalyId) {
+    throw new Error("Usage: deepsql growth ack <anomalyId>");
+  }
+  const session = resolveSession(opts);
+
+  const response = await request(
+    session.baseUrl,
+    `/growth-monitoring/anomalies/${encodeURIComponent(anomalyId)}/acknowledge`,
+    { method: "POST", token: session.token },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+  if (response?.success) {
+    stdout.write(`Acknowledged anomaly ${anomalyId}.\n`);
+  } else {
+    stdout.write(`${response?.message || "Acknowledge attempt did not return success."}\n`);
+    process.exitCode = 1;
+  }
+}
+
+// ─── capture ───────────────────────────────────────────────────────────────
+
+async function cmdCapture(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const response = await request(
+    session.baseUrl,
+    `/growth-monitoring/capture/${encodeURIComponent(connectionId)}`,
+    { method: "POST", token: session.token },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+  stdout.write(
+    `${response?.message || "Snapshot capture requested."}\n` +
+      `The job runs asynchronously on the backend; re-run ` +
+      `\`deepsql growth trends\` in a minute or two to see the new data.\n`,
+  );
+}
+
+// ─── config ────────────────────────────────────────────────────────────────
+//
+// Two flavors: `config show` (read) and `config set --file <p>` (admin
+// write). The set form takes the full GrowthAlertConfiguration JSON
+// body so we don't have to enumerate every threshold flag — the schema
+// is wider than most CLI inputs warrant and JSON keeps us honest.
+
+async function cmdConfig(opts, io = {}) {
+  const action = opts.positional[0] || "show";
+  if (action === "show") return cmdConfigShow(opts, io);
+  if (action === "set") return cmdConfigSet(opts, io);
+  throw new Error(`Unknown config action: ${action}. Try \`show\` or \`set --file <path>\`.`);
+}
+
+async function cmdConfigShow(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const response = await request(
+    session.baseUrl,
+    `/growth-monitoring/config/${encodeURIComponent(connectionId)}`,
+    { token: session.token, query: { tableName: opts.table || null } },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  const single = response?.configuration;
+  const list = Array.isArray(response?.configurations) ? response.configurations : null;
+
+  if (single) {
+    renderConfig(stdout, single);
+    return;
+  }
+  if (!list || list.length === 0) {
+    stdout.write(
+      "No growth-monitoring configurations for this connection. " +
+        "Defaults are applied. To customize thresholds, " +
+        "POST a GrowthAlertConfiguration JSON via " +
+        "`deepsql growth config set --file <path>`.\n",
+    );
+    return;
+  }
+  stdout.write(`${list.length} alert configuration${list.length === 1 ? "" : "s"}:\n`);
+  for (const c of list) {
+    stdout.write("\n");
+    renderConfig(stdout, c);
+  }
+}
+
+async function cmdConfigSet(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (!opts.file) {
+    throw new Error(
+      "Usage: deepsql growth config set --file <path-to-config.json>\n" +
+        "The JSON body must match GrowthAlertConfiguration (connectionId required).",
+    );
+  }
+  let body;
+  try {
+    body = JSON.parse(fs.readFileSync(opts.file, "utf8"));
+  } catch (err) {
+    throw new Error(`Could not read/parse ${opts.file}: ${err.message}`);
+  }
+  if (!body.connectionId) {
+    throw new Error("Config JSON must include a `connectionId` field.");
+  }
+  const session = resolveSession(opts);
+  const response = await request(
+    session.baseUrl,
+    "/growth-monitoring/config",
+    { method: "POST", token: session.token, json: body },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+  if (response?.success) {
+    stdout.write(`Saved growth-monitoring configuration.\n`);
+    if (response.configuration) renderConfig(stdout, response.configuration);
+  } else {
+    stderr.write(`${response?.message || "Save did not return success."}\n`);
+    process.exitCode = 1;
+  }
+}
+
+// ─── helpers ───────────────────────────────────────────────────────────────
+
+function clampDays(value, fallback) {
+  if (value == null) return fallback;
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n) || n < 1) return fallback;
+  return Math.min(365, n);
+}
+
+function formatBytes(bytes) {
+  if (bytes == null) return "?";
+  const abs = Math.abs(bytes);
+  if (abs < 1024) return `${bytes} B`;
+  if (abs < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (abs < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (abs < 1024 * 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+  return `${(bytes / (1024 * 1024 * 1024 * 1024)).toFixed(2)} TB`;
+}
+
+function formatNumber(n) {
+  if (n == null) return "?";
+  return Number(n).toLocaleString("en-US");
+}
+
+function signedPct(n) {
+  if (n == null) return "n/a";
+  const sign = n > 0 ? "+" : "";
+  return `${sign}${Number(n).toFixed(1)}%`;
+}
+
+function renderConfig(stdout, c) {
+  const scope = c.tableName ? `table=${c.tableName}` : "connection-wide";
+  stdout.write(`Configuration (${scope}):\n`);
+  if (c.percentageGrowthWarning != null) {
+    stdout.write(`  growth %  warning=${c.percentageGrowthWarning}%  critical=${c.percentageGrowthCritical}%\n`);
+  }
+  if (c.absoluteGrowthWarningBytes != null) {
+    stdout.write(`  growth bytes  warning=${formatBytes(c.absoluteGrowthWarningBytes)}  critical=${formatBytes(c.absoluteGrowthCriticalBytes)}\n`);
+  }
+  if (c.rowSpikeWarning != null) {
+    stdout.write(`  row spike  warning=${formatNumber(c.rowSpikeWarning)}  critical=${formatNumber(c.rowSpikeCritical)}` +
+      (c.rowSpikePercentage != null ? `  pct=${c.rowSpikePercentage}%` : "") + "\n");
+  }
+  if (c.zScoreThreshold != null) {
+    stdout.write(`  z-score threshold: ${c.zScoreThreshold}\n`);
+  }
+  if (c.historicalWindowHours != null) {
+    stdout.write(`  historical window: ${c.historicalWindowHours} hours\n`);
+  }
+  if (c.minHoursBetweenAlerts != null) {
+    stdout.write(`  min hours between alerts: ${c.minHoursBetweenAlerts}\n`);
+  }
+  if (c.notificationChannels) stdout.write(`  channels: ${c.notificationChannels}\n`);
+  if (c.emailRecipients) stdout.write(`  email: ${c.emailRecipients}\n`);
+  if (c.webhookUrl) stdout.write(`  webhook: ${c.webhookUrl}\n`);
+  stdout.write(`  enabled: ${c.isEnabled !== false}\n`);
+}
+
+module.exports = { run };