oban-essentials

Files (3)

• SKILL.md
• oban_job_template.ex · assets/
• oban_testing_checklist.md · assets/

SKILL.md (first lines)

# Oban Essentials

Use this skill before writing ANY Oban worker or enqueuing jobs.


## End-to-End Workflow

When setting up a new Oban worker, follow these steps in order:

1. **Add queue to config** — define the queue name and concurrency in `config/config.exs`
2. **Define worker module** — `use Oban.Worker` with explicit `queue`, `max_attempts`, and `unique` options
3. **Enqueue from context** — call `Oban.insert/1` inside a context function, not a LiveView
4. **Write tests** — use `Oban.Testing` with `assert_enqueued` and `perform_job`, covering all return paths


## RULES — Follow these with no exceptions

**1.** **Use `Oban.Worker` with explicit `queue` and `max_attempts`** — never rely on defaults — see [Worker Definition](#worker-definition)
**2.** **Make workers idempotent** — the same job may execute more than once, so guard side effects — see [Idempotency](#idempotency)
**3.** **Never put large data in job args** — store IDs and fetch fresh data in the worker — see [Job Args Best Practices](#job-args-best-practices)
**4.** **Use `Oban.insert/1` (not `Oban.insert!/1`)** — handle the error tuple instead of raising — see [Enqueuing Jobs](#enqueuing-jobs)
**5.** **Enqueue from contexts, not LiveViews** — keep the web layer thin — see [Enqueuing from Contexts](#enqueuing-from-contexts)
**6.** **Return one of `{:ok, _}`, `{:error, _}`, `{:cancel, _}`, `{:snooze, _}` from `perform/1`** — never raise for expected failures — see [Return Values](#return-values)


## FCIS at this boundary

`perform/1` is an **edge runner**: load by ID, call pure/context functions, return Oban-tagged results. Do not bury domain rules only inside the worker.

❌ **Bad:** worker owns complex domain state

```elixir
def perform(%Oban.Job{args: %{"order_id" => id}}) do
  order = Repo.get!(Order, id)
  total = Enum.reduce(order.lines, 0, &(&1.amount + &2))
  # ad-hoc retries / partial updates mixed here...
  Repo.update!(Ecto.Changeset.change(order, total: total, shipped: true))
  :ok
end
```

✅ **Good:** fetch → domain → tuple

```elixir
@impl Oban.Worker
def perform(%Oban.Job{args: %{"order_id" => id}}) do
  with {:ok, order} <- Orders.fetch(id),
       {:ok, order} <- Orders.mark_shipped(order) do
    {:ok, order.id}
  else
    {:error, :not_found} -> {:cancel, "order missing"}
    {:error, reason} -> {:error, reason}
  end
end
```

## Worker Definition

See [`assets/oban_job_template.ex`](assets/oban_job_template.ex) for a copy-paste worker skeleton (`perform/1`, `max_attempts`, `unique:`, `backoff/1`, idempotency guard).

```elixir
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
    with {:ok, user} <- MyApp.Accounts.fetch_user(user_id),
         {:ok, result} <- MyApp.Accounts.send_welcome_if_needed(user) do
      {:ok, result}
    else
      {:error, :not_found} -> {:cancel, "user #{user_id} not found"}
      {:error, reason} -> {:error, reason}
    end
  end
end
```


## Enqueuing Jobs

```elixir
# 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:**
```elixir
MyApp.Workers.SendWelcomeEmail.new(%{user_id: user.id}) |> Oban.insert!()
```

### Enqueuing from Contexts

✅ **Good — context handles the job:**
```elixir
defmodule MyApp.Accounts do
  def register_user(attrs) do
    with {:ok, user} <- create_user(attrs) do
      MyApp.Workers.SendWelcomeEmail.new(%{user_id: user.id})
      |> Oban.insert()

      {:ok, user}
    end
  end
end
```

❌ **Bad — LiveView enqueues directly:**
```elixir

From igmarin/elixir-phoenix-skills, MIT.

More from igmarin/elixir-phoenix-skills