AWS DynamoDB persistence

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.

Usage

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

var persistence = endpointConfiguration.UsePersistence<DynamoPersistence>();
// optional client
persistence.DynamoClient(new AmazonDynamoDBClient());

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:

persistence.UseSharedTable(new TableConfiguration
{
    TableName = "MyTable",
    PartitionKeyName = "MyPartitionKey",
    SortKeyName = "MySortKey"
});

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 exist. Table creation can explicitly be disabled even with installers remaining enabled using the DisableTablesCreation setting:

persistence.DisableTablesCreation();

Customizing the AmazonDynamoDBClient provider

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

class CustomDynamoClientProvider
    : IDynamoClientProvider
{
    // get fully configured via DI
    public CustomDynamoClientProvider(IAmazonDynamoDB dynamoClient)
    {
        Client = dynamoClient;
    }
    public IAmazonDynamoDB Client { get; }
}

and then registered on the container

endpointConfiguration.RegisterComponents(c => c.AddTransient<IDynamoClientProvider, CustomDynamoClientProvider>());

Permissions

Below is the list of minimum required IAM policies for operating the DynamoDB persistence with installers enabled:

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

If installers are disabled, or if DisableTableCreation is called, the dynamodb:CreateTable, dynamodb:DescribeTable and dynamodb:UpdateTimeToLive policies are not required.

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.

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

These settings may be set when initializing the AmazonDynamoDBClient via the AmazonDynamoDBConfig properties:

var dynamoDbClient = new AmazonDynamoDBClient(
    new AmazonDynamoDBConfig
    {
        Timeout = TimeSpan.FromSeconds(10),
        RetryMode = RequestRetryMode.Adaptive,
        MaxErrorRetry = 3
    });
persistence.DynamoClient(dynamoDbClient);