simple_query 0.5.0 → 0.6.0

data/lib/simple_query/builder.rb

@@ -12,18 +12,18 @@ module SimpleQuery
       @arel_table = @model.arel_table
 
       @selects = []
-      @wheres = WhereClause.new(@arel_table)
+      @wheres = WhereClause.new(@arel_table, @model)
       @joins = JoinClause.new
-      @group_having = GroupHavingClause.new(@arel_table)
+      @group_having = GroupHavingClause.new(@arel_table, @model)
       @orders = OrderClause.new(@arel_table)
       @limits = LimitOffsetClause.new
       @distinct_flag = DistinctClause.new
-      @aggregations = AggregationClause.new(@arel_table)
+      @aggregations = AggregationClause.new(@arel_table, @model)
 
       @query_cache = {}
       @query_built = false
       @read_model_class = nil
-      @result_struct = nil
+      @result_structs = {}
     end
 
     def select(*fields)
@@ -172,7 +172,8 @@ module SimpleQuery
     # Method to get last/bottom record by column
     def last_by(column, alias_name: nil)
       alias_name ||= "last_#{column}"
-      custom_aggregation("LAST_VALUE(#{resolve_column_name(column)}) OVER (ORDER BY #{resolve_column_name(column)})",
+      custom_aggregation("LAST_VALUE(#{resolve_column_name(column)}) OVER (ORDER BY #{resolve_column_name(column)} " \
+                         "ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING)",
                          alias_name)
     end
 
@@ -191,37 +192,44 @@ module SimpleQuery
     end
 
     def bulk_update(set:)
-      table_name = @arel_table.name
-      set_sql = SetClause.new(set).to_sql
+      validate_bulk_update_scope!
 
+      set_sql = SetClause.new(set, @model).to_sql
       raise ArgumentError, "No columns to update" if set_sql.empty?
 
-      where_sql = build_where_sql
-      sql = "UPDATE #{table_name} SET #{set_sql}"
-      sql += " WHERE #{where_sql}" unless where_sql.nil? || where_sql.empty?
+      update = Arel::UpdateManager.new
+      update.table(@arel_table)
+      update.set(Arel.sql(set_sql))
+      condition = @wheres.to_arel
+      update.where(condition) if condition
 
-      ActiveRecord::Base.connection.execute(sql)
+      connection.execute(compile_sql(update))
     end
 
     def stream_each(batch_size: 1000, &block)
-      adapter = ActiveRecord::Base.connection.adapter_name.downcase
+      validate_stream_batch_size!(batch_size)
+
+      adapter_name = connection.adapter_name
+      adapter = adapter_name.downcase
       if adapter.include?("postgres")
         stream_each_postgres(batch_size, &block)
       elsif adapter.include?("mysql")
         stream_each_mysql(&block)
       else
-        raise "stream_each is only implemented for Postgres and MySQL."
+        message = "stream_each is only implemented for PostgreSQL and MySQL adapters " \
+                  "(current adapter: #{adapter_name})"
+        raise UnsupportedAdapterError, message
       end
     end
 
     def execute
-      records = ActiveRecord::Base.connection.select_all(cached_sql)
+      records = connection.select_all(cached_sql)
       build_result_objects_from_rows(records)
     end
 
     def lazy_execute
       Enumerator.new do |yielder|
-        records = ActiveRecord::Base.connection.select_all(cached_sql)
+        records = connection.select_all(cached_sql)
         if @read_model_class
           build_read_models_enumerator(records, yielder)
         else
@@ -256,6 +264,22 @@ module SimpleQuery
 
     private
 
+    def validate_stream_batch_size!(batch_size)
+      return if batch_size.is_a?(Integer) && batch_size.positive?
+
+      raise ArgumentError, "stream_each batch_size must be a positive Integer"
+    end
+
+    def validate_bulk_update_scope!
+      unsupported = []
+      unsupported << "joins" if @joins.joins.any?
+      unsupported << "limit/offset" if @limits.limit_value || @limits.offset_value
+      unsupported << "group/having" if @group_having.group_fields.any? || @group_having.having_conditions.any?
+      return if unsupported.empty?
+
+      raise ArgumentError, "bulk_update only supports where conditions (found #{unsupported.join(", ")})"
+    end
+
     def build_select_expressions
       expressions = []
 
@@ -273,11 +297,13 @@ module SimpleQuery
       expressions
     end
 
-    def build_where_sql
-      condition = @wheres.to_arel
-      return "" unless condition
+    def connection
+      @model.connection
+    end
 
-      condition.to_sql
+    # Compiles with the model's own connection, inlining any bind values.
+    def compile_sql(arel)
+      connection.unprepared_statement { connection.to_sql(arel) }
     end
 
     def reset_query
@@ -299,7 +325,7 @@ module SimpleQuery
         @aggregations.aggregations
       ]
 
-      @query_cache[key] ||= build_query.to_sql
+      @query_cache[key] ||= compile_sql(build_query)
     end
 
     def build_result_objects_from_rows(records)
@@ -340,7 +366,8 @@ module SimpleQuery
     end
 
     def result_struct(columns)
-      @result_struct ||= Struct.new(*columns.map(&:to_sym))
+      struct_key = columns.map(&:to_s)
+      @result_structs[struct_key] ||= Struct.new(*struct_key.map(&:to_sym))
     end
 
     def apply_distinct
@@ -392,9 +419,10 @@ module SimpleQuery
       end
     end
 
-    def method_missing(method_name, *args, &block)
+    def method_missing(method_name, *args, **kwargs, &block)
       if (scope_block = find_scope(method_name))
-        instance_exec(*args, &scope_block)
+        validate_scope_arity!(method_name, scope_block, scope_arguments_for_validation(scope_block, args, kwargs))
+        instance_exec(*args, **kwargs, &scope_block)
         self
       else
         super
@@ -410,5 +438,69 @@ module SimpleQuery
 
       model._simple_scopes[method_name.to_sym]
     end
+
+    def validate_scope_arity!(scope_name, scope_block, args)
+      range = scope_argument_range(scope_block)
+      provided = args.length
+      return if scope_arity_matches?(range, provided)
+
+      raise ArgumentError,
+            "simple_scope :#{scope_name} expected #{scope_arity_description(range)}, provided #{provided}"
+    end
+
+    def scope_arguments_for_validation(scope_block, args, kwargs)
+      return args if kwargs.empty? || scope_uses_keyword_arguments?(scope_block)
+
+      args + [kwargs]
+    end
+
+    def scope_argument_range(scope_block)
+      # Keyword argument arity has Ruby-version-specific edge cases; let Ruby raise its native error.
+      return nil if scope_uses_keyword_arguments?(scope_block)
+
+      minimum = minimum_scope_arguments(scope_block)
+      maximum = maximum_scope_arguments(scope_block)
+
+      [minimum, maximum]
+    end
+
+    def scope_uses_keyword_arguments?(scope_block)
+      scope_block.parameters.any? { |kind, _name| [:key, :keyreq, :keyrest].include?(kind) }
+    end
+
+    def minimum_scope_arguments(scope_block)
+      arity = scope_block.arity
+      return arity if arity >= 0
+
+      -arity - 1
+    end
+
+    def maximum_scope_arguments(scope_block)
+      parameters = scope_block.parameters
+      return nil if parameters.any? { |kind, _name| kind == :rest }
+
+      parameters.count { |kind, _name| [:req, :opt].include?(kind) }
+    end
+
+    def scope_arity_matches?(range, provided)
+      return true if range.nil?
+
+      minimum, maximum = range
+      return provided >= minimum if maximum.nil?
+
+      provided.between?(minimum, maximum)
+    end
+
+    def scope_arity_description(range)
+      minimum, maximum = range
+      return "at least #{argument_count_description(minimum)}" if maximum.nil?
+      return "exactly #{argument_count_description(minimum)}" if minimum == maximum
+
+      "#{minimum} to #{argument_count_description(maximum)}"
+    end
+
+    def argument_count_description(count)
+      "#{count} #{count == 1 ? "argument" : "arguments"}"
+    end
   end
 end

data/lib/simple_query/clauses/aggregation_clause.rb

@@ -4,8 +4,9 @@ module SimpleQuery
   class AggregationClause
     attr_reader :aggregations
 
-    def initialize(table)
+    def initialize(table, model = ActiveRecord::Base)
       @table = table
+      @model = model
       @aggregations = []
     end
 
@@ -91,15 +92,17 @@ module SimpleQuery
       alias_name ||= "group_concat_#{sanitize_alias(column)}"
 
       # Use database-specific group concatenation
-      adapter = ActiveRecord::Base.connection.adapter_name.downcase
+      connection = @model.connection
+      adapter = connection.adapter_name.downcase
+      quoted_separator = connection.quote(separator.to_s)
 
       expression = case adapter
                    when /mysql/
-                     "GROUP_CONCAT(#{column_expr} SEPARATOR '#{separator}')"
+                     "GROUP_CONCAT(#{column_expr} SEPARATOR #{quoted_separator})"
                    when /postgres/
-                     "STRING_AGG(#{column_expr}::text, '#{separator}')"
+                     "STRING_AGG(#{column_expr}::text, #{quoted_separator})"
                    when /sqlite/
-                     "GROUP_CONCAT(#{column_expr}, '#{separator}')"
+                     "GROUP_CONCAT(#{column_expr}, #{quoted_separator})"
                    else
                      # Fallback for other databases
                      "GROUP_CONCAT(#{column_expr})"

data/lib/simple_query/clauses/group_having_clause.rb

@@ -4,8 +4,9 @@ module SimpleQuery
   class GroupHavingClause
     attr_reader :group_fields, :having_conditions
 
-    def initialize(table)
+    def initialize(table, model = ActiveRecord::Base)
       @table = table
+      @model = model
       @group_fields = []
       @having_conditions = []
     end
@@ -15,15 +16,14 @@ module SimpleQuery
     end
 
     def add_having(condition)
-      @having_conditions << condition
+      clause = WhereClause.new(@table, @model)
+      clause.add(condition)
+      @having_conditions.concat(clause.conditions)
     end
 
     def apply_to(query)
       @group_fields.each { |g| query.group(g) }
-      if @having_conditions.any?
-        combined = @having_conditions.inject { |c, a| c.and(a) }
-        query.having(combined)
-      end
+      query.having(WhereClause.combine(@having_conditions)) if @having_conditions.any?
       query
     end
   end

data/lib/simple_query/clauses/set_clause.rb

@@ -2,8 +2,9 @@
 
 module SimpleQuery
   class SetClause
-    def initialize(set_hash)
+    def initialize(set_hash, model = ActiveRecord::Base)
       @set_hash = set_hash
+      @model = model
     end
 
     def to_sql
@@ -15,11 +16,11 @@ module SimpleQuery
     private
 
     def quote_column(col)
-      ActiveRecord::Base.connection.quote_column_name(col)
+      @model.connection.quote_column_name(col)
     end
 
     def quote_value(val)
-      ActiveRecord::Base.connection.quote(val)
+      @model.connection.quote(val)
     end
   end
 end

data/lib/simple_query/clauses/where_clause.rb

@@ -4,8 +4,16 @@ module SimpleQuery
   class WhereClause
     attr_reader :conditions
 
-    def initialize(table)
+    def self.combine(conditions)
+      return nil if conditions.empty?
+      return conditions.first if conditions.one?
+
+      Arel::Nodes::And.new(conditions.map { |c| c.is_a?(Arel::Nodes::Grouping) ? c : Arel::Nodes::Grouping.new(c) })
+    end
+
+    def initialize(table, model = ActiveRecord::Base)
       @table = table
+      @model = model
       @conditions = []
     end
 
@@ -15,11 +23,7 @@ module SimpleQuery
     end
 
     def to_arel
-      return nil if @conditions.empty?
-
-      @conditions.inject do |combined, current|
-        combined.and(current)
-      end
+      self.class.combine(@conditions)
     end
 
     private
@@ -27,15 +31,36 @@ module SimpleQuery
     def parse_condition(condition)
       case condition
       when Hash
-        condition.map { |field, value| @table[field].eq(value) }
-      when Arel::Nodes::Node
+        condition.map { |field, value| hash_predicate(field, value) }
+      when Arel::Nodes::Node, Arel::Attributes::Attribute
         [condition]
       when Array
-        sanitized_sql = ActiveRecord::Base.send(:sanitize_sql_array, condition)
+        sanitized_sql = @model.send(:sanitize_sql_array, condition)
         [Arel.sql(sanitized_sql)]
       else
         [Arel.sql(condition.to_s)]
       end
     end
+
+    def hash_predicate(field, value)
+      attribute = @table[field]
+      return attribute.eq(value) if force_equality?(field, value)
+
+      case value
+      when Array
+        values = value.compact
+        predicate = attribute.in(values)
+        values.size == value.size ? predicate : predicate.or(attribute.eq(nil))
+      when Range
+        attribute.between(value)
+      else
+        attribute.eq(value)
+      end
+    end
+
+    # PostgreSQL array/range columns compare arrays and ranges by equality, like ActiveRecord does.
+    def force_equality?(field, value)
+      @table.able_to_type_cast? && @table.type_for_attribute(field.to_s).force_equality?(value)
+    end
   end
 end

data/lib/simple_query/stream/mysql_stream.rb

@@ -6,12 +6,17 @@ module SimpleQuery
       def stream_each_mysql(&block)
         select_sql = cached_sql
 
-        raw_conn = ActiveRecord::Base.connection.raw_connection
+        raw_conn = connection.raw_connection
 
         result = raw_conn.query(select_sql, stream: true, cache_rows: false, as: :hash)
-        result.each do |mysql_row|
-          record = build_row_object_mysql(mysql_row)
-          block.call(record)
+        begin
+          result.each do |mysql_row|
+            record = build_row_object_mysql(mysql_row)
+            block.call(record)
+          end
+        ensure
+          # Discards unread rows so the connection can run the next query after an error or break.
+          result.free
         end
       end
 

data/lib/simple_query/stream/postgres_stream.rb

@@ -3,17 +3,27 @@
 module SimpleQuery
   module Stream
     module PostgresStream
+      PQTRANS_IDLE = 0 # PG::PQTRANS_IDLE
+
       # rubocop:disable Metrics/MethodLength
       def stream_each_postgres(batch_size, &block)
+        validate_postgres_stream_batch_size!(batch_size)
+
         select_sql = cached_sql
 
-        conn = ActiveRecord::Base.connection.raw_connection
+        conn = connection.raw_connection
         cursor_name = "simple_query_cursor_#{object_id}"
 
+        # Cursors need a transaction. Reuse the caller's one instead of committing it.
+        own_transaction = conn.transaction_status == PQTRANS_IDLE
+        cursor_declared = false
+        cursor_close_started = false
+        completed = false
+
         begin
-          conn.exec("BEGIN")
-          declare_sql = "DECLARE #{cursor_name} NO SCROLL CURSOR FOR #{select_sql}"
-          conn.exec(declare_sql)
+          conn.exec("BEGIN") if own_transaction
+          conn.exec("DECLARE #{cursor_name} NO SCROLL CURSOR FOR #{select_sql}")
+          cursor_declared = true
 
           loop do
             res = conn.exec("FETCH #{batch_size} FROM #{cursor_name}")
@@ -25,21 +35,45 @@ module SimpleQuery
             end
           end
 
+          cursor_close_started = true
           conn.exec("CLOSE #{cursor_name}")
-          conn.exec("COMMIT")
-        rescue StandardError => e
-          begin
-            conn.exec("ROLLBACK")
-          rescue StandardError
-            nil
+          conn.exec("COMMIT") if own_transaction
+          completed = true
+        ensure
+          # Also runs when the caller leaves the block early with break/return.
+          unless completed
+            abort_postgres_stream(conn, cursor_name, close_cursor: cursor_declared && !cursor_close_started,
+                                                     rollback: own_transaction)
           end
-          raise e
         end
       end
       # rubocop:enable Metrics/MethodLength
 
       private
 
+      def validate_postgres_stream_batch_size!(batch_size)
+        return if batch_size.is_a?(Integer) && batch_size.positive?
+
+        raise ArgumentError, "stream_each batch_size must be a positive Integer"
+      end
+
+      def abort_postgres_stream(conn, cursor_name, close_cursor:, rollback:)
+        close_postgres_stream_cursor(conn, cursor_name) if close_cursor
+        rollback_postgres_stream_transaction(conn) if rollback
+      end
+
+      def close_postgres_stream_cursor(conn, cursor_name)
+        conn.exec("CLOSE #{cursor_name}")
+      rescue StandardError
+        nil
+      end
+
+      def rollback_postgres_stream_transaction(conn)
+        conn.exec("ROLLBACK")
+      rescue StandardError
+        nil
+      end
+
       def build_row_object(pg_row)
         if @read_model_class
           obj = @read_model_class.allocate

data/lib/simple_query/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleQuery
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/simple_query.rb

@@ -19,6 +19,8 @@ require_relative "simple_query/clauses/aggregation_clause"
 module SimpleQuery
   extend ActiveSupport::Concern
 
+  class UnsupportedAdapterError < StandardError; end
+
   class Configuration
     attr_accessor :auto_include_ar
 
@@ -46,12 +48,16 @@ module SimpleQuery
     end
 
     def simple_scope(name, body = nil, &block)
-      raise ArgumentError, "Pass either a proc/lambda or a block, not both" if body && block_given?
+      raise ArgumentError, "Pass either a proc/lambda or a block, not both" if !body.nil? && block_given?
+
+      scope_body = body.nil? ? block : body
+      raise ArgumentError, "You must provide a block or a proc" if scope_body.nil?
+      raise ArgumentError, "simple_scope body must respond to #to_proc" unless scope_body.respond_to?(:to_proc)
 
-      scope_body = body || block
-      raise ArgumentError, "You must provide a block or a proc" unless scope_body
+      scope_proc = scope_body.to_proc
+      raise ArgumentError, "simple_scope body #to_proc must return a Proc" unless scope_proc.is_a?(Proc)
 
-      _simple_scopes[name.to_sym] = scope_body
+      _simple_scopes[name.to_sym] = scope_proc
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_query
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Alex Kholodniak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-30 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -17,9 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-    - - "<="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -27,9 +27,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-    - - "<="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.2'
 description: SimpleQuery provides a flexible and performant way to construct complex
   database queries in Ruby on Rails applications. It offers an intuitive interface
   for building queries with joins, conditions, and aggregations, while potentially