Amazon DocumentDB
Developer Guide

Step 3: Access 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:

  1. Download the mongo shell for MongoDB 3.6:

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

       

    • To install the mongo shell on Ubuntu

      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 16.04

        echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu 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.

       

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

  2. 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
  3. 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.
  4. 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
  5. 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" } )
  6. When you are finished, exit from the mongo shell:

    exit

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