Migrations create and modify the database tables and indexes Oban Pro needs to function.

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

Usage

To use migrations in your application you'll need to generate an Ecto.Migration that wraps calls to Oban.Pro.Migration:

mix ecto.gen.migration add_oban_pro

Open the generated migration and delegate the up/0 and down/0 functions to Oban.Pro.Migration:

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

  def up, do: Oban.Pro.Migration.up()

  def down, do: Oban.Pro.Migration.down()
end

This will run all of the necessary migrations for your database.

Now, run the migration to create the table:

mix ecto.migrate

Concurrent Migrations

For systems with many retained jobs, you may want to create indexes concurrently to avoid blocking writes to your tables during migration. The only option allows splitting migrations into separate steps for schema changes and index creation:

mix ecto.gen.migration add_oban_pro_schemas
mix ecto.gen.migration add_oban_pro_indexes

The schemas migration will add all necessary tables and columns within a DDL transaction:

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

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

Then the indexes migration will add indexes concurrently, outside of a transaction:

defmodule MyApp.Repo.Migrations.AddObanProIndexes 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(only: :indexes)
  def down, do: Oban.Pro.Migration.down(only: :indexes)
end

When to Use Split Migrations

Use the default, combined approach when:

1. Setting up a development or test environment
2. Working with small tables where index creation is quick
3. Simplicity is preferred over non-blocking operations

Choose split migrations when:

1. Operating on a database where blocking writes could cause downtime
2. Working with large tables where index creation would block for an extended period

Upgrading

Like Oban, migrations are versioned and you may need to run the migration again when new oban_pro versions are released. To do this, generate a new migration:

mix ecto.gen.migration upgrade_oban_pro

Open the generated migration in your editor and call the up and down functions on Oban.Pro.Migration, with an optional version number:

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

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

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

Differences from Oban : .tip

Unlike Oban, the migration versions correspond directly to the oban_pro package version. In addition, running down/0 will only step back one version, not all the way down.

Isolation with Prefixes

Oban supports namespacing through PostgreSQL schemas, therefore so does Oban Pro. Specify a prefix within your migration:

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

  def up, do: Oban.Pro.Migration.up(prefix: "private")

  def down, do: Oban.Pro.Migration.down(prefix: "private")
end