Oban Background Jobs Reference
Quick reference for Elixir Oban patterns.
Oban Pro Detection
Before applying patterns, check for Oban Pro:
grep -E "oban_pro|oban_web" mix.exs
grep -r "use Oban.Pro.Worker" lib/
grep -r "Oban.Pro.Engines.Smart" config/
If Oban Pro detected, use Pro patterns for ALL new workers:
| Standard Oban |
Oban Pro |
use Oban.Worker |
use Oban.Pro.Worker |
def perform(%Job{}) |
def process(%Job{}) |
Oban.Testing |
Oban.Pro.Testing |
| Advisory lock engine |
Oban.Pro.Engines.Smart |
Pro features (all optional): args_schema (typed args), Workflows, Batches, Chunks,
Relay, hooks, encryption, deadlines, chaining, Smart Engine (global concurrency + rate limiting).
Pro plugins (DynamicCron, DynamicLifeline, DynamicPruner) enhance OSS equivalents — swap module, don't run both.
See references/oban-pro-basics.md for all patterns and migration guide.
Iron Laws — Never Violate These
- JOBS MUST BE IDEMPOTENT — Safe to retry. Use idempotency keys for payments
- JOBS MUST STORE IDs, NOT STRUCTS — JSON serialization.
%{user_id: 1} not %{user: %User{}}
- JOBS MUST HANDLE ALL RETURN VALUES —
:ok, {:error, _}, {:cancel, _}, {:snooze, _}
- ARGS USE STRING KEYS — Pattern match
%{"user_id" => id} not %{user_id: id}
- UNIQUE CONSTRAINTS FOR USER ACTIONS — Prevent double-click duplicates
- NEVER STORE LARGE DATA IN ARGS — Store references (IDs, paths), not content
- SMART ENGINE: NEVER USE
attempt TO LIMIT SNOOZES — Snooze rolls back attempt counter. Use meta["snoozed"] instead. Causes infinite loops
Quick Worker Template
defmodule MyApp.Workers.ExampleWorker do
use Oban.Worker,
queue: :default,
max_attempts: 5,
unique: [period: {5, :minutes}, keys: [:entity_id]]
@impl Oban.Worker
def perform(%Oban.Job{args: %{"entity_id" => id}}) do
case process(id) do
{:ok, _} -> :ok
{:error, :not_found} -> {:cancel, "Entity not found"}
{:error, :rate_limited} -> {:snooze, {5, :minutes}}
{:error, reason} -> {:error, reason}
end
end
end
Return Value Meanings
| Return |
State |
Behavior |
:ok |
completed |
Success |
{:ok, value} |
completed |
Success with value |
{:error, reason} |
retryable |
Retry with backoff |
{:cancel, reason} |
cancelled |
Stop permanently |
{:snooze, seconds} |
scheduled |
Delay and retry |
Quick Decisions
Which Queue?
- Critical operations → High concurrency (20+)
- Mailers/Webhooks (I/O) → Medium concurrency (30-50)
- CPU-intensive → Low concurrency (3-5)
- External APIs → Use
dispatch_cooldown for rate limiting
Testing Pattern
use Oban.Testing, repo: MyApp.Repo
# Assert enqueued
assert_enqueued worker: MyApp.Worker, args: %{id: 1}
# Execute and verify
assert :ok = perform_job(MyApp.Worker, %{id: 1})
Common Anti-patterns
| Wrong |
Right |
%{user_id: id} pattern match |
%{"user_id" => id} (string keys) |
%{user: %User{}} in args |
%{user_id: 1} (IDs only) |
| No idempotency for payments |
Use idempotency keys |
| Ignoring return values |
Handle all outcomes explicitly |
References
For detailed patterns, see:
references/worker-patterns.md - Worker options, backoff, timeout
references/queue-config.md - Queue design, pool sizing, cron, Smart Engine
references/testing-patterns.md - Testing, assertions, drain (OSS + Pro)
references/oban-pro-basics.md - Pro.Worker, Workflow, Batch, Chunk, Relay, plugins
1---
2name: oban
3description: Oban job processing — workers, perform/1 (OSS) and process/1 (Pro), queues,
4 cron, retries, unique jobs, idempotency, Oban Pro (Workflow, Batch, Chunk, Smart
5 Engine), Testing. Use when writing Oban workers, queue config, or debugging jobs.
6metadata:
7 source: https://skillmd.com/skills/majiayu000/oban
8---
9
10# Oban Background Jobs Reference
11
12Quick reference for Elixir Oban patterns.
13
14## Oban Pro Detection
15
16**Before applying patterns, check for Oban Pro:**
17
18```bash
19grep -E "oban_pro|oban_web" mix.exs
20grep -r "use Oban.Pro.Worker" lib/
21grep -r "Oban.Pro.Engines.Smart" config/
22```
23
24**If Oban Pro detected**, use Pro patterns for ALL new workers:
25
26| Standard Oban | Oban Pro |
27|---------------|----------|
28| `use Oban.Worker` | `use Oban.Pro.Worker` |
29| `def perform(%Job{})` | `def process(%Job{})` |
30| `Oban.Testing` | `Oban.Pro.Testing` |
31| Advisory lock engine | `Oban.Pro.Engines.Smart` |
32
33**Pro features** (all optional): `args_schema` (typed args), Workflows, Batches, Chunks,
34Relay, hooks, encryption, deadlines, chaining, Smart Engine (global concurrency + rate limiting).
35Pro plugins (DynamicCron, DynamicLifeline, DynamicPruner) **enhance** OSS equivalents — swap module, don't run both.
36See `references/oban-pro-basics.md` for all patterns and migration guide.
37
38---
39
40## Iron Laws — Never Violate These
41
421. **JOBS MUST BE IDEMPOTENT** — Safe to retry. Use idempotency keys for payments
432. **JOBS MUST STORE IDs, NOT STRUCTS** — JSON serialization. `%{user_id: 1}` not `%{user: %User{}}`
443. **JOBS MUST HANDLE ALL RETURN VALUES** — `:ok`, `{:error, _}`, `{:cancel, _}`, `{:snooze, _}`
454. **ARGS USE STRING KEYS** — Pattern match `%{"user_id" => id}` not `%{user_id: id}`
465. **UNIQUE CONSTRAINTS FOR USER ACTIONS** — Prevent double-click duplicates
476. **NEVER STORE LARGE DATA IN ARGS** — Store references (IDs, paths), not content
487. **SMART ENGINE: NEVER USE `attempt` TO LIMIT SNOOZES** — Snooze rolls back attempt counter. Use `meta["snoozed"]` instead. Causes infinite loops
49
50## Quick Worker Template
51
52```elixir
53defmodule MyApp.Workers.ExampleWorker do
54 use Oban.Worker,
55 queue: :default,
56 max_attempts: 5,
57 unique: [period: {5, :minutes}, keys: [:entity_id]]
58
59 @impl Oban.Worker
60 def perform(%Oban.Job{args: %{"entity_id" => id}}) do
61 case process(id) do
62 {:ok, _} -> :ok
63 {:error, :not_found} -> {:cancel, "Entity not found"}
64 {:error, :rate_limited} -> {:snooze, {5, :minutes}}
65 {:error, reason} -> {:error, reason}
66 end
67 end
68end
69```
70
71## Return Value Meanings
72
73| Return | State | Behavior |
74|--------|-------|----------|
75| `:ok` | `completed` | Success |
76| `{:ok, value}` | `completed` | Success with value |
77| `{:error, reason}` | `retryable` | Retry with backoff |
78| `{:cancel, reason}` | `cancelled` | Stop permanently |
79| `{:snooze, seconds}` | `scheduled` | Delay and retry |
80
81## Quick Decisions
82
83### Which Queue?
84
85- **Critical operations** → High concurrency (20+)
86- **Mailers/Webhooks (I/O)** → Medium concurrency (30-50)
87- **CPU-intensive** → Low concurrency (3-5)
88- **External APIs** → Use `dispatch_cooldown` for rate limiting
89
90### Testing Pattern
91
92```elixir
93use Oban.Testing, repo: MyApp.Repo
94
95# Assert enqueued
96assert_enqueued worker: MyApp.Worker, args: %{id: 1}
97
98# Execute and verify
99assert :ok = perform_job(MyApp.Worker, %{id: 1})
100```
101
102## Common Anti-patterns
103
104| Wrong | Right |
105|-------|-------|
106| `%{user_id: id}` pattern match | `%{"user_id" => id}` (string keys) |
107| `%{user: %User{}}` in args | `%{user_id: 1}` (IDs only) |
108| No idempotency for payments | Use idempotency keys |
109| Ignoring return values | Handle all outcomes explicitly |
110
111## References
112
113For detailed patterns, see:
114
115- `references/worker-patterns.md` - Worker options, backoff, timeout
116- `references/queue-config.md` - Queue design, pool sizing, cron, Smart Engine
117- `references/testing-patterns.md` - Testing, assertions, drain (OSS + Pro)
118- `references/oban-pro-basics.md` - Pro.Worker, Workflow, Batch, Chunk, Relay, plugins