Amazon DocumentDB
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

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.

Note

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=https://repo.mongodb.org/yum/amazon/2013.03/mongodb-org/3.6/x86_64/ gpgcheck=1 enabled=1 gpgkey=https://www.mongodb.org/static/pgp/server-3.6.asc

    The following one line command creates the repository file.

    echo -e "[mongodb-org-3.6] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2013.03/mongodb-org/3.6/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://www.mongodb.org/static/pgp/server-3.6.asc" | 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://keyserver.ubuntu.com:80 --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] http://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.0 multiverse" > /etc/apt/sources.list.d/mongodb-org-4.0.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 https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem. This operation downloads a file named rds-combined-ca-bundle.pem.

wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

Important

The certificate authority (CA) certificate for Amazon DocumentDB clusters is being updated. As of September 1, 2019, the new CA bundle (rds-combined-ca-bundle.pem) contains both the old CA certificate (rds-ca-2015-root.pem) and the new CA certificate (rds-ca-2019-root.pem).

To avoid an interruption in connectivity between your application and your Amazon DocumentDB clusters, take the following actions before February 5, 2020:

  1. Download the new CA certificate (rds-ca-2019-root.pem) and update your application to use the new CA certificate to create TLS connections to Amazon DocumentDB.

  2. Modify the instances in your Amazon DocumentDB clusters to update the server certificate.

As of November 1, 2019, all new Amazon DocumentDB instances you create will use the new server certificate and will require the new CA certificate to create TLS connections. For more information, see Updating Your Amazon DocumentDB TLS Certificates.

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 https://console.aws.amazon.com/docdb.

    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:

    exit

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