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. |
Usage
Add a NuGet package reference to NServiceBus.
. 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.
.
Customize the table name and other table attributes using the following configuration API:
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.
When using the 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.
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. 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);