Docs Menu
Docs Home
/
MongoDB Atlas
/

Connect to Your Cluster

On this page

  • Required Access
  • Prerequisites
  • Connect to Your Atlas Cluster
  • Next Steps

Estimated completion time: 5 minutes

You can connect to your cluster in a variety of ways. In this tutorial, you use one of the following methods:

➤ Use the Select your language drop-down menu to set the connection method for this tutorial, including mongosh and Compass.

Note

If you're using the atlas setup or atlas quickstart commands with default options to get started with Atlas, the Atlas CLI provides you with a mongosh command to connect to your cluster.

To connect to a cluster, you must be a database user.

Before you start, verify that you have:

To download and install mongosh:

1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Click Connect for the cluster to which you want to connect.

3
4

Select your operating system from the dropdown.

5
  • If you are using Windows or Linux, download using one of the following options:

    • Click Download mongosh to begin the download.

    • Click Copy download URL to copy a download URL to your clipboard, then either:

      • Use curl to fetch the installer file, or

      • Paste the URL in a browser window.

  • If you are using macOS, you can use the provided Homebrew command to download the shell.

6

Select the appropriate tab based on your operating system:

  1. Download using one of the following options:

    • Click Download mongosh to begin the download.

    • Click Copy download URL to copy a download URL to your clipboard, then either:

      • Use curl to fetch the installer file from the URL, or

      • Paste the URL in a browser window.

  2. Extract the files from the downloaded archive.

  3. Add the mongosh binary to your PATH environment variable.

    Ensure that the extracted MongoDB Shell binary is in the desired location in your filesystem, then add that location to your PATH environment variable.

    1. Open the Control Panel.

    2. In the System and Security category, click System.

    3. Click Advanced system settings. The System Properties modal displays.

    4. Click Environment Variables.

    5. Select Path and click Edit.

    6. Click New and add the filepath to your mongosh binary.

  1. Use the Homebrew command provided.

  2. Copy the Homebrew command from the Atlas UI window and run it in a terminal.

  1. Download the installer using one of the following options:

    • Click Download mongosh to begin the download.

    • Click Copy download URL to copy a download URL to your clipboard, then either:

      • Use curl to fetch the installer file from the URL, or

      • Paste the URL in a browser window.

    Note

    The type of file you download depends on the operating system you selected. If you select a version of:

    • Ubuntu or Debian you receive a .deb package.

    • RHEL, Amazon Linux, or SUSE you receive an .rpm package.

    If your operating system isn't listed, see the .tgz installation instructions in the mongosh documentation.

  2. Install the mongosh package.

    Use dpkg to install mongosh:

    sudo dpkg -i mongodb-mongosh_<mongosh-version-and-platform>.deb

    Use rpm to install mongosh:

    sudo rpm -i mongodb-mongosh_<mongosh-version-and-platform>.rpm

You should now be able to run mongosh using your terminal.

7

To see if you have correctly added mongosh to your system path, run the following command in your terminal:

mongosh --version

You should see an output similar to the following:

0.14.0

To download and install MongoDB Compass:

1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Click Connect for the cluster to which you want to connect.

3

From the Connect Modal, click Compass.

4

Click I do not have MongoDB Compass. Select your operating system from the dropdown.

5
6
  • A terminal.

  • A text editor.

  • Go

  • A Go project. To initialize a project, use the go mod command. To learn more, see Go Quick Start.

To configure Maven or Gradle to build and run your project, see Add MongoDB as a Dependency.

To install the Node.js driver, run the following command at a terminal prompt:

npm install mongodb --save

To install the Python driver, called PyMongo:

1
2

Run the following command in your terminal:

python -m pip install "pymongo[snappy,gssapi,srv,tls]"

This command installs the PyMongo driver and a few dependencies for the driver. To learn more, see the Python Driver Installation Page on GitHub.

3

Test your PyMongo installation to ensure you can successfully connect to your cluster.

  1. Run the following command to open the Python shell:

    python
  2. Import PyMongo by running the following command in the Python shell:

    import pymongo
  3. Check your PyMongo version using the following command:

    pymongo.version

    If PyMongo is correctly installed, you should see an output similar to the following:

    '3.11.0'

In this section, you get your cluster's connection string from the Atlas UI and connect to your cluster by using your preferred connection method.

To learn about all supported methods, see Connect to Your Cloud Cluster. For additional driver examples, see Connect via Drivers.

1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Click Connect for the cluster to which you want to connect.

3

From the Connect Modal, click Shell.

4
5

This is a unique connection string specific to your Atlas cluster. Atlas replaces the username of the connection string with the username of the database user you created earlier in this procedure.

6
7

When prompted, enter your database user's password. You will be prompted to enter the password you specified when you created your database user in Atlas.

You should now be connected to your Atlas cluster within the mongosh. Your terminal should display something similar to the following:

MongoDB Enterprise GettingStarted-shard-0:PRIMARY>

Important

Connection Troubleshooting

If you are having trouble connecting to your cluster, double check that you have added your IP address to your IP access list and that you are specifying the correct database user credentials. If you have forgotten your database user credentials, you can always create a new database user.

1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Click Connect for the cluster to which you want to connect.

3
  1. Click I have MongoDB Compass.

  2. Choose your version of MongoDB Compass in the dropdown. To check the version of MongoDB Compass that you have installed on your system, click About MongoDB Compass in the application.

  3. Copy the connection string presented in the Atlas Connect dialog box.

4

Use the copied connection string for connecting to MongoDB Compass if your deployment uses a single cloud provider or doesn't use any of the following: SSL, authentication certificates, or an SSH tunnel.

  1. Click New Connection and paste the connection string into the Paste your connection string field.

  2. (Optional) To save this connection for future use, click Create Favorite and add a name for this connection. You can find saved favorite connections under Favorites in the left pane of the MongoDB Compass Connect window.

  3. Click Connect.

Fill in connection fields individually if your deployment spans more than one cloud provider or if it uses one of the following: SSL, authentication certificates, or an SSH tunnel.

  1. Click Fill in Connection Fields Individually.

  2. Under the hostname tab, enter the hostname and port, and choose your authentication mechanism from the dropdown.

  3. Under the More options tab, configure the following:

    To learn more, see Connect to MongoDB in the MongoDB Compass documentation.

  4. (Optional) To save this connection for future use, click Create Favorite and add a name for this connection. You can find saved favorite connections under Favorites in the left pane of the MongoDB Compass Connect window.

  5. Click Connect.

1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Click Connect for the cluster to which you want to connect.

3

From the Connect Modal, click Drivers.

4

Select your version of the driver from the dropdown. The connection string displays.

5
6

Replace <password> with the password specified when you created your database user.

Note

If your passwords, database names, or connection strings contain reserved URI characters, you must escape the characters. For example, if your password is @bc123, you must escape the @ character when specifying the password in the connection string, such as %40bc123. To learn more, see Special Characters in Connection String Password.

7

The following sample application connects to your Atlas cluster with your connection string and sends a ping to confirm a successful connection. To test the sample application:

  1. Create a new directory called connect and initialize your project by using the dotnet new command.

    mkdir connect
    cd connect
    dotnet new console
  2. Run the following command to add the .NET/C# Driver to your project as a dependency:

    dotnet add package MongoDB.Driver
  3. Replace the contents of the Program.cs file with the following code. Make sure to replace the placeholder with your updated connection string:

    1using MongoDB.Bson;
    2using MongoDB.Driver;
    3
    4public class Connect
    5{
    6 // Replace the following with your Atlas connection string
    7 private const string MongoConnectionString = "mongodb+srv://<db_username>:<db_password>@<clusterName>.mongodb.net/?retryWrites=true&w=majority";
    8
    9 public static void Main(string[] args)
    10 {
    11 // Connect to your Atlas cluster
    12 var client = new MongoClient(MongoConnectionString);
    13
    14 // Send a ping to confirm a successful connection
    15 try {
    16 var result = client.GetDatabase("admin").RunCommand<BsonDocument>(new BsonDocument("ping", 1));
    17 Console.WriteLine("Successfully connected to Atlas");
    18 }
    19 catch (Exception e) { Console.WriteLine(e);}
    20 }
    21}
  4. To run your application, use the following command:

    dotnet run Program.cs
    Successfully connected to Atlas
1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Click Connect for the cluster to which you want to connect.

3

From the Connect Modal, click Drivers.

4

Select your version of the driver from the dropdown. The connection string displays.

5
6

Replace <password> with the password specified when you created your database user.

Note

If your passwords, database names, or connection strings contain reserved URI characters, you must escape the characters. For example, if your password is @bc123, you must escape the @ character when specifying the password in the connection string, such as %40bc123. To learn more, see Special Characters in Connection String Password.

7

The following sample application connects to your Atlas cluster with your connection string and sends a ping to confirm a successful connection. To test the sample application:

  1. Create a new directory called connect and initialize your project by using the go mod command.

    mkdir connect
    cd connect
    go mod init connect
  2. Run the following commands to download the Go driver and driver dependencies:

    go get go.mongodb.org/mongo-driver/mongo
    go get github.com/joho/godotenv
  3. In your project, create a new file called connect.go and paste the following code. Make sure to replace the placeholder with your updated connection string:

    1package main
    2
    3import (
    4 "context"
    5 "fmt"
    6
    7 "go.mongodb.org/mongo-driver/bson"
    8 "go.mongodb.org/mongo-driver/mongo"
    9 "go.mongodb.org/mongo-driver/mongo/options"
    10)
    11
    12func main() {
    13
    14 // Replace the following with your Atlas connection string
    15 uri := "mongodb+srv://<db_username>:<db_password>@<clusterName>.mongodb.net/?retryWrites=true&w=majority"
    16
    17 // Connect to your Atlas cluster
    18 client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))
    19 if err != nil {
    20 panic(err)
    21 }
    22 defer client.Disconnect(context.TODO())
    23
    24 // Send a ping to confirm a successful connection
    25 var result bson.M
    26 if err := client.Database("admin").RunCommand(context.TODO(), bson.D{{"ping", 1}}).Decode(&result); err != nil {
    27 panic(err)
    28 }
    29 fmt.Println("Successfully connected to Atlas")
    30}
  4. To run your application, use the following command:

    go run connect.go
    Successfully connected to Atlas
1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Click Connect for the cluster to which you want to connect.

3

From the Connect Modal, click Drivers.

4

Select your version of the driver from the dropdown. The connection string displays.

5
6

Replace <password> with the password specified when you created your database user.

Note

If your passwords, database names, or connection strings contain reserved URI characters, you must escape the characters. For example, if your password is @bc123, you must escape the @ character when specifying the password in the connection string, such as %40bc123. To learn more, see Special Characters in Connection String Password.

7

The following sample application connects to your Atlas cluster with your connection string and sends a ping to confirm a successful connection. To test the sample application, copy the following code into a file called Connect.java.

Replace the placeholder with your updated connection string:

1import com.mongodb.*;
2import org.bson.BsonDocument;
3import org.bson.BsonInt64;
4import org.bson.Document;
5import org.bson.conversions.Bson;
6
7import com.mongodb.client.MongoClient;
8import com.mongodb.client.MongoClients;
9import com.mongodb.client.MongoDatabase;
10
11public class Connect {
12 public static void main(String[] args) {
13 // Replace the placeholder with your Atlas connection string
14 String uri = "mongodb+srv://<db_username>:<db_password>@<clusterName>.mongodb.net/?retryWrites=true&w=majority";
15
16 // Construct a ServerApi instance using the ServerApi.builder() method
17 ServerApi serverApi = ServerApi.builder()
18 .version(ServerApiVersion.V1)
19 .build();
20
21 MongoClientSettings settings = MongoClientSettings.builder()
22 .applyConnectionString(new ConnectionString(uri))
23 .serverApi(serverApi)
24 .build();
25
26 // Create a new client and connect to the server
27 try (MongoClient mongoClient = MongoClients.create(settings)) {
28 MongoDatabase database = mongoClient.getDatabase("admin");
29 try {
30 // Send a ping to confirm a successful connection
31 Bson command = new BsonDocument("ping", new BsonInt64(1));
32 Document commandResult = database.runCommand(command);
33 System.out.println("Successfully connected to Atlas");
34 } catch (MongoException e) {
35 System.err.println(e);
36 }
37 }
38 }
39}

Compile and run the Connect.java file by using an IDE or the following commands:

javac Connect.java
java Connect
Successfully connected to Atlas
1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Click Connect for the cluster to which you want to connect.

3

From the Connect Modal, click Drivers.

4

Select your version of the driver from the dropdown. The connection string displays.

5
6

Replace <password> with the password specified when you created your database user.

Note

If your passwords, database names, or connection strings contain reserved URI characters, you must escape the characters. For example, if your password is @bc123, you must escape the @ character when specifying the password in the connection string, such as %40bc123. To learn more, see Special Characters in Connection String Password.

7

The following sample application connects to your Atlas cluster with your connection string and returns a confirmation message. To test the sample application, copy the following code into a file called connect.js.

Replace the placeholder with your updated connection string:

1const { MongoClient } = require("mongodb");
2
3// Replace the following with your Atlas connection string
4const url = "mongodb+srv://<db_username>:<db_password>@<clusterName>.mongodb.net/?retryWrites=true&w=majority";
5
6// Connect to your Atlas cluster
7const client = new MongoClient(url);
8
9async function run() {
10 try {
11 await client.connect();
12 console.log("Successfully connected to Atlas");
13
14 } catch (err) {
15 console.log(err.stack);
16 }
17 finally {
18 await client.close();
19 }
20}
21
22run().catch(console.dir);

To run the sample application, use the following command:

node connect.js
Successfully connected to Atlas
1
  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Click Connect for the cluster to which you want to connect.

3

From the Connect Modal, click Drivers.

4

The connection string displays.

5
6

Replace <password> with the password specified when you created your database user.

Note

If your passwords, database names, or connection strings contain reserved URI characters, you must escape the characters. For example, if your password is @bc123, you must escape the @ character when specifying the password in the connection string, such as %40bc123. To learn more, see Special Characters in Connection String Password.

7

To connect to a running MongoDB instance, PyMongo requires MongoClient. In the Python shell running in your terminal, run the following command to import MongoClient:

from pymongo import MongoClient
8

Create the command that specifies a client for connecting to your cluster.

  1. In your Python shell, paste your updated connection string into the following command:

    client = MongoClient('<connection-string>')
  2. Update the connection string with your database user password.

  3. Verify that you have enclosed the connection string in single quotes.

  4. Run the resulting command. It specifies a client that will connect to your cluster.

  5. Connect to your cluster using this client.

Now that you've connected to your cluster, proceed to Insert and View Data in Your Cluster.