---

name: rails-jobs-patterns description: ActiveJob and background processing patterns for Rails. Automatically invoked when working with background jobs, Sidekiq, async processing, job queues, scheduling, or the app/jobs directory. Triggers on "job", "background job", "ActiveJob", "Sidekiq", "async", "queue", "perform_later", "worker", "scheduled job", "cron", "retry", "idempotent". allowed-tools: Read, Grep, Glob

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:

Copydef 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

Detailed Documentation

• patterns.md - Complete job patterns with examples

Basic Job Structure

Copyclass 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

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

Testing Jobs

CopyRSpec.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