Skip to main content

CREATE A MULTI-REGION DYNAMODB GLOBAL TABLE

This guide shows you how to create a DynamoDB global table that replicates between us-east-1 and eu-west-1, uses eventual multi-region consistency and emits a NEW_AND_OLD_IMAGES stream.

Prerequisites

  • A Swamp repository
  • AWS credentials in the default credential chain, with permission to create DynamoDB tables and replicas in both regions (see Authenticate to AWS with SSO), or credentials stored in a vault

Pull the extension

swamp extension pull @swamp/aws/dynamodb

The output looks 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:

Define the global table

Create a behavior named sessions-global of type @swamp/aws/dynamodb/global-table (see Create and Run a Behavior) with these global arguments:

globalArguments:
  TableName: sessions
  region: us-east-1
  BillingMode: PAY_PER_REQUEST
  MultiRegionConsistency: EVENTUAL
  AttributeDefinitions:
    - AttributeName: sessionId
      AttributeType: S
  KeySchema:
    - AttributeName: sessionId
      KeyType: HASH
  StreamSpecification:
    StreamViewType: NEW_AND_OLD_IMAGES
  Replicas:
    - Region: us-east-1
    - Region: eu-west-1

region is the region the requests go to. Include it in Replicas as well, so the table exists there.

To add more regions, append entries to Replicas. Each replica entry also accepts its own settings, such as PointInTimeRecoverySpecification, DeletionProtectionEnabled, TableClass and Tags. See the extensions reference for the full replica shape.

If you need STRONG consistency instead, set MultiRegionConsistency: STRONG and check the AWS requirements for strongly consistent global tables before you create the table.

If the AWS credentials are stored in a vault, wire them into the definition instead of relying on the environment:

globalArguments:
  accessKeyId: "${{ vault.get('aws', 'access-key-id') }}"
  secretAccessKey: "${{ vault.get('aws', 'secret-access-key') }}"

Use AWS Secrets Manager and Storing Secrets cover setting up the vault.

Create the table and replicas

swamp behavior run sessions-global create

The create method asks AWS to create the sessions global table with replicas in us-east-1 and eu-west-1, and writes the table's resource state to Swamp data.

Record the replicated state

swamp behavior run sessions-global sync

The sync method reads the current state of the sessions table, including both replicas, from AWS and records it in Swamp data.

To change replicas, streams or capacity later, edit the global arguments and run the update method. To read the recorded state, see Query and Manage Data.