Get Started with Amazon DocumentDB

There are many ways to connect and get started with Amazon DocumentDB. We created this guide because we found this way to be the quickest, simplest and easiest way for users to get started using our powerful document database. This guide utilizes AWS Cloud9, a web-based terminal to connect and query your Amazon DocumentDB cluster using the mongo shell directly from the AWS Management Console. New AWS customers who are eligible for the AWS Free Tier can use AWS Cloud9 for free. If your AWS Cloud9 environment makes use of resources beyond the free tier, you are charged the normal AWS rates for those resources. This guide will get you started with Amazon DocumentDB in less than 15 minutes and the expected cost is less than $0.10/hour.

Note

Amazon DocumentDB does not have a free tier. For more information on pricing, please see Amazon DocumentDB (with MongoDB compatibility) pricing.

If you would rather connect to your Amazon DocumentDB from your local machine by creating an SSH connection to an Amazon EC2 instance, please see the Connect with EC2 instructions

Prerequisites

Before you create your first Amazon DocumentDB cluster, you must do the following:

Create an Amazon Web Services (AWS) account

Before you can begin using Amazon DocumentDB, you must have an Amazon Web Services (AWS) account. The AWS account is free. You pay only for the services and resources that you use.

If you do not have an AWS account, complete the following steps to create one.

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

   Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.

Set up the needed AWS Identity and Access Management (IAM) permissions.

Access to manage Amazon DocumentDB resources such as clusters, instances, and cluster parameter groups requires credentials that AWS can use to authenticate your requests. For more information, see Identity and Access Management in Amazon DocumentDB.

1. In the search bar of the AWS Management Console, type in IAM and select IAM in the drop down menu that appears.

2. Once you’re in the IAM console, select Users from the navigation pane.

3. Select your username.

4. Click the button Add permissions.

5. Select Attach existing policies directly.

6. Type AmazonDocDBFullAccess in the search bar and select it once it appears in the search results.

7. Click the blue button at the bottom that says Next: Review.

8. Click the blue button at the bottom that says Add permissions.

Create an Amazon Virtual Private Cloud (Amazon VPC)

This step is only necessary if you don’t already have a default Amazon VPC. If you don’t, then complete step 1 of the Getting Started with Amazon VPC in the Amazon VPC User Guide. This will take less than five minutes.

Step 1: Create an AWS Cloud9 environment

AWS Cloud9 provides a web-based terminal that you can use to connect to and query your Amazon DocumentDB cluster using the mongo shell.

1. From the AWS Management Console navigate to the AWS Cloud9 console and choose Create environment.

   

2. In the Environment name and description section, in the Name field, enter DocumentDBCloud9.

   

3. Choose Next step.

   

4. In the Configure settings section, choose Next step.

   

5. In the Review section, choose Create environment.

   

Note

The provisioning of the AWS Cloud9 environment can take up to three minutes.

Step 2: Create a security group

This security group will enable you to connect to your Amazon DocumentDB cluster from your AWS Cloud9 environment.

1. On the Amazon EC2 Management Console, under Network and Security, choose Security groups.

   

2. Choose Create security group.

   

3. In the Basic details box, input the following for each field:

   • For Security group name, enter demoDocDB.
   • For Description, enter a description.
   • For VPC, accept the usage of your default VPC.

   

4. In the Inbound rules section, choose Add rule.

   

5. For Type, choose Custom TCP Rule.

   

6. For Port range, enter 27017.

   

7. The source is the security group for the AWS Cloud9 environment you just created. To see a list of available security groups, enter cloud9 in the destination field. Choose the security group with the name aws-cloud9-<`environment name`>.

   

8. Accept all other defaults and choose Create security group.

   

Note

Port 27017 is the default port for Amazon DocumentDB.

Step 3: Create an Amazon DocumentDB cluster

In this step you will create an Amazon DocumentDB cluster using the security group you created in the previous step.

1. On the Amazon DocumentDB management console, under Clusters, choose Create.

   

2. On the Create Amazon DocumentDB cluster page, in the Configuration section, choose 1 for Number of instances. Choosing one instance helps minimize costs. If this were a production system, it is recommended to provision three instances for high availability. You can leave the other settings in the Configuration section at their default.

   

3. In the Authentication section, enter a username and password.

   

4. Turn on Show advanced settings.

   

5. In the Network settings section, for VPC security groups, choose demoDocDB.

   

6. Choose Create cluster.

   

Amazon DocumentDB is now provisioning your cluster, which can take up to a few minutes to finish. You can connect to your cluster when both the cluster and instance status show as Available.

Step 4: Install the mongo shell

You will now install the mongo shell in your AWS Cloud9 environment that you created in Step 1. The mongo shell is a command-line utility that you use to connect and query your Amazon DocumentDB cluster.

1. If your AWS Cloud9 environment is still open from Step 1, go back to that environment and skip to instruction 3. If you navigated away from you AWS Cloud9 environment, in the AWS Cloud9 management console, under Your environments, find the environment labeledDocumentDBCloud9. Choose Open IDE.

   

2. At the command prompt, create the repository file with the following command:

   echo -e "[mongodb-org-4.0] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2013.03/mongodb-org/4.0/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc" | sudo tee /etc/yum.repos.d/mongodb-org-4.0.repo

3. When it is complete, install the mongo shell with the following command:

   sudo yum install -y mongodb-org-shell

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

   Note

   Encryption-in-transit is enabled by default on Amazon DocumentDB. You can optionally disable TLS. For more information, see Managing Amazon DocumentDB Cluster TLS Settings.

Step 5: Connect to your Amazon DocumentDB cluster

You will now connect to your Amazon DocumentDB cluster using the mongo shell that you installed in Step 4.

1. On the Amazon DocumentDB management console, under Clusters, locate your cluster. Choose the cluster you created by clicking on the cluster identifier.

   

2. In the Connectivity and Security tab, under Connect to this cluster with the mongo shell, copy the connection string provided. Omit copying <insertYourPassword> so that you are prompted for the password by the mongo shell when you connect.

   

3. Go back to your AWS Cloud9 environment and paste the connection string.

When you enter your password and your prompt becomes rs0:PRIMARY> prompt, you are successfully connected to your Amazon DocumentDB cluster.

Note

For information about troubleshooting, see Troubleshooting Amazon DocumentDB.

Step 6: Insert and query data

Now that you are connected to your cluster, you can run a few queries to get familiar with using a document database.

1. To insert a single document, enter the following:

   db.collection.insert({"hello":"DocumentDB"})

2. You get the following output:

   WriteResult({ "nInserted" : 1 })

3. You can read the document that you wrote with the findOne() command (because it only returns a single document). Input the following:

   db.collection.findOne()

4. You get the following output:

   { "_id" : ObjectId("5e401fe56056fda7321fbd67"), "hello" : "DocumentDB" }

5. To perform a few more queries, consider a gaming profiles use case. First, insert a few entries into a collection titled profiles. Input the following:

   db.profiles.insertMany([
               { "_id" : 1, "name" : "Matt", "status": "active", "level": 12, "score":202},
               { "_id" : 2, "name" : "Frank", "status": "inactive", "level": 2, "score":9},
               { "_id" : 3, "name" : "Karen", "status": "active", "level": 7, "score":87},
               { "_id" : 4, "name" : "Katie", "status": "active", "level": 3, "score":27}
               ])

6. You get the following output:

   { "acknowledged" : true, "insertedIds" : [ 1, 2, 3, 4 ] }

7. Use the find() command to return all the documents in the profiles collection. Input the following:

   db.profiles.find()

8. You will get an output that will match the data you typed in Step 5.

9. Use a query for a single document using a filter. Input the following:

   db.profiles.find({name: "Katie"})

10. You should get back this output:

    { "_id" : 4, "name" : "Katie", "status": "active", "level": 3, "score":27}

11. Now let’s try to find a profile and modify it using the findAndModify command. We’ll give the user Matt an extra ten points with the following code:

       db.profiles.findAndModify({
           query: { name: "Matt", status: "active"},
           update: { $inc: { score: 10 } }
       })

12. You get the following output (note that his score hasn’t increased yet):

       {
       "_id" : 1,
       "name" : "Matt",
       "status" : "active",
       "level" : 12,
       "score" : 202
       }

13. You can verify that his score has changed with the following query:

    db.profiles.find({name: "Matt"})

14. You get the following output:

    { "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" : 212 }

Step 7: Explore

Congratulations! You have successfully completed the Get Started Guide to Amazon DocumentDB.

What’s next? Learn how to fully leverage this database with some of its popular features:

• Managing Amazon DocumentDB

• Scaling

• Backing up and restoring

Note

The cluster you created from this get started exercise will continue to accrue cost unless you delete it. For directions, see Deleting an Amazon DocumentDB Cluster.