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
chainoption 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 thebyoption, and theon_cancelledandon_discardedoptions 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, orbatch_retryable, and each callback runs once per batch as an isolated job.The schema gains
oban_jobs_batch_indexandoban_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_limitorrate_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-levelpartitionis 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 toNoneclears 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. Theobanpro startcommand remains for compatibility, still defaults to one process per CPU core, and accepts the newOBAN_PROCESSES,OBAN_SETUP, andOBAN_TEARDOWNenvironment variables as well as the previousOBAN_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
keysrequireargsormetain the fields. Periods also accept strings like"7 days".[Notifier] Support
ERL_EPMD_PORTin the Erlang notifierThe notifier honors
ERL_EPMD_PORTfor 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 licensenow shows the license id and customer along with the expiration.[Telemetry] Standardize telemetry counts as
countPruner and lifeline telemetry now report
countinstead ofpruned_count,rescued_count, andrepaired_count, matching Oban’s own events. The pruner still reportsarchived_count.[Testing] Speed up resetting between tests
reset_obanclears tables withDELETErather thanTRUNCATE, 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_workflowinherited 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_graftrejects 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_workflowdependency 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.