activerecord-quick_read 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d401b9ac50f22d00aeecc23fa0b526b6be514bd0ff16ef9b59de596e43b26ba
-  data.tar.gz: e62a73b6cd6295759857c0a1600bd012e552dcdf6594cb9512678296e627311c
+  metadata.gz: 6d2a22ddf1957e253d53140f7ede9c14b6e329d707f4e4be8c7c6752b9bedfc8
+  data.tar.gz: d7b7b455816cccc89bbe69a83a07ec448a4f84756469838f8ba614a2c84b0735
 SHA512:
-  metadata.gz: 994202293a9083b9bc13fb25707abea8cfd455eefa7804065a6ce2ebb80f42f258a4db8017825fec312dce6e999560f6c349c2edbdd1be264067c80ec8a082c7
-  data.tar.gz: 357fee568bb033ed9778413d70e41a901c7b528382c24bda22f45cffff84ffecde43821c7a24a96660cda6117794187c98b0f6f1ba61e7966e9d7557e27d2bd9
+  metadata.gz: 34771e716d9b34b9e9f56437960206462f92157bf562f8e2a71d09ca2b3ec069300abd1d7a5aad5bee5e0f4f1e9a9a2dfbe04fd2886539e72b00a920df14b1e1
+  data.tar.gz: a3dc6d0a256c59f0f83763fded7aa4fa2d8fbdf724b5accdcb80e949f9f419aca1827243f6d70b29227197fbd4659f82f1ae2c1549435216d76d48013370ac25

data/.ruby-version

@@ -1 +1 @@
-3.1.2
+3.4.7

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [1.2.1] - 2026-08-26
+
+- Fixed a missing `require "benchmark"` that broke `quick_reads` on Rails 8.1
+- Optimized `quick_build` (memoized the struct class and no longer mutates the input hash)
+- Switched `quick_reads` to `select_rows` (positional) for full-column reads, avoiding per-row hash allocation
+- Removed the runtime `benchmark` dependency in favor of `Process.clock_gettime`
+- Added benchmarks and updated the README performance claims
+
+## [1.2.0] - 2026-08-26
+
+- Added support for older Rails 5 (`parent` fallback for `module_parent`)
+- Removed the `activerecord` version bounds, enabling Rails 8.x (e.g. 8.0.5.1) that were previously excluded by `<= 8`
+- Fixed `quick_read` and `quick_reads` when called directly on a model
+- Expanded the README and test suite
+
 ## [0.1.0] - 2023-04-21
 
 - Initial release

data/Gemfile

@@ -9,4 +9,17 @@ gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
 
+gem "benchmark-ips"
+
+gem "activerecord", "~> 8.1"
+
+gem "sqlite3", "~> 2.1"
+
 gem "standard", "~> 1.3"
+
+# Gems extracted from Ruby's stdlib in Ruby 3.4+ that Rails 7.0 still requires
+gem "mutex_m"
+gem "base64"
+gem "bigdecimal"
+gem "racc"
+gem "ostruct"

data/Gemfile.lock

@@ -1,33 +1,54 @@
 PATH
   remote: .
   specs:
-    activerecord-quick_read (1.0.0)
-      activerecord (>= 5, <= 8)
+    activerecord-quick_read (1.2.1)
+      activerecord
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (7.0.4.3)
-      activesupport (= 7.0.4.3)
-    activerecord (7.0.4.3)
-      activemodel (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-    activesupport (7.0.4.3)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+    activemodel (8.1.3.1)
+      activesupport (= 8.1.3.1)
+    activerecord (8.1.3.1)
+      activemodel (= 8.1.3.1)
+      activesupport (= 8.1.3.1)
+      timeout (>= 0.4.0)
+    activesupport (8.1.3.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
       minitest (>= 5.1)
-      tzinfo (~> 2.0)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     ast (2.4.2)
-    concurrent-ruby (1.2.2)
+    base64 (0.3.0)
+    benchmark-ips (2.15.1)
+    bigdecimal (4.1.2)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
     diff-lcs (1.5.0)
-    i18n (1.12.0)
+    drb (2.2.3)
+    i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
     language_server-protocol (3.17.0.3)
-    minitest (5.18.0)
+    logger (1.7.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    mutex_m (0.3.0)
+    ostruct (0.6.3)
     parallel (1.23.0)
     parser (3.2.2.0)
       ast (~> 2.4.1)
+    prism (1.9.0)
+    racc (1.8.1)
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.8.0)
@@ -61,23 +82,35 @@ GEM
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    sqlite3 (2.9.6-arm64-darwin)
     standard (1.27.0)
       language_server-protocol (~> 3.17.0.2)
       rubocop (~> 1.50.2)
       rubocop-performance (~> 1.16.0)
+    timeout (0.6.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.4.2)
+    uri (1.1.1)
 
 PLATFORMS
   arm64-darwin-22
-  ruby
+  arm64-darwin-23
 
 DEPENDENCIES
+  activerecord (~> 8.1)
   activerecord-quick_read!
+  base64
+  benchmark-ips
+  bigdecimal
+  mutex_m
+  ostruct
+  racc
   rake (~> 13.0)
   rspec (~> 3.0)
+  sqlite3 (~> 2.1)
   standard (~> 1.3)
 
 BUNDLED WITH
-   2.4.12
+  4.0.19

data/README.md

@@ -1,15 +1,39 @@
 # ActiveRecord::QuickRead
 
-Makes rails go _faster_. Improve read times 4x!
+[![Gem Version](https://badge.fury.io/rb/activerecord-quick_read.svg)](https://badge.fury.io/rb/activerecord-quick_read)
+
+Makes Rails go faster. Speedups scale with the size and complexity of your models, up to ~13x.
 
 ### How does it work?
 
-Skips active record instantiation, query just the results and use them as plain hashes, converted
-to structs with the same attributes as your model. The structs will gracefully upgrade to full
-version of your model, in the event that you need to update them.
+A normal ActiveRecord query does more than run SQL. Once the rows come back, ActiveRecord
+instantiates a model object for **every** row: allocating the object, running `initialize`,
+typecasting each column, setting up dirty tracking, and evaluating any `after_initialize` callbacks.
+For large result sets that per-row work adds up fast, and you end up paying for features you may not
+even use (like attribute change tracking) when all you wanted was to *read* the data.
 
-## Installation
+`quick_read` sidesteps all of that. It runs the exact same scoped SQL, but reads the raw rows with
+`connection.select_rows`, which returns each row as a plain array of values instead of the
+column-keyed hashes that `select_all` builds. Each array is then mapped positionally to a lightweight
+`Struct` whose members mirror the model's columns:
 
+```ruby
+# the Lite class generated for your model, e.g.:
+Report::Lite = Struct.new(:id, :message, :status, :created_at, :updated_at)
+```
+
+Most of the speed comes from what's *not* allocated: no model objects, no per-row hash, no
+typecasting, no dirty tracking, and no `after_initialize` callbacks. The struct is built directly
+from the raw row values. The result is the same data you asked for, returned faster when you read
+and serialize it. The speedup grows with the size and complexity of your model.
+
+The structs are *upgradeable*, not throwaway. Each `Lite` instance knows its source model and can
+lazily materialize a full ActiveRecord object on demand (via `method_missing`). So when you call a
+method the struct doesn't have (like `save`, `update`, or an association such as `report.author`) it
+transparently builds the real model behind the scenes and delegates to it. You only pay the cost of
+instantiation when you actually need to write, not when you're just reading.
+
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
@@ -21,36 +45,131 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-Use `#quick_read` on your ActiveRecord relations (or `#quick_reads` for all scoped records)
-Use `#quick_build` on your ActiveRecord models
+Add quickness to your models, then call `#quick_read` on an ActiveRecord relation to get a single
+record, or `#quick_reads` to get all scoped records. Use `#quick_build` on your models to build a
+lite instance from a hash.
 
-First, add quickness to your model:
-```
+### Enable on a single model
+
+```ruby
 class Report < ApplicationRecord
   extend ActiveRecord::QuickRead
 end
 ```
 
-Then you're ready to start going faster!
+### Enable for every model via ApplicationRecord
 
-It's as simple as:
+Instead of extending each model individually, extend `ApplicationRecord` once and every subclass
+inherits the quick read behavior:
 
 ```ruby
-Report.where(id: params[:id]).quick_read
+class ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+
+  extend ActiveRecord::QuickRead
+end
+```
+
+Because models aren't fully defined until boot, the `Lite` structs are built lazily after Rails
+initializes (via the included railtie). Any class that inherits from `ApplicationRecord`, even ones
+defined in engines or gems, automatically gets a `Lite` struct.
+
+As a side benefit, defining a struct requires reading the model's `column_names`, which warms
+ActiveRecord's schema cache and touches each model at boot. That in turn pre-warms the models, so
+your first real web requests don't pay the one-time schema-loading cost.
+
+### Reading
+
+```ruby
+# A single record
+report = Report.where(id: params[:id]).quick_read
+report.id          # => 1
+report.message     # => "All done"
+report.class       # => Report::Lite
+
+# All scoped records
+reports = Report.where(status: "done").quick_reads
+reports.first.title
 ```
 
-Load your batches 4x quicker:
+The returned `Report::Lite` is a struct with the same attributes (and `#to_h`) as your model:
+
 ```ruby
-Report.all.in_batches { |batch| batch.quick_reads.map(&:to_h) }
+Report.order(:created_at).quick_reads.map(&:to_h)
 ```
 
-Gracefully upgrade to a full-fledged ActiveRecord object, and even issue `update` statements:
+### Batching
+
+Load your batches faster, with bigger wins on larger, more complex models:
+
 ```ruby
-Report.all.quick_reads.each { |report| report.update(status: "done") if report.message = ?? }
+Report.in_batches do |batch|
+  batch.quick_reads.each do |report|
+    puts report.message
+  end
+end
+```
+
+### Building
+
+Build a lite instance from attributes without hitting the database:
+
+```ruby
+draft = Report.quick_build(id: 1, message: "hello")
+```
+
+### Upgrading to a full Active Record object
+
+Lite instances lazily upgrade to full-fledged ActiveRecord objects on demand. Calling any method the
+struct doesn't have (like `save`, `update`, or association accessors) transparently materializes the
+underlying model:
+
+```ruby
+Report.where(status: "queued").quick_reads.each do |report|
+  report.update(status: "done")
+end
+```
+
+```ruby
+report = Report.first.quick_read
+report.author          # => loads the belongs_to association on the full model
+report.save!
+```
+
+### Reloading
+
+Refresh a lite instance with fresh data from the database:
+
+```ruby
+report = Report.first.quick_read
+# ... the underlying row changes elsewhere ...
+report.reload
+report.message # => updated value
 ```
 
 It just works.
 
+## Benchmarks
+
+Measured against ActiveRecord 8.1 and SQLite with 10,000 records (see `benchmarks/read_benchmark.rb`).
+The model includes string, integer, date, decimal, text, and JSON-serialized columns to exercise
+typecasting:
+
+| Scenario | ActiveRecord | quick_read | Speedup |
+| --- | --- | --- | --- |
+| Read fields | 7.6 i/s | 63.7 i/s | ~8.3x |
+| Convert to hashes | 4.7 i/s | 56.4 i/s | ~13.7x |
+| Access associations | 1.1 i/s | 1.0 i/s | ~same |
+
+The win comes from skipping typecasting and instantiation when reading. The speedup depends on the
+size and complexity of your models: more columns, and heavier typecasting (dates, decimals, JSON,
+etc.), mean a bigger gap. When you access associations, each lite struct upgrades to a full
+ActiveRecord object (via `method_missing`), so performance is comparable to a plain ActiveRecord read.
+
+Run it yourself:
+
+    $ bundle exec ruby benchmarks/read_benchmark.rb
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -59,7 +178,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/activerecord-quick_read. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/activerecord-quick_read/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/ridiculous/activerecord-quick_reads. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/ridiculous/activerecord-quick_reads/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -67,4 +186,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the ActiveRecord::QuickRead project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/activerecord-quick_read/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the ActiveRecord::QuickRead project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ridiculous/activerecord-quick_reads/blob/main/CODE_OF_CONDUCT.md).

data/benchmarks/read_benchmark.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "benchmark/ips"
+require "active_record"
+require "activerecord/quick_read"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+ActiveRecord::Base.logger = nil
+
+ActiveRecord::Schema.define do
+  create_table :authors do |t|
+    t.string :name
+  end
+
+  create_table :reports do |t|
+    t.integer :author_id
+    t.string :message
+    t.string :status
+    t.integer :score
+    t.date :published_on
+    t.decimal :amount, precision: 10, scale: 2
+    t.text :body
+    t.text :payload
+    t.timestamps
+  end
+end
+
+class Author < ActiveRecord::Base
+  has_many :reports
+end
+
+class Report < ActiveRecord::Base
+  belongs_to :author
+
+  serialize :payload, coder: JSON
+
+  extend ActiveRecord::QuickRead
+end
+
+ROWS = Integer(ENV.fetch("ROWS", "10_000"))
+AUTHORS = Integer(ENV.fetch("AUTHORS", "100"))
+now = Time.now
+
+Author.insert_all(AUTHORS.times.map { |i| {name: "Author #{i}"} })
+
+Report.insert_all(
+  ROWS.times.map do |i|
+    {
+      message: "message #{i}",
+      status: i.even? ? "done" : "queued",
+      score: i,
+      author_id: (i % AUTHORS) + 1,
+      published_on: "2026-08-26",
+      amount: 1234.56,
+      body: "lorem ipsum dolor sit amet, consectetur adipiscing elit #{i}",
+      payload: {foo: "bar", baz: i, nested: {a: [1, 2, 3]}},
+      created_at: now,
+      updated_at: now
+    }
+  end
+)
+
+puts "Benchmarking #{ROWS} records\n\n"
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("activerecord read") do
+    Report.all.each do |r|
+      r.message
+      r.status
+      r.score
+      r.published_on
+      r.amount
+      r.body
+      r.payload
+      r.created_at
+      r.updated_at
+    end
+  end
+
+  x.report("quick_reads read") do
+    Report.quick_reads.each do |r|
+      r.message
+      r.status
+      r.score
+      r.published_on
+      r.amount
+      r.body
+      r.payload
+      r.created_at
+      r.updated_at
+    end
+  end
+
+  x.report("activerecord attributes") { Report.all.map(&:attributes) }
+  x.report("quick_reads to_h") { Report.quick_reads.map(&:to_h) }
+
+  x.report("activerecord association") { Report.all.each { |r| r.author&.name } }
+  x.report("quick_reads association") { Report.quick_reads.each { |r| r.author&.name } }
+
+  x.compare!
+end

data/lib/activerecord/quick_read/lite_base.rb

@@ -28,7 +28,7 @@ module ActiveRecord
 
       # Since the struct that includes this module is defined within the model's namespace
       def _ar_model
-        self.class.module_parent
+        self.class.respond_to?(:module_parent) ? self.class.module_parent : self.class.parent
       end
     end
   end

data/lib/activerecord/quick_read/railtie.rb

@@ -4,7 +4,7 @@ module ActiveRecord
       config.after_initialize do
         QuickRead.define_lite_structs
       rescue => e
-        ActiveRecord::Base.logger.debug("QuickRead") { "Failed to define lite structs #{e.message}" }
+        ActiveRecord::Base.logger.debug { "QuickRead: Failed to define lite structs #{e.message}" }
       end
     end
   end

data/lib/activerecord/quick_read/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   module QuickRead
-    VERSION = "1.1.0"
+    VERSION = "1.2.1"
   end
 end

data/lib/activerecord/quick_read.rb

@@ -23,7 +23,7 @@ module ActiveRecord
 
       QuickRead.define_lite_struct(model)
     rescue => e
-      ActiveRecord::Base.logger.debug("QuickRead") { "Failed to define quick models #{e.message}" }
+      ActiveRecord::Base.logger.debug { "QuickRead: Failed to define quick models #{e.message}" }
     end
 
     def self.models
@@ -33,13 +33,13 @@ module ActiveRecord
     def self.define_lite_structs
       return if QuickRead.models.empty?
 
-      ActiveRecord::Base.logger.debug("QuickRead") { "Defining #{QuickRead.models.size} quick models" }
-      time = Benchmark.realtime do
-        while model = models.pop
-          define_lite_struct(model)
-        end
+      ActiveRecord::Base.logger.debug { "QuickRead: Defining #{QuickRead.models.size} quick models" }
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      while (model = models.pop)
+        define_lite_struct(model)
       end
-      ActiveRecord::Base.logger.debug("QuickRead") { "Defining quick models took #{time.round(4)}s" }
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      ActiveRecord::Base.logger.debug { "QuickRead: Defining quick models took #{elapsed.round(4)}s" }
     end
 
     def self.define_lite_struct(model)
@@ -59,16 +59,22 @@ module ActiveRecord
     end
 
     def quick_build(attrs = {})
-      klass = const_get(:Lite)
-      klass.new(*attrs.symbolize_keys!.values_at(*klass.members))
+      klass = @quick_read_lite ||= const_get(:Lite)
+      klass.new(*klass.members.map { |member| attrs.fetch(member) { attrs[member.to_s] } })
     end
 
     def quick_reads
-      connection.select_all(current_scope.to_sql).map { |attrs| quick_build(attrs) }
+      scope = current_scope || all
+      klass = @quick_read_lite ||= const_get(:Lite)
+      if scope.select_values.empty?
+        connection.select_rows(scope.to_sql).map { |values| klass.new(*values) }
+      else
+        connection.select_all(scope.to_sql).map { |attrs| quick_build(attrs) }
+      end
     end
 
     def quick_read
-      current_scope.limit(1).quick_reads.first
+      (current_scope || all).limit(1).quick_reads.first
     end
 
     # Instantiate a new ActiveRecord object from a plain hash, marked as persisted, no changes, typecast

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-quick_read
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Ryan Buckley
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,21 +15,17 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: '8'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: '8'
-description: Makes rails go _faster_. Improve read times 4x!
+        version: '0'
+description: Faster ActiveRecord reads. Skips model instantiation and returns lightweight
+  objects (with untypecast values) just for reading. Fallback to full-fledged ActiveRecords
+  on method_missing.
 email:
 - ridiculous@hey.com
 executables: []
@@ -48,6 +43,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmarks/read_benchmark.rb
 - lib/activerecord/quick_read.rb
 - lib/activerecord/quick_read/lite_base.rb
 - lib/activerecord/quick_read/railtie.rb
@@ -59,7 +55,6 @@ metadata:
   homepage_uri: https://github.com/ridiculous/activerecord-quick_reads
   source_code_uri: https://github.com/ridiculous/activerecord-quick_reads
   changelog_uri: https://github.com/ridiculous/activerecord-quick_reads/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -74,8 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
-summary: Makes rails go _faster_. Improve read times 4x!
+summary: Speed up ActiveRecord reads by skipping model instantiation.
 test_files: []