# Add Oban Background Jobs to a Phoenix LiveView App

Yes. An agent adds Oban with its migration and config, moves a hand-rolled GenServer cleanup onto a cron worker, runs mix test in its sandbox, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-background-jobs/phoenix-liveview/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how the app already does background work. In a LiveView app like fly-apps/live_beats, `mix.exs` depends on `phoenix` 1.7, `ecto_sql` 3.11, `postgrex`, `flame` and `bumblebee`, with no job library, and its `test` alias runs `ecto.create` and `ecto.migrate` before the suite. `lib/live_beats/application.ex` starts the children with a `!parent &&` guard so FLAME runners skip the endpoint, presence and one more child: `{LiveBeats.SongsCleaner, interval: {3600 * 6, :second}}`. That module in `lib/live_beats/songs_cleaner.ex` is a GenServer that reads `FLY_REGION` and `PRIMARY_REGION`, returns `:ignore` outside the primary region, and otherwise calls `Process.send_after` every thirty minutes to run `MediaLibrary.expire_songs_older_than/2`, which `lib/live_beats/media_library.ex` implements as an `Ecto.Multi` that deletes old songs, decrements each user's `songs_count` and removes the files. `test/live_beats/media_library_test.exs` covers that function; nothing covers the polling or the region check.

It installs Oban the way its documentation lays out. `{:oban, "~> 2.24"}` goes into `mix.exs`, `mix ecto.gen.migration add_oban_jobs_table` produces a migration whose `up` calls `Oban.Migration.up(version: 14)` and whose `down` rolls back to version 1, `config/config.exs` gains `config :live_beats, Oban` with `engine: Oban.Engines.Basic`, `repo: LiveBeats.Repo`, a `maintenance` queue of concurrency one, the Cron plugin, and the lifeline and pruner options, and `config/test.exs` sets `testing: :manual` so the suite never runs a queue. The supervisor child `{Oban, Application.fetch_env!(:live_beats, Oban)}` is added behind the same `!parent &&` guard as the cleaner it replaces, since a FLAME runner should execute transcription, not jobs.

The cleanup becomes a worker. `lib/live_beats/workers/expire_songs.ex` uses `Oban.Worker` with `queue: :maintenance`, `max_attempts: 3` and a uniqueness window, and its `perform/1` calls `MediaLibrary.expire_songs_older_than(3600 * 6, :second)`, the exact interval the application passed before. The Cron plugin's crontab runs it every thirty minutes, matching the old poll, and because Oban elects one leader across connected nodes, the `FLY_REGION` check is no longer needed: `songs_cleaner.ex` is deleted and the description says why. Any other side effect the issue names, such as sending a song's transcript off the request path, follows the same shape: a worker module, an `Oban.insert` call where the GenServer or `Task` used to be.

Before opening anything it runs the suite. The sandbox installs Elixir and OTP matching the `Dockerfile`'s builder image, starts a local PostgreSQL with the `postgres` credentials `config/test.exs` expects, runs `mix deps.get`, `mix compile --warnings-as-errors` and `mix test`, and adds `test/live_beats/workers/expire_songs_test.exs`, which uses `Oban.Testing` to `perform_job` the worker against a song older than the window and assert it is gone and the user's count is down. The output goes into the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add Oban background jobs to this Phoenix LiveView app and move the existing song expiry onto it. Read mix.exs, mix.lock, lib/live_beats/application.ex, lib/live_beats/songs_cleaner.ex, lib/live_beats/media_library.ex, config/config.exs, config/test.exs, config/runtime.exs, lib/live_beats/release.ex, the migrations under priv/repo/migrations and test/live_beats/media_library_test.exs first. Add the oban dependency, generate the jobs table migration with Oban.Migration, configure Oban with the Basic engine, the app's Repo, a maintenance queue, the Cron plugin and the lifeline and pruner options, set testing to manual in the test config, and start Oban in the supervision tree under the same guard the current cleaner uses so FLAME runners skip it. Write an ExpireSongs worker that calls MediaLibrary.expire_songs_older_than with the interval the application passes today, schedule it with the Cron plugin at the cleaner's current cadence, delete the GenServer, and explain in the description why the region check is no longer needed. In your sandbox install Elixir and OTP matching the Dockerfile, start PostgreSQL with the test credentials, run mix deps.get, mix compile --warnings-as-errors and mix test, add a worker test with Oban.Testing, and open a pull request that lists the files changed and the command output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request touching `mix.exs`, `mix.lock`, `config/config.exs`, `config/test.exs`, `lib/live_beats/application.ex`, a new migration under `priv/repo/migrations`, a new `lib/live_beats/workers/expire_songs.ex`, a new worker test, and the deletion of `lib/live_beats/songs_cleaner.ex`. The description maps the old GenServer's thirty-minute poll and six-hour window onto the crontab entry and the worker argument, and explains that Oban's leader election replaces the primary-region check.

The run's record holds the `mix compile --warnings-as-errors` and `mix test` output from the sandbox, including the new worker test, and every file the agent read before deciding to keep `expire_songs_older_than/2` untouched and wrap it.

Before merging, a reviewer checks that the release command in `fly.toml`, which runs `LiveBeats.Release.migrate/0`, will apply the new migration on deploy, and decides whether the Oban dashboard or a Telemetry handler should report failed jobs, which the pull request mentions but does not add.

## Run it on every Linear issue labelled backend

A team that tracks server work in Linear starts one run per issue from an automation with a `linear` trigger on the `backend` label, in the Project that holds the Phoenix repository. The trigger adds the issue after this prompt and fills in no placeholder, so an issue that asks to move transcription, email, or an upload post-processing step onto a queue is what the agent reads, and it reuses the Oban setup once it is merged rather than adding it twice.

Each run clones the app into its own sandbox, starts its own PostgreSQL, and opens its own pull request linking the issue. An automation run has its own `max_runs_per_hour` cap, and a second labelled issue gets a second sandbox.

## Why run it on Rush?

Replacing a GenServer with a job queue is easy to get subtly wrong: a worker that runs on every node, a cron entry that drifts from the old interval, a test config that leaves a queue running under the SQL sandbox. The agent reads the supervisor, the cleaner and the test setup together, keeps the existing domain function as the thing the worker calls, and runs the full suite against a real PostgreSQL in its sandbox, so the pull request arrives green with the equivalence spelled out.

The sandbox installs the Elixir and OTP versions the `Dockerfile` builds with and a database with the test credentials, which is the environment the repository's own `mix test` alias assumes and most laptops only approximate. The same request runs against every Phoenix app an organisation maintains, each in its own sandbox, and each pull request keeps the full command record for the reviewer.

## Frequently asked questions

### Why Oban rather than keeping the GenServer?

The GenServer runs on every node unless an environment check stops it, retries nothing, and leaves no record of a run. Oban stores each job in PostgreSQL, elects one node to run the cron, retries failures up to `max_attempts`, and prunes finished jobs, which is what the issue asks for and what the next background task will need too.

### What about FLAME runners?

The application already skips the endpoint, presence and the cleaner on a runner with a `!parent &&` guard. Oban goes behind the same guard, so a runner started to transcribe audio never processes the maintenance queue.

### Why is the region check gone?

The GenServer returned `:ignore` outside the primary region so the cleanup ran once per cluster. Oban's peers elect a single leader to run cron, so the same guarantee comes from the library, and `FLY_REGION` is no longer read.

### Do the existing tests change?

No. `expire_songs_older_than/2` and its tests in `media_library_test.exs` stay as they are. With `testing: :manual` in the test config no queue runs, and the new worker test calls `perform_job` directly through `Oban.Testing`.

### Does the migration run on deploy?

The release command in `fly.toml` runs `LiveBeats.Release.migrate/0`, which applies every pending migration, so the jobs table is created before the new release starts Oban. The reviewer checks that step before merging.

## More Phoenix LiveView jobs

- [Add a Dark Mode Toggle to a Phoenix LiveView App](https://getrush.ai/run/add-dark-mode/phoenix-liveview/)
- [Set Up GitHub Actions CI for a Phoenix LiveView App](https://getrush.ai/run/add-github-actions-ci/phoenix-liveview/)
- [Add Health Checks to a Phoenix LiveView App](https://getrush.ai/run/add-health-checks/phoenix-liveview/)

## The same job on other stacks

- [Add Background Jobs to a Vapor App from a Linear Issue](https://getrush.ai/run/add-background-jobs/vapor/)
- [Add Background Jobs to a Litestar App](https://getrush.ai/run/add-background-jobs/litestar/)
- [Add Background Jobs with Oban to a Phoenix App](https://getrush.ai/run/add-background-jobs/phoenix/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
