Amazon DocumentDB

Introduction

In this tutorial, you will create an Amazon DocumentDB cluster. Operations on the cluster using CLI commands using CLI commands. For more information about Amazon DocumentDB, see Amazon DocumentDB Developer Guide.

Prerequisites

Before starting, you should have the following prerequisites configured

• An AWS account
• AWS CLI on your computer

Amazon DocumentDB tutorial

• Create an Amazon DocumentDB cluster using AWS CLI
• Adding an Amazon DocumentDB instance to a cluster using AWS CLI
• Describing Clusters and Instances using AWS CLI
• Install the mongo shell on MacOS
• Connecting to Amazon DocumentDB
• Performing Amazon DocumentDB CRUD operations using Mongo Shell
• Performing Amazon DocumentDB CRUD operations using python
• Adding a Replica to an Amazon DocumentDB Cluster using AWS CLI
• Amazon DocumentDB High Availability Failover using AWS CLI
• Creating an Amazon DocumentDB global cluster using AWS CLI
• Delete an Instance from a Cluster using AWS CLI
• Delete an Amazon DocumentDB global cluster using AWS CLI
• Removing Global Clusters using AWS CLI

Create an Amazon DocumentDB cluster using AWS CLI

Before you begin, If you have not installed the AWS CLI, see Setting up the Amazon Redshift CLI. This tutorial uses the us-east-1 region.

Now we’re ready to launch a Amazon DocumentDB cluster by using the AWS CLI.

An Amazon DocumentDB cluster consists of instances and a cluster volume that represents the data for the cluster. The cluster volume is replicated six ways across three Availability Zones as a single, virtual volume. The cluster contains a primary instance and, optionally, up to 15 replica instances. 

The following sections show how to create an Amazon DocumentDB cluster using the AWS CLI. You can then add additional replica instances for that cluster.

• When you use the console to create your Amazon DocumentDB cluster, a primary instance is automatically created for you at the same time.
• When you use the AWS CLI to create your Amazon DocumentDB cluster, after the cluster’s status is available, you must then create the primary instance for that cluster.

The following procedures describe how to use the AWS CLI to launch an Amazon DocumentDB cluster and create an Amazon DocumentDB replica.

To create an Amazon DocumentDB cluster, call the create-db-cluster AWS CLI.

aws docdb create-db-cluster \
      --db-cluster-identifier sample-cluster \
      --engine docdb \
      --engine-version 5.0.0 \
      --master-username masteruser \
      --master-user-password masteruser123

The db-subnet-group-name or vpc-security-group-id parameter is not specified, Amazon DocumentDB will use the default subnet group and Amazon VPC security group for the given region.

This command returns the following result.

It takes several minutes to create the cluster. You can use the following AWS CLI to monitor the status of your cluster. 

aws docdb describe-db-clusters \
--filter Name=engine,Values=docdb \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[*].Status'

Adding an Amazon DocumentDB instance to a cluster using AWS CLI

Use the create-db-instance AWS CLI operation with the following parameters to create the primary instance for your cluster.

You can choice instance class from result of following command

aws docdb describe-orderable-db-instance-options --engine docdb --query 'OrderableDBInstanceOptions[*].DBInstanceClass'

aws docdb create-db-instance \
--db-cluster-identifier sample-cluster \
--db-instance-identifier primary-instance \
--db-instance-class db.t3.medium \
--engine docdb

This command returns the following result.

The following AWS CLI command lists the details for Amazon DocumentDB instances in a region.

aws docdb describe-db-instances --db-instance-identifier primary-instance

This command returns the following result.

Describing Clusters and Instances using AWS CLI

To view the details of your Amazon DocumentDB clusters using the AWS CLI, use the describe-db-clusters command. 

The following AWS CLI command list information about the Amazon DocumentDB cluster identification, status, and endpoint.

aws docdb describe-db-clusters --db-cluster-identifier sample-cluster --query 'DBClusters[*].[DBClusterIdentifier,Status,Endpoint]'

This command returns the following result.

Install the mongo shell on MacOS

Install the mongo shell with the following command:

brew tap mongodb/brew
brew install mongosh

To encrypt data in transit, download the public key for Amazon DocumentDB. The following command downloads a file named global-bundle.pem:

cd Downloads
curl -O https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

You must explicitly grant inbound access to your client in order to connect to the cluster. When you created a cluster in the previous step, because you did not specify a security group, you associated the default cluster security group with the cluster.

The default cluster security group contains no rules to authorize any inbound traffic to the cluster. To access the new cluster, you must add rules for inbound traffic, which are called ingress rules, to the cluster security group. If you are accessing your cluster from the Internet, you will need to authorize a Classless Inter-Domain Routing IP (CIDR/IP) address range.

Run the following command to enable your computer to connect to your Redshift cluster. Then login into your cluster using mongo shell.

#get VpcSecurityGroupId
aws docdb describe-clusters --cluster-identifier sample-cluster --query 'DBClusters[*].[VpcSecurityGroups]'

#allow connect to DocumentDB cluster from my computer
aws ec2 authorize-security-group-ingress --group-id sg-083f2ca0560111a3b --protocol tcp --port 27017 --cidr 111.111.111.111/32

This command returns the following result.

Connecting to Amazon DocumentDB

 Run the following command to connect the Amazon DocumentDB cluster

docdbEndpoint=sample-cluster.cluster-cy1qzrkhqwpp.us-east-1.docdb.amazonaws.com:27017
docdbUser=masteruser
docdbPass=masteruser123
mongosh --tls --host $docdbEndpoint --tlsCAFile global-bundle.pem --username $docdbUser --password $docdbPass

This command returns the following result.

Use the below command to view the available databases in the your Amazon DocumentDB cluster

show dbs

Performing Amazon DocumentDB CRUD operations using Mongo Shell

MongoDB database concepts:

• A record in MongoDB is a document, which is a data structure composed of field and value pairs, similar to JSON objects. The value of a field can include other documents, arrays, and arrays of documents. A document is roughly equivalent to a row in a relational database table.
• A collection in MongoDB is a group of documents, and is roughly equivalent to a relational database table.
• A database in MongoDB is a group of collections, and is similar to a relational database with a group of related tables.

To show current database name

db

To create a database in Amazon DocumentDB, execute the use command, specifying a database name. Create a new database called docdbdemo.

use docdbdemo

When you create a new database in Amazon DocumentDB, there are no collections created for you. You can see this on your cluster by running the following command.

show collections

Creating Documents

You will now insert a document to a new collection called products in your docdbdemo database using the below query.

db.products.insert({
  "name":"java cookbook",
  "sku":"222222",
  "description":"Problems and Solutions for Java Developers",
  "price":200
})

You should see output that looks like this

You can insert multiple documents in a single batch to bulk load products. Use the insertMany command below. 

db.products.insertMany([
{
  "name":"Python3 boto",
  "sku":"222223",
  "description":"basic boto3 and python for everyone",
  "price":100
},
{
  "name":"C# Programmer's Handbook",
  "sku":"222224",
  "description":"complete coverage of features of C#",
  "price":100
}
])

Reading Documents

Use the below query to read data inserted to Amazon DocumentDB. The find command takes a filter criteria and returns the document matching the criteria. The pretty command is appended to display the results in an easy-to-read format.

db.products.find({"sku":"222223"}).pretty()

The matched document is returned as the output of the above query.

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

db.products.find().pretty()

Updating Documents

You will now update a document to add reviews using the $set operator with the update command. Reviews is a new array containing review and rating fields.

db.products.update(
  {
    "sku":"222223"
  },
  {
    $set:{    
      "reviews":[
        {
          "rating":4,
          "review":"perfect book"
        },
        {
          "rating":4.5,
          "review":"very good"
        },
        {
          "rating":5,
          "review":"Just love it"
        }
      ]
    }
  }
)

The output indicates the number of documents that were matched, upserted, and modified.

You can read the document modified above to ensure that the changes are applied.

db.products.find({"sku":"222223"}).pretty()

Deleting Documents

You can delete a document using the below code.

db.products.remove({"sku":"222224"})

Performing Amazon DocumentDB CRUD operations using python

Prerequisites

Before starting, you should have the following prerequisites configured

• Install pymongo
• Download source code sample python CRUD

To install pymongo, execute following command on MacOS

pip3 install pymongo

Edit sample_python_documentdb.py

Open sample_python_documentdb.py, edit variable with current DocumentDB value

username = "masteruser"
password = "masteruser@123"
clusterendpoint = "your_endpoint:27017"
tlsCAFile = "global-bundle.pem"

Execute python file

Execute the code and examine the output

python3 sample_python_documentdb.py

Adding a Replica to an Amazon DocumentDB Cluster using AWS CLI

To add an instance to your Amazon DocumentDB cluster, run the following command

aws docdb create-db-instance \
       --db-cluster-identifier sample-cluster \
       --db-instance-identifier instance-2 \
       --availability-zone us-east-1b \
       --promotion-tier 1 \
       --db-instance-class db.t3.medium \
       --engine docdb

The following example returns the DBClusterIdentifier, DBInstanceIdentifier  for sample-cluster

aws docdb describe-db-clusters \
    --db-cluster-identifier sample-cluster \
    --query 'DBClusters[*].[DBClusterIdentifier,DBClusterMembers[*].DBInstanceIdentifier]'

Amazon DocumentDB High Availability Failover using AWS CLI

A failover for a cluster promotes one of the Amazon DocumentDB replicas (read-only instances) in the cluster to be the primary instance (the cluster writer).When the primary instance fails, Amazon DocumentDB automatically fails over to an Amazon DocumentDB replica

The following operation forces a failover of the sample-cluster cluster. 

aws docdb failover-db-cluster --db-cluster-identifier sample-cluster

Creating an Amazon DocumentDB global cluster using AWS CLI

To create an Amazon DocumentDB regional cluster, call the create-db-clusterAWS CLI. The following AWS CLI command creates an Amazon DocumentDB cluster named global-cluster-id

aws docdb create-db-cluster \
--global-cluster-identifier global-cluster-id \
--source-db-cluster-identifier arn:aws:rds:us-east-1:111122223333:cluster-id

Output from this operation looks something like the following

A global cluster needs at least one secondary cluster in a different region than the primary cluster, and you can add up to five secondary clusters. 

I’m not adding a secondary cluster in this tutorial, but to add an AWS Region to an Amazon DocumentDB global cluster you can use:

aws docdb --region us-east-2 \
  create-db-cluster \
    --db-cluster-identifier cluster-id \
    --global-cluster-identifier global-cluster-id \
    --engine-version version

aws docdb --region us-east-2 \
  create-db-instance \
    --db-cluster-identifier cluster-id \
    --global-cluster-identifier global-cluster-id \
    --engine-version version \
    --engine docdb
      

Delete an Instance from a Cluster using AWS CLI

The following procedure deletes an Amazon DocumentDB instance using the AWS CLI.

aws docdb delete-db-instance --db-instance-identifier instance-2

Output from this operation looks something like the following.

Removing Global Clusters using AWS CLI

You can’t delete the global cluster until after you detach all associated clusters, leaving the primary for last. 

To remove a cluster from a global cluster, run the remove-from-global-clusterCLI command with the following parameters:

• --global-cluster-identifier — The name (identifier) of your global cluster.
• --db-cluster-identifier — The name of each cluster to remove from the global cluster.

Example:

aws docdb --region secondary_region \
  remove-from-global-cluster \
    --db-cluster-identifier secondary_cluster_ARN \
    --global-cluster-identifier global_cluster_id

aws docdb --region primary_region \
  remove-from-global-cluster \
    --db-cluster-identifier primary_cluster_ARN \
    --global-cluster-identifier global_cluster_id

In my case

aws docdb remove-from-global-cluster --db-cluster-identifier arn:aws:rds:us-east-1:111122223333:cluster-id --global-cluster-identifier global_cluster_id

To delete a global cluster, run the delete-global-cluster CLI command with the name of the AWS Region and the global cluster identifier, as shown in the following example.

aws docdb –region us-eas-1 delete-global-cluster \
–global-cluster-identifier global_cluster_id

If you also want to delete cluster, run the following command.

#list instance
aws docdb describe-db-clusters \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[].[DBClusterIdentifier,DBClusterMembers[].DBInstanceIdentifier]'

#delete instance
aws docdb delete-db-instance \
    --db-instance-identifier sample-instance

#delete cluster
aws docdb delete-db-cluster \
    --db-cluster-identifier sample-cluster \
    -skip-final-snapshot

Conclusion

These steps provide an example to manage Amazon DocumentDB cluster. The specific configuration details may vary depending on your environment and setup. It’s recommended to consult the relevant documentation from AWS for detailed instructions on setting up. I hope will this your helpful. Thank you for reading the DevopsRoles page!

Refer

https://docs.aws.amazon.com/documentdb/latest/developerguide/what-is.html

https://catalog.us-east-1.prod.workshops.aws/workshops/464d6c17-9faa-4fef-ac9f-dd49610174d3/en-US

https://docs.aws.amazon.com/lambda/latest/dg/with-documentdb-tutorial.html#docdb-prerequisites