client_session – Logical sessions for sequential operations

Logical sessions for ordering sequential operations.

Requires MongoDB 3.6.

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

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().

For multi-document transactions, you can only specify read/write (CRUD) operations on existing collections. For example, a multi-document transaction cannot include a create or drop collection/index operations, including an insert operation that would result in the creation of a new collection.

A session may only have a single active transaction at a time, multiple transactions on the same session can be executed in sequence.

New in version 3.7.

See also

The MongoDB documentation on

transactions

Classes

class pymongo.client_session.ClientSession(client, server_session, options, authset, implicit)

A session for ordering sequential operations.

abort_transaction()

Abort a multi-statement transaction.

New in version 3.7.

advance_cluster_time(cluster_time)

Update the cluster time for this session.

Parameters:

• cluster_time: The cluster_time from another ClientSession instance.

advance_operation_time(operation_time)

Update the operation time for this session.

Parameters:

• operation_time: The operation_time from another ClientSession instance.

client

The MongoClient this session was created from.

cluster_time

The cluster time returned by the last operation executed in this session.

commit_transaction()

Commit a multi-statement transaction.

New in version 3.7.

end_session()

Finish this session. If a transaction has started, abort it.

It is an error to use the session after the session has ended.

has_ended

True if this session is finished.

operation_time

The operation time returned by the last operation executed in this session.

options

The SessionOptions this session was created with.

session_id

A BSON document, the opaque server session identifier.

start_transaction(read_concern=None, write_concern=None, read_preference=None)

Start a multi-statement transaction.

Takes the same arguments as TransactionOptions.

New in version 3.7.

class pymongo.client_session.SessionOptions(causal_consistency=True, default_transaction_options=None)

Options for a new ClientSession.

Parameters:

• causal_consistency (optional): If True (the default), read operations are causally ordered within the session.
• default_transaction_options (optional): The default TransactionOptions to use for transactions started on this session.

causal_consistency

Whether causal consistency is configured.

default_transaction_options

The default TransactionOptions to use for transactions started on this session.

New in version 3.7.

class pymongo.client_session.TransactionOptions(read_concern=None, write_concern=None, read_preference=None)

Options for ClientSession.start_transaction().

Parameters:

• read_concern: The ReadConcern to use for this transaction.
• write_concern: The WriteConcern to use for this transaction.

New in version 3.7.

read_concern

This transaction’s ReadConcern.

read_preference

This transaction’s ReadPreference.

write_concern

This transaction’s WriteConcern.