Dev Blog #1: Introducing DynamoDbLite

[marklauter]

What is DynamoDbLite?

DynamoDbLite is an in-process implementation of the AWS IAmazonDynamoDB interface backed by SQLite. It provides a drop-in replacement for the real DynamoDB client — no AWS credentials, no internet, no provisioned capacity charges. Just add the NuGet package and point your DI container at it.

The goal is simple: make local development and testing with DynamoDB fast, free, and frictionless.

Why not DynamoDB Local?

AWS provides DynamoDB Local, a Java-based emulator that runs as a separate process. It works, but it has drawbacks:

• Requires a JRE and a separate process to manage
• Startup time adds friction to test suites
• Docker-based workflows add complexity
• Not embeddable in mobile or desktop apps

DynamoDbLite runs in-process. It's a C# library — instantiate it and go. In-memory mode is perfect for tests; file-based mode (with SQLite WAL) works for persistent local development or even embedded in mobile apps.

What's been built so far

The project has progressed through 11 development phases, each adding a layer of DynamoDB functionality:

1. Table Management — CreateTable, DeleteTable, DescribeTable, ListTables
2. Item CRUD — PutItem, GetItem, DeleteItem, UpdateItem with full expression support (ConditionExpression, ProjectionExpression, UpdateExpression) and all ReturnValues modes
3. Querying — Query and Scan with KeyConditionExpression, FilterExpression, pagination, and ScanIndexForward
4. Batch Operations — BatchGetItem (100-item limit) and BatchWriteItem (25-op limit) with multi-table support
5. Secondary Indexes — GSI and LSI with all projection types, sparse indexes, and UpdateTable for GSI create/delete with backfill
6. Transactions — TransactWriteItems and TransactGetItems with all-or-nothing semantics, idempotency tokens, and ReturnValuesOnConditionCheckFailure
7. TTL — Background expiration with automatic filtering on all reads
8. Tags — TagResource, UntagResource, ListTagsOfResource
9. Capacity & Limits — Mock responses for DescribeEndpoints and DescribeLimits
10. Export & Import — Background export to DynamoDB JSON format with file-based import
11. Storage Split — Refactored into InMemorySqliteStore and FileSqliteStore with proper concurrency handling

The test suite currently has 501 tests covering both storage backends.

How it works under the hood

The architecture maps DynamoDB concepts onto SQLite:

• Each DynamoDB table gets an items SQLite table with columns for partition key, sort key, TTL epoch, and a JSON blob for the full item
• Each secondary index gets its own SQLite table (idx_{tableName}_{indexName})
• DynamoDB expressions (ConditionExpression, FilterExpression, UpdateExpression, ProjectionExpression, KeyConditionExpression) are parsed using Superpower parser combinators into an AST, then evaluated in C#
• Key condition expressions are translated into SQL WHERE clauses for efficient querying
• The IAmazonDynamoDB interface is implemented as a partial class split by feature area

Tech stack

• C# 14 / .NET 10
• Microsoft.Data.Sqlite + Dapper for storage
• Superpower for expression parsing
• xUnit v3 for testing
• AWSSDK.DynamoDBv2 (v4) for the interface contract

What's next

There's still ground to cover — Streams, Global Tables, and some edge cases in expression evaluation are tracked as tech debt. The focus is on covering the operations that matter most for local dev and testing scenarios.

If you're working with DynamoDB in .NET and want a lighter alternative to DynamoDB Local, give it a try. Issues and feedback are welcome.

---

This is the first entry in the DynamoDbLite dev blog. Future posts will cover implementation details, design decisions, and new features as they land.