Skip to content

Transactions

Mutating routes commit on 2xx/3xx, roll back otherwise — plus what waits for the commit, a unique key held elsewhere, and atomic blocks.

A mutating request runs inside a transaction with no boilerplate. Import SeaOrmDatabaseModule and the HTTP edge opens it around every mutating request, hands the handler the transactional executor, and decides commit or rollback on the request’s outcome. The hard cases — serialization conflicts, deadlocks — get their own primitive, with a defined boundary between what the edge’s unit of work handles and what the service owns.

The conflict classifier matches against sqlx’s typed DatabaseError::code() (SQLSTATE) — never a formatted error string — so a digit substring in a message can’t trigger a false retry. SeaORM provides the TransactionTrait the programmatic boundary builds on.

The edge classifies the HTTP method and branches:

GET / HEAD / OPTIONS / TRACE → the pool, no transaction
POST / PUT / PATCH / DELETE → a lazy transaction, BEGIN on the first
data-layer touch;
commit on 2xx/3xx,
rollback otherwise

Inside the handler, every Repo call runs on whichever the unit installed — same code, different mode. The decision matrix:

OutcomeDecision
Ok(2xx) or Ok(3xx)commit
Ok(4xx) or Ok(5xx)rollback
Err(_) from the handlerrollback, whatever an exception filter answered
Handler past the request timeoutrollback; 503 with Retry-After
Commit errorresponse becomes 500, rollback is implicit
Commit did not answerresponse becomes 500, no Retry-After: its writes may have landed

A failed mutation never half-persists, even when the failure surfaces as a typed 4xx body from a thiserror-derived error. See Repo and executor for the full sequence, including the escape-on-spawn case.

/graphql and /mcp are the exceptions to the method rule: their requests carry operations that are units of their own, so the request itself runs on the pool — its guards read there — whatever its method, and each operation settles its own work.

Every other edge runs the same unit of work, through the same binding, and commits on its own outcome — you list nothing for it:

UnitCommits when
GraphQL querynothing to commit: it runs on the pool
GraphQL mutationits answer reports data; each root field kept unless it answers null for an error (below)
WebSocket messagethe reply is not an error frame
WebSocket connect or disconnect hookthe hook ran to its end
MCP operationit answered Ok, with no isError: true in the tool’s result
Queue attempt, scheduled tickthe method returned Ok (or the pool, on transactional = false)
Lifecycle hookthe hook returned Ok

A read is a touch: a message or a tool that only reads still opens the transaction on its first query, and commits it.

A GraphQL response always answers 200, so the status line cannot say what committed. Each operation of the document is a unit of its own instead, and a mutation’s root fields each run in a savepoint of it, kept or rolled back on the answer the field gives. With createPost returning Result<Option<Post>>, a nullable Post:

mutation {
a: createPost(input: { title: "first" }) { id } # kept
b: createPost(input: { title: "" }) { id } # null: rolled back alone
c: createPost(input: { title: "third" }) { id } # kept
}
  • A query runs on the pool, its own unit, opening no transaction.
  • A mutation is one transaction, opened on its first statement. Its root fields resolve one after the other, each inside an atomic block: a root field that answers null for an error — its own, or a Non-Null field’s below it whose null climbs to it — rolls back its writes and drops the events it emitted, and the operation’s other fields commit. Its error reads as the resolver wrote it: a unique violation is its CONFLICT, never an empty 500.
  • A null that stays below the root field leaves its work standing. A nullable field that fails under it, or a Non-Null one under a nullable parent, answers null where it lands (where a failed field’s null lands), and the root field keeps its answer: what the answer reports, the database holds.
  • An answer with no data rolls the whole operation back. A Non-Null root field — Result<Post>, a Post! — hands its null to data itself, so the answer reports nothing: the root fields that answered before it roll back too, and none after it runs. A mutation sent beside others whose work must stand on its own returns Result<Option<T>>.
  • A mutation runs each root field once. async-graphql 7.2.1 runs a root field once per selection, where the specification runs one response key once, so a document naming one twice — a: createPost(…) { id } beside a: createPost(…) { title }, two fragments that each select it, one fragment spread twice — would write twice and answer one of the two. Its copies merge into the first before validation, so the field writes once, in one savepoint, and answers what each copy selects. Copies naming different arguments are no one field, and are refused before any root field runs, with data: null: side by side, as in a: createPost(input: $p) beside a: createPost(input: $q), by validation’s own conflict error, which names both; under different type conditions, a fragment’s included, by one INVALID_ARGUMENT error at the copy that differs (where a failed field’s null lands). A copy @skip or @include leaves out runs nothing, so it repeats nothing.
  • A field that never touches the database sends nothing: its savepoint is as lazy as the transaction around it.
  • A batch holding a mutation runs its operations one at a time, in document order, so its units never hold several pooled connections at once; a batch of queries runs them all at once.
  • Over graphql-ws each query and mutation is a unit of its own too, opened inside the socket’s; a subscription keeps the connection’s pool.
  • When an operation’s commit cannot be honoured — it failed, or did not answer within its net — the operation answers data: null and one opaque INTERNAL error: a response never reports a write that did not land.
  • Under a request timeout, a request holding a mutation takes the deadline over: an operation still running there is cut inside its unit, rolled back and answered UNAVAILABLE in band, while one already committing is waited for. A request of queries alone is cut as any request is, 503.

A deadline cuts the body, never the commit

Section titled “A deadline cuts the body, never the commit”

Every unit with a deadline — a request’s timeout, a WebSocket message’s, an MCP operation’s, a job’s or a tick’s timeout — cuts its body there and nothing else. A body cut at its deadline is rolled back and answered as a timeout: 503 with Retry-After, an UNAVAILABLE frame or error with reason: "timeout", a retryable JobTimedOut. Its rollback may still wait on a statement Postgres holds behind a lock; the edge answers at the deadline all the same, and the driver ends the rollback on a task of its own.

A body that answered in time is never turned into a timeout by its commit: the COMMIT runs to its answer on the driver’s task, which a client gone, an operation stopped or a closing window does not cut, and which the driver drains before the pool closes at shutdown. SeaORM waits for that answer at most the statement budget plus a second (<PREFIX>_SEAORM__STATEMENT_TIMEOUT_SECS, 15 by default); a commit that does not answer by then may have landed, so the unit fails in doubt — never retried, a request answered 500 without Retry-After, a job dead-lettered, a tick reported retryable=false:

Terminal window
ERROR nest_rs::orm: the unit's commit did not answer within its net; its writes may have landed transport="queue" outcome="in_doubt" net_ms=16000 trace_id=… span_id=…

An event emitted inside the transaction is dispatched after the commit, and dropped when the transaction rolls back or fails to commit, or the request fails — an event announces a fact, and a write that did not land is not one. The same holds at every boundary that settles a transaction: a WebSocket message, an MCP operation, a queue attempt, a scheduled tick, a lifecycle hook. The listeners run outside the transaction they waited for, each a unit of work of its own — a transaction committed on the Result it answers and bounded by its own timeout — with the caller’s scope, ability and every value the emitter carries; the response leaves once they have — or at the unit’s deadline, whichever comes first, and with the commit’s answer when that comes only past the deadline. Past the deadline a listener runs on, the unit answers the outcome it committed, and a slow listener never turns a committed write into a timeout (a debug line on nest_rs::orm: after-commit work outlived the unit's deadline).

A job you push waits too: with the queue feature, the push is written into the transaction as an outbox record and filed once it commits — see A push inside a transaction.

A WebSocket broadcast and a storage write do not wait, and cannot: each answers its caller — a send failure, an object key — and that answer only exists once the socket or the store has been asked. Inside a transaction they happen where they are written; when the work must follow the commit, emit an event and do it in its listener.

An atomic block holds what is emitted inside it: when it keeps its writes, the events join the request’s and wait for the request’s commit; when it rolls back, they are dropped with its writes.

The primitive underneath is nest_rs::database::after_commit, which the bus calls; a database driver implements it for its own transactions.

A statement that fails inside a transaction aborts the whole transaction, and the commonest failure a service expects is a unique key a concurrent request has just taken. An insert that should land, or meet the row already holding its key, says so instead of failing: Repo::insert_unscoped_or_existing sends INSERT … ON CONFLICT (key) DO NOTHING RETURNING, then reads the live row holding the key, so nothing fails and the transaction carries on.

crates/features/src/users/service.rs (from the demo, abridged)
let linked = Repo::<UserIdentities>::insert_unscoped_or_existing(
new_identity_active(user_id, identity),
[
user_identity::Column::Provider,
user_identity::Column::Subject,
],
)
.await?;
if let Insertion::New(_) = linked {
// …
}

Insertion::New holds the row inserted, Insertion::Existing the one that held the key. The key needs a unique index over exactly its columns; on an entity declared soft_delete, one over its live rows alone is inferred too, and a tombstone is never returned. It is insert_unscoped’s escape, under the same bar — provisioning before a principal exists, work no principal does.

A statement that may fail any other way runs in nest_rs::database::atomic. The block is a savepoint inside the request’s transaction: an error rolls back the block alone, and the request carries on and commits. Several statements that land together or not at all — a user and the identity it signs in with — run in one block too, which on a safe route is a transaction of its own.

crates/features/src/users/service.rs (from the demo, abridged)
let provisioned: Result<entity::Model, ServiceError> = atomic(async {
let user = match Repo::<Users>::insert_unscoped_or_existing(
active,
[entity::Column::Email],
)
.await?
{
Insertion::New(user) => {
// …
user
}
Insertion::Existing(user) => user,
};
self.link_identity(user.id, identity).await?;
Ok(user)
})
.await;
  • Ok keeps the block’s writes in the request’s transaction, which still commits or rolls back as a whole.
  • Err, a panic, or a failure the block swallowed rolls the block back and nothing else. A block that returns Ok over a failed statement answers AtomicError::Poisoned, since nothing it wrote stands.
  • On a safe route, where the request runs on the pool, the block is a transaction of its own, committed when it returns Ok. A block in a block is a savepoint of its own and rolls back alone. Its COMMIT runs on the driver’s task too: a deadline that cuts the body while it commits leaves it to finish, and the unit fails in doubt, its writes possibly landed.
  • Nothing is sent until the block’s first statement: a block that never queries costs no round trip.

The block’s error type takes an AtomicError — ServiceError does, by the class of the database’s refusal — so ? works inside it. A Repo call inside the block runs on the block’s savepoint: the request waits while a block is open, since a statement of its own would land inside the savepoint, and a statement issued from inside the block on the unit’s own transaction is refused, whether or not the block has opened yet, rather than left to wait for the block that holds it.

A conflict the database reports is observed by the request’s unit and retried by the service that owns a replayable boundary: Serialization conflicts.