Getting Started

Getting Started

DynamoDbLite is an in-process IAmazonDynamoDB backed by SQLite — use it as a drop-in replacement for DynamoDB in tests, local development, and offline-capable apps. This page walks through installation, DI registration, direct construction, and a minimal working example.

Built against AWSSDK.DynamoDBv2 v4 on .NET 10. See the AWS DynamoDB Developer Guide for DynamoDB concepts.

Prerequisites

• .NET 10 SDK
• Source reference — NuGet packages are not yet published

Installation

Add a project reference to DynamoDbLite:

<ProjectReference Include="..\DynamoDbLite\DynamoDbLite.csproj" />
<ProjectReference Include="..\DynamoDbLite.DependencyInjection\DynamoDbLite.DependencyInjection.csproj" /> <!-- optional, for DI registration -->

Setup

Option 1: Dependency Injection

Register DynamoDbLite with your DI container using AddDynamoDbLite(). The client is registered as a singleton IAmazonDynamoDB.

From configuration (appsettings.json):

{
  "DynamoDbLiteOptions": {
    "ConnectionString": "Data Source=DynamoDbLite;Mode=Memory;Cache=Shared"
  }
}

using DynamoDbLite.DependencyInjection;

builder.Services.AddDynamoDbLite(builder.Configuration);

// Or with a custom section name
builder.Services.AddDynamoDbLite(builder.Configuration, "MyCustomSection");

The configuration section name defaults to "DynamoDbLiteOptions". Pass a second argument to use a different section.

With explicit options:

builder.Services.AddDynamoDbLite(new DynamoDbLiteOptions(
    "Data Source=myapp.db"));

The AddDynamoDbLite method uses TryAddSingleton, so it won't overwrite an existing IAmazonDynamoDB registration.

Option 2: Direct Instantiation

using DynamoDbLite;

// In-memory (default)
var client = new DynamoDbClient();

// In-memory with explicit connection string
var client = new DynamoDbClient(new DynamoDbLiteOptions(
    "Data Source=DynamoDbLite;Mode=Memory;Cache=Shared"));

// File-based (persistent)
var client = new DynamoDbClient(new DynamoDbLiteOptions(
    "Data Source=myapp.db"));

DynamoDbClient implements IDisposable but not IAsyncDisposable — use using var, not await using. Or let the DI container manage its lifetime.

Storage Modes

Mode	Connection String	Use Case
In-Memory	Data Source=DynamoDbLite;Mode=Memory;Cache=Shared	Unit tests, development
File-Based	Data Source=myapp.db	Persistent storage, mobile apps

The mode is auto-detected from the connection string: if it contains :memory: or Mode=Memory, an in-memory store is used; otherwise, a file-based store is created. File-based stores enable WAL (write-ahead logging) mode automatically.

Minimal Working Example

using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;
using DynamoDbLite;

using var client = new DynamoDbClient();

// Create a table
await client.CreateTableAsync(new CreateTableRequest
{
    TableName = "Users",
    KeySchema =
    [
        new KeySchemaElement { AttributeName = "UserId", KeyType = KeyType.HASH }
    ],
    AttributeDefinitions =
    [
        new AttributeDefinition { AttributeName = "UserId", AttributeType = ScalarAttributeType.S }
    ],
    ProvisionedThroughput = new ProvisionedThroughput
    {
        // Accepted for API compatibility but not enforced — DynamoDbLite has no capacity limits.
        ReadCapacityUnits = 5,
        WriteCapacityUnits = 5
    }
});

// Put an item
await client.PutItemAsync(new PutItemRequest
{
    TableName = "Users",
    Item = new Dictionary<string, AttributeValue>
    {
        ["UserId"] = new() { S = "user-123" },
        ["Name"] = new() { S = "Alice" },
        ["Age"] = new() { N = "30" }
    }
});

// Get the item
var response = await client.GetItemAsync(new GetItemRequest
{
    TableName = "Users",
    Key = new Dictionary<string, AttributeValue>
    {
        ["UserId"] = new() { S = "user-123" }
    }
});

Console.WriteLine(response.Item["Name"].S); // "Alice"

Configuration Reference

DynamoDbLiteOptions is a positional record with a single property:

Property	Type	Default	Description
ConnectionString	string	"Data Source=DynamoDbLite;Mode=Memory;Cache=Shared"	SQLite connection string

The connection string follows Microsoft.Data.Sqlite connection string format, but is normalized before use: Pooling=true, Mode=ReadWriteCreate, and ForeignKeys=true are forced. Specifying these in your connection string has no effect.

Next Steps

• Table Operations — creating and managing tables
• Item Operations — reading and writing data
• Query and Scan — filtering and scanning items
• Secondary Indexes — adding GSIs and LSIs