MongoClient Class Reference


                    
                    
                    encoder

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

Declaration

Swift

public let encoder: BSONEncoder

Show on GitHub


                    
                    
                    decoder

Decoder whose options are inherited by databases derived from this client.

Declaration

Swift

public let decoder: BSONDecoder

Show on GitHub


                    
                    
                    readConcern

The read concern set on this client, or nil if one is not set.

Declaration

Swift

public let readConcern: ReadConcern?

Show on GitHub


                    
                    
                    readPreference

The ReadPreference set on this client.

Declaration

Swift

public let readPreference: ReadPreference

Show on GitHub


                    
                    
                    writeConcern

The write concern set on this client, or nil if one is not set.

Declaration

Swift

public let writeConcern: WriteConcern?

Show on GitHub


                    
                    
                    init(_:using:options:)

Create a new client for a MongoDB deployment. For options that included in both the MongoConnectionString 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.

Declaration

Swift

public init(
    _ connectionString: MongoConnectionString,
    using eventLoopGroup: EventLoopGroup,
    options: MongoClientOptions? = nil
) throws

Parameters

`connectionString`	the `MongoConnectionString` to connect to.
`eventLoopGroup`	A SwiftNIO `EventLoopGroup` which the client will use for executing operations. It is the user’s responsibility to ensure the group remains active for as long as the client does, and to ensure the group is properly shut down when it is no longer in use.
`options`	optional `MongoClientOptions` to use for this client.

Show on GitHub


                    
                    
                    init(_:using:options:)

Create a new client for a MongoDB deployment. 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.

Declaration

Swift

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

Parameters

`connectionString`	the connection string to connect to.
`eventLoopGroup`	A SwiftNIO `EventLoopGroup` which the client will use for executing operations. It is the user’s responsibility to ensure the group remains active for as long as the client does, and to ensure the group is properly shut down when it is no longer in use.
`options`	optional `MongoClientOptions` to use for this client.

Show on GitHub


                    
                    
                    close()

Closes this MongoClient, closing all connections to the server and cleaning up internal state.

Call this method exactly once when you are finished using the client. You must ensure that all operations using the client have completed before calling this.

The returned future will not be fulfilled until all cursors and change streams created from this client have been been killed, and all sessions created from this client have been ended.

The returned future must be fulfilled before the EventLoopGroup provided to this client’s constructor is shut down.

Declaration

Swift

public func close() -> EventLoopFuture<Void>

Show on GitHub


                    
                    
                    syncClose()

Shuts this MongoClient down in a blocking fashion, closing all connections to the server and cleaning up internal state.

Call this method exactly once when you are finished using the client. You must ensure that all operations using the client have completed before calling this. This method will block until all cursors and change streams created from this client have been killed, and all sessions created from this client have been ended.

This method must complete before the EventLoopGroup provided to this client’s constructor is shut down.

Declaration

Swift

public func syncClose() throws

Show on GitHub


                    
                    
                    startSession(options:)

Starts a new ClientSession with the provided options.

This session must be explicitly as an argument to each command that should be executed as part of the session.

ClientSessions are not thread safe so you must ensure the returned session is not used concurrently for multiple operations.

When you are done using this session, you must call ClientSession.end() on it, unless if you are on a platform where structured concurrency is available, in which case the session will be ended automatically when the object is deinitialized. In that case, you must make sure to maintain a reference to this object until all operations using it have completed.

Declaration

Swift

public func startSession(options: ClientSessionOptions? = nil) -> ClientSession

Show on GitHub


                    
                    
                    withSession(options:_:)

Starts a new ClientSession with the provided options and passes it to the provided closure. The session must be explicitly passed as an argument to each command within the closure that should be executed as part of the session.

The session is only valid within the body of the closure and will be ended after the body completes.

ClientSessions are not thread safe so you must ensure the session is not used concurrently for multiple operations.

Declaration

Swift

public func withSession<T>(
    options: ClientSessionOptions? = nil,
    _ sessionBody: (ClientSession) throws -> EventLoopFuture<T>
) -> EventLoopFuture<T>

Parameters

`options`	Options to use when creating the session.
`sessionBody`	A closure which takes in a `ClientSession` and returns an `EventLoopFuture<T>`.

Return Value

An EventLoopFuture<T>, the return value of the user-provided closure.

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

CompatibilityError if the deployment does not support sessions.
MongoError.LogicError if this client has already been closed.

Show on GitHub


                    
                    
                    listDatabases(_:options:session:)

Retrieves a list of databases in this client’s MongoDB deployment.

Declaration

Swift

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

Parameters

`filter`	Optional `BSONDocument` 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

An EventLoopFuture<[DatabaseSpecification]>. On success, the future contains an array of the specifications of databases matching the provided criteria.

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

MongoError.LogicError if the provided session is inactive.
MongoError.LogicError if this client has already been closed.
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.

Show on GitHub


                    
                    
                    listMongoDatabases(_:options:session:)

Get a list of MongoDatabases corresponding to the databases in this client’s MongoDB deployment.

Declaration

Swift

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

Parameters

`filter`	Optional `BSONDocument` 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 EventLoopFuture<[MongoDatabase]>. On success, the future contains an array of MongoDatabases that match the provided filter.

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

MongoError.LogicError if the provided session is inactive.
MongoError.LogicError if this client has already been closed.
MongoError.CommandError if options.authorizedDatabases is false and the user does not have listDatabases permissions.

Show on GitHub


                    
                    
                    listDatabaseNames(_:options:session:)

Get the names of databases in this client’s MongoDB deployment.

Declaration

Swift

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

Parameters

`filter`	Optional `BSONDocument` 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 EventLoopFuture<[String]>. On success, the future contains an array of names of databases that match the provided filter.

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

MongoError.LogicError if the provided session is inactive.
MongoError.LogicError if this client has already been closed.
MongoError.CommandError if options.authorizedDatabases is false and the user does not have listDatabases permissions.

Show on GitHub


                    
                    
                    db(_:options:)

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.

Show on GitHub


                    
                    
                    watch(_:options:session:)

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.

Warning

If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the change stream is dead before it leaves scope, invoke ChangeStream.kill(...) on it.

See also

SeeAlso:

Note

Supported in MongoDB version 4.0+ only.

Declaration

Swift

public func watch(
    _ pipeline: [BSONDocument] = [],
    options: ChangeStreamOptions? = nil,
    session: ClientSession? = nil
) -> EventLoopFuture<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

An EventLoopFuture<ChangeStream>. On success, contains a ChangeStream watching all collections in this deployment.

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

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.

Show on GitHub


                    
                    
                    watch(_:options:session:withFullDocumentType:)

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.

Warning

If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the change stream is dead before it leaves scope, invoke ChangeStream.kill(...) on it.

See also

SeeAlso:

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
) -> EventLoopFuture<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 `ChangeStreamEvent`s will be decoded to.

Return Value

An EventLoopFuture<ChangeStream>. On success, contains a ChangeStream watching all collections in this deployment.

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

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.

Show on GitHub


                    
                    
                    watch(_:options:session:withEventType:)

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.

Warning

If the returned change stream is alive when it goes out of scope, it will leak resources. To ensure the change stream is dead before it leaves scope, invoke ChangeStream.kill(...) on it.

See also

SeeAlso:

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
) -> EventLoopFuture<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

An EventLoopFuture<ChangeStream>. On success, contains a ChangeStream watching all collections in this deployment.

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

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.

Show on GitHub


                    
                    
                    bound(to:)

Returns an EventLoopBoundMongoClient, a wrapper around this MongoClient that will return EventLoopFutures on the specified EventLoop.

Note

This MongoClient must be kept alive in order to use the EventLoopBoundMongoClient.

Declaration

Swift

public func bound(to eventLoop: EventLoop) -> EventLoopBoundMongoClient

Parameters


                                eventLoop

An EventLoop which the returned EventLoopBoundMongoClient will be bound to.

Return Value

An EventLoopBoundMongoClient bound to the specified EventLoop.

Show on GitHub


                    
                    
                    addCommandEventHandler(_:)

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

Show on GitHub


                    
                    
                    addCommandEventHandler(_:)

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)

Show on GitHub


                    
                    
                    addSDAMEventHandler(_:)

Attach an SDAMEventHandler 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 addSDAMEventHandler<T>(_ handler: T) where T : SDAMEventHandler

Show on GitHub


                    
                    
                    addSDAMEventHandler(_:)

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)

Show on GitHub


                    
                    
                    close()

Asynchronous

Closes this MongoClient, closing all connections to the server and cleaning up internal state.

Call this method exactly once when you are finished using the client.

This function will not complete until all cursors and change streams created from this client have been been killed, and all sessions created from this client have been ended.

You must await the result of this method before shutting down the EventLoopGroup provided to this client’s constructor.

Declaration

Swift

public func close() async throws

Show on GitHub


                    
                    
                    withSession(options:_:)

Asynchronous

Starts a new ClientSession with the provided options and passes it to the provided closure. The session must be explicitly passed as an argument to each command within the closure that should be executed as part of the session.

The session is only valid within the body of the closure and will be ended after the body completes.

ClientSessions are not thread safe so you must ensure the session is not used concurrently for multiple operations.

Throws

Throws:

RuntimeError.CompatibilityError if the deployment does not support sessions.

Declaration

Swift

public func withSession<T>(
    options: ClientSessionOptions? = nil,
    _ sessionBody: (ClientSession) async throws -> T
) async throws -> T

Parameters

`options`	Options to use when creating the session.
`sessionBody`	An `async` closure which takes in a `ClientSession` and returns a `T`.

Return Value

A T, the return value of the user-provided closure.

Show on GitHub


                    
                    
                    listDatabases(_:options:session:)

Asynchronous

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
) async throws -> [DatabaseSpecification]

Parameters

`filter`	Optional `BSONDocument` 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.

Show on GitHub


                    
                    
                    listMongoDatabases(_:options:session:)

Asynchronous

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
) async throws -> [MongoDatabase]

Parameters

`filter`	Optional `BSONDocument` 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.

Show on GitHub


                    
                    
                    listDatabaseNames(_:options:session:)

Asynchronous

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
) async throws -> [String]

Parameters

`filter`	Optional `BSONDocument` 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.

Show on GitHub


                    
                    
                    watch(_:options:session:)

Asynchronous

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.

See also

SeeAlso:

Note

Supported in MongoDB version 4.0+ only.

Declaration

Swift

public func watch(
    _ pipeline: [BSONDocument] = [],
    options: ChangeStreamOptions? = nil,
    session: ClientSession? = nil
) async 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.

Show on GitHub


                    
                    
                    watch(_:options:session:withFullDocumentType:)

Asynchronous

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.

See also

SeeAlso:

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
) async 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 `ChangeStreamEvent`s will be decoded to.

Return Value

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

Show on GitHub


                    
                    
                    watch(_:options:session:withEventType:)

Asynchronous

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.

See also

SeeAlso:

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

Show on GitHub


                    
                    
                    ==(_:_:)

Declaration

Swift

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

Show on GitHub