rails-jobs-patterns

ag0os's avatarfrom ag0os

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

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026

When & Why to Use This Skill

This Claude skill provides comprehensive patterns and best practices for Ruby on Rails background processing using ActiveJob and Sidekiq. It empowers developers to build resilient, scalable systems by implementing idempotent jobs, robust error handling, and optimized queue management strategies.

Use Cases

  • Designing idempotent background jobs to prevent duplicate data processing in critical workflows like payment processing or order fulfillment.
  • Implementing advanced error handling and retry strategies (retry_on/discard_on) to manage transient failures in external API integrations.
  • Optimizing application responsiveness by offloading long-running tasks, such as batch data exports or heavy image processing, to background workers.
  • Configuring multi-priority queue systems (critical, default, low) to ensure high-priority business logic is executed with minimal latency.
  • Establishing standardized testing patterns for background jobs to ensure reliable execution and correct queue routing.
namerails-jobs-patterns
descriptionActiveJob 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-toolsRead, 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:

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

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