occams-record 1.4.0.pre.beta1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 662bd65e909a1d957ebdbbd2d3bec3fe96fb45aac2117a786c9a3ad02b03259b
-  data.tar.gz: abeb69ff706dbb11f3fae3672ae60c407080f418fce7330779a7b550915aa886
+  metadata.gz: d09d84ccc4713f32959380098b74112e45fa6a84a47698f1cec2d6fc4c4886a9
+  data.tar.gz: b94244c91ed19b02cfb36ff02c72b6510ab38da73f7d76e13e8104713fa2ed03
 SHA512:
-  metadata.gz: 8981d9c820b64ebeca28dcbe3ab7ac44e35d8ec7e14df201e890ccf6cf1cf1888d6f78ba6cac001f1a9c458f604189b1aafaf7ff644288499faf5d5afeb896c3
-  data.tar.gz: cdd61c50313a964db4ebdb271dbb875fc4ea888dd0b57df78be78d043e655e04e821e0cef8d9b60034e90866289a0d764f72a7728a18f46c778e511101b72f4a
+  metadata.gz: 950a0baa705302727a9ab9d20bb286e2fdc44cdd8b6aee3edb1b02c0a640786beca3492e799bcf4efe87c3a01289c6f4edb2daa07dc24650a5c29d6276733737
+  data.tar.gz: dc07af2830bf268dac941834d36bc1cca3ffe64f5e1e3eadfe901b11fe1fcf545ba9804da4fd683697ee26201faf0936b06aaa203ac661aa14eed69b036e2109

data/README.md

@@ -9,6 +9,7 @@ OccamsRecord is a high-efficiency, advanced query library for use alongside Acti
 * 3x-5x faster than ActiveRecord queries, *minimum*.
 * Uses 1/3 the memory of ActiveRecord query results.
 * Eliminates the N+1 query problem. (This often exceeds the baseline 3x-5x gain.)
+* Support for cursors (Postgres only, new in v1.4.0)
 
 ### 2) Supercharged querying & eager loading
 
@@ -19,7 +20,9 @@ Continue using ActiveRecord's query builder, but let Occams take over running th
 ```ruby
 OccamsRecord
   .query(User.active)
-  .eager_load(:orders, ->(q) { q.where("created_at >= ?", date).order("created_at DESC") })
+  .eager_load(:orders) {
+    scope { |q| q.where("created_at >= ?", date).order("created_at DESC") }
+  }
 ```
 
 **Use `ORDER BY` with `find_each`/`find_in_batches`**
@@ -32,6 +35,16 @@ OccamsRecord
   }
 ```
 
+**Use cursors**
+
+```ruby
+OccamsRecord
+  .query(Order.order("created_at DESC"))
+  .find_each_with_cursor { |order|
+    ...
+  }
+```
+
 **Use `find_each`/`find_in_batches` with raw SQL**
 
 ```ruby
@@ -147,24 +160,71 @@ orders = OccamsRecord
   .query(q)
   # Only SELECT the columns you need. Your DBA will thank you.
   .eager_load(:customer, select: "id, name")
-  
-  # A Proc can use ActiveRecord's query builder
-  .eager_load(:line_items, ->(q) { q.active.order("created_at") }) {
+
+  # Or use 'scope' to access the full power of ActiveRecord's query builder.
+  # Here, only 'active' line items will be returned, and in a specific order.
+  .eager_load(:line_items) {
+    scope { |q| q.active.order("created_at") }
+
     eager_load(:product)
     eager_load(:something_else)
   }
   .run
 ```
 
-Occams Record also supports loading ad hoc associations using raw SQL. We'll get to that in the next section.
+Occams Record also supports loading ad hoc associations using raw SQL. We'll get to that in a later section.
+
+## Query with cursors
+
+`find_each_with_cursor`/`find_in_batches_with_cursor` work like `find_each`/`find_in_batches`, except they use cursors. For large data sets, cursors offer a noticible speed boost. Postgres only.
+
+```ruby
+OccamsRecord
+  .query(q)
+  .eager_load(:customer)
+  .find_each_with_cursor do |order|
+    ...
+  end
+```
+
+The `cursor.open` method allows lower level access to cursor behavior. See `OccamsRecord::Cursor` for more info.
+
+```ruby
+orders = OccamsRecord
+  .query(q)
+  .eager_load(:customer)
+  .cursor
+  .open do |cursor|
+    cursor.move(:forward, 300)
+    cursor.fetch(:forward, 100)
+  end
+```
 
 ## Raw SQL queries
 
 ActiveRecord has raw SQL escape hatches like `find_by_sql` and `exec_query`, but they give up critical features like eager loading and `find_each`/`find_in_batches`. Occams Record's escape hatches don't make you give up anything.
 
-**Batched loading**
+**Batched loading with cursors**
+
+`find_each_with_cursor`, `find_in_batches_with_cursor`, and `cursor.open` are all available.
+
+```ruby
+OccamsRecord
+  .sql("
+    SELECT * FROM orders
+    WHERE order_date > %{date}
+    ORDER BY order_date DESC, id
+  ", {
+    date: 10.years.ago
+  })
+  .find_each_with_cursor(batch_size: 1000) do |order|
+    ...
+  end
+```
+
+**Batched loading without cursors**
 
-To use `find_each`/`find_in_batches` you must provide the limit and offset statements yourself; Occams will provide the values. Also, notice that the binding syntax is a bit different (it uses Ruby's built-in named string substitution).
+If your database doesn't support cursors, you can use `find_each`/`find_in_batches`. Just provide `LIMIT` and `OFFSET` (see below), and Occams will plug in the right numbers.
 
 ```ruby
 OccamsRecord
@@ -299,7 +359,7 @@ bundle install
 bundle exec rake test
 
 # test against Postgres
-TEST_DATABASE_URL=postgres://postgres@localhost:5432/occams_record bundle exec rake test
+TEST_DATABASE_URL=postgresql://postgres@localhost:5432/occams_record bundle exec rake test
 
 # test against MySQL
 TEST_DATABASE_URL=mysql2://root:@127.0.0.1:3306/occams_record bundle exec rake test

data/lib/occams-record/batches/offset_limit/raw_query.rb

@@ -1,6 +1,9 @@
 module OccamsRecord
   module Batches
     module OffsetLimit
+      #
+      # Implements batched loading for pure SQL.
+      #
       class RawQuery
         def initialize(conn, sql, binds, use: nil, query_logger: nil, eager_loaders: nil)
           @conn, @sql, @binds = conn, sql, binds

data/lib/occams-record/batches/offset_limit/scoped.rb

@@ -1,9 +1,9 @@
 module OccamsRecord
-  #
-  # Methods for building batch finding methods. It expects "model" and "scope" methods to be present.
-  #
   module Batches
     module OffsetLimit
+      #
+      # Implements batched loading for ActiveRecord model scopes.
+      #
       class Scoped
         def initialize(model, scope, use: nil, query_logger: nil, eager_loaders: nil)
           @model, @scope = model, scope

data/lib/occams-record/cursor.rb

@@ -1,10 +1,10 @@
 require 'securerandom'
 
 module OccamsRecord
-#
-# An interface to database cursors. Supported databases:
-#   * PostgreSQL
-#
+  #
+  # An interface to database cursors. Supported databases:
+  #   * PostgreSQL
+  #
   class Cursor
     # @private
     SCROLL = {

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

@@ -19,7 +19,7 @@ module OccamsRecord
       # @yield perform eager loading on *this* association (optional)
       #
       def initialize(ref, scope = nil, use: nil, as: nil, optimizer: :select, &builder)
-        @ref, @scope, @use, @as = ref, scope, use, as
+        @ref, @scopes, @use, @as = ref, Array(scope), use, as
         @model = ref.klass
         @name = (as || ref.name).to_s
         @eager_loaders = EagerLoaders::Context.new(@model)
@@ -27,6 +27,20 @@ module OccamsRecord
         instance_exec(&builder) if builder
       end
 
+      #
+      # An alternative to passing a "scope" lambda to the constructor. Your block is passed the query
+      # so you can call select, where, order, etc on it.
+      #
+      # If you call scope multiple times, the results will be additive.
+      #
+      # @yield [ActiveRecord::Relation] a relation to modify with select, where, order, etc
+      # @return self
+      #
+      def scope(&scope)
+        @scopes << scope if scope
+        self
+      end
+
       #
       # Run the query and merge the results into the given rows.
       #
@@ -71,7 +85,7 @@ module OccamsRecord
       def base_scope
         q = @ref.klass.all
         q = q.instance_exec(&@ref.scope) if @ref.scope
-        q = @scope.(q) if @scope
+        q = @scopes.reduce(q) { |acc, scope| scope.(acc) }
         q
       end
     end

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

@@ -115,7 +115,7 @@ module OccamsRecord
 
       def build_loader!(assoc, custom_name, scope, select, use, optimizer, builder)
         build_loader(assoc, custom_name, scope, select, use, optimizer, builder) ||
-          raise("OccamsRecord: No assocation `:#{assoc}` on `#{@model.name}` or subclasses")
+          raise("OccamsRecord: No association `:#{assoc}` on `#{@model.name}` or subclasses")
       end
 
       def build_loader(assoc, custom_name, scope, select, use, optimizer, builder)

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

@@ -17,7 +17,7 @@ module OccamsRecord
       # @yield perform eager loading on *this* association (optional)
       #
       def initialize(ref, scope = nil, use: nil, as: nil, optimizer: nil, &builder)
-        @ref, @scope, @use = ref, scope, use
+        @ref, @scopes, @use = ref, Array(scope), use
         @name = (as || ref.name).to_s
         @foreign_type = @ref.foreign_type.to_sym
         @foreign_key = @ref.foreign_key.to_sym
@@ -25,6 +25,20 @@ module OccamsRecord
         instance_exec(&builder) if builder
       end
 
+      #
+      # An alternative to passing a "scope" lambda to the constructor. Your block is passed the query
+      # so you can call select, where, order, etc on it.
+      #
+      # If you call scope multiple times, the results will be additive.
+      #
+      # @yield [ActiveRecord::Relation] a relation to modify with select, where, order, etc
+      # @return self
+      #
+      def scope(&scope)
+        @scopes << scope if scope
+        self
+      end
+
       #
       # Run the query and merge the results into the given rows.
       #
@@ -83,7 +97,7 @@ module OccamsRecord
       def base_scope(model)
         q = model.all
         q = q.instance_exec(&@ref.scope) if @ref.scope
-        q = @scope.(q) if @scope
+        q = @scopes.reduce(q) { |acc, scope| scope.(acc) }
         q
       end
     end

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # @private
-  VERSION = "1.4.0-beta1".freeze
+  VERSION = "1.5.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 1.4.0.pre.beta1
+  version: 1.5.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-05-22 00:00:00.000000000 Z
+date: 2023-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -94,11 +94,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: The missing high-efficiency query API for ActiveRecord