Struct mongodb::ClientSession
source · [−]pub struct ClientSession { /* private fields */ }
Expand description
A MongoDB client session. This struct represents a logical session used for ordering sequential
operations. To create a ClientSession
, call start_session
on a Client
.
ClientSession
instances are not thread safe or fork safe. They can only be used by one thread
or process at a time.
Transactions
Transactions are used to execute a series of operations across multiple documents and collections atomically. For more information about when and how to use transactions in MongoDB, see the manual.
Replica set transactions are supported on MongoDB 4.0+. Sharded transactions are supported on
MongoDDB 4.2+. Transactions are associated with a ClientSession
. To begin a transaction, call
ClientSession::start_transaction
on a ClientSession
. The ClientSession
must be passed to
operations to be executed within the transaction.
use mongodb::{
bson::{doc, Document},
error::{Result, TRANSIENT_TRANSACTION_ERROR, UNKNOWN_TRANSACTION_COMMIT_RESULT},
options::{Acknowledgment, ReadConcern, TransactionOptions, WriteConcern},
ClientSession,
Collection,
};
let mut session = client.start_session(None).await?;
let options = TransactionOptions::builder()
.read_concern(ReadConcern::majority())
.write_concern(WriteConcern::builder().w(Acknowledgment::Majority).build())
.build();
session.start_transaction(options).await?;
// A "TransientTransactionError" label indicates that the entire transaction can be retried
// with a reasonable expectation that it will succeed.
while let Err(error) = execute_transaction(&coll, &mut session).await {
if !error.contains_label(TRANSIENT_TRANSACTION_ERROR) {
break;
}
}
async fn execute_transaction(coll: &Collection<Document>, session: &mut ClientSession) -> Result<()> {
coll.insert_one_with_session(doc! { "x": 1 }, None, session).await?;
coll.delete_one_with_session(doc! { "y": 2 }, None, session).await?;
// An "UnknownTransactionCommitResult" label indicates that it is unknown whether the
// commit has satisfied the write concern associated with the transaction. If an error
// with this label is returned, it is safe to retry the commit until the write concern is
// satisfied or an error without the label is returned.
loop {
let result = session.commit_transaction().await;
if let Err(ref error) = result {
if error.contains_label(UNKNOWN_TRANSACTION_COMMIT_RESULT) {
continue;
}
}
result?
}
}
Implementations
sourceimpl ClientSession
impl ClientSession
sourcepub fn cluster_time(&self) -> Option<&ClusterTime>
pub fn cluster_time(&self) -> Option<&ClusterTime>
The highest seen cluster time this session has seen so far.
This will be None
if this session has not been used in an operation yet.
sourcepub fn options(&self) -> Option<&SessionOptions>
pub fn options(&self) -> Option<&SessionOptions>
The options used to create this session.
sourcepub fn advance_cluster_time(&mut self, to: &ClusterTime)
pub fn advance_cluster_time(&mut self, to: &ClusterTime)
Set the cluster time to the provided one if it is greater than this session’s highest seen
cluster time or if this session’s cluster time is None
.
sourcepub fn advance_operation_time(&mut self, ts: Timestamp)
pub fn advance_operation_time(&mut self, ts: Timestamp)
Advance operation time for this session. If the provided timestamp is earlier than this session’s current operation time, then the operation time is unchanged.
sourcepub fn operation_time(&self) -> Option<Timestamp>
pub fn operation_time(&self) -> Option<Timestamp>
The operation time returned by the last operation executed in this session.
sourcepub async fn start_transaction(
&mut self,
options: impl Into<Option<TransactionOptions>>
) -> Result<()>
pub async fn start_transaction(
&mut self,
options: impl Into<Option<TransactionOptions>>
) -> Result<()>
Starts a new transaction on this session with the given TransactionOptions
. If no options
are provided, the session’s defaultTransactionOptions
will be used. This session must
be passed into each operation within the transaction; otherwise, the operation will be
executed outside of the transaction.
Errors returned from operations executed within a transaction may include a
crate::error::TRANSIENT_TRANSACTION_ERROR
label. This label indicates that the entire
transaction can be retried with a reasonable expectation that it will succeed.
Transactions are supported on MongoDB 4.0+. The Rust driver currently only supports transactions on replica sets.
session.start_transaction(None).await?;
let result = coll.insert_one_with_session(doc! { "x": 1 }, None, &mut session).await?;
session.commit_transaction().await?;
sourcepub async fn commit_transaction(&mut self) -> Result<()>
pub async fn commit_transaction(&mut self) -> Result<()>
Commits the transaction that is currently active on this session.
This method may return an error with a crate::error::UNKNOWN_TRANSACTION_COMMIT_RESULT
label. This label indicates that it is unknown whether the commit has satisfied the write
concern associated with the transaction. If an error with this label is returned, it is
safe to retry the commit until the write concern is satisfied or an error without the label
is returned.
session.start_transaction(None).await?;
let result = coll.insert_one_with_session(doc! { "x": 1 }, None, &mut session).await?;
session.commit_transaction().await?;
This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.
sourcepub async fn abort_transaction(&mut self) -> Result<()>
pub async fn abort_transaction(&mut self) -> Result<()>
Aborts the transaction that is currently active on this session. Any open transaction will
be aborted automatically in the Drop
implementation of ClientSession
.
session.start_transaction(None).await?;
match execute_transaction(&coll, &mut session).await {
Ok(_) => session.commit_transaction().await?,
Err(_) => session.abort_transaction().await?,
}
async fn execute_transaction(coll: &Collection<Document>, session: &mut ClientSession) -> Result<()> {
coll.insert_one_with_session(doc! { "x": 1 }, None, session).await?;
coll.delete_one_with_session(doc! { "y": 2 }, None, session).await?;
Ok(())
}
This operation will retry once upon failure if the connection and encountered error support retryability. See the documentation here for more information on retryable writes.
Trait Implementations
sourceimpl Debug for ClientSession
impl Debug for ClientSession
sourceimpl Drop for ClientSession
impl Drop for ClientSession
sourceimpl From<ClientSession> for ClientSession
Available on crate features sync
or tokio-sync
only.
impl From<ClientSession> for ClientSession
sync
or tokio-sync
only.sourcefn from(async_client_session: AsyncClientSession) -> Self
fn from(async_client_session: AsyncClientSession) -> Self
Converts to this type from the input type.
Auto Trait Implementations
impl !RefUnwindSafe for ClientSession
impl Send for ClientSession
impl Sync for ClientSession
impl Unpin for ClientSession
impl !UnwindSafe for ClientSession
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more