Upgrading to v1.6

This release brings powerful workflow enhancements, overhauled queue partitioning, improved dynamic plugins, and various optimizations and usability improvements.

Before Upgrading

Note: This guidance applies to v1.6 only. If you're upgrading directly to v1.7, none of the migrations does not have these concerns.

The v1.6 migration adds generated columns and indexes for improved partitioning and workflows. This may cause table locking if your oban_jobs table contains millions of records. This is particularly impactful for systems with long retention policies.

After upgrading, partition keys will be repaired automatically. If you prefer to pre-generate them before upgrading, run Pro v1.5.4+ until all jobs have been processed.

To minimize disruption on large tables:

  1. Consider reducing your table size by pruning old jobs before migration
  2. Schedule the migration during low-traffic periods
  3. Split the migration into manual steps with concurrent index creation

Bump Your Deps

Update Oban and Pro to the latest versions:

{:oban_pro, "~> 1.6.0", repo: "oban"},

Run Oban.Pro.Migration

Generate a new migration:

$ mix ecto.gen.migration upgrade_oban_pro_to_1_6

Within the generated migration module:

use Ecto.Migration

def up, do: Oban.Pro.Migration.up(version: "1.6.0")

def down, do: Oban.Pro.Migration.down(version: "1.6.0")

Alternatively, for large tables, split the schemas and indexes migrations:

$ mix ecto.gen.migration upgrade_oban_pro_schemas_to_1_6
$ mix ecto.gen.migration upgrade_oban_pro_indexes_to_1_6

defmodule MyApp.Repo.Migrations.UpgradeObanProSchemasTo16 do
  use Ecto.Migration

  def up, do: Oban.Pro.Migration.up(version: "1.6.0", only: :schemas)
  def down, do: Oban.Pro.Migration.down(version: "1.6.0", only: :schemas)
end

defmodule MyApp.Repo.Migrations.UpgradeObanProIndexesTo16 do
  use Ecto.Migration

  # Not needed with use advisory locks, i.e. `migration_lock: :pg_advisory_lock`
  @disable_migration_lock true
  @disable_ddl_transaction true

  def up, do: Oban.Pro.Migration.up(version: "1.6.0", only: :indexes)
  def down, do: Oban.Pro.Migration.down(version: "1.6.0", only: :indexes)
end

See the Oban.Pro.Migration module docs for additional options.

Configure DynamicQueues Persistence (Optional)

DynamicQueues now preserves runtime changes across application restarts. You can also configure automatic queue deletion with the sync_mode option.

# Automatically delete queues missing from configuration
config :my_app, Oban,
  plugins: [{DynamicQueues, sync_mode: :automatic, queues: [...]}]

Configure Safe Hash for Uniqueness (Optional)

Enable "safe" hashing to avoid key collisions with seemingly unique values:

config :oban_pro, Oban.Pro.Utils, safe_hash: true

The resulting hash will apply to uniq_key, chain_key, and partition_key values stored in job meta. The generated values will not match the previous values for configurations that use sub-fields in args.