Writing a Sidekiq Worker

Direct Answer

A native Sidekiq job includes Sidekiq::Job, defines perform with small JSON-compatible arguments, and is enqueued with perform_async. Pass stable identifiers rather than live Active Record objects, reload current data inside the job, and make the external or database effect safe to repeat. Let unexpected failures raise so Sidekiq can record and retry them; turn expected business outcomes into explicit state instead of exceptions. The job payload is a durable interface, so argument changes must remain compatible with already queued work.

Deep Dive & Architecture

A queued payload can outlive the request, the process, and the deployment that created it. It should contain enough stable information to locate the work without serializing incidental application state. Reloading an ID sees current truth; storing a deliberate immutable value is appropriate only when the historical snapshot itself is the contract.

Idempotency is about the business effect, not whether Ruby executes twice. A database uniqueness constraint can protect one receipt record, and an external API idempotency key can protect one provider action. A boolean checked before sending can still race unless its read and write share a safe boundary.

Exceptions communicate unexpected failure to Sidekiq. Broad rescue inside perform should either translate to a more meaningful exception or complete an explicit compensating state; silent logging loses retry and alerting. Timeouts should be bounded so one worker thread does not remain occupied indefinitely.

Testing separates the enqueue contract from execution. One test can assert that the correct job and simple arguments are enqueued after the business event. Another can run perform directly with controlled records and prove success, duplicate execution, missing data, and external failure behaviour.

Code Example

class ReceiptJob
  include Sidekiq::Job
  sidekiq_options queue: 'mailers'

  def perform(order_id)
    order = Order.find(order_id)
    return if order.receipt_sent?

    ReceiptDelivery.call(
      order: order,
      idempotency_key: "order-receipt-#{order.id}"
    )
    order.update!(receipt_sent_at: Time.current)
  end
end

ReceiptJob.perform_async(order.id)

Common Mistakes & Pitfalls

Passing objects/Active Records to perform (they don't survive JSON) — pass IDs and re-fetch.