Rails Background Job Patterns Skill

Rails Background Job Patterns

Patterns for building reliable, efficient background jobs in Rails applications.

When This Skill Applies

Creating background jobs with ActiveJob
Configuring Sidekiq queues and workers
Implementing idempotent job patterns
Error handling and retry strategies
Batch processing large datasets
Scheduling recurring jobs

Core Principles

Idempotency

Jobs should be safe to run multiple times:

def perform(order_id)
  order = Order.find(order_id)
  return if order.processed?  # Guard against re-processing

  order.with_lock do
    return if order.processed?
    process_order(order)
    order.update!(status: 'processed')
  end
end

Small, Focused Jobs

Single responsibility per job
Pass IDs, not objects (serialization)
Keep payloads minimal

Error Handling

Use retry_on for transient failures
Use discard_on for permanent failures
Log errors with context

Quick Reference

| Pattern | Use When | |---------|----------| | retry_on | Transient errors (network, timeout) | | discard_on | Permanent failures (record deleted) | | with_lock | Preventing concurrent execution | | Batch processing | Large datasets | | Result tracking | Job status reporting |

Detailed Documentation

patterns.md - Complete job patterns with examples

Basic Job Structure

class ProcessOrderJob < ApplicationJob
  queue_as :default

  retry_on ActiveRecord::RecordNotFound, wait: 5.seconds, attempts: 3
  discard_on ActiveJob::DeserializationError

  def perform(order_id)
    order = Order.find(order_id)
    OrderProcessor.new(order).process!
  end
end

Queue Configuration

# config/sidekiq.yml
:queues:
  - [critical, 6]
  - [default, 3]
  - [low, 1]

Testing Jobs

RSpec.describe ProcessOrderJob, type: :job do
  include ActiveJob::TestHelper

  it 'processes the order' do
    order = create(:order)

    expect {
      ProcessOrderJob.perform_now(order.id)
    }.to change { order.reload.status }.from('pending').to('processed')
  end

  it 'enqueues in the correct queue' do
    expect {
      ProcessOrderJob.perform_later(1)
    }.to have_enqueued_job.on_queue('default')
  end
end

Agent Skills: Rails Background Job Patterns

Skill Files