sql_query_analyzer 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de53885b50c1f9d62d98d6713ac536f29b30ebdada947a54bde86610cbc594f2
-  data.tar.gz: 3211b01b3d49e290bb9a7724a3527602b6a80c3cd2d9b7416160967885c6b7dc
+  metadata.gz: dc77c3595765e78f3b480fff180bc02c3a075466decb48a3b97e01c32be36f5c
+  data.tar.gz: 157c99237424e4cdc85f01c1dc93b3aefab554f3052c09e860fceaa58417b2fe
 SHA512:
-  metadata.gz: 8bbd2f6b1c5cc37034909e5f4a7e24aefc77e2d7d5719ee0d2d5908873249a01ba6ec9d32641658d0d316119ca9b30ce1da0cfbf31d43db02b49930321a92288
-  data.tar.gz: 2c016cca40185f82db401a0a582f5746c15072d6726ebcf7f6ad4e2ff228aecff6e863c00a08ff1da0dce5c7b43d9549e3b047dded9da5255af6f77b0576396c
+  metadata.gz: 8224852f6757433d6b44813b96addc97cca6e9d5457c751444f6c8d9c6b7ac0c7220767ba9ad1b2b5ff342892f221841a81edc1c0ae44efe56ebe3ff29ff249d
+  data.tar.gz: 46d9cb2b4d207de95c7a1d574676c321b9220f128095d5d824e8f2eccd21a53f72eb9b5926e9709309abc0baf55ee65537ad5fc6b0ab5c1b89d2162f0f50f867

data/lib/sql_query_analyzer/execute.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 module SqlQueryAnalyzer
+  # Executes EXPLAIN queries on the database
   class Execute
     def self.explain_sql(raw_sql, run)
       query_with_options = run ? "EXPLAIN ANALYZE #{raw_sql}" : "EXPLAIN #{raw_sql}"

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(run: false)
-
-      unless self.is_a?(ActiveRecord::Relation)
-        puts "⚠️ Not an ActiveRecord Relation. Skipping explain_with_suggestions."
-        return
+      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, 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,4 +1,7 @@
+# frozen_string_literal: true
+
 module SqlQueryAnalyzer
+  # Analyzes sequential scans and provides enhanced messaging and index suggestions
   class SequentialScanAdvisor
     attr_reader :query_plan
 
@@ -13,8 +16,8 @@ module SqlQueryAnalyzer
 
       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."
+               'but no filter condition found. Likely a full table read ' \
+               '(e.g., SELECT *), or small table size makes index use unnecessary.'
       end
 
       messages = []
@@ -29,47 +32,47 @@ module SqlQueryAnalyzer
     private
 
     def sequential_scan_detected?
-      query_plan.include?("Seq Scan on")
+      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 ]
+      [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:") }
+      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
+                .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)
+                    .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
+      schema_cols.select { |col| cleaned.include?(col) }.uniq
     end
 
     def missing_composite_index?(table_name, columns)
       existing = ActiveRecord::Base
-                   .connection
-                   .indexes(table_name.to_sym)
-                   .map(&:columns)
-                   .map { |cols| cols.map(&:downcase) }
+                 .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 }
+      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,9 +1,12 @@
+# 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
 
@@ -17,6 +20,7 @@ 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
@@ -30,31 +34,31 @@ module SqlQueryAnalyzer
       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")
+      full_plan = @explain_output.map { |row| row['QUERY PLAN'] }.join("\n")
 
       @explain_output.each_with_index do |row, idx|
-        line = row["QUERY PLAN"]
+        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|
           next unless rule[:matcher].call(line)
 
-          suggestion = Suggestion.new(rule[:severity], rule[:message])
-          if rule[:message].include?("Sequential Scan")
+          message = rule[:message]
+          if rule[:message].include?('Sequential Scan')
             dynamic = SequentialScanAdvisor.new(full_plan).enhanced_message
-            suggestion = Suggestion.new(rule[:severity], dynamic) if dynamic
+            message = dynamic unless dynamic.nil?
           end
 
           warnings << {
             line_number: idx + 1,
-            line_text:   line,
-            suggestion:  suggestion
+            line_text: line,
+            suggestion: Suggestion.new(rule[:severity], message)
           }
         end
       end
@@ -62,15 +66,16 @@ module SqlQueryAnalyzer
       warnings.concat(SqlLevelRules.evaluate(@sql))
 
       presenter = QueryPlanPresenter.new(
-        output:        @explain_output.map { |r| r["QUERY PLAN"] },
-        warnings:      warnings,
-        total_cost:    total_cost,
+        output: @explain_output.map { |r| r['QUERY PLAN'] },
+        warnings: warnings,
+        total_cost: total_cost,
         rows_estimate: rows_estimate,
-        actual_time:   actual_time
+        actual_time: actual_time
       )
 
       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&.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.1"
+  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.1
+  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:
   - - ">="