Setting up a Document Database

With Amazon DocumentDB (with MongoDB compatibility) and AWS Cloud9

Amazon DocumentDB (with MongoDB compatibility) is a fast, scalable, highly available, and fully managed document database service that supports MongoDB workloads, and makes it easy to store, query, and index JSON data.

This tutorial shows you how to get started with Amazon DocumentDB using AWS Cloud9. You will learn how to connect to your Amazon DocumentDB cluster from your AWS Cloud9 environment with a mongo shell and run a few queries.

For new DocumentDB customers, this walkthrough should not cost anything.

The following diagram shows the final architecture of this walkthrough.

About this Tutorial
Time 10 minutes or less                                  

Amazon DocumentDB and AWS Cloud9 are free-tier eligible. See AWS Cloud9 pricing and Amazon DocumentDB pricing for more information. For new users, this walkthrough should be free.

Use Case Databases
Products Amazon DocumentDB (with MongoDB compatibility), AWS Cloud9
Audience Developer
Level 200: Intermediate. This content focuses on providing an overview of AWS services or features, with the assumption that the customer has a working knowledge of the topic.
Last Updated August 2020

1. Creating an AWS Cloud9 Environment

1.1 – Using the AWS management console, on the AWS Cloud9 management console, choose Create environment.


1.2 – Enter the name DocumentDBCloud9.


1.3 – Choose Next step.


1.4 – In the Configure Settings section, accept all defaults.

1.5 – Choose Next step.

1.6 – In the Review section, choose Create environment.


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

2. Creating a security group

2.1 – On the Amazon EC2 management console, under Network & Security, choose Security groups.

2.2 – Choose Create security group.

2.3 – For Security group name, enter demoDocDB.

2.4 – For Description, enter a description.

2.5 – For VPC, accept the usage of your default VPC

2.6 – In the Inbound rules section, choose Add rule.

2.7 – For Type, choose Custom TCP Rule.

2.8 – For Port Range, enter 27017.

2.9 – The source security group is the security group for the AWS Cloud9 environment you just created. Keep the Source as the default value of Custom and enter "cloud9" in the field adjacent to Custom to see a list of available security groups.


2.10 – Choose the security group with the name aws-cloud9-<environment name>

2.11 – Accept all other defaults and choose Create security group. You do not need to modify the outbound rules.

The following screenshot shows you the security groups that were created in this step as well as the AWS Cloud9 security group that was created when you created an AWS Cloud9 environment.


3. Creating an Amazon DocumentDB cluster

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


3.2 – On the Create Amazon DocumentDB cluster page, select db.t3.medium under Instance class, and then choose 1 for Number of instances. These options will help minimize costs.


3.3 – Leave other settings at their default.

3.4 – In the Authentication section, enter a username and password.


3.5 – Turn on Show advanced settings.


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


3.7 – 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. While Amazon DocumentDB provisions the cluster, complete the remaining steps to connect to your Amazon DocumentDB cluster.

4. Installing the mongo shell

4.1 – If your AWS Cloud9 environment is still open, you can skip to step 3.

4.2 – On the AWS Cloud9 management console, under Your environments, choose DocumentDBCloud9.

4.3 – Choose open IDE.

4.4 – At the command prompt, create the repository file with the following code:

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

4.5 – When it is complete, install the mongo shell with the following code:

sudo yum install -y mongodb-org-shell

4.6 – To encrypt data in transit, download the CA certificate for Amazon DocumentDB. See the following code:


4.7 – You are now ready to connect to your Amazon DocumentDB cluster.

5. Connect to your Amazon DocumentDB Cluster

5.1 – On the Amazon DocumentDB management console, under Clusters, locate your cluster. This post uses the cluster docdb-2020-02-08-14-15-11.


5.2 – Choose the cluster you created by clicking on the cluster identifier (i.e., docdb-2020-02-08-14-15-11 in this example).

5.3 – Copy the connection string provided under “Connect to this cluster with the mongo shell”

Omit <insertYourPassword> so that you are prompted for the password by the mongo shell when you connect. This way, you don’t have to type your password in cleartext.


5.4 – Your connection string should look like the following code (see screenshot)


5.5 – When you enter your password and can see the rs0:PRIMARY> prompt, you are successfully connected to your Amazon DocumentDB cluster.

For information about troubleshooting, see Troubleshooting Amazon DocumentDB.

6. Inserting and querying data

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

To insert a single document, enter the following code:


You get the following output:

WriteResult({ "nInserted" : 1 })

6.2 - You can read the document that you wrote with the findOne() command (because it only returns a single document). See the following code:


You get the following output:

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

6.3 - To perform a few more queries, consider a gaming profiles use case. First, insert a few entries into a collection entitled profiles. See the following code:


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

{ "_id" : 2, "name" : "Justin", "status": "inactive", "level": 2, "score":9},

{ "_id" : 3, "name" : "Beth", "status": "active", "level": 7, "score":87},

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


You get the following output:

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

6.4 - Use the find() command to return all the documents in the profiles collection. See the following code:


You get the following output:

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

{ "_id" : 2, "name" : "Justin", "status" : "inactive", "level" : 2, "score" : 9 }

{ "_id" : 3, "name" : "Beth", "status" : "active", "level" : 7, "score" : 87 }

{ "_id" : 4, "name" : "Jesse", "status" : "active", "level" : 3,

6.5 - Use a query for a single document using a filter. See the following code.

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

You get the following output:

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

6.6 - A common use case in gaming is finding a profile for a given user and increment a value in the user’s profile. In this scenario, you want to run a promotion for the top active gamers. If the gamer fills out a survey, you increase their score by +10.

To do that, use the findAndModify command. In this use case, the user Tim received and completed a survey. To give Tim the credit to their score, enter the following code:


   query: { name: "Tim", status: "active"},

   update: { $inc: { score: 10 } }


You get the following output:


      "_id" : 1,

      "name" : "Tim",

      "status" : "active",

      "level" : 12,

      "score" : 202


6.7 - You can verify the result with the following query:

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

You get the following output:

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

7. Cleaning up

When you complete the walkthrough, stop your Amazon DocumentDB cluster to reduce costs or delete the cluster altogether.

By default, after 30 minutes of inactivity, your AWS Cloud9 environment stops the underlying EC2 instance to help save costs.



This tutorial showed you how to get started with Amazon DocumentDB by creating an AWS Cloud9 environment.

You were able to install the mongo shell, create an Amazon DocumentDB cluster, connect to your cluster, and perform a few queries, seeing how easy it is to insert and query JSON documents within Amazon DocumentDB.

Amazon DocumentDB (with MongoDB compatibility) is a fast, scalable, highly available, and fully managed document database service that supports MongoDB workloads, and makes it easy to store, query, and index JSON data.

Was this tutorial helpful?

Thank you
Please let us know what you liked.
Sorry to disappoint you
Is something out-of-date, confusing or inaccurate? Please help us improve this tutorial by providing feedback.