Struct mongodb::Client

pub struct Client { /* private fields */ }

This is the main entry point for the API. A Client is used to connect to a MongoDB cluster. By default, it will monitor the topology of the cluster, keeping track of any changes, such as servers being added or removed.

Client uses std::sync::Arc internally, so it can safely be shared across threads or async tasks. For example:

let client = Client::with_uri_str("mongodb://example.com").await?;

for i in 0..5 {
    let client_ref = client.clone();

    task::spawn(async move {
        let collection = client_ref.database("items").collection::<Document>(&format!("coll{}", i));

        // Do something with the collection
    });
}

Notes on performance

Spawning many asynchronous tasks that use the driver concurrently like this is often the best way to achieve maximum performance, as the driver is designed to work well in such situations.

Additionally, using a custom Rust type that implements Serialize and Deserialize as the generic parameter of Collection instead of bson::Document can reduce the amount of time the driver and your application spends serializing and deserializing BSON, which can also lead to increased performance.

TCP Keepalive

TCP keepalive is enabled by default with tcp_keepalive_time set to 120 seconds. The driver does not set tcp_keepalive_intvl. See the MongoDB Diagnostics FAQ keepalive section for instructions on setting these values at the system level.

Clean shutdown

Because Rust has no async equivalent of Drop, values that require server-side cleanup when dropped spawn a new async task to perform that cleanup. This can cause two potential issues:

• Drop tasks pending or in progress when the async runtime shuts down may not complete, causing server-side resources to not be freed.
• Drop tasks may run at an arbitrary time even after no Client values exist, making it hard to reason about associated resources (e.g. event handlers).

To address these issues, we highly recommend you use Client::shutdown in the termination path of your application. This will ensure that outstanding resources have been cleaned up and terminate internal worker tasks before returning. Please note that shutdown will wait for all outstanding resource handles to be dropped, so they must either have been dropped before calling shutdown or in a concurrent task; see the documentation of shutdown for more details.

Implementations

impl Client

pub async fn with_uri_str(uri: impl AsRef<str>) -> Result<Self>

Creates a new Client connected to the cluster specified by uri. uri must be a valid MongoDB connection string.

See the documentation on ClientOptions::parse for more details.

pub fn with_options(options: ClientOptions) -> Result<Self>

Creates a new Client connected to the cluster specified by options.

pub fn selection_criteria(&self) -> Option<&SelectionCriteria>

Gets the default selection criteria the Client uses for operations..

pub fn read_concern(&self) -> Option<&ReadConcern>

Gets the default read concern the Client uses for operations.

pub fn write_concern(&self) -> Option<&WriteConcern>

Gets the default write concern the Client uses for operations.

pub fn database(&self, name: &str) -> Database

Gets a handle to a database specified by name in the cluster the Client is connected to. The Database options (e.g. read preference and write concern) will default to those of the Client.

This method does not send or receive anything across the wire to the database, so it can be used repeatedly without incurring any costs from I/O.

pub fn database_with_options( &self, name: &str, options: DatabaseOptions ) -> Database

Gets a handle to a database specified by name in the cluster the Client is connected to. Operations done with this Database will use the options specified by options by default and will otherwise default to those of the Client.

This method does not send or receive anything across the wire to the database, so it can be used repeatedly without incurring any costs from I/O.

pub fn default_database(&self) -> Option<Database>

Gets a handle to the default database specified in the ClientOptions or MongoDB connection string used to construct this Client.

If no default database was specified, None will be returned.

pub async fn list_databases( &self, filter: impl Into<Option<Document>>, options: impl Into<Option<ListDatabasesOptions>> ) -> Result<Vec<DatabaseSpecification>>

Gets information about each database present in the cluster the Client is connected to.

pub async fn list_databases_with_session( &self, filter: impl Into<Option<Document>>, options: impl Into<Option<ListDatabasesOptions>>, session: &mut ClientSession ) -> Result<Vec<DatabaseSpecification>>

Gets information about each database present in the cluster the Client is connected to using the provided ClientSession.

pub async fn list_database_names( &self, filter: impl Into<Option<Document>>, options: impl Into<Option<ListDatabasesOptions>> ) -> Result<Vec<String>>

Gets the names of the databases present in the cluster the Client is connected to.

pub async fn start_session( &self, options: impl Into<Option<SessionOptions>> ) -> Result<ClientSession>

Starts a new ClientSession.

pub async fn watch( &self, pipeline: impl IntoIterator<Item = Document>, options: impl Into<Option<ChangeStreamOptions>> ) -> Result<ChangeStream<ChangeStreamEvent<Document>>>

Starts a new ChangeStream that receives events for all changes in the cluster. The stream does not observe changes from system collections or the “config”, “local” or “admin” databases. Note that this method (watch on a cluster) is only supported in MongoDB 4.0 or greater.

See the documentation here on change streams.

Change streams require either a “majority” read concern or no read concern. Anything else will cause a server error.

Note that using a $project stage to remove any of the _id operationType or ns fields will cause an error. The driver requires these fields to support resumability. For more information on resumability, see the documentation for ChangeStream

If the pipeline alters the structure of the returned events, the parsed type will need to be changed via ChangeStream::with_type.

pub async fn watch_with_session( &self, pipeline: impl IntoIterator<Item = Document>, options: impl Into<Option<ChangeStreamOptions>>, session: &mut ClientSession ) -> Result<SessionChangeStream<ChangeStreamEvent<Document>>>

Starts a new SessionChangeStream that receives events for all changes in the cluster using the provided ClientSession. See Client::watch for more information.

pub async fn shutdown(self)

Shut down this Client, terminating background thread workers and closing connections. This will wait for any live handles to server-side resources (see below) to be dropped and any associated server-side operations to finish.

IMPORTANT: Any live resource handles that are not dropped will cause this method to wait indefinitely. It’s strongly recommended to structure your usage to avoid this, e.g. by only using those types in shorter-lived scopes than the Client. If this is not possible, see shutdown_immediate. For example:

async fn upload_data(bucket: &GridFsBucket) {
  let stream = bucket.open_upload_stream("test", None);
   // .. write to the stream ..
}

let client = Client::with_uri_str("mongodb://example.com").await?;
let bucket = client.database("test").gridfs_bucket(None);
upload_data(&bucket).await;
client.shutdown().await;
// Background cleanup work from `upload_data` is guaranteed to have run.

If the handle is used in the same scope as shutdown, explicit drop may be needed:

let client = Client::with_uri_str("mongodb://example.com").await?;
let bucket = client.database("test").gridfs_bucket(None);
let stream = bucket.open_upload_stream("test", None);
// .. write to the stream ..
drop(stream);
client.shutdown().await;
// Background cleanup work for `stream` is guaranteed to have run.

Calling any methods on clones of this Client or derived handles after this will return errors.

Handles to server-side resources are Cursor, SessionCursor, Session, or GridFsUploadStream.

pub async fn shutdown_immediate(self)

Shut down this Client, terminating background thread workers and closing connections. This does not wait for other pending resources to be cleaned up, which may cause both client-side errors and server-side resource leaks. Calling any methods on clones of this Client or derived handles after this will return errors.

let client = Client::with_uri_str("mongodb://example.com").await?;
let bucket = client.database("test").gridfs_bucket(None);
let stream = bucket.open_upload_stream("test", None);
// .. write to the stream ..
client.shutdown_immediate().await;
// Background cleanup work for `stream` may or may not have run.

pub async fn warm_connection_pool(&self)

Add connections to the connection pool up to min_pool_size. This is normally not needed - the connection pool will be filled in the background, and new connections created as needed up to max_pool_size. However, it can sometimes be preferable to pay the (larger) cost of creating new connections up-front so that individual operations execute as quickly as possible.

Note that topology changes require rebuilding the connection pool, so this method cannot guarantee that the pool will always be filled for the lifetime of the Client.

Does nothing if min_pool_size is unset or zero.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.