deferred_columns 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 58afb2439a990ba59410a0c6ba84713a818966d79ed467753140f75b967e270f
4
+ data.tar.gz: d86d4ebfc9fb4d92d97bc6749cfd1425535b6bd0286e7baa1d830f3b822b46a0
5
+ SHA512:
6
+ metadata.gz: e525b7a3dc919695632aaa0769097b10c4d4d372324bbacef3aedd52a6372ce62cdce1acb07482381a875cc4f6831d310581657f4256fca7e45fe430bb3171c9
7
+ data.tar.gz: 7e60acaed185a81655312b04ff94426e75759e7e94d35ad1f600dad024f4b387990cfbc0ae75144e25b8533c9b05bc10e878ae743ff7b8e6c5dcd72934bcd949
data/CHANGELOG.md ADDED
@@ -0,0 +1,6 @@
1
+ # Changelog
2
+
3
+ ## 0.0.1 (2026-11-17)
4
+
5
+ - Initial release: `defer_columns`, `with_deferred`, `select_all_columns`, and `DeferredColumns::NotLoadedError`.
6
+ - Supports Active Record 7.2, 8.0, 8.1 and main.
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2026 Maximo Mussini
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,279 @@
1
+ <h1 align="center">
2
+ Deferred Columns
3
+ <p align="center">
4
+ <a href="https://github.com/ElMassimo/deferred_columns/actions"><img alt="Build Status" src="https://github.com/ElMassimo/deferred_columns/workflows/build/badge.svg"/></a>
5
+ <a href="https://github.com/ElMassimo/deferred_columns/blob/main/LICENSE.txt"><img alt="License" src="https://img.shields.io/badge/license-MIT-428F7E.svg"/></a>
6
+ </p>
7
+ </h1>
8
+
9
+ [Active Record]: https://guides.rubyonrails.org/active_record_basics.html
10
+ [ignored_columns]: https://api.rubyonrails.org/classes/ActiveRecord/ModelSchema/ClassMethods.html#method-i-ignored_columns-3D
11
+ [columns_on_demand]: https://github.com/willbryant/columns_on_demand
12
+ [Issues]: https://github.com/ElMassimo/deferred_columns/issues
13
+
14
+ Leave heavy columns out of the default `SELECT` of your [Active Record] models, and load them only in the queries that need them.
15
+
16
+ ```ruby
17
+ class Song < ApplicationRecord
18
+ defer_columns :lyrics, :waveform
19
+ end
20
+ ```
21
+
22
+ ```ruby
23
+ Song.where(album: abraxas)
24
+ # SELECT "songs"."id", "songs"."album_id", "songs"."track", "songs"."name", "songs"."composer"
25
+ # FROM "songs" WHERE "songs"."album_id" = 1
26
+
27
+ Song.with_deferred(:lyrics).where(album: abraxas)
28
+ # SELECT "songs"."id", "songs"."album_id", "songs"."track", "songs"."name", "songs"."composer", "songs"."lyrics"
29
+ # FROM "songs" WHERE "songs"."album_id" = 1
30
+ ```
31
+
32
+ ```ruby
33
+ song = Song.find_by(name: "Oye como va")
34
+
35
+ song.lyrics
36
+ # DeferredColumns::NotLoadedError: Song#lyrics is a deferred column, so it isn't loaded by default.
37
+ # Select it in the query, for example: Song.with_deferred(:lyrics)
38
+ ```
39
+
40
+ ## Why? 🤔
41
+
42
+ Active Record loads every column of a table, whether or not the code reads it.
43
+
44
+ Most tables have a few columns that are much larger than the rest, and that only one or two places need: lyrics, documents, JSON payloads, binary blobs, embeddings. Every other query still transfers them from the database, decodes them, and allocates them.
45
+
46
+ Selecting columns explicitly works for a single query, but it's easy to miss one, and it doesn't apply to associations. [`ignored_columns`][ignored_columns] removes the column from the model altogether, so there's nothing to opt into.
47
+
48
+ This library makes leaving a column out the default, and loading it an explicit choice in the query.
49
+
50
+ ## Features ⚡️
51
+
52
+ - One line per model, in the spirit of [`ignored_columns`][ignored_columns]
53
+ - Opt in per query, with `with_deferred(:lyrics)` or `select_all_columns`
54
+ - Applies to associations, `preload`, `includes`, `eager_load`, `joins` and single table inheritance
55
+ - Leaves calculations alone: `count`, `pluck`, `exists?` and friends work as usual
56
+ - Raises instead of running a query per record when a column wasn't loaded
57
+ - Skips validations of deferred columns that weren't loaded
58
+ - No `default_scope`, and models without deferred columns keep `SELECT *`
59
+
60
+ ## Installation 💿
61
+
62
+ Add this line to your application's Gemfile:
63
+
64
+ ```ruby
65
+ gem 'deferred_columns'
66
+ ```
67
+
68
+ And then run:
69
+
70
+ $ bundle install
71
+
72
+ ## Usage 🚀
73
+
74
+ ### Declaring deferred columns
75
+
76
+ Call `defer_columns` in any model:
77
+
78
+ ```ruby
79
+ class Album < ApplicationRecord
80
+ defer_columns :liner_notes, :cover_art
81
+ end
82
+ ```
83
+
84
+ Subclasses inherit the deferred columns of their parent, and can add their own:
85
+
86
+ ```ruby
87
+ class LiveRecording < Song
88
+ defer_columns :crowd_noise
89
+ end
90
+
91
+ LiveRecording.deferred_columns # => ["lyrics", "waveform", "crowd_noise"]
92
+ ```
93
+
94
+ ### Loading deferred columns
95
+
96
+ `with_deferred` adds deferred columns to the default ones, in the same query:
97
+
98
+ ```ruby
99
+ Song.with_deferred(:lyrics).find_by(name: "Samba pa ti")
100
+ Song.where(track: 1..3).with_deferred(:lyrics, :waveform)
101
+ album.songs.with_deferred(:lyrics)
102
+ ```
103
+
104
+ `select_all_columns` loads every column, including the deferred ones:
105
+
106
+ ```ruby
107
+ Album.select_all_columns.find(id)
108
+ ```
109
+
110
+ Passing a column that isn't deferred raises an `ArgumentError`, which catches typos early:
111
+
112
+ ```ruby
113
+ Song.with_deferred(:lirycs)
114
+ # ArgumentError: lirycs is not a deferred column of Song
115
+ ```
116
+
117
+ An explicit `select` loads exactly the columns it names, deferred or not, and takes precedence over `with_deferred`:
118
+
119
+ ```ruby
120
+ Song.select(:id, :name, :lyrics)
121
+ ```
122
+
123
+ ### Associations
124
+
125
+ Associations, `preload`, `includes` and `eager_load` all leave deferred columns out.
126
+
127
+ To load them along with an association, define an association with a scope:
128
+
129
+ ```ruby
130
+ class Album < ApplicationRecord
131
+ has_many :songs
132
+ has_many :songs_with_lyrics, -> { with_deferred(:lyrics) }, class_name: "Song"
133
+ end
134
+
135
+ Album.preload(:songs_with_lyrics)
136
+ ```
137
+
138
+ > **Note**
139
+ >
140
+ > `eager_load` builds a single query for every model involved, and always uses their default columns. Use `preload` with a scoped association instead, or select the table explicitly:
141
+ >
142
+ > ```ruby
143
+ > Song.eager_load(:album).select(Song.arel_table[Arel.star])
144
+ > ```
145
+
146
+ ### Reading deferred columns
147
+
148
+ Reading a deferred column that the query didn't load raises `DeferredColumns::NotLoadedError`, without running a query:
149
+
150
+ ```ruby
151
+ song = Song.first
152
+
153
+ song.lyrics # raises DeferredColumns::NotLoadedError
154
+ song.has_attribute?(:lyrics) # => false
155
+ song.as_json # leaves lyrics out
156
+ ```
157
+
158
+ The error is a subclass of `ActiveModel::MissingAttributeError`, so existing rescues keep working. It also exposes `model` and `column`.
159
+
160
+ Other ways of reading attributes, such as `song[:lyrics]` and `read_attribute(:lyrics)`, behave as they do for any column a query didn't select.
161
+
162
+ New records have every column, so `Song.new.lyrics` works as usual.
163
+
164
+ You can override the reader in the model and call `super`:
165
+
166
+ ```ruby
167
+ class Song < ApplicationRecord
168
+ defer_columns :lyrics
169
+
170
+ def lyrics
171
+ super&.strip
172
+ end
173
+ end
174
+ ```
175
+
176
+ ### Writing records
177
+
178
+ Saving a record only writes the columns that changed, so updating other columns leaves deferred columns untouched:
179
+
180
+ ```ruby
181
+ song = Song.find_by(name: "El Nicoya")
182
+ song.update!(composer: "José Areas")
183
+ # UPDATE "songs" SET "composer" = 'José Areas' WHERE "songs"."id" = 9
184
+ ```
185
+
186
+ Assigning a deferred column doesn't require loading it first:
187
+
188
+ ```ruby
189
+ song.update!(lyrics: "Instrumental")
190
+ ```
191
+
192
+ ### Validations
193
+
194
+ A deferred column that wasn't loaded can't have changed, so its validations are skipped:
195
+
196
+ ```ruby
197
+ class Album < ApplicationRecord
198
+ defer_columns :liner_notes
199
+
200
+ validates :name, :liner_notes, presence: true
201
+ end
202
+
203
+ album = Album.find_by(name: "Abraxas")
204
+ album.update!(name: "Abraxas (Remastered)") # validates name, skips liner_notes
205
+ ```
206
+
207
+ The validations run as usual when the column was loaded or assigned, and on new records.
208
+
209
+ > **Note**
210
+ >
211
+ > This applies to validators such as `presence` or `length`. A custom `validate` method that reads a deferred column should check `has_attribute?` first.
212
+
213
+ ### Calculations
214
+
215
+ Calculations build their own `SELECT`, and work the same with or without `with_deferred`:
216
+
217
+ ```ruby
218
+ Song.with_deferred(:lyrics).where(album: abraxas).count
219
+ # SELECT COUNT(*) FROM "songs" WHERE "songs"."album_id" = 1
220
+
221
+ Song.where(album: abraxas).pluck(:lyrics)
222
+ ```
223
+
224
+ ### Reloading
225
+
226
+ `reload` loads the default columns again, which leaves out any deferred columns the record had loaded. To reload them, query again:
227
+
228
+ ```ruby
229
+ song = Song.with_deferred(:lyrics).find(song.id)
230
+ ```
231
+
232
+ ### What it doesn't do
233
+
234
+ - It doesn't load deferred columns lazily. A query per record is easy to miss and expensive in a loop, so missing columns raise instead.
235
+ - It doesn't change raw SQL, such as `find_by_sql`.
236
+ - It only changes reads. If a column is expensive to write, for example because of a large index, moving it to a separate table is still the better fit.
237
+
238
+ ## How it works 🔧
239
+
240
+ When a query doesn't select any columns, Active Record either selects `*` or, for models with [`ignored_columns`][ignored_columns], lists the remaining columns. This library adds deferred columns to that same decision in `Relation#build_select`.
241
+
242
+ `eager_load` builds its `SELECT` from each model's column names instead, so the library also adjusts those.
243
+
244
+ `with_deferred` stores the requested columns as a relation extension, so they survive `merge` and association scopes, and `count` keeps counting rows.
245
+
246
+ ## Compatibility
247
+
248
+ - Ruby 3.1 or newer
249
+ - Active Record 7.2, 8.0, 8.1 and `main`
250
+ - Tested on SQLite and PostgreSQL
251
+
252
+ ## Running tests 🧪
253
+
254
+ ```sh
255
+ bundle install
256
+ bin/rspec
257
+ ```
258
+
259
+ To run the tests against a specific version of Rails, set `BUNDLE_GEMFILE` to one of the files in `gemfiles`:
260
+
261
+ ```sh
262
+ BUNDLE_GEMFILE=gemfiles/Gemfile-rails.7.2.x bundle install
263
+ BUNDLE_GEMFILE=gemfiles/Gemfile-rails.7.2.x bin/rspec
264
+ ```
265
+
266
+ The tests run on an in-memory SQLite database by default. To run them on PostgreSQL, set `DATABASE_URL`:
267
+
268
+ ```sh
269
+ createdb deferred_columns_test
270
+ DATABASE_URL=postgres:///deferred_columns_test bin/rspec
271
+ ```
272
+
273
+ ## Acknowledgements 🙏
274
+
275
+ - [columns_on_demand], which first left columns out of the default `SELECT` from `Relation#build_select`
276
+
277
+ ## License
278
+
279
+ The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
@@ -0,0 +1,11 @@
1
+ # frozen_string_literal: true
2
+
3
+ module DeferredColumns
4
+ # `eager_load` builds its SELECT from the column names of each joined model,
5
+ # without going through Relation#build_select.
6
+ module JoinPart
7
+ def column_names
8
+ base_klass.deferred_columns.empty? ? super : base_klass.default_select_columns
9
+ end
10
+ end
11
+ end
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+
3
+ module DeferredColumns
4
+ # Class methods available in every Active Record model.
5
+ module Model
6
+ def self.extended(base)
7
+ base.class_attribute :deferred_columns, instance_accessor: false, default: [].freeze
8
+ end
9
+
10
+ # Leaves the given columns out of the default SELECT.
11
+ #
12
+ # Reading one of them on a record that was loaded without it raises
13
+ # DeferredColumns::NotLoadedError, instead of running a query per record.
14
+ def defer_columns(*columns)
15
+ columns = columns.flatten.map(&:to_s)
16
+ self.deferred_columns = (deferred_columns | columns).freeze
17
+
18
+ columns.each do |column|
19
+ deferred_column_readers.define_method(column) do
20
+ raise NotLoadedError.new(self.class, column) unless has_attribute?(column)
21
+
22
+ super()
23
+ end
24
+ end
25
+ end
26
+
27
+ # Loads the given deferred columns, along with the default ones.
28
+ def with_deferred(*columns)
29
+ all.with_deferred(*columns)
30
+ end
31
+
32
+ # Loads every column, including the deferred ones.
33
+ def select_all_columns
34
+ all.select_all_columns
35
+ end
36
+
37
+ # The columns loaded by a query that doesn't select any explicitly.
38
+ def default_select_columns
39
+ deferred = deferred_columns
40
+ columns = column_names
41
+ cached = @default_select_columns
42
+ return cached[2] if cached && cached[0].equal?(deferred) && cached[1].equal?(columns)
43
+
44
+ (@default_select_columns = [deferred, columns, (columns - deferred).freeze])[2]
45
+ end
46
+
47
+ private
48
+
49
+ def deferred_column_readers
50
+ @deferred_column_readers ||= Module.new.tap { |readers| include readers }
51
+ end
52
+ end
53
+ end
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+
3
+ module DeferredColumns
4
+ # Query methods, and the default SELECT for models with deferred columns.
5
+ module Relation
6
+ # Carries the columns a query opted into. Stored as an extension so that it
7
+ # survives merges and association scopes, and so that `count` still counts
8
+ # rows instead of the selected columns.
9
+ class OptIn < Module
10
+ attr_reader :columns
11
+
12
+ def initialize(columns)
13
+ @columns = columns.freeze
14
+ super()
15
+ end
16
+ end
17
+
18
+ # Loads the given deferred columns, along with the default ones. A query
19
+ # that selects columns explicitly loads exactly those columns instead.
20
+ def with_deferred(*columns)
21
+ columns = columns.flatten.map(&:to_s)
22
+ raise ArgumentError, 'with_deferred requires at least one column' if columns.empty?
23
+
24
+ unknown = columns - klass.deferred_columns
25
+ if unknown.any?
26
+ raise ArgumentError, "#{unknown.join(', ')} #{unknown.one? ? 'is not a deferred column' : 'are not deferred columns'} of #{klass.name}"
27
+ end
28
+
29
+ extending(OptIn.new(columns))
30
+ end
31
+
32
+ # Loads every column, including the deferred ones.
33
+ def select_all_columns
34
+ deferred = klass.deferred_columns
35
+ deferred.empty? ? self : extending(OptIn.new(deferred))
36
+ end
37
+
38
+ private
39
+
40
+ def build_select(arel)
41
+ deferred = klass.deferred_columns
42
+ return super if deferred.empty? || select_values.any?
43
+
44
+ opted = deferred_columns_opted_into & deferred
45
+ loaded = opted.empty? ? klass.default_select_columns : klass.column_names - (deferred - opted)
46
+ arel.project(*loaded.map { |column| table[column] })
47
+ end
48
+
49
+ def deferred_columns_opted_into
50
+ extending_values.grep(OptIn).flat_map(&:columns).uniq
51
+ end
52
+ end
53
+ end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+
3
+ module DeferredColumns
4
+ # A deferred column that wasn't loaded can't have changed, so validators skip
5
+ # it instead of raising, or reading it as nil.
6
+ module Validator
7
+ def validate(record)
8
+ unloaded = attributes.select { |attribute| DeferredColumns.unloaded?(record, attribute) }
9
+ return super if unloaded.empty?
10
+
11
+ loaded = attributes - unloaded
12
+ return if loaded.empty?
13
+
14
+ dup.tap { |validator| validator.instance_variable_set(:@attributes, loaded) }.validate(record)
15
+ end
16
+ end
17
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module DeferredColumns
4
+ VERSION = '0.0.1'
5
+ end
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'active_record'
4
+ require 'deferred_columns/version'
5
+
6
+ # Leaves heavy columns out of the default SELECT of an Active Record model, and
7
+ # lets each query opt into them.
8
+ #
9
+ # class Song < ActiveRecord::Base
10
+ # defer_columns :lyrics
11
+ # end
12
+ #
13
+ # Song.where(album: abraxas) # every column but lyrics
14
+ # Song.with_deferred(:lyrics).first # plus lyrics, in the same query
15
+ # Song.first.lyrics # raises DeferredColumns::NotLoadedError
16
+ module DeferredColumns
17
+ # Raised when reading a deferred column that the query didn't select.
18
+ class NotLoadedError < ActiveModel::MissingAttributeError
19
+ attr_reader :model, :column
20
+
21
+ def initialize(model, column)
22
+ @model = model
23
+ @column = column
24
+ super(
25
+ "#{model.name}##{column} is a deferred column, so it isn't loaded by default. " \
26
+ "Select it in the query, for example: #{model.name}.with_deferred(:#{column})",
27
+ )
28
+ end
29
+ end
30
+
31
+ # Whether the record was loaded without the given deferred column.
32
+ def self.unloaded?(record, column)
33
+ model = record.class
34
+ model.respond_to?(:deferred_columns) &&
35
+ model.deferred_columns.include?(column.to_s) &&
36
+ !record.has_attribute?(column)
37
+ end
38
+ end
39
+
40
+ require 'deferred_columns/model'
41
+ require 'deferred_columns/relation'
42
+ require 'deferred_columns/join_part'
43
+ require 'deferred_columns/validator'
44
+
45
+ ActiveSupport.on_load(:active_record) do
46
+ extend DeferredColumns::Model
47
+ ActiveRecord::Relation.prepend(DeferredColumns::Relation)
48
+
49
+ require 'active_record/associations/join_dependency/join_part'
50
+ ActiveRecord::Associations::JoinDependency::JoinPart.prepend(DeferredColumns::JoinPart)
51
+ end
52
+
53
+ ActiveModel::EachValidator.prepend(DeferredColumns::Validator)
metadata ADDED
@@ -0,0 +1,69 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: deferred_columns
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.0.1
5
+ platform: ruby
6
+ authors:
7
+ - Maximo Mussini
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: activerecord
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - ">="
17
+ - !ruby/object:Gem::Version
18
+ version: '7.2'
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - ">="
24
+ - !ruby/object:Gem::Version
25
+ version: '7.2'
26
+ description: deferred_columns leaves the columns you choose out of every query that
27
+ does not ask for them, and raises instead of querying when code reads them without
28
+ opting in.
29
+ email:
30
+ - maximomussini@gmail.com
31
+ executables: []
32
+ extensions: []
33
+ extra_rdoc_files: []
34
+ files:
35
+ - CHANGELOG.md
36
+ - LICENSE.txt
37
+ - README.md
38
+ - lib/deferred_columns.rb
39
+ - lib/deferred_columns/join_part.rb
40
+ - lib/deferred_columns/model.rb
41
+ - lib/deferred_columns/relation.rb
42
+ - lib/deferred_columns/validator.rb
43
+ - lib/deferred_columns/version.rb
44
+ homepage: https://github.com/ElMassimo/deferred_columns
45
+ licenses:
46
+ - MIT
47
+ metadata:
48
+ homepage_uri: https://github.com/ElMassimo/deferred_columns
49
+ source_code_uri: https://github.com/ElMassimo/deferred_columns
50
+ changelog_uri: https://github.com/ElMassimo/deferred_columns/blob/main/CHANGELOG.md
51
+ rubygems_mfa_required: 'true'
52
+ rdoc_options: []
53
+ require_paths:
54
+ - lib
55
+ required_ruby_version: !ruby/object:Gem::Requirement
56
+ requirements:
57
+ - - ">="
58
+ - !ruby/object:Gem::Version
59
+ version: 3.1.0
60
+ required_rubygems_version: !ruby/object:Gem::Requirement
61
+ requirements:
62
+ - - ">="
63
+ - !ruby/object:Gem::Version
64
+ version: '0'
65
+ requirements: []
66
+ rubygems_version: 4.0.20
67
+ specification_version: 4
68
+ summary: Leave heavy columns out of the default SELECT of your Active Record models.
69
+ test_files: []