sql_query_analyzer 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 584bbafae1893ed4f45410cc46eafe6e120e98990205b6843f2e82cc9dd3b9f0
-  data.tar.gz: fe27bac5ebe7e38cc961c6abdffa5fc2bf0eef37f97864cd8ed23a7cb1599d70
+  metadata.gz: dc77c3595765e78f3b480fff180bc02c3a075466decb48a3b97e01c32be36f5c
+  data.tar.gz: 157c99237424e4cdc85f01c1dc93b3aefab554f3052c09e860fceaa58417b2fe
 SHA512:
-  metadata.gz: 893727f91285119c0734f23f76e594f5f5085041cdbe9e3f750f785791de417a23f2b44c8f1f4a1b5392dc605e23b26d35acfe4c675f3ea93a089be6157e4711
-  data.tar.gz: e703a05ad2758df8b778bd872b2f6eecffe05855c7f48a2a603ddbe34ed17d5914b8eef67aed3491d44c0e5843099d47d3e6783fbb5b590b15ac7ad83bb149f3
+  metadata.gz: 8224852f6757433d6b44813b96addc97cca6e9d5457c751444f6c8d9c6b7ac0c7220767ba9ad1b2b5ff342892f221841a81edc1c0ae44efe56ebe3ff29ff249d
+  data.tar.gz: 46d9cb2b4d207de95c7a1d574676c321b9220f128095d5d824e8f2eccd21a53f72eb9b5926e9709309abc0baf55ee65537ad5fc6b0ab5c1b89d2162f0f50f867

data/lib/sql_query_analyzer/execute.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 module SqlQueryAnalyzer
+  # Executes EXPLAIN queries on the database
   class Execute
-    def self.explain_sql(raw_sql)
-      ActiveRecord::Base.connection.execute("EXPLAIN ANALYZE #{raw_sql}")
+    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,22 +1,23 @@
+# frozen_string_literal: true
+
 # lib/sql_query_analyzer/explain_analyzer.rb
 module SqlQueryAnalyzer
+  # Module that adds explain_with_suggestions method to ActiveRecord::Relation
   module ExplainAnalyzer
-    def explain_with_suggestions
-
-      unless self.is_a?(ActiveRecord::Relation)
-        puts "⚠️ Not an ActiveRecord Relation. Skipping explain_with_suggestions."
-        return
+    def explain_with_suggestions(run: false)
+      unless is_a?(ActiveRecord::Relation)
+        puts '⚠️ Not an ActiveRecord Relation. Skipping explain_with_suggestions.'
+        return nil
       end
 
-      raw_sql = self.to_sql
+      raw_sql = to_sql
 
-      explain_output = SqlQueryAnalyzer::Execute.explain_sql(raw_sql)
+      explain_output = SqlQueryAnalyzer::Execute.explain_sql(raw_sql, run)
       engine = SqlQueryAnalyzer::SuggestionEngine.new(explain_output, raw_sql)
-      suggestions = engine.analyze
-
-      nil
-    rescue => e
+      engine.analyze
+    rescue StandardError => e
       puts "Error analyzing query: #{e.message}"
+      nil
     end
   end
 end

data/lib/sql_query_analyzer/query_plan_presenter.rb

@@ -1,54 +1,69 @@
+# frozen_string_literal: true
+
 require 'pastel'
 
 module SqlQueryAnalyzer
+  # Presents query plan output with colored formatting and suggestions
   class QueryPlanPresenter
-    def initialize(output:, warnings:, total_cost:, rows_estimate:, actual_time:)
+    def initialize(output:, warnings:, total_cost:, rows_estimate:, actual_time:, output_stream: $stdout)
       @output = output
       @warnings = warnings
       @total_cost = total_cost
       @rows_estimate = rows_estimate
       @actual_time = actual_time
       @pastel = Pastel.new
+      @output_stream = output_stream
     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
+      display_query_plan
+      display_metrics
+      display_warnings_or_success
     end
 
-    def self.classify_cost(cost)
+    def self.classify_cost(cost, output_stream: $stdout)
       return unless cost
+
       pastel = Pastel.new
 
       case cost
       when 0..300
-        puts pastel.green("\n✅ Query cost is LOW. All good!")
+        output_stream.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.")
+        output_stream.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!")
+        output_stream.puts pastel.red.bold("\n🛑 Query cost is HIGH. Recommend tuning immediately!")
       end
     end
 
     private
 
+    def display_query_plan
+      @output_stream.puts @pastel.bold("\n🔍 QUERY PLAN:")
+      @output.each_with_index do |line, idx|
+        @output_stream.puts "  #{@pastel.cyan("#{idx + 1}:")} #{line}"
+      end
+    end
+
+    def display_metrics
+      @output_stream.puts @pastel.bold("\n📊 Query Metrics:")
+      @output_stream.puts "  💰 Total Cost: #{@pastel.green(@total_cost)}" if @total_cost
+      @output_stream.puts "  📈 Rows Estimate: #{@pastel.blue(@rows_estimate)}" if @rows_estimate
+      @output_stream.puts "  ⏱️  Actual Time: #{@pastel.magenta("#{@actual_time} ms")}" if @actual_time
+    end
+
+    def display_warnings_or_success
+      if @warnings.any?
+        @output_stream.puts @pastel.bold("\n🚩 Warnings and Suggestions:")
+        @warnings.each do |warn|
+          @output_stream.puts "  #{@pastel.yellow("Line #{warn[:line_number]}:")} #{warn[:line_text]}"
+          @output_stream.puts "    👉 #{colorize_by_severity(warn[:suggestion])}"
+        end
+      else
+        @output_stream.puts @pastel.green("\n✅ No immediate problems detected in the query plan.")
+      end
+    end
+
     def colorize_by_severity(suggestion)
       case suggestion.severity
       when :critical

data/lib/sql_query_analyzer/sequential_scan_advisor.rb

@@ -1,54 +1,78 @@
+# frozen_string_literal: true
+
 module SqlQueryAnalyzer
+  # Analyzes sequential scans and provides enhanced messaging and index suggestions
   class SequentialScanAdvisor
-    def initialize(line_text)
-      @line_text = line_text
+    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 table_name
 
-      if column_names.empty?
-        return "⚡ 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
+      return nil unless sequential_scan_detected?
 
-      missing_indexes = column_names.select do |column|
-        !index_exists?(table_name, column)
+      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
 
-      if missing_indexes.any?
-        "⚡ Sequential Scan detected on '#{table_name}'. Consider adding indexes on: #{missing_indexes.join(', ')}."
-      else
-        "⚡ Sequential Scan detected on '#{table_name}', but indexes seem to exist. Might be due to low table size or outdated stats."
+      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
-      # Simplified pattern: "Seq Scan on users  (cost=...)"
-      if @line_text =~ /Seq Scan on (\w+)/
-        table_name = $1
-        columns = extract_filter_columns(@line_text)
-        [table_name, columns]
-      else
-        [nil, []]
-      end
+      table_name = query_plan.match(/Seq Scan on (\w+)/)&.captures&.first
+      [table_name, extract_columns_from_filter]
     end
 
-    def extract_filter_columns(text)
-      # Example EXPLAIN line might include: "Filter: (email = 'x')"
-      text.scan(/Filter: \((.*?)\)/).flatten
-          .flat_map { |f| f.scan(/\b(\w+)\s*=/) }
-          .flatten
+    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
+      schema_cols.select { |col| cleaned.include?(col) }.uniq
     end
 
-    def index_exists?(table_name, column)
-      ActiveRecord::Base.connection.indexes(table_name).any? do |idx|
-        idx.columns.include?(column)
-      end
-    rescue => e
-      false # Assume false in case of table missing or dev env differences
+    def missing_composite_index?(table_name, columns)
+      existing = ActiveRecord::Base
+                 .connection
+                 .indexes(table_name.to_sym)
+                 .map(&:columns)
+                 .map { |cols| cols.map(&:downcase) }
+
+      existing.none? { |idx_cols| idx_cols == columns || idx_cols.first(columns.length) == columns }
     end
   end
 end

data/lib/sql_query_analyzer/sql_level_rules.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 module SqlQueryAnalyzer
+  # Evaluates SQL-level rules like SELECT * and JOIN without ON
   class SqlLevelRules
     def self.evaluate(sql)
       return [] unless sql
@@ -9,7 +12,7 @@ module SqlQueryAnalyzer
         warnings << {
           line_number: 'N/A',
           line_text: 'SELECT *',
-          suggestion: Suggestion.new(:warning, "🚨 Query uses SELECT *. Specify only needed columns for performance.")
+          suggestion: Suggestion.new(:warning, '🚨 Query uses SELECT *. Specify only needed columns for performance.')
         }
       end
 
@@ -17,7 +20,8 @@ module SqlQueryAnalyzer
         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).")
+          suggestion: Suggestion.new(:critical,
+                                     '⚡ JOIN without ON detected. May cause massive row combinations (CROSS JOIN).')
         }
       end
 

data/lib/sql_query_analyzer/suggestion_engine.rb

@@ -1,14 +1,18 @@
+# frozen_string_literal: true
+
 require_relative 'suggestion_rules'
 require_relative 'query_plan_presenter'
 require_relative 'sql_level_rules'
+require_relative 'sequential_scan_advisor'
 
 module SqlQueryAnalyzer
+  # Represents a single suggestion with severity and message
   class Suggestion
     attr_reader :severity, :message
 
     def initialize(severity, message)
       @severity = severity
-      @message = message
+      @message  = message
     end
 
     def to_s
@@ -16,50 +20,53 @@ module SqlQueryAnalyzer
     end
   end
 
+  # Main engine that analyzes EXPLAIN output and generates suggestions
   class SuggestionEngine
     def initialize(explain_output, sql = nil)
       @explain_output = explain_output
-      @sql = sql
+      @sql            = sql
     end
 
     def analyze
-      output = []
-      warnings = []
-      total_cost, rows_estimate, actual_time = nil
+      warnings       = []
+      total_cost     = nil
+      rows_estimate  = nil
+      actual_time    = nil
+
+      # Build the full plan text (all lines) so advisors can see Filters, etc.
+      full_plan = @explain_output.map { |row| row['QUERY PLAN'] }.join("\n")
 
       @explain_output.each_with_index do |row, idx|
-        line = row["QUERY PLAN"]
-        output << line
+        line = row['QUERY PLAN']
 
+        # Capture cost & estimates
         if line =~ /cost=\d+\.\d+\.\.(\d+\.\d+) rows=(\d+)/
-          total_cost = $1.to_f
-          rows_estimate = $2.to_i
+          total_cost    = ::Regexp.last_match(1).to_f
+          rows_estimate = ::Regexp.last_match(2).to_i
         end
-
-        actual_time ||= $1.to_f if line =~ /actual time=(\d+\.\d+)/
+        actual_time ||= ::Regexp.last_match(1).to_f if line =~ /actual time=(\d+\.\d+)/
 
         SuggestionRules.all.each do |rule|
-          if rule[:matcher].call(line)
+          next unless rule[:matcher].call(line)
 
-            suggestion = Suggestion.new(rule[:severity], rule[:message])
-            if rule[:message].include?("Sequential Scan")
-              dynamic_msg = SequentialScanAdvisor.new(line).enhanced_message
-              suggestion = Suggestion.new(rule[:severity], dynamic_msg) if dynamic_msg
-            end
-
-            warnings << {
-              line_number: idx + 1,
-              line_text: line,
-              suggestion: suggestion
-            }
+          message = rule[:message]
+          if rule[:message].include?('Sequential Scan')
+            dynamic = SequentialScanAdvisor.new(full_plan).enhanced_message
+            message = dynamic unless dynamic.nil?
           end
+
+          warnings << {
+            line_number: idx + 1,
+            line_text: line,
+            suggestion: Suggestion.new(rule[:severity], message)
+          }
         end
       end
 
       warnings.concat(SqlLevelRules.evaluate(@sql))
 
       presenter = QueryPlanPresenter.new(
-        output: output,
+        output: @explain_output.map { |r| r['QUERY PLAN'] },
         warnings: warnings,
         total_cost: total_cost,
         rows_estimate: rows_estimate,
@@ -68,6 +75,7 @@ module SqlQueryAnalyzer
 
       presenter.display
       QueryPlanPresenter.classify_cost(total_cost)
+      warnings
     end
   end
 end

data/lib/sql_query_analyzer/suggestion_rules.rb

@@ -1,41 +1,44 @@
+# frozen_string_literal: true
+
 module SqlQueryAnalyzer
+  # Contains rules for matching query plan patterns and generating suggestions
   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."
+          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."
+          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."
+          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."
+          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."
+          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."
+          message: '🔀 Merge Join used. Efficient if input is sorted properly; check indexes.'
         },
         {
-          matcher: ->(line) { line.downcase.include?('cte') || line.downcase.include?('with') },
+          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."
+          message: '🔧 CTE usage detected. Be aware CTEs can materialize (costly) in Postgres < 12.'
         }
       ]
     end

data/lib/sql_query_analyzer/version.rb

@@ -1,5 +1,6 @@
+# frozen_string_literal: true
+
 # lib/sql_query_analyzer/version.rb
 module SqlQueryAnalyzer
-  
-  VERSION = "0.2.0"
+  VERSION = '0.3.0'
 end

data/lib/sql_query_analyzer.rb

@@ -1,13 +1,16 @@
+# frozen_string_literal: true
+
 # lib/sql_query_analyzer.rb
-require "active_support"
-require "active_record"
+require 'active_support/all'
+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"
+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'
 
+# Main module for SQL Query Analyzer gem
 module SqlQueryAnalyzer
   # Future configurations can go here
 end

metadata

@@ -1,15 +1,69 @@
 --- !ruby/object:Gem::Specification
 name: sql_query_analyzer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Anoob Bava
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-04-29 00:00:00.000000000 Z
+date: 2025-09-09 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: pastel
   requirement: !ruby/object:Gem::Requirement
@@ -28,16 +82,22 @@ dependencies:
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +112,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 description: A Ruby on Rails gem that analyzes SQL queries and suggests optimizations
   like missing indexes, inefficient sorts, and risky joins.
 email:
@@ -72,7 +146,8 @@ files:
 homepage: https://github.com/anoobbava/sql_query_analyzer
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -81,7 +156,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="