How to use AWS CLI to manage Amazon DynamoDB

Andrei Maksimov

Andrei Maksimov

0
(0)

The AWS Command Line Interface (CLI) is a unified tool to manage your AWS services. With just one tool to download and configure, you can control multiple AWS services from the command line and automate them through scripts. This article covers how to use AWS CLI to manage Amazon DynamoDB with lots of hands-on examples that you can use during your day-to-day AWS activities.

AWS CLI Installation

You can install AWS CLI on Windows, macOS, and Linux. In addition to that, Amazon Linux AMI already contains AWS CLI as a part of the OS distribution, so you don’t have to install it manually.

Windows

For modern Windows distributions, we recommend you to use Chocolatey package manager to install AWS CLI:

# AWS CLI
choco install awscli

# Session Manager plugin
choco install awscli-session-manager

# AWS-Shell
choco install python
choco install pip
pip install aws-shell

macOS

To install AWS CLI on macOS, we recommend you to use brew package manager:

# AWS CLI
brew install awscli

# Session Manager plugin
brew install --cask session-manager-plugin

# AWS-Shell
pip install aws-shell

Linux

Depending on your Linux distribution, the installation steps are different.

CentOS, Fedora, RHEL

For YUM-based distributions (CentOS, Fedora, RHEL), you can use the following installation steps:

# AWS CLI
sudo yum update
sudo yum install wget -y
wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum install epel-release-latest-7.noarch.rpm
sudo yum -y install python-pip
sudo pip install awscli

# Session Manager plugin
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm" \
  -o "session-manager-plugin.rpm"
sudo yum install -y session-manager-plugin.rpm

# AWS-Shell
pip install aws-shell

Debian, Ubuntu

For APT-based distributions (Debian, Ubuntu), you can use slightly different installation steps:

# AWS CLI
sudo apt-get install python-pip
sudo pip install awscli

# Session Manager plugin
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" \
  -o "session-manager-plugin.deb"
sudo dpkg -i session-manager-plugin.deb

# AWS-Shell
pip install aws-shell

Other Linux distributions

For other Linux distributions, you can use manual AWS CLI installation steps.

AWS CLI DynamoDB Commands

Usually, you’re using AWS CLI commands to manage DynamoDB when you need to automate DynamoDB operations using scripts or in your CICD automation pipeline. For example, you can configure the Jenkins pipeline to execute AWS CLI commands for any AWS account in your environment.

Managing DynamoDB tables

This section of the article will cover the most common examples of using AWS CLI commands to manage DynamoDB tables.

Create table

To create a DynamoDB table using AWS CLI, you need to use the aws dynamodb create-table command which expects at least four arguments:

  • --table-name – defines the DynamoDB table name
  • --attribute-definitions – a JSON-like definition of all table attributes and their types that you’re going to use in the DynamoDB table and indexes
  • --key-schema – specifies the attributes that make up the primary key for a table or an index (partition or sort keys)
  • --billing-mode – Controls how you are charged for read and write throughput and how you manage capacity. Allowed values: PROVISIONED and PAY_PER_REQUEST.

Let’s create a simple AWS demo DynamoDB table to store demo product catalog items.

Table namePrimary Key
ProductCatalogPartition key: Id (Number)

To create this DynamoDB table, use the following AWS CLI command:

aws dynamodb create-table \
    --table-name ProductCatalog \
    --attribute-definitions AttributeName=id,AttributeType=N \
    --key-schema AttributeName=id,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST

Note: it is recommended to use PAY_PER_REQUEST billing mode only for brand new tables when you don’t know the table’s scaling capacity upfront.

How to use AWS CLI to manage Amazon DynamoDB - Create table (simple index)

As a result, you’ll get the following DynamoDB table in your AWS console:

How to use AWS CLI to manage Amazon DynamoDB - Create simple DynamoDB table

Now, let’s create a DynamoDB table for storing users’ accounts with the composite index.

Table namePrimary Key
MyWebsiteUsersPartition key: user_id (String)
Sort key: created_at (String)

In the example below, we’ll use another billing mode where we’ll specify the exact amount of the read and write capacity units for the table:

aws dynamodb create-table \
    --table-name MyWebsiteUsers \
    --attribute-definitions AttributeName=user_id,AttributeType=S AttributeName=created_at,AttributeType=S \
    --key-schema AttributeName=user_id,KeyType=HASH AttributeName=created_at,KeyType=RANGE \
    --billing-mode PROVISIONED \
    --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5
How to use AWS CLI to manage Amazon DynamoDB - Create DynamoDB table with composite index (terminal)

As a result, you’ll get the following DynamoDB table in your AWS console:

How to use AWS CLI to manage Amazon DynamoDB - Create DynamoDB table with composite index

You can specify arguments’ values in a JSON syntax too. The following command will produce the same result as we got from the previous command execution:

aws dynamodb create-table \
    --table-name MyWebsiteUsers \
    --attribute-definitions '[{"AttributeName":"user_id", "AttributeType":"S"}, {"AttributeName":"created_at", "AttributeType":"S"}]' \
    --key-schema '[{"AttributeName":"user_id", "KeyType":"HASH"}, {"AttributeName":"created_at", "KeyType":"RANGE"}]' \
    --billing-mode PROVISIONED \
    --provisioned-throughput '{"ReadCapacityUnits": 5, "WriteCapacityUnits": 5}'

List tables

To list DynamoDB tables using AWS CLI, you need to use the aws dynamodb list-tables command:

aws dynamodb list-tables
How to use AWS CLI to manage Amazon DynamoDB - List tables command

Describe table

To describe the DynamoDB table using AWS CLI, you need to use the aws dynamodb describe-table command with the required --table-name argument. This command will return the table key schema, capacity mode, provisioned WCU and RCU, amount of items stored in the table, table status, consumed storage space, and much more.

aws dynamodb describe-table \
    --table-name MyWebsiteUsers
How to use AWS CLI to manage Amazon DynamoDB - Describe table command

Delete table

To delete DynamoDB Table using AWS CLI, you need to use the aws dynamodb delete-table command with the required --table-name argument:

aws dynamodb delete-table \
    --table-name ProductCatalog

Note: this command removes the table, data, and related DynamoDB Streams.

Note: it might take a while to delete your table and its data; meanwhile, the table will be in the DELETING state.

How to use AWS CLI to manage Amazon DynamoDB - Delete table

Backup table

To backup the DynamoDB table using AWS CLI, you need to use the aws dynamodb create-backup command with two required arguments:

  • --table-name – specifies the DynamoDB table to backup
  • --backup-name – specifies the name of the to backup
aws dynamodb create-backup \
    --table-name ProductCatalog \
    --backup-name ProductCatalog-backup-$(date +"%m-%d-%Y")

Note: Check additional date command format options here.

The command above will request a full, on-demand backup of your DynamoDB table. The backup will contain all the data, table key structure, LSIs and GSIs, and information about streams and provisioned read and write capacity.

DynamoDB backup is an asynchronous operation and does not consume any of the provisioned throughputs.

How to use AWS CLI to manage Amazon DynamoDB - Backup table command

List table backups

To list DynamoDB table backups using AWS CLI, you need to use the aws dynamodb list-backups command with --table-name argument.

The following command will list all on-demand backups initiated by the user or DynamoDB itself:

aws dynamodb list-backups \
    --table-name ProductCatalog
How to use AWS CLI to manage Amazon DynamoDB - List backups command

To specify the type of backup, you need to use the --backup-type argument, which accepts the following values:

  • USER – On-demand backup created by you.
  • SYSTEM – On-demand backup automatically created by DynamoDB.
  • ALL – All types of on-demand backups (USER and SYSTEM).

In addition to that, you can use the --time-range-lower-bound and --time-range-upper-bound arguments to list backups between two dates (in epoch format). It is convenient to use the date command to convert date time to the timestamp:

# Linux
aws dynamodb list-backups \
    --table-name ProductCatalog \
    --time-range-lower-bound $(date -d '12/14/2021 14:30:00' +"%s") \
    --time-range-upper-bound $(date -d '12/14/2021 20:00:00' +"%s") \
    --backup-type USER

# macOS
aws dynamodb list-backups \
    --table-name ProductCatalog \
    --time-range-lower-bound $(date -jf "%Y-%m-%d %H:%M:%S" "2021-12-14 14:30:00" +%s) \
    --time-range-upper-bound $(date -jf "%Y-%m-%d %H:%M:%S" "2021-12-14 20:00:00" +%s) \
    --backup-type USER
How to use AWS CLI to manage Amazon DynamoDB - List backups time range command

Describe table backup

To describe the DynamoDB table backup using AWS CLI, you need to use the aws dynamodb describe-backup command with --backup-arn argument:

aws dynamodb describe-backup \
    --backup-arn arn:aws:dynamodb:us-east-1:585584209241:table/ProductCatalog/backup/01639513066901-b635e30a
How to use AWS CLI to manage Amazon DynamoDB - Describe backup command

Restore table from backup

To restore the DynamoDB table from the backup using AWS CLI, you need to use the aws dynamodb restore-table-from-backup command, which requires the --target-table-name and --backup-arn arguments:

aws dynamodb restore-table-from-backup \
    --target-table-name ProductCatalog-restored \
    --backup-arn arn:aws:dynamodb:us-east-1:585584209241:table/ProductCatalog/backup/01639513066901-b635e30a

DynamoDB the restore table from the backup operation does not set up table tags, autoscaling settings, streams, TTL, and CloudWatch Metrics.

How to use AWS CLI to manage Amazon DynamoDB - Restore table from backup command

Managing DynamoDB table items

This section of the article will cover the most common examples of using AWS CLI commands to manage DynamoDB items.

Put item

To insert (put) an item to the DynamoDB table using AWS CLI, you need to use the aws dynamodb put-item command.

You can provide the item information in the form of JSON data structure in the terminal:

aws dynamodb put-item \
    --table-name ProductCatalog \
    --item '{"id": {"N": "100"}, "Title": {"S": "My-Product"}}'
How to use AWS CLI to manage Amazon DynamoDB - Put item

Alternatively, you can put the same JSON content of the DynamoDB item to the file (for example, item.json):

{"id": {"N": "100"}, "Title": {"S": "My-Product"}}

And insert it from the JSON file:

aws dynamodb put-item \
    --table-name ProductCatalog \
    --item file://item.json

Note: if the new item has the same primary key as one of the already existing items, an existing item with the same primary key will be completely overridden by the newly provided item.

Put multiple items (batch write item)

To write multiple items to DynamoDB at once using AWS CLI, you need to use the aws dynamodb batch-write-item command and provide it a list of items for PutRequest or DeleteRequest operations in the JSON format using --request-items argument.

The best way of doing this, is to create a JSON file (request.json) with the requested changes:

{
    "ProductCatalog": [
        {
            "PutRequest": {
                "Item": {
                    "id": {"N": "100"},
                    "Title": {"S": "My-Product"}
                }
            }
        },
        {
            "PutRequest": {
                "Item": {
                    "id": {"N": "101"},
                    "Title": {"S": "My-Product-1"}
                }
            }
        },
        {
            "PutRequest": {
                "Item": {
                    "id": {"N": "102"},
                    "Title": {"S": "My-Product-2"}
                }
            }
        }
    ]
}

Now, you can run the following command to apply changes:

aws dynamodb batch-write-item \
    --request-items file://request.json

Here’s an execution output:

How to use AWS CLI to manage Amazon DynamoDB - Batch write item

Get all items (Scan operation)

To get all items from the DynamoDB table using AWS CLI, you need to use the aws dynamodb scan command with at least --table-name argument provided:

aws dynamodb scan \
    --table-name ProductCatalog

Here’s an execution output:

How to use AWS CLI to manage Amazon DynamoDB - Get all items (scan)

Note: you can use the --starting-token argument to query the next chunk of scanned data if your request is returning more data than specified.

How to use AWS CLI to manage Amazon DynamoDB - Get all items (scan) with paging

Get single item

To get a single item from DynamoDB using AWS CLI, you need to use the aws dynamodb get-item command with the --key argument:

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"id": {"N": "102"}}' \
    --consistent-read

Note: you can use the optional --consistent-read argument to do a consistent read from the table.

How to use AWS CLI to manage Amazon DynamoDB - Get single item

Delete item

To delete an item from DynamoDB using AWS CLI, you need to use aws dynamodb delete-item command with the required --key argument.

aws dynamodb delete-item \
    --table-name NameOfTheTable \
    --key '{"id": {"N": "102"}}'
How to use AWS CLI to manage Amazon DynamoDB - Delete single item by key

You can use the --condition-expression and --expression-attribute-values arguments to delete items based on conditions. For more information, check out Condition Expressions documentation.

aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"id": {"N": "101"}}' \
    --condition-expression 'attribute_not_exists(Title)'

Note: if the condition expression is not satisfied, you’ll get the following error message: An error occurred (ConditionalCheckFailedException) when calling the DeleteItem operation: The conditional request failed.

How to use AWS CLI to manage Amazon DynamoDB - Delete single item with condition

In our example, the first command failed, because the DynamoDB item had an existing Title attribute.

Query set of items

To query items from DynamoDB using AWS CLI, you need to use the aws dynamodb query command. You can query any DynamoDB table by the primary or secondary indexes:

aws dynamodb query \
    --table-name ProductCatalog \
    --key-condition-expression "id = :id" \
    --expression-attribute-values '{":id": {"N": "101"}}'
How to use AWS CLI to manage Amazon DynamoDB - Query item by index

A couple of notes:

  • If you want to narrow down the query results on a non-index attribute, you can combine it with --filter-expression argument which acts in the same way as --condition-expression argument of the aws dynamodb delete-item command
  • The --filter-expression argument is applied after the items have already been read and the process of filtering does not reduce consumed read capacity units

Update item

To update the DynamoDB item using AWS CLI, you need to use the aws dynamodb update-item command.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"id":{"N":"101"}}' \
    --update-expression "SET Title = :t" \
    --expression-attribute-values '{":t": { "S": "Updated-Title" }}' \
    --return-values ALL_NEW
How to use AWS CLI to manage Amazon DynamoDB - Update item

If you’d like to add additional attributes during the update operation, you need to specify them too:

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"id":{"N":"101"}}' \
    --update-expression "SET Title = :t, Description = :d" \
    --expression-attribute-values '{":t": { "S": "Updated-Title" }, ":d": {"S": "My description"}}' \
    --return-values ALL_NEW
How to use AWS CLI to manage Amazon DynamoDB - Add attribute to existing item

Increment item attribute

To update the DynamoDB item using AWS CLI, you need to use the aws dynamodb update-item command, but instead of using update-expression and expression-attribute-values use the attribute-updates shorthand:

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"id":{"N":"102"}}' \
    --attribute-updates '{"amount_of_items": {"Value": {"N": "1"},"Action": "ADD"}}' \
    --return-values ALL_NEW
How to use AWS CLI to manage Amazon DynamoDB - Increment item attribute

Summary

In this article, we’ve covered how to use AWS CLI to manage Amazon DynamoDB with lots of hands-on examples that you can use during your day-to-day AWS activities.

How useful was this post?

Click on a star to rate it!

As you found this post useful...

Follow us on social media!

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?

Like this article?

Share on facebook
Share on Facebook
Share on twitter
Share on Twitter
Share on linkedin
Share on Linkdin
Share on pinterest
Share on Pinterest

Want to be an author of another post?

We’re looking for skilled technical authors for our blog!

Leave a comment

If you’d like to ask a question about the code or piece of configuration, feel free to use https://codeshare.io/ or a similar tool as Facebook comments are breaking code formatting.