client_session – Logical sessions for sequential operations¶
Logical sessions for ordering sequential operations.
New in version 3.6.
Causally Consistent Reads¶
with client.start_session(causal_consistency=True) as session:
collection = client.db.collection
collection.update_one({'_id': 1}, {'$set': {'x': 10}}, session=session)
secondary_c = collection.with_options(
read_preference=ReadPreference.SECONDARY)
# A secondary read waits for replication of the write.
secondary_c.find_one({'_id': 1}, session=session)
If causal_consistency is True (the default), read operations that use the session are causally after previous read and write operations. Using a causally consistent session, an application can read its own writes and is guaranteed monotonic reads, even when reading from replica set secondaries.
See also
The MongoDB documentation on causal-consistency.
Transactions¶
New in version 3.7.
MongoDB 4.0 adds support for transactions on replica set primaries. A
transaction is associated with a ClientSession. To start a transaction
on a session, use ClientSession.start_transaction() in a with-statement.
Then, execute an operation within the transaction by passing the session to the
operation:
orders = client.db.orders
inventory = client.db.inventory
with client.start_session() as session:
with session.start_transaction():
orders.insert_one({"sku": "abc123", "qty": 100}, session=session)
inventory.update_one({"sku": "abc123", "qty": {"$gte": 100}},
{"$inc": {"qty": -100}}, session=session)
Upon normal completion of with session.start_transaction() block, the
transaction automatically calls ClientSession.commit_transaction().
If the block exits with an exception, the transaction automatically calls
ClientSession.abort_transaction().
In general, multi-document transactions only support read/write (CRUD) operations on existing collections. However, MongoDB 4.4 adds support for creating collections and indexes with some limitations, including an insert operation that would result in the creation of a new collection. For a complete description of all the supported and unsupported operations see the MongoDB server’s documentation for transactions.
A session may only have a single active transaction at a time, multiple transactions on the same session can be executed in sequence.