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 bodyA 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.
The opt-out, and when it is right
Section titled “The opt-out, and when it is right”transactional = false runs the job on the pool, where every statement
commits on its own:
#[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).
Going further
Section titled “Going further”- Transactions — the unit each edge settles.
- Retries and failure — the budget a failed attempt spends.
- Repo and executor — the executor an attempt installs.