Sessions

The server-tracked identity behind causal consistency, retryable writes, and transactions

Not a connectiona session is decoupled from any one underlying connection
Causal consistencya later read in the same session can be guaranteed to see an earlier write
Retry identitysession + transaction number lets the server recognize a retried write
Mostly invisiblemost operations already get an implicit, driver-managed session

1.Logical sessions

A logical session is a server-side identity for a sequence of related operations, created by the driver and identified by a session ID. It is not a network connection — the same session can span multiple connections, and a connection can carry operations from different sessions over time.

Key features

Created with client.startSession() — most drivers also start one implicitly for single operations, even if the application never calls this explicitly
A session is identified by a session ID the driver attaches to operations run through it
Sessions enable causal consistency: within one session, later reads can be guaranteed to reflect earlier writes made in that same session
Sessions are the mechanism retryable writes and multi-document transactions are both built on
A session is decoupled from any one connection — the driver can route its operations over different underlying connections transparently

Command

text

const session = client.startSession(); /* ...operations passing { session }... */ session.endSession();

A session is a server-tracked identity for a sequence of operations, independent of any one connection — it is the foundation causal consistency, retryable writes, and transactions are all built on.

2.Why transactions and retryable writes need a session

A transaction needs somewhere to hold its in-progress state — its session is that place. Retryable writes need a way for the server to recognize "this is the same logical write being retried, not a second one" — the session ID plus a per-write transaction number is exactly that identity.

Key features

A transaction is scoped to a session — there is no such thing as a transaction without one, since the session is what holds its uncommitted state between operations
Retryable writes attach a session ID and an incrementing transaction number to each write, so a retried write after a network blip is recognized as "the same attempt", not a duplicate
Without that identity, the server (and the driver) cannot safely distinguish "retry this exact operation" from "this is a new, different operation that happens to look similar"
Retryable writes are enabled by default in modern drivers for single-statement writes, precisely because this identity makes retrying safe
A session ending abruptly (client crash, timeout) aborts any in-progress transaction on it — the transaction has no independent existence outside its session

Command

text

// A transaction: always session.startTransaction(). A retryable write: session identity + txnNumber, usually handled by the driver automatically.

A transaction needs a session to hold its state between operations; a retryable write needs the session-scoped identity to let the server recognize a retry as the same attempt, not a duplicate.

3.Session lifetime and driver management

An idle session is automatically cleaned up by the server after a timeout (30 minutes by default) if it is never explicitly ended. Most drivers also start an implicit session for any operation that does not have one, so application code often benefits from sessions without ever calling startSession() directly.

Key features

An idle session (no operations for the timeout period, 30 minutes by default) is automatically reaped server-side
Most official drivers create an implicit session for any operation issued without one, so single-operation code already benefits from retryable writes without explicit session code
endSession() should still be called explicitly on any session the application created, to release its resources promptly rather than waiting on the idle timeout
A session cannot be shared safely across concurrent operations that both expect exclusive use of it — particularly relevant inside a transaction
Long-lived application processes should avoid creating and abandoning many sessions without ending them, since each one holds server-side resources until cleaned up

Command

text

// Implicit: db.collection.findOne({...}) already gets an implicit session. Explicit: needed for transactions or causal consistency.

Most single operations already get an implicit session with retryable-write safety for free — reach for explicit startSession()/endSession() specifically for transactions or causal consistency, and always end what you start.

Spotted a mistake on this page? Tell us.

Read Sheet