DynamoDBv2.Transactions 4.0.14.102

DynamoDBv2.Transactions

A high-performance .NET library for Amazon DynamoDB transactions with compile-time source generation — up to 82x faster than reflection-based mapping.

<p align="center">

</p>

<p align="center">

</p>

<p align="center">

</p>

Why This Library?

DynamoDBv2.Transactions skips the implicit DescribeTable call that the standard AWS SDK wrapper makes, using DynamoDB attributes directly instead. Combined with the source generator, this delivers dramatically faster performance:

<table> <tr> <td width="50%">

Source Generator vs Reflection

</td> <td width="50%">

End-to-End vs Standard SDK Wrapper

</td> </tr> </table>

All key lookups are zero-allocation via compile-time switch expressions. Just make your entity class partial — no other changes needed.

Installation

dotnet add package DynamoDBv2.Transactions

Quick Start

1. Define Your Entity

Make it partial and the source generator handles the rest — zero configuration:

[DynamoDBTable("MyTable")]
public partial class MyEntity : ITransactional
{
    [DynamoDBHashKey("PK")]
    public string Id { get; set; }

    [DynamoDBProperty("Name")]
    public string Name { get; set; }

    [DynamoDBVersion]
    public long? Version { get; set; }
}

The generator auto-discovers all partial classes with [DynamoDBHashKey] and registers them at startup via [ModuleInitializer]. Non-partial classes fall back to cached reflection seamlessly.

2. Perform a Transaction

using DynamoDBv2.Transactions;

var client = new AmazonDynamoDBClient();

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.CreateOrUpdate(new MyEntity
    {
        Id = "user-123",
        Name = "Alice"
    });
}

Features

• AWS SDK v4: Built for AWSSDK.DynamoDBv2 v4.x
• Source Generator: Compile-time DynamoDB attribute mapping — zero reflection for partial classes
• Transactional Operations: CreateOrUpdate, Delete, Update, Patch, ConditionCheck
• 100-Item Limit Validation: Enforces DynamoDB's limit before sending the request
• TransactionOptions: ClientRequestToken, ReturnConsumedCapacity, ReturnItemCollectionMetrics
• Versioning: Automatic version increment handling for optimistic concurrency
• Async API: Fully asynchronous
• Multi-targeting: .NET 8.0, .NET 9.0, and .NET 10.0

Usage Examples

Deleting an Item

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.DeleteAsync<TestTable>(userIdToDelete);
}

Patching a Property

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.PatchAsync<TestTable, DateTime?>(userId, t => t.SomeNullableDate1, updatedDate);
}

Conditional Check + Update

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.ConditionGreaterThan<TestTable, int>(userId, t => t.SomeInt, 100);
    transactor.CreateOrUpdate(new TestTable { UserId = userId, SomeInt = 200 });
}

Complex Multi-Operation Transaction

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.ConditionNotEquals<TestTable, bool>(userId, t => t.SomeBool, false);
    transactor.CreateOrUpdate(testItem);
    transactor.PatchAsync<TestTable, int>(userId, t => t.SomeInt, 200);
}

Version Check Before Update

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.ConditionVersionEquals<TestTable>(userId, t => t.Version, expectedVersion);
    transactor.CreateOrUpdate(new TestTable { UserId = userId, SomeInt = 250 });
}

Using TransactionOptions

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.Options = new TransactionOptions
    {
        ClientRequestToken = "idempotency-token-123",
        ReturnConsumedCapacity = ReturnConsumedCapacity.TOTAL
    };

    transactor.CreateOrUpdate(item1);
    transactor.CreateOrUpdate(item2);
}

Detailed Benchmark Results

Mapper Performance: Source-Generated vs Reflection

Isolated mapping operations — no DynamoDB I/O. Entity with 15 properties including all common types. Reflection results use warmed-up ConcurrentDictionary caches (best-case reflection).

BenchmarkDotNet v0.15.8, Linux Ubuntu 25.10
.NET SDK 9.0.311, .NET 9.0.13, X64 RyuJIT x86-64-v3

Runtime=.NET 9.0  IterationCount=20  LaunchCount=3  WarmupCount=5

End-to-End Transaction Performance

Full transactional writes against DynamoDB (includes network I/O via localstack).

BenchmarkDotNet v0.13.12, Windows 11
AMD Ryzen 9 6900HS, .NET 8.0.2

Job=OutOfProc  IterationCount=15  LaunchCount=3  WarmupCount=10

Running Benchmarks

dotnet run --project test/DynamoDBv2.Transactions.Benchmarks -c Release -- --filter '*MapperBenchmark*'
dotnet run --project test/DynamoDBv2.Transactions.Benchmarks -c Release -- --filter '*Benchmark*'

Running Tests

Integration tests run via Docker Compose with localstack:

docker-compose up --exit-code-from tests tests localstack
docker-compose up --exit-code-from unittests unittests

Versioning

This library's version tracks the underlying AWSSDK.DynamoDBv2 version:

Format: {aws_major}.{aws_minor}.{aws_patch}.{aws_rev × 100 + lib_rev}

The first three segments always tell you which AWS SDK version is inside.

Contributing

When creating PRs, please ensure:

• No sensitive information (tokens, keys, credentials) is included
• All existing tests pass (docker-compose up --exit-code-from tests tests localstack)
• New features include appropriate test coverage

License

Copyright © 2026, Vitali Bibikov. Code released under the MIT license.

Contact

Vitali Bibikov — bibikovvitaly@gmail.com