Amazon DynamoDB CLI - The Complete Guide

Amazon DynamoDB is a fully managed NoSQL database service by AWS that delivers fast and predictable performance with seamless scalability. With its ability to handle massive amounts of data and support high-traffic applications, DynamoDB has become an essential tool for many developers and businesses.

This guide aims to help you effectively utilize the Amazon DynamoDB Command Line Interface (CLI) to manage your database, covering topics such as installation, configuration, basic and advanced CLI commands, and everything backed by many examples.

By the end of this guide, you'll be well-equipped to harness the full power of DynamoDB CLI to improve your workflow and manage your database with ease.

Getting Started

You need to install the AWS CLI and set up your credentials on your local machine before using the sync command. It's important to note that this guide only covers the minimal setup using an AWS Access Key ID and Secret Key, and doesn't include AWS profiles or Multi-Factor authentication. To ensure security, it's recommended that you don't use your root credentials for your daily work. Instead, create a dedicated IAM user with restricted permissions, enable MFA for your root user, delete any Access Keys, and store the credentials safely.

Installing the AWS CLI

Install the latest version of the AWS CLI by adhering to the documentation specific to your operating system.

If you are using macOS, you can easily install the CLI through Homebrew by executing the command: brew install awscli.

The AWS CLI is a comprehensive tool that allows you to manage AWS resources programmatically, control services from your terminal, and automate processes using scripts.

Configuring AWS Credentials

To access the AWS API using our newly installed tool, we must configure our account details. Please navigate to your Security Credentials page.

To create a new Access Key ID and Secret Access Key, click on "Create Access Key". Make sure to note down both keys before closing the creation window, as the Secret Access Key cannot be retrieved later.

Return to your terminal and execute aws configure. Then, follow the prompts to input your keys, default region (e.g. eu-west-1), and default output format (e.g. json).

To confirm that everything is working properly, run aws sts get-caller-identity. If you see your unique 12-digit account identifier without any errors, then everything is set up correctly.

DynamoDB CLI Basics

After setting up the command line interface, our next step is to delve into the specifics of the DynamoDB CLI.

Overview of Important DynamoDB CLI Commands

Here are some of the important AWS DynamoDB CLI commands:

1. aws dynamodb create-table: Creates a new table in DynamoDB.

2. aws dynamodb update-table: Update an existing table in DynamoDB.

3. aws dynamodb delete-table: Deletes an existing table in DynamoDB.

4. aws dynamodb list-tables: Lists all the tables in DynamoDB.

5. aws dynamodb describe-table: Provides a detailed description of an existing table in DynamoDB.

6. aws dynamodb get-item: Retrieves a single item from an existing table in DynamoDB.

7. aws dynamodb query: Retrieves one or more items from a table based on a query condition.

8. aws dynamodb scan: Retrieves all the items in a table.

9. aws dynamodb put-item: Adds a new item to an existing table in DynamoDB.

10. aws dynamodb update-item: Modifies an existing item in a table.

11. aws dynamodb delete-item: Deletes an existing item from a table.

Note: These are just a few of the most commonly used commands. There are many more commands available for DynamoDB in the AWS CLI documentation.

We will delve into each of these commands in greater detail in the following paragraphs.

Listing, Creating, Describing, and Deleting Tables using CLI

Using the AWS DynamoDB CLI, you can easily list, create, and delete tables in your DynamoDB database.

The aws dynamodb list-tables command allows you to view a list of all the tables in your database.

# querying for our tables
# you can specify the region via `--region`
# else the default will be used
aws dynamodb list-tables --region eu-central-1

# the response will include a list of all tables
{
    "TableNames": [
        "TableA",
        "TableB",
        "TableC"
    ]
}

When creating a new table, you can use the aws dynamodb create-table command and specify the table name, primary key, and any other optional parameters.

aws dynamodb create-table \
    --table-name MyTable \
    --attribute-definitions AttributeName=MyAttribute,AttributeType=S \
    --key-schema AttributeName=MyAttribute,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST

This command creates a new DynamoDB table named MyTable with a single attribute named MyAttribute of type string.

The attribute is also used as the hash key for the table. Finally, the --billing-mode flag is set to PAY_PER_REQUEST, which means that you only pay for the read-and-write requests that you make to the table. Alternatively, you can also select the provisioned capacity mode for the table.

aws dynamodb create-table \
    --table-name MyTable \
    --attribute-definitions AttributeName=MyAttribute,AttributeType=S \
    --key-schema AttributeName=MyAttribute,KeyType=HASH \
    --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5

Note: With the AWS Free Tier, you will receive 25 write capacity units (WCU) and 25 read capacity units (RCU). This covers a significant amount of read and write capacity per second. To learn more about DynamoDB's pricing, please refer to our comprehensive guide.

If you need to delete a table, you can use the aws dynamodb delete-table command and specify the table name. It's important to note that once a table is deleted, all of its data is permanently lost and cannot be recovered. Therefore, it's crucial to use caution when deleting tables and ensure that you have a backup of your data before doing so.

aws dynamodb delete-table --table-name MyTable

The aws dynamodb describe-table command is used to retrieve information about a specific DynamoDB table.

The command takes a single parameter, --table-name, which specifies the name of the table to describe.

aws dynamodb describe-table --table-name MyTable

Example response

{
    "Table": {
        "AttributeDefinitions": [
            {
                "AttributeName": "MyAttribute",
                "AttributeType": "S"
            }
        ],
        "TableName": "MyTable",
        "KeySchema": [
            {
                "AttributeName": "MyAttribute",
                "KeyType": "HASH"
            }
        ],
        "TableStatus": "ACTIVE",
        "CreationDateTime": "2021-01-16T19:10:28.752000+01:00",
        "ProvisionedThroughput": {
            "LastDecreaseDateTime": "2021-01-16T19:10:44.163000+01:00",
            "NumberOfDecreasesToday": 0,
            "ReadCapacityUnits": 1,
            "WriteCapacityUnits": 1
        },
        "TableSizeBytes": 400,
        "ItemCount": 4,
        "TableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/MyTable",
        "LocalSecondaryIndexes": [],
        "GlobalSecondaryIndexes": []
    }
}

This response contains detailed information about the MyTable DynamoDB table, including its attribute definitions, key schema, provisioned throughput, and other metadata.

Querying and Scanning Tables

The query command is used to retrieve one or more items from a DynamoDB table that match a specific partition key value (and optional range key value).

Here's an example command for querying a table named MyTable for all items with a partition key value of 123:

aws dynamodb query \
    --table-name MyTable \
    --key-condition-expression "MyPartitionKey = :val" \
    --expression-attribute-values '{ ":val": { "S": "123" } }'

The --key-condition-expression parameter specifies the condition that the partition key value must match, and the --expression-attribute-values parameter provides the actual value to match against.

Here's an example response that you might see after running the command:

{
    "Items": [
        {
            "MyPartitionKey": {
                "S": "123"
            },
            "MyAttribute": {
                "S": "Hello, world!"
            }
        },
    ],
    "Count": 1,
    "ScannedCount": 6,
    "LastEvaluatedKey": {
        "MyPartitionKey": {
            "S": "123"
        }
    }
}

The get-item command is used to retrieve a single item from a DynamoDB table by its primary key.

Here's an example command for getting an item with a partition key value of "123" and a sort key value of abc from a table named MyTable:

aws dynamodb get-item \
    --table-name MyTable \
    --key '{ "MyPartitionKey": { "S": "123" }, "MySortKey": { "S": "abc" } }'

The --key parameter specifies the primary key of the item to retrieve. In our case, our table has not only a partition key but also a range key. Instead of requiring a unique partition key, only the combination of the partition and range keys needs to be unique.

Here's an example response that you might see after running the command:

{
    "Item": {
        "MyPartitionKey": {
            "S": "123"
        },
        "MySortKey": {
            "S": "abc"
        },
        "MyAttribute": {
            "S": "Hello, world!"
        }
    }
}

The scan command is used to retrieve one or more items from a DynamoDB table by scanning the entire table. Be aware that the Scan command will simply iterate through all the table's items until it finds a match.

The scan command is not only slow but also costly, as you will be charged for every scanned item rather than only for the matched results, as you would with a query operation.

aws dynamodb scan \
    --table-name MyTable \
    --filter-expression "MyAttribute = :val" \
    --expression-attribute-values '{":val": {"S": "Hello"}}'

This response contains an array of items that were retrieved by the scan, as well as metadata about the scan results.

{
    "Items": [
        {
            "MyPartitionKey": {
                "S": "123"
            },
            "MySortKey": {
                "S": "abc"
            },
            "MyAttribute": {
                "S": "Hello, world!"
            }
        },
        {
            "MyPartitionKey": {
                "S": "456"
            },
            "MySortKey": {
                "S": "def"
            },
            "MyAttribute": {
                "S": "Goodbye, world!"
            }
        }
    ],
    "Count": 2,
    "ScannedCount": 2,
    "LastEvaluatedKey": {
        "MyPartitionKey": {
            "S": "456"
        },
        "MySortKey": {
            "S": "def"
        }
    }
}

Note that the LastEvaluatedKey parameter is included in the response, which indicates that there are more items in the table that were not retrieved by this scan.

Inserting, Updating, and Deleting Items Using CLI

The put-item command is used to create a new item or replace an existing item in a DynamoDB table.

aws dynamodb put-item \
    --table-name MyTable \
    --item '{ "MyPartitionKey": {"S": "123"}, "MyAttribute": {"S": "Hello, world!"} }'

The --item parameter indicates the attributes of the new item to be added. The response will include metadata regarding the used capacity.

{
    "ConsumedCapacity": {
        "TableName": "MyTable",
        "CapacityUnits": 1
    }
}

The update-item command is used to modify one or more attributes of an existing item in a DynamoDB table.

aws dynamodb update-item \
    --table-name MyTable \
    --key '{ "MyPartitionKey": { "S": "123" } }' \
    --update-expression "SET MyAttribute = :val" \
    --expression-attribute-values '{ ":val": { "S": "Goodbye, world!" } }'

Our example updates the field MyAttribute of an item in the MyTable table that has a partition key value of 123.

• the --update-expression parameter specifies the modification to make

• the --expression-attribute-values parameter provides the new value to set.

{
    "Attributes": {
        "MyAttribute": {
            "S": "Goodbye, world!"
        }
    },
    "ConsumedCapacity": {
        "TableName": "MyTable",
        "CapacityUnits": 1
    }
}

This response contains the updated attributes of the item, as well as information about the capacity units consumed by the update-item request.

The delete-item command is used to remove an existing item from a DynamoDB table. Here's an example command for deleting an item from a table named "MyTable":

aws dynamodb delete-item \
    --table-name MyTable \
    --key '{ "MyPartitionKey": { "S": "123" } }'

The --key parameter specifies the primary key of the item to delete.

{
    "Attributes": {
        "MyPartitionKey": {
            "S": "123"
        }
    },
    "ConsumedCapacity": {
        "TableName": "MyTable",
        "CapacityUnits": 1
    }
}

This response contains the attributes of the deleted item, as well as information about the capacity units consumed by the delete-item request.

Advanced DynamoDB CLI Commands

We have covered the essential commands for daily use. However, there are additional advanced commands that can assist you in accomplishing various objectives.

Atomic Updates

If you're running a multi-tenant application or any application where there is a possibility that a single record can be updated by parallel processes, it's essential to consider thread safety.

In our example, two functions simultaneously read the same state for an object and subsequently update the same field. As a result of this concurrent processing, one update is immediately lost because both functions are unaware of each other's simultaneous operations.

With DynamoDB, we can ensure atomic updates that ensure the integrity of our data. To atomically update a field in DynamoDB, you can use the update-item command with the --update-expression option.

The --update-expression option allows you to specify the update operation you want to perform on the item. To atomically update a field, you can use the SET operation together with condition expression, e.g. by explicitly comparing a field with an expected value. We can also use comparator functions like attribute_exists which for example check if the attribute exists before updating it.

Here's an example command that atomically updates the balance field of an item with the id of 12345 in a table called accounts:

aws dynamodb update-item \
    --table-name accounts \
    --key '{"id": {"N": "2131"}}' \
    --update-expression "SET balance = :new_balance" \
    --condition-expression "balance = :old_balance" \
    --expression-attribute-values '{":new_balance": {"N": "320"}, ":old_balance": {"N": "245"}}'

The update will only succeed if the balance prior to the update matches our expectations. Otherwise, the command will return an error.

Batch Operations

Batch operations in DynamoDB CLI allow you to perform multiple write operations (put, update, or delete) on one or more items in a single operation.

To perform a batch operation, you can use the batch-write-item command in the DynamoDB CLI. You need to specify the table name and a list of one or more write requests, where each request contains the type of operation (put, update, or delete) and the item data.

Here's an example of a batch operation that inserts two new items:

aws dynamodb batch-write-item \
    --table-name my-table \
    --request-items \
        '{ "PutRequest": { "Item": { "id": {"S": "item1" }, "name": { "S": "Item One" } } } }, \
         { "PutRequest": { "Item": { "id": {"S": "item2" }, "name": { "S": "Item Two" } } } }'

Exporting and Importing data

You can quickly export small tables with a single scan:

aws dynamodb scan \
    --table-name my-table \
    --select ALL_ATTRIBUTES \
    --no-paginate --output json \
    > my-table-export.json

Keep in mind that a single scan operation can read only up to a maximum of 1 MB of data. As a result, exporting large tables with just one request is not feasible.

By converting the output to a batch write operation, you can restore the exported items in another table easily:

# creating the batch write file
cat my-table-export \
    | jq '{ "<TABLE_NAME>": [ .[] | { PutRequest: { Item: . } } ] }' \
    > batch-write.txt

# putting the items
aws dynamodb batch-write-item --request-items file://batch-write.txt

Creating Backups and Restoring Them

To create managed backups via the DynamoDB CLI, you can use the aws dynamodb create-backup command:

aws dynamodb create-backup \
    --table-name my-table \
    --backup-name my-table-backup

Creating and Checking Backups

The backup creation process may take some time, depending on the size of your table. You can always check the available backups and their status using the list-backups command, which only requires you to provide the table name using --table-name. A response will appear as follows:

{
    "BackupSummaries": [
        {
            "TableName": "prod-crawlers-cars",
            "TableId": "0a198448-1fd6-473e-9231-24ab9affe23d",
            "TableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/my-table",
            "BackupArn": "arn:aws:dynamodb:us-east-1:12345678912:table/my-table/backup/01687370254652-2fe55c93",
            "BackupName": "my-table-backup",
            "BackupCreationDateTime": "2023-06-21T19:57:34.652000+02:00",
            "BackupStatus": "AVAILABLE",
            "BackupType": "USER",
            "BackupSizeBytes": 614
        }
    ]
}

To restore a managed backup, you can use the aws dynamodb restore-table-from-backup command. Here's an example command:

aws dynamodb restore-table-from-backup \
    --target-table-name my-restored-table \
    --backup-arn arn:aws:dynamodb:us-east-1:123456789012:backup/my-table-backup

You can only restore the backup to a new table, not to an existing one.

Note that restoring a table from a backup, like creating the backup itself, can take some time, depending on the size of the table and the workload on your AWS account. Also, the restored table will not have any of the original table's indexes or stream settings, so you will need to recreate them manually if needed.

Conclusion

With the AWS CLI, you can automate numerous daily tasks related to DynamoDB from your terminal, regardless of whether you are a beginner or an experienced AWS user.

Frequently Asked Questions

1. What is the Amazon DynamoDB CLI?
   Amazon DynamoDB CLI is a command line interface that allows users to manage their DynamoDB database, including creating, updating, and deleting tables, as well as querying and modifying items.

2. How do I install and configure AWS CLI for DynamoDB?
   Install the latest version of AWS CLI according to your operating system's documentation. After installation, run aws configure and input your AWS Access Key ID, Secret Key, default region, and output format to set up your credentials.

3. What are some basic DynamoDB CLI commands?
   Some basic commands include aws dynamodb create-table, aws dynamodb update-table, aws dynamodb delete-table, aws dynamodb list-tables, aws dynamodb describe-table, aws dynamodb get-item, aws dynamodb query, aws dynamodb scan, aws dynamodb put-item, aws dynamodb update-item, and aws dynamodb delete-item.

4. How can I perform atomic updates using DynamoDB CLI?
   To perform atomic updates, use the update-item command with the --update-expression option and the attribute_exists function to check if the attribute exists before updating it.

5. How do I create backups and restore them using DynamoDB CLI?
   To create a backup, use the aws dynamodb create-backup command. To restore a backup, use the aws dynamodb restore-table-from-backup command. Note that you can only restore the backup to a new table, not an existing one.

Related Reads

Head over to our bi-weekly newsletter or check out the following blog posts

• AWS Lambda CLI - Full Guide

• ECS on Fargate: The Greatest Services to Run Your Containers

• AWS Edge Locations: What They Are and Where to Find Them