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

rails-jobs-patterns

Rails Background Job Patterns

When This Skill Applies

Core Principles