Get Started with Amazon DocumentDB - Amazon DocumentDB

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.

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

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

  1. In the search bar of the AWS 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 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.

  1. From the AWS Management Console navigate to the AWS Cloud9 console and choose Create environment.

  2. In the Details section of the Create environment dialog, enter DocumentDBCloud9 in the Name field.

  3. For the New EC2 instance, Network settings, and Tags sections, leave the default setting as they are and click Create at the bottom of the screen.

Your new AWS Cloud9 environment appears in the Environments table:

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.

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

  2. Choose Create security group.

  3. In the Basic details section:

    1. For Security group name, enter demoDocDB.

    2. For Description, enter a description.

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

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

    1. For Type, choose Custom TCP Rule.

    2. For Port range, enter 27017.

    3. For Source, choose the security group for the AWS Cloud9 environment you just created. To see a list of available security groups, enter cloud9 in the search field on the right side to the Source field. Choose the security group with the name aws-cloud9-<environment name>.

    4. For Destination, choose Custom. In the field next to it, search for the security group you just made called demoEC2. You may need to refresh your browser for the Amazon EC2 console to auto-populate the demoEC2 source name.

    Note

    Port 27017 is the default port for Amazon DocumentDB.

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

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

  2. On the Create Amazon DocumentDB cluster page, in the Cluster type section, choose Instance Based Clusters (this is the default option).

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

  4. For Connectivity, leave the default setting of Don't connect to an EC2 compute resource.

  5. In the Authentication section, enter sign-in credentials.

  6. Turn on Show advanced settings.

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

  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.

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.

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

  2. 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
  3. When it is complete, install the mongo shell with the following command:

    sudo yum install -y mongodb-org-shell

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

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

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

    db.collection.insert({"hello":"DocumentDB"})
  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:

    db.collection.findOne()
  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:

    db.profiles.find()
  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:

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.