Pagination in Rails: a Ruby on Rails guide for developers

Large result sets can cripple your Rails application if you're not careful with how you load and display data. Pagination in Rails: a Ruby on Rails guide for developers walks you through proven patterns that keep your queries fast, your memory footprint low, and your users happy. We'll cover everything from lightweight gems to database-native strategies that scale with your traffic.

Why pagination matters in production

When you query 100,000 records from your database and render them all in one HTTP response, you're about to learn some painful lessons. The database takes longer to build the result set, your Ruby process consumes more memory, the response body balloons in size, and your users stare at a blank screen for seconds. Pagination breaks large datasets into manageable chunks so each request is fast, predictable, and cacheable.

The difference between pagination strategies is often the difference between a 50ms response and a 5-second crawl. We've rebuilt pagination logic on dozens of production systems, and the pattern is always the same: start with a lightweight solution, measure real-world query performance, then switch to keyset pagination if sorting or offset speed becomes a bottleneck.

Pagy for lightweight pagination

Pagy is our go-to gem for most Rails projects. It's lean, it doesn't load unnecessary code, and it handles the math correctly without magic. Unlike Kaminari or Will Paginate, Pagy doesn't override ActiveRecord, so your queries stay explicit and your debugging stays sane.

Install it with:

gem 'pagy', '~> 6.0'

Bundle, then include the helper in your ApplicationController:

class ApplicationController < ActionController::Base
  include Pagy::Backend
end

In your controller, use Pagy to paginate your query:

class ProductsController < ApplicationController
  def index
    @pagy, @products = pagy(Product.where(active: true).order(created_at: :desc))
    render :index
  end
end

In your view, use the helpers to render links:

<%= pagy_nav(@pagy) %>
<% @products.each do |product| %>
  <div><%= product.name %></div>
<% end %>

Pagy keeps its configuration minimal. You set the items per page once in an initializer:

# config/initializers/pagy.rb
Pagy::DEFAULT[:items] = 25

Real-world scenario: we ran Pagy on an e-commerce platform with 2M+ products. Query times stayed under 100ms across all pages because Pagy's LIMIT/OFFSET approach works well for small offsets. The pagination links were simple HTML with no JavaScript. When we hit page 50 or higher, we switched strategies—more on that next.

Keyset pagination for big tables

LIMIT/OFFSET pagination degrades as your offset grows. Database needs to skip the first N rows before returning results. Page 1,000 might hit 999,000 skipped rows. Keyset pagination (cursor-based pagination) avoids this by filtering on the sort key itself, not position.

Instead of "give me rows 100-125," you ask "give me 25 rows after the product with id=5042." The database uses an index on that column and returns results in constant time.

Here's how to implement keyset pagination in Rails:

class ProductsController < ApplicationController
  def index
    @per_page = 25
    cursor = params[:cursor]
    
    query = Product.where(active: true).order(id: :asc)
    
    if cursor.present?
      query = query.where('id > ?', cursor)
    end
    
    @products = query.limit(@per_page + 1)
    
    # If we got more than @per_page, there's a next page
    has_next = @products.size > @per_page
    @products = @products.first(@per_page)
    
    @next_cursor = @products.last.id if has_next
  end
end

In your view, pass the cursor in the query string:

<% @products.each do |product| %>
  <div><%= product.name %></div>
<% end %>

<% if @next_cursor %>
  <%= link_to 'Next', products_path(cursor: @next_cursor) %>
<% end %>

Keyset pagination is perfect for infinite scroll or deep pagination. We used it on a ride-hailing platform to load trip history: users could load 10,000 trips without slowdown because we never skipped rows. The trade-off is you can't jump to page 47 directly—you can only go forward one page at a time. For most interfaces, that's fine.

Keyset pagination requires a stable sort column. Use a primary key or unique indexed column, not timestamps that can have duplicates. If you need to sort by multiple columns, use a composite index:

# db/migrate/xxx_add_composite_index.rb
add_index :products, [:status, :created_at, :id], name: 'idx_products_status_created_id'

Then filter on both when you query:

if cursor.present?
  status, created_at, id = cursor.split(',')
  query = query.where('(status, created_at, id) > (?, ?, ?)', status, created_at, id)
end

Limit page sizes

A common mistake is letting users request 10,000 items per page via a query parameter. Set sensible defaults and caps:

class ProductsController < ApplicationController
  ITEMS_PER_PAGE_MAX = 100
  ITEMS_PER_PAGE_DEFAULT = 25
  
  def index
    items_per_page = [
      (params[:per_page] || ITEMS_PER_PAGE_DEFAULT).to_i,
      ITEMS_PER_PAGE_MAX
    ].min
    
    @pagy, @products = pagy(Product.all, items: items_per_page)
  end
end

You can also enforce this at the Pagy configuration level:

# config/initializers/pagy.rb
Pagy::DEFAULT[:items] = 25
Pagy::DEFAULT[:max_items] = 100

Real scenario: we had a SaaS CRM where a sales team member kept requesting 50,000 leads per page. The database query took 8 seconds, blocked other queries, and the response was too large for the browser. Setting a hard cap at 100 items solved it immediately. The user got their data faster by requesting multiple pages with smaller limits.

Index ordered columns

Pagination only stays fast if your database can execute the sort efficiently. Always index the column you're sorting by:

# db/migrate/xxx_add_pagination_index.rb
add_index :products, :created_at
add_index :orders, :status
add_index :users, :updated_at

If you're using keyset pagination, the index is critical. Without it, the WHERE clause becomes a full table scan:

# Slow: full table scan
Product.where('id > ?', 5042).order(id: :asc)

# Fast: index on id (which is the primary key, so it exists by default)

For queries with multiple conditions and sorts, use composite indexes:

# config/initializers/pagy.rb
# This query benefits from an index on (status, created_at)
Product.where(status: 'active').order(created_at: :desc)

# db/migrate
add_index :products, [:status, :created_at], name: 'idx_products_status_created'

Check your indexes with EXPLAIN in Rails console or your database client. A good EXPLAIN output shows "Index" in the plan, not "Seq Scan" or "Full Table Scan":

Product.where(status: 'active').order(created_at: :desc).explain

On a travel platform, we had 50M bookings. A query sorting by created_at without an index took 12 seconds. Adding the index brought it to 80ms. That's the difference between a working feature and an unusable one.

Common mistakes

• Sorting without indexes: Always index the columns in your ORDER BY clause. Use EXPLAIN to verify.
• Allowing unlimited page sizes: Set a hard cap with Pagy's max_items or validate the per_page parameter yourself.
• Mixing OFFSET pagination for deep pages: Switch to keyset pagination when users go past page 10 or so. OFFSET scales poorly.
• Paginating unsorted results: If you don't specify an ORDER BY, results are undefined across pages. Users see duplicates or missing rows.
• Loading all data in memory: Don't do Product.all.paginate. Let the database handle LIMIT/OFFSET.
• Using non-unique sort keys for keyset pagination: If multiple rows have the same id (impossible) or created_at (very possible), keyset pagination skips rows. Use id as a tiebreaker.

Key takeaways

• Pagy is the lean, standard choice for most Rails pagination. It stays out of your way and lets you control queries explicitly.
• Keyset (cursor-based) pagination is the tool for large tables and deep page loads. It queries in constant time by filtering on the sort key, not position.
• Always limit page sizes with a hard cap. Prevent users from accidentally requesting 50,000 rows in one query.
• Index every column you sort by, especially for keyset pagination. An unindexed sort is a full table scan waiting to happen.
• Test with production-like data volumes. Pagination might feel fast on a development database with 1,000 rows but crawl on 10M rows.