Navigation

Connect to Your Cluster

Estimated completion time: 5 minutes

You can connect to your cluster in a variety of ways. This tutorial describes how to connect to your cluster using the mongo shell and PyMongo driver.

Note

You must have a MongoDB user setup on your cluster to access your deployment. For security purposes, Atlas requires clients to authenticate as MongoDB users to access clusters.

Download and Install Utility

The following steps show you how to download and install the mongo shell and PyMongo driver. Select the appropriate tab based on how you would like to connect to your cluster:

Tools Required

To complete this tutorial you must have:

  • A terminal.
  • Python.
  • The pip package installer. This comes prepackaged with the Python download.
  • The PyMongo driver.
  • A text editor.

Install the PyMongo Driver

MongoDB drivers allow you to communicate with your MongoDB database programatically.

For this tutorial, we will walk through setting up and using the Python MongoDB driver, called PyMongo. If you are interested in working with a different driver, refer to the MongoDB Driver documentation.

Prerequisites

  • To install PyMongo, you must have Python installed. Visit the Python Downloads Page and download the latest version of Python for your operating system.
  • You will also need the pip package installer. Python 2 >=2.7.9 and Python 3 >=3.4 downloaded from https://python.org come with pip already installed. If you need to install pip manually, refer to the pip installation page for instructions.

Once you have Python and pip installed:

1

Open your terminal.

2

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 as well as a few dependencies for the driver. For more information on these dependencies, refer to the Python Driver Installation Page on GitHub.

3

Test your PyMongo installation.

Let’s test your PyMongo installation to make sure 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.4.0'
    

Tools Required

To complete this tutorial you must have:

  • A terminal
  • The mongo shell

Download and Install the Shell

Estimated completion time: 5 minutes

The mongo shell is an interactive command line interface to MongoDB. You can use the mongo shell to insert and interact with data on your Atlas cluster.

Atlas provides an easy way to download and install the mongo shell. To download and install the mongo shell:

1

Open the Connect dialog.

From your Clusters view, click the Connect button for your cluster.

Screenshot highlighting cluster connect button.
2

Click Connect with the Mongo Shell.

3

Click I do not have the Mongo Shell installed and select your operating system.

Select your operating system from the dropdown in step 1 of the dialog.

4

Download the mongo shell.

  • If you are using Windows or Linux, you can choose to either download the shell directly, or fetch the shell via URL.
  • If you are using macOS, you can use the provided Homebrew command to download the shell.
5

Add the mongo shell to your system path.

To run the mongo shell from your terminal, you will need to add the shell to your system path. Select the appropriate tab based on your operating system:

  1. Double-click the .msi file in Windows Explorer and proceed through the installation wizard.
  2. Add the bin directory to your command path.
    1. Click windows icon and select Control Panel.
    2. Click System and Security, then System, then Advanced System Settings.
    3. Click Environment Variables.
    4. Select Path and click Edit.
    5. Add the bin directory where the installer placed your MongoDB executables and click OK.

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

  1. Run the following command in your terminal to extract the mongo shell:

    tar -xzf ./<filename>.tgz
    
  2. Add the bin directory to your PATH environment variable.

    export PATH=/<extraction-directory>/bin:$PATH
    

    Note

    This command applies only to the current shell session. Edit the PATH environment variable in ~/.profile to update the variable across shell sessions and reboots.

You should now be able to run the mongo shell using your terminal.

6

Test your mongo shell installation.

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

mongo --version

You should see an output similar to the following:

MongoDB shell version v4.0.7
git version: 7c13a75b928ace3f65c9553352689dc0a6d0ca83
allocator: system
modules: none
build environment:
    distarch: x86_64
    target_arch: x86_64

Connect to Your Atlas Cluster

The following steps show you how to connect to your cluster using the mongo Shell and PyMongo driver. Select the appropriate tab based on how you would like to connect to your cluster:

Estimated completion time: 5 minutes

You’ll need to get your cluster’s connection string from Atlas to connect to the cluster using the PyMongo driver.

1

Open the Connect dialog.

From your Clusters view, click the Connect button for your cluster.

Screenshot highlighting cluster connect button.
2

Click Connect Your Application.

3

Select Python from the Driver dropdown and select your version of the driver.

4

Copy the provided connection string from the Connection String Only dialog tab.

Image showing the connection string example
5

In a text editor, update the copied connection string with your password.

For security purposes, Atlas does not show your MongoDB user’s password in the connection string. Instead, your connection string has a placeholder <password>.

Open your preferred text editor and paste the connection string that you copied from Atlas. Replace <password> with the password you specified when you created your MongoDB user.

6

Import MongoClient from PyMongo.

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
7

Connect to your cluster.

In your Python shell, run the following command to specify a client to connect to your cluster. You will need to paste your updated connection string from your text editor into this command:

client = MongoClient('<your updated connection string>')

Your connection string should be in single quotes, and should be updated to contain your MongoDB user password. After you run this command, you will be able to connect to your cluster using this client.

Estimated completion time: 3 minutes

Now that you have installed the mongo shell, you can use the shell to connect to your Atlas cluster.

1

Open the Connect dialog.

From your Clusters view, click the Connect button for your cluster.

Screenshot highlighting cluster connect button.
2

Click Connect with the Mongo Shell.

3

Click I have the Mongo Shell Installed and select your mongo shell version from the drop-down.

4

Copy the provided connection string to your clipboard.

Image highlighting sample copyable connection string.

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

5

Paste and run your connection string in your terminal.

7

When prompted, enter your MongoDB user’s password.

You will be prompted to enter the password you specified when you created your MongoDB user in Atlas.

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

MongoDB Enterprise GettingStarted-shard-0:PRIMARY>

Connection Troubleshooting

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

Next Steps

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