Docs Menu
Docs Home
/
Languages
/
Rust
/
Rust Driver
/
Fundamentals
/
Connections

Connection Guide

On this page

  • Overview
  • Connection URI
  • Parts of a Connection URI
  • MongoDB Client
  • Client Creation Methods
  • Connection Example
  • Other Ways to Connect to MongoDB
  • Connect to a MongoDB Server on Your Local Machine
  • Connect to a Replica Set

Overview

In this guide, you can learn how to connect to a MongoDB instance or replica set deployment by using the Rust driver.

This guide includes the following sections:

  • Connection URI describes connection URIs and their constituent parts

  • MongoDB Client describes the Client type and ways to create a client from a connection string

  • Connection Example provides examples that show how to connect to MongoDB by using an Atlas connection string

  • Other Ways to Connect to MongoDB describes ways to connect to MongoDB deployments that are not hosted on Atlas

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.

Parts of a Connection URI

The following example explains each part of a sample connection URI:

Parts of a connection URI

In this example, we use mongodb for the protocol, which specifies the Standard Connection String Format. You can also use the DNS Seed List Connection Format if you want more flexibility in your deployment and the ability to change the servers in rotation without reconfiguring clients.

If you are using password-based authentication, the part of the connection string after the protocol contains your username and password. Replace the placeholder for user with your username and pass with your password. If you are using an authentication mechanism that does not require a username and password, omit this part of the connection URI.

The part of the connection string after the credentials specifies the hostname or IP address and port of your MongoDB instance. In the preceding example, we use sample.host as the hostname and 27017 as the port. Replace these values to point to your MongoDB instance.

The last part of the connection string specifies connection and authentication options. In the example, we set two connection options: maxPoolSize=20 and w=majority.

Tip

Connection Options

To learn more about setting connection options, see the guide on Connection Options.

MongoDB Client

To connect to MongoDB, you must create a Client instance. A client manages your connections and runs database commands.

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.

Client Creation Methods

You can create a client that uses your connection string and other client options by passing a ClientOptions object to the with_options() method.

To specify your connection URI, pass it to the parse() method of ClientOptions. To set any other options, set the relevant field of the ClientOptions struct.

If you do not specify any client options, create a client by passing your connection string to the Client::with_uri_str() method.

To learn more about creating a client, see the API documentation for Client and with_options().

Tip

Stable API

You can set the Stable API version as an option to avoid breaking changes when you upgrade to a new server version.

To learn more about the Stable API feature, see the Stable API guide.

Connection Example

The following code shows how you can create a client that uses an Atlas connection string and the Stable API version, connect to MongoDB, and verify that the connection is successful. Select from the Asynchronous API or Synchronous API tabs below for corresponding connection code samples.

Tip

To learn more about asynchronous and synchronous runtimes, see the Asynchronous and Synchronous APIs guide.

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)?;
    // 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(())
}

Tip

Follow the Quick Start guide to retrieve your Atlas connection string.

Note

To learn about connecting to Atlas Serverless, see the Serverless Instance Limitations page to identify the minimum driver version you need.

Other Ways to Connect to MongoDB

If you must connect to a single MongoDB server instance or replica set that is not hosted on Atlas, see the following sections to find out how to connect.

Connect to a MongoDB Server on Your Local Machine

If you must run the MongoDB Server on your local machine for development purposes, you must complete the following:

  1. Follow the Install MongoDB tutorial to install the MongoDB Server on your machine. Select the appropriate installation tutorial for your machine and operating system.

  2. After you complete the installation, start the server.

Important

Always secure your server from malicious attacks. See the Security Checklist for a list of security recommendations.

After you successfully start the MongoDB Server, connect to your local instance by performing the following steps:

  1. Replace the connection string stored in the uri variable in the preceding example with the connection string for your local MongoDB instance.

    If your MongoDB Server is running locally, you can use the following connection string to connect to MongoDB:

    mongodb://localhost:<port>

    In this connection string, <port> is the port number you configured your server to listen for incoming connections.

  2. Run the connection code. If the code executes successfully, you should see the following output in your console:

    Pinged your deployment. You successfully connected to MongoDB!

Tip

See also:

To learn more about connection strings and custom formats, see Connection Strings in the Server manual.

Connect to a Replica Set

A MongoDB replica set deployment is a group of connected instances, or nodes, where the nodes store the same set of data. This configuration of instances provides data redundancy and high data availability.

To connect to a replica set deployment, specify the hostname and port numbers of each instance, separated by commas, and the replica set name as the value of the replicaSet parameter in the connection string.

In the following example, the hostnames are host1, host2, and host3, and the port numbers are all 27017. The replica set name is myRS. The following code shows the connection URI for the replica set with these specifications:

mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS

When connecting to a replica set, the driver takes the following actions by default:

  • Discovers all replica set members when given the address of any one member.

  • Sends operations to the appropriate member, such as instructions to write against the primary node. To learn more about the replica set primary, see Replica Set Primary in the Server manual.

Tip

You are only required to specify one host to connect to a replica set. However, to ensure connectivity when the specified host is unavailable, provide the full list of hosts.

Direct Connection

To force operations on the host designated in the connection URI, specify the directConnection option. Direct connections display the following behavior:

Back

Connections

Next

Connection Options