query_guard 0.4.1 → 0.5.0

data/lib/query_guard/migrations/migration_risk_detectors.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Migrations
+    # Detects risky patterns in Rails migration files.
+    # Uses pragmatic line-by-line analysis rather than complex regex.
+    # Returns structured finding data for each detected risk.
+    class MigrationRiskDetectors
+      # Detects migration risks from file content
+      def self.detect_risks(migration_content, migration_name)
+        risks = []
+
+        # Run all detectors
+        risks.concat(detect_unsafe_index_additions(migration_content, migration_name))
+        risks.concat(detect_table_locking_operations(migration_content, migration_name))
+        risks.concat(detect_non_null_additions(migration_content, migration_name))
+        risks.concat(detect_full_table_updates(migration_content, migration_name))
+        risks.concat(detect_unsafe_raw_sql(migration_content, migration_name))
+
+        risks
+      end
+
+      private
+
+      # Detect index additions without algorithm: :concurrently or add_index without safe options
+      def self.detect_unsafe_index_additions(content, migration_name)
+        risks = []
+
+        # Find all add_index occurrences
+        lines = content.lines
+        lines.each_with_index do |line, index|
+          next unless line.include?("add_index")
+
+          # Check if line includes algorithm: :concurrently
+          unless line.include?("algorithm: :concurrently") || line.include?("algorithm: :concurrent")
+            risks << {
+              type: :index_not_concurrent,
+              severity: :error,
+              line_number: index + 1,
+              migration_name: migration_name,
+              title: "Index Addition Without CONCURRENTLY",
+              description: "Adding an index locks the table. Use algorithm: :concurrently for PostgreSQL.",
+              message: "add_index without algorithm: :concurrently",
+              recommendation: "Add algorithm: :concurrently to allow concurrent queries during index creation",
+              metadata: {
+                operation: "add_index",
+                risk_level: :high,
+                locking: true
+              }
+            }
+          end
+        end
+
+        risks
+      end
+
+      # Detect operations that lock the table: remove_column, change_column, rename_column
+      def self.detect_table_locking_operations(content, migration_name)
+        risks = []
+        lines = content.lines
+
+        lines.each_with_index do |line, index|
+          next if line.strip.start_with?("#")
+          next if line.strip.empty?
+
+          # Check with word boundary to match method calls with or without parentheses
+          case line
+          when /\bremove_column\b/
+            risks << {
+              type: :remove_column_lock,
+              severity: :error,
+              line_number: index + 1,
+              migration_name: migration_name,
+              title: "Remove Column Locks Table",
+              description: "Removing a column rewrites the entire table, causing extended lock.",
+              message: "remove_column operation locks table",
+              recommendation: "Use safe_remove_column from a migration-safe gem, or manually soft-delete the column first",
+              metadata: { operation: "remove_column", risk_level: :high, locking: true }
+            }
+          when /\bchange_column\b/
+            risks << {
+              type: :change_column_lock,
+              severity: :error,
+              line_number: index + 1,
+              migration_name: migration_name,
+              title: "Change Column Locks Table",
+              description: "Changing a column type rewrites the entire table, causing extended lock.",
+              message: "change_column operation locks table",
+              recommendation: "Create new column, migrate data with backfill, then drop old column in separate migration",
+              metadata: { operation: "change_column", risk_level: :high, locking: true }
+            }
+          when /\brename_column\b/
+            risks << {
+              type: :rename_column_lock,
+              severity: :warn,
+              line_number: index + 1,
+              migration_name: migration_name,
+              title: "Rename Column Brief Lock",
+              description: "Renaming a column briefly locks the table during metadata update.",
+              message: "rename_column operation locks table briefly",
+              recommendation: "Use with caution in large tables; consider aliasing instead",
+              metadata: { operation: "rename_column", risk_level: :medium, locking: true }
+            }
+          end
+        end
+
+        risks
+      end
+
+      # Detect adding NOT NULL columns without safe rollout pattern
+      def self.detect_non_null_additions(content, migration_name)
+        risks = []
+        lines = content.lines
+
+        lines.each_with_index do |line, index|
+          next unless line.include?("add_column")
+          next if line.strip.start_with?("#")
+
+          # Check for null: false without default
+          if line.include?("null: false") && !line.include?("default:")
+            risks << {
+              type: :non_null_no_default,
+              severity: :error,
+              line_number: index + 1,
+              migration_name: migration_name,
+              title: "Non-NULL Column Without Default",
+              description: "Adding a NOT NULL column without a default value will fail on populated tables.",
+              message: "add_column null: false (no default)",
+              recommendation: "Provide a default value, or add the column as nullable and backfill in separate step.",
+              metadata: { operation: "add_column", risk_level: :high }
+            }
+          end
+        end
+
+        risks
+      end
+
+      # Detect full-table updates inside migrations
+      def self.detect_full_table_updates(content, migration_name)
+        risks = []
+        lines = content.lines
+
+        lines.each_with_index do |line, index|
+          next if line.strip.start_with?("#")
+
+          # Detect Model.update_all or delete_all calls
+          if line.include?(".update_all") || line.include?(".delete_all")
+            risks << {
+              type: :full_table_update,
+              severity: :error,
+              line_number: index + 1,
+              migration_name: migration_name,
+              title: "Full-Table Update in Migration",
+              description: "Updating all rows in a migration locks the table and is slow on large tables.",
+              message: "update_all or delete_all in migration",
+              recommendation: "Use a separate rake task or background job for large updates. Process rows in batches with pauses.",
+              metadata: { operation: "updateall", risk_level: :high, locking: true }
+            }
+          end
+        end
+
+        risks
+      end
+
+      # Detect unsafe raw SQL statements
+      def self.detect_unsafe_raw_sql(content, migration_name)
+        risks = []
+        lines = content.lines
+
+        lines.each_with_index do |line, index|
+          next if line.strip.start_with?("#")
+          next if line.strip.empty?
+
+          # Check for dangerous SQL keywords in quoted strings in execute() calls
+          if line.include?("execute") && (line.include?('"') || line.include?("'"))
+            # Extract the SQL string from the line
+            sql_match = line.match(/"([^"]+)"|'([^']+)'/)
+            if sql_match
+              sql = sql_match[1] || sql_match[2]
+              upcase_sql = sql.upcase
+
+              if upcase_sql.include?("TRUNCATE")
+                risks << {
+                  type: :dangerous_raw_sql,
+                  severity: :error,
+                  line_number: index + 1,
+                  migration_name: migration_name,
+                  title: "TRUNCATE in Migration",
+                  description: "TRUNCATE operations are dangerous and can cause data loss.",
+                  message: "TRUNCATE detected in raw SQL",
+                  recommendation: "Avoid TRUNCATE; use safer alternatives or manual database cleanup",
+                  metadata: { operation: "raw_sql", risk_level: :critical }
+                }
+              elsif upcase_sql.include?("DROP")
+                risks << {
+                  type: :dangerous_raw_sql,
+                  severity: :error,
+                  line_number: index + 1,
+                  migration_name: migration_name,
+                  title: "DROP in Migration",
+                  description: "DROP operations are dangerous and can cause data loss.",
+                  message: "DROP detected in raw SQL",
+                  recommendation: "Avoid DROP in migrations; use Rails schema helpers instead",
+                  metadata: { operation: "raw_sql", risk_level: :critical }
+                }
+              elsif upcase_sql.include?("LOCK TABLE")
+                risks << {
+                  type: :explicit_table_lock,
+                  severity: :warn,
+                  line_number: index + 1,
+                  migration_name: migration_name,
+                  title: "Explicit Table Lock",
+                  description: "Explicit LOCK TABLE statements block all table access.",
+                  message: "LOCK TABLE detected in raw SQL",
+                  recommendation: "Avoid explicit locks; let migrations handle locking implicitly",
+                  metadata: { operation: "raw_sql", risk_level: :medium }
+                }
+              elsif (upcase_sql.include?("UPDATE") || upcase_sql.include?("DELETE")) && !upcase_sql.include?("WHERE")
+                risks << {
+                  type: :unsafe_raw_sql_full_table,
+                  severity: :error,
+                  line_number: index + 1,
+                  migration_name: migration_name,
+                  title: "Full Table SQL Without WHERE",
+                  description: "UPDATE/DELETE without WHERE clause affects entire table.",
+                  message: "Full table operation without WHERE clause",
+                  recommendation: "Always include WHERE clause; batch operations for safety",
+                  metadata: { operation: "raw_sql", risk_level: :critical }
+                }
+              end
+            end
+          end
+
+          # Also check for dangerous keywords on their own line
+          upcase_line = line.upcase
+
+          if upcase_line.include?("TRUNCATE") && !line.strip.start_with?("#")
+            # Skip if already reported from execute() parsing
+            next if line.include?("execute")
+
+            risks << {
+              type: :dangerous_raw_sql,
+              severity: :error,
+              line_number: index + 1,
+              migration_name: migration_name,
+              title: "TRUNCATE in Migration",
+              description: "TRUNCATE operations are dangerous and can cause data loss.",
+              message: "TRUNCATE detected",
+              recommendation: "Avoid TRUNCATE; use safer alternatives or manual database cleanup",
+              metadata: { operation: "raw_sql", risk_level: :critical }
+            }
+          elsif upcase_line.include?("DROP TABLE") || upcase_line.include?("DROP COLUMN")
+            next if line.include?("execute")
+
+            risks << {
+              type: :dangerous_raw_sql,
+              severity: :error,
+              line_number: index + 1,
+              migration_name: migration_name,
+              title: "DROP in Migration",
+              description: "DROP operations are dangerous and can cause data loss.",
+              message: "DROP detected",
+              recommendation: "Avoid DROP in migrations; use Rails schema helpers instead",
+              metadata: { operation: "raw_sql", risk_level: :critical }
+            }
+          elsif upcase_line.include?("LOCK TABLE")
+            next if line.include?("execute")
+
+            risks << {
+              type: :explicit_table_lock,
+              severity: :warn,
+              line_number: index + 1,
+              migration_name: migration_name,
+              title: "Explicit Table Lock",
+              description: "Explicit LOCK TABLE statements block all table access.",
+              message: "LOCK TABLE detected",
+              recommendation: "Avoid explicit locks; let migrations handle locking implicitly",
+              metadata: { operation: "raw_sql", risk_level: :medium }
+            }
+          end
+        end
+
+        risks
+      end
+    end
+  end
+end

data/lib/query_guard/migrations/postgresql_adapter.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Migrations
+    # PostgreSQL-specific metadata adapter
+    #
+    # Queries PostgreSQL system catalog to estimate table sizes
+    # and determine lock risk based on row count and write activity.
+    #
+    # Row count thresholds (from PostgreSQL best practices):
+    # - < 1M rows: Low lock risk, fast schema changes
+    # - 1M - 10M rows: Medium lock risk, monitor lock times
+    # - 10M - 100M rows: High lock risk, use concurrent operations
+    # - > 100M rows: Critical risk, requires special handling
+    class PostgreSQLAdapter < DatabaseAdapter
+      # Lock duration thresholds (milliseconds)
+      # Based on typical PostgreSQL behavior
+      LOCK_THRESHOLDS = {
+        low: 1_000_000,        # < 1M rows
+        medium: 10_000_000,    # 1M - 10M rows
+        high: 100_000_000,     # 10M - 100M rows
+        critical: Float::INFINITY  # > 100M rows
+      }.freeze
+
+      # Initialize PostgreSQL adapter
+      #
+      # @param connection [Object] Active database connection (responds to exec_query)
+      # @param schema [String] Schema to query (default: public)
+      # @option cache [Boolean] Whether to cache row count queries (default: true)
+      def initialize(connection, schema: "public", cache: true)
+        @connection = connection
+        @schema = schema
+        @cache_enabled = cache
+        @cache = {} if cache
+      end
+
+      # Estimate row count using PostgreSQL statistics
+      #
+      # Uses pg_class.reltuples for estimated row count.
+      # Falls back to COUNT(*) if stats unavailable.
+      #
+      # @param table_name [String, Symbol] Table name
+      # @return [Integer, nil] Estimated rows, or nil if unavailable
+      def estimate_table_rows(table_name)
+        return nil unless connected?
+        return @cache[table_name.to_s] if @cache_enabled && @cache.key?(table_name.to_s)
+
+        begin
+          # Use PostgreSQL statistics (faster, less accurate)
+          result = @connection.exec_query(
+            "SELECT reltuples::bigint as estimated_rows FROM pg_class
+             WHERE relname = $1 AND relnamespace = 
+               (SELECT oid FROM pg_namespace WHERE nspname = $2)
+             LIMIT 1",
+            "GetTableRows",
+            [[table_name.to_s, :string], [@schema, :string]]
+          )
+
+          rows = result.rows.dig(0, 0)&.to_i
+          @cache[table_name.to_s] = rows if @cache_enabled
+          rows
+        rescue StandardError => e
+          # Fail gracefully - log if possible, return nil
+          warn "Failed to get row count for #{table_name}: #{e.message}"
+          nil
+        end
+      end
+
+      # Estimate lock risk based on table size
+      #
+      # Larger tables take longer to lock and rewrite,
+      # increasing risk of production impact.
+      #
+      # @param table_name [String, Symbol] Table name
+      # @return [Symbol, nil] Risk level: :low, :medium, :high, :critical
+      def estimate_lock_risk(table_name)
+        rows = estimate_table_rows(table_name)
+        return nil if rows.nil?
+
+        case rows
+        when 0...LOCK_THRESHOLDS[:low]
+          :low
+        when LOCK_THRESHOLDS[:low]...LOCK_THRESHOLDS[:medium]
+          :medium
+        when LOCK_THRESHOLDS[:medium]...LOCK_THRESHOLDS[:high]
+          :high
+        else
+          :critical
+        end
+      end
+
+      # Check if table exists
+      #
+      # @param table_name [String, Symbol] Table name
+      # @return [Boolean] True if table exists in schema
+      def table_exists?(table_name)
+        return false unless connected?
+
+        begin
+          result = @connection.exec_query(
+            "SELECT 1 FROM information_schema.tables
+             WHERE table_schema = $1 AND table_name = $2 LIMIT 1",
+            "CheckTableExists",
+            [[@schema, :string], [table_name.to_s, :string]]
+          )
+          result.rows.any?
+        rescue StandardError => e
+          warn "Failed to check if table exists #{table_name}: #{e.message}"
+          false
+        end
+      end
+
+      # List all tables in schema
+      #
+      # @return [Array<String>] Table names
+      def list_tables
+        return [] unless connected?
+
+        begin
+          result = @connection.exec_query(
+            "SELECT table_name FROM information_schema.tables
+             WHERE table_schema = $1
+             ORDER BY table_name",
+            "ListTables",
+            [[@schema, :string]]
+          )
+          result.rows.flatten
+        rescue StandardError => e
+          warn "Failed to list tables: #{e.message}"
+          []
+        end
+      end
+
+      # Check if connection is healthy
+      #
+      # @return [Boolean] True if we can query the database
+      def connected?
+        return false if @connection.nil?
+
+        begin
+          @connection.exec_query("SELECT 1 LIMIT 1")
+          true
+        rescue StandardError => e
+          warn "Database connection check failed: #{e.message}"
+          false
+        end
+      end
+
+      # Clear the row count cache
+      #
+      # Call this if you've made schema changes and want fresh stats.
+      def clear_cache
+        @cache.clear if @cache_enabled && @cache
+      end
+    end
+  end
+end

data/lib/query_guard/migrations/table_risk_analyzer.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Migrations
+    # Enhances risk analysis with table-size-aware context
+    #
+    # When database metadata is available, escalates risk severity
+    # for operations on large tables.
+    #
+    # For example:
+    # - add_index on 10M row table = CRITICAL (will lock for minutes)
+    # - add_index on 100K row table = ERROR (will lock briefly)
+    #
+    # Works gracefully if database unavailable by falling back to
+    # static analysis.
+    class TableRiskAnalyzer
+      # Risk escalation factors based on table size
+      ESCALATION_FACTORS = {
+        low: 0,        # < 1M rows: no escalation
+        medium: 1,     # 1M - 10M rows: escalate 1 level (error -> critical)
+        high: 2,       # 10M - 100M rows: escalate 2 levels (warn -> critical)
+        critical: 3    # > 100M rows: already critical
+      }.freeze
+
+      # Initialize analyzer
+      #
+      # @param adapter [DatabaseAdapter] Optional database adapter
+      def initialize(adapter = nil)
+        @adapter = adapter || NullDatabaseAdapter.new
+      end
+
+      # Enhance risks with table size information
+      #
+      # @param migration_content [String] Migration file content
+      # @param risks [Array<Hash>] Risks from MigrationRiskDetectors
+      # @return [Array<Hash>] Risks with table metadata added
+      def enhance_risks(migration_content, risks)
+        return risks unless @adapter.connected?
+
+        # Extract affected tables from migration
+        affected_tables = TableSizeResolver.affected_tables(migration_content)
+        return risks if affected_tables.empty?
+
+        # Build table metadata cache
+        table_metadata = {}
+        affected_tables.each do |table_name|
+          row_count = @adapter.estimate_table_rows(table_name)
+          lock_risk = @adapter.estimate_lock_risk(table_name)
+
+          table_metadata[table_name] = {
+            estimated_rows: row_count,
+            lock_risk: lock_risk
+          }
+        end
+
+        # Enhance each risk with table metadata
+        risks.map do |risk|
+          enhance_single_risk(risk, migration_content, table_metadata)
+        end
+      end
+
+      protected
+
+      def enhance_single_risk(risk, migration_content, table_metadata)
+        # Copy risk hash so we don't mutate original
+        enhanced_risk = risk.dup
+        metadata = (risk[:metadata] || {}).dup
+
+        # Try to determine which table this risk refers to
+        affected_tables = TableSizeResolver.affected_tables(migration_content)
+        risk_type = risk[:type]
+
+        # Different risk types affect different tables
+        table_name = determine_risk_table(risk_type, migration_content, affected_tables)
+
+        if table_name && table_metadata[table_name]
+          table_info = table_metadata[table_name]
+
+          # Add table metadata to risk
+          metadata[:table_name] = table_name
+          metadata[:estimated_table_rows] = table_info[:estimated_rows]
+          metadata[:table_lock_risk] = table_info[:lock_risk]
+
+          enhanced_risk[:metadata] = metadata
+
+          # Escalate severity if table is large
+          if table_info[:lock_risk]
+            enhanced_risk = escalate_risk_for_table(enhanced_risk, table_info[:lock_risk])
+            # Preserve our table metadata additions
+            enhanced_risk[:metadata].merge!(metadata)
+            enhanced_risk[:metadata][:severity_escalated] = true
+            enhanced_risk[:metadata][:escalation_reason] = "Large table (#{format_row_count(table_info[:estimated_rows])} rows)"
+          end
+        else
+          enhanced_risk[:metadata] = metadata
+        end
+
+        enhanced_risk
+      end
+
+      def determine_risk_table(risk_type, migration_content, affected_tables)
+        # Heuristic: find the most likely table for this risk
+        # Could be enhanced with more sophisticated analysis
+
+        affected_tables.first # Simple: return first affected table for now
+      end
+
+      def escalate_risk_for_table(risk, lock_risk)
+        return risk if lock_risk.nil?
+
+        # Only escalate errors and warnings, not info
+        return risk if risk[:severity] == :info
+
+        escalation = ESCALATION_FACTORS[lock_risk] || 0
+        return risk if escalation.zero?
+
+        # Escalate severity based on table size
+        escalated_risk = risk.dup
+        original_severity = risk[:severity]
+
+        escalated_risk[:severity] = case original_severity
+                                   when :warn
+                                     # Escalate WARN to ERROR for medium+ tables (escalation >= 1)
+                                     escalation >= 1 ? :error : :warn
+                                   when :error
+                                     # Escalate ERROR to CRITICAL for medium+ tables (escalation >= 1)
+                                     escalation >= 1 ? :critical : :error
+                                   else
+                                     original_severity
+                                   end
+
+        escalated_risk[:metadata] = (risk[:metadata] || {}).dup
+        escalated_risk[:metadata][:original_severity] = original_severity
+
+        escalated_risk
+      end
+
+      def format_row_count(count)
+        return "unknown" if count.nil?
+
+        case count
+        when 0..999
+          "#{count}"
+        when 1000..999_999
+          "#{(count / 1000.0).round(1)}K"
+        when 1_000_000..999_999_999
+          "#{(count / 1_000_000.0).round(1)}M"
+        else
+          "#{(count / 1_000_000_000.0).round(1)}B"
+        end
+      end
+    end
+  end
+end