benedictus 0.2.0

data/lib/benedictus/heuristics/external_sort.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Heuristics
+    class ExternalSort < Base
+      def initialize(**)
+        super()
+      end
+
+      def apply(node)
+        return [] unless node.node_type == "Sort"
+        return [] unless node.sort_method.to_s.include?("external")
+
+        space = if node.sort_space_used
+                  " (#{node.sort_space_used} kB on #{node.sort_space_type || "disk"})"
+                else
+                  ""
+                end
+
+        [
+          warning(
+            severity: :critical,
+            code: :external_sort,
+            message: "Sort spilled to disk via `#{node.sort_method}`#{space}.",
+            suggestion: "Increase `work_mem` or add an index that already orders the data."
+          )
+        ]
+      end
+    end
+  end
+end

data/lib/benedictus/heuristics/nested_loop_blowup.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Heuristics
+    class NestedLoopBlowup < Base
+      DEFAULT_THRESHOLD = 10_000
+
+      def self.config_key
+        :nested_loop_threshold
+      end
+
+      def initialize(threshold: DEFAULT_THRESHOLD)
+        super()
+        @threshold = threshold
+      end
+
+      def apply(node)
+        return [] unless node.node_type == "Nested Loop"
+
+        inner = node.children.find { |c| c.parent_relationship == "Inner" } || node.children.last
+        return [] unless inner&.actual_loops && inner.actual_loops > @threshold
+
+        [
+          warning(
+            severity: :warning,
+            code: :nested_loop_blowup,
+            message: "Nested Loop drove #{inner.actual_loops} iterations on the inner side.",
+            suggestion: "Consider a Hash Join or Merge Join — try increasing `work_mem` or rewriting the join."
+          )
+        ]
+      end
+    end
+  end
+end

data/lib/benedictus/heuristics/registry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Heuristics
+    class Registry
+      DEFAULT_HEURISTICS = [
+        SeqScanOnLargeTable,
+        RowEstimateDrift,
+        ExternalSort,
+        NestedLoopBlowup,
+        ExpensivePerRowScan
+      ].freeze
+
+      def initialize(heuristics = nil, config: {})
+        source = heuristics || DEFAULT_HEURISTICS
+        @heuristics = source.map { |h| instantiate(h, config) }
+      end
+
+      def annotate(tree)
+        tree.each_node do |node|
+          @heuristics.each do |heuristic|
+            node.warnings.concat(heuristic.apply(node))
+          end
+        end
+        tree
+      end
+
+      def self.annotate(tree, config: {})
+        new(config: config).annotate(tree)
+      end
+
+      private
+
+      def instantiate(heuristic, config)
+        return heuristic unless heuristic.is_a?(Class)
+
+        if heuristic.respond_to?(:config_key) && config.key?(key = heuristic.config_key)
+          heuristic.new(threshold: config[key])
+        else
+          heuristic.new
+        end
+      end
+    end
+  end
+end

data/lib/benedictus/heuristics/row_estimate_drift.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Heuristics
+    class RowEstimateDrift < Base
+      DEFAULT_FACTOR = 10
+
+      def self.config_key
+        :drift_factor
+      end
+
+      def initialize(threshold: DEFAULT_FACTOR)
+        super()
+        @factor = threshold
+      end
+
+      def apply(node)
+        return [] unless node.actual_rows && node.plan_rows
+        return [] if node.actual_rows.zero? && node.plan_rows.zero?
+
+        actual = node.actual_rows
+        plan   = [node.plan_rows, 1].max
+        ratio  = [actual.to_f / plan, plan.to_f / [actual, 1].max].max
+
+        return [] if ratio < @factor
+
+        relation = node.relation_name
+        suggestion = relation ? "Run `ANALYZE #{relation}` to refresh planner statistics." : nil
+
+        [
+          warning(
+            severity: :warning,
+            code: :row_estimate_drift,
+            message: "Plan estimated #{plan} rows, actual was #{actual} (#{ratio.round(1)}x drift).",
+            suggestion: suggestion
+          )
+        ]
+      end
+    end
+  end
+end

data/lib/benedictus/heuristics/seq_scan_on_large_table.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Heuristics
+    class SeqScanOnLargeTable < Base
+      DEFAULT_THRESHOLD = 10_000
+
+      def self.config_key
+        :seq_scan_threshold
+      end
+
+      def initialize(threshold: DEFAULT_THRESHOLD)
+        super()
+        @threshold = threshold
+      end
+
+      def apply(node)
+        return [] unless node.node_type == "Seq Scan"
+        return [] unless node.plan_rows && node.plan_rows > @threshold
+
+        relation = node.relation_name || "this table"
+        rows     = node.plan_rows
+        [
+          warning(
+            severity: :critical,
+            code: :seq_scan_on_large_table,
+            message: "Seq Scan on a table with ~#{rows.to_i} estimated rows",
+            suggestion: "Consider adding an index that matches the filter on `#{relation}`."
+          )
+        ]
+      end
+    end
+  end
+end

data/lib/benedictus/heuristics/warning.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Heuristics
+    WARNING_SEVERITIES = %i[info warning critical].freeze
+
+    Warning = Struct.new(:severity, :code, :message, :suggestion, keyword_init: true) do
+      def initialize(*)
+        super
+        return if WARNING_SEVERITIES.include?(severity)
+
+        raise ArgumentError, "severity must be one of #{WARNING_SEVERITIES.inspect}"
+      end
+    end
+  end
+end

data/lib/benedictus/plan/node.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Plan
+    class Node
+      attr_reader :node_type, :relation_name, :alias_name, :index_name,
+                  :startup_cost, :total_cost,
+                  :plan_rows, :plan_width,
+                  :actual_startup_time, :actual_total_time,
+                  :actual_rows, :actual_loops,
+                  :filter, :index_cond, :join_filter, :hash_cond, :recheck_cond,
+                  :sort_method, :sort_key, :sort_space_type, :sort_space_used,
+                  :join_type, :strategy, :parent_relationship, :subplan_name,
+                  :children, :attrs
+
+      attr_accessor :warnings
+
+      def initialize(raw, children: [])
+        @raw                = raw
+        @node_type          = raw["Node Type"]
+        @relation_name      = raw["Relation Name"]
+        @alias_name         = raw["Alias"]
+        @index_name         = raw["Index Name"]
+        @startup_cost       = raw["Startup Cost"]
+        @total_cost         = raw["Total Cost"]
+        @plan_rows          = raw["Plan Rows"]
+        @plan_width         = raw["Plan Width"]
+        @actual_startup_time = raw["Actual Startup Time"]
+        @actual_total_time  = raw["Actual Total Time"]
+        @actual_rows        = raw["Actual Rows"]
+        @actual_loops       = raw["Actual Loops"]
+        @filter             = raw["Filter"]
+        @index_cond         = raw["Index Cond"]
+        @join_filter        = raw["Join Filter"]
+        @hash_cond          = raw["Hash Cond"]
+        @recheck_cond       = raw["Recheck Cond"]
+        @sort_method        = raw["Sort Method"]
+        @sort_key           = raw["Sort Key"]
+        @sort_space_type    = raw["Sort Space Type"]
+        @sort_space_used    = raw["Sort Space Used"]
+        @join_type          = raw["Join Type"]
+        @strategy           = raw["Strategy"]
+        @parent_relationship = raw["Parent Relationship"]
+        @subplan_name       = raw["Subplan Name"]
+        @children           = children
+        @attrs              = raw.reject { |k, _| RECOGNIZED_KEYS.include?(k) || k == "Plans" }
+        @warnings           = []
+      end
+
+      def analyzed?
+        !actual_total_time.nil?
+      end
+
+      def leaf?
+        children.empty?
+      end
+
+      def target
+        return alias_name if alias_name && relation_name && alias_name != relation_name
+
+        relation_name
+      end
+
+      RECOGNIZED_KEYS = [
+        "Node Type", "Relation Name", "Alias", "Index Name",
+        "Startup Cost", "Total Cost", "Plan Rows", "Plan Width",
+        "Actual Startup Time", "Actual Total Time",
+        "Actual Rows", "Actual Loops",
+        "Filter", "Index Cond", "Join Filter", "Hash Cond", "Recheck Cond",
+        "Sort Method", "Sort Key", "Sort Space Type", "Sort Space Used",
+        "Join Type", "Strategy", "Parent Relationship", "Subplan Name"
+      ].freeze
+    end
+  end
+end

data/lib/benedictus/plan/parser.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Plan
+    class Parser
+      class << self
+        def parse(json)
+          data = json.is_a?(String) ? JSON.parse(json) : json
+
+          raise Benedictus::DatabaseError, "EXPLAIN returned an empty result" if data.is_a?(Array) && data.empty?
+
+          envelope = data.is_a?(Array) ? data.first : data
+
+          unless envelope.is_a?(Hash) && envelope["Plan"].is_a?(Hash)
+            raise Benedictus::DatabaseError,
+                  "EXPLAIN output did not contain a top-level 'Plan' object"
+          end
+
+          root = build_node(envelope["Plan"])
+
+          Tree.new(
+            root,
+            planning_time: envelope["Planning Time"],
+            execution_time: envelope["Execution Time"],
+            triggers: envelope["Triggers"] || [],
+            raw: data
+          )
+        end
+
+        private
+
+        def build_node(raw)
+          plans = raw["Plans"]
+          children = plans.is_a?(Array) ? plans.map { |child| build_node(child) } : []
+          Node.new(raw, children: children)
+        end
+      end
+    end
+  end
+end

data/lib/benedictus/plan/tree.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Plan
+    class Tree
+      attr_reader :root, :planning_time, :execution_time, :triggers, :raw
+
+      def initialize(root, planning_time: nil, execution_time: nil, triggers: [], raw: nil)
+        @root           = root
+        @planning_time  = planning_time
+        @execution_time = execution_time
+        @triggers       = triggers
+        @raw            = raw
+      end
+
+      def each_node(&block)
+        return enum_for(:each_node) unless block
+
+        traverse(root, &block)
+      end
+
+      def total_cost
+        root.total_cost
+      end
+
+      def total_time
+        return execution_time if execution_time
+
+        root.actual_total_time
+      end
+
+      def analyzed?
+        root.analyzed?
+      end
+
+      def total_rows
+        root.actual_rows || root.plan_rows
+      end
+
+      def warnings
+        each_node.flat_map(&:warnings)
+      end
+
+      private
+
+      def traverse(node, &block)
+        block.call(node)
+        node.children.each { |child| traverse(child, &block) }
+      end
+    end
+  end
+end

data/lib/benedictus/plan_runner.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Benedictus
+  class PlanRunner
+    def self.call(**kwargs)
+      new(**kwargs).call
+    end
+
+    def initialize(relation:, analyze: false, buffers: false, verbose: false, format: "JSON")
+      @relation = relation
+      @analyze  = analyze
+      @buffers  = buffers
+      @verbose  = verbose
+      @format   = format
+    end
+
+    def call
+      reject_raw_sql_adapter_under_analyze!
+
+      sql = @relation.to_sql
+      Benedictus::SafetyGuard.assert_select!(sql) if @analyze
+
+      explain_sql = "EXPLAIN (#{options_string}) #{sql}"
+
+      if @analyze
+        Benedictus::SafetyGuard.with_rollback(@relation.klass) { execute(explain_sql) }
+      else
+        execute(explain_sql)
+      end
+    rescue StandardError => e
+      raise if e.is_a?(Benedictus::Error)
+
+      raise Benedictus::DatabaseError, "EXPLAIN failed: #{e.class}: #{e.message}"
+    end
+
+    private
+
+    def reject_raw_sql_adapter_under_analyze!
+      return unless @analyze
+      return unless defined?(Benedictus::RelationResolver::RawSqlAdapter)
+      return unless @relation.is_a?(Benedictus::RelationResolver::RawSqlAdapter)
+
+      raise Benedictus::UnsafeQueryError,
+            "--analyze cannot be used with raw SQL strings; pass an ActiveRecord::Relation."
+    end
+
+    def options_string
+      opts = []
+      opts << "ANALYZE" if @analyze
+      opts << "BUFFERS" if @buffers && @analyze
+      opts << "VERBOSE" if @verbose
+      opts << "FORMAT #{@format}"
+      opts.join(", ")
+    end
+
+    def execute(sql)
+      result = @relation.klass.connection.exec_query(sql)
+      return result if @format != "JSON"
+
+      payload = extract_json_payload(result)
+      JSON.parse(payload)
+    end
+
+    def extract_json_payload(result)
+      rows = result.respond_to?(:rows) ? result.rows : result
+      first = Array(rows).first
+      first = first.first if first.is_a?(Array)
+      first
+    end
+  end
+end

data/lib/benedictus/rails_loader.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Benedictus
+  class RailsLoader
+    ENV_VAR = "BENEDICTUS_RAILS_ENV"
+
+    def self.load!(start_dir: Dir.pwd)
+      new(start_dir: start_dir).load!
+    end
+
+    def initialize(start_dir: Dir.pwd)
+      @start_dir = File.expand_path(start_dir)
+    end
+
+    def load!
+      ENV["RAILS_ENV"] ||= ENV[ENV_VAR] || "development"
+
+      env_path = locate_environment_rb
+      require env_path
+      env_path
+    end
+
+    private
+
+    def locate_environment_rb
+      dir = @start_dir
+      loop do
+        candidate = File.join(dir, "config", "environment.rb")
+        return candidate if File.file?(candidate)
+
+        parent = File.dirname(dir)
+        break if parent == dir
+
+        dir = parent
+      end
+
+      raise Benedictus::RailsNotFoundError,
+            "Could not find config/environment.rb above #{@start_dir}. Run benedictus from inside a Rails application."
+    end
+  end
+end

data/lib/benedictus/relation_resolver.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Benedictus
+  class RelationResolver
+    MAX_DEPTH = 5
+
+    class RawSqlAdapter
+      attr_reader :sql
+
+      def initialize(sql)
+        @sql = sql
+      end
+
+      def to_sql
+        @sql
+      end
+
+      def klass
+        defined?(ActiveRecord::Base) ? ActiveRecord::Base : nil
+      end
+    end
+
+    def self.call(value)
+      new.call(value)
+    end
+
+    def call(value, depth: 0)
+      raise UnresolvableExpression, "exceeded resolution depth (#{MAX_DEPTH})" if depth > MAX_DEPTH
+
+      return value if active_record_relation?(value)
+      return call(value.call, depth: depth + 1) if value.respond_to?(:call)
+      return call(value.to_relation, depth: depth + 1) if value.respond_to?(:to_relation)
+      return RawSqlAdapter.new(value.to_sql) if value.respond_to?(:to_sql)
+
+      raise UnresolvableExpression,
+            "Expression returned a #{value.class}; expected an ActiveRecord::Relation " \
+            "or something responding to .to_sql."
+    end
+
+    private
+
+    def active_record_relation?(value)
+      defined?(ActiveRecord::Relation) && value.is_a?(ActiveRecord::Relation)
+    end
+  end
+end

data/lib/benedictus/renderers/json_renderer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Renderers
+    class JsonRenderer
+      def initialize(plan_data)
+        @plan_data = plan_data
+      end
+
+      def render
+        JSON.pretty_generate(@plan_data)
+      end
+    end
+  end
+end

data/lib/benedictus/renderers/raw_renderer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Benedictus
+  module Renderers
+    class RawRenderer
+      def initialize(result)
+        @result = result
+      end
+
+      def render
+        rows = @result.respond_to?(:rows) ? @result.rows : @result
+        Array(rows).flatten.join("\n")
+      end
+    end
+  end
+end