rails_vitals 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce21f0b9edbbef2e18452c51755bf980c067c92afb651a86ee99b78aac0cbe6d
-  data.tar.gz: 0ee7cddd129757762d01cdce2f049622bb6f449e44de05ff5d592bfd4933136d
+  metadata.gz: c655986f52ddc0e0848b8e67c28d603ccea2a97dc6b85d9157a7a670fd298fc6
+  data.tar.gz: 49bbb1b8fc0041bd75edb7d3d990ed517dcd907f64b7f99af95eb2d33dbdee80
 SHA512:
-  metadata.gz: 201b26e862cafbde3dfe07f1011ceb3d8241f362ff5386cbae8edbe5e0a250aa99ac800fd4c3d57d9984beec6f54348c78bd7a13f5265cae6a390d137494348e
-  data.tar.gz: de6f0ff8c15da14e155850368884cd14830dce374505ad098f8c3a902865d16ad7d42bd17a38ba51561b3e2fb829e73b03abf2530f16873f6249b1782da4ccc5
+  metadata.gz: 7e905ff8aa217f398c7521b677c088f637b5483cd153af51db1453fbee560476d32b230a3a9d432d975910f60fd9992cd4368a79b6be07abb4a6f676cff5c866
+  data.tar.gz: fcd80c62bc58c1adfed045eb3764f29918705d6b9e0952af68f0f2601197f3af5079ca5abbe62aa6361c950b188711102f96ba3e36b28fa2766138b1fb69ce1d

data/app/helpers/rails_vitals/application_helper.rb

@@ -104,6 +104,16 @@ module RailsVitals
       }[risk.to_sym] || COLOR_NEUTRAL
     end
 
+    # Returns a hex color for EXPLAIN warning severity (:danger, :warning, :info)
+    def explain_severity_color(severity)
+      case severity&.to_sym
+      when :danger  then COLOR_LIGHT_RED
+      when :warning then COLOR_ORANGE
+      when :info    then "#90cdf4"
+      else               COLOR_ORANGE
+      end
+    end
+
     # Returns a readable hex text color for a numeric health score (0-100)
     def score_text_color(score)
       case score.to_i

data/app/views/rails_vitals/explains/show.html.erb

@@ -50,7 +50,7 @@
       </div>
 
       <% @result.warnings.each do |w| %>
-        <% severity_color = w[:severity] == :danger ? "#fc8181" : "#f6ad55" %>
+        <% severity_color = explain_severity_color(w[:severity]) %>
 
         <div
           style="background:#1a202c;border-left:3px solid <%= severity_color %>;
@@ -81,6 +81,13 @@
             <div class="text-muted">
               Nested Loop processed a large number of rows. Verify join columns are indexed.
             </div>
+          <% when :function_call %>
+            <div class="bold mb-4" style="color:<%= severity_color %>;">
+              Function Call Detected
+            </div>
+            <div class="text-muted">
+              <%= w[:message] %>
+            </div>
           <% end %>
         </div>
       <% end %>

data/lib/rails_vitals/analyzers/explain_analyzer.rb

@@ -10,7 +10,14 @@ module RailsVitals
       COLOR_NEUTRAL = "#a0aec0"
       COLOR_COOL = "#76e4f7"
 
-      # Node types and their risk/education metadata
+      # ─── Result / PlanNode structs ────────────────────────────────────────────────
+
+      Result = Struct.new(
+        :sql, :plan, :warnings, :suggestions,
+        :total_cost, :actual_time_ms, :rows_examined,
+        :interpretation, :error, :function_calls, :dry_run_result,
+        keyword_init: true
+      )
       NODE_METADATA = {
         "Seq Scan" => {
           risk: :danger,
@@ -114,12 +121,7 @@ module RailsVitals
         }
       }.freeze
 
-      Result = Struct.new(
-        :sql, :plan, :warnings, :suggestions,
-        :total_cost, :actual_time_ms, :rows_examined,
-        :interpretation, :error,
-        keyword_init: true
-      )
+      # ─── Safe SQL analysis ───────────────────────────────────────────────────────
 
       PlanNode = Struct.new(
         :node_type, :relation, :alias_name,
@@ -132,15 +134,34 @@ module RailsVitals
         keyword_init: true
       )
 
+      ALLOWED_FUNCTIONS = %w[
+        COUNT SUM AVG MIN MAX
+        COALESCE NULLIF
+        NOW CURRENT_TIMESTAMP CURRENT_DATE CURRENT_TIME LOCALTIMESTAMP LOCALTIME
+        EXTRACT DATE_PART DATE_TRUNC AGE
+        UPPER LOWER TRIM LENGTH SUBSTRING CONCAT REPLACE POSITION REVERSE
+        ROUND FLOOR CEIL ABS MOD POWER SQRT
+        GREATEST LEAST CAST
+        ROW_NUMBER RANK DENSE_RANK LAG LEAD FIRST_VALUE LAST_VALUE NTILE
+        ARRAY_AGG STRING_AGG
+        JSON_EXTRACT_PATH_TEXT JSONB_EXTRACT_PATH
+      ].freeze
+
+      FUNCTION_CALL_PATTERN = /\b(?!#{ALLOWED_FUNCTIONS.join('|')}\b)[a-zA-Z_]\w*\s*\(/
+
       def self.analyze(sql, binds: [])
         return unsupported_env unless supported_environment?
         return unsupported_sql unless select_query?(sql)
 
         safe_sql = substitute_binds(sql, binds)
+        has_function_calls = contains_function_calls?(safe_sql)
 
-        raw = ActiveRecord::Base.connection.execute(
+        dry_run_result = dry_run(safe_sql)
+        return dry_run_result if dry_run_result.error
+
+        raw = exec_in_read_only_transaction(
           "EXPLAIN (FORMAT JSON, ANALYZE true, BUFFERS false) #{safe_sql}"
-        ).first["QUERY PLAN"]
+        )
 
         plan_json = JSON.parse(raw)
         root_plan = plan_json.first["Plan"]
@@ -150,6 +171,14 @@ module RailsVitals
         warnings = extract_warnings(root_node)
         suggestions = build_suggestions(warnings, root_node)
 
+        if has_function_calls
+          warnings << {
+            type: :function_call,
+            severity: :info,
+            message: "Query contains function calls — executed inside a read-only transaction that prevents writes"
+          }
+        end
+
         result = Result.new(
           sql: safe_sql,
           plan: root_node,
@@ -158,6 +187,8 @@ module RailsVitals
           total_cost: root_plan["Total Cost"]&.round(2),
           actual_time_ms: exec_time,
           rows_examined: count_rows_examined(root_plan),
+          function_calls: has_function_calls,
+          dry_run_result: dry_run_result,
           error: nil
         )
 
@@ -169,6 +200,28 @@ module RailsVitals
                    actual_time_ms: nil, rows_examined: nil)
       end
 
+      def self.dry_run(sql, binds: [])
+        safe_sql = substitute_binds(sql, binds)
+
+        raw = exec_in_read_only_transaction(
+          "EXPLAIN (FORMAT JSON, ANALYZE false, BUFFERS false) #{safe_sql}"
+        )
+
+        plan_json = JSON.parse(raw)
+        root_plan = plan_json.first["Plan"]
+
+        Result.new(
+          sql: safe_sql,
+          total_cost: root_plan["Total Cost"]&.round(2),
+          plan: build_node(root_plan),
+          error: nil
+        )
+      rescue => e
+        Result.new(error: e.message, sql: sql, plan: nil,
+                   warnings: [], suggestions: [], total_cost: nil,
+                   actual_time_ms: nil, rows_examined: nil)
+      end
+
       private
 
       def self.supported_environment?
@@ -179,6 +232,35 @@ module RailsVitals
         sql.strip.match?(/\ASELECT/i)
       end
 
+      def self.contains_function_calls?(sql)
+        clean = sql.gsub(/'.*?(?:''|')/, "").gsub(/".*?"/, "")
+        clean.match?(FUNCTION_CALL_PATTERN)
+      end
+
+      def self.exec_in_read_only_transaction(sql)
+        if postgresql?
+          connection = ActiveRecord::Base.connection
+          connection.execute("BEGIN")
+          connection.execute("SET TRANSACTION READ ONLY")
+          begin
+            result = connection.execute(sql)
+            connection.execute("COMMIT")
+            result.first["QUERY PLAN"]
+          rescue => e
+            connection.execute("ROLLBACK") rescue nil
+            raise e
+          end
+        else
+          ActiveRecord::Base.connection.execute(sql).first["QUERY PLAN"]
+        end
+      end
+
+      def self.postgresql?
+        ActiveRecord::Base.connection.adapter_name.match?(/postgresql/i)
+      rescue
+        false
+      end
+
       def self.substitute_binds(sql, binds)
         # Replace $1, $2 placeholders with safe literal values
         result = sql.dup
@@ -334,6 +416,10 @@ module RailsVitals
           parts << "Sequential scan detected — missing index is causing full table reads"
         end
 
+        if result.function_calls
+          parts << "Query uses function calls — executed in a read-only transaction that prevents writes"
+        end
+
         if result.actual_time_ms.to_f > 100
           parts << "query took #{result.actual_time_ms}ms — above the 100ms warning threshold"
         end

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

@@ -39,7 +39,14 @@ module RailsVitals
           return missing_sql_response if sql.nil? || sql.strip.empty?
           return rejected_sql_response(sql) if dml_present?(sql)
 
-          result = Analyzers::ExplainAnalyzer.analyze(sql.strip)
+          cleaned_sql = sql.strip
+
+          cost_estimate = Analyzers::ExplainAnalyzer.dry_run(cleaned_sql)
+          if cost_estimate.error
+            return error_response("Cost estimate failed: #{cost_estimate.error}")
+          end
+
+          result = Analyzers::ExplainAnalyzer.analyze(cleaned_sql)
 
           return error_response(result.error) if result.error
 
@@ -48,6 +55,11 @@ module RailsVitals
             total_cost: result.total_cost,
             actual_time_ms: result.actual_time_ms,
             rows_examined: result.rows_examined,
+            cost_estimate: {
+              total_cost: cost_estimate.total_cost,
+              note: "Cost estimate from dry-run EXPLAIN (ANALYZE was not executed for this estimate)"
+            },
+            function_calls: result.function_calls,
             warnings: serialize_warnings(result.warnings),
             suggestions: serialize_suggestions(result.suggestions),
             interpretation: result.interpretation

data/lib/rails_vitals/version.rb

@@ -1,3 +1,3 @@
 module RailsVitals
-  VERSION = "0.6.1"
+  VERSION = "0.6.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_vitals
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - David Sanchez