[Queues] Allow dispatch_cooldown in queue options
Oban itself accepts dispatch_cooldown as a per-queue option, but the Queues service rejected it because the persisted queue schema didn't recognize the field. Now the option is validated, persisted, and passed through to the queue's producer when it starts.
[Smart] Exclude dupe unique jobs from workflow counts
Workflow counters were incremented from all member changesets before unique de-dup ran, so a member that deduped was counted but never inserted. The drift left workflows permanently stuck with phantom suspended or available counts Now workflows are upserted after dupe detection and deduplicated members are excluded from the counts.
[Cron] Include the Oban Pro compiler in the release package
The compiler task was omitted from the package, causing projects configured with the :oban_pro
compiler to fail with a missing task error.
[Backfill] Add a module for for cursor-based dataset backfills
Backfill walks a dataset with recursive jobs, advancing a keyset cursor one window per job. Each iteration is a single Oban job that processes a batch and schedules its successor, so a backfill makes steady progress without holding a long transaction or running a long-lived process.
The cursor walks any unique, ordered column—integer or UUID alike—so the same backfill works across key types. Configure the key, batch limit, and order; throttle to pace the chain; bound each window with a timeout; or dry run to confirm a backfill terminates without persisting any writes.
Cursor helpers translate a query into the cursor's advance protocol: update_all/delete_all for in-place writes, and each/fetch for per-row or batched work such as external API and inference calls.
Trigger a backfill from a migration or console with start/2, and stop one with cancel/2. A dedicated index on backfill_id keeps lookups fast.
[Chunk] Store only customized options in chunk job meta
Chunk workers previously persisted the full set of chunk options to every job's meta, including defaults like size, sleep, timeout, and leading. Now only options explicitly set on the worker are stored, and defaults are merged in at processing time. This shrinks the meta written for each chunk job while preserving identical runtime behavior.
[Cron] Schedule jobs inline on workers and decorated functions
Add a :cron option to Oban.Pro.Worker and Oban.Pro.Decorator. The bare form accepts a cron
expression, while the keyword form supports :expression, :timezone, :name, :guaranteed,
and :paused. An :oban option scopes annotations to a particular Oban instance.
A Mix compiler records annotated workers and decorators in a per-app manifest that
Oban.Pro.Cron loads at startup. Discovery no longer depends on which modules happen to be
loaded, fixing missing entries in environments with lazy code loading.
Using cron: without adding :oban_pro to the project's compilers emits a compile-time
warning.
[Diagnostics] Include executing pid in diagnostics reply
The diagnostics reply now carries executing job's pid alongside the existing process info.
[Engine] Add per_node option to scale global partitioned limits
Global limits are normally a fixed ceiling across all nodes. The new per_node: true modifier
treats allowed as a per-node value that scales with the number of nodes running a queue.
It's intended for partitioned queues, where each partition stays bounded while the cluster's
throughput grows with capacity. Without a partition it's equivalent to a local_limit of the
same value.
[Lifeline] Add selective matching to retry_exhausted
The retry_exhausted option now accepts a simple match spec in addition to a boolean, so
exhausted jobs can be retried for specific workers or queues. Pass workers and/or queues and any
exhausted job that doesn't match is still discarded:
plugins: [
{DynamicLifeline, retry_exhausted: [workers: [MyWorker], queues: [:safe]]}
]
Passing true or false behaves as before, retrying or discarding every exhausted job.
[Migration] Optimize chain and chunk indexes for large tables
Replace existing chain and chunk indexes with definitions tailored to their lookup patterns. Chain lookups avoid scanning completed jobs, while chunk fetching uses index order for priority and scheduling, keeping both operations fast as job tables grow.
[Pro] Promote dynamic plugins to top-level services
Oban v2.24 introduced dedicated cron, lifeline, pruner, and queue configuration keys, so
the corresponding Pro modules no longer belong under :plugins and no longer need the Dynamic
prefix to distinguish them:
Oban.Pro.Plugins.DynamicCron → Oban.Pro.CronOban.Pro.Plugins.DynamicLifeline → Oban.Pro.LifelineOban.Pro.Plugins.DynamicPruner → Oban.Pro.PrunerOban.Pro.Plugins.DynamicQueues → Oban.Pro.QueuesThe old modules remain as shims so existing configuration and function calls keep working, with
@deprecated annotations pointing at the new names. Nothing needs to change immediately, but
the shims will be removed in a future major version.
[Migration] Drop indexes renamed by the v1.7 migration
The v1.7 migration renamed the indexes it replaced with an _old suffix to retain the
originals. Those aren't needed now, and v1.8 drops the remaining indexes to reclaim space and
database cycles.
[Pruner] Use persisted and runtime-updatable rules
Replace implicitly ordered queue, state, and worker overrides with database-backed pruning rules. Rules support compound matches, explicit first-match precedence, per-rule retention limits, pausing, and runtime management without restarting Oban.
Existing mode and override configuration is translated automatically for backward compatibility.
[Pruner] Add declarative job archiving
Rules can now set archive: true to preserve matched jobs instead of deleting them. Archived
jobs are copied to a dedicated oban_jobs_archive table before they're removed from
oban_jobs, retaining the job's full record (args, meta, errors, timestamps) for long-term
storage and later inspection.
The copy runs in the same transaction as the delete, so a job is never lost between the two tables, and rows are moved with a single set-based insert without round-tripping through the application.
The oban_jobs_archive table mirrors oban_jobs and is created by the standard v1.8.0
migration. Read archived jobs back through the new Oban.Pro.Archive queryable, which loads
rows as ordinary Oban.Job structs:
Repo.all(Oban.Pro.Archive)
[worker: MyApp.AuditWorker, state: "completed"]
|> Oban.Pro.Archive.query()
|> Oban.all_jobs()
Prune telemetry now includes an archived_count measurement alongside pruned_count.
[Worker] Add global overrides for pro worker defaults
Oban bakes in system-wide defaults for options like max_attempts (20), which previously could
only be changed by setting the option on every worker. Pro workers can now override the defaults
for max_attempts, priority, and queue across an entire application:
config :oban_pro, worker_defaults: [max_attempts: 5, priority: 1]
Defaults apply to any Pro worker that doesn't set the option itself, so values from use or
passed to new/2 always take precedence. The config is read at compile time and validated
against the allowed subset, so unknown or invalid options raise with a clear error.
[Worker] Add fetch_recorded/2 to enhance fetching from external storage
Define Worker.fetch_recorded/2 that is capable of fetching externally stored recordings
without the worker module loaded, as well as optionally bypoassing decode. Recorded data also
includes a size attribute as an external hint, so Web can alert users about the overal size
before downloading and displaying large recordings.
[Worker] Support encrypted key rotation and authentication
Encrypted workers accept a :keyring module in place of a static :key. Each job records which
key encrypted it, so keys can rotate without stranding jobs inserted beforehand. Define a
keyring module, and configure it for a worker:
use Oban.Pro.Worker, encrypted: [keyring: MyApp.Keyring]
New jobs use aes_256_gcm rather than aes_256_ctr, authenticating args so tampering fails the
job instead of decrypting to garbage. Existing jobs are still read with aes_256_ctr.
[Worker] Add on_retried/2 worker hook for retried jobs
Retrying a job marks it as available for future execution but doesn't run the worker immediately, so there was no execution hook that fired at the moment an operator retried a job.
Add on_retried/2 to complete the set of external state hooks. It's called with the :manual
reason after a job's state is reset. As with the other external hooks, the callback runs against
the fully loaded job (decryption and structuring applied) and exceptions are caught and logged
without affecting the retry.
[Worker] Use a units syntax for recorded size limits
Add units syntax, {32, :mb}, with support for kb, mb, and gb units to simplify defining
storage size limits.
[Worker] Add pluggable storage for recorded job output
Recorded output can now be written to and read from external object stores (S3, R2, Tigris,
etc.) through the new Oban.Pro.Storage behaviour, rather than only living inline on a job.
Setting global worker defaults has moved to :oban_pro, Oban.Pro.Worker for consistency with
other compile-time options, and setting a global recorded option is now also possible.
config :oban_pro, Oban.Pro.Worker, recorded: [storage: MyApp.S3, limit: 32_000_000]
[Workflow] Add saga-style workflow compensations
Steps declare compensation through an automatically detected compensate/1 worker callback or
an explicit function capture. Declarations are serialized into job meta when the workflow is
built, keeping behavior stable across deploys.
When a workflow terminates according to its compensate_on policy, Pro materializes a linked
compensation workflow with completed steps arranged in reverse dependency order. Cascade
compensations receive reconstructed context and recorded ancestry.
Workflow rescue repairs drifted counters and re-evaluates unresolved candidates so a crash can't strand pending compensation.
[Workflow] Expose compensations in workflow status
Rework status/1 to read from the workflow table rather than raw jobs, and add a new
compensation field with linked workflow details.
Reading from the table is significantly faster, counts include the suspended state, durations
are only reported once a workflow finishes, and unnamed workflows fall back to a single worker
name.
[Engine] Rename the Smart engine to Oban.Pro.Engine
The engine is now Oban.Pro.Engine to match the flatter module names introduced for Pro's
services. Update the :engine option in your config:
config :my_app, Oban,
- engine: Oban.Pro.Engines.Smart
+ engine: Oban.Pro.Engine
Oban.Pro.Engines.Smart still works and delegates all callbacks to the new module, so there's
no rush to change it and no deprecation warnings.
[Worker] Drop the obsolete recorded to option
The option was never promoted into recorded meta or used at fetch time for bulk operations. This silently drops the option to prevent failing validation for any projects that may have set it.
[Testing] Await hook execution to prevent leaking side-effects
Hooks triggered by cancellation, exhaustion, and workflow operations were executed in fire-and-forget tasks. During testing this allowed hooks to finish after a test had already concluded, producing racy results when draining jobs.
When draining, the task is awaited so all side-effects complete before the drain returns. Outside of draining it remains fire-and-forget and isolated from the caller.
[Worker] Warn about risky unique states in Pro workers
Pro workers validated the shape of :unique options but skipped the advisory check that
Oban.Worker performs, so state lists that can't detect duplicates or omit in-flight states
compiled silently.
[Worker] Await async hook side-effects during testing
Bulk worker hooks (on_retried, on_cancelled, on_discarded) and other deferred side-effects
ran in a detached task that borrowed the test's sandbox connection. When a test process exited
while that task was still querying, the connection was reclaimed mid-query, leaking a Postgrex
"owner exited" error even though no assertions failed.
Utils.async_maybe_await now awaits whenever testing is enabled, not only during draining, so
these side-effects complete before a test concludes.
[Worker] Unify shared result type in the stage module
The c:after_process/3 callback stated it only returned :ok, which was incorrect. Now there's
a properly defined t:result/0 that is shared between *process callbacks.
[Workflow] Return nil for missing recordings in workflows
External recorded output outlives its job and may expire or be reaped from the store while the
job row remains. In that case all_recorded/3 and get_recorded/2 now return nil for the
absent entry, matching their documented contract, rather than leaking an {:error, :missing}
tuple. A genuinely unreachable store still returns {:error, reason} so an outage isn't
silently mistaken for absent output.
Cascades continue to treat missing dependency output as an error and retry, since a just-completed step's output should still be present.
[Smart] Check uniqueness before job insertion
Unique jobs are now verified when they're inserted, safely across processes and nodes, rather than relying exclusively on the unique index to reject conflicts. The index remains in place as a backstop, and this version also tolerates non-unique index variants that are better suited to some databases.
Conflicting inserts return the existing job with conflict? set to true, rather than
annotating the conflicted job's meta with uniq_conflict.
[Pro] Support upcoming Oban v2.24 changes
Oban v2.24 has config changes and internal module adjustments that Pro relied on. This change makes it possible to use Pro v1.7 with v2.24 rather than forcing an upgrade to Pro v1.8
[Chunk] Use latest completion time to trigger chunks
A leading chunk decides whether to run immediately based on how long it's been since the last job in the chunk finished. It now derives that from the maximum completion time across the chunk, which uses the chunk index for a substantial speedup.
This always reflects the true last completion even when a retried job finishes out of id order.
[DynamicLifeline] Ensure configured queue included for chunk_id
The configured queue wouldn't always be used when computing the chunk_id value and it would
fall back to "default". Passing a queue through manually and repairing chunks always used the
correct queue in the calculation, which led to differing chunks for jobs that should be related.
[DynamicPruner] Optimize workflow preservation during pruning
Split active workflow checks into targeted queries that properly use existing workflow indexes and avoid pruning timeouts.
[Migration] Reapply SQL functions on every migration run
Functions were created in schema migrations, so they only ran for new versions. That meant function fixes never reached an already recorded version, subtly breaking functionality.
Trigger and helper functions are now recreated on any migration run, regardless of whether that version ran before. In particular, this restores the workflow trigger lock ordering and UTC timestamps for anyone who migrated to 1.7.0 before those fixes shipped.
[Smart] Guarantee chains release exactly one held job
Under some query plans, a single flush released every held member of a chain at once, silently breaking serialization for chains used to enforce one active job at a time.
[Worker] Safely cast wait_for infinity in signals
A persisted wait_for: :infinity wasn't correctly cast back to an atom across retries.
[Smart] Prepare acking query to avoid replanning
Acking ran as an unnamed statement, so it was planned on every call. Adding a name lets Postgres cache the plan per connection, which cuts overall ack time 1.3-2.5x for typical small batches.
[Smart] Support advisory unique indexes for insert-only
Detect when the oban_jobs_unique_index exists on a uniq_key column without a UNIQUE
declaration and switch to an advisory mode. In this mode, dupes are detected with indexed
lookups before insertion, rather than relying on the index to enforce uniqueness through
conflicts.
This primarily benefits CockroachDB, where mid-statement unique validation causes transient constraint errors during bulk transitions.
[Smart] Guard against double execution from replayed acks
Acks replayed after an ambiguous commit (committed server-side, but the client saw a connection
error) could rewind a refetched job to the scheduled state and trigger a concurrent execution.
Acks now only apply to the execution that produced them, and stale acks are dropped rather than replaying until they stick. This situation required precise timing around connection failures that are unlikely, but possible under load.
[Chain] Repeat suspended check during chains repair
Prevents potential double execution of repaired chains by re-using the suspended check
internally to avoid stale subquery snapshot.
[RateLimit] Isolate rate windows by algorithm during rollouts
When a queue switched algorithms and the producers were briefly mixed, a producer could read a window written by a different algorithm and crash.
Producers now only merge windows written with the same algorithm, so a mixed rollout stays consistent and clears itself once the switch completes.
[RateLimit] Refill idle token buckets in the rate limiter
The token_bucket algorithm stopped refilling once a bucket hit its limit and the queue went idle, leaving the queue wedged with zero demand until restarted. Idle buckets now refill on their own after a burst.
[RateLimit] Respect partitions in rate limit consumption
Oban.Pro.RateLimit.consume/3 computed each producer's capacity from global demand. For a
partitioned rate limit this made consume/3 disagree with available/2 Capacity is now scoped
to the requested partition's window, matching available/2 across all algorithms.
[Workflow] Wait for deeply nested sub grafts
A downstream job depending on a graft stopped waiting once the workflow containing that graft was itself grafted. At that point, the consumer cascaded as soon as the grafter finished, before the grafted jobs ran.
[Smart] Repair unique violations out-of-band
Staging now repairs the conflict out-of-band on a fresh connection and skips the current round, letting the next pass promote the freed jobs. Recovery no longer depends on the aborted transaction, so the Stager keeps making progress.
[Smart] Refresh partition configuration periodically
In a multi-node deployment, jobs could be inserted without a partition key on nodes that hadn't yet seen a queue's partition configuration. Once a queue became partitioned, those nodes kept enqueueing unpartitioned jobs until they were restarted.
Partition configuration is now refreshed periodically on every node, so newly partitioned queues are picked up everywhere within a short window without requiring a restart.
[Smart] Retry producer fetches on lock contention
Stop leaking lock_not_available exceptions that may crash the producer. Lock contention in
CRDB is now treated like a deadlock and retried after a jittery sleep, giving the same try-lock
behaviour as Postgres.
[Smart] Correct unique index check for CRDB compatibility
The unique index check didn't account for the sort order, which is always included in CRDB index definitions.
[Worker] Restore deprecated after_process/2 hook callback
The two-arity after_process/2 callback was deprecated in favor of after_process/3 long ago,
but a refactor in 1.7 silently dropped support for it.
[Worker] Trigger on_cancelled/2 for all expired deadlines
Previously on_cancelled/2 only fired for deadlines enforced mid-execution when force was
enabled. Now, jobs whose deadline elapses before execution also trigger with a :deadline
reason.
[Worker] Avoid notifier subscription for await_signal/1 when draining
Immediately park the job or timeout when draining, rather than attempting to subscribe to a notifier. Otherwise, expect a Notifier to be running and warn loudly.
[Workflow] Fix sub-workflow context jobs with parent deps
Prevent workflow context from being suspended when attaching a sub-workflow with dependencies.
[Workflow] Wait for sub-workflows grafted via add_workflow/4
A downstream job that depends on a graft failed to wait for grafted sub-workflows. The cascade ran immediately after the grafter, before any of the grafted jobs executed. Grafted jobs that aren't direct members of the graft are now tied back to the graft.
[Smart] Guard attempt changes against acking replays
Prevent replayed snooze acking from decrementing an attempt beyond the acceptable range. In
rare cases an ack transaction could commit, but have the connection drop before the response,
which would lead to the entire transaction replaying later. That could violate the
attempt_range check constraint on subsequent fetches, causing a producer crash loop.
[Smart] Utilize full limit across partitions with burst
Partitioned queues using burst mode wouldn't fill the entire local quota when there are numerous active partitions, but only of them were deep. In that situation, shallow partitions would waste the deep partitions slice, leaving available queue capacity idle.
Burst mode uses a new, optimized query that allows idle capacity to flow to partitions that have a backlog, so a skewed queue is filled to the limit as expected.
[Workflow] Fix deadlocks when staging jobs in workflows
Under high throughput, staging scheduled or retryable jobs in workflows could deadlock against other job state changes, surfacing as intermittent errors. Workflow progress is now tracked in a way that avoids the conflict, and staging automatically retries in the rare event a deadlock still occurs.
[Workflow] Prevent status/2 from hanging on nested grafts
Checking the status of a workflow that contained grafts nested inside other grafts could loop indefinitely instead of returning. Status checks now handle nested grafts correctly and return as expected.
[Worker] Park await_signal/1 immediately while draining
Calling await_signal/1 while draining jobs raised an error because there's no notifier to
deliver a live signal. Now the job parks instead, so a signal buffered before the drain resumes
it as expected.
[Worker] Use is_valid_period guard for deadline
Validate using the now-standard, and more accurate, Period guard rather than custom logic.
[DynamicLifeline] Repair multiple stalled chains per cycle
Chain repair previously continued a single stalled chain per run, so recovering multiple
stranded chains took multiple repairs. Repair now advances up to the DynamicLifeline's
repair_limit chain's head in one pass.
[DynamicLifeline] Rescue workflows that never had a job start
The workflow rescue sweep filtered on started_at < threshold, which is never true when a
workflow's upstream jobs were deduplicated by a unique conflict. Those workflows lacked
started_at data and stayed orphaned in the database.
[Batch] Fix incorrect types used in batch validation
Oban v2.23 fixed a longstanding bug in the validator logic that would silently let unknown types fall through and be ignored. This updates Batch validation to use properly defined types.
[Smart] Apply burst quota to untracked partitions
Previously, the per-partition demand for keys not yet present in tracked used the global_limit
rather than the burst quota. On the first fetch for a newly active partition, including cold
start, only allowed jobs would dispatch, even when burst capacity was free.
[Workflow] Preserve sub-workflow identity through apply_graft/2
Multiple add_many sub-workflows in a single graft could collide because they shared common
names ("0", "1", etc.) and a single workflow id. Now the sub-workflow id is retained for grafts,
eliminating the collision without changing auto-generated job names.
[Smart] Fill all burst slots under uneven partition counts
Burst mode is meant to maximize throughput by letting partitions exceed their per-partition
global limit when capacity is available. With an uneven split, such as local_limit: 5 across
two active partitions, each partition was capped at 2 and one slot sat idle.
Burst now fills the remaining capacity, with the extra slot going to whichever partition has the highest-priority next job.
[DynamicLifeline] Fix repair cycle on Ecto 3.14+
The :repair_limit option was passed through to Repo.all and Repo.update_all as a query
option, which Ecto 3.14 rejects (earlier versions silently ignored it), breaking workflow,
chain, partition, and chunk repairs.
[Smart] Retry fetching after deadlock errors
An unhandled 40P01 raised within a producer would terminate it. The crashed producer was
unregistered and no longer refreshed, and the leader cleaned it up, making the queue disappear
until it was restarted.
[Workflow] Serialize concurrently acking jobs from a shared workflow
Producers acking workflow jobs could deadlock on oban_workflows rows when the update trigger
locked them in non-deterministic order. Take per-workflow locks so concurrent flushing serialize
before the trigger fires, eliminating the deadlock rather than relying on retry.
[Diagnostics] Pull oban conf directly from registery
Prevent testing race conditions caused by oban instances shutting down between selecting them from the registry and pulling configuration.
[DynamicCron] Add cron_at to scheduled job metadata
Each scheduled job now carries its slot time in UTC under cron_at, alongside the existing cron
fields. The slot is the same value for both on-time and guaranteed catch-up inserts, giving
callbacks a stable time anchor that survives retries and re-runs without re-parsing the cron
expression.
[Worker] Preserve unsaved_error in job error hooks
The original error was overwritten after resolving structured args, which was a regression from the previous behavior.
[Chain] Restore predicate in chain query for partial index
One of the primary chain subqueries lacked a predicate check, which prevented the query from using the proper chain index.
[Chain] Process hybrid legacy and suspended chains
When any legacy chain existed, the chain flusher and rescuer would only match the legacy representation and skip suspended followers entirely. This is a parallel fix to the recent legacy workflow changes.
[Workflow] Correctly process hybrid legacy and suspended workflows
Workflows with mixed on_hold meta and suspended states weren't transitioned properly, which
could leave those workflows stuck and without a way to recover.
Now on-hold 'scheduled' and 'suspended' jobs are checked together for legacy workflows. The detection cache now expires as well, so a legacy system can transition to non-legacy after older jobs have processed.
[Chain] Detect legacy chains separately from workflows
Split the legacy detection so chain rescue and flushing can be gated on chain data alone. The previous check required a legacy workflow, so a system without legacy workflows never rescued legacy chains.
[Worker] Encode signal payloads as native terms
Signal payloads were silently converted to JSON, which would cause an exception for unencodable terms such as tuples. Signals are now treated the same as recorded job data, so any term round-trips through signal/await_signal intact.
[Migration] Stop dropping any indexes in 1.7 migration
Previously, the v1.7 migration dropped several indexes during the upgrade to make way for
optimized replacements. Now the migration renames the originals with an _old suffix and
creates the new indexes alongside them, leaving the slow drops to a separate cleanup migration
users run on their own schedule.
[Smart] Repair more states during unique violations
When the Smart engine hits a unique violation transitioning a job, it previously only cleared siblings in the executing state, leaving potential duplicates in available or retryable to trip the same violation on their next transition.
[Workflow] Fix timezone shift in workflow timestamp triggers
The workflows trigger used now() to populate timestamps, which returned timestamptz and
could differ from UTC used elsewhere. Now timestamps are cast as UTC for consistency.
signal/3 and await_signal/1.
[Worker] Add signal and await_signal for external events
Introduces signal/2,3 and await_signal/1, letting jobs pause mid-execution and resume when a
signal arrives. The Smart engine preserves scheduled_at when a signal lands during the snooze
ack window, so signals delivered before, during, or after parking are never lost.
Workflow.signal/3,4 is a thin wrapper that resolves named jobs and delegates to the worker.
[Workflow] Restructure all_recorded query for index optimization
Restructure the fragment so each disjunct includes its own containment predicate.
[Workflow] Optimize legacy suspended check to use workflow index
Replace the containment operator (@>) in legacy workflow detection query with key existence
operators that match the partial workflow index, avoiding a sequential scan when the meta GIN
index is removed.
[Smart] Determine unique mode based on index shape
The mode must be determined from the shape of oban_jobs_unique_index itself rather than column
presence. An upgraded database can retain the legacy uniq_key generated column while the only
remaining unique index is the expression-based one created by the v1.7 migration.
[Usage Rules] Include usage-rules in packaged releases
None of the usage-rules were included in the packaged release.
[Chunk] Rename Oban.Pro.Workers.Chunk to Oban.Pro.Chunk
Rename the Chunk worker to Oban.Pro.Chunk to match the naming convention used by Batch and
Workflow. The old module is preserved as a deprecated shim that delegates to the new module.
[Workflow] Optimize workflow flush query for pathological cases
Overhaul workflow flushing query to avoid lateral sub-queries, minimize buffer hits, avoid repeated TOAST reads, and use a more efficient hash join for same-workflow dependencies.
For a 10_000->1 fan-in workflow the result is 31x faster, with 222x fewer buffer hits.
[Pro] Fix bootstrap file checking on Windows
File checks failed on Windows because Mix copies files to _build instead of symlinking. The
NIF was navigating from priv_dir up to find source files, which only worked when symlinks
resolved to deps.
[Refresh] Gracefully check for hex availability
Ensure hex is available before attempting to update in the oban_pro.refresh task.
[Pro] Update app modules list after compiling sources
Encrypted modules handled by the :oban_pro compiler weren't included in the .app file
because it was generated before they were compiled. Releases use the modules list to determine
what to load at boot, causing releases to crash with UndefinedFunctionError for encrypted
modules.
[Pro] Fix Windows NIF loading in bootstrap module
On Windows, BEAM passes NIF function pointers via a callback table at load time instead of resolving them through dynamic linking. The bootstrap module now properly defines, resolves, and casts callbacks for cross-platform operation.
[Migration] Stop adding suspended state to the oban_jobs_state enum
The suspended state must be added by Oban's v14 migration prior to running the Pro 1.7.0
migration. Postgres prohibits altering a type and referencing it within the same transaction,
and the upgrade could fail.
[Workflow] Use t:add_cascade_opts/0 for add_graft/4
The add_graft/4 function accepts workflow opts in addition to job opts, but only specified the
t:add_opts/0 type.
chunk_id generation for smoother upgrade to v1.7Generate a chunk_id at job insertion time and store it in meta. This pre-populates the
identifier that Pro v1.7 uses for optimized chunk queries, ensuring jobs inserted on v1.6 will
work seamlessly immediately after upgrading. Pro v1.7 will backfill jobs with a missing chunk_id
after a minute or so, but does so in batches.
[Worker] Conditionally add @impl to worker opts/0
Oban v2.21 marked c:Worker.__opts__/0 as a callback and made it public. Now, Oban.Pro.Worker
marks the __opts__/0 function as a callback for Oban v2.21, but not for older versions.
[Unique] Include suspended state in unique bmp mapping
The suspended state is available for uniqueness as of Oban v2.21, but it was lacking from the
uniq bmp mapping. The state is now supported to prevent errors when inserting unique jobs.
[Pro] Use suspended state for workflow and chain tracking
Jobs waiting on workflow or chain dependencies now use a proper suspended job state instead of
the previous on_hold psuedo-state.
This provides cleaner state semantics, better query performance through simplified indexes, and
enables the database triggers to track workflow state counts accurately. The scheduled_at
timestamp is preserved directly on suspended jobs, eliminating the need for orig_scheduled_at
in meta.
[Pro] Add usage rules for agentic coding assistants
Ship reference documents that help coding agents understand Pro's idioms and best practices. Rules cover workers, queues, composition primitives (workflows, batches, chains, chunks), plugins, and testing.
[Chunk] Optimize queries with centralized index and better job acking
Use a pre-computed chunk_id for chunk tracking, enabling a partial index for much faster
chunk lookups. This eliminates dynamic query construction based on partitioning fields in favor
of direct chunk_id matching.
Chunks now use a single SQL operation for acking , reducing database round-trips when completing, cancelling, or retrying jobs within a chunk. The new acking operation has better compatibility with non-Postgres databases such as CockroachDB.
[Chunk] Add :snooze support to chunk workers
Chunks can now selectively snooze jobs using {:snooze, period, jobs} or selectively snooze
some jobs with snooze: {period, jobs} in the keyword list result. Snoozed jobs are rescheduled after the specified
period, while unlisted jobs complete normally.
[DynamicCron] Add get/2 function for fetching entries by name
Provides a convenient way to retrieve a single cron entry without fetching all entries. Accepts either a worker module or custom string name and returns {:ok, entry} or {:error, message}.
[DynamicLifeline] Improve workflow rescue accuracy and remove limit
The DynamicLifeline's workflow rescue mechanism now queries the aggregate table for workflows with suspended jobs, providing more accurate detection than scanning the jobs table for suspended jobs alone.
This catches edge cases where workflows are stuck but their suspended jobs may have been lost or
deleted. Legacy on_hold workflows that predate the aggregate table are still found via a
direct jobs table query.
Only workflows that have been executing for more than a minute are candidates for rescuing by default.
[DynamicLifeline] Automatically repair chunk jobs missing chunk_id
Chunk workers now use a pre-computed chunk_id for grouping. Jobs created before this change
won't have a chunk_id in their metadata, which would prevent them from being grouped correctly.
The DynamicLifeline plugin now automatically computes and sets the chunk_id for any chunk jobs
that are missing it, similar to how it repairs missing partition_key values for partitioned
queues.
[DynamicPruner] Add configurable preserve_workflows option
Allow disabling workflow job preservation during pruning via the new preserve_workflows
option, which defaults to true for backwards compatibility. When disabled, jobs are pruned
regardless of whether their workflow is still active. This is useful for large workflows that
naturally run longer than a pruning cycle.
[Migration] Replace generated columns with expression indexes
Generated columns for uniq_key and partition_key were originally added for CockroachDB
compatibility but introduced unnecessary complexity and excessive table locking for large
tables. This change replaces them with expression indexes directly on the meta JSONB fields.
A generated_columns migration option is still available for apps that are running CockroachDB
and need the old functionality. The Smart engine detects which mode is being used and handles
conflicts accordingly.
[Migration] Add partial indexes for pruning and staging
Partial indexes reduce index size and improve query performance by only indexing rows that match
the filter condition. This adds partial indexes for terminal job states and a staging index for
jobs ready to transition to available.
Also fixes completed job pruning to use completed_at instead of scheduled_at, which is the
semantically correct timestamp for determining job age.
The new staging query may perform 2-10x faster depending on the number of jobs and overall state distribution.
[Rate Limit] Add centralized module for using rate limits outside of job execution
The module's functions allow checking, resetting, and consuming rate limits from running queues.
The consume/3 function is fully distributed and spreads consumption across multiple nodes when
a single producer cannot satisfy the request.
[Smart] Add auto_space option to spread out bulk inserts
When inserting large batches of jobs, auto_space schedules each batch at
increasing intervals. This prevents overwhelming queues when jobs can't
all execute immediately.
[Smart] Add on_conflict: :skip option for bulk inserts
Support skipping unique conflicts without row locking during insert_all. When enabled, conflicting jobs are silently skipped and only newly inserted jobs are returned. This improves performance for high-throughput scenarios where tracking conflicts isn't needed.
[Smart] Add transaction option for bulk insert atomicity
Support transaction: :per_batch to commit each batch independently during insert_all/2.
Previously inserted batches persist even if a later batch fails. The default transaction: :all
preserves the existing all-or-nothing behavior.
[Smart] Add telemetry sub-spans for engine fetch_jobs
Instrument the fetch_jobs transaction with nested telemetry spans for granular observability
into acking, flushing, demand calculation, and job fetching. Each sub-span emits standard span
events under [:oban, :engine, :fetch_jobs, :ack | :flush | :demand | :fetch].
[Smart] Support selecting between multiple rate limiting algorithms
Rate limited queues can select from :sliding_window, :fixed_window, and :token_bucket
algorithms to control how rate quotas are consumed. The :sliding_window algorithm remains the
default.
[Smart] Add :fixed_window rate limiting algorithm
Introduce a fixed window algorithm, which resets the count when the period expires rather than using weighted averaging.
[Smart] Add token bucket rate limiting algorithm
Introduce token bucket algorithm that refills tokens continuously at a fixed rate rather than
resetting at period boundaries. Tokens refill at allowed / period per second, providing
smoother rate limiting with natural burst handling.
[Worker] Add @impl declaration for worker __opts__/0
Mark Oban.Pro.Worker.__opts__/0 as implementing the new __opts__/0 public callback from
Oban.Worker.
[Worker] Add on_cancelled/2 and on_discarded/2 worker hooks
Introduce two new worker callbacks that fire when jobs are cancelled or discarded, regardless of how the state transition happens:
on_cancelled/2 receives :dependency or :manual reasonon_discarded/2 receives :exhausted reasonBoth callbacks work with global hooks via attach_hook/1 and module-level hooks via the
:hooks option.
[Worker] Apply structured args timeout/1 and backoff/1
Automatically apply encryption and structuring before calling user defined timeout/1 or
backoff/1 implementations. This allows pattern matching on structured args without any code
changes.
[Worker] Variable weight rate limit tracking via options and callback
Add support for job weights in rate limiting, allowing jobs to consume variable amounts of rate limit capacity:
use Oban.Pro.Worker, rate: [weight: 5]Worker.new(args, rate: [weight: 3])weight/1 for dynamic weight calculation at dispatch timeJobs with higher weights consume more rate limit capacity, enabling fine-grained control over resource-intensive operations.
[Workflow] Optimize workflow flushing with de-duplication
Restructure workflow flushing to compute dependency states once per unique dependency rather than once per job-dep combination. This eliminates the M*N scaling problem when M jobs share common dependencies.
Benchmarks show ~2x faster execution, 7x fewer buffer hits, and 15x fewer index scans for workflows with shared dependencies.
[Workflow] Flushing is optimized to load minimal data up front
Only the exact data needed for workflow flush operations is loaded from the database, rather
than the entire job structure. This saves data over the wire, serialization overhead, and memory
usage for active workflows or jobs with large args, errors, or meta.
The full job structure is loaded asynchronously when cancellation callbacks are needed.
[Workflow] Add table for centralized workflow tracking
Introduces a dedicated table to track workflow metadata and job state counts, replacing expensive aggregation queries with precomputed values. This improves performance for large workflows and enables efficient filtering/sorting in Oban Web.
[Workflow] Add unique workflow support to prevent duplicates
Workflows can now be created with unique: true to prevent multiple workflows with the same
name from running concurrently. When a duplicate unique workflow is inserted, its jobs are
marked with conflict?: true instead of being inserted.
[Pro] Packages are distributed with encrypted source code
Pro packages are encrypted, with licenses that stay fresh for 30 days. Development remains seamless, so documentation, type signatures, and LSP integration all work normally.
Enterprise license holders receive unencrypted source code.
See the Upgrade Guide for details on checking license status and refreshing.
[DynamicPartitioner] Deprecate the DynamicPartitioner plugin
The complexity and edge cases introduced by partitioned tables far outweigh the benefits for most applications.
[Workflow] Deprecate after_cancelled/2 in favor of universal on_cancelled/2
The after_cancelled/2 callback is deprecated in favor of the universal on_cancelled/2 hook.
Currently, both hooks will be called if defined, and users should switch to on_cancelled/2.
[Migration] Fix migration check crash with dynamic repo config
The migration telemetry handler crashed on startup when users configured a placeholder repo
module with get_dynamic_repo providing the actual repo at runtime. The handler attempted to
call get_dynamic_repo/0 on the static repo before evaluating the dynamic repo callback.
[Refresher] Add error handling to producer record refreshing
Previously, if refresh_producers or cleanup_producers raised (e.g., due to a connection checkout timeout), the GenServer would crash and restart, causing missed heartbeats and timer resets. Now errors are caught and logged, allowing the refresh cycle to continue uninterrupted.
[Testing] Ensure ordered run_workflow/2 output
Always order workflow jobs by execution completion order to preserve sequential execution results.
[Worker] Trigger on_cancelled/2 when deadline force-cancels
When a job with deadline: [force: true] exceeds its deadline during execution, the
on_cancelled/2 hook is now called with :deadline as the reason. This allows workers to
perform cleanup or notifications when jobs are terminated due to deadline expiration.
[Oban] Add job diagnostics for runtime process inspection
Introduce runtime diagnostics for executing Oban.Pro.Worker jobs, allowing external tools like
Oban Web to request process information (stacktrace, memory, status) for running jobs via
PubSub.
[DynamicCron] Skip worker validation when deleting DynamicCron
When a worker module is removed from the codebase, it was previously impossible to delete its persisted cron entry using the delete: true option because validation would fail trying to load the module.
[Smart] Fix unique violation retry loop for similar states
Clearing unique violations could fail to find conflicting jobs when the job's current state
(e.g., retryable) was included in its unique states. This caused the clearing query not to
match, so nothing would be cleared, causing an infinite retry loop.
Retries are now limited and an error logged for excessive retry loops.
[Smart] Prevent chain race condition on concurrent insert
When two transactions concurrently insert jobs for the same chain without any prior jobs in the
chain, both could see "no existing job" and insert as available, violating sequential
guarantees.
[Smart] Include :meta options in t:partition/0
Using meta for partitioning has been supported for a while now, but the type was outdated.
[Workflow] Fix context for deps in nested sub-workflows
When using add_cascade with a fan-out tuple (e.g., {items, &fun/2}) inside a nested
sub-workflow that also has dependencies, the fan-out jobs would incorrectly receive the outer
workflow's context instead of their immediate parent sub-workflow's context.
[DynamicCron] Optimize cron entry insertion history tracking
The history tracking for cron entries retained too much information and was needlessly expensive to read and write. This simplifies the insertion format and dramatically simplifies tracking updates.
The optimization is backward compatible and existing arrays with history will continue to work, they'll just be replaced with single-element arrays on the next insertion.
[Workflow] Support fan-out tuple form in add_graft/4
The type specification for add_graft/4 indicated support for the cascade fan-out form
{Enum.t(), (any(), map() -> any())}, but only the single-function form was implemented.
Now you can fan out graft points the same way you would with add_cascade:
Workflow.new()
|> Workflow.add(:setup, SetupWorker.new(%{}))
|> Workflow.add_graft(:process, {items, &process_item/2}, deps: :setup)
|> Workflow.add(:finalize, FinalizeWorker.new(%{}), deps: :process)
[Workflow] Wait for arbitrarily nested grafted sub-workflows
Jobs depending on a graft now properly wait for dynamically appended sub-workflows at any
nesting depth. Previously, when a grafted workflow used append + add_many to create
additional jobs, the dependent job could run before those nested jobs completed.
The flush mechanism now tracks the complete ancestor chain so workflows flush correctly regardless of how deeply they are nested.
[Workflow] Inherit all context for nested sub-workflows
When using add_cascade with fan-out inside nested sub-workflows, context from intermediate
parent workflows was not accessible. Jobs would only see context from the outermost workflow,
skipping any workflows in between.
Now context is correctly inherited through any depth of workflow nesting. Each level's context is merged in order from outermost to innermost, with closer ancestors overriding values from farther ones.
[Smart] Ensure partition key cache never hits under load
The timed cache for partition keys could fail to return cached results when jobs were being inserted concurrently, causing repeated database queries for available partition keys. This removes stale telemetry handlers that were interfering with cache lookups.
[DynamicLifeline] Correctly filter empty partitions during rescue queries
The partition rescue query could incorrectly check producers with empty partitions after queue updates.
[Smart] Improve partition query by repairing unpartitioned jobs
Partitioning selects fewer keys, more accurately, to prioritize active partitions. This ensures partitions with higher priority or older jobs are processed first, while still distributing work across all active partitions.
Jobs in partitioned queues that are missing a partition key (such as jobs scheduled before a
queue was partitioned) are now repaired by DynamicLifeline automatically.
Overall, this change means fetching jobs in partitioned queues requires fewer resources even after bulk job inserts.
[Smart] Add telemetry and logging for unique repairs
Emit [:oban, :engine, :uniq_violation_repaired] telemetry on every unique repair and log an
error once per unique key to surface potential issues that could otherwise silently degrade
staging and fetching performance.
[Workflow] Preserve name for deeply nested sub-workflows
Preserve the sub-workflow's name for jobs from nested sub-workflows when composing workflows
with add_workflow/3. Previously, nesting a workflow containing add_many/3 inside another
add_workflow/3 would incorrectly overwrite the inner jobs' metadata.
[Workflow] Prevent context conflicts in deeply nested workflows
Preserve the workflow id for jobs from nested sub-workflows to prevent multiple context jobs
from sharing the same workflow_id. This eliminates an Ecto.MultipleResultsError when using
put_context/2 in workflows nested multiple levels deep via add_workflow/2.
[Workflow] Wait for dynamically appended jobs for grafted workflows
Jobs depending on a grafted workflow now correctly wait for all dynamically inserted jobs,
including those added via add_many/4 within apply_graft/2.
Previously, when a grafter job used apply_graft/2 with a workflow containing nested
sub-workflows (from add_many/4), dependent jobs would execute before the appended jobs
completed.
[Workflow] Track recursive graft dependencies from parent workflows
When a grafting job creates sub-grafts recursively, jobs depending on the original graft now correctly wait for all recursive grafts to complete.
The fix ensures nested graft jobs share the root graft's workflow_id so the parent's wildcard
dependency can find them.
[Worker] Validate structured args during update_job/3
Structured args weren't validated during update_job/3 calls, which could lead to errors when
the job eventually processed. Now, same validation is applied on update as when the job is built
with new/2
[Decorator] Correct typespec for the subset of unique opts for decorated jobs
The typespec for period, states, and timestamp were incomplete or too loose. The new
typespec references the types from Oban.Job.
[Smart] Fix inaccurate acking for externally modified jobs
When another node or process updates a job while it's executing, or inserts a conflicting unique job, the ack query could fail to lock or update. This could cause mismatches between tracked and actual job states.
[Worker] Ensure after_process/3 hooks trigger on cancellation
Executing jobs that were manually cancelled via Oban.cancel_job or similar mechanisms, didn't
have after_process/3 hooks triggered due to a caching issue. That situation is handled now and
hooks are called as expected.
[Refresher] Cleanup producers regardless of running queues
The refresher will now cleanup stale producers from any leader node, not just nodes that are running queues. This aims to ensure producers are cleaned up even with subtle misconfigurations, e.g. disabling queues without disabling plugins.
[Docs] Extract svg diagrams into separate files
Inline svg images involve a lot of text and can overwhelm an LLM's context window. This extracts the svgs out as separate assets and loads them dynamically instead.
[Workflow] Add atom_keys option to configure cascade context
The atom_keys option controls whether the keys in a cascade function's context map are
atomized or converted to strings. This helps with consistency for nested workflows, or when
atoms may not exist between nodes.
[Testing] Add missing functions to make a drop-in replacement for Oban.Testing
Add missing functions (build_job/3, perform_job/1,2, and with_testing_mode/2) to ensure
Oban.Pro.Testing is fully compatible with Oban.Testing. This allows seamless migration from
Pro without modifying existing test helpers or test code.
[Workflow] Flatten contexts within nested grafts
When building complex workflows with nested grafts (a graft within another graft), the recorded results from upstream jobs were being incorrectly nested in the context passed to downstream jobs. Now, nesting is applied correctly at any level of nesting.
[Workflow] Prevent deadlocks for queues processing workflows
Adds locking to prevent deadlocks when jobs from the same workflow or chain complete simultaneously on different nodes.
[Workflow] Correct condition guard in status query
The query used to expand the status for sub-workflows didn't make use of the existing workflow indexes, which could lead to poor performance in busy systems.
[DynamicCron] Compare inserted times in UTC for guaranteed cron
Prevent double triggering jobs for guaranteed cron during DST changes. Time is always compared in UTC, rather than shifting to the current timezone.
[Refresher] Prevent active producers from erroneous cleanup
When a queue's producer is stuck in a transaction retry loop, it isn't able to handle new messages, including periodic refresh requests. This would allow the producer record to become outdated in the database, at which point it is subject to erroneous cleanup.
Refreshing now proactively discovers and refreshes all active producers through the Registry, rather than relying on individual producers messages.
[Workflow] Explicitly group workflow conditions for flushing query
The boolean grouping of statements in a workflow query was incorrectly interpreted and resulted in a highly inefficient workflow query.
[Smart] Fetch and execute jobs with missing partition keys
Previously, partitioned queues wouldn't run jobs with null partition keys. This was an edge case, usually caused by adding partition config to a queue with older, scheduled jobs in it.
[Relay] Add with_retries option to await/2
It's now possible to keep waiting for a job to complete across retries. The awaiting process will keep waiting until the job has exhausted all attempts before or the timeout is reached. This makes async/await more reliable for jobs that have flickering failures.
[Refresher] Fix shutdown order to prevent rescue mistakes
Queue producer refreshing, which is essential to identifying live queues, could terminate too
early during node shutdown. When the shutdown_grace_period exceeded the refresh interval,
producers would lose the ability to update their timestamps while still running, leading to
false stale producer detection and unnecessary job rescues.
Refreshing now survives instance shutdowns and continues updating producer timestamps throughout the grace period.
[Smart] Prevent deadlock during concurrent unique insert and fetch operations
Inserting unique jobs that conflicted with currently executing jobs could cause a deadlock. The ack query now takes an explicit lock to ensure updates complete, while also preventing the deadlock.
[Workflow] Update workflow flushing syntax for CRDB
The flushing query used a syntax that is valid in Postgres, but incompatible with how CRDB handles JSONB function output.
[Workflow] Include cascade options in apply_graft/2
The spec only included t:new_opts/0, but the function also creates cascade jobs and should
include t:add_cascade_opts/0.
[DynamicQueues] Correct typespec for update/3
The typespect listed t:queue_opts/0, which is a union of tuples, but should be a keyword list.
[DynamicPruner] Retain jobs in active workflows when pruning
The DynamicPruner no longer deletes jobs that are part of an active workflow or related
sub-workflow. If any job in a workflow is in an incomplete state (e.g. executing), no jobs in
the workflow will be pruned.
[DynamicQueues] Enabling clearing limits on queue config update
Clearing a DynamicQueue's rate_limit or global_limit by setting nil, or swapping between
options, now works with a config update.
[Workflow] Handle empty enumerables passed to add_many/4
Empty sub-workflows no longer prevent downstream jobs in a workflow from executing. Now, step elimination ensures the workflow executes in the expected order when a sub-workflow created from an empty enumerable.
[Worker] Move option validation to after_compile/2 hook
Validating options with an exception in an after_verify/1 hook breaks progressive compilation
and causes ongoing warnings during subsequent compilations. Options are now validated with
after_compile/2 instead.
[Smart] Prevent leaking tracked partitions between job fetches.
A race condition between acking and fetching could cause tracked global partitions to be retained when jobs weren't still processing. Now that logic is simplified and corrected to ensure only actively running job partitions are tracked.