oban-essentials

Oban Essentials

RULES — Follow these with no exceptions

1. Always use Oban.Worker with explicit queue and max_attempts options
2. Return {:ok, result} for success, {:error, reason} for retryable failures, {:cancel, reason} for permanent failures — prefer {:ok, result} over bare :ok for explicit intent (bare :ok is supported), and prefer {:error, reason} over raising
3. Make workers idempotent — the same job may run more than once due to retries or node restarts
4. Use unique option to prevent duplicate jobs — specify period, fields, and keys
5. Test with Oban.Testing — use assert_enqueued and perform_job, never call perform/1 directly
6. Never put large data in job args — store IDs and fetch fresh data in the worker
7. Use Oban.insert/1 (not Oban.insert!/1) and handle the error tuple

---

Worker Definition

defmodule MyApp.Workers.SendWelcomeEmail do
  use Oban.Worker,
    queue: :mailers,
    max_attempts: 3,
    unique: [period: 300, fields: [:args], keys: [:user_id]]

  @impl Oban.Worker
  def perform(%Oban.Job{args: %{"user_id" => user_id}}) do
    case MyApp.Accounts.get_user(user_id) do
      nil ->
        {:cancel, "user #{user_id} not found"}

      user ->
        MyApp.Mailer.send_welcome(user)
        {:ok, :sent}
    end
  end
end

Key Points

• queue — which queue runs this worker (must match config)
• max_attempts — total attempts including the first (3 = 1 original + 2 retries)
• unique — deduplication; period in seconds, keys specifies which args fields to compare
• Pattern match on %Oban.Job{args: ...} — args are always string-keyed maps (JSON serialized)

---

Enqueuing Jobs

# Basic insert — always handle the result
case MyApp.Workers.SendWelcomeEmail.new(%{user_id: user.id}) |> Oban.insert() do
  {:ok, job} -> {:ok, job}
  {:error, changeset} -> {:error, changeset}
end

# Schedule for later
%{user_id: user.id}
|> MyApp.Workers.SendWelcomeEmail.new(schedule_in: 3600)
|> Oban.insert()

# Bad — raises on failure, no error handling
MyApp.Workers.SendWelcomeEmail.new(%{user_id: user.id}) |> Oban.insert!()