sql_query_analyzer 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab9aa8ae033ce267111f508bfa46c9d18fb4b50da0f8dc175719ab40a4a416eb
-  data.tar.gz: f6a8db3ac983476c5c26893a76f4ac127bf83a1fae1172df3f76618e2865752b
+  metadata.gz: de53885b50c1f9d62d98d6713ac536f29b30ebdada947a54bde86610cbc594f2
+  data.tar.gz: 3211b01b3d49e290bb9a7724a3527602b6a80c3cd2d9b7416160967885c6b7dc
 SHA512:
-  metadata.gz: 7013b5496ff18a4753095df4850d3f6130567376a7157fc261848b56a970679c1da2aa55bfaf47f7423af5a4c4ad101e659137ee198342e7a291e2ea28fa25bf
-  data.tar.gz: 4f82e5a2bac1d408dfc9eb40f5b424125cedad911102790d81509a25e102e02fa12ed4da47efa97c360d920030ecdbf9dd320100e4cd9b9d9484ef7d3e7c39b1
+  metadata.gz: 8bbd2f6b1c5cc37034909e5f4a7e24aefc77e2d7d5719ee0d2d5908873249a01ba6ec9d32641658d0d316119ca9b30ce1da0cfbf31d43db02b49930321a92288
+  data.tar.gz: 2c016cca40185f82db401a0a582f5746c15072d6726ebcf7f6ad4e2ff228aecff6e863c00a08ff1da0dce5c7b43d9549e3b047dded9da5255af6f77b0576396c

data/lib/sql_query_analyzer/execute.rb

@@ -0,0 +1,8 @@
+module SqlQueryAnalyzer
+  class Execute
+    def self.explain_sql(raw_sql, run)
+      query_with_options = run ? "EXPLAIN ANALYZE #{raw_sql}" : "EXPLAIN #{raw_sql}"
+      ActiveRecord::Base.connection.execute(query_with_options)
+    end
+  end
+end

data/lib/sql_query_analyzer/explain_analyzer.rb

@@ -1,18 +1,20 @@
 # lib/sql_query_analyzer/explain_analyzer.rb
 module SqlQueryAnalyzer
   module ExplainAnalyzer
-    def explain_with_suggestions
-      explain_output = explain(analyze: true, verbose: true, costs: true, buffers: true, timing: true)
+    def explain_with_suggestions(run: false)
 
-      engine = SqlQueryAnalyzer::SuggestionEngine.new(explain_output, to_sql)
+      unless self.is_a?(ActiveRecord::Relation)
+        puts "⚠️ Not an ActiveRecord Relation. Skipping explain_with_suggestions."
+        return
+      end
+
+      raw_sql = self.to_sql
+
+      explain_output = SqlQueryAnalyzer::Execute.explain_sql(raw_sql, run)
+      engine = SqlQueryAnalyzer::SuggestionEngine.new(explain_output, raw_sql)
       suggestions = engine.analyze
 
-      puts "\n=== EXPLAIN ANALYZE OUTPUT ===\n"
-      puts explain_output
-      puts "\n=== SUGGESTIONS ===\n"
-      suggestions.each do |suggestion|
-        puts "[#{suggestion.severity.to_s.upcase}] #{suggestion.message}"
-      end
+      nil
     rescue => e
       puts "Error analyzing query: #{e.message}"
     end

data/lib/sql_query_analyzer/query_plan_presenter.rb

@@ -0,0 +1,65 @@
+require 'pastel'
+
+module SqlQueryAnalyzer
+  class QueryPlanPresenter
+    def initialize(output:, warnings:, total_cost:, rows_estimate:, actual_time:)
+      @output = output
+      @warnings = warnings
+      @total_cost = total_cost
+      @rows_estimate = rows_estimate
+      @actual_time = actual_time
+      @pastel = Pastel.new
+    end
+
+    def display
+      puts @pastel.bold("\n🔍 QUERY PLAN:")
+      @output.each_with_index do |line, idx|
+        puts "  #{@pastel.cyan("#{idx + 1}:")} #{line}"
+      end
+
+      puts @pastel.bold("\n📊 Query Metrics:")
+      puts "  💰 Total Cost: #{@pastel.green(@total_cost)}" if @total_cost
+      puts "  📈 Rows Estimate: #{@pastel.blue(@rows_estimate)}" if @rows_estimate
+      puts "  ⏱️  Actual Time: #{@pastel.magenta("#{@actual_time} ms")}" if @actual_time
+
+      if @warnings.any?
+        puts @pastel.bold("\n🚩 Warnings and Suggestions:")
+        @warnings.each do |warn|
+          puts "  #{@pastel.yellow("Line #{warn[:line_number]}:")} #{warn[:line_text]}"
+          puts "    👉 #{colorize_by_severity(warn[:suggestion])}"
+        end
+      else
+        puts @pastel.green("\n✅ No immediate problems detected in the query plan.")
+      end
+    end
+
+    def self.classify_cost(cost)
+      return unless cost
+      pastel = Pastel.new
+
+      case cost
+      when 0..300
+        puts pastel.green("\n✅ Query cost is LOW. All good!")
+      when 301..1000
+        puts pastel.yellow("\n🧐 Query cost is MODERATE. May benefit from optimizations.")
+      else
+        puts pastel.red.bold("\n🛑 Query cost is HIGH. Recommend tuning immediately!")
+      end
+    end
+
+    private
+
+    def colorize_by_severity(suggestion)
+      case suggestion.severity
+      when :critical
+        @pastel.red.bold(suggestion.to_s)
+      when :warning
+        @pastel.yellow.bold(suggestion.to_s)
+      when :info
+        @pastel.cyan(suggestion.to_s)
+      else
+        suggestion.to_s
+      end
+    end
+  end
+end

data/lib/sql_query_analyzer/sequential_scan_advisor.rb

@@ -0,0 +1,75 @@
+module SqlQueryAnalyzer
+  class SequentialScanAdvisor
+    attr_reader :query_plan
+
+    def initialize(query_plan)
+      @query_plan = query_plan
+    end
+
+    def enhanced_message
+      table_name, column_names = extract_table_and_columns
+
+      return nil unless sequential_scan_detected?
+
+      if column_names.empty?
+        return "👉 [CRITICAL] ⚡ Sequential Scan detected on '#{table_name}', " \
+               "but no filter condition found. Likely a full table read " \
+               "(e.g., SELECT *), or small table size makes index use unnecessary."
+      end
+
+      messages = []
+      messages << "👉 [CRITICAL] ⚡ Sequential Scan detected on '#{table_name}', " \
+                  "and filter involves columns: #{column_names.join(', ')}."
+      if missing_composite_index?(table_name, column_names)
+        messages << "💡 Consider adding a composite index on: #{column_names.join(', ')}"
+      end
+      messages.join("\n")
+    end
+
+    private
+
+    def sequential_scan_detected?
+      query_plan.include?("Seq Scan on")
+    end
+
+    def extract_table_and_columns
+      table_name = query_plan.match(/Seq Scan on (\w+)/)&.captures&.first
+      [ table_name, extract_columns_from_filter ]
+    end
+
+    def extract_columns_from_filter
+      # Grab the Filter line out of the full plan
+      filter_line = query_plan.lines.find { |l| l.strip.start_with?("Filter:") }
+      return [] unless filter_line
+
+      # Remove the "Filter:" prefix and any Postgres typecasts
+      cleaned = filter_line
+                  .sub("Filter:", "")
+                  .gsub(/::[a-zA-Z_ ]+/, "")
+                  .downcase
+
+      # Pull actual column names for this table from the schema
+      table_name = query_plan.match(/Seq Scan on (\w+)/)&.captures&.first
+      return [] unless table_name
+      schema_cols = ActiveRecord::Base
+                      .connection
+                      .columns(table_name.to_sym)
+                      .map(&:name)
+                      .map(&:downcase)
+
+      # Of all schema columns, pick those mentioned in the cleaned filter
+      extracted = schema_cols.select { |col| cleaned.include?(col) }.uniq
+      extracted
+    end
+
+    def missing_composite_index?(table_name, columns)
+      existing = ActiveRecord::Base
+                   .connection
+                   .indexes(table_name.to_sym)
+                   .map(&:columns)
+                   .map { |cols| cols.map(&:downcase) }
+
+      !existing.any? { |idx_cols| idx_cols == columns || idx_cols.first(columns.length) == columns }
+    end
+  end
+end

data/lib/sql_query_analyzer/sql_level_rules.rb

@@ -0,0 +1,27 @@
+module SqlQueryAnalyzer
+  class SqlLevelRules
+    def self.evaluate(sql)
+      return [] unless sql
+
+      warnings = []
+
+      if sql.match?(/select\s+\*/i)
+        warnings << {
+          line_number: 'N/A',
+          line_text: 'SELECT *',
+          suggestion: Suggestion.new(:warning, "🚨 Query uses SELECT *. Specify only needed columns for performance.")
+        }
+      end
+
+      if sql.match?(/join/i) && !sql.match?(/on/i)
+        warnings << {
+          line_number: 'N/A',
+          line_text: 'JOIN without ON',
+          suggestion: Suggestion.new(:critical, "⚡ JOIN without ON detected. May cause massive row combinations (CROSS JOIN).")
+        }
+      end
+
+      warnings
+    end
+  end
+end

data/lib/sql_query_analyzer/suggestion_engine.rb

@@ -1,52 +1,76 @@
-# lib/sql_query_analyzer/suggestion_engine.rb
+require_relative 'suggestion_rules'
+require_relative 'query_plan_presenter'
+require_relative 'sql_level_rules'
+require_relative 'sequential_scan_advisor'
+
 module SqlQueryAnalyzer
   class Suggestion
     attr_reader :severity, :message
 
     def initialize(severity, message)
       @severity = severity
-      @message = message
+      @message  = message
+    end
+
+    def to_s
+      "[#{severity.to_s.upcase}] #{message}"
     end
   end
 
   class SuggestionEngine
     def initialize(explain_output, sql = nil)
       @explain_output = explain_output
-      @sql = sql
+      @sql            = sql
     end
 
     def analyze
-      suggestions = []
+      warnings       = []
+      total_cost     = nil
+      rows_estimate  = nil
+      actual_time    = nil
 
-      # Rule 1: Sequential Scan
-      if @explain_output.match?(/Seq Scan/i)
-        suggestions << Suggestion.new(:critical, "⚡ Sequential Scan detected. Consider adding indexes to avoid full table scans.")
-      end
+      # Build the full plan text (all lines) so advisors can see Filters, etc.
+      full_plan = @explain_output.map { |row| row["QUERY PLAN"] }.join("\n")
 
-      # Rule 2: SELECT *
-      if @sql&.match?(/select\s+\*/i)
-        suggestions << Suggestion.new(:warning, "🚨 Query uses SELECT *. Selecting only needed columns is more efficient.")
-      end
+      @explain_output.each_with_index do |row, idx|
+        line = row["QUERY PLAN"]
 
-      # Rule 3: Sort operation
-      if @explain_output.match?(/Sort/i)
-        suggestions << Suggestion.new(:info, "📈 Sort detected. Consider adding an index to support ORDER BY.")
-      end
+        # Capture cost & estimates
+        if line =~ /cost=\d+\.\d+\.\.(\d+\.\d+) rows=(\d+)/
+          total_cost    = $1.to_f
+          rows_estimate = $2.to_i
+        end
+        actual_time ||= $1.to_f if line =~ /actual time=(\d+\.\d+)/
 
-      # Rule 4: Missing JOIN conditions
-      if @sql&.match?(/join/i) && !@sql.match?(/on/i)
-        suggestions << Suggestion.new(:critical, "⚡ JOIN without ON detected. May cause massive row combinations (CROSS JOIN).")
-      end
+        SuggestionRules.all.each do |rule|
+          next unless rule[:matcher].call(line)
+
+          suggestion = Suggestion.new(rule[:severity], rule[:message])
+          if rule[:message].include?("Sequential Scan")
+            dynamic = SequentialScanAdvisor.new(full_plan).enhanced_message
+            suggestion = Suggestion.new(rule[:severity], dynamic) if dynamic
+          end
 
-      # Rule 5: High Rows estimation
-      if @explain_output.match?(/rows=(\d+)/)
-        rows = @explain_output.match(/rows=(\d+)/)[1].to_i
-        if rows > 100_000
-          suggestions << Suggestion.new(:critical, "🔥 High number of rows (#{rows}). Consider using WHERE conditions or LIMIT.")
+          warnings << {
+            line_number: idx + 1,
+            line_text:   line,
+            suggestion:  suggestion
+          }
         end
       end
 
-      suggestions
+      warnings.concat(SqlLevelRules.evaluate(@sql))
+
+      presenter = QueryPlanPresenter.new(
+        output:        @explain_output.map { |r| r["QUERY PLAN"] },
+        warnings:      warnings,
+        total_cost:    total_cost,
+        rows_estimate: rows_estimate,
+        actual_time:   actual_time
+      )
+
+      presenter.display
+      QueryPlanPresenter.classify_cost(total_cost)
     end
   end
 end

data/lib/sql_query_analyzer/suggestion_rules.rb

@@ -0,0 +1,43 @@
+module SqlQueryAnalyzer
+  class SuggestionRules
+    def self.all
+      [
+        {
+          matcher: ->(line) { line.include?('Seq Scan') },
+          severity: :critical,
+          message: "⚡ Sequential Scan detected. Add appropriate indexes to avoid full table scans."
+        },
+        {
+          matcher: ->(line) { line.include?('Nested Loop') },
+          severity: :warning,
+          message: "🌀 Nested Loop detected. Ensure JOINs are optimized and indexed."
+        },
+        {
+          matcher: ->(line) { line.include?('Bitmap Heap Scan') },
+          severity: :info,
+          message: "📦 Bitmap Heap Scan used. Acceptable but check if an index-only scan is possible."
+        },
+        {
+          matcher: ->(line) { line.include?('Materialize') },
+          severity: :warning,
+          message: "📄 Materialize detected. May cause extra memory usage if result sets are large."
+        },
+        {
+          matcher: ->(line) { line.include?('Hash Join') },
+          severity: :info,
+          message: "🔗 Hash Join used. Generally fast for large datasets, but check hash table memory usage."
+        },
+        {
+          matcher: ->(line) { line.include?('Merge Join') },
+          severity: :info,
+          message: "🔀 Merge Join used. Efficient if input is sorted properly; check indexes."
+        },
+        {
+          matcher: ->(line) { line&.match?(/^\s*WITH\s+\w+\s+AS\s*\(/i) },
+          severity: :info,
+          message: "🔧 CTE usage detected. Be aware CTEs can materialize (costly) in Postgres < 12."
+        }
+      ]
+    end
+  end
+end

data/lib/sql_query_analyzer/version.rb

@@ -1,5 +1,5 @@
 # lib/sql_query_analyzer/version.rb
 module SqlQueryAnalyzer
   
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/sql_query_analyzer.rb

@@ -5,6 +5,8 @@ require "active_record"
 require "sql_query_analyzer/version"
 require "sql_query_analyzer/suggestion_engine"
 require "sql_query_analyzer/explain_analyzer"
+require "sql_query_analyzer/execute"
+require "sql_query_analyzer/sequential_scan_advisor"
 
 module SqlQueryAnalyzer
   # Future configurations can go here

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: sql_query_analyzer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Anoob Bava
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-04-28 00:00:00.000000000 Z
+date: 2025-04-29 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -33,8 +61,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/sql_query_analyzer.rb
+- lib/sql_query_analyzer/execute.rb
 - lib/sql_query_analyzer/explain_analyzer.rb
+- lib/sql_query_analyzer/query_plan_presenter.rb
+- lib/sql_query_analyzer/sequential_scan_advisor.rb
+- lib/sql_query_analyzer/sql_level_rules.rb
 - lib/sql_query_analyzer/suggestion_engine.rb
+- lib/sql_query_analyzer/suggestion_rules.rb
 - lib/sql_query_analyzer/version.rb
 homepage: https://github.com/anoobbava/sql_query_analyzer
 licenses: