Upgrading to v2.6

For Oban OSS users the v2.6 upgrade is a drop in replacement—there isn't anything to do! However, Web+Pro users will need to make some changes to unlock the goodness of engines.

Bump Your Deps

Update Oban, Web and Pro to the latest versions:

[
  {:oban, "~> 2.6"},
  {:oban_web, "~> 2.6", organization: "oban"},
  {:oban_pro, "~> 0.7", organization: "oban"}
  ...
]

Be sure to specify both :oban_web and :oban_pro if you use them both. There aren't any dependencies between Web and Pro now. That means you're free to use Pro for workers and only include Web for Phoenix servers, etc.

Switch to the SmartEngine

The SmartEngine uses centralized records to track and exchange state globally, enabling features such as global concurrency.

First, create a migration to add the new oban_producers table:

$ mix ecto.gen.migration add_oban_producers

Within the migration module:

use Ecto.Migration

defdelegate change, to: Oban.Pro.Migrations.Producers

If you have multiple Oban instances or use prefixes, you can specify the prefix and create multiple tables in one migration:

use Ecto.Migration

def change do
  Oban.Pro.Migrations.Producers.change()
  Oban.Pro.Migrations.Producers.change(prefix: "special")
  Oban.Pro.Migrations.Producers.change(prefix: "private")
end

Next, update your config to use the SmartEngine:

config :my_app, Oban,
  engine: Oban.Pro.Queue.SmartEngine,
  ...

If you have multiple Oban instances you need to configure each one to use the SmartEngine, otherwise they'll default to the BasicEngine.

Start Gossiping

Oban Pro no longer writes heartbeat records to oban_beats. Instead, any Oban instance that runs queues must use the Gossip plugin to broadcast status via PubSub.

To start, include the Gossip plugin in your Oban config:

config :my_app, Oban,
  plugins: [
    Oban.Plugins.Gossip
    ...

With the default configuration the plugin will broadcast every 1 second. If that is too frequent you can configure the interval:

  plugins: [
    {Oban.Plugins.Gossip, interval: :timer.seconds(5)}
    ...

Remove the Workflow Manager

Due to an improvement in how configuration is passed to workers the WorkflowManager plugin is no longer needed. You can remove it from your list of plugins:

plugins: [
  Oban.Pro.Plugins.Lifeline,
- Oban.Pro.Plugins.WorkflowManager,
  ...

Remove Extra Lifeline Options

The Lifeline plugin is simplified and doesn't accept as many configuration options. If you previously configured the record_interval or delete_interval you can remove them:

plugins: [{
  Oban.Pro.Plugins.Lifeline,
- delete_interval: :timer.minutes(10),
- record_interval: :timer.seconds(10),
  rescue_interval: :timer.minutes(5)
}]

Drop the Beats Table

Once you've rolled out the switch to producer records, the smart engine and the gossip plugin you are free to remove the oban_beats table at your discretion (preferrably in a follow up release, to prevent errors):

$ mix ecto.gen.migration drop_oban_beats

Within the generated migration module:

use Ecto.Migration

def up do
  drop_if_exists table("oban_beats")
  drop_if_exists table("oban_beats", prefix: "private") # If you have any prefixes:
end

def down do
  # No going back!
end