MongoClient

public class MongoClient
extension MongoClient: Equatable

A MongoDB Client providing a synchronous API.

  • Encoder whose options are inherited by databases derived from this client.

    Declaration

    Swift

    public var encoder: BSONEncoder { get }
  • Decoder whose options are inherited by databases derived from this client.

    Declaration

    Swift

    public var decoder: BSONDecoder { get }
  • The read concern set on this client, or nil if one is not set.

    Declaration

    Swift

    public var readConcern: ReadConcern? { get }
  • The ReadPreference set on this client.

    Declaration

    Swift

    public var readPreference: ReadPreference { get }
  • The write concern set on this client, or nil if one is not set.

    Declaration

    Swift

    public var writeConcern: WriteConcern? { get }
  • Create a new client connection to a MongoDB server. For options that included in both the connection string URI and the MongoClientOptions struct, the final value is set in descending order of priority: the value specified in MongoClientOptions (if non-nil), the value specified in the URI, or the default value if both are unset.

    Throws

    Throws:

    • A MongoError.InvalidArgumentError if the connection string passed in is improperly formatted.
    • A MongoError.InvalidArgumentError if the connection string specifies the use of TLS but libmongoc was not built with TLS support.

    Declaration

    Swift

    public init(_ connectionString: String = "mongodb://localhost:27017", options: MongoClientOptions? = nil) throws

    Parameters

    connectionString

    the connection string to connect to.

    options

    optional MongoClientOptions to use for this client

  • Starts a new ClientSession with the provided options.

    Declaration

    Swift

    public func startSession(options: ClientSessionOptions? = nil) -> ClientSession
  • Starts a new ClientSession with the provided options and passes it to the provided closure. The session is only valid within the body of the closure and will be ended after the body completes.

    Throws

    • RuntimeError.compatibilityError if the deployment does not support sessions.

    Declaration

    Swift

    public func withSession<T>(
        options: ClientSessionOptions? = nil,
        _ sessionBody: (ClientSession) throws -> T
    ) rethrows -> T
  • Run the listDatabases command.

    Throws

    Throws:

    • MongoError.LogicError if the provided session is inactive.
    • EncodingError if an error is encountered while encoding the options to BSON.
    • MongoError.CommandError if options.authorizedDatabases is false and the user does not have listDatabases permissions.

    Declaration

    Swift

    public func listDatabases(
        _ filter: BSONDocument? = nil,
        options: ListDatabasesOptions? = nil,
        session: ClientSession? = nil
    ) throws -> [DatabaseSpecification]

    Parameters

    filter

    Optional Document specifying a filter that the listed databases must pass. This filter can be based on the “name”, “sizeOnDisk”, “empty”, or “shards” fields of the output.

    options

    Optional ListDatabasesOptions specifying options for listing databases.

    session

    Optional ClientSession to use when executing this command.

    Return Value

    A [DatabaseSpecification] containing the databases matching provided criteria.

  • Get a list of MongoDatabases.

    Throws

    Throws:

    • MongoError.LogicError if the provided session is inactive.
    • MongoError.CommandError if options.authorizedDatabases is false and the user does not have listDatabases permissions.

    Declaration

    Swift

    public func listMongoDatabases(
        _ filter: BSONDocument? = nil,
        options: ListDatabasesOptions? = nil,
        session: ClientSession? = nil
    ) throws -> [MongoDatabase]

    Parameters

    filter

    Optional Document specifying a filter on the names of the returned databases.

    options

    Optional ListDatabasesOptions specifying options for listing databases.

    session

    Optional ClientSession to use when executing this command

    Return Value

    An Array of MongoDatabases that match the provided filter.

  • Get a list of names of databases.

    Throws

    Throws:

    • MongoError.LogicError if the provided session is inactive.
    • MongoError.CommandError if options.authorizedDatabases is false and the user does not have listDatabases permissions.

    Declaration

    Swift

    public func listDatabaseNames(
        _ filter: BSONDocument? = nil,
        options: ListDatabasesOptions? = nil,
        session: ClientSession? = nil
    ) throws -> [String]

    Parameters

    filter

    Optional Document specifying a filter on the names of the returned databases.

    options

    Optional ListDatabasesOptions specifying options for listing databases.

    session

    Optional ClientSession to use when executing this command

    Return Value

    A [String] containing names of databases that match the provided filter.

  • Gets a MongoDatabase instance for the given database name. If an option is not specified in the optional MongoDatabaseOptions param, the database will inherit the value from the parent client or the default if the client’s option is not set. To override an option inherited from the client (e.g. a read concern) with the default value, it must be explicitly specified in the options param (e.g. ReadConcern.serverDefault, not nil).

    Declaration

    Swift

    public func db(_ name: String, options: MongoDatabaseOptions? = nil) -> MongoDatabase

    Parameters

    name

    the name of the database to retrieve

    options

    Optional MongoDatabaseOptions to use for the retrieved database

    Return Value

    a MongoDatabase corresponding to the provided database name

  • Starts a ChangeStream on a MongoClient. Allows the client to observe all changes in a cluster - excluding system collections and the “config”, “local”, and “admin” databases.

    Throws

    Throws:

    • MongoError.CommandError if an error occurs on the server while creating the change stream.
    • MongoError.InvalidArgumentError if the options passed formed an invalid combination.
    • MongoError.InvalidArgumentError if the _id field is projected out of the change stream documents by the pipeline.

    Note

    Supported in MongoDB version 4.0+ only.

    Declaration

    Swift

    public func watch(
        _ pipeline: [BSONDocument] = [],
        options: ChangeStreamOptions? = nil,
        session: ClientSession? = nil
    ) throws -> ChangeStream<ChangeStreamEvent<BSONDocument>>

    Parameters

    pipeline

    An array of aggregation pipeline stages to apply to the events returned by the change stream.

    options

    An optional ChangeStreamOptions to use when constructing the change stream.

    session

    An optional ClientSession to use with this change stream.

    Return Value

    a ChangeStream on all collections in all databases in a cluster.

  • Starts a ChangeStream on a MongoClient. Allows the client to observe all changes in a cluster - excluding system collections and the “config”, “local”, and “admin” databases. Associates the specified Codable type T with the fullDocument field in the ChangeStreamEvents emitted by the returned ChangeStream.

    Throws

    Throws:

    • MongoError.CommandError if an error occurs on the server while creating the change stream.
    • MongoError.InvalidArgumentError if the options passed formed an invalid combination.
    • MongoError.InvalidArgumentError if the _id field is projected out of the change stream documents by the pipeline.

    Note

    Supported in MongoDB version 4.0+ only.

    Declaration

    Swift

    public func watch<FullDocType: Codable>(
        _ pipeline: [BSONDocument] = [],
        options: ChangeStreamOptions? = nil,
        session: ClientSession? = nil,
        withFullDocumentType _: FullDocType.Type
    ) throws -> ChangeStream<ChangeStreamEvent<FullDocType>>

    Parameters

    pipeline

    An array of aggregation pipeline stages to apply to the events returned by the change stream.

    options

    An optional ChangeStreamOptions to use when constructing the change stream.

    session

    An optional ClientSession to use with this change stream.

    withFullDocumentType

    The type that the fullDocument field of the emitted ChangeStreamEvents will be decoded to.

    Return Value

    A ChangeStream on all collections in all databases in a cluster.

  • Starts a ChangeStream on a MongoClient. Allows the client to observe all changes in a cluster - excluding system collections and the “config”, “local”, and “admin” databases. Associates the specified Codable type T with the returned ChangeStream.

    Throws

    Throws:

    • MongoError.CommandError if an error occurs on the server while creating the change stream.
    • MongoError.InvalidArgumentError if the options passed formed an invalid combination.
    • MongoError.InvalidArgumentError if the _id field is projected out of the change stream documents by the pipeline.

    Note

    Supported in MongoDB version 4.0+ only.

    Declaration

    Swift

    public func watch<EventType: Codable>(
        _ pipeline: [BSONDocument] = [],
        options: ChangeStreamOptions? = nil,
        session: ClientSession? = nil,
        withEventType _: EventType.Type
    ) throws -> ChangeStream<EventType>

    Parameters

    pipeline

    An array of aggregation pipeline stages to apply to the events returned by the change stream.

    options

    An optional ChangeStreamOptions to use when constructing the change stream.

    session

    An optional ClientSession to use with this change stream.

    withEventType

    The type that the entire change stream response will be decoded to and that will be returned when iterating through the change stream.

    Return Value

    A ChangeStream on all collections in all databases in a cluster.

  • Attach a CommandEventHandler that will receive CommandEvents emitted by this client.

    Note: the client stores a weak reference to this handler, so it must be kept alive separately in order for it to continue to receive events.

    Declaration

    Swift

    public func addCommandEventHandler<T>(_ handler: T) where T : CommandEventHandler
  • Attach a callback that will receive CommandEvents emitted by this client.

    Note: if the provided callback captures this client, it must do so weakly. Otherwise, it will constitute a strong reference cycle and potentially result in memory leaks.

    Declaration

    Swift

    public func addCommandEventHandler(_ handlerFunc: @escaping (CommandEvent) -> Void)
  • Attach an SDAMEventHandler that will receive SDAMEvents emitted by this client.

    Note: the client stores a weak reference to this handler, so it must be kept alive separately in order for it to continue to receive events.

    Declaration

    Swift

    public func addSDAMEventHandler<T>(_ handler: T) where T : SDAMEventHandler
  • Attach a callback that will receive SDAMEvents emitted by this client.

    Note: if the provided callback captures this client, it must do so weakly. Otherwise, it will constitute a strong reference cycle and potentially result in memory leaks.

    Declaration

    Swift

    public func addSDAMEventHandler(_ handlerFunc: @escaping (SDAMEvent) -> Void)
  • Declaration

    Swift

    public static func == (lhs: MongoClient, rhs: MongoClient) -> Bool