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 = MongoCollectionOptions(readConcern: .majority, writeConcern: .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.

See also

Show on GitHub

  • The client used to start this session.

    Declaration

    Swift

    public let client: MongoClient
    Show on GitHub

  • The EventLoop this ClientSession is bound to.

    Declaration

    Swift

    public let eventLoop: EventLoop?
    Show on GitHub

  • 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: BSONDocument? { get }
    Show on GitHub

  • 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: BSONTimestamp? { get }
    Show on GitHub

  • The options used to start this session.

    Declaration

    Swift

    public let options: ClientSessionOptions?
    Show on GitHub

  • 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. You must ensure to hold a reference to this session until the returned future is fulfilled, and the future must be fulfilled before the session’s parent MongoClient is closed.

    Note: on Swift versions and platforms where structured concurrency is available, this method will be called automatically upon deinitialization and does not need to be called by the user.

    Declaration

    Swift

    public func end() -> EventLoopFuture<Void>
    Show on GitHub

  • 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: BSONDocument)

    Parameters

    clusterTime

    The session’s new cluster time, as a BSONDocument like ["cluster time": Timestamp(...)]
    Show on GitHub

  • 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: BSONTimestamp)

    Parameters

    operationTime

    The session’s new operationTime
    Show on GitHub

  • Starts a multi-document transaction for all subsequent operations in this session.

    Any options provided in options will override the default transaction options for this session and any options inherited from MongoClient.

    Operations executed as part of the transaction will use the options specified on the transaction, and those options cannot be overridden at a per-operation level. Any options that overlap with the transaction options which can be specified at a per operation level (e.g. write concern) will be ignored if specified. This includes options specified at the database or collection level on the object used to execute an operation.

    The transaction must be completed with commitTransaction or abortTransaction. An in-progress transaction is automatically aborted when ClientSession.end() is called.

    See also

    SeeAlso:

    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:

    Show on GitHub

  • Commits a multi-document transaction for this session. Server and network errors are not ignored.

    See also

    SeeAlso:

    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:

    Show on GitHub

  • Aborts a multi-document transaction for this session. Server and network errors are ignored.

    See also

    SeeAlso:

    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:

    Show on GitHub

  • Starts a multi-document transaction for all subsequent operations in this session.

    Any options provided in options will override the default transaction options for this session and any options inherited from MongoClient.

    Operations executed as part of the transaction will use the options specified on the transaction, and those options cannot be overridden at a per-operation level. Any options that overlap with the transaction options which can be specified at a per operation level (e.g. write concern) will be ignored if specified. This includes options specified at the database or collection level on the object used to execute an operation.

    The transaction must be completed with commitTransaction or abortTransaction. An in-progress transaction is automatically aborted if the session goes out of scope before commitTransaction is called.

    Throws

    Throws:

    See also

    SeeAlso:

    Declaration

    Swift

    public func startTransaction(options: TransactionOptions? = nil) async throws

    Parameters

    options

    The options to use when starting this transaction.
    Show on GitHub
  • commitTransaction() Asynchronous

    Commits a multi-document transaction for this session. Server and network errors are not ignored.

    Throws

    Throws:

    See also

    SeeAlso:

    Declaration

    Swift

    public func commitTransaction() async throws
    Show on GitHub
  • abortTransaction() Asynchronous

    Aborts a multi-document transaction for this session. Server and network errors are ignored.

    Throws

    Throws:

    See also

    SeeAlso:

    Declaration

    Swift

    public func abortTransaction() async throws
    Show on GitHub