# 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: ```python 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: ```python 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: ```python @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](chunk.md): ```python # 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: ```python @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](workflow.md). Workflows hold jobs in the same `suspended` state, which would make ordering unpredictable.