Amazon DocumentDB
Developer Guide

Step 3: Access and Use Your Amazon DocumentDB Cluster Using the mongo Shell

In this step, you connect to your Amazon DocumentDB cluster using the mongo shell. You perform these steps using the Amazon EC2 instance that you created in Step 2: Launch an Amazon EC2 Instance.


Before you begin, ensure that your Amazon DocumentDB cluster and instance are both available. For information on checking the status of your cluster or instance, see:

Step 3.a: Install the mongo shell

Install the mongo shell on your system.

On Amazon Linux

To install the mongo shell on Amazon Linux

  1. Create the repository file /etc/yum.repos.d/mongodb-org-3.6.repo with the following contents:

    [mongodb-org-3.6] name=MongoDB Repository baseurl= gpgcheck=1 enabled=1 gpgkey=

    The following one line command creates the repository file.

    echo -e "[mongodb-org-3.6] \nname=MongoDB Repository\nbaseurl=\ngpgcheck=1 \nenabled=1 \ngpgkey=" | sudo tee /etc/yum.repos.d/mongodb-org-3.6.repo
  2. Install the MongoDB shell.

    sudo yum install -y mongodb-org-shell

For information about installing earlier versions of MongoDB on your Amazon Linux system, see Install MongoDB Community Edition on Amazon Linux in the MongoDB documentation.


On Ubuntu 18.04

To install the mongo shell on Ubuntu 18.04

  1. Import the public key that will be used by the package management system.

    sudo apt-key adv --keyserver hkp:// --recv 2930ADAE8CAF5059EE73BB4B58712A2291FA4AD5
  2. Create the list file /etc/apt/sources.list.d/mongodb-org-3.6.list for MongoDB using the command appropriate for your version of Ubuntu.

    Ubuntu 18.04

    echo "deb [ arch=amd64,arm64 ] xenial/mongodb-org/3.6 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.6.list
  3. Reload the local package database using the following command:

    sudo apt-get update
  4. Install the MongoDB shell.

    sudo apt-get install -y mongodb-org-shell

For information about installing earlier versions of MongoDB on your Ubuntu system, see Install MongoDB Community Edition on Ubuntu.


On other operating systems

To install the mongo shell on other operating systems, see Install MongoDB Community Edition in the MongoDB documentation.

Step 3.b: Manage Amazon DocumentDB TLS

Transport Layer Security (TLS) is enabled by default for new Amazon DocumentDB clusters; however, you can disable it. For more information, see Managing Amazon DocumentDB Cluster TLS Settings.

To encrypt data in transit, download the public key for Amazon DocumentDB from This operation downloads a file named rds-combined-ca-bundle.pem.


Step 3.c: Connect and Use Amazon DocumentDB

To connect to and use your Amazon DocumentDB cluster

  1. Get the mongo connection command for the cluster:

    1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at

    2. If the cluster you want to connect to is not in the US East (N. Virginia) Region, in the upper-right corner of the console, change to your cluster's Region.

    3. In the left navigation pane, choose Clusters. Then from the list of clusters, choose the name of the cluster that you want to connect to.

    4. On the cluster's detail page, locate the Connect section. Then locate and copy the mongo shell connection string. Use this string in the next step.

                           Screen shot showing the mongo shell connection string in the connect section.
  2. Use the mongo shell to connect to Amazon DocumentDB.

    To connect to your cluster using mongo, paste the connection command you copied in the previous step to your command window. Then, after changing the <insertYourPassword> to your master password, run the command.

    Example: Line breaks are added for readability only.

    mongo --ssl --host endpoint --sslCAFile rds-combined-ca-bundle.pem --username yourMasterUsername --password yourMasterPassword
  3. From the mongo shell, issue a few operations:

    1. Insert a new document:

      db.inventory.insert( { "SKU" : "38220349", "Description" : "14 oz. whole wheat bread", "Vendor" : { "Name" : "Example Bakery, LLC.", "Street" : "321 No. Gilbert", "City" : "Anytown", "State-Provence" : "CA", "Country" : "USA", "Phone" : "000-555-0100", "Contacts" : [ { "LName" : "Stiles", "FName" : "Jonathan", "FriendlyName" : "JJ", "Role" : "Sales", "Phone" : "000-555-0111" } ], }, "Stock" : { "OnHand" : "4", "OrderWhenBelow" : "6", "OrderQuantity" : "8" }, "UnitPrice" : { "Wholesale" : "1.71", "Retail" : "2.39" } } )
    2. Find all documents:

      db.inventory.find( {} ).pretty()
    3. Update a document:

      The following example updates the document by replacing the current UnitPrice embedded document with a new one, which has new Wholesale and Retail prices, and adding a DayOld price.

      db.inventory.update( { "SKU" : "38220349" }, { $set: { "UnitPrice" : { "Wholesale" : "1.87", "Retail" : "2.69", "DayOld" : "1.89" } } } )

      When the operation is finished, the embedded UnitPrice document looks like the following. The rest of the document is unchanged.

      { "SKU" : "38220349", "Description" : "14 oz. whole wheat bread", "Vendor" : { "Name" : "Example Bakery, LLC.", "Street" : "321 No. Gilbert", "City" : "Anytown", "State-Provence" : "CA", "Country" : "USA", "Phone" : "000-555-0100", "Contacts" : [ { "LName" : "Stiles", "FName" : "Jonathan", "FriendlyName" : "JJ", "Role" : "Sales", "Phone" : "000-555-0111" } ], }, "Stock" : { "OnHand" : "4", "OrderWhenBelow" : "6", "OrderQuantity" : "8" }, "UnitPrice" : { "Wholesale" : "1.87", "Retail" : "2.69", "DayOld" : "1.89" } }
    4. Delete a document:

      db.inventory.remove( { "SKU" : "38220349" } )
  4. When you are finished, exit from the mongo shell:


To delete your cluster and stop incurring costs, go to Step 4: (Optional) Delete the Amazon DocumentDB Instance and Cluster.