sidekiq

Sidekiq

Iron Laws

1. Jobs are idempotent - Safe to retry multiple times
2. Pass IDs and JSON primitives only - Never pass ORM objects
3. Enqueue after commit - Use the active ORM's commit-safe hook, not after_save or inline before commit
4. Keep queue names intentional - Operationally meaningful
5. Use retries intentionally - Don't hide permanent failures
6. Profile slow jobs - Use Sidekiq 8 profiling
7. Iterate large datasets - Use Sidekiq::Iteration

Version Compatibility

Job Template

class MyJob
  include Sidekiq::Job

  sidekiq_options queue: 'default', retry: 3

  def perform(user_id)
    user = User.find(user_id)
    # Do work
  end
end

JSON-Safe Arguments

✅ Correct:

MyJob.perform_async(user.id)                    # IDs
MyJob.perform_async(123, "string", true)        # Primitives
MyJob.perform_async(user.created_at.iso8601)    # Dates as strings

❌ Incorrect:

MyJob.perform_async(user)              # ORM objects
MyJob.perform_async(Date.today)        # Date objects
MyJob.perform_async(status: :active)   # Symbols

Idempotency

Jobs must be safe to run multiple times:

class ProcessPaymentJob
  include Sidekiq::Job

  def perform(payment_id)
    payment = Payment.find(payment_id)
    return if payment.processed?  # State check
    
    payment.with_lock do
      return if payment.processed?  # Double-check
      payment.process!
    end
  end
end

Strategies: State check | Upsert | UUID dedup | Locking

Commit-Safe Enqueueing by ORM

Always identify the ORM for the touched package before giving enqueue advice.

Active Record

Use after_commit for model-driven enqueueing that depends on committed data:

class User < ApplicationRecord
  after_commit :enqueue_welcome_email, on: :create

  private

  def enqueue_welcome_email
    WelcomeEmailJob.perform_async(id)
  end
end