Chains#

Chains link jobs together so they run in a strict sequential order. A job in a chain won’t run until the job before it is completed, cancelled, or discarded, regardless of queue concurrency, scheduling, snoozing, or retries.

Chains are suited to jobs that synchronize internal state with outside events, where order matters. For example, applying webhooks from a payment processor to track an account’s balance.

Usage#

Declare a chain worker with the chain option:

from oban import worker


@worker(queue="webhooks", chain=True)
class WebhookWorker:
    async def process(self, job):
        account = await Account.find(job.args["account_id"])

        await account.handle_webhook_event(job.args["event"])

Chain jobs are enqueued like any other job, one at a time or in bulk:

await oban.enqueue_many([WebhookWorker.new(event) for event in events])

Each job runs once the job enqueued before it has finished. Jobs that are waiting on an earlier job are inserted in the suspended state, and the next job is released as soon as the previous one finishes.

Chain Partitioning#

By default, chains are partitioned by queue and worker, so every job for the same worker forms a single chain. That’s often stricter than necessary. Webhooks for separate accounts can run concurrently, as long as the webhooks for each account run in order. Use the by option to partition chains by specific fields instead:

@worker(queue="webhooks", chain={"by": {"args": "account_id"}})
class WebhookWorker: ...

Now there’s one chain per account, and webhooks for different accounts run concurrently. The by option takes the same form as queue and chunk partitioning:

# Chain by worker, the default
chain = {"by": "worker"}

# Chain by an args key, without considering the worker
chain = {"by": {"args": "account_id"}}

# Chain by multiple args keys
chain = {"by": {"args": ["account_id", "cohort"]}}

# Chain by worker and an args key
chain = {"by": {"worker": True, "args": "account_id"}}

# Chain by a meta key
chain = {"by": {"meta": "source_id"}}

Chains always include the queue, so jobs in different queues are never part of the same chain. Partitioning by args or meta without worker links jobs from every worker that shares the same chain options and values.

Handling Cancelled and Discarded Jobs#

The on_cancelled and on_discarded options control what happens to a chain when one of its jobs is cancelled or discarded:

  • "ignore" — keep processing the chain as if the job completed successfully. This is the default.

  • "hold" — stop processing the chain until the job is retried and completes, or is deleted.

Here’s a chain that holds when a job is cancelled or discarded:

@worker(chain={"on_cancelled": "hold", "on_discarded": "hold"})
class LedgerWorker: ...

Chain options can only be set on the worker, not on individual jobs.

Implementation Notes#

  • Snoozed and retryable jobs keep their chain waiting. The next job is only released once the job finishes for good.

  • A job that was scheduled for the future stays scheduled when it’s released, and runs at its original time.

  • Released jobs no longer take part in uniqueness checks. Otherwise a conflict with a newer job could stop the chain entirely.

  • The next job is released as soon as a job finishes executing, or is cancelled or deleted with functions such as oban.cancel_job or oban.delete_many_jobs. When a job is changed any other way, e.g. directly in the database, the lifeline releases the next job on its next run, within a minute by default.

  • Retrying a suspended chain job with retry_job makes it available immediately, out of order. Retry the job that’s holding the chain instead.

  • Chain jobs can’t be added to a workflow. Workflows hold jobs in the same suspended state, which would make ordering unpredictable.