activerecord-quick_read 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1309eaf96974d8b58dcf9129d7562f9a4a768845f1b90ab14281cd71feeb9325
-  data.tar.gz: 82eed52c3a1fe90420610c53a8f613ead78d7ae38adfa9da9fc95ae32bc1717b
+  metadata.gz: 6d2a22ddf1957e253d53140f7ede9c14b6e329d707f4e4be8c7c6752b9bedfc8
+  data.tar.gz: d7b7b455816cccc89bbe69a83a07ec448a4f84756469838f8ba614a2c84b0735
 SHA512:
-  metadata.gz: 2881f4c609eed7c8758b0e7f40382e1f432be17fc0df25289d5a7a264bf657c8c9efd0e4801e0020780c2dc12289ff27c58e05a6a41a8fb557ce872cb4465463
-  data.tar.gz: 5f45b9b3d261d5c16e40cc5ff4493de991ce5e73a206e2e655f7dde7607c8ee14eae776ac667334eb44c0e67586bdde414208a5bc4850e9c5d74a9f203081acc
+  metadata.gz: 34771e716d9b34b9e9f56437960206462f92157bf562f8e2a71d09ca2b3ec069300abd1d7a5aad5bee5e0f4f1e9a9a2dfbe04fd2886539e72b00a920df14b1e1
+  data.tar.gz: a3dc6d0a256c59f0f83763fded7aa4fa2d8fbdf724b5accdcb80e949f9f419aca1827243f6d70b29227197fbd4659f82f1ae2c1549435216d76d48013370ac25

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [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`)

data/Gemfile

@@ -9,7 +9,11 @@ gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
 
-gem "sqlite3", "~> 1.6"
+gem "benchmark-ips"
+
+gem "activerecord", "~> 8.1"
+
+gem "sqlite3", "~> 2.1"
 
 gem "standard", "~> 1.3"
 
@@ -18,3 +22,4 @@ gem "mutex_m"
 gem "base64"
 gem "bigdecimal"
 gem "racc"
+gem "ostruct"

data/Gemfile.lock

@@ -1,37 +1,53 @@
 PATH
   remote: .
   specs:
-    activerecord-quick_read (1.2.0)
+    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)
     base64 (0.3.0)
+    benchmark-ips (2.15.1)
     bigdecimal (4.1.2)
-    concurrent-ruby (1.2.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)
-    mini_portile2 (2.8.9)
-    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)
@@ -66,30 +82,35 @@ GEM
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.13.0)
-    sqlite3 (1.7.3)
-      mini_portile2 (~> 2.8.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 (~> 1.6)
+  sqlite3 (~> 2.1)
   standard (~> 1.3)
 
 BUNDLED WITH
-   2.4.12
+  4.0.19

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/activerecord-quick_read.svg)](https://badge.fury.io/rb/activerecord-quick_read)
 
-Makes rails go _faster_. Improve read times 4x!
+Makes Rails go faster. Speedups scale with the size and complexity of your models, up to ~13x.
 
 ### How does it work?
 
@@ -12,18 +12,20 @@ typecasting each column, setting up dirty tracking, and evaluating any `after_in
 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.
 
-`quick_read` sidesteps all of that. It still runs the exact same scoped SQL through
-`connection.select_all`, which returns each row as a plain hash. Then, instead of building model
-objects, each hash is wrapped in a lightweight `Struct` whose members mirror the model's columns:
+`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)
 ```
 
-Because structs are plain Ruby objects there's no typecasting, no dirty tracking, no
-`after_initialize` callbacks, and far less allocation. The result is the same data you asked for,
-returned 4x faster.
+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
@@ -72,6 +74,10 @@ Because models aren't fully defined until boot, the `Lite` structs are built laz
 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
@@ -94,7 +100,7 @@ Report.order(:created_at).quick_reads.map(&:to_h)
 
 ### Batching
 
-Load your batches 4x quicker:
+Load your batches faster, with bigger wins on larger, more complex models:
 
 ```ruby
 Report.in_batches do |batch|
@@ -143,6 +149,27 @@ 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.

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/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.2.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,13 +59,18 @@ 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
       scope = current_scope || all
-      connection.select_all(scope.to_sql).map { |attrs| quick_build(attrs) }
+      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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-quick_read
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Ryan Buckley
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -44,7 +43,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- activerecord-quick_read.gemspec
+- benchmarks/read_benchmark.rb
 - lib/activerecord/quick_read.rb
 - lib/activerecord/quick_read/lite_base.rb
 - lib/activerecord/quick_read/railtie.rb
@@ -56,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
@@ -71,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: Speed up ActiveRecord reads by skipping model instantiation.
 test_files: []

data/activerecord-quick_read.gemspec

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/activerecord/quick_read/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "activerecord-quick_read"
-  spec.version = ActiveRecord::QuickRead::VERSION
-  spec.authors = ["Ryan Buckley"]
-  spec.email = ["ridiculous@hey.com"]
-
-  spec.summary = "Speed up ActiveRecord reads by skipping model instantiation."
-  spec.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."
-  spec.homepage = "https://github.com/ridiculous/activerecord-quick_reads"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.6.0"
-
-  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/ridiculous/activerecord-quick_reads"
-  spec.metadata["changelog_uri"] = "https://github.com/ridiculous/activerecord-quick_reads/CHANGELOG.md"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Uncomment to register a new dependency of your gem
-  spec.add_dependency "activerecord"
-
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
-end