ClientSession

public final class ClientSession

A MongoDB client session. This class represents a logical session used for ordering sequential operations.

To create a client session, use startSession or withSession on a MongoClient.

If causalConsistency is not set to false when starting a session, read and write operations that use the session will be provided causal consistency guarantees depending on the read and write concerns used. Using “majority” read and write preferences will provide the full set of guarantees. See https://docs.mongodb.com/manual/core/read-isolation-consistency-recency/#sessions for more details.

e.g.

   let opts = CollectionOptions(readConcern: ReadConcern(.majority), writeConcern: try WriteConcern(w: .majority))
   let collection = database.collection("mycoll", options: opts)
   let futureCount = client.withSession { session in
       collection.insertOne(["x": 1], session: session).flatMap { _ in
           collection.countDocuments(session: session)
       }
   }

To disable causal consistency, set causalConsistency to false in the ClientSessionOptions passed in to either withSession or startSession.

  • The client used to start this session.

    Declaration

    Swift

    public let client: MongoClient
  • The most recent cluster time seen by this session. This value will be nil if either of the following are true:

    • No operations have been executed using this session and advanceClusterTime has not been called.
    • This session has been ended.

    Declaration

    Swift

    public var clusterTime: Document? { get }
  • The operation time of the most recent operation performed using this session. This value will be nil if either of the following are true:

    • No operations have been performed using this session and advanceOperationTime has not been called.
    • This session has been ended.

    Declaration

    Swift

    public var operationTime: Timestamp? { get }
  • The options used to start this session.

    Declaration

    Swift

    public let options: ClientSessionOptions?
  • Ends this ClientSession. Call this method when you are finished using the session. You must ensure that all operations using this session have completed before calling this. The returned future must be fulfilled before this session’s parent MongoClient is closed.

    Declaration

    Swift

    public func end() -> EventLoopFuture<Void>
  • Advances the clusterTime for this session to the given time, if it is greater than the current clusterTime. If the session has been ended, or if the provided clusterTime is less than the current clusterTime, this method has no effect.

    Declaration

    Swift

    public func advanceClusterTime(to clusterTime: Document)

    Parameters

    clusterTime

    The session’s new cluster time, as a Document like ["cluster time": Timestamp(...)]

  • Advances the operationTime for this session to the given time if it is greater than the current operationTime. If the session has been ended, or if the provided operationTime is less than the current operationTime, this method has no effect.

    Declaration

    Swift

    public func advanceOperationTime(to operationTime: Timestamp)

    Parameters

    operationTime

    The session’s new operationTime

  • Starts a multi-document transaction for all subsequent operations in this session. Any options provided in options override the default transaction options for this session and any options inherited from MongoClient. The transaction must be completed with commitTransaction or abortTransaction. An in-progress transaction is automatically aborted when ClientSession.end() is called.

    Declaration

    Swift

    public func startTransaction(options: TransactionOptions? = nil) -> EventLoopFuture<Void>

    Parameters

    options

    The options to use when starting this transaction

    Return Value

    An EventLoopFuture<Void> that succeeds when startTransaction is successful.

    If the future fails, the error is likely one of the following:

    • CommandError if an error occurs that prevents the command from executing.
    • LogicError if the session already has an in-progress transaction.
    • LogicError if startTransaction is called on an ended session.
  • Commits a multi-document transaction for this session. Server and network errors are not ignored.

    Declaration

    Swift

    public func commitTransaction() -> EventLoopFuture<Void>

    Return Value

    An EventLoopFuture<Void> that succeeds when commitTransaction is successful.

    If the future fails, the error is likely one of the following:

    • CommandError if an error occurs that prevents the command from executing.
    • LogicError if the session has no in-progress transaction.
    • LogicError if commitTransaction is called on an ended session.
  • Aborts a multi-document transaction for this session. Server and network errors are ignored.

    Declaration

    Swift

    public func abortTransaction() -> EventLoopFuture<Void>

    Return Value

    An EventLoopFuture<Void> that succeeds when abortTransaction is successful.

    If the future fails, the error is likely one of the following:

    • LogicError if the session has no in-progress transaction.
    • LogicError if abortTransaction is called on an ended session.