Get Started with Amazon DocumentDB - Amazon DocumentDB
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

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 Amazon Cloud9, a web-based terminal to connect and query your Amazon DocumentDB cluster using the mongo shell directly from the Amazon Web Services Management Console. New customers who are eligible for the Amazon Free Tier can use Amazon DocumentDB and Amazon Cloud9 for free. If your Amazon Cloud9 environment or Amazon DocumentDB cluster makes use of resources beyond the free tier, you are charged the normal Amazon rates for those resources. This guide will get you started with Amazon DocumentDB in less than 15 minutes.

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


Before you create your first Amazon DocumentDB cluster, you must do the following:

Create an Amazon Web Services (Amazon) account

Before you can begin using Amazon DocumentDB, you must have an Amazon Web Services (Amazon) account. The Amazon account is free. You pay only for the services and resources that you use.

If you do not have an Amazon Web Services account, use the following procedure to create one.

To sign up for Amazon Web Services
  1. Open and choose Sign Up.

  2. Follow the on-screen instructions.

Set up the needed Amazon Identity and Access Management (IAM) permissions.

Access to manage Amazon DocumentDB resources such as clusters, instances, and cluster parameter groups requires credentials that Amazon can use to authenticate your requests. For more information, see Identity and Access Management in Amazon DocumentDB.

  1. In the search bar of the Amazon Web Services Management Console, type in IAM and select IAM in the drop down menu that appears.

  2. Once you're in the IAM console, select Users from the navigation pane.

  3. Select your username.

  4. Click the button Add permissions.

  5. Select Attach existing policies directly.

  6. Type AmazonDocDBFullAccess in the search bar and select it once it appears in the search results.

  7. Click the blue button at the bottom that says Next: Review.

  8. 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 Amazon Cloud9 environment

Amazon Cloud9 provides a web-based terminal that you can use to connect to and query your Amazon DocumentDB cluster using the mongo shell.

  1. From the Amazon Web Services Management Console navigate to the Amazon Cloud9 console and choose Create environment.

  2. In the Environment name and description section, in the Name field, enter DocumentDBCloud9.

  3. Choose Next step.

  4. In the Configure settings section, choose Next step.

  5. In the Review section, choose Create environment.


The provisioning of the Amazon 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 Amazon Cloud9 environment.

  1. On the Amazon EC2 Management Console, under Network and Security, choose Security groups.

  2. Choose Create security group.

  3. In the Basic details box, input the following for each field:

    • For Security group name, enter demoDocDB.

    • For Description, enter a description.

    • For VPC, accept the usage of your default VPC.

  4. In the Inbound rules section, choose Add rule.

  5. For Type, choose Custom TCP Rule.

  6. For Port range, enter 27017.

  7. The source is the security group for the Amazon 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>.

  8. Accept all other defaults and choose Create security group.


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.

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

  2. 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.

  3. In the Authentication section, enter a username and password.

  4. Turn on Show advanced settings.

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

  6. 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.

Step 4: Install the mongo shell

You will now install the mongo shell in your Amazon 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.

  1. If your Amazon Cloud9 environment is still open from Step 1, go back to that environment and skip to instruction 3. If you navigated away from you Amazon Cloud9 environment, in the Amazon Cloud9 management console, under Your environments, find the environment labeledDocumentDBCloud9. Choose Open IDE.

  2. At the command prompt, create the repository file with the following command:

    echo -e "[mongodb-org-4.0] \nname=MongoDB Repository\nbaseurl=\ngpgcheck=1 \nenabled=1 \ngpgkey=" | sudo tee /etc/yum.repos.d/mongodb-org-4.0.repo
  3. When it is complete, install the mongo shell with the following command:

    sudo yum install -y mongodb-org-shell
  4. To encrypt data in transit, download the public key for Amazon DocumentDB from This operation downloads a file named 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.

  1. On the Amazon DocumentDB management console, under Clusters, locate your cluster. Choose the cluster you created by clicking on the cluster identifier.

  2. 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.

  3. Go back to your Amazon 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.


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.

  1. To insert a single document, enter the following:

  2. You get the following output:

    WriteResult({ "nInserted" : 1 })

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

  4. You get the following output:

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

  5. 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} ])
  6. You get the following output:

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

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

  8. You will get an output that will match the data you typed in Step 5.

  9. Use a query for a single document using a filter. Input the following:

    db.profiles.find({name: "Katie"})
  10. You should get back this output:

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

  11. 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 } } })
  12. You get the following output (note that his score hasn’t increased yet):

    { "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" : 202 }
  13. You can verify that his score has changed with the following query:

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

  14. 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:


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.