AWS Database Blog

Getting started with Amazon DocumentDB (with MongoDB compatibility); Part 3 – using Robo 3T

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 3 of this series, this post shows you how you get started with Amazon DocumentDB and Robo 3T (formerly Robomongo). Robo 3T is a lightweight, open-source, shell centric, cross-platform graphical user interface tool for managing MongoDB workloads. Robo 3T makes you more efficient by giving you the ability to create databases, collections, add users, documents, execute one-time queries with auto-completion, and visualize results from a GUI interface.

For this post, you create a single instance Amazon DocumentDB cluster inside your VPC, an EC2 Linux VM in the same VPC, set up an SSH tunnel between the two, connect to your cluster using Robo 3T, and run a few queries from your local computer. The following diagram shows the final architecture of this walkthrough.

Creating an Amazon DocumentDB cluster

You can create an Amazon DocumentDB cluster using the AWS Command Line Interface (AWS CLI) or the AWS Management Console. If you have an existing cluster, skip this step.

Creating your cluster with AWS CLI

To create a cluster using the AWS CLI with smart defaults, use the following code for Linux, macOS, or Unix:

aws docdb create-db-cluster \
      --db-cluster-identifier sample-cluster \
      --engine docdb \
      --deletion-protection \
      --master-username master-user \
      --master-user-password password

For Windows, enter the following code:

aws docdb create-db-cluster ^
      --db-cluster-identifier sample-cluster ^
      --engine docdb ^
      --deletion-protection ^
      --master-username master-user ^
      --master-user-password password

Creating your cluster on the console

To create your cluster on the console with the smart defaults, complete the following steps:

  1. On the Amazon DocumentDB console, under Clusters, choose Create.
  2. On the Create Amazon DocumentDB cluster page, for Number of instances, choose 1 to minimize costs.
  3. Leave other settings at their default.
  4. In the Authentication section, enter a username and password.
  5. Choose Create cluster.
  6. Enable inbound connection for your cluster’s security group.
    To add an inbound connection to your cluster’s security group

    • a. Sign in to the AWS Management Console and open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
    • b. In the Resources section of the main window, choose Security groups.
    • c. From the list of security groups locate the security group you used when creating your cluster (it is most likely the defaultsecurity group) and choose the box to the left of the security group’s name.
    • d. From the Actions menu, choose Edit inbound rules then choose or enter the rule constraints.
      • Type—From the list, choose the protocol to open to network traffic.
      • Protocol—From the list, choose the type of protocol.
      • Port Range—For a custom rule, enter a port number or port range. Be sure that the port number or range includes the port you specified when you created your cluster (default: 27017).
      • Source—Specifies the traffic that can reach your instance. From the list, choose the traffic source. If you choose Custom, specify a single IP address or an IP address range in CIDR notation (e.g., 203.0.113.5/32).
      • Description—Enter a description for this rule.
      • When finished creating the rule, choose Save.

Launch an EC2 Instance

Amazon DocumentDB clusters are deployed within an Amazon Virtual Private Cloud (Amazon VPC). They can be accessed directly by Amazon Elastic Compute Cloud (Amazon EC2) instances or other AWS services that are deployed in the same Amazon VPC. To connect to your cluster using Robo 3T from your client machine (Windows, macOS, Linux), you need a Linux EC2 instance in the same VPC and security group as your DocumentDB cluster. Later in the walkthrough, we will create an SSH tunnel from your laptop to your cluster via your EC2 instance. You can either use an existing EC2 instance in the same VPC and security group as your cluster or create a free Linux EC2 instance in the same VCP and security group as your cluster. For more information, see Getting Started with Amazon EC2 Linux Instances.

Connecting using Robo 3T

If you don’t have Robo 3T, you can download it. As of this writing, the latest Robo 3T version is 1.3. You can skip this step if you already have Robo 3T.

  1. Open Robo 3T and choose Create.
  2. Copy the cluster endpoint from the cluster.
  3. On the Connection tab, enter the cluster endpoint information.
  4. On the Authentication tab, enter the authentication information for your cluster. Make sure to use a custom database name like ‘test’ or ‘testdb’. Using ‘admin’ (default setting) does not work for DocumentDB for clusters with no databases. Once you have created your first database you can modify your connection to use ‘admin’.
  5. On the SSH tab, check the box for ‘Use SSH tunnel’, and add the SSH address, username, and private key/password of your EC2 instance. The SSH address is the public DNS of your EC2 instance. If you used a private key to create your EC2 instance, use the same key for your Robo 3T SSH tunnel. You can get the SSH address, username and private key from the AWS EC2 console. If you are on Linux/macOS client machine, you might have to change the permissions of your private key using the following command: 
    > chmod 400 /fullPathToYourPemFile/<yourKey>.pem

  6. On the SSL tab, and add the Amazon DocumentDB certificate.
    Note
    If you are on macOS Catalina or above, choose Self-signed Certificate as the Authentication Method because the macOS does not accept certificates with validity greater than 825 days.

    You can download the certificate with the following command:

    > wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

    If you do not have wget, you can also download the certificate by going to the URL directly from your web browser.

  7. Select Advanced Options.
  8. For Invalid Hostnames, choose Allowed.
  9. Test the connection by choosing Test.

    A Diagnostic window opens with the test results.
  10. Choose Close.
  11. Choose Save.
  12. Choose your cluster and choose Connect.
  13. Under the drop-down menu for your cluster, under Collections, choose Create Collection.
  14. Choose Insert Document and insert a document.
  15. Run your first Amazon DocumentDB query from Robo 3T.

For more information on Robo 3T’s capabilities, see the GitHub repo.

Cleaning up

When you complete the walkthrough, you can either stop your Amazon DocumentDB cluster to reduce costs or delete the cluster.

Summary

This post showed you how to get started with Amazon DocumentDB using Robo 3T. By establishing a connection to your Amazon DocumentDB cluster from Robo 3T, you can now create a database, collection, and indexes; insert documents; and query them from a single tool. For more advanced features such as in-place query editing, SQL query over MongoDB, visual query builder, aggregation editor, and schema explorer, check out Studio 3T.

For more information on getting started with Amazon DocumentDB from your local machine, see Getting started with Amazon DocumentDB (with MongoDB compatibility); Part 1 – using Amazon EC2 and Getting Started with Amazon DocumentDB (with MongoDB compatibility); Part 2 – using AWS Cloud9. For more information about recent launches and blog posts, see Amazon DocumentDB (with MongoDB compatibility) resources.

 

 

About the Author

 

Meet Bhagdev is a Sr. Product Manager with Amazon Web Services