query_guard 0.4.1 → 0.5.0

data/lib/query_guard/explain/plan_signals.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Explain
+    # Data structures for query plan signals extracted from EXPLAIN output.
+    # These immutable objects represent actionable insights from actual query plans.
+
+    # Represents a single node in the query plan tree
+    class PlanNode
+      attr_reader :node_type, :relation_name, :depth, :estimated_rows,
+                  :estimated_cost, :actual_rows, :actual_duration_ms,
+                  :children, :filter, :index_name, :sort_key
+
+      def initialize(data, depth = 0)
+        @raw_data = data
+        @node_type = data.dig("Node Type") || "Unknown"  # Seq Scan, Index Scan, etc.
+        @relation_name = data.dig("Relation Name")       # users, orders, etc.
+        @index_name = data.dig("Index Name")             # idx_users_email, etc.
+        @depth = depth
+
+        # Estimated metrics (from planner)
+        @estimated_rows = data.dig("Estimated Rows") || 0
+        @estimated_cost = data.dig("Total Cost") || 0.0
+
+        # Actual metrics (only with ANALYZE)
+        @actual_rows = data.dig("Actual Rows")
+        @actual_duration_ms = data.dig("Actual Total Time")
+
+        # Plan details
+        @filter = data.dig("Filter")                      # WHERE condition
+        @sort_key = data.dig("Sort Key")                  # ORDER BY clause
+
+        # Recursively process child plans
+        child_plans = data.dig("Plans") || []
+        @children = child_plans.map { |child| PlanNode.new(child, depth + 1) }
+      end
+
+      # Check if this node performs a sequential scan
+      #
+      # @return [Boolean]
+      def sequential_scan?
+        node_type == "Seq Scan"
+      end
+
+      # Check if this node uses an index
+      #
+      # @return [Boolean]
+      def index_scan?
+        node_type.include?("Index")
+      end
+
+      # Find all sequential scans in plan tree
+      #
+      # @return [Array<PlanNode>]
+      def sequential_scans
+        scans = sequential_scan? ? [self] : []
+        children.each { |child| scans.concat(child.sequential_scans) }
+        scans
+      end
+
+      # Find all nodes of given type
+      #
+      # @param type [String] Node type to search for
+      # @return [Array<PlanNode>]
+      def nodes_of_type(type)
+        nodes = node_type == type ? [self] : []
+        children.each { |child| nodes.concat(child.nodes_of_type(type)) }
+        nodes
+      end
+
+      # Estimate quality: ratio of actual vs estimated rows
+      # Returns nil if no actual execution data
+      #
+      # @return [Float, nil] Actual rows / Estimated rows (or nil)
+      def estimate_accuracy_ratio
+        return nil if actual_rows.nil? || estimated_rows.zero?
+
+        (actual_rows.to_f / estimated_rows).round(2)
+      end
+
+      # Check if estimates were wildly inaccurate
+      #
+      # @param threshold [Float] How many times off is "bad"? (default 10x)
+      # @return [Boolean]
+      def estimate_inaccurate?(threshold = 10)
+        ratio = estimate_accuracy_ratio
+        return false if ratio.nil?
+
+        ratio > threshold || ratio < (1.0 / threshold)
+      end
+
+      # Human-readable node description
+      #
+      # @return [String]
+      def to_s
+        parts = [node_type]
+        parts << "on #{relation_name}" if relation_name
+        parts << "using #{index_name}" if index_name
+        parts.join(" ")
+      end
+
+      # Convert to hash for serialization
+      #
+      # @return [Hash]
+      def to_h
+        {
+          node_type: node_type,
+          relation_name: relation_name,
+          index_name: index_name,
+          depth: depth,
+          estimated_rows: estimated_rows,
+          estimated_cost: estimated_cost,
+          actual_rows: actual_rows,
+          actual_duration_ms: actual_duration_ms,
+          is_sequential_scan: sequential_scan?,
+          is_index_scan: index_scan?,
+          estimate_friendly: estimate_accuracy_ratio,
+          children: children.map(&:to_h)
+        }
+      end
+    end
+
+    # Complete query plan and extracted signals
+    class QueryPlan
+      attr_reader :root_node, :planning_time_ms, :execution_time_ms, :triggers
+
+      def initialize(explain_output)
+        @raw_output = explain_output
+
+        # Top-level metrics
+        @planning_time_ms = explain_output.dig("Planning Time") || 0
+        @execution_time_ms = explain_output.dig("Execution Time") || 0
+        @triggers = explain_output.dig("Triggers") || []
+
+        # Root plan node
+        @root_node = PlanNode.new(explain_output.dig("Plan") || {})
+      end
+
+      # Extract all sequential scans from entire plan tree
+      #
+      # @return [Array<PlanNode>]
+      def sequential_scans
+        root_node.sequential_scans
+      end
+
+      # Find specific relation scans
+      #
+      # @param table_name [String] Table to find scans for
+      # @return [Array<PlanNode>]
+      def scans_for_table(table_name)
+        root_node.nodes_of_type("Seq Scan")
+          .select { |node| node.relation_name == table_name }
+      end
+
+      # Check if plan uses any indexes
+      #
+      # @return [Boolean]
+      def uses_indexes?
+        root_node.nodes_of_type("Index Scan").any? ||
+          root_node.nodes_of_type("Bitmap Index Scan").any? ||
+          root_node.nodes_of_type("Index Only Scan").any?
+      end
+
+      # Total estimated cost of query
+      #
+      # @return [Float]
+      def total_estimated_cost
+        root_node.estimated_cost
+      end
+
+      # Convert to hash for serialization
+      #
+      # @return [Hash]
+      def to_h
+        {
+          planning_time_ms: planning_time_ms,
+          execution_time_ms: execution_time_ms,
+          total_estimated_cost: total_estimated_cost,
+          has_sequential_scans: sequential_scans.any?,
+          sequential_scan_count: sequential_scans.length,
+          uses_indexes: uses_indexes?,
+          root_node: root_node.to_h
+        }
+      end
+    end
+
+    # Actionable signals extracted from query plan
+    class PlanSignals
+      attr_reader :plan, :signals, :extracted_at
+
+      def initialize(plan)
+        @plan = plan
+        @extracted_at = Time.now
+        @signals = extract_signals
+      end
+
+      # All extracted signals as array
+      #
+      # @return [Array<Hash>]
+      def to_a
+        signals
+      end
+
+      # Find signals of specific type
+      #
+      # @param type [String] Signal type
+      # @return [Array<Hash>]
+      def signals_of_type(type)
+        signals.select { |s| s[:type] == type }
+      end
+
+      # Get most critical signals
+      #
+      # @param severity [Symbol] :high, :medium, :low
+      # @return [Array<Hash>]
+      def critical_signals(severity = :high)
+        signals.select { |s| s[:severity] == severity }
+      end
+
+      # Convert to hash for serialization
+      #
+      # @return [Hash]
+      def to_h
+        {
+          plan: plan.to_h,
+          signals: signals,
+          extracted_at: extracted_at
+        }
+      end
+
+      private
+
+      def extract_signals
+        signals = []
+
+        # Signal: Sequential scans on large tables
+        sequential_scans.each do |scan|
+          signals << {
+            type: :sequential_scan,
+            severity: :high,
+            table: scan.relation_name,
+            estimated_rows: scan.estimated_rows,
+            message: "Sequential scan on #{scan.relation_name} (#{scan.estimated_rows} estimated rows)",
+            recommendation: "Consider adding an index to support query predicates"
+          }
+        end
+
+        # Signal: Missing indexes (likely)
+        plan.root_node.nodes_of_type("Seq Scan").each do |scan|
+          if scan.filter && !plan.scans_for_table(scan.relation_name).any? { |s| s.index_scan? }
+            signals << {
+              type: :likely_missing_index,
+              severity: :high,
+              table: scan.relation_name,
+              filter: scan.filter,
+              message: "Sequential scan with filter on #{scan.relation_name}",
+              recommendation: "Analyze columns in filter condition for index opportunities"
+            }
+          end
+        end
+
+        # Signal: Inaccurate estimate
+        walk_plan(plan.root_node).each do |node|
+          if node.estimate_inaccurate?
+            ratio = node.estimate_accuracy_ratio
+            signals << {
+              type: :estimate_inaccuracy,
+              severity: :medium,
+              node: node.to_s,
+              ratio: ratio,
+              message: "Estimate off by #{(ratio * 100).to_i}% (estimated: #{node.estimated_rows}, actual: #{node.actual_rows})",
+              recommendation: "Consider running ANALYZE on table statistics"
+            }
+          end
+        end
+
+        # Signal: High cost query
+        if plan.total_estimated_cost > 10000
+          signals << {
+            type: :high_estimated_cost,
+            severity: :medium,
+            cost: plan.total_estimated_cost,
+            message: "Query has high estimated cost: #{plan.total_estimated_cost.round(2)}",
+            recommendation: "Review query structure and indexes"
+          }
+        end
+
+        # Signal: Nested loop joins (potential N+1 equivalent)
+        walk_plan(plan.root_node).each do |node|
+          if nested_loop_join?(node)
+            inner_relation = find_inner_scan(node)
+            signals << {
+              type: :nested_loop_join,
+              severity: :medium,
+              message: "Nested loop join detected#{inner_relation ? " with #{inner_relation}" : ""}",
+              recommendation: "Consider adding indexes on inner table join columns or using hash join with increased work_mem",
+              inner_table: inner_relation
+            }
+          end
+        end
+
+        # Signal: High planning time (possible to_sql overhead or complex stats)
+        if plan.planning_time_ms > 100
+          signals << {
+            type: :high_planning_time,
+            severity: :low,
+            planning_time_ms: plan.planning_time_ms,
+            message: "High planning time: #{plan.planning_time_ms.round(2)}ms",
+            recommendation: "Query planner took significant time; check for complex joins, CTEs, or stale statistics"
+          }
+        end
+
+        # Signal: Sort operations on large result sets
+        walk_plan(plan.root_node).each do |node|
+          if node.sort_key && node.estimated_rows > 1000
+            signals << {
+              type: :expensive_sort,
+              severity: :medium,
+              estimated_rows: node.estimated_rows,
+              message: "Sorting large result set (#{node.estimated_rows} estimated rows) on #{node.sort_key}",
+              recommendation: "Verify sort is necessary; consider index-backed ordering or pagination"
+            }
+          end
+        end
+
+        # Signal: Bitmap scans (generally less efficient than proper indexes)
+        walk_plan(plan.root_node).each do |node|
+          if bitmap_scan?(node)
+            signals << {
+              type: :bitmap_scan,
+              severity: :low,
+              table: node.relation_name,
+              message: "Bitmap index scan on #{node.relation_name}",
+              recommendation: "Confirm index choice is appropriate; may indicate need for composite index"
+            }
+          end
+        end
+
+        signals
+      end
+
+      def sequential_scans
+        plan.sequential_scans
+      end
+
+      def walk_plan(node)
+        nodes = [node]
+        node.children.each { |child| nodes.concat(walk_plan(child)) }
+        nodes
+      end
+
+      # Check if node is a nested loop join
+      #
+      # @param node [PlanNode] Node to check
+      # @return [Boolean]
+      def nested_loop_join?(node)
+        node.node_type == "Nested Loop"
+      end
+
+      # Check if node is a bitmap scan
+      #
+      # @param node [PlanNode] Node to check
+      # @return [Boolean]
+      def bitmap_scan?(node)
+        node.node_type.include?("Bitmap")
+      end
+
+      # Find inner scan node in nested loop (typically the rightmost scan)
+      #
+      # @param node [PlanNode] Nested loop node
+      # @return [String, nil] Table name of inner scan
+      def find_inner_scan(node)
+        return nil if node.children.empty?
+
+        # The last child is typically the inner scan
+        inner_child = node.children.last
+        # Traverse to find the actual table scan
+        scan_node = walk_plan(inner_child).find do |n|
+          n.sequential_scan? || n.index_scan?
+        end
+        scan_node&.relation_name
+      end
+    end
+  end
+end

data/lib/query_guard/explain/postgresql_adapter.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "json"
+
+module QueryGuard
+  module Explain
+    # PostgreSQL-specific EXPLAIN plan adapter.
+    # Executes EXPLAIN (FORMAT JSON, ANALYZE) for PostgreSQL queries.
+    #
+    # Features:
+    # - Safely executes EXPLAIN with ANALYZE for actual metrics
+    # - Returns well-structured JSON plan data
+    # - Fails gracefully if connection unavailable
+    # - Filters out unsafe query patterns
+    # - Configurable timeout and ANALYZE flag
+    #
+    # Example:
+    #   adapter = PostgreSQLAdapter.new(ActiveRecord::Base.connection)
+    #   plan = adapter.get_plan("SELECT * FROM users WHERE status = 'active'")
+    #
+    # Note: Requires postgres adapter (pg gem) with access to query execution
+    class PostgreSQLAdapter < AdapterInterface
+      DEFAULT_EXPLAIN_TIMEOUT = 5.0  # seconds
+
+      # Initialize PostgreSQL adapter
+      #
+      # @param connection [PG::Connection or ActiveRecord Adapter] PostgreSQL connection
+      # @param options [Hash] Configuration options
+      #   @option options [Float] :timeout Explain query timeout (default: 5.0s)
+      #   @option options [Boolean] :use_analyze Whether to use ANALYZE (default: false for safety)
+      #   @option options [Logger] :logger Optional logger instance for debugging
+      #   @option options [Boolean] :validate_connection Check connection is valid on init (default: true)
+      def initialize(connection, options = {})
+        super(connection)
+        @timeout = options[:timeout] || DEFAULT_EXPLAIN_TIMEOUT
+        @use_analyze = options.fetch(:use_analyze, false)
+        @logger = options[:logger]
+        @validate_connection = options.fetch(:validate_connection, true)
+
+        validate_connection! if @validate_connection
+      end
+
+      # Execute EXPLAIN and return parsed JSON plan
+      #
+      # @param sql [String] SQL query to analyze
+      # @param options [Hash] Override default options
+      # @return [Hash] Parsed EXPLAIN plan JSON
+      # @raise [AdapterError] If query can't be explained
+      def get_plan(sql, options = {})
+        unless can_explain?(sql)
+          error_msg = "Cannot EXPLAIN this query type: #{sql.strip[0..50]}..."
+          log_warn(error_msg)
+          raise UnsupportedQueryError, error_msg
+        end
+
+        use_analyze = options.fetch(:use_analyze, @use_analyze)
+        explain_sql = build_explain_query(sql, use_analyze)
+
+        log_debug("Executing EXPLAIN query", use_analyze: use_analyze)
+        plan_json = execute_explain(explain_sql)
+        JSON.parse(plan_json)
+      rescue JSON::ParserError => e
+        error_msg = "Failed to parse EXPLAIN output: #{e.message}"
+        log_warn(error_msg)
+        raise PlanParseError, error_msg
+      rescue Timeout::Error => e
+        error_msg = "EXPLAIN query timed out after #{@timeout}s"
+        log_warn(error_msg)
+        raise TimeoutError, error_msg
+      rescue StandardError => e
+        log_warn("EXPLAIN execution failed: #{e.message}")
+        raise AdapterError, "EXPLAIN execution failed: #{e.message}"
+      end
+
+      # Check if query can be safely explained
+      #
+      # @param sql [String] SQL query
+      # @return [Boolean] True if query is safe to EXPLAIN
+      def can_explain?(sql)
+        normalized = sql.strip.upcase
+        # Only EXPLAIN SELECT, WITH (CTE), and simple UPDATE/DELETE
+        return false if normalized.start_with?("PRAGMA", "BEGIN", "COMMIT")
+        return false if normalized.start_with?("DROP", "ALTER", "CREATE", "TRUNCATE")
+        return false if normalized.include?("RETURNING") && !normalized.start_with?("SELECT")
+
+        true
+      end
+
+      # Engine identifier
+      #
+      # @return [Symbol]
+      def engine_name
+        :postgresql
+      end
+
+      # Get version of PostgreSQL server
+      #
+      # @return [String] PostgreSQL version
+      def server_version
+        execute_query("SELECT version()").first.first
+      rescue StandardError => e
+        raise ConnectionError, "Cannot connect to PostgreSQL: #{e.message}"
+      end
+
+      private
+
+      def build_explain_query(sql, use_analyze)
+        # EXPLAIN (FORMAT JSON) provides output in JSON format
+        # ANALYZE actually runs the query (for real metrics) but is slower
+        # For safety, default to just EXPLAIN without ANALYZE
+
+        options = "FORMAT JSON"
+        options += ", ANALYZE" if use_analyze
+        options += ", BUFFERS" if use_analyze  # useful with ANALYZE
+
+        "EXPLAIN (#{options}) #{sql}"
+      end
+
+      def execute_explain(explain_sql)
+        begin
+          result = execute_query_with_timeout(explain_sql)
+          # Result is array of rows, each with plan JSON
+          # PostgreSQL returns one row with the full plan as JSON
+          plan_or_nil = result.first&.first
+          plan_or_nil || raise(AdapterError, "EXPLAIN returned empty result")
+        rescue Timeout::Error
+          raise TimeoutError, "EXPLAIN query timed out after #{@timeout}s"
+        rescue AdapterError
+          raise
+        rescue StandardError => e
+          raise AdapterError, "Failed to execute EXPLAIN: #{e.message}", original_error: e
+        end
+      end
+
+      def execute_query_with_timeout(sql)
+        if connection.respond_to?(:execute)
+          # ActiveRecord adapter (most common)
+          execute_activerecord(sql)
+        elsif connection.respond_to?(:query)
+          # pg gem raw connection
+          execute_pg_gem(sql)
+        else
+          raise ConnectionError, "Cannot determine connection type for EXPLAIN"
+        end
+      end
+
+      def execute_activerecord(sql)
+        # Using ActiveRecord's query execution
+        # This handles connection pooling automatically
+        result = connection.execute(sql)
+
+        # ActiveRecord result sets have different formats per adapter
+        if result.respond_to?(:rows)
+          # Most adapters
+          result.rows
+        elsif result.respond_to?(:first)
+          # Compatibility with some adapters
+          [result]
+        else
+          raise AdapterError, "Unable to read EXPLAIN result"
+        end
+      end
+
+      def execute_pg_gem(sql)
+        # Raw pg gem connection
+        # Note: This is rarely used in Rails but supported for completeness
+        begin
+          result = connection.query(sql)
+          result.map(&:values)
+        rescue PG::Error => e
+          raise AdapterError, "PostgreSQL query failed: #{e.message}"
+        end
+      end
+
+      def execute_query(sql)
+        if connection.respond_to?(:execute)
+          connection.execute(sql)
+        elsif connection.respond_to?(:query)
+          connection.query(sql)
+        else
+          raise ConnectionError, "Cannot execute query with this connection"
+        end
+      end
+
+      def validate_connection!
+        server_version
+        log_debug("PostgreSQL connection validated")
+      rescue StandardError => e
+        connection_error = "Cannot validate PostgreSQL connection: #{e.message}"
+        log_warn(connection_error)
+        raise ConnectionError, connection_error
+      end
+
+      def log_debug(message, **context)
+        return unless @logger
+
+        context_str = context.empty? ? "" : " (#{context.to_s})"
+        @logger.debug("[QueryGuard::PostgreSQLAdapter] #{message}#{context_str}")
+      end
+
+      def log_warn(message)
+        return unless @logger
+
+        @logger.warn("[QueryGuard::PostgreSQLAdapter] #{message}")
+      end
+    end
+  end
+end