Oban: background jobs inside your Elixir database

The problem Oban solves for Elixir applications

Most background job systems put a broker between your application and the work: Redis, RabbitMQ, or a hosted service. That broker is a second stateful system to run, back up and reason about. Oban takes the opposite position. It stores jobs in the SQL database you already operate, and the README states the goal plainly: Oban "retains job data for historic metrics and inspection." The job row is not deleted after processing.

The consequence that matters most is transactional control. Because jobs live in the same database as your application data, you can enqueue a job alongside other database changes so that everything commits or rolls back atomically. If the surrounding transaction fails, the job never exists. With an external broker you either write a compensating delete or accept a job that runs against data that was never committed.

The audience is Elixir teams that already run PostgreSQL and would rather not add a broker to their stack. The README frames the dependency argument directly: if you are running a web app, there is a very good chance you are already on top of a SQL database, so running the queue there minimizes system dependencies and simplifies backups. If your application has no SQL database at all, the premise collapses and Oban is the wrong tool.

How Oban dispatches jobs from the oban_jobs table

Jobs are stored in a single table but executed in distinct queues. Each queue carries its own concurrency limit, and the README's stated reason is isolation: a single slow queue cannot back up faster queues. That is a scheduling guarantee, not a performance claim, and it is the design decision that shapes everything else.

Each job runs in a dedicated process. The README lists three consequences: fully concurrent execution, a clean environment between jobs, and efficient cleanup afterwards. Practically, that means a crashing job does not take its neighbours down with it, and the process boundary is what makes mid-execution cancellation possible at all.

Dispatch is push-based rather than purely polling. Insert triggers ensure jobs are dispatched on all connected nodes as soon as they are inserted into the database. Around that, queues are described as resilient: a failing query does not crash the supervision tree, and a backoff mechanism retries it later. Shutdown is handled the same way, with queue shutdown delayed so slow jobs can finish, queues paused at the start of shutdown, and anything still running after the grace period eligible for rescue.

State changes propagate across the cluster without distributed Erlang. The README says queues can be started, stopped, paused, resumed and scaled at runtime locally or across all running nodes, explicitly including environments like Heroku. That is a deliberate constraint: the database is the coordination point, so you do not need to open Erlang distribution between dynos.

Installing Oban and running a first job

The README points at Hex for the package, and the repository's own development setup is described by compose.yaml, which starts PostgreSQL 18.3 and MySQL 9.1 for local work. That file is a development convenience for the project itself, not an installation guide for your application, but it does show which databases the maintainers test against.

The README's installation section is where the application setup lives, and it defers to the official documentation on hexdocs for the latest stable release rather than reproducing the steps here. That is worth taking seriously: the README you are reading on the main branch is for unreleased code, and the note at the top says so explicitly. Follow the hexdocs installation page for the version you actually install.

What the README does establish is the shape of the setup. You add the dependency, configure an Oban instance under your application's config with a repo and a set of queues, and run the migration that creates the jobs table. The engines section then determines which database backs it: PostgreSQL, MySQL or SQLite3, each with its own engine and, per the README, differing levels of maturity and suitability for production.

The quick getting started section covers the worker side: you define a module with a `perform/1` function, which is what receives the job arguments when a job executes. Once the instance is supervised and the queues are declared, work begins flowing. What you should see is rows accumulating in the jobs table rather than disappearing, because completed jobs are retained for inspection and metrics. That retention is the single most visible difference from a broker-backed queue, and it is the first thing to confirm after setup.

Where Oban is the wrong choice

The database is the queue, and that is a real limit. Every dispatch, every state transition and every metric write is a database operation against the same instance serving your application traffic. A job system that runs at a very high rate, or one whose backlog is measured in millions of pending rows, competes with the queries your users are waiting on. The README does not present Oban as a system for that shape of workload, and the retention model makes it worse: because processed jobs are kept rather than deleted, the table grows by design.

Engine parity is the second issue, and the README is unusually direct about it. It says each engine supports the same core functionality "though they have differing levels of maturity and suitability for production." Read that as a signal. PostgreSQL is the engine the project treats as the default; if you are choosing MySQL or SQLite3, verify for yourself which features you depend on are actually supported on that engine before you commit to it.

The third boundary is licensing. The README advertises "enterprise grade features" and then separates them: Smart Engine, Pro Worker, Workflows, Batches, Dynamic Plugins and Decorator are all in Oban Pro, a licensed package. The Apache-2.0 core is a complete job queue, but global concurrency, global rate limiting, queue partitioning, insert batching, job dependencies and batch progress tracking are not in it. If your requirements list includes any of those, you are evaluating a commercial product, not the open source repository.

Oban compared with a dedicated broker like Redis-backed queues

The comparison is not about features, it is about where state lives. A Redis-backed queue keeps pending work in memory and typically deletes a job once it completes. Oban keeps jobs in a relational table and retains them after processing. The README states the trade explicitly: retaining job data is what enables historic metrics and inspection, and it is why you can leave an application running indefinitely without jobs being lost or orphaned by crashes.

That difference cuts both ways. With an in-memory broker, throughput is bounded by the broker rather than by your primary database, and the primary database never carries queue load. With Oban, you get atomic enqueue inside your existing transactions and you get a queryable history, but you accept that queue traffic and application traffic share one system.

The operational difference is smaller than it first appears. Both approaches need a running stateful service. The argument for Oban is that you already run the SQL database, so you are not adding one. If you are already running Redis for caching or pub/sub, that argument weakens considerably, and the decision comes down to whether transactional enqueue and retained history are worth more to you than keeping queue load off the primary database.

Maintenance, upgrades and what the licence covers

The repository is not archived, and the last push was on 2026-09-21. Releases are infrequent rather than constant: v2.24.0 on 2026-08-25, v2.23.0 on 2026-05-27, v2.22.1 on 2026-04-30. That cadence matters for planning. A queue library sits inside your application's supervision tree and its schema lives in your database, so upgrading is not a dependency bump you can ignore. Expect to run migrations when the jobs table changes, and expect to read CHANGELOG.md before doing it.

The README carries a warning worth repeating: the version on the main branch is for the unreleased branch, and readers should reference the official documentation on hexdocs for the latest stable release. If you are installing from Hex, you are not reading the documentation that matches your version. Check hexdocs against your installed release rather than trusting the repository README.

Licensing is Apache-2.0 for this repository, which is a permissive licence, but the boundary is what you actually need to understand. Oban Pro is a separate licensed package with its own terms, and the README lists its capabilities without describing how they are licensed or priced. Nothing here is legal advice: if your organisation has rules about which licences are acceptable, confirm which package you are depending on before you add it, because the answer changes based on whether you need Smart Engine, Batches or Workflows.

Editorial conclusion

Adopt Oban if your Elixir app already runs PostgreSQL and you want job inserts to commit inside the same transaction as the rows they belong to, plus a job table you can query later. Do not adopt it if you need queue semantics a SQL database cannot give you, or if you are on MySQL or SQLite3 and expect the same production footing the README describes for PostgreSQL. Before committing, verify three things: that your Elixir version is at least 1.15, that you can run the migration that creates the oban_jobs table in every environment, and whether the feature you actually need (global concurrency, batches, workflows) lives in the paid Oban Pro package rather than the Apache-2.0 core. The last push to the repository was on 2026-09-21.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. oban-bg/oban on GitHub
3. Project website
4. README
5. Releases