Get Started with Amazon DocumentDB

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

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

Open https://portal.aws.amazon.com/billing/signup.
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 .

In the search bar of the AWS Management Console, type in IAM and select IAM in the drop down menu that appears.
Once you’re in the IAM console, select Users from the navigation pane.
Select your username.
Click the button Add permissions.
Select Attach existing policies directly.
Type in the search bar and select it once it appears in the search results.
Click the blue button at the bottom that says Next: Review.
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.

From the AWS Management Console navigate to the AWS Cloud9 console and choose Create environment.
In the Environment name and description section, in the Name field, enter DocumentDBCloud9.
Choose Next step.
In the Configure settings section, choose Next step.
In the Review section, choose Create environment.

Note

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

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

Choose Create security group.
In the Inbound rules section, choose Add rule.
For Type, choose Custom TCP Rule.
For Port range, enter 27017.
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`>.
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.

On the Amazon DocumentDB management console, under Clusters, choose Create.
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.
In the Authentication section, enter a username and password.
Turn on Show advanced settings.
In the Network settings section, for VPC security groups, choose demoDocDB.
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.

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.

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.
At the command prompt, create the repository file with the following command:
When it is complete, install the mongo shell with the following command:
```
sudo yum install -y mongodb-org-shell
```
To encrypt data in transit, download the public key for Amazon DocumentDB from . This operation downloads a file named rds-combined-ca-bundle.pem.
```
wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem
```
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.

On the Amazon DocumentDB management console, under Clusters, locate your cluster. Choose the cluster you created by clicking on the cluster identifier.
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.
Go back to your AWS Cloud9 environment and paste the connection string.

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

Note

For information about troubleshooting, see Troubleshooting Amazon DocumentDB.

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:
You get the following output:

WriteResult({ "nInserted" : 1 })
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 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}

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. Input the following:
You will get an output that will match the data you typed in Step 5.
Use a query for a single document using a filter. Input the following:
```
db.profiles.find({name: "Katie"})
```
You should get back this output:

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

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 } }
   })

You get the following output (note that his score hasn’t increased yet):
You can verify that his score has changed with the following query:
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

Note