/ /

Create a MongoDB Client

Overview

To connect to a MongoDB deployment, you need two things:

Connection URI, also known as a connection string, which tells the Rust driver which MongoDB deployment to connect to.
Client instance, which creates the connection to the MongoDB deployment and lets you perform operations on it.

You can also use either of these components to customize the way the Rust driver behaves while connected to MongoDB.

This guide shows you how to create a connection string and use a Client instance to connect to MongoDB.

Connection URI

A connection URI, also known as a connection string, tells the driver how to connect to MongoDB and how to behave while connected.

A standard connection string includes the following components:

Component	Description
`mongodb://`	Required. A prefix that identifies this as a string in the standard connection format.
`<db_username>:<db_password>`	Optional. Authentication credentials. If you include these, the client authenticates the user against the database specified in `authSource`. For more information about the `authSource` connection option, see the Authentication Mechanisms guide.
`hostname[:port]`	Required. The hostname and optional port number where MongoDB is running. If you don't include the port number, the driver uses the default port, `27017`.
`/defaultauthdb`	Optional. The authentication database to use if the connection string includes authentication credentials but not the `authSource` option.
`?<options>`	Optional. A query string that specifies connection-specific options as `<name>=<value>` pairs. See the Specify Connection Options guide for a full description of these options.

For more information about creating a connection string, see Connection Strings in the MongoDB Server documentation.

Create a MongoDB Client

A client manages your connections and runs database commands. To create a Client instance, pass your connection string to the Client::with_uri_str() method, as shown in the following example:

let client = Client::with_uri_str(uri)?;

Specify Connection Options

You can specify connection options when creating a client by passing a ClientOptions object to the with_options() method.

You can also specify connection options in your connection string by passing your connection string to the parse() method of a ClientOptions struct.

The following code examples show how you can create a client, specify a Stable API connection option, connect to MongoDB, and verify that the connection is successful. Select the Asynchronous API or Synchronous API tab below for the corresponding code example:

use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, Client };
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    // Replace the placeholder with your Atlas connection string
    let uri = "<connection string>";
    let mut client_options = ClientOptions::parse(uri).await?;
    // Set the server_api field of the client_options object to Stable API version 1
    let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
    client_options.server_api = Some(server_api);
    // Create a new client and connect to the server
    let client = Client::with_options(client_options)?;
    // Send a ping to confirm a successful connection
    client.database("admin").run_command(doc! { "ping": 1 }).await?;
    println!("Pinged your deployment. You successfully connected to MongoDB!");
    Ok(())
}

use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, sync::Client };
fn main() -> mongodb::error::Result<()> {
    // Replace the placeholder with your Atlas connection string
    let uri = "<connection string>";
    let mut client_options = ClientOptions::parse(uri).run()?;
    // Set the server_api field of the client_options object to Stable API version 1
    let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
    client_options.server_api = Some(server_api);
    // Create a new client and connect to the server
    let client = Client::with_options(client_options)?;
    // Send a ping to confirm a successful connection
    client.database("admin").run_command(doc! { "ping": 1 }).run()?;
    println!("Pinged your deployment. You successfully connected to MongoDB!");
    Ok(())
}

For more information about available connection options, see the Specify Connection Options guide.

Tip

Reuse Your Client

You can improve performance by reusing your client across sessions and operations. You can use the same Client instance to perform multiple tasks, instead of creating a new one each time. The Client type is safe for concurrent use by multiple threads or async tasks.

API Documentation

To learn more about using the Rust driver to create a Client instance, see the following API documentation:

Back

Get Started

Choose a Connection Target