All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading