Skip to content

Job transactions

A queue attempt or a scheduled tick runs in one transaction — atomic per attempt, retried only where it could help — and the opt-out.

Queue processors and cron jobs run outside any HTTP request — no method to classify, no response to inspect. The worker transport (#[scheduled], #[processor]) runs every job as a unit of work through the same binding:

job
↓
SeaOrmUnitOfWork ──→ installs a lazy transaction, settled on the job's Ok/Err
↓
processor body

A job attempt is atomic by default. The transaction is lazy — a job that never touches the database never opens one — and it commits when the job returns Ok, rolls back otherwise. That is what makes a retry safe: a job that failed halfway left nothing behind for the second attempt to write again.

Atomic per attempt is not the same as idempotent per job, and the difference is the queue’s, not the transaction’s. A backend that delivers at least once — which is what a durable queue is — can redeliver a job whose attempt committed, if the worker died between the commit and the acknowledgement. The transaction guarantees you never see half an attempt’s writes; it cannot promise the body runs once. A job whose re-execution would be harmful wants an idempotency key regardless of this setting.

And a retry only happens where it could help. A job whose body succeeded but whose transaction could not be settled is a failed attempt — but whether to re-attempt it is read from what the database said, never assumed — and where it said it. A statement inside the attempt that failed on a serialization conflict or a deadlock (40001, 40P01), on a pool that never handed out a connection, or on one the server closed (08…, 57P0…) is retryable: nothing is durable before COMMIT, so the framework knows the attempt wrote nothing. At the commit the reading flips: a constraint checked at COMMIT fails identically every time, and a commit whose outcome is unknown — the connection lost mid-COMMIT — may have landed. Neither of the last two is replayed: a retry re-runs the whole body, including every side effect that is not the database’s, and the framework only promises “nothing left to repeat” for a transaction it knows rolled back. Both abort straight to the dead-letter queue, where the failure is visible, instead of burning the budget in silence.

A schedule has no retry budget and no dead-letter, so #[every] / #[cron] / #[after] report the failure at error on nest_rs::schedule and fire again at the next occurrence — the classification is logged rather than acted on, because there is nothing there for it to decide.

No caller means no ambient ability, which means Repo reads and writes are unscoped — correct for system work with no principal to scope to. A job acting for a principal, or for a visitor, wraps its body in with_ability(ability, body), which scopes it to those rules; it only ever narrows, so inside a request it intersects with the caller’s ability, never replaces it.

transactional = false runs the job on the pool, where every statement commits on its own:

crates/features/src/audio/queue/processor.rs
#[process(queue = AudioQueue, retries = 3, transactional = false)]
async fn transcode(&self, job: TranscodeCommand) -> anyhow::Result<()> { /* ... */ }

The key is the same word on all four job decorators — #[process], #[every], #[cron], #[after].

Reach for it when the job brackets long work that is not the database’s: read a row, spend minutes transcoding, write the result. The default would hold a pooled connection across the middle. Such a job owns its own consistency, and an idempotency key is what makes its retry safe — the transaction never was.

A job that wants a narrower unit than the attempt has two answers: an atomic block, a savepoint of the attempt’s transaction that rolls back alone, or transactional = false, plus its own idempotency, when nothing may be held across the work. retry_on_conflict around the ambient executor would replay into the transaction the conflict already aborted: it is for a programmatic boundary in a service, not for a job body (see Transactions).