DynamoDB Management Using AWS CLI with LocalStack

4 min readNov 24, 2024

Assuming the LocalStack has been created using the steps in a previous post Installing LocalStack (To Simulate AWS) using Docker Desktop for Windows and the AWS CLI has been installed.

Assuming the articles below has been visited:

This guide presents a scenario-based approach to managing DynamoDB on LocalStack. Each section introduces a scenario, followed by relevant JSON configuration and AWS CLI commands with the appropriate LocalStack profile and endpoint settings.

Table Management

Building a DynamoDB table named Orders to store e-commerce order data. The table will use OrderId as the partition key and CustomerId as an additional sort key.

Create Table

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb create-table --cli-input-json '{
    "TableName": "Orders",
    "KeySchema": [
        { "AttributeName": "OrderId", "KeyType": "HASH" },
        { "AttributeName": "CustomerId", "KeyType": "RANGE" }
    ],
    "AttributeDefinitions": [
        { "AttributeName": "OrderId", "AttributeType": "S" },
        { "AttributeName": "CustomerId", "AttributeType": "S" }
    ],
    "BillingMode": "PAY_PER_REQUEST"
}'

List Tables

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb list-tables

Describe Table

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb delete-table --table-name Orders

Delete Table

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb delete-table --table-name Orders

Item Management

Managing orders in the Orders table.

Add a Single Order

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb put-item --table-name Orders --item '{"OrderId": {"S": "003"}, "CustomerId": {"S": "C003"}, "Amount": {"N": "300.00"}, "Status": {"S": "Shipped"}}'

Batch Write Orders

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb batch-write-item --request-items '{
    "Orders": [
        {
            "PutRequest": {
                "Item": {
                    "OrderId": { "S": "001" },
                    "CustomerId": { "S": "C001" },
                    "Amount": { "N": "250.50" },
                    "Status": { "S": "Pending" }
                }
            }
        },
        {
            "PutRequest": {
                "Item": {
                    "OrderId": { "S": "002" },
                    "CustomerId": { "S": "C002" },
                    "Amount": { "N": "100.00" },
                    "Status": { "S": "Completed" }
                }
            }
        }
    ]
}'

Retrieve an Order

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb get-item --table-name Orders --key '{"OrderId": {"S": "001"}, "CustomerId": {"S": "C001"}}'

Update an Order

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb update-item --table-name Orders --key '{"OrderId": {"S": "001"}, "CustomerId": {"S": "C001"}}'--update-expression "SET #status = :status" --expression-attribute-names '{"#status": "Status"}' --expression-attribute-values '{":status": {"S": "Delivered"}}'

Delete an Order

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb delete-item --table-name Orders --key '{"OrderId": {"S": "003"}, "CustomerId": {"S": "C003"}}'

Query and Scan

Querying and Scanning the Orders table to retrieve

Query Orders for a Customer:

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb query --table-name Orders --key-condition-expression "OrderId = :orderId" --expression-attribute-values '{":orderId": {"S": "001"}}'

Scan for Pending Orders

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb scan --table-name Orders --filter-expression "#status = :status" --expression-attribute-names '{"#status": "Status"}' --expression-attribute-values '{":status": {"S": "Pending"}}'

Index Management

Creating a GSI on the Orders table to query by Status.

JSON for GSI Creation:

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb update-table --table-name Orders --cli-input-json '{
    "AttributeDefinitions": [
        { "AttributeName": "Status", "AttributeType": "S" }
    ],
    "GlobalSecondaryIndexUpdates": [
        {
            "Create": {
                "IndexName": "StatusIndex",
                "KeySchema": [
                    { "AttributeName": "Status", "KeyType": "HASH" }
                ],
                "Projection": {
                    "ProjectionType": "ALL"
                },
                "ProvisionedThroughput": {
                    "ReadCapacityUnits": 5,
                    "WriteCapacityUnits": 5
                }
            }
        }
    ]
}'

Query using GSI

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb query --table-name Orders --index-name StatusIndex --key-condition-expression "#status = :status" --expression-attribute-names '{"#status": "Status"}' --expression-attribute-values '{":status": {"S": "Delivered"}}'

Delete a GSI

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb update-table --table-name Orders --global-secondary-index-updates '[{"Delete": {"IndexName": "StatusIndex"}}]'

Enabling TTL (Time to Live)

Setting up a Time-to-Live (TTL) attribute called ExpirationTime to automatically remove expired items from the Orders table.

Enable TTL

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb update-time-to-live --table-name Orders --time-to-live-specification "Enabled=true,AttributeName=ExpirationTime"

Verify TTL Status

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb describe-time-to-live --table-name Orders

Disable TTL

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb update-time-to-live --table-name Orders --time-to-live-specification "Enabled=false,AttributeName=ExpirationTime"

Tagging DynamoDB Resources

Adding tags to your DynamoDB table for better cost tracking and resource organization.

Add Tags to a Table

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb tag-resource --resource-arn arn:aws:dynamodb:us-east-1:000000000000:table/Orders --tags Key=Environment,Value=Development Key=Owner,Value=TeamA

List Tags

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb list-tags-of-resource --resource-arn arn:aws:dynamodb:us-east-1:000000000000:table/Orders

Remove Tag

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb untag-resource --resource-arn arn:aws:dynamodb:us-east-1:000000000000:table/Orders --tag-keys Environment Owner

Exporting Data

Exporting Table Data Using Scan to Local

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb scan --table-name Orders --output json > OrdersBackup.json

DynamoDB Streams

Enabling DynamoDB Streams to capture changes to your table for auditing or real-time processing.

Enable Streams

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb update-table --table-name Orders --stream-specification StreamEnabled=true,StreamViewType=NEW_AND_OLD_IMAGES

Describe Table (providing Stream arn)

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb describe-table --table-name Orders

Describe Streams (provides shardId)

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodbstreams describe-stream --stream-arn arn:aws:dynamodb:us-east-1:000000000000:table/Orders/stream/2024-11-24T16:36:13.515

List Stream Records (provides shard iterator)

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodbstreams get-shard-iterator --stream-arn arn:aws:dynamodb:us-east-1:000000000000:table/Orders/stream/2024-11-24T16:36:13.515 --shard-id shardId-00000001732400000000-000000000000 --shard-iterator-type LATEST

Fetch Stream Records using Iterator

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodbstreams get-records --shard-iterator AAAAAAAAAAEr0Ft4gscUphdVDhyb9yO/lpSG8e7bVZ9HU46IO7mod8XRUT0NWSXfDjZgb8k1tRtWx//4Lrmr2FpVpRJz4Lrl0aHdfP4Ov8YHUzFRE4BVgVxZF9MHZwKaRaxdc7OQO2oHF4gmP2ASXlSQr4EhyEu8Ek00K/OssUb3/5ZaXUnvY3WrBsXURWgIeqbDfMVEpzF3zSur9+q0t/tZT647lRFO

Managing Provisioned Capacity

Adjusting the read and write capacity for a provisioned mode DynamoDB table.

Update Provisioned Capacity

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb update-table --table-name Orders --provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5

Querying and Scanning with Pagination

Handling large datasets by paginating query or scan results.

Paginated Query

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb query --table-name Orders --key-condition-expression "OrderId = :orderId" --expression-attribute-values '{":orderId": {"S": "001"}}' --max-items 2

Paginated Scan

aws --profile localstack --endpoint-url=http://localhost:4566 dynamodb scan --table-name Orders --max-items 2

Note: Use --profile <your profile>and --endpoint-url=<your endpoint> for all operations in a local environment