Ruby on Rails
ActiveRecord Cookbook

Problem

Load a record by primary key, and fail loudly when it is missing.

ActiveRecord

User.find(42)
User.find(1, 2, 3) # returns an array

SQL

SELECT "users".* FROM "users" WHERE "users"."id" = 42 LIMIT 1;
SELECT "users".* FROM "users" WHERE "users"."id" IN (1, 2, 3);

Why This Works

find is optimized for primary-key lookups and raises ActiveRecord::RecordNotFound when a record is missing, which Rails converts to a 404 in controllers.

Performance Notes

• Uses the primary key index — always fast.
• The array form issues a single IN query, not one query per id.
• Order of records in the array form is not guaranteed to match the input.

Common Mistakes

• Rescuing RecordNotFound to fall back to find_by. Use find_by directly when a nil result is acceptable.
• Assuming User.find([1, 2, 3]) preserves order — sort explicitly if you need it.

Alternative

User.find_by(id: 42) # returns nil instead of raising

Problem

Fetch the first record matching a condition, or nil if none exists.

ActiveRecord

User.find_by(email: "jane@example.com")
User.find_by(email: "jane@example.com", active: true)

SQL

SELECT "users".* FROM "users"
WHERE "users"."email" = 'jane@example.com'
LIMIT 1;

Why This Works

find_by is a shortcut for where(...).first — one query, single record, no exception.

Performance Notes

• Ensure the lookup column is indexed. On columns like email, add a unique index.
• For case-insensitive lookups, prefer a functional index (lower(email)) or a citext column over where("LOWER(email) = ?", ...).

Common Mistakes

• Chaining .first after find_by — find_by already returns a single record.
• Using find_by inside a loop instead of a single where(id: ids) query — that is an N+1.

Problem

Fetch a record by attributes and raise if it does not exist.

ActiveRecord

User.find_by!(email: params[:email])

Why This Works

Identical to find_by, but raises ActiveRecord::RecordNotFound when nothing is found — which Rails renders as a 404 in controllers, matching the behavior of find.

Common Mistakes

• Using find_by! where a nil result is a valid business outcome — the raised exception becomes a noisy 404 in error trackers.

Alternative

user = User.find_by(email: params[:email])
return head :not_found unless user

Problem

Return the first record from a relation, ordered by primary key by default.

ActiveRecord

User.first
User.where(active: true).first
User.order(:created_at).first(3) # returns an array of 3

SQL

SELECT "users".* FROM "users" ORDER BY "users"."id" ASC LIMIT 1;

Why This Works

When no order is set, first adds ORDER BY primary_key ASC to make the result deterministic.

Performance Notes

• The implicit ORDER BY id uses the primary key index and stays fast.
• If you already applied an order, that ordering is respected instead.

Common Mistakes

• Assuming first respects insertion order without an explicit order. It orders by primary key, which usually — but not always — matches insertion order.

Problem

Return the last record of a relation.

ActiveRecord

User.last
User.order(:created_at).last

SQL

SELECT "users".* FROM "users" ORDER BY "users"."id" DESC LIMIT 1;

Why This Works

Without an explicit order, ActiveRecord reverses ORDER BY id ASC to DESC and takes one row. If you have an order clause, it inverts that instead.

Performance Notes

• Cheap on the default ordering thanks to the primary key index.
• Loading last against a large ordered scope may load everything in memory if the relation has already been loaded — call last before .to_a, not after.

Common Mistakes

• Using last to mean "most recently created". If IDs aren't strictly monotonic (UUIDs, sharded ids), that assumption breaks. Use order(created_at: :desc).first when the intent is temporal.

Problem

Return a single record without imposing an order.

ActiveRecord

User.take
User.where(active: true).take
User.take(5) # array of up to 5

SQL

SELECT "users".* FROM "users" LIMIT 1;

Why This Works

take issues a plain LIMIT 1 — no ORDER BY. Use it when you only need any matching row.

Performance Notes

• Slightly faster than first when order does not matter, because the database can return the first row it finds.

Common Mistakes

• Using take where consistent ordering matters (pagination, "first" record semantics). Results can vary between runs.

Problem

Fetch exactly one record and raise if zero or more than one matches.

ActiveRecord

User.where(email: "jane@example.com").sole

Why This Works

Available on Rails 7+. Raises ActiveRecord::RecordNotFound when nothing matches and ActiveRecord::SoleRecordExceeded when more than one row matches. Useful for enforcing uniqueness invariants at query time.

Performance Notes

• Issues a LIMIT 2 internally to detect the "more than one" case without pulling every row.
• Back the lookup column with a unique index so duplicates are impossible in the first place.

Common Mistakes

• Using sole on data that is not guaranteed unique — the exception will fire in production the moment a duplicate slips in.

Problem

Check whether any record matches a condition without loading it.

ActiveRecord

User.exists?(42)
User.exists?(email: "jane@example.com")
User.where(active: true).exists?

SQL

SELECT 1 AS one FROM "users"
WHERE "users"."email" = 'jane@example.com'
LIMIT 1;

Why This Works

The database returns a single constant, not the row, so no columns are read and no ActiveRecord object is instantiated.

Performance Notes

• Much cheaper than .any? or .count > 0 when the relation is not already loaded.
• .any? on an unloaded relation issues a COUNT(*) — exists? is the right primitive.

Common Mistakes

• Using User.where(...).count.positive?. That performs a full COUNT(*) when a LIMIT 1 would do.

Alternative

users.load if needed_later
users.any? # OK after the relation is already loaded

Problem

Get an array of primary keys for a relation.

ActiveRecord

User.where(active: true).ids
# => [1, 4, 7, 9, ...]

SQL

SELECT "users"."id" FROM "users" WHERE "users"."active" = TRUE;

Why This Works

Equivalent to pluck(primary_key). Returns a plain Ruby array of IDs, skipping model instantiation entirely.

Performance Notes

• Only reads the primary key column — the smallest possible payload.
• Good for feeding into where(id: ids), delete_all, or background jobs.

Common Mistakes

• Pulling millions of ids into memory. Use find_each(:pluck) { ... } or batched deletes instead.

Problem

Pull one or more column values from a single row.

ActiveRecord

User.where(email: "jane@example.com").pick(:id)
User.where(active: true).pick(:id, :name)

SQL

SELECT "users"."id", "users"."name" FROM "users"
WHERE "users"."active" = TRUE
LIMIT 1;

Why This Works

pick is limit(1).pluck(...).first in one call — one row, only the columns you asked for.

Performance Notes

• Cheaper than find_by(...).id: no model instantiation, only the requested columns are read.

Common Mistakes

• Using pluck(...).first instead of pick(...). Without limit(1), the database returns every matching row before Ruby throws them away.

Problem

Load an array of raw column values without instantiating models.

ActiveRecord

User.where(active: true).pluck(:email)
User.pluck(:id, :email)
# => [[1, "jane@example.com"], [2, "john@example.com"]]

SQL

SELECT "users"."email" FROM "users" WHERE "users"."active" = TRUE;

Why This Works

pluck bypasses model instantiation, casting only the columns you asked for. It is the fastest way to get raw values.

Performance Notes

• Reads only the selected columns — huge win on wide tables.
• Loads the entire result set into memory. For large sets, combine with in_batches.
• Type casting still runs, so decimals and times return as the expected Ruby type.

Common Mistakes

• User.all.map(&:email) — instantiates every user just to read one column.
• Plucking after an includes — the eager-loaded associations are thrown away.

Problem

Return ActiveRecord objects containing only a subset of columns, or computed columns.

ActiveRecord

User.select(:id, :email)
User.select("users.*, COUNT(orders.id) AS orders_count")
    .left_joins(:orders)
    .group("users.id")

SQL

SELECT "users"."id", "users"."email" FROM "users";

Why This Works

Unlike pluck, select returns real model instances. Attributes that were not selected are missing — accessing them raises ActiveModel::MissingAttributeError.

Performance Notes

• Useful for wide tables where you only need a couple of columns but still want model behavior (methods, scopes).
• Combine with computed aggregates to expose values that don't exist as columns.

Common Mistakes

• Selecting a subset and later calling an accessor for a missing column — production surprise waiting to happen.
• Using select when you actually want pluck. If you don't need model instances, pluck is faster.

Problem

Iterate over a large set of records without loading them all into memory.

ActiveRecord

User.where(active: true).find_each(batch_size: 500) do |user|
  UserSyncJob.perform_later(user.id)
end

SQL

SELECT "users".* FROM "users"
WHERE "users"."active" = TRUE
ORDER BY "users"."id" ASC
LIMIT 500;
-- next batch:
SELECT "users".* FROM "users"
WHERE "users"."active" = TRUE
  AND "users"."id" > 500
ORDER BY "users"."id" ASC
LIMIT 500;

Why This Works

find_each paginates through records by primary key using keyset pagination, yielding one at a time. Memory stays flat regardless of table size.

Performance Notes

• Always keyset-paginated by primary key — that's why the ordering is enforced.
• Default batch size is 1,000. Tune it against memory versus round-trip count.
• Custom order clauses are ignored (and warn) — this is intentional to keep pagination consistent.

Common Mistakes

• Using .each on a giant table — loads everything into memory.
• Expecting a custom order to be respected. Use in_batches with an explicit key if you need different ordering.

Problem

Process large tables in chunks — for example, sending a batch to an external API.

ActiveRecord

User.where(active: true).find_in_batches(batch_size: 1_000) do |batch|
  BillingApi.upsert_batch(batch.map { |u| u.slice(:id, :email) })
end

Why This Works

Same keyset pagination as find_each, but yields the batch itself. Ideal for bulk APIs, bulk inserts, or writing to a file per chunk.

Performance Notes

• Prefer in_batches (returns a relation per batch) when you want to chain update_all, delete_all, or pluck without instantiating models.
• Batch size is a memory-versus-throughput trade — larger batches mean more RAM per iteration but fewer round trips.

Common Mistakes

• Using find_in_batches when you only need update_all. in_batches.update_all(...) skips model instantiation entirely.

Alternative

User.where(active: false).in_batches(of: 5_000).update_all(archived_at: Time.current)