DEV Community: Hassan Farooq

Pagination, filtering, and sorting in a Rails JSON API

Hassan Farooq — Sat, 27 Jun 2026 19:06:30 +0000

Every list endpoint starts innocent. GET /api/users, return them all, ship it. Then a customer signs up forty thousand users, someone asks to filter by role, and the front end wants the newest first. Now you need pagination, filtering, and sorting, and the way you wire them up decides whether the endpoint stays fast and safe or becomes a security hole that also happens to be slow. Here's how I build it, and where the Ransack gem helps.

The request shape

I accept explicit, named params instead of letting the client send anything that smells like SQL.

GET /api/users?role=admin&created_after=2026-01-01&sort=-created_at&page=2&per_page=25

A handy convention for sort: a leading minus means descending, so sort=-created_at is newest first and sort=created_at is oldest first. page and per_page handle paging, with per_page capped on the server so nobody asks for a million rows at once.

The hand-rolled version

class Api::UsersController < Api::BaseController
  MAX_PER_PAGE = 100
  SORTABLE = %w[created_at name email].freeze

  def index
    users = User.all
    users = users.where(role: params[:role]) if params[:role].present?
    users = users.where("created_at >= ?", params[:created_after]) if params[:created_after].present?
    users = users.order(sort_clause)

    per_page = [(params[:per_page] || 25).to_i, MAX_PER_PAGE].min
    page     = [(params[:page] || 1).to_i, 1].max
    paged    = users.limit(per_page).offset((page - 1) * per_page)

    render json: {
      data: paged.map { |u| UserSerializer.new(u) },
      meta: {
        current_page: page,
        per_page: per_page,
        total_count: users.count,
        total_pages: (users.count.to_f / per_page).ceil
      }
    }
  end

  private

  def sort_clause
    field = params[:sort].to_s.delete_prefix("-")
    field = "created_at" unless SORTABLE.include?(field)
    direction = params[:sort].to_s.start_with?("-") ? :desc : :asc
    { field => direction }
  end
end

It reads as a lot, but it's doing four jobs: filter, sort, page, and report back where you are.

The three things that actually matter

Whitelist the columns people can sort and filter by. This is the big one. If you drop params[:sort] straight into order(...), you've handed the client an SQL injection vector and let them sort by some unindexed column that drags the database to its knees. So I keep a SORTABLE allowlist and fall back to a sane default when the field isn't on it. Same thinking for filters: only known params get applied, everything else is ignored.

Cap per_page. Without a ceiling, per_page=1000000 either runs your app out of memory or makes Postgres sweat. Clamp it server side and move on.

Index what you filter and sort by. Here that's role and created_at. Without indexes, every page is a sequential scan, and sorting by an unindexed column means a full sort on every single request. Pagination doesn't save you from a missing index, it just hides the cost until the table grows.

The metadata

The response splits into data and meta. data is the page of records. meta tells the client where it is: current page, per page, total count, total pages. The front end needs that to draw "page 3 of 47" and to know when to stop. On large endpoints I sometimes drop total_count, because counting every matching row on each request gets expensive, and I return a next_cursor instead. Which brings up the real decision.

Offset versus cursor

Offset pagination is what LIMIT and OFFSET give you, and what most gems do by default. It's simple and it lets you jump straight to any page. Two problems show up at scale. OFFSET 1000000 still makes Postgres walk and throw away a million rows before it returns yours, so deep pages crawl. And if rows get inserted or deleted while someone is paging, the window shifts under them and they see the same record twice or miss one entirely.

Cursor pagination, also called keyset pagination, uses a stable pointer instead of a row count. You ask for WHERE created_at < ? ORDER BY created_at DESC LIMIT 25 and hand back the last value you saw as the next cursor. It stays fast at any depth because it seeks straight into the index instead of counting past rows, and it's stable when data changes underneath. The tradeoff is you only get next and previous, not "jump to page 47." I use offset for admin tables and small lists, and cursor for big feeds and exports.

Where Ransack comes in

For paging I reach for Pagy, which is tiny and fast, or Kaminari if I want the more featureful one. For filtering and sorting, Ransack is the usual pick:

# Gemfile: gem "ransack"

def index
  q = User.ransack(params[:q])      # ?q[role_eq]=admin&q[created_at_gteq]=2026-01-01
  q.sorts = params[:sort] || "created_at desc"
  users = q.result.page(params[:page]).per(per_page)   # with Kaminari
  # render data + meta
end

You get a whole query language for free. role_eq for equality, name_cont for "contains", created_at_gteq for a date floor, sorting through q.sorts, even filtering across associations. For an admin screen with a dozen filter combinations, it saves a real amount of code.

There's a catch worth saying out loud, because it bit a lot of people. By default Ransack exposes your whole schema to the client. Every column becomes queryable, which is both a data leak and a way to run slow queries against unindexed columns. Modern Ransack makes you opt in:

class User < ApplicationRecord
  def self.ransackable_attributes(_auth = nil)
    %w[role created_at name email]
  end

  def self.ransackable_associations(_auth = nil)
    []
  end
end

That's the exact same whitelist idea from the hand-rolled version, just expressed through Ransack's hooks. For a small public API I usually prefer explicit params, because the attack surface is smaller and I control every query. For a big internal admin, Ransack earns its place.

The short version

Accept explicit params, whitelist the columns you sort and filter on, cap per_page, and index whatever you filter or sort by. Return data plus meta. Use offset pagination for small and admin lists, cursor pagination for large feeds. Reach for Pagy or Kaminari to page and Ransack to filter, and whatever you do, lock Ransack down with ransackable_attributes so it isn't quietly exposing your whole database.

Building a production-ready create endpoint in Rails

Hassan Farooq — Sat, 27 Jun 2026 18:56:38 +0000

"Design an endpoint to create an order" sounds like a five-line answer. Route, controller, save, done. The reason interviewers like it is that the five-line version skips everything that actually matters in production: the right status codes, where the slow work goes, and what happens when the same request arrives twice. Here's how I'd build it and explain it.

The route

POST /orders.

POST because creating a resource is neither safe nor idempotent. The path is the plural resource name, and creating against the collection is the REST convention for "make a new one." That part really is the easy bit, so don't spend your interview minutes there.

What the controller does, and what it doesn't

The controller handles the HTTP layer and nothing else. It authenticates, authorizes, permits params, hands the actual work to a service, and turns the result into a response.

class OrdersController < ApplicationController
  before_action :authenticate_user!

  def create
    result = OrderCreator.call(user: current_user, params: order_params)

    if result.success?
      render json: OrderSerializer.new(result.order), status: :created
    else
      render json: { errors: result.errors }, status: :unprocessable_entity
    end
  end

  private

  def order_params
    params.require(:order).permit(:product_id, :quantity)
  end
end

Notice what's not in there. No Stripe call, no mailer, no transaction, no line-item math. Those belong in OrderCreator. If you ever want proof that a controller is too fat, count how many reasons it would have to change. This one changes only when the HTTP contract changes.

Status codes are part of the design

This is where the junior answer usually returns 200 for everything and moves on. The status code is how the client knows what happened without parsing your body, so it's worth getting right.

Return 201 Created on success, not 200, and include the new order in the body. A Location header pointing at the new resource is a nice touch.

Return 422 Unprocessable Entity when validation fails, with a structured error body so the front end can show messages next to the right fields.

Return 401 Unauthorized when there's no valid auth, and 403 Forbidden when the user is logged in but not allowed to do this. Those two get conflated constantly, and keeping them straight signals you've actually built APIs.

Return 400 Bad Request when the input is malformed, like the whole order key is missing.

Where the real work goes

The service creates the order and its line items inside a transaction, so they commit together or not at all. The slow and external stuff, charging the card, sending the confirmation email, syncing to a CRM, goes to background jobs. A user shouldn't wait on an SMTP server, and a third party having a bad day shouldn't take your order endpoint down with it. I covered the transaction-versus-external-call reasoning in more depth in my MVC post, but the short version is that a charge can't be rolled back, so it lives outside the transaction.

The part almost everyone forgets: duplicate requests

A user double-taps the buy button. Or the network hiccups and the client retries. Either way the same POST hits you twice, and a naive endpoint cheerfully creates two identical orders and charges the card twice.

The fix is an idempotency key. The client generates a unique key per logical request and sends it in a header. You store that key with a unique constraint, and if a second request shows up with the same key, you return the original result instead of creating anything new.

def create
  existing = IdempotencyKey.find_by(key: request.headers["Idempotency-Key"])
  return render(json: existing.response_body, status: existing.status) if existing

  result = OrderCreator.call(user: current_user, params: order_params)
  # ...store the key with the result, then render
end

This is exactly how Stripe's own API handles retries, which is a good thing to mention because it shows you've read how a serious payments API solves the same problem.

Rounding it out

A few things I'd name to show I'm thinking past one endpoint. A consistent JSON error shape across the whole API so clients parse errors one way. Pagination and filtering on the list endpoint, GET /orders, because it will get slow once a customer has thousands. And versioning under /api/v1/ so a future breaking change doesn't break every client at once.

The short version

POST /orders with a thin controller that authenticates, permits params, and calls a service. 201 on success, 422 on validation errors, and the right 401 versus 403 for auth. Real work in a transaction, slow work in background jobs, and an idempotency key so a double-tap or a retry doesn't create a second order. The route was never the hard part. Everything after it is.

validates vs validate in Rails

Hassan Farooq — Sat, 27 Jun 2026 18:36:55 +0000

The difference between validates and validate in Rails is one letter, and that letter changes everything. One is the built-in helper you feed a list of rules. The other is a hook for a method you write yourself. People mix them up because they read almost the same out loud, so the way I keep them straight is to remember that the plural one comes with rules included and the singular one is bring-your-own.

validates: the built-in rules

validates, with the s, takes an attribute and a set of standard rules that Rails already knows how to enforce. Presence, uniqueness, length, numericality, format, and so on.

class User < ApplicationRecord
  validates :email, presence: true, uniqueness: true
  validates :age,   numericality: { greater_than: 0 }
  validates :title, length: { maximum: 255 }
end

You're not writing any logic here. You're declaring what should be true and letting Rails supply the checking. This covers the large majority of everyday validations, and if a built-in rule fits, use it instead of hand-rolling anything.

validate: your own method

validate, no s, registers a method you wrote. You reach for it when the rule is specific to your domain or depends on more than one field, so no built-in helper covers it. The classic example is making sure an event doesn't end before it starts.

class Event < ApplicationRecord
  validate :end_after_start

  private

  def end_after_start
    return if starts_at.blank? || ends_at.blank?

    if ends_at <= starts_at
      errors.add(:ends_at, "must be after the start time")
    end
  end
end

Three details in that method matter, and they're the parts people get wrong the first time.

The guard clause comes first. I return early if either timestamp is missing, because whether the fields are present is a different question. That's a job for validates :starts_at, :ends_at, presence: true. My custom method only cares about the order of two values that already exist. Skip the guard and you get a nil comparison blowing up, plus a confusing second error on top of the presence one.

errors.add is how a custom validation fails. You attach a message to a specific attribute, and that's what flips valid? to false and what shows up in event.errors for the form to display. No errors.add, no failure, the record saves happily.

The method is private. Nothing outside the model should be calling end_after_start directly, so it lives below a private line with the rest of the internals.

Both of these stop at the application layer

Here's the part worth saying out loud in an interview. validates and validate both run in Ruby, before the INSERT or UPDATE. They're perfect for friendly error messages on a form. They do not protect you under concurrency.

Picture two requests signing up with the same email at the same instant. Both run the uniqueness check, both see no existing row, both pass, both insert. Now you have duplicate emails and a validation that swore it prevented exactly that. The fix is a database constraint underneath the validation:

add_index :users, :email, unique: true

The pattern is validation for the user experience, constraint for correctness. For the event example you can go a step further and add a Postgres check so the rule holds even if a row gets written outside the Rails model:

add_check_constraint :events, "ends_at > starts_at", name: "events_end_after_start"

The short version

validates with an s is for Rails' built-in rules you declare. validate with no s is for a custom method you write, where the guard clause and errors.add do the work. And neither one is a substitute for a database constraint when the data absolutely has to be correct. Use the validation so the user gets a clear message, and back it with a constraint so a race condition can't slip past.

Scopes vs class methods in Rails

Hassan Farooq — Sat, 27 Jun 2026 18:25:29 +0000

Scopes and class methods in Rails do almost the same job, which is exactly why the question trips people up. The honest answer is that a scope is basically a class method that returns a query, with one safety feature bolted on. Once you know what that feature is, you know when to use which. The whole thing comes down to a single nil.

What a scope actually is

A scope is a named, reusable piece of a query. You define it with scope, hand it a lambda, and it gives you back an ActiveRecord::Relation.

class Post < ApplicationRecord
  scope :published, -> { where(published: true) }
  scope :recent,    -> { order(created_at: :desc) }
  scope :by_author, ->(author_id) { where(author_id: author_id) }
end

Two things make that useful. Because every scope returns a relation, you can chain them, and because a relation is lazy, no SQL runs until you actually read the results.

Post.published.recent.limit(10)
Post.published.by_author(42).recent

Each call hands the next one a relation to build on, so all of that collapses into a single SELECT at the end. You're composing one query out of small named parts, not running three.

They're closer than you think

Here's the part that surprises people. A scope and a class method that returns a relation are nearly identical. These two are equivalent:

scope :published, -> { where(published: true) }

def self.published
  where(published: true)
end

Both give you Post.published. Both return a relation. Both chain. So if they're the same, why have both? The difference only shows up when the logic returns nothing useful.

The nil that breaks the chain

A scope has one guarantee a plain method doesn't. If the body of a scope returns nil, Rails quietly swaps in all, so the chain keeps working. A class method has no such net. Return nil from it and the next method in the chain blows up.

Picture a search with a guard clause for a blank term:

def self.search(term)
  return all if term.blank?

  where("title ILIKE ?", "%#{sanitize_sql_like(term)}%")
end

That return all is the whole point. If you wrote return nil instead, then Post.search("").recent would call .recent on nil and you'd get a NoMethodError. The scope version would have rescued you by falling back to all automatically, but inside a class method you're responsible for returning a relation yourself.

So the rule I follow:

Use a scope for simple, always-chainable fragments, especially one-liners like the three on the Post model above.

Use a class method when there's real logic, a conditional, a guard clause, or several steps, because then you want to control the relation by hand and return all on purpose.

One thing scopes are not for

Scopes are for shaping queries, not for doing work. A scope should be a where, an order, a joins, something that narrows or sorts records. The moment you catch a scope sending an email, updating rows, or calling an API, it's in the wrong place. That isn't query composition anymore, and it belongs in a service object.

The short version

Scopes are named, chainable queries that always hand back a relation. A class method does the same job but gives you room for branching and conditionals. Reach for a scope when it's a clean one-liner, reach for a class method when there's logic involved, and whichever you pick, return all instead of nil so the next link in the chain doesn't snap.

How to add a NOT NULL column to a large table safely in Rails

Hassan Farooq — Sat, 27 Jun 2026 18:04:28 +0000

A migration that runs in two milliseconds on your laptop can lock a production table for thirty seconds and pile up every request behind it. The gap is data. Your dev table has twelve rows. The production table has twelve million. An interviewer asked me how I'd add a required status column to a large orders table, and the real answer is that you don't do it in one migration, you do it in four small ones.

First, the part people skip.

What a migration actually is

A migration is a versioned schema change written as Ruby. Each one has a timestamp, Rails records which have run in a schema_migrations table, and db/schema.rb always reflects the current shape of the database. The win is that schema changes become reviewable code that every environment applies in the same order, instead of someone SSHing into production and running ALTER TABLE by hand at 11pm.

class AddEmailToUsers < ActiveRecord::Migration[8.0]
  def change
    add_column :users, :email, :string
    add_index  :users, :email, unique: true
  end
end

That migration is totally fine on a small table. The trouble only shows up at scale, so that's where the interesting decisions live.

What changes when the table is big and live

On your machine the migration runs against an empty table while nothing else is happening. In production it runs against millions of rows while real traffic hits the same table. Four things start to matter that never mattered in dev.

Locks. Some operations grab a lock that blocks reads or writes while they run. Hold that lock on a busy table for a few seconds and requests stack up behind it until something times out.

Table size. Anything that has to touch every row, like a backfill or a column rewrite, takes time proportional to row count. Twelve million rows is a different animal from twelve.

Rolling deploys. During a deploy, old and new versions of your code run at the same time against the same database. The schema has to work for both versions at every moment. This is the part that catches people, and it's why a single migration often can't be safe.

Reversibility. If a deploy goes wrong you want to roll back cleanly, so I want each step to be reversible on its own.

The trap

Here's the migration almost everyone writes first:

add_column :orders, :status, :string, null: false, default: "pending"

One line, reads great, and it's a landmine on a large table. Two problems. On older Postgres, adding a column with a default rewrites every single row while holding a lock, so the table is frozen for the length of that rewrite. And the null: false breaks your rolling deploy the instant the old code, which knows nothing about status, inserts an order without it.

The fix is to stop thinking in one migration and start thinking in phases, each one safe on its own and shipped separately.

Step 1: add the column, nullable

class AddStatusToOrders < ActiveRecord::Migration[8.0]
  def change
    add_column :orders, :status, :string, default: "pending"
  end
end

On Postgres 11 and up, adding a column with a constant default is a metadata change. It does not rewrite the table, so it returns almost instantly. New rows get "pending". Old rows stay NULL for now, and that's fine, because the column is still nullable and old code can keep inserting without touching it.

Step 2: backfill the old rows in batches

class BackfillOrderStatus < ActiveRecord::Migration[8.0]
  disable_ddl_transaction!

  def up
    Order.where(status: nil).in_batches(of: 10_000) do |batch|
      batch.update_all(status: "pending")
      sleep(0.1)
    end
  end

  def down
    # nothing to undo
  end
end

The point of batching is to never hold a long lock. Ten thousand rows at a time, each in its own quick transaction, with a short pause so other queries get a turn. Updating all twelve million in one statement would be one enormous transaction sitting on a lock, which is the thing we're trying to avoid.

Step 3: ship the code that sets status

Deploy your application change so every path that creates an order sets status explicitly. After this point, nothing writes a NULL anymore. This is a code deploy, not a migration, and it has to land before the next step.

Step 4: enforce NOT NULL safely

Now that the column is fully populated and nobody writes NULL, you can add the constraint. Doing it the blunt way still scans the whole table under a lock to verify, so on Postgres I validate it in two moves:

class MakeOrderStatusNotNull < ActiveRecord::Migration[8.0]
  def up
    add_check_constraint :orders, "status IS NOT NULL",
      name: "orders_status_not_null", validate: false
    validate_check_constraint :orders, name: "orders_status_not_null"
  end

  def down
    remove_check_constraint :orders, name: "orders_status_not_null"
  end
end

Adding the constraint as validate: false is instant because it doesn't check existing rows yet. Then validate_check_constraint checks them without taking the heavy lock that a plain NOT NULL would. Once it passes, you have the guarantee you wanted and nobody noticed.

The short version

A migration is versioned schema-as-code, and the moment a table gets big and busy you care about locks, table size, rolling deploys, and clean rollbacks. To add a required column: add it nullable, backfill in batches, deploy code that sets it, then enforce NOT NULL. The one rule worth tattooing on your hand is never add a NOT NULL column with a backfill in a single migration on a large table.

One tool that makes this automatic: the strong_migrations gem. It flags unsafe migrations in code review and prints the safe version for you, so you catch the landmine before it ships instead of during the incident.

Stop putting side effects in Rails callbacks

Hassan Farooq — Sat, 27 Jun 2026 15:27:16 +0000

Callbacks are one of those Rails features that feel great for about three months and then quietly ruin your afternoon. The question I got asked in an interview was simple: are model callbacks good to use, and how do you avoid overusing them? My answer is that they're good for data and bad for behavior, and the trouble starts the moment you forget which is which.

Where callbacks earn their keep

The good use is small, record-local cleanup. Stuff that's only about keeping the row itself tidy, and that should happen no matter who saves the record.

class User < ApplicationRecord
  before_validation :normalize_email

  private

  def normalize_email
    self.email = email.to_s.strip.downcase
  end
end

Downcasing an email, stripping whitespace, setting a default, generating a slug from a title. These are cheap, predictable, and they don't reach outside the record. Nobody gets surprised by a callback that lowercases an email. This is exactly what before_validation and before_save are for, and I'd reach for them without a second thought.

Where they turn on you

Now the bad use. Side effects.

class Order < ApplicationRecord
  after_create :charge_customer      # external API
  after_create :send_confirmation    # email
  after_create :sync_to_crm          # another external API
end

This looks tidy. It isn't. A plain Order.create now secretly charges a card, sends an email, and pokes a third party, and none of that is visible at the place you called create.

Here's how it bites. Six months later someone writes a rake task to backfill old orders, calls Order.create, and accidentally emails five thousand customers and runs five thousand charges. Or you sit down to write a test for something unrelated to payments, and you can't, because every create in the suite now needs Stripe, the mailer, and the CRM stubbed. The save and the side effects are welded together, and you can't pull them apart.

There's also a sharp edge most people meet by accident. destroy_all runs callbacks, delete_all skips them. Same intent, "remove these rows," two different behaviors depending on which method you typed. If your cleanup logic lives in a callback, one of those quietly does the wrong thing.

How to keep them from spreading

The trick is noticing when a callback stopped being cleanup and turned into a workflow. The fix is to pull that workflow out into a service object you call on purpose.

class OrderCreator
  def self.call(user:, params:)
    order = user.orders.create!(params)

    PaymentCharger.call(order)
    OrderMailer.confirmation(order.id).deliver_later
    CrmSyncJob.perform_later(order.id)

    order
  end
end

Same work, completely different feel. The side effects are right there in front of you, in order, on purpose. A test that just needs an order calls create! and gets an order, nothing else. The jobs are queued because you asked, not because saving a row happened to trigger them. When the CRM sync breaks, you know exactly where to look.

The line I'd actually say

Use callbacks for data, not for behavior. If a callback only touches the record's own attributes, leave it. The second it reaches outside the record, like sending mail, calling an API, or orchestrating other models, it belongs in a service object.

One honest caveat so you don't sound like a zealot. after_commit is a reasonable middle ground for "enqueue a job once this record is actually saved," because it only fires after the transaction commits, not on a rollback. Even then I usually enqueue from the service layer instead, just to keep the flow visible. Both are defensible. The thing worth being able to explain is why fat callbacks hurt, because that's the part that tells an interviewer you've been burned by them before.

Fat controllers, fat models, and the layer MVC forgot

Hassan Farooq — Sat, 27 Jun 2026 14:52:43 +0000

MVC is the first thing anyone learns about Rails and the last thing people actually get right. The pattern itself is simple. Three layers, each with one job. Where it falls apart is the stuff that doesn't fit cleanly into any of the three, and that's exactly what interviewers poke at.

I'll walk through the three layers fast, then spend the real time on the question that separates a junior answer from a mid-level one: where do you put the logic for creating an order, charging Stripe, and sending a confirmation email?

The three layers

The model owns your data and the rules attached to it. With Active Record that means associations, validations, scopes, and small bits of behavior that belong to the record itself, like order.total or user.full_name. If the question is "what is true about this record," the answer lives in the model.

The controller handles one request. It reads params, checks who you are and what you're allowed to do, calls a model or a service, and picks a response. That's it. A controller should read like a list of instructions a manager gives, not like the work itself. People call a bloated one a "fat controller," and it's a smell.

The view renders what the user sees. An ERB template, a Turbo Stream, a JSON response from a serializer. Presentation only. The view should never decide business rules. It just shows whatever the controller handed it.

A request walks through them in order. The router matches the URL to a controller action, the controller calls a model or service, the result goes to a view, and the response heads back to the browser.

The part nobody teaches

Here's the trap. Rails makes it so easy to put code in the model or the controller that people put everything there. Both rot the same way.

Stuff everything in the model and you get a 600-line User class that sends emails, talks to Stripe, and syncs a CRM, all triggered by callbacks you forgot existed. Stuff everything in the controller and you get a create action that's forty lines of business logic with rendering buried at the bottom.

The fix is to notice when an operation isn't really model data and isn't really request handling. When something coordinates several models, calls an external service, or kicks off side effects, it's a workflow. Workflows go in a service object. That's the missing letter MVC never gave you.

The order example

So you need to create an order, charge the customer through Stripe, and email them a confirmation. Three things, and they each belong in a different place.

Start with the controller. It should stay boring:

class OrdersController < ApplicationController
  def create
    result = OrderCreator.call(user: current_user, params: order_params)

    if result.success?
      render json: result.order, status: :created
    else
      render json: { errors: result.errors }, status: :unprocessable_entity
    end
  end

  private

  def order_params
    params.require(:order).permit(:product_id, :quantity)
  end
end

Notice what's missing. No Stripe, no mailer, no transaction. The controller checks the user (through current_user), permits params, hands off to a service, and turns the result into a response. If you came back in a year and the only change was the JSON shape, this is the only file you'd touch.

Now the service, where the actual workflow lives:

class OrderCreator
  def self.call(user:, params:)
    new(user, params).call
  end

  def initialize(user, params)
    @user = user
    @params = params
  end

  def call
    order = nil

    Order.transaction do
      order = @user.orders.create!(@params)
      order.build_line_items_from_cart!
    end

    charge_customer(order)
    OrderMailer.confirmation(order.id).deliver_later

    Result.success(order)
  rescue ActiveRecord::RecordInvalid => e
    Result.failure(e.record.errors.full_messages)
  rescue Stripe::CardError => e
    order&.update(status: "payment_failed")
    Result.failure([e.message])
  end

  private

  def charge_customer(order)
    Stripe::Charge.create(
      amount: order.total_cents,
      currency: "usd",
      customer: @user.stripe_customer_id,
      idempotency_key: "order-#{order.id}"
    )
  end
end

Three pieces, three homes:

The order and its line items are database writes that have to succeed or fail together. You don't want an order with no line items, or line items pointing at an order that never saved. So they go inside a transaction. I use create! with the bang so a failure raises and the transaction rolls back instead of silently saving half the data. The order's own rules, like validates :quantity, numericality: { greater_than: 0 }, still live on the Order model where they belong.

The Stripe charge sits in the service but outside the transaction, and that placement is deliberate. A transaction holds a database connection and often locks rows. If you wrap a network call to Stripe inside it, you're holding that lock for as long as Stripe takes to answer, which could be seconds. Worse, a charge can't be rolled back. If the DB transaction fails after the card was charged, your database and Stripe now disagree and the customer is out real money. So I charge after the transaction commits, with an idempotency key so a retry never double-charges.

The email goes to a background job with deliver_later. The customer shouldn't sit and wait for an SMTP server, and a flaky mail provider shouldn't blow up an otherwise good order. Note I pass order.id, not the order object, because the job runs later and should reload fresh data.

The one-liner

If an interviewer asks and you've got ten seconds: controllers coordinate the request, models hold data and record-level rules, views render, and any multi-step workflow with side effects goes in a service object. The order example is the proof. Creation in a transaction, the external charge outside it, the email in a job, and a controller thin enough to read in one breath.

HABTM, has_many through, STI, and polymorphic associations in Rails

Hassan Farooq — Thu, 25 Jun 2026 16:31:08 +0000

Once you're past belongs_to and has_many, Rails gives you four more association tools that confuse a lot of people in interviews: has_and_belongs_to_many, has_many :through, single table inheritance, and polymorphic associations. They sound advanced, but each one solves a specific, concrete problem. The trick is knowing which problem.

I'll go through all four with real tables and real code, then end on the one comparison interviewers love to ask: why pick has_many :through over HABTM.

has_and_belongs_to_many (HABTM)

This is the simplest way to model a many-to-many relationship. Say a user can be on many projects, and a project can have many users. You set it up on both sides:

class User < ApplicationRecord
  has_and_belongs_to_many :projects
end

class Project < ApplicationRecord
  has_and_belongs_to_many :users
end

Behind the scenes there's a join table that holds nothing but the two foreign keys. By convention Rails wants it named after both tables in alphabetical order:

create_table :projects_users, id: false do |t|
  t.belongs_to :project
  t.belongs_to :user
end

Notice id: false. The join table has no primary key and, more importantly, no model. You never write class ProjectsUser. That's the whole point of HABTM: it's lightweight. You get user.projects and project.users and that's it.

It's also where HABTM runs out of room. There's no model, so there's nowhere to put a role, a joined_at timestamp, a validation, or a callback. The join is just a link and stays a link.

has_many :through

This is the grown-up version of the same many-to-many. Instead of a bare join table, you create a real model for the relationship and route through it:

class User < ApplicationRecord
  has_many :memberships
  has_many :projects, through: :memberships
end

class Project < ApplicationRecord
  has_many :memberships
  has_many :users, through: :memberships
end

class Membership < ApplicationRecord
  belongs_to :user
  belongs_to :project
end

The migration looks like a normal table because it is one:

create_table :memberships do |t|
  t.belongs_to :user, null: false, foreign_key: true
  t.belongs_to :project, null: false, foreign_key: true
  t.string :role, default: "member"
  t.datetime :joined_at
  t.timestamps
end

Now the relationship can carry data. A membership has a role, a joined date, timestamps, validations, whatever you need. You can ask user.memberships.where(role: "admin") or add validates :role, inclusion: { in: %w[member admin owner] } on the Membership model. None of that is possible with a plain HABTM join.

You still get the convenient shortcut: user.projects skips straight past memberships to the projects on the other side. You just also have the join model available when you need it.

Single table inheritance (STI)

STI is for when several models are variations on a theme and share most of their columns. Instead of one table per model, they all live in one table, and Rails uses a type column to remember which class each row belongs to.

class User < ApplicationRecord
end

class Admin < User
end

class Customer < User
end

There's no separate admins or customers table. Everything sits in users, and you just need that type column:

add_column :users, :type, :string

When you call Admin.create(email: "a@example.com"), Rails writes a row to users with type set to "Admin". When you later run Admin.all, it automatically adds WHERE type = 'Admin' for you. User.all still returns everyone, and each record comes back as the right subclass, so an admin row gives you back an Admin instance with all its methods.

STI is great when the subclasses are genuinely alike and differ mostly in behavior. It gets ugly fast when they don't. If Admin needs five columns that Customer never uses, every customer row carries five NULLs forever, and the table turns into a junk drawer. The rule I use: STI when subclasses share almost all their columns, separate tables when they diverge.

Polymorphic associations

A polymorphic association lets one model belong to more than one kind of parent, without a separate foreign key for each one. The classic example is comments. You want to comment on a post, and also on a photo, and maybe later on a video. You don't want post_id, photo_id, and video_id columns sitting mostly empty on the comments table.

Instead you store two columns: one for the parent's id, and one for the parent's type.

class Comment < ApplicationRecord
  belongs_to :commentable, polymorphic: true
end

class Post < ApplicationRecord
  has_many :comments, as: :commentable
end

class Photo < ApplicationRecord
  has_many :comments, as: :commentable
end

The migration uses references with polymorphic: true, which creates both columns at once:

create_table :comments do |t|
  t.text :body
  t.references :commentable, polymorphic: true, null: false
  t.timestamps
end

That gives you commentable_type (a string like "Post" or "Photo") and commentable_id. When you save a comment on a post, Rails stores "Post" and the post's id. When you read comment.commentable, it uses the type to know which table to look in. You can comment on any model that declares has_many :comments, as: :commentable, and adding a new commentable type later means zero schema changes.

One thing to watch: a polymorphic column can't have a normal database foreign key constraint, because the database doesn't know which table the id points to. You give up that bit of referential integrity in exchange for the flexibility.

So when do you pick has_many :through over HABTM?

This is the question that comes up most, and the answer is short: the moment the relationship itself needs to hold anything.

HABTM gives you a link and nothing else. The second you need a role on the membership, or a timestamp for when someone joined, or a validation that stops duplicates, or a callback, or even just the ability to query the join directly, HABTM has no place to put it. There's no model. You'd have to migrate to has_many :through anyway, and migrating later is more painful than starting there.

So in practice I almost always reach for has_many :through. HABTM is fine for a pure tag-style link that you're certain will never grow attributes, like connecting articles to categories where the connection is just a connection. But "never" is a strong word, and most join tables sprout a column eventually. Starting with a join model costs you one extra file today and saves you a migration and a refactor down the line.

If you can only remember one line for the interview: use HABTM when the relationship is just a link, and has_many :through when the relationship is a thing in its own right.

includes vs joins vs preload vs eager_load in Rails

Hassan Farooq — Mon, 22 Jun 2026 17:45:29 +0000

These four all deal with associations, and they're easy to mix up. The way I keep them straight is to ask two questions about each: what SQL does it run, and does it actually pull the associated records into memory? Once you can answer both, picking the right one is straightforward.

Method	SQL it generates	Loads the association?	Reach for it when
`joins`	INNER JOIN	No	You filter or sort by the associated table
`preload`	Separate queries, one per association	Yes	You'll read the association and want it loaded separately
`eager_load`	A single LEFT OUTER JOIN	Yes	You need to read and filter by the association in one query
`includes`	Rails picks preload or eager_load	Yes	The default for killing N+1 when you're not sure which you need

joins

joins builds a SQL join but does not load anything into memory. User.joins(:posts).where(posts: { published: true }) filters users by their posts cheaply. But if you then call user.posts in Ruby, you get a fresh query for every user, which is the N+1 you were trying to avoid, because the posts were never loaded. Use joins to filter and sort, not to display.

preload

preload always runs separate queries, one for the users and one for their posts, then stitches them together in memory. There is no join, so you can't reference the posts table in a where. Try it and Rails will complain.

eager_load

eager_load forces a single LEFT OUTER JOIN and builds the association out of the joined rows. Unlike preload, it still works when you filter on the joined table, because the join is right there in the query.

includes

includes is the one I reach for most. You're telling Rails what you want ("load these associations, don't N+1 me") and letting it choose the strategy. By default it preloads with separate queries. The moment you reference the associated table in a where or order, it switches to eager_load and runs the join instead. You usually don't have to think about which.

Putting it to work

Two quick cases to make it stick.

To list users along with their posts, use User.includes(:posts). You're displaying the association, so separate queries are fine and you've killed the N+1.

To find only the users who have published posts, use User.joins(:posts).where(posts: { published: true }). You're filtering by the association and you never need the post objects in memory, so there's no reason to load them. If you want to filter and then display those posts, use includes together with references, or just use eager_load.

What is a database transaction, and when do you reach for one in Rails?

Hassan Farooq — Mon, 22 Jun 2026 17:24:25 +0000

A transaction groups several database writes into one atomic unit. Either all of them commit, or none of them do. That is the guarantee you are buying: you never end up with half the work done and a database that contradicts itself.

People recite the full ACID list (atomicity, consistency, isolation, durability), but the property I actually reach for day to day is atomicity. All or nothing.

A real scenario: checkout

Placing an order looks like one action to the user, but under the hood it is several writes that all have to agree with each other.

Order.transaction do
  order = user.orders.create!(status: "pending")
  cart.items.each do |item|
    order.line_items.create!(product: item.product, quantity: item.quantity)
    item.product.decrement!(:stock, item.quantity)
  end
end

Say the line items save fine but the stock decrement blows up halfway through the loop. Without a transaction I now have an order that sold three units of something while only deducting one from inventory. With the transaction, the exception rolls the whole block back and I am left in a clean state, as if the order never happened.

Gotchas I watch for

Rollback only fires on a raised exception. This is the one that bites people. create returns false on a validation failure, it does not raise, so the transaction happily commits everything else around it. Use the bang versions inside the block (create!, save!, update!) so a failure actually throws and triggers the rollback.

Don't rescue the exception inside the block. If you wrap the body in a begin/rescue and swallow the error, you have also swallowed the signal that tells the transaction to roll back, so it commits anyway. If you genuinely need to abort without an exception bubbling up to your callers, raise ActiveRecord::Rollback. It rolls back quietly and does not re-raise.

Keep slow external calls out of the transaction. An open transaction holds locks on the rows you have touched. If you put a Stripe charge or any HTTP request inside the block, you are holding those locks for the length of a network round trip. Under load that is how you get lock contention and a drained connection pool.

Why the Stripe charge specifically is risky

There are two problems. The first is the lock-holding one above. The second is worse: a charge is an external side effect, and you cannot roll it back. If the transaction commits and something downstream fails, or the transaction rolls back after Stripe already charged the card, your database and Stripe now disagree, and nothing reconciles that for you.

The pattern I use is to do the local database work inside the transaction and handle the charge outside it. Confirm the payment through webhooks and reconcile against them, so a retry never double-charges the customer.

How do you know you need a database index?

Hassan Farooq — Mon, 22 Jun 2026 17:04:48 +0000

I got asked this in an interview years ago, and I've asked it from the other side of the table since. I like it because the lazy answer ("index everything") is wrong, and the real skill is knowing where to look before you touch anything. So here's the whole loop: how I spot a column that needs an index, how I prove the index actually helped, and what it costs me to add one.

Which columns actually need one

The candidates are columns you filter, sort, or join on. In SQL terms, anything in a WHERE, ORDER BY, JOIN, or GROUP BY on a table that's big or growing.

A few I always check first:

Foreign keys, like user_id and order_id. In Rails these don't get an index automatically when you add the reference unless you ask for one, and they get hammered by association lookups and joins. This is the missing index I find most often.

Lookup columns like email, slug, and token. These usually want a unique index anyway.

Filter and sort columns like status and created_at, the stuff your dashboards page over.

None of it matters at small scale. A sequential scan over 500 rows is instant. The pain shows up at a few million rows, when an endpoint that felt fine in development starts timing out in production.

How I measure whether it helped

Mostly EXPLAIN ANALYZE.

EXPLAIN ANALYZE
SELECT * FROM orders WHERE user_id = 42 AND status = 'paid';

Here's what I read in the output. A Seq Scan on a big table is the red flag: Postgres is reading every row to answer the query. After I add the index, I want to see that become an Index Scan or a Bitmap Index Scan.

I compare the actual time before and after, not just the plan shape. I also check estimated rows against actual rows. When those are far apart, the planner is running on stale statistics, and a quick ANALYZE sometimes fixes the query with no index at all.

The local plan only goes so far. To find what's worth fixing, I look at production: pg_stat_statements for the genuinely expensive queries, plus whatever APM is running (New Relic, Skylight, Datadog) and the query timings in the Rails log. It's easy to lovingly optimize a query that runs twice a day while ignoring the one that runs ten thousand times an hour.

Indexes aren't free

This is the part people skip. Every index costs disk space, and it slows down writes, because every INSERT, UPDATE, and DELETE has to keep the index current. On a write-heavy table that adds up fast.

So I don't index on a hunch. I index columns I can show are being queried, and I drop indexes nobody uses. An unused index is pure cost. It slows your writes and gives you nothing back.

The practical one: `Order.where(user_id: id, status: "paid")`

I'd add a composite index on [:user_id, :status]:

add_index :orders, [:user_id, :status]

Column order is the whole game here. user_id goes first because it's the selective, always-present equality filter. The B-tree narrows to one user's orders, then status filters within that small set.

There's a bonus: because user_id is the leftmost column, this same index also covers queries that filter on user_id alone, so you don't need a second index just for it.

Reversing it to [:status, :user_id] would be worse. status has only a handful of distinct values, so leading with it barely narrows the search before it gets to user_id.

The N+1 Query Problem

Hassan Farooq — Sun, 21 Jun 2026 19:18:46 +0000

You ship a /posts index page. It renders 50 posts, and for each one it shows the author's name with post.author.name. QA says the page is slow, and the logs are full of repetitive SQL.

What is this problem called, and why is it happening?
How would you detect it, in dev and in a running app?
How do you fix it, and what's the difference between the main fixing strategies?

Answer: N+1 queries

What it is and why it happens

This is the N+1 query problem. One query loads the 50 posts, then Active Record fires one more query per post to load post.author. That's 1 + N queries (1 for posts, 50 for authors) when it could be 2, or even 1. Active Record associations are lazy by default, so the author isn't loaded until you call post.author. Do that inside a loop and you get a round trip per record.

How to detect it

Dev logs: you'll see the same SELECT ... FROM authors WHERE id = ? over and over with different IDs. That repetition is the tell.
The Bullet gem: built for this. It warns you in dev when you should add eager loading, and also when you're eager-loading something you don't need.
An APM in production (Sentry, New Relic, Scout): flags endpoints firing a lot of queries.
Tests: assert on query count with something like assert_queries or an RSpec matcher so CI catches a regression before it ships.

How to fix it

Eager-load the association:

# N+1
@posts = Post.all
@posts.each { |p| puts p.author.name }   # 1 + 50 queries

# Fixed
@posts = Post.includes(:author)
@posts.each { |p| puts p.author.name }   # 2 queries

There are four tools, and they don't do the same thing:

Method	What it does	When to use it
`preload`	Loads the association in a separate query and matches it in memory	You just need the data and aren't filtering or ordering by the association
`eager_load`	One `LEFT OUTER JOIN` that loads everything in a single query	You need to filter or order by the association and read its attributes
`includes`	Defaults to `preload`, but switches to `eager_load` if you reference the association in a `where` or `order`	Your usual default. Let Rails decide
`joins`	`INNER JOIN` for filtering or sorting. Does not load the association into memory	You need to filter by the association but don't read its attributes

The trap: joins alone does not preload. If you joins(:author) and then call p.author.name in the loop, you're right back to N+1. Reach for includes or eager_load when you actually read the association's attributes.

DEV Community: Hassan Farooq

Pagination, filtering, and sorting in a Rails JSON API

The request shape

The hand-rolled version

The three things that actually matter

The metadata

Offset versus cursor

Where Ransack comes in

The short version

Building a production-ready create endpoint in Rails

The route

What the controller does, and what it doesn't

Status codes are part of the design

Where the real work goes

The part almost everyone forgets: duplicate requests

Rounding it out

The short version

validates vs validate in Rails

validates: the built-in rules

validate: your own method

Both of these stop at the application layer

The short version

Scopes vs class methods in Rails

What a scope actually is

They're closer than you think

The nil that breaks the chain

One thing scopes are not for

The short version

How to add a NOT NULL column to a large table safely in Rails

What a migration actually is

What changes when the table is big and live

The trap

Step 1: add the column, nullable

Step 2: backfill the old rows in batches

Step 3: ship the code that sets status

Step 4: enforce NOT NULL safely

The short version

Stop putting side effects in Rails callbacks

Where callbacks earn their keep

Where they turn on you

How to keep them from spreading

The line I'd actually say

Fat controllers, fat models, and the layer MVC forgot

The three layers

The part nobody teaches

The order example

The one-liner

HABTM, has_many through, STI, and polymorphic associations in Rails

has_and_belongs_to_many (HABTM)

has_many :through

Single table inheritance (STI)

Polymorphic associations

So when do you pick has_many :through over HABTM?

includes vs joins vs preload vs eager_load in Rails

joins

preload

eager_load

includes

Putting it to work

What is a database transaction, and when do you reach for one in Rails?

A real scenario: checkout

Gotchas I watch for

Why the Stripe charge specifically is risky

How do you know you need a database index?

Which columns actually need one

How I measure whether it helped

Indexes aren't free

The practical one: Order.where(user_id: id, status: "paid")

The N+1 Query Problem

Answer: N+1 queries

The practical one: `Order.where(user_id: id, status: "paid")`