Skip to main content

STORE SWAMP RUNTIME DATA IN A DYNAMODB DATASTORE

This guide shows you how to move a repository's runtime data, locks and sync state into a DynamoDB table. You use the bootstrap workflow from @webframp/dynamodb-datastore-bootstrap, which provisions the table and a least-privilege IAM managed policy and then switches the repository to the @webframp/dynamodb-datastore datastore.

Prerequisites

  • A Swamp repository
  • AWS credentials in the default credential chain, with permission to create a DynamoDB table, enable TTL on it and create an IAM managed policy (see Authenticate to AWS with SSO)
  • A plan for which IAM identity will run Swamp after the switch. That identity must hold the managed policy this workflow creates, or have it attached afterwards.

Pull the extensions

Pull the datastore the repository will switch to:

swamp extension pull @webframp/dynamodb-datastore

The output looks like:

INF extension·pull: Pulling "@webframp/dynamodb-datastore"@"2026.10.14.1"
INF extension·pull: Identity verified: "@webframp/dynamodb-datastore"@"2026.10.14.1"
INF extension·pull: Pulled "@webframp/dynamodb-datastore"@"2026.10.14.1"
INF extension·pull: Extracted 13 files:

Then pull the bootstrap extension, which ships the provisioner behavior type and the workflow:

swamp extension pull @webframp/dynamodb-datastore-bootstrap

The output looks like:

INF extension·pull: Pulling "@webframp/dynamodb-datastore-bootstrap"@"2026.10.14.1"
INF extension·pull: Identity verified: "@webframp/dynamodb-datastore-bootstrap"@"2026.10.14.1"
INF extension·pull: Pulled "@webframp/dynamodb-datastore-bootstrap"@"2026.10.14.1"
INF extension·pull: Extracted 6 files:

Create the behaviors the workflow uses

The workflow expects two behaviors with these exact names. Create them as shown in Create and Run a Behavior.

Create swamp-dynamodb-provisioner of type @webframp/dynamodb-datastore-bootstrap/provisioner with these global arguments:

globalArguments:
  region: us-east-1
  table_name: swamp-runtime
  policy_name: swamp-runtime-access

Then create swamp-dynamodb-setup of type command/shell. The workflow's final step uses it to run the datastore setup command.

If you choose a different region, table name or policy name, use the same values in the workflow inputs below.

Run the bootstrap workflow

swamp workflow run @webframp/bootstrap-dynamodb-datastore \
    --input region=us-east-1 \
    --input table_name=swamp-runtime \
    --input policy_name=swamp-runtime-access

The workflow runs the provisioner's provision method, which creates or verifies the swamp-runtime table and the swamp-runtime-access managed policy. It then runs swamp datastore setup extension @webframp/dynamodb-datastore through swamp-dynamodb-setup, which writes the DynamoDB datastore into the repository's configuration.

The table uses on-demand billing, a pk/sk key schema, a gsi1 index and TTL on the ttl attribute. The policy grants the seven runtime actions the datastore needs, limited to that table.

After the switch

  • Attach the swamp-runtime-access policy to every IAM identity that runs Swamp against this repository, including CI runners and swamp serve hosts.
  • To point the datastore at a VPC endpoint or DynamoDB Local, or to change maxChunkBytes, see the datastore keys in Datastore Configuration.
  • To trace datastore operations, configure a tracer as described in Set Up OpenTelemetry.

The provisioner creates or verifies existing resources, so you can run the workflow again with the same inputs if a run fails partway.