GETTING STARTED WITH AMAZON DYNAMODB IN SWAMP

In this tutorial, we will define an Amazon DynamoDB table as a Swamp behavior, then run the methods that build the table in AWS and record its state in Swamp.

What we will build

We will pull the @swamp/aws/dynamodb extension and create a behavior named orders-table. It describes an on-demand table called orders with one string partition key, pk. Then we will run the behavior's create and sync methods. At the end, the orders table exists in us-east-1 and Swamp holds a record of its state.

Prerequisites

• Swamp installed (see Install Swamp)
• A terminal open in a Swamp repository
• AWS credentials in the default credential chain, with permission to create DynamoDB tables (see Authenticate to AWS with SSO)

The create step builds a real table in the AWS account those credentials belong to.

Pull the extension

First, we pull the extension that provides the DynamoDB behavior type:

swamp extension pull @swamp/aws/dynamodb

You will see output like:

INF extension·pull: Pulling "@swamp/aws/dynamodb"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/aws/dynamodb"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/aws/dynamodb"@"2026.10.13.1"
INF extension·pull: Extracted 6 files:

The repository can now use the @swamp/aws/dynamodb/global-table behavior type.

Define the table

Next, we create a behavior named orders-table of type @swamp/aws/dynamodb/global-table, as shown in Create and Run a Behavior. We give it these global arguments:

globalArguments:
  TableName: orders
  region: us-east-1
  BillingMode: PAY_PER_REQUEST
  AttributeDefinitions:
    - AttributeName: pk
      AttributeType: S
  KeySchema:
    - AttributeName: pk
      KeyType: HASH
  Replicas:
    - Region: us-east-1

Notice that Replicas lists one region. The global-table type requires Replicas, even for a table in a single region.

Notice also that the definition contains no credentials. The behavior reads them from the AWS environment in our terminal.

Create the table

Now we run the create method:

swamp behavior run orders-table create

The create method asks AWS to create the orders table in us-east-1 and writes the table's resource state to Swamp data.

If the run reports that it cannot find credentials, the AWS credentials are not available in this terminal. Sign in again with the method you use for AWS, then repeat this step.

Sync the state

Next, we read the table back from AWS:

swamp behavior run orders-table sync

The sync method reads the current state of the orders table from AWS and records it in Swamp data.

We can run sync again at any point to get the table's latest state. It reads from AWS and does not change the table.

What we built

We pulled the DynamoDB extension, defined an on-demand orders table as the orders-table behavior, created the table in AWS with create, and recorded its current state with sync. That state is now Swamp data, and you can read it with the queries described in Query and Manage Data.