rails-profiler 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a0b42cc0bcdfe940609dbb07f9ee29a23cd00495c738711950749b22e58d664
-  data.tar.gz: b61678855bf48c082f4776773ce1754328c4e6b6d1672ea2542a836f79d9602a
+  metadata.gz: a118e9ba5a79bc87f82ee566e0e2af65a7199fff6694561ad080f990fb7bf8cd
+  data.tar.gz: 44e2391b361cbcda4ea4a133fefb7db653cd2f0a48e72859216c368ce1867ded
 SHA512:
-  metadata.gz: bde96bed30d2bc7fda19f62a10a2a1b9d55e1e73b83bc91ae0bba63ae7fb58a0d66ca692cb3db7ca66d17c29cfc69d190123095d6cc8f428e33e4d3030733b70
-  data.tar.gz: 310c1ddfc31ab16fddd783db87e24bbe10a5c48058f678215f389f66056ede8af928438f7a350fd4f9ab8828f49f6daf4cdffd4f41634c76b3f9d1f0a0840f0f
+  metadata.gz: c69ecc008b9b9c79161cdc18326c9b0c43e99b7a7284b2681980c0c2d2b7a94c10f77dc186b2826f2cf111f53063e10a3790c4245e4c8a4a07bdde7f49b02e7a
+  data.tar.gz: 22031e28d3fc173b52dab71ed8f1fe8f0faf350134ed683b2847d1ad3a4e44e5de438b6de76d83a3f2b554aa22175cee5b578af0aacc4a8b247f2fd32390d431

data/app/assets/builds/profiler.css

@@ -867,6 +867,217 @@ tr:hover .btn-row-delete {
   line-height: 1.5;
 }
 
+.profiler-query-card--n1 {
+  border-left: 3px solid var(--profiler-warning);
+  background: var(--profiler-warning-bg);
+}
+
+.profiler-n1-group {
+  border: 1px solid var(--profiler-warning);
+  border-radius: var(--profiler-radius-md);
+  overflow: hidden;
+}
+.profiler-n1-group__header {
+  display: flex;
+  align-items: center;
+  gap: var(--profiler-space-3);
+  padding: var(--profiler-space-2) var(--profiler-space-3);
+  background: var(--profiler-warning-bg);
+  cursor: pointer;
+  user-select: none;
+}
+.profiler-n1-group__header:hover {
+  filter: brightness(0.97);
+}
+.profiler-n1-group__count {
+  font-size: var(--profiler-text-xs);
+  font-weight: 700;
+  font-family: var(--profiler-font-mono);
+  color: var(--profiler-warning);
+  white-space: nowrap;
+}
+.profiler-n1-group__pattern {
+  flex: 1;
+  font-size: var(--profiler-text-xs);
+  font-family: var(--profiler-font-mono);
+  color: var(--profiler-text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.profiler-n1-group__toggle {
+  font-size: var(--profiler-text-xs);
+  color: var(--profiler-text-muted);
+  white-space: nowrap;
+}
+
+.profiler-n1-backtrace {
+  background: var(--profiler-bg-lighter);
+  border-top: 1px solid var(--profiler-border);
+  padding: var(--profiler-space-2) var(--profiler-space-3);
+}
+.profiler-n1-backtrace__frame {
+  font-size: var(--profiler-text-xs);
+  font-family: var(--profiler-font-mono);
+  color: var(--profiler-text-muted);
+  line-height: 1.8;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.profiler-alert-banner {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--profiler-space-3);
+  padding: var(--profiler-space-3) var(--profiler-space-4);
+  border-radius: var(--profiler-radius-md);
+  border: 1px solid;
+  font-size: var(--profiler-text-sm);
+}
+.profiler-alert-banner--warning {
+  background: var(--profiler-warning-bg);
+  border-color: var(--profiler-warning);
+  color: var(--profiler-text);
+}
+.profiler-alert-banner--error {
+  background: var(--profiler-error-bg);
+  border-color: var(--profiler-error);
+}
+.profiler-alert-banner__icon {
+  flex-shrink: 0;
+  font-size: var(--profiler-text-base);
+}
+
+.profiler-badge {
+  display: inline-block;
+  padding: 1px 6px;
+  border-radius: var(--profiler-radius-sm);
+  font-size: var(--profiler-text-xs);
+  font-weight: 600;
+  font-family: var(--profiler-font-mono);
+  line-height: 1.6;
+}
+.profiler-badge--warning {
+  background: var(--profiler-warning-bg);
+  color: var(--profiler-warning);
+  border: 1px solid rgba(251, 146, 60, 0.3);
+}
+.profiler-badge--error {
+  background: var(--profiler-error-bg);
+  color: var(--profiler-error);
+}
+
+.profiler-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--profiler-space-1);
+  border: 1px solid var(--profiler-border);
+  border-radius: var(--profiler-radius-sm);
+  background: var(--profiler-bg-elevated);
+  color: var(--profiler-text-muted);
+  font-size: var(--profiler-text-sm);
+  font-family: var(--profiler-font-mono);
+  cursor: pointer;
+  transition: all var(--profiler-transition-base);
+}
+.profiler-btn:hover {
+  border-color: var(--profiler-accent);
+  color: var(--profiler-accent);
+}
+.profiler-btn--sm {
+  padding: 1px 8px;
+  font-size: var(--profiler-text-xs);
+}
+
+.profiler-modal__overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.6);
+  z-index: 9000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--profiler-space-4);
+}
+
+.profiler-modal {
+  background: var(--profiler-bg-elevated);
+  border: 1px solid var(--profiler-border);
+  border-radius: var(--profiler-radius-lg, var(--profiler-radius-md));
+  box-shadow: var(--profiler-shadow-lg, var(--profiler-shadow-sm));
+  width: 100%;
+  max-width: 760px;
+  max-height: 80vh;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+.profiler-modal__header {
+  display: flex;
+  align-items: center;
+  gap: var(--profiler-space-3);
+  padding: var(--profiler-space-3) var(--profiler-space-4);
+  border-bottom: 1px solid var(--profiler-border);
+  background: var(--profiler-bg-light);
+  flex-shrink: 0;
+}
+.profiler-modal__title {
+  font-weight: 600;
+  font-family: var(--profiler-font-mono);
+  font-size: var(--profiler-text-sm);
+  flex: 1;
+}
+.profiler-modal__close {
+  background: none;
+  border: none;
+  color: var(--profiler-text-muted);
+  font-size: var(--profiler-text-lg);
+  cursor: pointer;
+  padding: 0 var(--profiler-space-1);
+  line-height: 1;
+}
+.profiler-modal__close:hover {
+  color: var(--profiler-text);
+}
+.profiler-modal__body {
+  padding: var(--profiler-space-4);
+  overflow-y: auto;
+  flex: 1;
+}
+
+.profiler-explain-result {
+  font-family: var(--profiler-font-mono);
+  font-size: var(--profiler-text-xs);
+  color: var(--profiler-text);
+  white-space: pre-wrap;
+  word-break: break-all;
+  line-height: 1.6;
+  margin: 0;
+}
+
+.profiler-explain-node {
+  padding: var(--profiler-space-1) var(--profiler-space-2);
+  margin-bottom: 2px;
+  border-radius: var(--profiler-radius-sm);
+  font-family: var(--profiler-font-mono);
+  font-size: var(--profiler-text-xs);
+}
+.profiler-explain-node--expensive {
+  background: var(--profiler-error-bg);
+  border-left: 2px solid var(--profiler-error);
+}
+.profiler-explain-node__type {
+  font-weight: 600;
+  color: var(--profiler-accent);
+}
+.profiler-explain-node__stats {
+  display: flex;
+  gap: var(--profiler-space-3);
+  margin-top: 1px;
+  flex-wrap: wrap;
+}
+
 .profiler-dump-card {
   background: var(--profiler-bg-light);
   border: 1px solid var(--profiler-border);

data/app/assets/builds/profiler.js

@@ -1263,10 +1263,154 @@
   }
 
   // app/assets/typescript/profiler/components/dashboard/tabs/DatabaseTab.tsx
-  function DatabaseTab({ dbData }) {
+  function normalizeSql(sql) {
+    return sql.replace(/\$\d+/g, "?").replace(/\b\d+\b/g, "?").replace(/'[^']*'/g, "?").replace(/"[^"]*"/g, "?").trim();
+  }
+  function computeN1Groups(queries) {
+    const groups = /* @__PURE__ */ new Map();
+    queries.forEach((query, index) => {
+      if (query.cached || query.transaction) return;
+      const pattern = normalizeSql(query.sql);
+      if (!groups.has(pattern)) {
+        groups.set(pattern, { indices: [], backtrace: query.backtrace ?? [] });
+      }
+      groups.get(pattern).indices.push(index);
+    });
+    const result = [];
+    groups.forEach(({ indices, backtrace }, pattern) => {
+      if (indices.length >= 3) {
+        result.push({ pattern, indices, backtrace });
+      }
+    });
+    return result.sort((a3, b) => b.indices.length - a3.indices.length);
+  }
+  function renderPlanNode(node, depth = 0) {
+    const type = node["Node Type"] ?? "";
+    const actualRows = node["Actual Rows"] ?? 0;
+    const planRows = node["Plan Rows"] ?? 1;
+    const isExpensive = type.includes("Seq Scan") || type.includes("Hash Join") || type.includes("Nested Loop") || type.includes("Filter") || actualRows > 0 && planRows > 0 && actualRows > planRows * 10;
+    const children = node["Plans"] ?? [];
+    return /* @__PURE__ */ u3("div", { class: `profiler-explain-node${isExpensive ? " profiler-explain-node--expensive" : ""}`, style: `margin-left:${depth * 14}px`, children: [
+      /* @__PURE__ */ u3("span", { class: "profiler-explain-node__type", children: type }),
+      node["Relation Name"] && /* @__PURE__ */ u3("span", { class: "profiler-text--muted", children: [
+        " on ",
+        node["Relation Name"]
+      ] }),
+      node["Index Name"] && /* @__PURE__ */ u3("span", { class: "profiler-text--muted", children: [
+        " using ",
+        node["Index Name"]
+      ] }),
+      /* @__PURE__ */ u3("div", { class: "profiler-explain-node__stats profiler-text--xs profiler-text--muted", children: [
+        node["Actual Total Time"] != null && /* @__PURE__ */ u3("span", { children: [
+          "time: ",
+          node["Actual Total Time"].toFixed(3),
+          "ms"
+        ] }),
+        node["Actual Rows"] != null && /* @__PURE__ */ u3("span", { children: [
+          "rows: ",
+          actualRows,
+          " (est: ",
+          planRows,
+          ")"
+        ] }),
+        node["Total Cost"] != null && /* @__PURE__ */ u3("span", { children: [
+          "cost: ",
+          node["Total Cost"].toFixed(2)
+        ] }),
+        node["Filter"] && /* @__PURE__ */ u3("span", { class: "profiler-text--warning", children: [
+          "filter: ",
+          node["Filter"]
+        ] })
+      ] }),
+      children.map((child, i3) => renderPlanNode(child, depth + 1))
+    ] });
+  }
+  function ExplainModal({ state, onClose }) {
+    if (!state.open) return null;
+    const renderResult = () => {
+      if (state.loading) return /* @__PURE__ */ u3("div", { class: "profiler-text--muted", children: "Running EXPLAIN ANALYZE\u2026" });
+      if (state.error) return /* @__PURE__ */ u3("div", { class: "profiler-text--error", children: state.error });
+      if (!state.result) return null;
+      if (state.format === "json") {
+        try {
+          const parsed = typeof state.result === "string" ? JSON.parse(state.result) : state.result;
+          const plans = Array.isArray(parsed) ? parsed : [parsed];
+          return /* @__PURE__ */ u3("div", { class: "profiler-explain-result", children: plans.map((entry, i3) => /* @__PURE__ */ u3("div", { children: [
+            renderPlanNode(entry["Plan"] ?? entry),
+            entry["Planning Time"] != null && /* @__PURE__ */ u3("div", { class: "profiler-text--xs profiler-text--muted profiler-mt-2", children: [
+              "Planning: ",
+              entry["Planning Time"].toFixed(3),
+              "ms",
+              entry["Execution Time"] != null && /* @__PURE__ */ u3(k, { children: [
+                " \xB7 Execution: ",
+                entry["Execution Time"].toFixed(3),
+                "ms"
+              ] })
+            ] })
+          ] }, i3)) });
+        } catch {
+          return /* @__PURE__ */ u3("pre", { class: "profiler-explain-result", children: String(state.result) });
+        }
+      }
+      return /* @__PURE__ */ u3("pre", { class: "profiler-explain-result", children: String(state.result) });
+    };
+    return /* @__PURE__ */ u3("div", { class: "profiler-modal__overlay", onClick: onClose, children: /* @__PURE__ */ u3("div", { class: "profiler-modal", onClick: (e3) => e3.stopPropagation(), children: [
+      /* @__PURE__ */ u3("div", { class: "profiler-modal__header", children: [
+        /* @__PURE__ */ u3("span", { class: "profiler-modal__title", children: "EXPLAIN ANALYZE" }),
+        /* @__PURE__ */ u3("span", { class: "profiler-text--xs profiler-text--muted", children: state.adapter }),
+        /* @__PURE__ */ u3("button", { class: "profiler-modal__close", onClick: onClose, children: "\xD7" })
+      ] }),
+      /* @__PURE__ */ u3("div", { class: "profiler-modal__body", children: renderResult() })
+    ] }) });
+  }
+  function DatabaseTab({ dbData, token }) {
+    const [openBacktraces, setOpenBacktraces] = d2(/* @__PURE__ */ new Set());
+    const [explainState, setExplainState] = d2({
+      open: false,
+      loading: false,
+      result: null,
+      format: "text",
+      adapter: "",
+      error: null
+    });
     if (!dbData?.queries) {
       return /* @__PURE__ */ u3("div", { class: "profiler-empty", children: /* @__PURE__ */ u3("p", { class: "profiler-empty__description", children: "No database queries recorded" }) });
     }
+    const n1Groups = computeN1Groups(dbData.queries);
+    const n1IndexSet = new Set(n1Groups.flatMap((g2) => g2.indices));
+    const toggleBacktrace = (pattern) => {
+      setOpenBacktraces((prev) => {
+        const next = new Set(prev);
+        next.has(pattern) ? next.delete(pattern) : next.add(pattern);
+        return next;
+      });
+    };
+    const runExplain = async (queryIndex) => {
+      setExplainState({ open: true, loading: true, result: null, format: "text", adapter: "", error: null });
+      try {
+        const res = await fetch("/_profiler/api/explain", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ token, query_index: queryIndex })
+        });
+        if (!res.ok) {
+          const body = await res.json().catch(() => ({}));
+          setExplainState((s3) => ({ ...s3, loading: false, error: body.error ?? `HTTP ${res.status}` }));
+          return;
+        }
+        const data = await res.json();
+        setExplainState((s3) => ({
+          ...s3,
+          loading: false,
+          result: data.result,
+          format: data.format ?? "text",
+          adapter: data.adapter ?? ""
+        }));
+      } catch (err) {
+        setExplainState((s3) => ({ ...s3, loading: false, error: err.message ?? "Request failed" }));
+      }
+    };
+    const closeExplain = () => setExplainState((s3) => ({ ...s3, open: false }));
     return /* @__PURE__ */ u3(k, { children: [
       /* @__PURE__ */ u3("h2", { class: "profiler-section__header", children: [
         "Database Queries (",
@@ -1290,19 +1434,60 @@
           /* @__PURE__ */ u3("strong", { children: dbData.cached_queries })
         ] })
       ] }),
-      dbData.queries.map((query, index) => /* @__PURE__ */ u3("div", { class: `profiler-query-card${query.slow ? " profiler-query-card--slow" : ""}`, children: [
+      n1Groups.length > 0 && /* @__PURE__ */ u3("div", { class: "profiler-alert-banner profiler-alert-banner--warning profiler-mb-4", children: [
+        /* @__PURE__ */ u3("span", { class: "profiler-alert-banner__icon", children: "\u26A0\uFE0F" }),
+        /* @__PURE__ */ u3("div", { children: [
+          /* @__PURE__ */ u3("strong", { children: "Potential N+1 detected" }),
+          " \u2014 ",
+          n1Groups.length,
+          " pattern",
+          n1Groups.length > 1 ? "s" : "",
+          " repeated ",
+          n1Groups.reduce((sum, g2) => sum + g2.indices.length, 0),
+          " times total",
+          /* @__PURE__ */ u3("div", { class: "profiler-text--xs profiler-text--muted profiler-mt-1", children: "Queries causing N+1 are highlighted below. Expand each group to see the call stack." })
+        ] })
+      ] }),
+      n1Groups.map((group) => /* @__PURE__ */ u3("div", { class: "profiler-n1-group profiler-mb-4", children: [
+        /* @__PURE__ */ u3("div", { class: "profiler-n1-group__header", onClick: () => toggleBacktrace(group.pattern), children: [
+          /* @__PURE__ */ u3("span", { class: "profiler-n1-group__count", children: [
+            "N+1 \xB7 ",
+            group.indices.length,
+            "\xD7"
+          ] }),
+          /* @__PURE__ */ u3("code", { class: "profiler-n1-group__pattern", children: group.pattern }),
+          /* @__PURE__ */ u3("span", { class: "profiler-n1-group__toggle", children: [
+            openBacktraces.has(group.pattern) ? "\u25B2" : "\u25BC",
+            " backtrace"
+          ] })
+        ] }),
+        openBacktraces.has(group.pattern) && group.backtrace.length > 0 && /* @__PURE__ */ u3("div", { class: "profiler-n1-backtrace", children: group.backtrace.map((frame, i3) => /* @__PURE__ */ u3("div", { class: "profiler-n1-backtrace__frame", children: frame }, i3)) })
+      ] }, group.pattern)),
+      dbData.queries.map((query, index) => /* @__PURE__ */ u3("div", { class: [
+        "profiler-query-card",
+        query.slow ? "profiler-query-card--slow" : "",
+        n1IndexSet.has(index) ? "profiler-query-card--n1" : ""
+      ].filter(Boolean).join(" "), children: [
         /* @__PURE__ */ u3("div", { class: "profiler-query-card__header", children: [
-          /* @__PURE__ */ u3("span", { class: "profiler-text--muted", children: [
-            "#",
-            index + 1
+          /* @__PURE__ */ u3("div", { class: "profiler-flex profiler-flex--gap-2", children: [
+            /* @__PURE__ */ u3("span", { class: "profiler-text--muted", children: [
+              "#",
+              index + 1
+            ] }),
+            n1IndexSet.has(index) && /* @__PURE__ */ u3("span", { class: "profiler-badge profiler-badge--warning", children: "N+1" }),
+            query.name && /* @__PURE__ */ u3("span", { class: "profiler-text--xs profiler-text--muted", children: query.name })
           ] }),
-          /* @__PURE__ */ u3("span", { class: `profiler-query-card__duration ${query.slow ? "profiler-query-card__duration--slow" : "profiler-query-card__duration--fast"}`, children: [
-            query.duration.toFixed(2),
-            " ms"
+          /* @__PURE__ */ u3("div", { class: "profiler-flex profiler-flex--gap-2", children: [
+            /* @__PURE__ */ u3("span", { class: `profiler-query-card__duration ${query.slow ? "profiler-query-card__duration--slow" : "profiler-query-card__duration--fast"}`, children: [
+              query.duration.toFixed(2),
+              " ms"
+            ] }),
+            !query.cached && !query.transaction && /* @__PURE__ */ u3("button", { class: "profiler-btn profiler-btn--sm", onClick: () => runExplain(index), children: "Explain" })
           ] })
         ] }),
         /* @__PURE__ */ u3("code", { class: "profiler-query-card__code", children: query.sql })
-      ] }, index))
+      ] }, index)),
+      /* @__PURE__ */ u3(ExplainModal, { state: explainState, onClose: closeExplain })
     ] });
   }
 
@@ -2545,7 +2730,7 @@
           activeTab === "exception" && /* @__PURE__ */ u3(ExceptionTab, { exceptionData: cd["exception"] }),
           activeTab === "request" && /* @__PURE__ */ u3(RequestTab, { profile }),
           activeTab === "dump" && /* @__PURE__ */ u3(DumpsTab, { dumpData: cd["dump"] }),
-          activeTab === "database" && /* @__PURE__ */ u3(DatabaseTab, { dbData: cd["database"] }),
+          activeTab === "database" && /* @__PURE__ */ u3(DatabaseTab, { dbData: cd["database"], token: profile.token }),
           activeTab === "ajax" && /* @__PURE__ */ u3(AjaxTab, { ajaxData: cd["ajax"] }),
           activeTab === "http" && /* @__PURE__ */ u3(HttpTab, { httpData: cd["http"] }),
           activeTab === "timeline" && /* @__PURE__ */ u3(FlameGraphTab, { flamegraphData: cd["flamegraph"], perfData: cd["performance"] }),

data/app/controllers/profiler/api/explain_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "profiler/explain_runner"
+
+module Profiler
+  module Api
+    class ExplainController < ApplicationController
+      skip_before_action :verify_authenticity_token
+
+      def create
+        unless Profiler.configuration.enabled
+          return render json: { error: "EXPLAIN is only available when the profiler is enabled" }, status: :forbidden
+        end
+
+        token       = params[:token].to_s
+        query_index = params[:query_index].to_i
+
+        if token.blank?
+          return render json: { error: "token is required" }, status: :unprocessable_entity
+        end
+
+        result = Profiler::ExplainRunner.run(token, query_index)
+        render json: result
+      rescue ArgumentError => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      rescue => e
+        render json: { error: e.message }, status: :internal_server_error
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -32,5 +32,6 @@ Profiler::Engine.routes.draw do
     resources :outbound_http, only: [:index]
     get "toolbar/:token", to: "toolbar#show"
     post "ajax/link", to: "ajax#link"
+    post "explain", to: "explain#create"
   end
 end

data/lib/profiler/explain_runner.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Profiler
+  # Shared service for running EXPLAIN ANALYZE on a stored query.
+  # Used by both the HTTP API controller and the MCP explain_query tool.
+  module ExplainRunner
+    # @param profile_token [String]
+    # @param query_index   [Integer]
+    # @return [Hash] { result:, format: "json"|"text", adapter: String }
+    #         or raises ArgumentError / RuntimeError
+    def self.run(profile_token, query_index)
+      unless Profiler.configuration.enabled
+        raise SecurityError, "EXPLAIN is only available when the profiler is enabled"
+      end
+
+      profile = Profiler.storage.load(profile_token)
+      raise ArgumentError, "Profile not found: #{profile_token}" unless profile
+
+      db_data = profile.collector_data("database")
+      raise ArgumentError, "No database data in this profile" unless db_data && db_data["queries"]
+
+      queries = db_data["queries"]
+      query_index = query_index.to_i
+      unless query_index >= 0 && query_index < queries.size
+        raise ArgumentError, "Query index #{query_index} out of range (0..#{queries.size - 1})"
+      end
+
+      query = queries[query_index]
+      sql   = query["sql"].to_s
+      binds = Array(query["binds"])
+
+      conn    = ActiveRecord::Base.connection
+      adapter = conn.adapter_name.downcase
+      full_sql = reconstruct_sql(sql, binds, conn, adapter)
+
+      explain_sql, format = build_explain_statement(full_sql, adapter)
+
+      rows = conn.exec_query(explain_sql, "EXPLAIN").to_a
+
+      result = if format == "json"
+        # PostgreSQL / MySQL return JSON in rows[0]["QUERY PLAN"] or rows[0]["EXPLAIN"]
+        raw = rows.first&.values&.first.to_s
+        JSON.parse(raw) rescue raw
+      else
+        rows.map { |r| r.values.join("\t") }.join("\n")
+      end
+
+      { result: result, format: format, adapter: adapter }
+    end
+
+    private
+
+    def self.reconstruct_sql(sql, binds, conn, adapter)
+      return sql if binds.empty?
+
+      if adapter.include?("postgresql")
+        result = sql.dup
+        binds.each_with_index do |value, i|
+          result = result.gsub("$#{i + 1}", conn.quote(value))
+        end
+        result
+      else
+        # MySQL / SQLite: replace ? sequentially
+        result = sql.dup
+        binds.each do |value|
+          result = result.sub("?", conn.quote(value))
+        end
+        result
+      end
+    end
+
+    def self.build_explain_statement(sql, adapter)
+      if adapter.include?("postgresql")
+        ["EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) #{sql}", "json"]
+      elsif adapter.include?("mysql")
+        ["EXPLAIN FORMAT=JSON #{sql}", "json"]
+      else
+        ["EXPLAIN QUERY PLAN #{sql}", "text"]
+      end
+    end
+  end
+end

data/lib/profiler/mcp/resources/n1_patterns.rb

@@ -14,15 +14,15 @@ module Profiler
             db_data = profile.collector_data("database")
             next unless db_data && db_data["queries"]
 
-            query_counts = db_data["queries"].group_by { |q| normalize_sql(q["sql"]) }
-                                             .transform_values(&:count)
+            query_groups = db_data["queries"].group_by { |q| normalize_sql(q["sql"]) }
 
-            query_counts.each do |normalized_sql, count|
+            query_groups.each do |normalized_sql, queries|
               pattern_map[normalized_sql] << {
                 token: profile.token,
                 path: profile.path,
-                count: count,
-                timestamp: profile.started_at&.iso8601
+                count: queries.size,
+                timestamp: profile.started_at&.iso8601,
+                backtrace: (queries.first["backtrace"] || []).first(3)
               }
             end
           end
@@ -35,7 +35,8 @@ module Profiler
           # Sort by total occurrence count descending
           sorted = n1_patterns.map do |sql, occurrences|
             total = occurrences.sum { |o| o[:count] }
-            { sql: sql, total_occurrences: total, profiles: occurrences }
+            sample_backtrace = occurrences.find { |o| o[:backtrace].any? }&.dig(:backtrace) || []
+            { sql: sql, total_occurrences: total, backtrace: sample_backtrace, profiles: occurrences }
           end.sort_by { |p| -p[:total_occurrences] }.first(20)
 
           {

data/lib/profiler/mcp/server.rb

@@ -65,6 +65,7 @@ module Profiler
         require_relative "tools/query_profiles"
         require_relative "tools/get_profile_detail"
         require_relative "tools/analyze_queries"
+        require_relative "tools/explain_query"
         require_relative "tools/get_profile_ajax"
         require_relative "tools/get_profile_dumps"
         require_relative "tools/get_profile_http"
@@ -116,6 +117,18 @@ module Profiler
             },
             handler: Tools::AnalyzeQueries
           ),
+          define_tool(
+            name: "explain_query",
+            description: "Run EXPLAIN ANALYZE on a specific query from a profile. Returns the query execution plan with cost and row estimates. Only available in development/test environments.",
+            input_schema: {
+              properties: {
+                token: { type: "string", description: "Profile token, or 'latest' for the most recent profile (required)" },
+                query_index: { type: "integer", description: "Zero-based index of the query within the profile's database queries list (required)" }
+              },
+              required: ["token", "query_index"]
+            },
+            handler: Tools::ExplainQuery
+          ),
           define_tool(
             name: "get_profile_ajax",
             description: "Get detailed AJAX sub-request breakdown for a profile. Use 'latest' as token to get the most recent profile.",

data/lib/profiler/mcp/tools/analyze_queries.rb

@@ -59,8 +59,8 @@ module Profiler
           slow_threshold = Profiler.configuration.slow_query_threshold
           slow_queries = queries.select { |q| q["duration"] > slow_threshold }
           query_counts = queries.group_by { |q| normalize_sql(q["sql"]) }
-                               .transform_values(&:count)
-                               .select { |_, count| count > 1 }
+                               .transform_values { |qs| { count: qs.size, backtrace: qs.first["backtrace"] || [] } }
+                               .select { |_, v| v[:count] >= 3 }
 
           unless summary_only
             # Detect slow queries
@@ -81,22 +81,27 @@ module Profiler
               lines << "All queries executed in less than #{slow_threshold}ms\n"
             end
 
-            # Detect duplicate queries (potential N+1)
+            # Detect duplicate queries (potential N+1, threshold: ≥ 3 occurrences)
             if query_counts.any?
               lines << "## ⚠️ Duplicate Queries (Potential N+1)"
-              lines << "Found #{query_counts.size} duplicate query patterns:\n"
+              lines << "Found #{query_counts.size} query pattern(s) repeated 3+ times:\n"
 
-              query_counts.sort_by { |_, count| -count }.first(5).each do |sql, count|
-                lines << "### Executed #{count} times:"
+              query_counts.sort_by { |_, v| -v[:count] }.first(5).each do |sql, v|
+                lines << "### Executed #{v[:count]} times:"
                 lines << "```sql"
                 lines << sql
-                lines << "```\n"
+                lines << "```"
+                if v[:backtrace].any?
+                  lines << "#### Called from:"
+                  v[:backtrace].first(3).each { |frame| lines << "  #{frame}" }
+                end
+                lines << ""
               end
 
               lines << "_... and #{query_counts.size - 5} more duplicate patterns_\n" if query_counts.size > 5
             else
               lines << "## ✅ No Duplicate Queries"
-              lines << "No potential N+1 query problems detected\n"
+              lines << "No query pattern repeated 3+ times\n"
             end
           end
 
@@ -106,7 +111,7 @@ module Profiler
           lines << "- **Total Duration:** #{queries.sum { |q| q['duration'] }.round(2)}ms"
           lines << "- **Average Duration:** #{(queries.sum { |q| q['duration'] } / queries.size).round(2)}ms"
           lines << "- **Slow Queries:** #{slow_queries.size}"
-          lines << "- **Duplicate Patterns:** #{query_counts.size}"
+          lines << "- **N+1 Patterns (≥3×):** #{query_counts.size}"
           lines << "- **Cached Queries:** #{queries.count { |q| q['cached'] }}"
 
           lines.join("\n")

data/lib/profiler/mcp/tools/explain_query.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "profiler/explain_runner"
+
+module Profiler
+  module MCP
+    module Tools
+      class ExplainQuery
+        def self.call(params)
+          token       = params["token"]
+          query_index = params["query_index"]
+
+          unless token
+            return [{ type: "text", text: "Error: token parameter is required" }]
+          end
+
+          if query_index.nil?
+            return [{ type: "text", text: "Error: query_index parameter is required" }]
+          end
+
+          unless Profiler.configuration.enabled
+            return [{ type: "text", text: "Error: EXPLAIN is only available when the profiler is enabled" }]
+          end
+
+          data = Profiler::ExplainRunner.run(token, query_index.to_i)
+
+          lines = []
+          lines << "# EXPLAIN ANALYZE — Query ##{query_index}"
+          lines << "Adapter: `#{data[:adapter]}`\n"
+
+          if data[:format] == "json"
+            lines << "```json"
+            lines << JSON.pretty_generate(data[:result])
+            lines << "```"
+          else
+            lines << "```"
+            lines << data[:result].to_s
+            lines << "```"
+          end
+
+          [{ type: "text", text: lines.join("\n") }]
+        rescue ArgumentError => e
+          [{ type: "text", text: "Error: #{e.message}" }]
+        rescue => e
+          [{ type: "text", text: "EXPLAIN failed: #{e.message}" }]
+        end
+      end
+    end
+  end
+end

data/lib/profiler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Profiler
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-profiler
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Sébastien Duplessy
@@ -107,6 +107,7 @@ files:
 - app/assets/builds/profiler.css
 - app/assets/builds/profiler.js
 - app/controllers/profiler/api/ajax_controller.rb
+- app/controllers/profiler/api/explain_controller.rb
 - app/controllers/profiler/api/jobs_controller.rb
 - app/controllers/profiler/api/outbound_http_controller.rb
 - app/controllers/profiler/api/profiles_controller.rb
@@ -138,6 +139,7 @@ files:
 - lib/profiler/collectors/view_collector.rb
 - lib/profiler/configuration.rb
 - lib/profiler/engine.rb
+- lib/profiler/explain_runner.rb
 - lib/profiler/instrumentation/active_job_instrumentation.rb
 - lib/profiler/instrumentation/net_http_instrumentation.rb
 - lib/profiler/instrumentation/sidekiq_middleware.rb
@@ -152,6 +154,7 @@ files:
 - lib/profiler/mcp/server.rb
 - lib/profiler/mcp/tools/analyze_queries.rb
 - lib/profiler/mcp/tools/clear_profiles.rb
+- lib/profiler/mcp/tools/explain_query.rb
 - lib/profiler/mcp/tools/get_profile_ajax.rb
 - lib/profiler/mcp/tools/get_profile_detail.rb
 - lib/profiler/mcp/tools/get_profile_dumps.rb