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 customers who are eligible for the AWS Free Tier can use Amazon DocumentDB and AWS Cloud9 for free. If your AWS Cloud9 environment or Amazon DocumentDB cluster 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.
Note
The instructions in this guide are specifically for creating and connecting to Amazon DocumentDB instance-based clusters. If you want to create and connect to Amazon DocumentDB elastic clusters, see Get started with Amazon DocumentDB elastic clusters.
Topics
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
Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.
When you sign up for an AWS account, an AWS account root user is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform tasks that require root user access.
- 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 for Amazon DocumentDB.
-
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
AmazonDocDBFullAccess
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 Details section of the Create environment dialog, enter
DocumentDBCloud9
in the Name field. -
In the New EC2 instance dialog, choose Amazon Linux 2 from the Platform drop-down list.
Important
To avoid errors during the creation of the Amazon DocumentDB database, you must select Amazon Linux 2 for the Platforms field. If you have selected to use an existing Amazon EC2 instance in the previous step, it too must have been created using Amazon Linux 2.
-
For the Network settings and Tags sections, leave the default setting as they are.
-
Click Create at the bottom of the screen.
Your new AWS Cloud9 environment appears in the Environments table:
![](/images/documentdb/latest/developerguide/images/cloud9/cloud9-environments.png)
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.
-
On the Amazon EC2 Management Console
, under Network and Security, choose Security groups. -
Choose Create security group.
-
In the Basic details section:
For Security group name, enter
demoDocDB
.For Description, enter a description.
For VPC, accept the usage of your default VPC.
-
In the Inbound rules section, choose Add rule.
For Type, choose Custom TCP.
For Port range, enter
27017
.For Source, choose the security group for the AWS Cloud9 environment that was created after you completed step 1. To see a list of available AWS Cloud9 security groups, enter
cloud9
in the search field on the right side to the Source field. Choose the security group with the nameaws-cloud9-<
.environment name
>
Note
Port 27017 is the default port for Amazon DocumentDB.
-
For the Destination field in Outbound rules, choose Custom. In the field next to it, search for the security group you just created called
demoDocDB
. You may need to refresh your browser for the Amazon EC2 console to auto-populate thedemoDocDB
source name. -
Accept all other defaults and choose Create security group.
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.
Note
The instructions in this step are specifically for creating Amazon DocumentDB instance-based clusters. If you want to create Amazon DocumentDB elastic clusters, see Get started with Amazon DocumentDB elastic clusters.
-
On the Amazon DocumentDB management console, under Clusters, choose Create.
-
On the Create Amazon DocumentDB cluster page, in the Cluster type section, choose Instance Based Clusters (this is the default option).
-
In the Configuration section, choose 1 instance. Choosing one instance helps minimize costs. If this were a production system, we would recommend that you provision three instances for high availability. You can leave the other settings in the Configuration section at their defaults.
-
For Connectivity, leave the default setting of Don't connect to an EC2 compute resource.
-
In the Authentication section, enter sign-in credentials.
-
Turn on Show advanced settings.
-
In the Network settings section, for VPC security groups, choose demoDocDB (VPC) if you are creating a test or demo cluster. If you are creating a cluster for a production system, choose default (VPC) or if you want to create a specific VPC security group, see Security groups in the Amazon Virtual Private Cloud User Guide.
-
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
.
Note
For information about cluster status values, see Cluster status values in the Monitoring Amazon DocumentDB chapter.
For information about instance status values, see Instance status values in the Monitoring Amazon DocumentDB chapter.
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.
-
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 Environments, find the environment labeled DocumentDBCloud9. Choose Open in the Cloud9 IDE column.
-
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
-
When it is complete, install the mongo shell with the following command:
sudo yum install -y mongodb-org-shell
Important
If you received errors during the mongo shell install process, check to see which platform you selected during the Cloud9 configuration. You must select Amazon Linux 2 for the Platforms field in Cloud9. If you selected to use an existing Amazon EC2 instance instead, it too must have been created using Amazon Linux 2.
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.
-
Encryption-in-transit is enabled by default on Amazon DocumentDB. You can optionally disable TLS. To download the current certificate required to authenticate to your cluster, in the Connectivity & security tab, in the Connect section, under Download the Amazon DocumentDB Certificate Authority (CA) certificate required to authenticate to your cluster, copy the connection string provided. Go back to your AWS Cloud9 environment and paste the connection string.
-
Return to your cluster in the Amazon DocumentDB console, unde Connectivity & security tab, in the Connect section, 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 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.
-
To insert a single document, enter the following:
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). Input the following: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 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:db.profiles.find()
-
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):
{ "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" : 202 }
-
You can verify that his score has changed with the following query:
db.profiles.find({name: "Matt"})
-
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:
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.