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_joboroban.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
suspendedchain job withretry_jobmakes 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
suspendedstate, which would make ordering unpredictable.