deferred_columns 0.0.1 → 0.0.2

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 58afb2439a990ba59410a0c6ba84713a818966d79ed467753140f75b967e270f
4
- data.tar.gz: d86d4ebfc9fb4d92d97bc6749cfd1425535b6bd0286e7baa1d830f3b822b46a0
3
+ metadata.gz: 673a05b43141ae812573a42241eb5d022d35bd2738adc8af21ad0f5e9e7ecec8
4
+ data.tar.gz: 50d38ddab545cf7d1f34e2dda4b65becb94937295a929b5a740444137127103a
5
5
  SHA512:
6
- metadata.gz: e525b7a3dc919695632aaa0769097b10c4d4d372324bbacef3aedd52a6372ce62cdce1acb07482381a875cc4f6831d310581657f4256fca7e45fe430bb3171c9
7
- data.tar.gz: 7e60acaed185a81655312b04ff94426e75759e7e94d35ad1f600dad024f4b387990cfbc0ae75144e25b8533c9b05bc10e878ae743ff7b8e6c5dcd72934bcd949
6
+ metadata.gz: d124bd7ea986c7cbacda770d5bf1443f8c5c97617c762771f64fafb81685d7d2d8c4f02a5fce0b10b4463897423e8fe8ef748ce155b03332686c03040bf2b87f
7
+ data.tar.gz: 2d80df8be79afc7c468fa07ad22dfcbda395ddccd64a021e7415e98ad8c9aa0f9feeb7e14202b5682e6d658a26c9351e360204e40005dff92cdafb8ac9180f7d
data/CHANGELOG.md CHANGED
@@ -1,5 +1,18 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.0.2 (2026-11-18)
4
+
5
+ - Rename `select_all_columns` to `with_deferred_columns`.
6
+ - Add named groups of deferred columns, with `defer_columns ..., as: :name`.
7
+ - Add `load_deferred`, to load deferred columns into a record that was loaded without them.
8
+ - Add `DeferredColumns.load`, to load deferred columns into many records with one query per model.
9
+ - Raise `NotLoadedError` from `read_attribute` and `[]` too, instead of returning `nil`.
10
+ - Keep the deferred columns a record had loaded when calling `reload`.
11
+ - Respect opt-ins in `eager_load`, and in `includes` when it eager loads, both in the query and in association scopes.
12
+ - Add `DeferredColumns.on_not_loaded`, to report a missing deferred column instead of raising, and load it with an extra query.
13
+ - Detect associations that were already loaded without the deferred columns that a preload scope opts into.
14
+ - Load deferred columns in `DeferredColumns.load` and `load_deferred` without instantiating a record per row.
15
+
3
16
  ## 0.0.1 (2026-11-17)
4
17
 
5
18
  - Initial release: `defer_columns`, `with_deferred`, `select_all_columns`, and `DeferredColumns::NotLoadedError`.
data/README.md CHANGED
@@ -9,53 +9,27 @@ Deferred Columns
9
9
  [Active Record]: https://guides.rubyonrails.org/active_record_basics.html
10
10
  [ignored_columns]: https://api.rubyonrails.org/classes/ActiveRecord/ModelSchema/ClassMethods.html#method-i-ignored_columns-3D
11
11
  [columns_on_demand]: https://github.com/willbryant/columns_on_demand
12
- [Issues]: https://github.com/ElMassimo/deferred_columns/issues
13
12
 
14
- Leave heavy columns out of the default `SELECT` of your [Active Record] models, and load them only in the queries that need them.
13
+ Leave large columns out of [Active Record] queries by default.
15
14
 
16
15
  ```ruby
17
16
  class Song < ApplicationRecord
18
17
  defer_columns :lyrics, :waveform
19
18
  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
19
 
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)
20
+ album.songs # no lyrics or waveform
21
+ album.songs.with_deferred(:lyrics) # includes lyrics in the same query
38
22
  ```
39
23
 
40
24
  ## Why? 🤔
41
25
 
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.
26
+ An album page only needs a track list, but by default `album.songs` fetches the lyrics and waveform for every song.
45
27
 
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.
28
+ You could use `select`, but then every query that loads songs needs a list of columns to keep.
29
+ [`ignored_columns`][ignored_columns] goes too far: you still want the lyrics on the song page.
47
30
 
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 *`
31
+ With `defer_columns`, only the query for the song page needs to change.
32
+ If you forget to select the lyrics, `song.lyrics` raises rather than quietly running another query.
59
33
 
60
34
  ## Installation 💿
61
35
 
@@ -71,17 +45,20 @@ And then run:
71
45
 
72
46
  ## Usage 🚀
73
47
 
74
- ### Declaring deferred columns
48
+ ### Loading deferred columns
75
49
 
76
- Call `defer_columns` in any model:
50
+ Use `with_deferred` to add one or more columns to the ones you'd normally get:
77
51
 
78
52
  ```ruby
79
- class Album < ApplicationRecord
80
- defer_columns :liner_notes, :cover_art
81
- end
53
+ Song.with_deferred(:lyrics).find_by(name: "Oye como va")
54
+ album.songs.with_deferred(:lyrics, :waveform)
55
+ Song.with_deferred_columns.find(id) # all columns
82
56
  ```
83
57
 
84
- Subclasses inherit the deferred columns of their parent, and can add their own:
58
+ An unknown column or group raises `ArgumentError`. If you use `select`, Active Record
59
+ loads exactly the columns you name, even on a relation with `with_deferred`.
60
+
61
+ Subclasses inherit their parent's deferred columns and can add their own:
85
62
 
86
63
  ```ruby
87
64
  class LiveRecording < Song
@@ -91,157 +68,143 @@ end
91
68
  LiveRecording.deferred_columns # => ["lyrics", "waveform", "crowd_noise"]
92
69
  ```
93
70
 
94
- ### Loading deferred columns
71
+ ### Grouping columns
95
72
 
96
- `with_deferred` adds deferred columns to the default ones, in the same query:
73
+ If you usually read a few columns together, give them a name:
97
74
 
98
75
  ```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:
76
+ class Album < ApplicationRecord
77
+ defer_columns :liner_notes, :cover_art, as: :booklet
78
+ end
105
79
 
106
- ```ruby
107
- Album.select_all_columns.find(id)
80
+ Album.with_deferred(:booklet)
108
81
  ```
109
82
 
110
- Passing a column that isn't deferred raises an `ArgumentError`, which catches typos early:
83
+ You can mix group and column names in a query. A column can belong to more
84
+ than one group, and declaring a group again adds to it.
111
85
 
112
- ```ruby
113
- Song.with_deferred(:lirycs)
114
- # ArgumentError: lirycs is not a deferred column of Song
115
- ```
86
+ ### Associations
116
87
 
117
- An explicit `select` loads exactly the columns it names, deferred or not, and takes precedence over `with_deferred`:
88
+ `Album.includes(:songs)` leaves out the lyrics, just like `album.songs`.
89
+ To preload the lyrics too, use an association scope:
118
90
 
119
91
  ```ruby
120
- Song.select(:id, :name, :lyrics)
92
+ class Album < ApplicationRecord
93
+ has_many :songs
94
+ has_many :songs_with_lyrics, -> { with_deferred(:lyrics) }, class_name: "Song"
95
+ end
96
+
97
+ Album.includes(:songs_with_lyrics)
121
98
  ```
122
99
 
123
- ### Associations
100
+ The same scope works with `preload`, `eager_load`, and `has_many :through`.
101
+ In `Song.with_deferred(:lyrics).eager_load(:album)`, only the songs get the extra column.
124
102
 
125
- Associations, `preload`, `includes` and `eager_load` all leave deferred columns out.
103
+ ### Loading into a record you already have
126
104
 
127
- To load them along with an association, define an association with a scope:
105
+ A job might receive a song without its lyrics. Use `load_deferred` to fetch them
106
+ without replacing the record:
128
107
 
129
108
  ```ruby
130
- class Album < ApplicationRecord
131
- has_many :songs
132
- has_many :songs_with_lyrics, -> { with_deferred(:lyrics) }, class_name: "Song"
109
+ class RefreshLyricsJob < ApplicationJob
110
+ def perform(song)
111
+ song.load_deferred(:lyrics)
112
+ song.update!(lyrics: LyricsService.normalize(song.lyrics))
113
+ end
133
114
  end
115
+ ```
116
+
117
+ Without arguments, `load_deferred` fetches all missing deferred columns.
118
+ It skips the query for new records or when the columns are already loaded.
119
+
120
+ For a collection, load the missing columns with one query per model instead of one per record:
134
121
 
135
- Album.preload(:songs_with_lyrics)
122
+ ```ruby
123
+ DeferredColumns.load(album.songs, :lyrics)
136
124
  ```
137
125
 
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
- > ```
126
+ Both forms accept group names and leave values you've already loaded or assigned alone.
145
127
 
146
128
  ### Reading deferred columns
147
129
 
148
- Reading a deferred column that the query didn't load raises `DeferredColumns::NotLoadedError`, without running a query:
149
-
150
130
  ```ruby
151
131
  song = Song.first
152
-
153
- song.lyrics # raises DeferredColumns::NotLoadedError
154
132
  song.has_attribute?(:lyrics) # => false
155
- song.as_json # leaves lyrics out
133
+ song.as_json # omits lyrics
134
+ song.lyrics # raises DeferredColumns::NotLoadedError
156
135
  ```
157
136
 
158
- The error is a subclass of `ActiveModel::MissingAttributeError`, so existing rescues keep working. It also exposes `model` and `column`.
137
+ `song[:lyrics]` and `song.read_attribute(:lyrics)` raise the same error.
138
+ It's a subclass of `ActiveModel::MissingAttributeError` and has `model` and `column` readers.
159
139
 
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.
140
+ New records have all their columns. If you override an attribute reader, call
141
+ `super` as usual.
161
142
 
162
- New records have every column, so `Song.new.lyrics` works as usual.
143
+ ### Reporting instead of raising
163
144
 
164
- You can override the reader in the model and call `super`:
145
+ In production you may want to know where you missed a `with_deferred` without
146
+ breaking the page:
165
147
 
166
148
  ```ruby
167
- class Song < ApplicationRecord
168
- defer_columns :lyrics
169
-
170
- def lyrics
171
- super&.strip
172
- end
173
- end
149
+ # config/initializers/deferred_columns.rb
150
+ DeferredColumns.on_not_loaded = ->(error) {
151
+ Rails.env.local? ? raise(error) : Rails.error.report(error)
152
+ }
174
153
  ```
175
154
 
176
- ### Writing records
155
+ If the handler returns, `song.lyrics` fetches the lyrics and returns them. In a
156
+ loop that's an extra query per song, so use the report to find the query that needs `with_deferred(:lyrics)`.
177
157
 
178
- Saving a record only writes the columns that changed, so updating other columns leaves deferred columns untouched:
158
+ The same handler runs if you try to preload lyrics into an association that
159
+ Active Record considers loaded. By default you get a `NotLoadedError` if the
160
+ lyrics are missing. If the handler returns, the preloader fetches them in bulk.
179
161
 
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
- ```
162
+ ### Writing records
185
163
 
186
- Assigning a deferred column doesn't require loading it first:
164
+ You don't need to load the lyrics to update a song, even if you're updating the lyrics themselves:
187
165
 
188
166
  ```ruby
167
+ song = Song.find_by(name: "El Nicoya")
168
+ song.update!(composer: "José Areas") # leaves lyrics untouched
189
169
  song.update!(lyrics: "Instrumental")
190
170
  ```
191
171
 
192
172
  ### Validations
193
173
 
194
- A deferred column that wasn't loaded can't have changed, so its validations are skipped:
195
-
196
174
  ```ruby
197
175
  class Album < ApplicationRecord
198
176
  defer_columns :liner_notes
199
-
200
177
  validates :name, :liner_notes, presence: true
201
178
  end
202
179
 
203
180
  album = Album.find_by(name: "Abraxas")
204
- album.update!(name: "Abraxas (Remastered)") # validates name, skips liner_notes
181
+ album.update!(name: "Abraxas (Remastered)") # validates name, skips liner_notes
205
182
  ```
206
183
 
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
- ```
184
+ Attribute validators such as `presence` and `length` skip a deferred column
185
+ unless you loaded or assigned it. On new records they run as usual.
186
+ In a custom `validate` method, check `has_attribute?(:liner_notes)` before reading it.
223
187
 
224
188
  ### Reloading
225
189
 
226
- `reload` loads the default columns again, which leaves out any deferred columns the record had loaded. To reload them, query again:
190
+ `reload` remembers which deferred columns you loaded and refreshes those in a second query:
227
191
 
228
192
  ```ruby
229
- song = Song.with_deferred(:lyrics).find(song.id)
193
+ song = Song.with_deferred(:lyrics).find(id)
194
+ song.reload.lyrics # fresh lyrics, still no waveform
230
195
  ```
231
196
 
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
197
  ## How it works 🔧
239
198
 
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.
199
+ Active Record builds the default `SELECT` in `Relation#build_select`. For
200
+ models with deferred columns, the gem lists the columns to fetch instead of
201
+ selecting `*`. There's no `default_scope`, and models without deferred columns
202
+ keep their usual queries. For `eager_load`, the gem adjusts the column list for
203
+ each model in the join.
243
204
 
244
- `with_deferred` stores the requested columns as a relation extension, so they survive `merge` and association scopes, and `count` keeps counting rows.
205
+ `with_deferred` keeps the requested columns in a relation extension, so they
206
+ survive `merge` and association scopes without changing what `count` counts.
207
+ `pluck` and `exists?` build their own selects. Raw SQL is unchanged.
245
208
 
246
209
  ## Compatibility
247
210
 
@@ -4,8 +4,27 @@ module DeferredColumns
4
4
  # `eager_load` builds its SELECT from the column names of each joined model,
5
5
  # without going through Relation#build_select.
6
6
  module JoinPart
7
+ # Opt-ins of the query, for the root model.
8
+ attr_writer :deferred_columns_opted_into
9
+
7
10
  def column_names
8
- base_klass.deferred_columns.empty? ? super : base_klass.default_select_columns
11
+ deferred = base_klass.deferred_columns
12
+ return super if deferred.empty?
13
+
14
+ opted = deferred_columns_opted_into & deferred
15
+ opted.empty? ? base_klass.default_select_columns : base_klass.column_names - (deferred - opted)
16
+ end
17
+
18
+ private
19
+
20
+ # Opt-ins of the association scope, for joined models.
21
+ def deferred_columns_opted_into
22
+ @deferred_columns_opted_into ||=
23
+ if is_a?(ActiveRecord::Associations::JoinDependency::JoinAssociation) && reflection.scope
24
+ DeferredColumns.opted_into(reflection.scope_for(base_klass.unscoped))
25
+ else
26
+ []
27
+ end
9
28
  end
10
29
  end
11
30
  end
@@ -5,19 +5,28 @@ module DeferredColumns
5
5
  module Model
6
6
  def self.extended(base)
7
7
  base.class_attribute :deferred_columns, instance_accessor: false, default: [].freeze
8
+ base.class_attribute :deferred_column_groups, instance_accessor: false, default: {}.freeze
8
9
  end
9
10
 
10
11
  # Leaves the given columns out of the default SELECT.
11
12
  #
12
13
  # 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)
14
+ # DeferredColumns::NotLoadedError, instead of running a query per record,
15
+ # unless DeferredColumns.on_not_loaded is configured to report it instead.
16
+ #
17
+ # Pass `as:` to name the group of columns, so that queries can opt into all
18
+ # of them with `with_deferred(:name)`.
19
+ def defer_columns(*columns, as: nil)
15
20
  columns = columns.flatten.map(&:to_s)
21
+ clashing = columns & deferred_column_groups.keys
22
+ raise ArgumentError, "#{clashing.join(', ')} already names a group of deferred columns in #{name}" if clashing.any?
23
+
16
24
  self.deferred_columns = (deferred_columns | columns).freeze
25
+ add_deferred_column_group(as.to_s, columns) if as
17
26
 
18
27
  columns.each do |column|
19
28
  deferred_column_readers.define_method(column) do
20
- raise NotLoadedError.new(self.class, column) unless has_attribute?(column)
29
+ DeferredColumns.not_loaded!(self, NotLoadedError.new(self.class, column)) unless has_attribute?(column)
21
30
 
22
31
  super()
23
32
  end
@@ -30,8 +39,8 @@ module DeferredColumns
30
39
  end
31
40
 
32
41
  # Loads every column, including the deferred ones.
33
- def select_all_columns
34
- all.select_all_columns
42
+ def with_deferred_columns
43
+ all.with_deferred_columns
35
44
  end
36
45
 
37
46
  # The columns loaded by a query that doesn't select any explicitly.
@@ -46,6 +55,13 @@ module DeferredColumns
46
55
 
47
56
  private
48
57
 
58
+ def add_deferred_column_group(group, columns)
59
+ raise ArgumentError, "#{group} is a deferred column of #{name}, so it can't name a group" if deferred_columns.include?(group)
60
+
61
+ grouped = (deferred_column_groups.fetch(group, []) | columns).freeze
62
+ self.deferred_column_groups = deferred_column_groups.merge(group => grouped).freeze
63
+ end
64
+
49
65
  def deferred_column_readers
50
66
  @deferred_column_readers ||= Module.new.tap { |readers| include readers }
51
67
  end
@@ -0,0 +1,31 @@
1
+ # frozen_string_literal: true
2
+
3
+ module DeferredColumns
4
+ # Preloading skips associations that are already loaded, so the deferred
5
+ # columns its scope opts into would never reach their records.
6
+ module Preloader
7
+ def run
8
+ load_opted_into_loaded_targets unless run?
9
+ super
10
+ end
11
+
12
+ private
13
+
14
+ def load_opted_into_loaded_targets
15
+ opted = DeferredColumns.opted_into(reflection_scope)
16
+ opted |= DeferredColumns.opted_into(preload_scope) if preload_scope
17
+ return if opted.empty?
18
+
19
+ records = owners.select { |owner| loaded?(owner) }.flat_map { |owner| target_for(owner) }
20
+ unloaded = records.select { |record| opted.any? { |column| DeferredColumns.unloaded?(record, column) } }
21
+ return if unloaded.empty?
22
+
23
+ model = unloaded.first.class
24
+ column = opted.find { |name| DeferredColumns.unloaded?(unloaded.first, name) }
25
+ message = "#{owners.first.class.name}##{reflection.name} was already loaded without #{model.name}##{column}, " \
26
+ 'so preloading it again with that deferred column skipped it. ' \
27
+ "Opt into it where the association is first loaded, for example: #{model.name}.with_deferred(:#{column})"
28
+ DeferredColumns.not_loaded!(unloaded, NotLoadedError.new(model, column, message), opted)
29
+ end
30
+ end
31
+ end
@@ -0,0 +1,69 @@
1
+ # frozen_string_literal: true
2
+
3
+ module DeferredColumns
4
+ # Instance methods available in every Active Record model.
5
+ module Record
6
+ # Loads deferred columns or groups into a record that was loaded without
7
+ # them, in a single query. Without arguments, loads every deferred column.
8
+ #
9
+ # Prefer `with_deferred` in the query that loads the records; this is for
10
+ # records loaded elsewhere, such as job arguments or `self` in a callback.
11
+ def load_deferred(*names)
12
+ DeferredColumns.load(self, *names)
13
+ self
14
+ end
15
+
16
+ # Raises instead of returning nil for deferred columns that weren't loaded,
17
+ # which also applies to `record[column]`.
18
+ def read_attribute(name, &)
19
+ if self.class.deferred_columns.any?
20
+ column = name.to_s
21
+ column = self.class.attribute_aliases.fetch(column, column)
22
+ DeferredColumns.not_loaded!(self, NotLoadedError.new(self.class, column)) if DeferredColumns.unloaded?(self, column)
23
+ end
24
+
25
+ super
26
+ end
27
+
28
+ # Reloads the record, keeping the deferred columns it had loaded.
29
+ def reload(*)
30
+ loaded = self.class.deferred_columns.select { |column| has_attribute?(column) }
31
+ super.tap { load_deferred(*loaded) if loaded.any? }
32
+ end
33
+
34
+ private
35
+
36
+ def load_deferred_column(column, value)
37
+ @attributes.write_from_database(column, value) unless has_attribute?(column)
38
+ end
39
+ end
40
+
41
+ # Loads deferred columns or groups into records that were loaded without them,
42
+ # with one query per model. Without names, loads every deferred column.
43
+ #
44
+ # Records that already have a column keep their value, and new records are
45
+ # skipped, so it only queries for what's missing.
46
+ def self.load(records, *names)
47
+ records = Array(records)
48
+ records.group_by(&:class).each do |model, siblings|
49
+ columns = deferred_columns!(model, names)
50
+ columns = model.deferred_columns if columns.empty?
51
+ persisted = siblings.reject(&:new_record?)
52
+ missing = columns.reject { |column| persisted.all? { |record| record.has_attribute?(column) } }
53
+ next if missing.empty?
54
+
55
+ primary_key = model.primary_key
56
+ query = model.unscoped.where(primary_key => persisted.map(&:id_in_database)).select(primary_key, *missing)
57
+ # Reads raw values, which the records cast when read, without instantiating
58
+ # a record per row or running its callbacks.
59
+ rows = model.with_connection { |connection| connection.select_rows(query.arel, "#{model.name} Load Deferred") }
60
+ key_type = model.type_for_attribute(primary_key)
61
+ rows = rows.index_by { |row| key_type.deserialize(row.first) }
62
+ persisted.each do |record|
63
+ row = rows.fetch(record.id_in_database) { raise ActiveRecord::RecordNotFound.new("Couldn't find #{model.name} with '#{primary_key}'=#{record.id_in_database}", model.name, primary_key) }
64
+ missing.each.with_index(1) { |column, index| record.send(:load_deferred_column, column, row[index]) }
65
+ end
66
+ end
67
+ records
68
+ end
69
+ end
@@ -18,19 +18,14 @@ module DeferredColumns
18
18
  # Loads the given deferred columns, along with the default ones. A query
19
19
  # that selects columns explicitly loads exactly those columns instead.
20
20
  def with_deferred(*columns)
21
- columns = columns.flatten.map(&:to_s)
21
+ columns = DeferredColumns.deferred_columns!(klass, columns)
22
22
  raise ArgumentError, 'with_deferred requires at least one column' if columns.empty?
23
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
24
  extending(OptIn.new(columns))
30
25
  end
31
26
 
32
27
  # Loads every column, including the deferred ones.
33
- def select_all_columns
28
+ def with_deferred_columns
34
29
  deferred = klass.deferred_columns
35
30
  deferred.empty? ? self : extending(OptIn.new(deferred))
36
31
  end
@@ -41,13 +36,19 @@ module DeferredColumns
41
36
  deferred = klass.deferred_columns
42
37
  return super if deferred.empty? || select_values.any?
43
38
 
44
- opted = deferred_columns_opted_into & deferred
39
+ opted = DeferredColumns.opted_into(self) & deferred
45
40
  loaded = opted.empty? ? klass.default_select_columns : klass.column_names - (deferred - opted)
46
41
  arel.project(*loaded.map { |column| table[column] })
47
42
  end
48
43
 
49
- def deferred_columns_opted_into
50
- extending_values.grep(OptIn).flat_map(&:columns).uniq
44
+ # Passes the opt-ins to the root of `eager_load`, which selects its columns.
45
+ def construct_join_dependency(...)
46
+ super.tap { |dependency| dependency.send(:join_root).deferred_columns_opted_into = DeferredColumns.opted_into(self) }
51
47
  end
52
48
  end
49
+
50
+ # The deferred columns a query opted into.
51
+ def self.opted_into(relation)
52
+ relation.extending_values.grep(Relation::OptIn).flat_map(&:columns).uniq
53
+ end
53
54
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module DeferredColumns
4
- VERSION = '0.0.1'
4
+ VERSION = '0.0.2'
5
5
  end
@@ -18,16 +18,51 @@ module DeferredColumns
18
18
  class NotLoadedError < ActiveModel::MissingAttributeError
19
19
  attr_reader :model, :column
20
20
 
21
- def initialize(model, column)
21
+ def initialize(model, column, message = nil)
22
22
  @model = model
23
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
- )
24
+ name = model.deferred_column_groups.find { |_group, columns| columns.include?(column) }&.first || column
25
+ super(message || "#{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(:#{name}), " \
27
+ "or load it into the record with load_deferred(:#{name})")
28
28
  end
29
29
  end
30
30
 
31
+ class << self
32
+ # Called with a NotLoadedError when code reads a deferred column that wasn't
33
+ # loaded, or preloads an association that was already loaded without the
34
+ # deferred columns its scope opts into. Raises the error by default.
35
+ #
36
+ # When it returns instead, the missing columns are loaded with an extra
37
+ # query and the code carries on, so production can report the error and
38
+ # keep working:
39
+ #
40
+ # DeferredColumns.on_not_loaded = ->(error) {
41
+ # Rails.env.local? ? raise(error) : Rails.error.report(error)
42
+ # }
43
+ attr_accessor :on_not_loaded
44
+ end
45
+ self.on_not_loaded = ->(error) { raise error }
46
+
47
+ # Internal: Hands the error to `on_not_loaded`, and loads the columns into
48
+ # the records if it doesn't raise.
49
+ def self.not_loaded!(records, error, columns = [error.column])
50
+ error.set_backtrace(caller(1))
51
+ on_not_loaded.call(error)
52
+ load(records, *columns)
53
+ end
54
+
55
+ # The columns for the given names of deferred columns or groups, as long as
56
+ # all of them are deferred in the model.
57
+ def self.deferred_columns!(model, names)
58
+ groups = model.deferred_column_groups
59
+ columns = names.flatten.flat_map { |name| groups.fetch(name.to_s) { [name.to_s] } }.uniq
60
+ unknown = columns - model.deferred_columns
61
+ return columns if unknown.empty?
62
+
63
+ raise ArgumentError, "#{unknown.join(', ')} #{unknown.one? ? 'is not a deferred column or group' : 'are not deferred columns or groups'} of #{model.name}"
64
+ end
65
+
31
66
  # Whether the record was loaded without the given deferred column.
32
67
  def self.unloaded?(record, column)
33
68
  model = record.class
@@ -38,16 +73,20 @@ module DeferredColumns
38
73
  end
39
74
 
40
75
  require 'deferred_columns/model'
76
+ require 'deferred_columns/record'
41
77
  require 'deferred_columns/relation'
42
78
  require 'deferred_columns/join_part'
79
+ require 'deferred_columns/preloader'
43
80
  require 'deferred_columns/validator'
44
81
 
45
82
  ActiveSupport.on_load(:active_record) do
46
83
  extend DeferredColumns::Model
84
+ include DeferredColumns::Record
47
85
  ActiveRecord::Relation.prepend(DeferredColumns::Relation)
48
86
 
49
87
  require 'active_record/associations/join_dependency/join_part'
50
88
  ActiveRecord::Associations::JoinDependency::JoinPart.prepend(DeferredColumns::JoinPart)
89
+ ActiveRecord::Associations::Preloader::Association.prepend(DeferredColumns::Preloader)
51
90
  end
52
91
 
53
92
  ActiveModel::EachValidator.prepend(DeferredColumns::Validator)
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: deferred_columns
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.1
4
+ version: 0.0.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Maximo Mussini
@@ -38,6 +38,8 @@ files:
38
38
  - lib/deferred_columns.rb
39
39
  - lib/deferred_columns/join_part.rb
40
40
  - lib/deferred_columns/model.rb
41
+ - lib/deferred_columns/preloader.rb
42
+ - lib/deferred_columns/record.rb
41
43
  - lib/deferred_columns/relation.rb
42
44
  - lib/deferred_columns/validator.rb
43
45
  - lib/deferred_columns/version.rb