DynamoDBv2.Transactions is a .NET library that provides a robust wrapper around the Amazon DynamoDB low-level API, enabling easy and efficient management of transactions for batch operations. This library is designed to simplify complex transactional logic and ensure data consistency across your DynamoDB operations. It skips additional implicit for some cases DescribeTable call, thus making DynamoDB attributes mandatory - alternatively too using the attributes you can provide KeyName/KeyValue as a separate parameter to a method.
• Source Link: ✅ Valid with Symbol Server • Deterministic (dll/exe): ✅ Valid • Compiler Flags: ✅ Valid
- Transactional Operations: Supports
CreateOrUpdate,Delete, andUpdateandConditionCheckoperations within transactions. - Error Handling: Gracefully handles transaction failures and rollbacks.
- Versioning Support: Automatic handling of version increments for transactional integrity.
- Easy Integration: Seamlessly integrates with existing DynamoDB setups.
- Asynchronous API: Fully asynchronous API for optimal performance.
- Add Source Generator in order to validate abscence of [DynamoDBHashKey("UserId")] attribute
- Write more tests on SortKey
- Write more benchmarks.
You can install the DynamoDBv2.Transactions library via NuGet Package Manager. Run the following command in your Package Manager Console:
Install-Package DynamoDBv2.TransactionsTo get started with DynamoDBv2.Transactions, you'll need to set up an instance of TransactionalWriter using an ITransactionManager, which is responsible for executing the transactions against your DynamoDB instance.
Ensure you have the AWS SDK for .NET configured in your project, with access to Amazon DynamoDB.
!!! It skips additional implicit for some cases DescribeTable call, thus making DynamoDB attribute [DynamoDBHashKey("YourId")] mandatory !!!
Which makes it faster in comparison with the traditional wrapper.
Here's a quick example to show you how to use the TransactionalWriter to perform a transaction:
using DynamoDBv2.Transactions;
// Initialize the DynamoDB client
var client = new AmazonDynamoDBClient();
// Setup transaction manager and writer
var transactionManager = new TransactionManager(client);
var writer = new TransactionalWriter(transactionManager);
var userId = Guid.NewGuid().ToString();
var testItem = new TestTable
{
UserId = userId,
SomeDecimal = 123.45m,
SomeDate = DateTime.UtcNow,
SomeInt = 123
};
// Perform transaction
await using (writer)
{
writer.CreateOrUpdate(testItem);
}
// Load and verify
var dbContext = new DynamoDBContext(client);
var data = await dbContext.LoadAsync<TestTable>(userId);
Console.WriteLine($"Item saved with UserId: {data.UserId}");// Arrange
var userIdToDelete = "unique-user-id";
// Act
await using (var transactor = new DynamoDbTransactor(_fixture.Db.Client))
{
transactor.DeleteAsync<TestTable>(userIdToDelete);
};
// This operation will asynchronously delete the specified item from DynamoDB.// Arrange
var userIdToPatch = "unique-user-id";
var updatedDate = DateTime.UtcNow.AddDays(1);
// Act
await using (var transactor = new DynamoDbTransactor(_fixture.Db.Client))
{
transactor.PatchAsync<TestTable, DateTime?>(userIdToPatch, t => t.SomeNullableDate1, updatedDate);
};
// This code patches the 'SomeNullableDate1' property of the specified item to a new date.// Arrange
var userIdToCheck = "unique-user-id";
// Act
await using (var transactor = new DynamoDbTransactor(_fixture.Db.Client))
{
transactor.ConditionGreaterThan<TestTable, int>(userIdToCheck, t => t.SomeInt, 100);
transactor.CreateOrUpdate(new TestTable { UserId = userIdToCheck, SomeInt = 200 });
};
// This will add a conditional check to ensure 'SomeInt' is greater than 100 before updating or creating the item.// Arrange
var userId = Guid.NewGuid().ToString();
var testItem = new TestTable
{
UserId = userId,
SomeInt = 150,
SomeDate = DateTime.UtcNow,
SomeBool = true
};
// Act
await using (var transactor = new DynamoDbTransactor(_fixture.Db.Client))
{
transactor.ConditionNotEquals<TestTable, bool>(userId, t => t.SomeBool, false);
transactor.CreateOrUpdate(testItem);
transactor.PatchAsync<TestTable, int>(userId, t => t.SomeInt, 200);
};
// This transaction will check if 'SomeBool' is not false, then create or update the item, and finally patch 'SomeInt' to 200.// Arrange
var userId = Guid.NewGuid().ToString();
var expectedVersion = 1;
// Act
await using (var transactor = new DynamoDbTransactor(_fixture.Db.Client))
{
transactor.ConditionVersionEquals<TestTable>(userId, t => t.Version, expectedVersion);
transactor.CreateOrUpdate(new TestTable { UserId = userId, SomeInt = 250 });
};
// This ensures the item's version matches the expected version before it is updated or created.// * Summary *
BenchmarkDotNet v0.13.12, Windows 11 (10.0.22631.3527/23H2/2023Update/SunValley3) AMD Ryzen 9 6900HS with Radeon Graphics, 1 CPU, 16 logical and 8 physical cores .NET SDK 8.0.200 [Host] : .NET 8.0.2 (8.0.224.6711), X64 RyuJIT AVX2 OutOfProc : .NET 8.0.2 (8.0.224.6711), X64 RyuJIT AVX2
Job=OutOfProc IterationCount=15 LaunchCount=3 WarmupCount=10
| Method | Mean | Error | StdDev | Allocated |
|---|---|---|---|---|
| DynamoDbTransactionsWrapper | 11.99 ms | 0.046 ms | 0.087 ms | 80.96 KB |
| OriginalWrapper | 15.83 ms | 0.236 ms | 0.442 ms | 83.77 KB |
| DynamoDbTransactionsWrapper3Items | 13.37 ms | 0.066 ms | 0.123 ms | 114.74 KB |
| OriginalWrapper3Items | 46.44 ms | 0.444 ms | 0.834 ms | 251.01 KB |
// * Hints * Outliers Benchmark.DynamoDbTransactionsWrapper3Items: OutOfProc -> 3 outliers were removed (13.64 ms..14.81 ms) Benchmark.OriginalWrapper3Items: OutOfProc -> 3 outliers were removed (48.78 ms..49.19 ms)
// * Legends * Mean : Arithmetic mean of all measurements Error : Half of 99.9% confidence interval StdDev : Standard deviation of all measurements Allocated : Allocated memory per single operation (managed only, inclusive, 1KB = 1024B) 1 ms : 1 Millisecond (0.001 sec)
// * Diagnostic Output - MemoryDiagnoser *
// ***** BenchmarkRunner: End ***** Run time: 00:04:09 (249.42 sec), executed benchmarks: 4
- Goto .\DynamoDBv2.Transactions
- dotnet build .\test\DynamoDBv2.Transactions.Benchmarks\ -c Release
- Execute in shell .\test\DynamoDBv2.Transactions.Benchmarks\bin\Release\net8.0\DynamoDBv2.Transactions.exe
ensure you have a test instance of DynamoDB available. (and configure it in env of the docker compose file) (On my env tests are running both in real DynamoDB and localstack instance) Tests are written using xUnit and should be configured to interact directly with your database:
- docker-compose up --exit-code-from tests tests localstack
- docker-compose up --exit-code-from unittests unittests
// Example test
[Fact]
public async Task SaveDataAndRetrieve()
{
var writer = new TransactionalWriter(new TransactionManager(_fixture.Db.Client));
var userId = Guid.NewGuid().ToString();
var testItem = new TestTable
{
UserId = userId,
SomeInt = 123
};
await using (var writer = new TransactionalWriter(new TransactionManager(_fixture.Db.Client)))
{
writer.CreateOrUpdate(testItem);
}
var retrievedItem = await _fixture.Db.Context.LoadAsync<TestTable>(userId);
Assert.NotNull(retrievedItem);
}When creating PRs, please review the following guidelines:
- The action code does not contain sensitive information.
- At least one of the commit messages contains the appropriate
+semver:keywords listed under [Incrementing the Version] for major and minor increments. - The action has been recompiled. See [Recompiling Manually] for details.
- The README.md has been updated with the latest version of the action. See [Updating the README.md] for details.
Copyright © 2024, Vitali Bibikov. Code released under the MIT license.
Your Name - [bibikovvitaly@gmail.com]