View Source Upgrading to v2.0
This information is extracted and expanded from the CHANGELOG.
This is a big release with a ton of new features and fixes, but also a few breaking changes. This guide will walk you through the upgrade process.
Bump Your Deps
Update Oban to the latest version:
defp deps do
[
{:oban, "~> 2.0.0"}
...
]
end
If you're an Oban Web+Pro user you'll also need to bump Oban.Web and add Oban.Pro:
defp deps do
[
{:oban, "~> 2.0.0"},
{:oban_web, "~> 2.0.0", organization: "oban"},
{:oban_pro, "~> 0.3.0", organization: "oban"}
...
]
end
Oban.Worker Changes
The perform/2
callback is replaced with perform/1
, where the only argument
is an Oban.Job struct. This unifies the interface for all Oban.Worker callbacks
and helps to eliminate confusion around pattern matching on arguments.
Change all worker definitions from accepting args
and a job
to only accept a
job and match on the nested args
key:
- def perform(%{"id" => id}, _job)
+ def perform(%Job{args: %{"id" => id}})
For finer control of job backoff the backoff/1
callback now expects a job
struct instead of an integer. Change any workers that expect an attempt number
to match on the full job struct:
- def backoff(attempt)
+ def backoff(%Job{attempt: attempt})
Update Your Config
The :verbose
setting was renamed to :log
to better align with values
accepted by Ecto.Repo
.
config :my_app, Oban,
- verbose: false,
+ log: false
...
Pruning is now handled by the new plugin system. Replace :prune
in your config
and pass a :max_age
value to the plugin:
config :my_app, Oban,
- prune: {:max_age, 60},
- prune_interval: 30_000,
- prune_limit: 5000,
+ plugins: [{Oban.Plugins.Pruner, max_age: 60}]
...
In test mode you can disable pruning by setting plugins
to false instead:
config :my_app, Oban,
- prune: false,
+ plugins: false
...
🌟 Oban.Pro users may opt to use the DynamicPruner instead for finer control. For example, to set per-state retention periods:
config :my_app, Oban,
plugins: [{
Oban.Pro.Plugins.DynamicPruner,
state_overrides: [
completed: {:max_age, {1, :day}},
discarded: {:max_age, {1, :month}}
]
}]
...
Pulse tracking and orphaned job rescue are removed from base Oban. This change means that you will need to manually rescue any jobs left executing state after a crash or forced shutdown.
Remove any :beats_maxage
, :rescue_after
or :rescue_interval
settings from
your config:
config :my_app, Oban,
- beats_maxage: 10,
- rescue_after: 30_000,
- rescue_interval: 5_000
...
🌟 Oban.Pro users may use the Lifeline plugin to retain automatic orphaned job rescue with lightweight heartbeat recording:
config :my_app, Oban,
plugins: [Oban.Pro.Plugins.Lifeline]
...
Update Your Tests
The new perform_job
test helper automates validating, normalizing and
perform jobs in unit tests.
To update your tests replace any calls to perform
with the new helper:
- assert :ok = MyApp.Worker.perform(%{id: 1}, %Oban.Job{})
+ assert :ok = perform_job(MyApp.Worker, %{id: 1})
The perform_job
helper will verify the worker, the arguments and any
provided options. It will then verify that your worker returns a valid result
and return the value for you to assert on.
Within integration tests replace drain_queue/3
with drain_queue/2
:
- Oban.drain_queue(:myqueue, with_safety: false)
+ Oban.drain_queue(queue: :myqueue, with_safety: false)
Update Telemetry
Telemetry event names have changed, along with some of the metadata and timing
units. The new event names are consistent and align with the now-standard
telemetry:span
conventions.
Update handlers to match on the new event names:
- def handle_event([:oban, :failure], measure, meta, _) do
+ def handle_event([:oban, :job, :exception], measure, meta, _) do
And update the attach
calls:
- :telemetry.attach("oban", [[:oban, :failure]], &handle_event/4, %{})
+ :telemetry.attach("oban", [[:oban, :job, :exception]], &handle_event/4, %{})
Finally, replace references to meta.stack
with meta.stacktrace
:
- Sentry.capture_exception(meta.error, stacktrace: meta.stack, extra: extra)
+ Sentry.capture_exception(meta.error, stacktrace: meta.stacktrace, extra: extra)
Here is a conversion chart for any other handlers you may have:
[:oban, :started] -> [:oban, :job, :start]
[:oban, :success] -> [:oban, :job, :stop]
[:oban, :failure] -> [:oban, :job, :exception]
[:oban, :trip_circuit] -> [:oban, :circuit, :trip]
[:oban, :open_circuit] -> [:oban, :circuit, :open]
Update Oban.Web (Optional)
Oban.Web is streamlined to share configuration with Oban and use the new plugin system. Remove any Oban.Web specific configuration:
- config :my_app, Oban.Web, repo: MyApp.Repo
Next, add the necessary plugins to the Oban config:
config :my_app, Oban,
plugins: [
Oban.Pro.Plugins.DynamicPruner,
Oban.Pro.Plugins.Lifeline,
Oban.Web.Plugins.Stats
],
...
Now remove ObanWeb from your application's supervision tree:
children = [
MyApp.Repo,
MyApp.Endpoint,
{Oban, oban_opts},
- {ObanWeb, oban_web_opts}
]
And delete any existing ObanWeb
migrations:
- defdelegate up, to: ObanWeb.Migrations
- defdelegate down, to: ObanWeb.Migrations
Finally, use the oban_dashboard
macro to easily mount in your router:
+ import Oban.Web.Router
scope "/" do
pipe_through :browser
- live "/oban", ObanWeb.DashboardLive, layout: {ObanWeb.LayoutView, "app.html"}
+ oban_dashboard("/oban")
end