Skip to content

Latest commit

 

History

History
98 lines (65 loc) · 4.3 KB

index.md

File metadata and controls

98 lines (65 loc) · 4.3 KB
title summary component reviewed related
AWS DynamoDB persistence
How to use NServiceBus with AWS DynamoDB
DynamoDB
2025-04-10
samples/aws/dynamodb-simple
samples/aws/dynamodb-transactions
nservicebus/transactional-session/persistences/dynamodb

Uses the AWS DynamoDB NoSQL database service for storage.

Persistence at a glance

For a description of each feature, see the persistence at a glance legend.

Feature
Supported storage types Sagas, Outbox
Transactions Using TransactWriteItems
Concurrency control Optimistic concurrency, optional pessimistic concurrency
Scripted deployment Not supported
Installers Table is created by installers
Local development Supported via LocalStack

Usage

Add a NuGet package reference to NServiceBus.Persistence.DynamoDB. Configure the endpoint to use the persistence with the following configuration API:

snippet: DynamoDBUsage

Customizing the table used

By default, the persister will store outbox and saga records in a shared table named NServiceBus.Storage.

Customize the table name and other table attributes using the following configuration API:

snippet: DynamoDBTableCustomizationShared

Outbox and saga data can be stored in separate tables; see the saga and outbox configuration documentation for further details.

Table creation

When installers are enabled, NServiceBus will try to create the configured tables if they do not already exist. Table creation can explicitly be disabled, even with installers remaining enabled, using the DisableTablesCreation setting:

snippet: DynamoDBDisableTableCreation

Customizing the AmazonDynamoDBClient provider

In cases when the AmazonDynamoDBClient is configured and used via dependency injection, a custom provider can be implemented:

snippet: DynamoDBCustomClientProvider

and then registered on the container

snippet: DynamoDBCustomClientProviderRegistration

Permissions

Below is the list of minimum required IAM policies for operating the DynamoDB persistence

Installers enabled:

  • dynamodb:CreateTable,
  • dynamodb:DescribeTable,
  • dynamodb:DescribeTimeToLive,
  • dynamodb:UpdateTimeToLive,
  • dynamodb:Query,
  • dynamodb:GetItem,
  • dynamodb:BatchWriteItem,
  • dynamodb:PutItem,
  • dynamodb:DeleteItem

Installers disabled (or when using DisableTableCreation())

  • dynamodb:DescribeTimeToLive,
  • dynamodb:Query,
  • dynamodb:GetItem,
  • dynamodb:BatchWriteItem,
  • dynamodb:PutItem,
  • dynamodb:DeleteItem

Provisioned throughput rate-limiting

When using provisioned throughput it is possible for the DynamoDB service to rate-limit usage, resulting in "provisioned throughput exceeded" exceptions indicated by the 429 status code.

Warning

When using Dynamo DB persistence with the outbox enabled, "provisioned throughput exceeded" errors may result in handler re-execution and/or duplicate message dispatches depending on which operation is throttled.

Note

AWS provides guidance on how to diagnose and troubleshoot provisioned throughput exceeded exceptions.

The Dynamo DB SDK provides a mechanism to automatically retry operations when rate-limiting occurs. These settings can be adjusted to help prevent messages from failing during spikes in message volume, rather than changing the provisioned capacity or switching to autoscaling or the on-demand capacity mode.

The retry-operations settings can be set when initializing the AmazonDynamoDBClient via the AmazonDynamoDBConfig properties:

snippet: DynamoDBConfigureThrottlingWithClientConfig