Creating a DynamoDB table in AWS - Step-by-Step CLI Walkthrough

Introduction

Sometimes you need a fast and simple way to store data that your app can quickly read and write. DynamoDB is a service that lets you create a table to store this data without worrying about managing servers.

When you want to store user profiles for a web app with quick access.

When you need to save session data for a mobile app that many users access.

When you want to keep track of orders in an online store with fast lookups.

When you need a database that automatically scales with your app's traffic.

When you want a simple key-value store without setting up a traditional database.

Config File - create-table.json

create-table.json

{
  "TableName": "example-table",
  "AttributeDefinitions": [
    {
      "AttributeName": "UserId",
      "AttributeType": "S"
    }
  ],
  "KeySchema": [
    {
      "AttributeName": "UserId",
      "KeyType": "HASH"
    }
  ],
  "ProvisionedThroughput": {
    "ReadCapacityUnits": 5,
    "WriteCapacityUnits": 5
  }
}

TableName: The name of your DynamoDB table.

AttributeDefinitions: Defines the attributes used as keys, here 'UserId' as a string.

KeySchema: Sets 'UserId' as the primary key (HASH key).

ProvisionedThroughput: Sets how much read and write capacity the table has, here 5 units each.

Commands

This command creates a DynamoDB table using the settings defined in the JSON file.

Terminal

aws dynamodb create-table --cli-input-json file://create-table.json

Expected Output

{

    "TableDescription": {

        "AttributeDefinitions": [

            {

                "AttributeName": "UserId",

                "AttributeType": "S"

            }

        ],

        "TableName": "example-table",

        "KeySchema": [

            {

                "AttributeName": "UserId",

                "KeyType": "HASH"

            }

        ],

        "TableStatus": "CREATING",

        "CreationDateTime": "2024-06-01T12:00:00.000Z",

        "ProvisionedThroughput": {

            "ReadCapacityUnits": 5,

            "WriteCapacityUnits": 5,

            "NumberOfDecreasesToday": 0

        },

        "TableSizeBytes": 0,

        "ItemCount": 0,

        "TableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/example-table"

    }

}

→

--cli-input-json - Specifies the JSON file with the table configuration.

This command checks the status and details of the table to confirm it was created successfully.

Terminal

aws dynamodb describe-table --table-name example-table

Expected Output

{

    "Table": {

        "AttributeDefinitions": [

            {

                "AttributeName": "UserId",

                "AttributeType": "S"

            }

        ],

        "TableName": "example-table",

        "KeySchema": [

            {

                "AttributeName": "UserId",

                "KeyType": "HASH"

            }

        ],

        "TableStatus": "ACTIVE",

        "CreationDateTime": "2024-06-01T12:00:00.000Z",

        "ProvisionedThroughput": {

            "ReadCapacityUnits": 5,

            "WriteCapacityUnits": 5,

            "NumberOfDecreasesToday": 0

        },

        "TableSizeBytes": 0,

        "ItemCount": 0,

        "TableArn": "arn:aws:dynamodb:us-east-1:123456789012:table/example-table"

    }

}

→

--table-name - Specifies the name of the table to describe.

Key Concept

If you remember nothing else from this pattern, remember: you create a DynamoDB table by defining its keys and capacity in a JSON file and then running a create command with that file.

Common Mistakes

Using an attribute in KeySchema that is not defined in AttributeDefinitions.

DynamoDB requires all key attributes to be defined first; otherwise, the table creation fails.

Make sure every attribute used as a key is listed in AttributeDefinitions with its type.

Not waiting for the table status to become ACTIVE before using it.

Trying to use the table while it is still CREATING will cause errors.

Use the describe-table command to check the status and wait until it shows ACTIVE.

Summary

Create a JSON file that defines the table name, keys, and capacity.

Run the AWS CLI create-table command with the JSON file to make the table.

Check the table status with describe-table to ensure it is ready to use.