On this page
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
Clienttype 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
A connection URI, also known as a connection string, tells the driver how to connect to MongoDB and how to behave while connected.
The following example explains each part of a sample 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
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:
To learn more about setting connection options, see the guide on Connection Options.
To connect to MongoDB, you must create a
Client instance. A
client manages your connections and runs database commands.
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.
You can create a client that uses your connection string and other
client options by passing a
ClientOptions object to the
To specify your connection URI, pass it to the
ClientOptions. To set any other
options, set the relevant field of the
If you do not specify any client options, create a client by passing your
connection string to the
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.
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.
To learn more about asynchronous and synchronous runtimes, see the Asynchronous and Synchronous APIs guide.
Follow the Quick Start guide to retrieve your Atlas connection string.
To learn about connecting to Atlas Serverless, see the Serverless Instance Limitations page to identify the minimum driver version you need.
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.
If you must run the MongoDB Server on your local machine for development purposes, you must complete the following:
Follow the Install MongoDB tutorial to install the MongoDB Server on your machine. Select the appropriate installation tutorial for your machine and operating system.
After you complete the installation, start the server.
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:
Replace the connection string stored in the
urivariable 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:
In this connection string,
<port>is the port number you configured your server to listen for incoming connections.
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!
To learn more about connection strings and custom formats, see Connection Strings in the Server manual.
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
replicaSet parameter in the connection string.
In the following example, the hostnames are
host3, and the port numbers are all
27017. The replica set name
myRS. The following code shows the connection URI for the replica
set with these specifications:
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.
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.
To force operations on the host designated in the connection URI,
directConnection option. Direct connections display the
They don't support SRV strings.
They fail on writes when the specified host is not the primary.
They require you to specify a secondary read preference when the specified host isn't the primary member. To learn more about these replica set members, see Replica Set Secondary Members in the Server manual.