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, the Node.js driver, and the PyMongo driver.

Prerequisites

  • An Atlas account with an active cluster.
  • An IP address added to your IP access list.
  • A MongoDB user on your cluster.

See Parts 1 - 4 of this tutorial for help with the prerequisites.

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.

Download and Install Utility

The following steps show you how to download and install the mongo shell, the Node.js driver, and the 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 use the Node.js driver, you must have:

    Install the Node.js Driver

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

    npm install mongodb --save
    

    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, download using one of the following options:

      • Click Download Mongo Shell 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.

    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, the Node.js driver and the 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 database 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 database 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 database user password. After you run this command, you will be able to connect to your cluster using this client.

      Estimated completion time: 5 minutes

      You’ll need to get your cluster’s connection string from Atlas to connect to the cluster using the Node.js 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 Node.js 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

      Connect with the sample app.

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

      Note

      Replace the placeholders on line 4 with your Atlas connection string.

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

      To run the sample application, use the following command:

      node connect.js
      

      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 database user you created earlier in this procedure.

      5

      Paste and run your connection string in your terminal.

      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 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 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.

      Next Steps

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