Upgrading to v2.20

This Oban release includes an optional, but recommended migration.

Bump Your Deps

Update Oban (and optionally Pro) to the latest versions:

elixir

[
  {:oban, "~> 2.20"},
]

Run Oban.Migrations for v13 (Optional)

The v13 migration adds compound indexes for cancelled_at and discarded_at columns. This is done to improve Oban.Plugins.Pruner performance for cancelled and discarded jobs.

To get started, create a migration to create the table:

bash

$ mix ecto.gen.migration upgrade_oban_jobs_to_v13

Within the generated migration module:

elixir

use Ecto.Migration

def up, do: Oban.Migrations.up(version: 13)

def down, do: Oban.Migrations.down(version: 13)

If you have multiple Oban instances, or use an alternate prefix, you'll need to run the migration for each prefix.

Update Unique States (Optional)

Prior to v2.20, you may have specified unique states as custom lists:

elixir

use Oban.Worker, unique: [states: [:scheduled, :available, :executing]]
use Oban.Worker, unique: [states: [:available, :scheduled, :executing, :retryable]]

Now you can use predefined unique groups that are safer and more standardized. The available groups are:

:all - All job states: [:scheduled, :available, :executing, :retryable, :completed, :discarded, :cancelled]
:incomplete - Jobs that haven't finished: [:available, :scheduled, :executing, :retryable]
:scheduled - Only scheduled jobs: [:scheduled]
:successful - Jobs that can complete successfully: [:available, :scheduled, :executing, :retryable, :completed]

Migration Examples

Replace custom state lists with the appropriate group:

diff

# For jobs that should be unique while incomplete
-use Oban.Worker, unique: [states: [:scheduled, :available, :executing, :retryable]]
+use Oban.Worker, unique: [states: :incomplete]

# For jobs that should be unique across all states
-use Oban.Worker, unique: [states: [:scheduled, :available, :executing, :retryable, :completed, :discarded, :cancelled]]
+use Oban.Worker, unique: [states: :all]

# For jobs that should be unique only when scheduled
-use Oban.Worker, unique: [states: [:scheduled]]
+use Oban.Worker, unique: [states: :scheduled]

# For jobs that should be unique while they can still complete successfully
-use Oban.Worker, unique: [states: [:available, :scheduled, :executing, :retryable, :completed]]
+use Oban.Worker, unique: [states: :successful]

These groups reduce the chance of misconfiguration and make unique constraints more predictable across your application.