occams-record 1.4.0.pre.beta1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 662bd65e909a1d957ebdbbd2d3bec3fe96fb45aac2117a786c9a3ad02b03259b
-  data.tar.gz: abeb69ff706dbb11f3fae3672ae60c407080f418fce7330779a7b550915aa886
+  metadata.gz: c1dc718c0f99f5ad039974f8db3bd1c5304e41a3b3275d26dd1d86235c7790fe
+  data.tar.gz: 8af374148ca1f1c8342b7eb8fdb30031d6c31a1d923a6e7cab55b96712ed2602
 SHA512:
-  metadata.gz: 8981d9c820b64ebeca28dcbe3ab7ac44e35d8ec7e14df201e890ccf6cf1cf1888d6f78ba6cac001f1a9c458f604189b1aafaf7ff644288499faf5d5afeb896c3
-  data.tar.gz: cdd61c50313a964db4ebdb271dbb875fc4ea888dd0b57df78be78d043e655e04e821e0cef8d9b60034e90866289a0d764f72a7728a18f46c778e511101b72f4a
+  metadata.gz: 54b539bc70b1fc92c087fbc91f7edbaa1eb4dabacfda80ca0afa4ccd4ac53e832d431f3c95e35785cfa7bd7075879c655ae54019c3f341255b4411929b5ae615
+  data.tar.gz: c1c9aed1007bcfeb0e577d08af6f86fa340e375fede08af03bd18fbc2538cfcbd4838fc5bd07c672fca6e02ca3c0ec9e8d442b3e3275deff58215dfba873df7a

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-beta1)
 
 ### 2) Supercharged querying & eager loading
 
@@ -32,6 +33,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
@@ -156,15 +167,59 @@ orders = OccamsRecord
   .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

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/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # @private
-  VERSION = "1.4.0-beta1".freeze
+  VERSION = "1.4.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.4.0
 platform: ruby
 authors:
 - Jordan Hollinger
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-22 00:00:00.000000000 Z
+date: 2022-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -83,7 +83,7 @@ homepage: https://jhollinger.github.io/occams-record/
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -94,12 +94,12 @@ 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
-signing_key:
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: The missing high-efficiency query API for ActiveRecord
 test_files: []