Changelog#

This release brings chains for running jobs in strict order, batches for grouping jobs with callbacks, and concurrency that’s fully integrated with Oban Web.

See the v0.8 Upgrade Guide for complete upgrade steps and migration caveats.

Chains#

Chains link jobs together so they run in strict sequential order. A job in a chain won’t run until the job before it is in a final state, regardless of scheduling, snoozing, and retries. Declare a chain with the chain option:

from oban import worker


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

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

Here, chains are partitioned by account id, so webhooks for each account run in order while different accounts can still run concurrently.

See the chain guide for the complete set of partitioning and holding options.

Batches#

Batches link jobs together and run callbacks after jobs execute. That lets you coordinate jobs running in parallel, then react once they’ve all finished, or as soon as one of them fails.

Workers define optional batch callbacks:

from oban import worker
from oban_pro import Batch


@worker(queue="mailers")
class EmailWorker:
    async def process(self, job):
        await mailer.daily_update(job.args["email"])

    async def batch_completed(self, job):
        jobs = await Batch.for_job(job).all_jobs()

        await mailer.notify_admins([job.args["email"] for job in jobs])


batch = Batch().add([EmailWorker.new({"email": email}) for email in emails])

await oban.enqueue_many(batch)

Here admins will be notified only when the batch completed, though finer grained callbacks are also available.

See the batch guide for the full list of callbacks, hybrid batches, and appending to or cancelling a batch.

Smart Concurrency with Oban Web#

Smart concurrency now works seamlessly with Oban Web in either direction. Queues report global limits, rate limits, and partitions the way Web expects.

Queues can now combine a global limit with a rate limit, and must declare partitioning for that particular limit.

# Run 1 job at a time for each account, and at most 100 jobs per minute for the whole queue
[queues.exports]
limit = 10
global_limit = { allowed = 1, partition = { args = "account_id" } }
rate_limit = { allowed = 100, period = 60 }

Limits can be scaled at runtime from Python as well, and passing None clears one entirely:

await oban.scale_queue(queue="exports", rate_limit={"allowed": 200, "period": 60})
await oban.scale_queue(queue="exports", rate_limit=None)

v0.8.0 — 2026-11-16#

Enhancements#

  • [Chain] Add chains for running jobs in strict order

    Workers declared with the chain option link their jobs together, so each job waits until the one before it is completed, cancelled, or discarded. Chains are partitioned by queue and worker by default, or by specific args or meta keys with the by option, and the on_cancelled and on_discarded options choose whether a failed job holds the chain or lets it continue.

  • [Batch] Add batches for grouping jobs with callbacks

    Workers opt in by defining batch_attempted, batch_cancelled, batch_completed, batch_discarded, batch_exhausted, or batch_retryable, and each callback runs once per batch as an isolated job.

    The schema gains oban_jobs_batch_index and oban_jobs_chain_index, which match the indexes from Oban Pro for Elixir, so reinstalling the schema is required.

  • [Core] Release chains, batches, and workflows after cancelling or deleting jobs

    Cancelling or deleting jobs through Oban now immediately releases the next job in a chain, inserts ready batch callbacks, and cascades through workflows, rather than waiting for the lifeline.

  • [Producer] Nest partitions inside global and rate limits

    Partitioning now lives inside global_limit or rate_limit, rather than as a top-level queue option, e.g. global_limit = { allowed = 1, partition = "worker" }. Queues may combine global and rate limits as long as only one is partitioned. A top-level partition is rejected as an unknown option.

  • [Producer] Report limits in queue checks

    Checks now include global limits, rate limits, and partitions in the shape Oban Web reads, so Web shows them for Python queues.

  • [Producer] Accept scaling from Web and Elixir

    Scale signals sent from Oban Web or Elixir nodes are accepted, along with period strings like "1 minute", and scaling a limit to None clears it rather than being ignored.

  • [CLI] Move multi-process execution to Oban

    Multi-process execution is now part of Oban and enabled with oban start --processes. The obanpro start command remains for compatibility, still defaults to one process per CPU core, and accepts the new OBAN_PROCESSES, OBAN_SETUP, and OBAN_TEARDOWN environment variables as well as the previous OBAN_PRO_* names.

  • [Unique] Use unique options from Oban

    Unique options and validation now live in Oban, with constraint-backed uniqueness built on top of them. Validation is stricter: unknown options are rejected, and keys require args or meta in the fields. Periods also accept strings like "7 days".

  • [Notifier] Support ERL_EPMD_PORT in the Erlang notifier

    The notifier honors ERL_EPMD_PORT for discovery and port lookups, matching how Erlang itself finds an EPMD running on a non-default port.

  • [Notifier] Accept any Erlang encodable term in payloads

    The Erlang notifier uses the term codec that’s shared with Oban, so signal and workflow payloads may contain any value that’s encodable as an Erlang term.

  • [Core] Replace source encryption with signed licenses

    Pro ships as pure-Python source with a signed license that’s verified offline, without any network access. Wheels no longer depend on the platform, stack traces show real source, and there’s no native binary to fail on import.

    An invalid or expired license is reported when an Oban instance is built. After a subscription renews, reinstall the package to pick up the renewed license. obanpro license now shows the license id and customer along with the expiration.

  • [Telemetry] Standardize telemetry counts as count

    Pruner and lifeline telemetry now report count instead of pruned_count, rescued_count, and repaired_count, matching Oban’s own events. The pruner still reports archived_count.

  • [Testing] Speed up resetting between tests

    reset_oban clears tables with DELETE rather than TRUNCATE, which is an order of magnitude faster for the near-empty tables used in tests. The job id sequence is still restarted.

Bug Fixes#

  • [Producer] Align sliding windows to the current period

    Rate windows weren’t aligned to the period, so nodes didn’t share boundaries, and dropping the previous window allowed up to twice the limit across a boundary. Windows now align to the period, every producer’s windows roll forward before merging, and the previous window’s share rounds up.

  • [Producer] Count every key against unpartitioned limits

    Jobs tracked by a partition key in a queue that’s no longer partitioned didn’t count toward the global limit, so the queue could exceed it.

  • [Producer] Skip rate windows from other algorithms

    Elixir rate limits may use fixed windows or token buckets, whose windows have a different shape. Producers now record that they use a sliding window and ignore windows from other algorithms, rather than miscounting them.

  • [Producer] Keep queues resumed after tracking limits

    Tracking demand replaced the stored producer meta with a stale paused flag, so resuming a queue that started paused was undone on its next fetch.

  • [Producer] Free global limit slots while paused

    Paused producers stopped tracking global limit slots, holding capacity for jobs that had already finished. Tracking now refreshes from the running jobs without fetching.

  • [Workflow] Release workflow jobs immediately

    Retrying workflow jobs now releases any whose dependencies already completed, rather than leaving them suspended until the lifeline repairs the workflow. Cancelling workflow jobs immediately cancels their held dependents, including those in parent workflows.

  • [Workflow] Fix sub-workflow jobs inheriting sibling deps

    Jobs without deps in a sub-workflow added via add_workflow inherited the deps of an earlier sibling job instead of the parent’s deps, whenever a job with its own deps preceded them.

  • [Workflow] Fix context, job, and recorded value lookups

    Context jobs stay completed when nested via add_workflow, rather than inheriting the parent’s deps and becoming suspended.

    Fetching jobs with all_jobs(deps_of=job) and fetching recorded values now match each dependency exactly, including whole sub-workflow and grafted dependencies. A sub-workflow dep no longer pulls in unrelated values from the parent workflow, a job without deps receives no recorded values, and values within a sub-workflow are keyed by job name rather than nested under the sub-workflow.

    Grafting now rewrites named deps inside grafted sub-workflows so they resolve rather than being cancelled, and add_graft rejects names that conflict with existing jobs, sub-workflows, or grafts.

  • [Workflow] Fix workflow graph edges and rendering

    Graphs now draw sub-workflows nested within their parent sub-workflow, include the edge from an add_workflow dependency into the sub-workflow, and draw grafts as their grafter job so dependents point at it. DOT and Mermaid output use generated node ids with escaped labels, so edges within sub-workflows connect to their nodes.

  • [Relay] Fix relay notifications arriving before job acks

    Relay waiters are now notified after a job’s ack commits, and relays listen for notifications before enqueueing. Jobs acked as part of a chunk also notify their relay waiters.

  • [Signal] Wait for the signal channel before awaiting

    Awaiting a signal now waits until the signal channel is live, so a signal sent just after the wait begins is no longer missed.

  • [Notifier] Discover every node behind a multi-address host

    The Erlang notifier reached only one machine when a host resolved to several, such as a Kubernetes headless service or a scaled Docker Compose service. Now each host resolves to all of its IPv4 addresses, the notifier asks EPMD on every one, and it dials the nodes it finds by address.

  • [Notifier] Bind the Erlang notifier’s listener on start

    The notifier binds its port when it starts instead of when it’s built, so a notifier that’s never started no longer holds a port, and a stopped notifier can be started again.