oban
Use when writing, scheduling, testing or debugging Oban jobs, even for a how-to question: workers, cron, retries, unique jobs, queues, Pro Workflow/Batch. Load it before touching job code; it holds the job rules.
Install
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/oban
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 ${CLAUDE_SKILL_DIR}/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
attemptTO LIMIT SNOOZES — Snooze rolls back attempt counter. Usemeta["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_cooldownfor 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:
${CLAUDE_SKILL_DIR}/references/worker-patterns.md- Worker options, backoff, timeout${CLAUDE_SKILL_DIR}/references/queue-config.md- Queue design, pool sizing, cron, Smart Engine${CLAUDE_SKILL_DIR}/references/testing-patterns.md- Testing, assertions, drain (OSS + Pro)${CLAUDE_SKILL_DIR}/references/oban-pro-basics.md- Pro.Worker, Workflow, Batch, Chunk, Relay, plugins
Files (claude-elixir-phoenix)
-
references
-
oban-pro-basics.md 9.7 KB
Loading… -
queue-config.md 3.1 KB
Loading… -
testing-patterns.md 2.9 KB
Loading… -
worker-patterns.md 3 KB
Loading…
-
-
SKILL.md 4.1 KB
--- name: oban description: "Use when writing, scheduling, testing or debugging Oban jobs, even for a how-to question: workers, cron, retries, unique jobs, queues, Pro Workflow/Batch. Load it before touching job code; it holds the job rules." effort: medium user-invocable: false paths: - "**/workers/**/*.ex" - "**/*_worker.ex" - "**/*_worker_test.exs" - "**/*_job.ex" --- # Oban Background Jobs Reference Quick reference for Elixir Oban patterns. ## Oban Pro Detection **Before applying patterns, check for Oban Pro:** ```bash 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 `${CLAUDE_SKILL_DIR}/references/oban-pro-basics.md` for all patterns and migration guide. --- ## Iron Laws — Never Violate These 1. **JOBS MUST BE IDEMPOTENT** — Safe to retry. Use idempotency keys for payments 2. **JOBS MUST STORE IDs, NOT STRUCTS** — JSON serialization. `%{user_id: 1}` not `%{user: %User{}}` 3. **JOBS MUST HANDLE ALL RETURN VALUES** — `:ok`, `{:error, _}`, `{:cancel, _}`, `{:snooze, _}` 4. **ARGS USE STRING KEYS** — Pattern match `%{"user_id" => id}` not `%{user_id: id}` 5. **UNIQUE CONSTRAINTS FOR USER ACTIONS** — Prevent double-click duplicates 6. **NEVER STORE LARGE DATA IN ARGS** — Store references (IDs, paths), not content 7. **SMART ENGINE: NEVER USE `attempt` TO LIMIT SNOOZES** — Snooze rolls back attempt counter. Use `meta["snoozed"]` instead. Causes infinite loops ## Quick Worker Template ```elixir 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 ```elixir 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: - `${CLAUDE_SKILL_DIR}/references/worker-patterns.md` - Worker options, backoff, timeout - `${CLAUDE_SKILL_DIR}/references/queue-config.md` - Queue design, pool sizing, cron, Smart Engine - `${CLAUDE_SKILL_DIR}/references/testing-patterns.md` - Testing, assertions, drain (OSS + Pro) - `${CLAUDE_SKILL_DIR}/references/oban-pro-basics.md` - Pro.Worker, Workflow, Batch, Chunk, Relay, plugins
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.