Connect to Your Cluster
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:
The MongoDB Shell, an interactive command line interface to MongoDB. You can use
mongosh
to insert and interact with data on your Atlas cluster.MongoDB Compass, a GUI for your MongoDB data. You can use Compass to explore, modify, and visualize your data.
A MongoDB driver to communicate with your MongoDB database programmatically. To see all supported languages, refer to the MongoDB Driver documentation.
➤ 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.
Required Access
To connect to a cluster, you must be a database user.
Prerequisites
Before you start, verify that you have:
A database user on your cluster.
Note
You must have a database user set up on your cluster to access your deployment. For security purposes, Atlas requires clients to authenticate as database users to access clusters.
A terminal
To download and install mongosh
:
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.
Download the MongoDB Shell.
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, orPaste the URL in a browser window.
Download the installer from the MongoDB Shell page.
If you are using macOS, you can use the provided Homebrew command to download the shell.
Install the MongoDB Shell.
Select the appropriate tab based on your operating system:
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, orPaste the URL in a browser window.
Download the installer from the MongoDB Shell page.
Extract the files from the downloaded archive.
Add the
mongosh
binary to yourPATH
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.Open the Control Panel.
In the System and Security category, click System.
Click Advanced system settings. The System Properties modal displays.
Click Environment Variables.
Select Path and click Edit.
Click New and add the filepath to your
mongosh
binary.
Use the Homebrew command provided.
Copy the Homebrew command from the Atlas UI window and run it in a terminal.
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, orPaste the URL in a browser window.
Download the installer from the MongoDB Shell page.
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.Install the
mongosh
package.
You should now be able to run mongosh
using your terminal.
Test your MongoDB Shell installation.
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:
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.
Click Compass.
From the Connect Modal, click Compass.
Click I do not have MongoDB Compass. Select your operating system from the dropdown.
A terminal.
A text editor.
A C# project. To initialize a project, run the
dotnet new console
command in your project directory. To learn more, see C# Quick Start.
A terminal.
A text editor.
A Go project. To initialize a project, use the
go mod
command. To learn more, see Go Quick Start.
Java Development Kit (JDK) version 8 or later.
The driver dependencies installed by using Maven or Gradle. We recommend using an integrated development environment (IDE) such as IntelliJ IDEA or Eclipse IDE to configure the dependencies.
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
A terminal.
A text editor.
Python. To download the latest version of Python for your operating system, see Python Downloads Page.
The pip package installer. Starting with Python 2.7.9 and Python 3.4, packages downloaded from https://python.org include
pip
. To installpip
manually, see the pip installation page. This package includes Python.
To install the Python driver, called PyMongo:
Install the PyMongo Driver.
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.
Test your PyMongo installation.
Test your PyMongo installation to ensure you can successfully connect to your cluster.
Run the following command to open the Python shell:
python Import PyMongo by running the following command in the Python shell:
import pymongo 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'
Connect to Your Atlas Cluster
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.
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.
Click Shell.
From the Connect Modal, click Shell.
Click I have the MongoDB Shell installed and select your mongosh
version from the drop-down.
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.
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.
Get the Connection String for MongoDB Compass from Atlas.
Click I have MongoDB Compass.
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.
Copy the connection string presented in the Atlas Connect dialog box.
Open MongoDB Compass and Connect to Atlas.
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.
Click New Connection and paste the connection string into the Paste your connection string field.
(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.
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.
Click Fill in Connection Fields Individually.
Under the hostname tab, enter the hostname and port, and choose your authentication mechanism from the dropdown.
Under the More options tab, configure the following:
If your deployment uses SSL or an SSH tunnel, specify SSL or SSH tunnel options.
If your deployment spans more than one cloud provider, specify read preference options.
If your deployment uses X.509 certificates, add a self-managed X.509 certificate or an auto-generated X.509 certificate managed by Atlas.
To learn more, see Connect to MongoDB in the MongoDB Compass documentation.
(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.
Click Connect.
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.
Click Drivers.
From the Connect Modal, click Drivers.
Configure the provided connection string.
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.
Connect with the sample application.
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:
Create a new directory called
connect
and initialize your project by using thedotnet new
command.mkdir connect cd connect dotnet new console Run the following command to add the .NET/C# Driver to your project as a dependency:
dotnet add package MongoDB.Driver Replace the contents of the
Program.cs
file with the following code. Make sure to replace the placeholder with your updated connection string:1 using MongoDB.Bson; 2 using MongoDB.Driver; 3 4 public 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 } To run your application, use the following command:
dotnet run Program.cs Successfully connected to Atlas
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.
Click Drivers.
From the Connect Modal, click Drivers.
Configure the provided connection string.
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.
Connect with the sample application.
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:
Create a new directory called
connect
and initialize your project by using thego mod
command.mkdir connect cd connect go mod init connect 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 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:1 package main 2 3 import ( 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 12 func 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 } To run your application, use the following command:
go run connect.go Successfully connected to Atlas
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.
Click Drivers.
From the Connect Modal, click Drivers.
Configure the provided connection string.
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.
Connect with the sample application.
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:
1 import com.mongodb.*; 2 import org.bson.BsonDocument; 3 import org.bson.BsonInt64; 4 import org.bson.Document; 5 import org.bson.conversions.Bson; 6 7 import com.mongodb.client.MongoClient; 8 import com.mongodb.client.MongoClients; 9 import com.mongodb.client.MongoDatabase; 10 11 public 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
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.
Click Drivers.
From the Connect Modal, click Drivers.
Configure the provided connection string.
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.
Connect with the sample application.
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:
1 const { MongoClient } = require("mongodb"); 2 3 // Replace the following with your Atlas connection string 4 const url = "mongodb+srv://<db_username>:<db_password>@<clusterName>.mongodb.net/?retryWrites=true&w=majority"; 5 6 // Connect to your Atlas cluster 7 const client = new MongoClient(url); 8 9 async 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 22 run().catch(console.dir);
To run the sample application, use the following command:
node connect.js
Successfully connected to Atlas
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.
Click Drivers.
From the Connect Modal, click Drivers.
Configure the provided connection string.
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.
Connect to your cluster.
Create the command that specifies a client for connecting to your cluster.
In your Python shell, paste your updated connection string into the following command:
client = MongoClient('<connection-string>') Update the connection string with your database user password.
Verify that you have enclosed the connection string in single quotes.
Run the resulting command. It specifies a client that will connect to your cluster.
Connect to your cluster using this client.
Next Steps
Now that you've connected to your cluster, proceed to Insert and View Data in Your Cluster.