AWS Database Blog

Getting Started with Amazon DocumentDB (with MongoDB compatibility); Part 2 – using AWS Cloud9

Amazon DocumentDB (with MongoDB compatibility) is a fast, scalable, highly available, and fully managed document database service that supports MongoDB workloads. You can use the same MongoDB 3.6, 4.0 or 5.0 application code, drivers, and tools to run, manage, and scale workloads on Amazon DocumentDB without having to worry about managing the underlying infrastructure. As a document database, Amazon DocumentDB makes it easy to store, query, and index JSON data.

In part 2 of this series, this post shows you how to get started with Amazon DocumentDB with an AWS Cloud9 environment. The first step is to create an AWS Cloud9 environment and an Amazon DocumentDB cluster in your default Amazon VPC. For instructions on creating a default VPC, see Getting Started with Amazon VPC. This post demonstrates how to connect to your Amazon DocumentDB cluster from your AWS Cloud9 environment with a mongo shell and run a few queries. The walkthrough costs less than $0.10 to complete. When creating AWS resources, we recommend that you follow the AWS IAM best practices. For more information on getting started with Amazon DocumentDB from your local machine, see Getting started with Amazon DocumentDB (with MongoDB compatibility); Part 1 – using Amazon EC2.

The following diagram shows the final architecture of this walkthrough.

For this walkthrough, use the default VPC in a given Region. For more information, see Creating a Virtual Private Cloud (VPC).

Creating an AWS Cloud9 environment

To create your AWS Cloud9 environment, complete the following steps:

  1. Using the AWS management console, on the AWS Cloud9 management console, choose Create environment.
  1. Under Environment name and description, for Name, enter a name for the environment.
    This post enters the name DocumentDBCloud9.
  1. Choose Next step.
  2. In the Configure settings section, accept all defaults.
  3. Choose Next step.
  4. In the Review section, choose Create environment.

The provisioning of the AWS Cloud9 environment can take up to three minutes. When it is complete, you see the following command prompt:

You are redirected to the command prompt to install the mongo shell and connect to your Amazon DocumentDB cluster.

Creating a security group

In this step, you create a new security group that enables you to connect to your Amazon DocumentDB cluster on port 27017 (the default port for Amazon DocumentDB) from your AWS Cloud9 environment. Complete the following steps:

  1. On the Amazon EC2 console, under Network & Security, choose Security groups.
  2. Choose Create security group.
  3. For Security group name, enter demoDocDB.
  4. For VPC, accept the usage of your default VPC
  5. For Description, enter a description.
  6. In the Inbound rules section, choose Add rule.
  7. For Type, choose Custom TCP Rule.
  8. For Port Range, enter 27017.
    The source security group is the security group for the AWS Cloud9 environment you just created.
  9. To see a list of available security groups, enter cloud9 in the destination field.
  10. Choose the security group with the name aws-cloud9-<environment name>.
  11. Accept all other defaults and choose Create security group.

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.

Creating an Amazon DocumentDB cluster

To create your Amazon DocumentDB cluster, complete the following steps:

  1. On the Amazon DocumentDB management console, under Clusters, choose Create.
  2. On the Create Amazon DocumentDB cluster page, for Instance class, select db.t3.medium.
  3. For Number of instances, choose 1.
    This helps minimize costs.
  4. Leave other settings at their default.
  5. In the Authentication section, enter a username and password.
  6. Turn on Show advanced settings.
  7. In the Network settings section, for VPC security groups, choose demoDocDB.
  8. 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.

Installing the mongo shell

You can now install the mongo shell, which is a command-line utility that you use to connect and query your Amazon DocumentDB cluster.

To install the mongo shell, complete the following steps:

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

  1. On the AWS Cloud9 management console, under Your environments, choose DocumentDBCloud9.
  2. Choose open IDE.
  3. At the command prompt, create the repository file with the following code: 
    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
  4. When it is complete, install the mongo shell with the following code: 
    sudo yum install -y mongodb-org-shell

    Transport Layer Security (TLS) is enabled by default for any new Amazon DocumentDB clusters. For more information, see Managing Amazon DocumentDB Cluster TLS Settings.

  5. To encrypt data in transit, download the CA certificate for Amazon DocumentDB. See the following code: 
    wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

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

Connecting to your Amazon DocumentDB cluster

  1. On the Amazon DocumentDB console, under Clusters, locate your cluster.
    This post uses the cluster docdb-2020-02-08-14-15-11.
  2. Choose the cluster you created.
  3. Copy the connection string provided.
    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.
    Your connection string should look like the following code:
    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.

Inserting and querying data

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:

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

You get the following output:

WriteResult({ "nInserted" : 1 })

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

db.collection.findOne()

You get the following output:

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

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:

db.profiles.insertMany([
{ "_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 ] }

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

db.profiles.find()

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, "score" : 27 }

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 }     

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:

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

You get the following output:

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

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 }

Cleaning up

When you complete the walkthrough, you can either stop your Amazon DocumentDB cluster to reduce costs or delete the cluster. By default, after 30 minutes of inactivity, your AWS Cloud9 environment stops the underlying EC2 instance to help save costs.

Summary

This post showed you how to get started with Amazon DocumentDB by creating an AWS Cloud9 environment, installing the mongo shell, creating an Amazon DocumentDB cluster, connecting to your cluster, and performing a few queries to see how easy it is to insert and query JSON documents within Amazon DocumentDB. For more information, see Ramping up on Amazon DocumentDB (with MongoDB compatibility). For more information about recent launches and blog posts, see Amazon DocumentDB (with MongoDB compatibility) resources.

 

About the Authors

 

Joseph Idziorek is a Principal Product Manager at Amazon Web Services.

 

 

 

 

Aleksandr Iziumov is a Solutions Architect at Amazon Web Services.