AWS Database Blog

Getting started with Amazon DocumentDB (with MongoDB compatibility); Part 1 – using Amazon EC2

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 1 of this series, this post shows you how to get started with Amazon DocumentDB. To do that, you are going to create an Amazon EC2 instance in your default Amazon VPC. For instructions on creating a default VPC, see Getting Started with Amazon VPC. You also provision a 1-instance Amazon DocumentDB cluster in the same default VPC. This post demonstrates how to SSH to the EC2 instance from your local computer and connect to your cluster from the EC2 instance with a mongo shell. Lastly, you learn how to run queries against your Amazon DocumentDB cluster. This walkthrough costs less than $0.10 to complete. When creating AWS resources, we recommend that you follow the AWS IAM best practices.

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 two security groups

The first step is to create two new security groups in your default VPC. The first security group (demoEC2) allows you to SSH into your EC2 instance from your local machine (client). The second security group (demoDocDB) enables you to connect to your Amazon DocumentDB cluster on port 27017 (the default port for Amazon DocumentDB) from your EC2 instance. Complete the following steps:

  1. On the Amazon EC2 console, choose Network & Security.
  2. Choose Security Groups.
  3. Choose Create Security Group.
    The page prompts you to supply a security group name and description.
  4. For the first security group, for Security group name, enter demoEC2.
  5. Optionally, enter a description.
  6. Choose Add Rule.
  7. For Type, choose SSH. The Port Range will automatically default to 22.
  8. For Source, choose MY IP.
    You can only access the demoEC2 security group from your current IP address. If your IP address changes, you must update the security group.
  9. Choose Create.
    Next, create a second security group for your Amazon DocumentDB cluster called demoDocDB.
  10. Repeat the previous steps, with the following changes:
  • For Type, choose Custom TCP.
  • For Port Range, enter 27017.
  • For Source, choose demoEC2.You may need to refresh your browser for the Amazon EC2 console to auto-populate the demoEC2 source name.
  1. Choose Create.

Creating an EC2 instance

The next step is to create an EC2 instance in the same Region and VPC that you use to provision your Amazon DocumentDB cluster. Create your Amazon DocumentDB cluster in your default VCP. Because Amazon DocumentDB is a VPC-only service, this post demonstrates how to SSH into the EC2 instance and use the EC2 instance to connect to your Amazon DocumentDB cluster. Complete the following steps:

  1. On the Amazon EC2 console, choose Launch instance.
  2. Locate Amazon Linux 2 AMI and choose Select.
  3. Select the t2.micro instance type.
  4. Choose Review and Launch.
  5. On the Step 7: Review Instance Launch page, review your final configuration.
    You also have to specify that you want to use the demoEC2 security group that you just created.
  6. Choose Edit security groups.
  7. Choose Select an existing security group.
  8. Select your demoEC2 group.
  9. Choose Review and Launch.
    If you selected the demoEC2 security group, you see the rules that you added at the bottom of the section. See the following screenshot.
  10. Verify the information and choose Launch.
  11. On the Select an existing key pair or create a new key pair section, you must provide an Amazon EC2 key pair.
    If you don’t have an EC2 key pair, choose Create a new key pair and follow the instructions. You have to download a private key file (.pem file). You need this file later when you log in to your EC2 instance.
    .
    If you have an EC2 key pair, under Select a key pair, choose your key pair from the list. You must already have the private key file (.pem file) available to log in to your EC2 instance.
  12. Choose Launch Instances.

Creating an Amazon DocumentDB cluster

While the EC2 instance is being provisioned, launch your Amazon DocumentDB cluster. Complete the following steps:

  1. On the Amazon DocumentDB 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.
    You use this username and password to authenticate your cluster in a later step.
  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.

Connecting to your EC2 instance

To install the mongo shell, you must first connect to your EC2 instance. Installing the mongo shell enables you to connect to and query your Amazon DocumentDB cluster. Complete the following steps:

  1. On the Amazon EC2 console, choose the instance you created.
    If the instance status is running, you can now connect to it and install the mongo shell.
  2. Choose Connect.
    You have three options for your connection method:
  • A standalone SSH client
  • Session Manager
  • EC2 Instance Connect (browser-based SSH connection)

This post covers EC2 Instance Connect and a standalone SSH client. EC2 Instance Connect is the quickest and often the most straightforward option because you connect to your EC2 instance with a click of the button with a browser-based SSH connection. A standalone SSH client is a good option if you want to connect to your cluster using an SSH client like Terminal or PuTTY on your local machine.

If your IP address changed after you started this walkthrough, or you are coming back to your environment at a later time, you must update your demoEC2 security group inbound rule to enable inbound traffic from your new API address.

EC2 Instance Connect

To connect to your EC2 instance using a browser-based SSH connection, complete the following steps:

  1. In the Connect to your instance section, for Connection method, select EC2 Instance Connect (browser-based SSH connection). The user name will default to “ec2-user.”
  2. Choose Connect.
    A command-line prompt opens, from which you can run commands. See the following screenshot.
    Proceed to the step Installing the mongo shell.

Standalone SSH client

To connect to the default connection method of a standalone SSH client, complete the following steps:

  1. In the Connect to your instance section, for Connection method, select A standalone SSH client.
  2. Choose Connect.
  3. In the Connect to your instance section, copy the example connection string.
    If you are using a macOS as your local machine, open the terminal and use the example connection string to connect to your EC2 instance. This step varies depending on what you are using as your local machine. For more information, see Connecting to Your Linux Instance Using SSH.When you choose Connect, you must make sure that the .pem file you downloaded or chose earlier has the correct permissions. For this walkthrough, name the .pem file documentdb.pem. The following screenshot shows you the .pem for your EC2 instance and how to set the correct permissions on your EC2 instance.
    When you connect to your EC2 instance for the first time, you must verify the authenticity of the host.
  4. If everything is correct, enter yes.
    You should now be connected to your EC2 instance that is in the same Region and VPC as your Amazon DocumentDB cluster. See the following screenshot.
    Proceed to the next step.

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 on Amazon Linux, complete the following steps.

  1. Create the repository file. At the command line of your EC2 instance, execute the follow command: 
    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

    When it is complete, install the mongo shell by executing the following command:

    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.

  2. 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 Document DB 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:

    mongo --ssl host docdb-2020-02-08-14-15-11.&lt;cluster&gt;.&lt;region&gt;.docdb.amazonaws.com:27107 --sslCAFile rds-combined-ca-bundle.pem --username demoUser --password

    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 called 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 incrementing 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 }

You can now continue to insert and query your data.

Cleaning up

When you complete the walkthrough, you can either stop your Amazon DocumentDB cluster and stop your EC2 instance to reduce costs, or delete the resources. For more information, see Deleting an Amazon DocumentDB Cluster and Terminate Your Instance.

Summary

This post showed you how to get started with Amazon DocumentDB by creating an EC2 instance, 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. The next blog post in this series shows you how to get started with Amazon DocumentDB using AWS Cloud9.

 

About the Authors

 

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

 

 

 

 

Randy DeFauw is a Principal Solutions Architect at Amazon Web Services. He works with the AWS customers to provide guidance and technical assistance on database projects, helping them improve the value of their solutions when using AWS.