occams-record 1.1.4 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c5eba9d662af4ceea78d6d50d9649dc88faebb18ab8f2d9e0704f4fe5367985
-  data.tar.gz: cd5aa76eeb6a5f89ed65bd10549e468173dc2f8aa896346925b4b3752cf7858e
+  metadata.gz: a1e01657287159a2aa1a27ff66c1932ae83235ad0140dbaafd58103862ddaa8f
+  data.tar.gz: ec9530c3844cd79739d1a2387031654e85f4a2a127d948df0c537431aa235ed5
 SHA512:
-  metadata.gz: d48d4389624f627302877ca6bcda1e7b1dc19facd4b54b4d255bb11b75d1f79149c1e79aff271b715eca0f43e03819e5aaaebc2897a7b0b29696eb20e0bcc4fc
-  data.tar.gz: ab8fdfddb10f751aa74274efc6229e5c24d32ec968fe8c88f30fd9af760652d9a75a2cc2bc17c29e3afcdd41b2d6f78e7cda60d485b6844458267beda2839aa2
+  metadata.gz: a0303147fa894e42d0642020a4a207c67b3a79fa3fc2dfa1b9be819224c8eee6bb261bfa2079a073cd1894f744b4995f307afff594f458c5b7ae7574b26b0d32
+  data.tar.gz: bf81dc3eeb78cbf9ed99740a1c4c8e1c71287f4af278c2a623d9220384460f952ccc50fa835393ef3fd416fa0019fccc6a6e41d0c8dbd77c637f08689ca5c585

data/README.md

@@ -12,14 +12,14 @@ OccamsRecord is a high-efficiency, advanced query library for use alongside Acti
 
 ### 2) Supercharged querying & eager loading
 
-Continue using ActiveRecord's query builder, but let Occams take over eager loading and raw SQL calls. None of the examples below are possible with ActiveRecord, but OccamsRecord won't limit you. (More complete examples are shown later, but these should whet your appetite.)
+Continue using ActiveRecord's query builder, but let Occams take over running them, eager loading, and raw SQL calls. None of the examples below are possible with ActiveRecord, but OccamsRecord makes them trivial. (More complete examples are shown later, but these should whet your appetite.)
 
 **Customize the SQL used to eager load associations**
 
 ```ruby
 OccamsRecord.
   query(User.active).
-  eager_load(:orders, ->(q) { q.where("created_at >= ?", date })
+  eager_load(:orders, ->(q) { q.where("created_at >= ?", date).order("created_at DESC") })
 ```
 
 **Use `ORDER BY` with `find_each`/`find_in_batches`**
@@ -97,6 +97,8 @@ gem 'occams-record'
 
 Full documentation is available at [rubydoc.info/gems/occams-record](http://www.rubydoc.info/gems/occams-record).
 
+Code lives at at [github.com/jhollinger/occams-record](https://github.com/jhollinger/occams-record). Contributions welcome!
+
 Build your queries like normal, using ActiveRecord's excellent query builder. Then pass them off to Occams Record.
 
 ```ruby
@@ -290,21 +292,27 @@ On the other hand, Active Record makes it *very* easy to forget to eager load as
 
 # Testing
 
-To run the tests, simply run:
-
 ```bash
 bundle install
+
+# test against SQLite
 bundle exec rake test
+
+# test against Postgres
+TEST_DATABASE_URL=postgres://postgres@localhost:5432/occams_record bundle exec rake test
 ```
 
-By default, bundler will install the latest (supported) version of ActiveRecord. To specify a version to test against, run:
+**Test against all supported ActiveRecord versions**
 
 ```bash
-AR=5.2 bundle update activerecord
-bundle exec rake test
-```
+bundle exec appraisal install
 
-Look inside `Gemfile` to see all testable versions.
+# test against SQLite
+bundle exec appraisal rake test
+
+# test against Postgres
+TEST_DATABASE_URL=postgres://postgres@localhost:5432/occams_record bundle exec appraisal rake test
+```
 
 # License
 

data/lib/occams-record/batches.rb

@@ -7,17 +7,19 @@ module OccamsRecord
     # Load records in batches of N and yield each record to a block if given. If no block is given,
     # returns an Enumerator.
     #
-    # NOTE Unlike ActiveRecord's find_each, ORDER BY is respected. It will be run inside
-    # of a transaction to ensure batch integrity.
+    # NOTE Unlike ActiveRecord's find_each, ORDER BY is respected. The primary key will be appended
+    # to the ORDER BY clause to help ensure consistent batches. Additionally, it will be run inside
+    # of a transaction.
     #
     # @param batch_size [Integer]
     # @param use_transaction [Boolean] Ensure it runs inside of a database transaction
+    # @param append_order_by [String] Append this column to ORDER BY to ensure consistent results. Defaults to the primary key. Pass false to disable.
     # @yield [OccamsRecord::Results::Row]
     # @return [Enumerator] will yield each record
     #
-    def find_each(batch_size: 1000, use_transaction: true)
+    def find_each(batch_size: 1000, use_transaction: true, append_order_by: nil)
       enum = Enumerator.new { |y|
-        batches(of: batch_size, use_transaction: use_transaction).each { |batch|
+        batches(of: batch_size, use_transaction: use_transaction, append_order_by: append_order_by).each { |batch|
           batch.each { |record| y.yield record }
         }
       }
@@ -38,11 +40,12 @@ module OccamsRecord
     #
     # @param batch_size [Integer]
     # @param use_transaction [Boolean] Ensure it runs inside of a database transaction
+    # @param append_order_by [String] Append this column to ORDER BY to ensure consistent results. Defaults to the primary key. Pass false to disable.
     # @yield [OccamsRecord::Results::Row]
     # @return [Enumerator] will yield each batch
     #
-    def find_in_batches(batch_size: 1000, use_transaction: true)
-      enum = batches(of: batch_size, use_transaction: use_transaction)
+    def find_in_batches(batch_size: 1000, use_transaction: true, append_order_by: nil)
+      enum = batches(of: batch_size, use_transaction: use_transaction, append_order_by: append_order_by)
       if block_given?
         enum.each { |batch| yield batch }
       else
@@ -60,30 +63,44 @@ module OccamsRecord
     #
     # @param of [Integer] batch size
     # @param use_transaction [Boolean] Ensure it runs inside of a database transaction
+    # @param append_order_by [String] Append this column to ORDER BY to ensure consistent results. Defaults to the primary key. Pass false to disable.
     # @return [Enumerator] yields batches
     #
-    def batches(of:, use_transaction: true)
+    def batches(of:, use_transaction: true, append_order_by: nil)
+      append_order =
+        case append_order_by
+        when false then nil
+        when nil then model.primary_key
+        else append_order_by
+        end
+
       Enumerator.new do |y|
         if use_transaction and model.connection.open_transactions == 0
           model.connection.transaction {
-            run_batches y, of
+            run_batches y, of, append_order
           }
         else
-          run_batches y, of
+          run_batches y, of, append_order
         end
       end
     end
 
-    def run_batches(y, of)
+    def run_batches(y, of, append_order_by = nil)
       limit = scope.limit_value
       batch_size = limit && limit < of ? limit : of
 
       offset = scope.offset_value || 0
       out_of_records, count = false, 0
+      order_by =
+        if append_order_by
+          append_order_by.to_s == model.primary_key.to_s ? append_order_by.to_sym : append_order_by
+        end
 
       until out_of_records
         l = limit && batch_size > limit - count ? limit - count : batch_size
-        q = scope.offset(offset).limit(l)
+        q = scope
+        q = q.order(order_by) if order_by
+        q = q.offset(offset).limit(l)
         results = Query.new(q, use: @use, query_logger: @query_logger, eager_loaders: @eager_loaders).run
 
         y.yield results if results.any?

data/lib/occams-record/connection.rb

@@ -0,0 +1,7 @@
+module OccamsRecord
+  class Connection
+    def initialize(model, role = nil)
+      @model, @role = model, role
+    end
+  end
+end

data/lib/occams-record/eager_loaders/belongs_to.rb

@@ -20,6 +20,7 @@ module OccamsRecord
             raise MissingColumnError.new(row, e.name)
           end
         }.compact.uniq
+        ids.sort! if $occams_record_test
 
         q = base_scope.where(@ref.association_primary_key => ids)
         yield q if ids.any?
@@ -33,7 +34,7 @@ module OccamsRecord
       #
       def merge!(assoc_rows, rows)
         Merge.new(rows, name).
-          single!(assoc_rows, {@ref.foreign_key.to_s => @ref.active_record_primary_key.to_s})
+          single!(assoc_rows, {@ref.foreign_key.to_s => @ref.association_primary_key.to_s})
       end
     end
   end

data/lib/occams-record/eager_loaders/has_one.rb

@@ -20,6 +20,7 @@ module OccamsRecord
             raise MissingColumnError.new(row, e.name)
           end
         }.compact.uniq
+        ids.sort! if $occams_record_test
 
         q = base_scope.where(@ref.foreign_key => ids)
         q.where!(@ref.type => rows[0].class&.model_name) if @ref.options[:as]

data/lib/occams-record/eager_loaders/polymorphic_belongs_to.rb

@@ -55,6 +55,7 @@ module OccamsRecord
           next if type.nil? or type == ""
           model = type.constantize
           ids = rows_of_type.map(&@foreign_key).uniq
+          ids.sort! if $occams_record_test
           q = base_scope(model).where(@ref.active_record_primary_key => ids)
           yield q if ids.any?
         end

data/lib/occams-record/raw_query.rb

@@ -4,7 +4,7 @@ module OccamsRecord
   # a Hash of binds. While this doesn't offer an additional performance boost, it's a nice way to
   # write safe, complicated SQL by hand while also supporting eager loading.
   #
-  #   results = OccamsRecord.sql(
+  #   results = OccamsRecord.sql("
   #     SELECT * FROM widgets
   #     WHERE category_id = %{cat_id}
   #   ", {
@@ -13,7 +13,6 @@ module OccamsRecord
   #
   # If you want to do eager loading, you must first the define a model to pull the associations from (unless
   # you're using the raw SQL eager loaders `eager_load_one` or `eager_load_many`).
-  # NOTE If you're using SQLite, you must *always* specify the model.
   #
   #   results = OccamsRecord.
   #     sql("
@@ -27,8 +26,20 @@ module OccamsRecord
   #     run
   #
   # NOTE To use find_each/find_in_batches, your SQL string must include 'LIMIT %{batch_limit} OFFSET %{batch_offset}',
-  # and an ORDER BY is strongly recomended.
-  # OccamsRecord will provide the bind values for you.
+  # and an ORDER BY is strongly recomended. OccamsRecord will provide the bind values for you.
+  #
+  # NOTE There is variation of the types of values returned (e.g. a Date object vs a date string) depending on the database
+  # and ActiveRecord version being used:
+  #
+  # Postgres always returns native Ruby types.
+  #
+  # SQLite will return native types for the following: integers, floats, string/text.
+  # For booleans it will return 0|1 for AR 6+, and "t|f" for AR 5-.
+  # Dates and times will be ISO8601 formatted strings.
+  # It is possible to coerce the SQLite adapter into returning native types for everything IF they're columns of a table
+  # that you have an AR model for. e.g. if you're selecting from the widgets, table: `OccamsRecord.sql("...").model(Widget)...`.
+  #
+  # MySQL ?
   #
   # @param sql [String] The SELECT statement to run. Binds should use Ruby's named string substitution.
   # @param binds [Hash] Bind values (Symbol keys)
@@ -156,7 +167,7 @@ module OccamsRecord
     # @param use_transaction [Boolean] Ensure it runs inside of a database transaction
     # @return [Enumerator] yields batches
     #
-    def batches(of:, use_transaction: true)
+    def batches(of:, use_transaction: true, append_order_by: nil)
       unless @sql =~ /LIMIT\s+%\{batch_limit\}/i and @sql =~ /OFFSET\s+%\{batch_offset\}/i
         raise ArgumentError, "When using find_each/find_in_batches you must specify 'LIMIT %{batch_limit} OFFSET %{batch_offset}'. SQL statement: #{@sql}"
       end

data/lib/occams-record/results/results.rb

@@ -36,14 +36,20 @@ module OccamsRecord
         attr_accessor(*association_names)
 
         # Build a getter for each attribute returned by the query. The values will be type converted on demand.
-        model_column_types = model ? model.attributes_builder.types : {}
+        model_column_types = model ? model.attributes_builder.types : nil
         self.columns.each_with_index do |col, idx|
-          type =
-            column_types[col] ||
-            model_column_types[col] ||
-            raise("OccamsRecord: Column `#{col}` does not exist on model `#{self.model_name}`")
-
-          case type.type
+          #
+          # NOTE there's lots of variation between DB adapters and AR versions here. Some notes:
+          # * Postgres AR < 6.1 `column_types` will contain entries for every column.
+          # * Postgres AR >= 6.1 `column_types` only contains entries for "exotic" types. Columns with "common" types have already been converted by the PG adapter.
+          # * SQLite `column_types` will always be empty. Some types will have already been convered by the SQLite adapter, but others will depend on
+          #   `model_column_types` for converstion. See test/raw_query_test.rb#test_common_types for examples.
+          # * MySQL ?
+          #
+          type = column_types[col] || model_column_types&.[](col)
+          case type&.type
+          when nil
+            define_method(col) { @raw_values[idx] }
           when :datetime
             define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx])&.in_time_zone }
           when :boolean

data/lib/occams-record/results/row.rb

@@ -152,7 +152,7 @@ module OccamsRecord
       def define_ids_reader!(assoc)
         model = self.class._model
         ref = model.reflections[assoc]
-        pkey = ref.association_primary_key.to_sym
+        pkey = ref.klass.primary_key.to_sym
 
         self.class.class_eval do
           define_method "#{assoc.singularize}_ids" do

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # Library version
-  VERSION = "1.1.4".freeze
+  VERSION = "1.2.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.2.1
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-12-17 00:00:00.000000000 Z
+date: 2021-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -19,7 +19,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,21 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.2'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A faster, lower-memory querying API for ActiveRecord that returns results
   as unadorned, read-only objects.
 email: jordan.hollinger@gmail.com
@@ -40,6 +54,7 @@ files:
 - README.md
 - lib/occams-record.rb
 - lib/occams-record/batches.rb
+- lib/occams-record/connection.rb
 - lib/occams-record/eager_loaders/ad_hoc_base.rb
 - lib/occams-record/eager_loaders/ad_hoc_many.rb
 - lib/occams-record/eager_loaders/ad_hoc_one.rb
@@ -81,8 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: The missing high-efficiency query API for ActiveRecord