Welcome to the documentation hub for Oproto.FluentDynamoDb - a fluent-style API wrapper for Amazon DynamoDB with automatic code generation capabilities.
New: The source generator now supports both single-entity and multi-entity table patterns, enabling true single-table design with entity-specific accessors. See Single-Entity Tables and Multi-Entity Tables for details.
This documentation is organized into four main sections to help you find what you need quickly:
New to the library? Start here to get up and running quickly.
- Quick Start - Get productive in 5 minutes
- Installation - Detailed installation and setup
- First Entity - Deep dive into entity definition
- Single-Entity Tables - Simple one-entity-per-table pattern
Learn the essential features you'll use every day.
- Configuration - Configure logging, geospatial, blob storage, and encryption
- Entity Definition - Define entities with attributes and keys
- Basic Operations - CRUD operations (Put, Get, Update, Delete)
- Querying Data - Query and scan operations
- Expression Formatting - String.Format-style expressions
- Expression-Based Updates - Type-safe update operations with IntelliSense
- Batch Operations - Batch get and write operations
- Transactions - DynamoDB transactions
- Projection Models - Optimize queries with automatic projections
- Logging Configuration - Configure logging and diagnostics
- Log Levels and Event IDs - Understand and filter logs
- Structured Logging - Query and analyze structured logs
Explore advanced patterns and optimizations.
- Internal Architecture - How source generation, expression translation, and request builders work
- Multi-Entity Tables - Single-table design with multiple entity types
- Advanced Type System - Maps, Sets, Lists, TTL, JSON blobs, and blob storage
- Composite Entities - Multi-item and related entities
- Discriminators - Flexible entity type identification for single-table design
- Field-Level Security - Logging redaction and KMS-based encryption
- Geospatial Support - Location-based queries with GeoHash, S2, and H3
- Global Secondary Indexes - GSI configuration and querying
- STS Integration - Custom client support for multi-tenancy
- Performance Optimization - Performance tuning guide
- Manual Patterns - Lower-level manual approaches
Detailed reference documentation for attributes, format specifiers, and troubleshooting.
- API Reference - Quick reference for all builder methods and generated code
- Attribute Reference - Complete attribute documentation
- Format Specifiers - Format specifier reference
- Error Handling - Exception handling patterns
- Troubleshooting - Common issues and solutions
- Logging Troubleshooting - Logging issues and debugging
- Advanced Types Migration - Migrate to advanced types
Practical code examples for common scenarios.
- Projection Models Examples - Projection models, GSI enforcement, and type overrides
- Advanced Types Examples - Maps, Sets, Lists, TTL, JSON, and blob storage examples
Complete, runnable applications demonstrating real-world patterns.
- TodoList - Basic CRUD operations with
[Scannable]tables and lambda expression updates - TransactionDemo - DynamoDB transactions with single-table design and SDK comparison
- InvoiceManager - Single-table design with hierarchical composite keys and
ToCompositeEntityAsync - StoreLocator - Geospatial queries comparing GeoHash, S2, and H3 spatial indexing
- INDEX - Alphabetical index of all topics
- QUICK_REFERENCE - Quick lookup for common operations
Get started quickly → Quick Start Guide
Define my first entity → First Entity Guide
Perform CRUD operations → Basic Operations
Query data efficiently → Querying Data
Use expression formatting → Expression Formatting
Write type-safe update operations → Expression-Based Updates
Optimize queries with projections → Projection Models
Use single-table design → Multi-Entity Tables
Configure optional features (logging, geospatial, encryption) → Configuration Guide
Configure logging and diagnostics → Logging Configuration
Use advanced types (Maps, Sets, Lists, TTL) → Advanced Type System
See practical examples → Advanced Types Examples
See a complete CRUD application → TodoList Example
Learn DynamoDB transactions → TransactionDemo Example
Implement single-table design → InvoiceManager Example
Build location-based queries → StoreLocator Example
Migrate existing entities → Advanced Types Migration
Work with complex entities → Composite Entities
Configure discriminators for single-table design → Discriminators
Protect sensitive data → Field-Level Security
Use location-based queries → Geospatial Support
Implement multi-tenancy → STS Integration
Optimize performance → Performance Optimization
Troubleshoot an issue → Troubleshooting Guide
Understand internal architecture → Internal Architecture
Find API methods quickly → API Reference
Find a specific topic → Documentation Index
The source generator eliminates boilerplate by automatically creating:
- Entity mapping methods (C# ↔ DynamoDB)
- Field name constants for type safety
- Key builder methods for partition and sort keys
- Strongly-typed query results
Write concise, readable expressions using string.Format-style syntax:
.Where($"{UserFields.Status} = {0} AND {UserFields.CreatedAt} > {1:o}", "active", DateTime.UtcNow.AddDays(-30))- Single entities - Traditional one-to-one mapping
- Multi-item entities - Entities spanning multiple DynamoDB items
- Related entities - Automatic population based on sort key patterns
- Composite keys - Computed and extracted key components
- Zero runtime reflection - all code generated at compile time
- AOT compatible - works with Native AOT and trimming
- Optimized for DynamoDB best practices
dotnet add package Oproto.FluentDynamoDbThe source generator is automatically included and runs during compilation.
- Quick Start - Get up and running in 5 minutes
- Entity Definition - Learn how to define entities
- Basic Operations - Master CRUD operations
- Querying Data - Learn to query efficiently
- Composite Entities - Work with complex data patterns
- Global Secondary Indexes - Optimize access patterns
- Performance Optimization - Tune for production
- STS Integration - Implement secure multi-tenancy
- Troubleshooting Guide - Common issues and solutions
- Error Handling - Exception handling patterns
- Attribute Reference - Verify attribute usage
Oproto.FluentDynamoDb is developed and maintained by Oproto Inc, a company building modern SaaS solutions for small business finance and accounting.
- 🏢 Company: oproto.com
- 👨💻 Developer Portal: oproto.io
- 📚 Documentation: fluentdynamodb.dev
- Dan Guisinger - danguisinger.com
We welcome contributions! Please:
- Report issues and bugs on GitHub
- Suggest new features
- Submit pull requests
- Improve documentation
This project is licensed under the MIT License - see the LICENSE file for details.
- Documentation Issues: Check the Troubleshooting Guide
- Feature Requests: Open an issue on GitHub
- Bug Reports: Include a minimal reproduction case
- Questions: Use GitHub Discussions for community support
Documentation for Oproto.FluentDynamoDb v0.3.0 and later. The library uses source generation with expression formatting as the recommended approach.