Skip to main content

Introduction

Welcome to FluentDynamoDB - a modern, fluent C# interface for Amazon DynamoDB that's fully AOT-compatible and uses source generators for type-safe, high-performance data access.

What is FluentDynamoDB?​

FluentDynamoDB is a suite of libraries that make working with DynamoDB in .NET applications intuitive and type-safe. It provides:

  • Fluent API - Chainable, readable methods for building queries and operations
  • AOT Compatibility - Full support for Native AOT compilation
  • Source Generators - Automatic table classes, key builders, and field constants
  • Type Safety - Lambda expressions for queries, filters, and updates
  • Enterprise Features - Encryption, blob storage, geospatial indexing, and more

Key Features​

Lambda Expression Support​

Write type-safe queries using C# lambda expressions with compile-time validation and IntelliSense support:

// Type-safe query with lambda expressions
var orders = await table.Query
    .Where<Order>(x => x.CustomerId == customerId && x.OrderId.StartsWith("ORDER#2024"))
    .WithFilter<Order>(x => x.Status == "pending" && x.Total > 100.00m)
    .ToListAsync();

// Type-safe conditional update
await table.Users.Update("user123")
    .Where(x => x.Status == "active")
    .Set(x => new UserUpdateModel { 
        Name = "Jane Doe",
        LoginCount = x.LoginCount.Add(1)
    })
    .UpdateAsync();

Source-Generated Entity Accessors​

Define entities with attributes and get type-safe table classes with entity accessors:

[DynamoDbTable("orders")]
public partial class Order
{
    [PartitionKey(Prefix = "CUSTOMER")]
    [DynamoDbAttribute("pk")]
    public string CustomerId { get; set; } = string.Empty;
    
    [SortKey(Prefix = "ORDER")]
    [DynamoDbAttribute("sk")]
    public string OrderId { get; set; } = string.Empty;
    
    [DynamoDbAttribute("status")]
    public string Status { get; set; } = string.Empty;
}

// Generated table class with entity accessors
var table = new OrdersTable(client, "orders");

// Clean, type-safe operations without generic parameters
var order = await table.Orders.GetAsync("customer123", "order456");
await table.Orders.PutAsync(order);
await table.Orders.DeleteAsync("customer123", "order456");

Single-Table Design Support​

First-class support for multi-entity tables with entity-specific accessors:

// Multi-entity table with entity accessors
var table = new OrdersTable(client, "orders");

// Each entity type has its own accessor
var order = await table.Orders.GetAsync("order123");
var orderLines = await table.OrderLines.Query()
    .Where(x => x.OrderId == "order123")
    .ToListAsync();

Three API Styles​

Choose the approach that fits your needs:

// 1. Lambda Expressions (Recommended) - type-safe with IntelliSense
await table.Users.Update("user123")
    .Where(x => x.Status == "active")
    .Set(x => new UserUpdateModel { Name = "Jane Doe" })
    .UpdateAsync();

// 2. Format Strings - concise with automatic parameter generation
await table.Users.Update("user123")
    .Where($"{User.Fields.Status} = {{0}}", "active")
    .Set($"SET {User.Fields.Name} = {{0}}", "Jane Doe")
    .UpdateAsync();

// 3. Manual Parameters - explicit control for complex scenarios
await table.Users.Update("user123")
    .Where("#status = :status")
    .WithAttribute("#status", "status")
    .WithValue(":status", "active")
    .Set("SET #name = :name")
    .WithAttribute("#name", "name")
    .WithValue(":name", "Jane Doe")
    .UpdateAsync();

Field-Level Encryption​

Transparent KMS-based encryption for sensitive data:

var options = new FluentDynamoDbOptions()
    .WithEncryption(encryptor);

var table = new UsersTable(client, "users", options);

Geospatial Indexing​

Built-in support for Geohash, Google S2, and Uber H3:

var options = new FluentDynamoDbOptions()
    .AddGeospatial();

var table = new LocationsTable(client, "locations", options);

About Amazon DynamoDB​

Amazon DynamoDB is a fully managed NoSQL database service provided by Amazon Web Services (AWS). It delivers fast and predictable performance with automatic scalability, making it ideal for applications that need consistent, single-digit millisecond latency at any scale.

Key DynamoDB characteristics:

  • Serverless - No servers to provision, patch, or manage
  • Scalable - Automatically scales throughput capacity
  • Highly Available - Built-in replication across multiple AWS Availability Zones
  • Flexible - Supports both document and key-value data models

For more information, see the official DynamoDB documentation.

Disclaimer

FluentDynamoDB is an independent open-source project maintained by Oproto Inc. It is not affiliated with, endorsed by, or sponsored by Amazon or Amazon Web Services.

Getting Started​

Head over to Installation to get started.