N+1 queries, eager loading and strict loading

A teacher opens the Kaksha dashboard, which lists nine open batches with the teacher’s name beside each one. The page sends ten SELECTs for a list of nine: one for the batches, nine more—one per row—to load batch.teacher. That is the N+1N+1 query: Reading a list with one query and then one more query per row of it, usually by following an association inside a loop; preloading the association turns the many queries into a few. More in “Associations” query problem, and this lesson measures it on a real schema, cuts the ten down to 2 or 1 with includes, preload and eager_load, catches the regression at the model with strict_loading, and ends with a query-count assertion the next pull request has to keep green.

Every number in the text comes from a run on Ruby 4.0.7 and Rails 8.1.4 against SQLite in-memory, so the counts you read are the counts you get when you run the examples.

A loop over nine batches sends 10 queries

The dashboard is three Ruby lines: load the open batches, iterate, print the teacher name of each. On a plain Batch.all the loop reads one SELECT to fetch the nine rows and then one more SELECT per row to load the belongs_to association, because batch.teacher is a method that queries the database the first time it is called. Nine batches make nine extra reads, which is why the pattern is called N+1: one query up front, then N more.

The next run does exactly that against a tiny schema (one teacher who owns nine batches), with a subscriber that counts every statement the sql.active_record notification announces. The subscriber ignores schema reads, the query cache and transaction boundaries, so what it counts is the SELECTs the loop sent:

# frozen_string_literal: true

# Reads 9 batches four ways and counts the SELECTs each one sends, by
# subscribing to the "sql.active_record" notification. The four reads build
# the same list on the page but take 10, 2, 2 and 1 query respectively.

require "active_record"
require "active_support/notifications"
require "logger"

ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
ActiveRecord::Base.logger = nil
ActiveRecord::Schema.verbose = false

ActiveRecord::Schema.define do
  create_table :teachers do |t|
    t.string :name
  end
  create_table :batches do |t|
    t.string :name
    t.integer :teacher_id
  end
end

class Teacher < ActiveRecord::Base
  has_many :batches
end

class Batch < ActiveRecord::Base
  belongs_to :teacher
end

teacher = Teacher.create!(name: "Asha")
9.times { |i| Batch.create!(name: "Batch #{i + 1}", teacher: teacher) }

def count_queries(label)
  statements = []
  subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
    next if payload[:name] == "SCHEMA" || payload[:cached]
    next if payload[:sql].start_with?("PRAGMA") || payload[:sql].start_with?("BEGIN") || payload[:sql].start_with?("COMMIT")
    statements << payload[:sql]
  end
  yield
ensure
  ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
  puts "#{label}: #{statements.size} queries"
  statements.each { |s| puts "  #{s}" }
  puts
end

count_queries("plain .all") do
  Batch.all.each { |b| b.teacher.name }
end

count_queries(".includes(:teacher)") do
  Batch.includes(:teacher).each { |b| b.teacher.name }
end

count_queries(".preload(:teacher)") do
  Batch.preload(:teacher).each { |b| b.teacher.name }
end

count_queries(".eager_load(:teacher)") do
  Batch.eager_load(:teacher).each { |b| b.teacher.name }
end

plain .all: 10 queries
  SELECT "batches".* FROM "batches"
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ?
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ?
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ?
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ?
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ?
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ?
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ?
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ?
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ?

.includes(:teacher): 2 queries
  SELECT "batches".* FROM "batches"
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ?

.preload(:teacher): 2 queries
  SELECT "batches".* FROM "batches"
  SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ?

.eager_load(:teacher): 1 queries
  SELECT "batches"."id" AS t0_r0, "batches"."name" AS t0_r1, "batches"."teacher_id" AS t0_r2, "teachers"."id" AS t1_r0, "teachers"."name" AS t1_r1 FROM "batches" LEFT OUTER JOIN "teachers" ON "teachers"."id" = "batches"."teacher_id"

Reading the recorded output section by section:

• plain .all sent 10 queries: one SELECT "batches".* for the list of nine rows, then nine identical SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ? statements, one per batch. Each follow-up read the association from the row’s teacher_id, which costs a round trip.
• .includes(:teacher) sent 2 queries: the same list, then one SELECT "teachers".* ... WHERE "teachers"."id" = ? that loads the teacher once. Nine lazy reads became a bound value filled in from the batches’ ids before the loop runs.
• .preload(:teacher) sent the same 2 queries as includes; the two methods are the same shape when nothing in the chain references the teacher’s columns.
• .eager_load(:teacher) sent 1 query: a LEFT OUTER JOIN with the aliased columns t0_r0, t0_r1, t1_r0, t1_r1, which rebuilds the two models from one row of the result set.

The scene walks the plain run in order: a loader asks for the batches, the view iterates, each row’s teacher reader sees no cached association and sends another SELECT. The counts move from 1 to 10 as the loop goes, which is why “ten queries for a nine-row page” is the shape of the bug when you spot it in a log.

Three plans: includes, preload and eager loading

Three methods on a relationrelation: A lazy query plan on an Active Record model that chains with where, order, group and friends; the SELECT runs only when a loader asks for rows. More in “Querying: relations, scopes and calculations” turn the ten queries into two or one. They all accept the same argument shapes (an association name, an array of names, a hash for nested associations), and they differ only in how Active Record builds the SQL:

• includes(:teacher) is the one to reach for first. It picks between preloadpreload: An Active Record query method that loads an association with a second SELECT and an IN list of the parents' ids; it cannot filter or sort by the children's columns because the first SELECT has no join. (two SELECTs) and eager_loadeager_load: An Active Record query method that loads an association through a LEFT OUTER JOIN, so a where or an order can use the children's columns; a condition on a child column also decides which children are loaded. (one SELECT with a LEFT OUTER JOIN) by looking at the rest of the relation: a plain chain uses preload; a chain that references the association’s columns in where, order or a joins clause switches to eager_load, because the database needs the join to apply the condition.
• preload(:teacher) always sends two SELECTs: one for the parents, one with WHERE "teachers"."id" IN (...) for the children. It cannot filter or sort by the children’s columns (there is only one query for them, and the parents’ SELECT does not know about them), so a preload(:teacher).where("teachers.name = ?") is an error.
• eager_load(:teacher) sends a SELECT with a LEFT OUTER JOIN and aliased columns. It can filter and sort by the association’s columns, and it is the right call for a report that picks parents by a child column. On a has_many the join returns one row per child, and Active Record folds those rows back into one parent with its children.

The table answers “which one fits my chain?” from three questions: do I filter by the child’s columns, is it a has_many, and must every child of each parent appear? Row by row it reads the Rails Query Interface guide back as behaviour: the preload row’s “cannot filter by children” is section 16.3 of the guide, and the eager_load row’s “can specify conditions” is section 16.4.

What references adds is small enough to be worth seeing: when the chain mentions the child’s columns in a SQL fragment (not a hash), Rails has to be told to join. The guide shows the two forms side by side:

# frozen_string_literal: true

# Two forms of a filter on a child's column, so includes knows what to do.
# Show-only snippet; see examples/n_plus_one.rb for a runnable file.

# Hash form: Active Record parses it and switches includes to eager_load.
Batch.includes(:teacher).where(teachers: { name: "Asha" })

# SQL fragment: Active Record cannot see the reference, so .references(:teacher)
# is needed to force the join; without it, the preload shape runs and the SQL
# fragment misses the join entirely.
Batch.includes(:teacher).where("teachers.name = ?", "Asha").references(:teacher)

Line 1 is a hash condition, which Rails parses, so it switches to eager_load on its own. Line 2 is a SQL string, so .references(:teacher) is needed; without it, Rails runs the preload shape and the SQL fragment misses the join. The includes method is a convenience: it gets the common cases right, and in the rare chain it does not, the two primitives (preload, eager_load) are a line away.

A has_many raises two questions about eager_load: does a limit count parents or joined rows, and what does a condition on the children do to the loaded association? The next run asks both, with three teachers who own three batches each:

# frozen_string_literal: true
# eager_load on a has_many: does a LIMIT count teachers or joined rows, and what does a
# condition on the batches' columns do to the loaded association? Three teachers own three
# batches each. A subscriber on sql.active_record prints the statements Active Record sends.
require "active_record"

ActiveRecord::Schema.verbose = false
ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")

ActiveRecord::Schema.define do
  create_table(:teachers) { |t| t.string :name, null: false }
  create_table(:batches) do |t|
    t.integer :teacher_id, null: false
    t.string :name, null: false
  end
end

class Teacher < ActiveRecord::Base
  has_many :batches
end

class Batch < ActiveRecord::Base
  belongs_to :teacher
end

%w[Asha Ravi Meena].each do |name|
  teacher = Teacher.create!(name: name)
  %w[Science Maths English].each { |subject| teacher.batches.create!(name: "#{name} #{subject}") }
end

log = []
ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
  log << payload[:sql] unless payload[:name] == "SCHEMA"
end

show = lambda do |title, relation|
  log.clear
  teachers = relation.to_a
  puts "#{title}: #{teachers.size} teachers, #{teachers.sum { |t| t.batches.size }} batches"
  log.each { |sql| puts "  #{sql}" }
end

show.call("eager_load(:batches).limit(2)", Teacher.eager_load(:batches).order(:id).limit(2))
show.call("preload(:batches).limit(2)", Teacher.preload(:batches).order(:id).limit(2))

filtered = Teacher.eager_load(:batches).where(batches: { name: ["Asha Science", "Ravi Maths"] }).order(:id).to_a
puts "eager_load + where on batches: " +
     filtered.map { |t| "#{t.name} #{t.batches.size} of #{Batch.where(teacher_id: t.id).count}" }.join(", ")

eager_load(:batches).limit(2): 2 teachers, 6 batches
  SELECT DISTINCT "teachers"."id" FROM "teachers" LEFT OUTER JOIN "batches" ON "batches"."teacher_id" = "teachers"."id" ORDER BY "teachers"."id" ASC LIMIT ?
  SELECT "teachers"."id" AS t0_r0, "teachers"."name" AS t0_r1, "batches"."id" AS t1_r0, "batches"."teacher_id" AS t1_r1, "batches"."name" AS t1_r2 FROM "teachers" LEFT OUTER JOIN "batches" ON "batches"."teacher_id" = "teachers"."id" WHERE "teachers"."id" IN (?, ?) ORDER BY "teachers"."id" ASC
preload(:batches).limit(2): 2 teachers, 6 batches
  SELECT "teachers".* FROM "teachers" ORDER BY "teachers"."id" ASC LIMIT ?
  SELECT "batches".* FROM "batches" WHERE "batches"."teacher_id" IN (?, ?)
eager_load + where on batches: Asha 1 of 3, Ravi 1 of 3

With limit(2), eager_load sent two queries, not one: a SELECT DISTINCT "teachers"."id" ... LIMIT ? to pick two teachers, then the join for those two ids, so the limit counted teachers and all six of their batches arrived. The condition is the real trap: where(batches: { name: [...] }) kept Asha and Ravi but loaded only 1 of their 3 batches each, because the WHERE filters the joined rows the association is built from.

Strict loading stops regressions at the model

Eager loading removes an N+1 only where you remembered to add it. The call three months later—a presenter that reads batch.teacher.phone on a page the designer forgot about—goes back to one query per row, and no one notices until the page gets slow. strict_loadingstrict_loading: A mode that raises ActiveRecord::StrictLoadingViolationError on any lazy association read, so a page that forgot an includes stops at the first lazy call rather than at the first slow user; set on a relation, a record, an association or an environment. turns the lazy load into an error, so the regression stops at the first missed call rather than at the first slow user.

Four places to turn it on, each a line:

• Batch.strict_loading.find_each { ... } on a relation.
• record.strict_loading! on an already loaded record (strict_loading!(mode: :n_plus_one_only) for the softer mode below).
• has_many :batches, strict_loading: true on an association, so a lazy read of that one association raises on every record, wherever the record came from.
• config.active_record.strict_loading_by_default = true in an environment, so every relation is strict unless the code opts out. Set config.active_record.action_on_strict_loading_violation = :log to send violations to the log instead of raising, while the app is being made safe one page at a time.

The strict mode :n_plus_one_only is the softer rule: the record itself may still load its associations lazily, but every record that one of its has_many associations brings back is marked strict, so lazily loading anything from those children raises. It is the one to reach for first, because it rules out the pattern that actually hurts (one query per child) without flagging a single lazy load on the parent. The recorded run shows both modes:

# frozen_string_literal: true

# Shows ActiveRecord::StrictLoadingViolationError raised on a lazy load,
# and the :n_plus_one_only mode that lets a single collection read go through
# but still raises when the loop reaches a child association. Each error is
# caught, so the script exits 0.

require "active_record"
require "logger"

ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
ActiveRecord::Base.logger = nil
ActiveRecord::Schema.verbose = false

ActiveRecord::Schema.define do
  create_table :teachers do |t|
    t.string :name
  end
  create_table :batches do |t|
    t.string :name
    t.integer :teacher_id
  end
  create_table :students do |t|
    t.string :name
    t.integer :batch_id
  end
end

class Teacher < ActiveRecord::Base
  has_many :batches
end

class Batch < ActiveRecord::Base
  belongs_to :teacher
  has_many :students
end

class Student < ActiveRecord::Base
  belongs_to :batch
end

teacher = Teacher.create!(name: "Asha")
3.times do |i|
  batch = Batch.create!(name: "Batch #{i + 1}", teacher: teacher)
  2.times { |j| Student.create!(name: "Student #{i + 1}-#{j + 1}", batch: batch) }
end

puts "1. .strict_loading relation: a lazy belongs_to raises"
begin
  Batch.strict_loading.find_each { |b| b.teacher.name }
rescue ActiveRecord::StrictLoadingViolationError => e
  puts "   #{e.class}"
  puts "   #{e.message}"
end
puts

puts "2. strict_loading!(mode: :n_plus_one_only): one collection read is allowed"
teacher_rec = Teacher.first
teacher_rec.strict_loading!(mode: :n_plus_one_only)
puts "   teacher.batches.length = #{teacher_rec.batches.length}"
puts

puts "3. :n_plus_one_only still raises on the child collection"
begin
  teacher_rec.batches.first.students.to_a
rescue ActiveRecord::StrictLoadingViolationError => e
  puts "   #{e.class}"
  puts "   #{e.message}"
end

1. .strict_loading relation: a lazy belongs_to raises
   ActiveRecord::StrictLoadingViolationError
   `Batch` is marked for strict_loading. The Teacher association named `:teacher` cannot be lazily loaded.

2. strict_loading!(mode: :n_plus_one_only): one collection read is allowed
   teacher.batches.length = 3

3. :n_plus_one_only still raises on the child collection
   ActiveRecord::StrictLoadingViolationError
   `Batch` is marked for strict_loading. The Student association named `:students` cannot be lazily loaded.

Reading the trace in order:

• Batch.strict_loading.find_each { |b| b.teacher.name } raised ActiveRecord::StrictLoadingViolationError with the message “Batch is marked for strict_loading. The Teacher association named :teacher cannot be lazily loaded.” The relation marks every record it loads, and the first lazy b.teacher is the one that fails. In a test suite the error points at the exact line that forgot an includes.
• teacher.strict_loading!(mode: :n_plus_one_only) then teacher.batches.length returned 3: the teacher’s own lazy read is allowed, because loading its batches once is not an N+1.
• teacher.batches.first.students.to_a raised the violation again, because the batches came back through a has_many and are marked strict, and .students on one of them would be the second step of the N+1 chain. The error names the child association and the model that owns it, so a stack frame reaches straight to the view that pulled it.

A query budget your tests enforce

A fix stays a fix only when a test counts the queries. ActiveSupport::Notifications.subscribed is the one to reach for: it attaches a subscriber only while a block runs and unsubscribes on the way out, so a leftover subscriber from one test cannot colour the counts of the next. Wrap it in a Minitest assertion for a query budgetquery budget: A test assertion that counts SELECTs sent during a block, usually with ActiveSupport::Notifications.subscribed on sql.active_record, so a page that regresses from two queries to many fails CI before a user sees it., and a page that lists batches with teachers is one budget away from a regression that fails CI instead of slowing production:

# frozen_string_literal: true

# A query-budget helper written as a Minitest assertion, built on
# ActiveSupport::Notifications.subscribed, which attaches a subscriber only
# while the block runs. The script runs two assertions: one that passes
# (the block uses .includes(:teacher)) and one that fails on purpose. The
# failure is caught and printed so the script exits 0.

require "active_record"
require "active_support/notifications"
require "minitest"
require "logger"

ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
ActiveRecord::Base.logger = nil
ActiveRecord::Schema.verbose = false

ActiveRecord::Schema.define do
  create_table :teachers do |t|
    t.string :name
  end
  create_table :batches do |t|
    t.string :name
    t.integer :teacher_id
  end
end

class Teacher < ActiveRecord::Base
  has_many :batches
end

class Batch < ActiveRecord::Base
  belongs_to :teacher
end

teacher = Teacher.create!(name: "Asha")
9.times { |i| Batch.create!(name: "Batch #{i + 1}", teacher: teacher) }

class QueryBudget
  include Minitest::Assertions
  attr_accessor :assertions
  def initialize
    @assertions = 0
  end

  def assert_queries_at_most(budget, &block)
    count = 0
    callback = ->(*, payload) do
      next if payload[:name] == "SCHEMA" || payload[:cached]
      next if payload[:sql].start_with?("PRAGMA", "BEGIN", "COMMIT")
      count += 1
    end
    ActiveSupport::Notifications.subscribed(callback, "sql.active_record", &block)
    assert count <= budget,
      "Expected at most #{budget} SELECTs, saw #{count}."
  end
end

budget = QueryBudget.new

puts "Case A: .includes(:teacher) under a budget of 3"
begin
  budget.assert_queries_at_most(3) do
    Batch.includes(:teacher).each { |b| b.teacher.name }
  end
  puts "  passed"
rescue Minitest::Assertion => e
  puts "  failed: #{e.message}"
end
puts

puts "Case B: naive loop under the same budget of 3"
begin
  budget.assert_queries_at_most(3) do
    Batch.all.each { |b| b.teacher.name }
  end
  puts "  passed"
rescue Minitest::Assertion => e
  puts "  failed: #{e.message}"
end

Case A: .includes(:teacher) under a budget of 3
  passed

Case B: naive loop under the same budget of 3
  failed: Expected at most 3 SELECTs, saw 10.

The recorded run calls the helper twice. Case A wraps Batch.includes(:teacher).each { |b| b.teacher.name } in assert_queries_at_most(3): the subscriber counts the two SELECTs the eager load sends, the assertion holds, and the case prints “passed”. Case B calls the same assertion around the naive loop; the subscriber counts ten SELECTs and the assertion fails with the message “Expected at most 3 SELECTs, saw 10.” which is the exact line a failing test prints when a page starts N+1-ing on main.

Rails has query assertions of its own, which rails/test_help adds to every test case of an app: assert_queries_count(2) { ... } passes only when the block sends exactly two queries, and assert_no_queries expects none. An exact count fails on a harmless extra query as readily as on an N+1, and neither one takes an upper bound, so a budget of “at most 3” needs a small helper like this one.

The subscriber ignores three kinds of events on purpose: payload[:name] == "SCHEMA" for queries Rails sends about the catalogue (not the app), payload[:cached] for reads served from the query cache (they take no round trip), and statements starting with PRAGMA, BEGIN or COMMIT, which are configuration or transaction boundaries. That leaves the actual SELECTs the application sent, which is what the budget is about.

Three rules keep a query-budget test honest:

• Budget per request, not per query: a page is one assertion of “at most 5 SELECTs end to end”, not “at most 1 SELECT for the batches and 1 for the teachers”. A number per query turns into bookkeeping; a number per request names the invariant.
• Count what the user pays for: a background job that fills a cache may send many queries, but the request that reads from the cache sends few. The assertion sits where the latency sits.
• Fail with the SQL on screen, not with a number alone. The helper can print the statements it counted; a reader who sees “saw 10 SELECTs” and the ten SELECT "teachers".* ... WHERE "teachers"."id" = ? lines reaches the fix in seconds. The query cache is a trap here: a cached read is not a round trip, but it is still an entry in the log. The subscriber filters cached: true so the budget counts real reads only.

Spot the N-plus-one pattern in the logs

The query-budget assertion catches regressions in CI; development has two cheaper tools that catch them while the page is open. The first is the Rails log itself. Every SELECT the app sends is printed with its duration and, in development, with the file and line that sent it, because config.active_record.verbose_query_logs is on there by default. A new app’s development config also sets config.active_record.query_log_tags_enabled = true, which appends a comment that names the application, the controller and the action. A page that logs ten SELECT "teachers" reads in a row—each tagged with the same controller action—is an N+1 you can read off the console without any extra tool.

Two gems extend that view. Prosopite says it detects N+1 queries “with zero false positives / false negatives”, prints the repeated statements with the call stack that sent them, and can raise in tests with Prosopite.raise = true. Bullet says it helps “kill N+1 queries and unused eager loading”, and shows an alert, a page footer or a console line only for the notifiers you switch on. Both are a line in the Gemfile; neither is needed here, because the query budget and strict_loading are enough on their own. The five tools of this lesson catch the same bug at different moments:

A different form of parallelism helps when the queries themselves cannot be joined: load_async on a relation runs the SELECT on a background thread, so a controller that needs two independent lists starts both at once and waits for them together. It is the right call for a dashboard that reads batches and announcements from the same database, each with its own where; it does nothing for an N+1 (that pattern is already one query waiting on the previous one). The Relation API notes that config.active_record.async_query_executor must be configured, for example :global_thread_pool, or the query runs in the foreground anyway.

Practise: cut a dashboard from 10 queries to 2

Copy n_plus_one.rb, which already seeds one teacher and nine batches, and extend it:

1. Add a has_many :announcements to Teacher and a belongs_to :teacher to Announcement, with two announcements per teacher. Build a page that renders every batch with its teacher’s name and the first announcement by that teacher. Count the queries of a plain loop, then of an eager load that reaches both associations in one includes(teacher: :announcements). Expect 1 + 9 + 9 = 19 under the plain loop, 3 under the eager load (batches, teachers, announcements).
2. Add strict_loading to the Batch class’ belongs_to, so every batch raises on a lazy .teacher read. Keep the eager-loaded page green and watch a one-line change on a different page (the one that forgot the include) raise.
3. Turn the counting block of step 1 into an assert_queries_at_most(5) assertion inside a Minitest test, and watch it fail when the include is removed.

The questions below reuse the teachers and batches of the recorded runs, and every wrong answer is one of the slips named above:

Interview questions

Warm-up: how do you spot an N+1 while a page is open in development?

Open the terminal running the server and read the SELECTs the request logged. An N+1 shows up as a cluster of identical statements with different bound values, one per row of the list on the page: SELECT "teachers".* FROM "teachers" WHERE "teachers"."id" = ? LIMIT ? nine times in a row, each with a different ?, right after the one SELECT that read the batches. With config.active_record.query_log_tags_enabled on (a new app sets it in development), each SELECT carries the controller and action that sent it, which turns a cluster of reads into one line you can point at (same tag, repeated). In a test, wrap the request in ActiveSupport::Notifications.subscribed(..., "sql.active_record") and count: a page that was 2 queries this morning and is 11 queries now has a new lazy read a reader should name.

Two harder questions from the module bank start where this section ends: one asks when includes takes the preload shape and when the eager_load shape, the other weighs a query budget against strict loading on a model and strict loading by default in a growing app.

Key takeaways

• A plain loop over N parents that reads a belongs_to on each one sends N+1 queries; the recorded run on nine batches showed 10 SELECTs where includes, preload or eager_load sends 2 or 1.
• includes(:assoc) picks between two SELECTs (preload shape) and one LEFT OUTER JOIN (eager_load shape) by looking at whether the chain references the association’s columns; references(:assoc) is the hint when a SQL fragment hides the reference.
• preload cannot filter by the children’s columns because it sends a separate SELECT for them; eager_load can filter and sort there, and a condition on a child column also trims the children each parent comes back with.
• strict_loading raises ActiveRecord::StrictLoadingViolationError on any lazy load; mode :n_plus_one_only lets the record itself load lazily but marks the records its has_many associations return as strict, so the second step, one query per child, still raises.
• ActiveSupport::Notifications.subscribed wraps a block in a temporary subscriber on sql.active_record, so a Minitest assertion can enforce “at most N SELECTs” per request and fail CI the day a page regresses.
• load_async runs independent SELECTs in parallel; it helps a dashboard that reads two unrelated lists and does nothing for an N+1, which is already serial by construction.