Demystifying
DynamoDB

A distributed database built from first principles on Cloudflare Durable Objects. Exact API compatibility with zero magic.

Get Started How it Scales

Alpha Release v0.1.0

The Vision

DynamoDB scales to absurd throughput not because of magic, but because of brutal operational discipline. shvm-db forces you to understand these physics by rebuilding them yourself.

Core Principles

Exact Parity: PutItem, GetItem, Query—same semantics, same constraints.
Single Writer: One partition key maps to exactly one Durable Object.
Zero Layers: No hidden caches. SQLite is the only source of truth.
Pay-per-Request: Scale to zero when idle, scale to infinity when hot.

// It's just an API call.
await client.send(new PutItemCommand({
  TableName: "Users",
  Item: {
    PK: { S: "user_123" },
    SK: { S: "profile" },
    role: { S: "engineer" }
  }
}));

Architecture & Scaling

We achieve massive throughput by recursively splitting partitions when they get hot.

Client

Worker Router Hash(PK) → Range

                            Durable Object
                            Partition Owner
                        

SQLite WAL Mode

Micro-Partitions

Partitions start as `(PK, -inf, +inf)`. As load increases, they split into `(PK, -inf, "m")` and `(PK, "m", +inf)` based on Sort Key.

Hot Partition Mitigation

If a single item is hot (e.g. 10k RPS), we can't split further. Solution: Write sharding (application level) or read replicas (eventual consistency).

Recursive Splitting

Durable Objects monitor their own CPU usage. If >80%, they trigger a split, migrating half the key range to a new DO instantly.

Distributed Systems Reality

Building a database at scale means choosing your tradeoffs explicitly. Here is how shvm-db handles the hard stuff.

Concurrency Control

Every write is serialized through a single Durable Object thread. We support Conditional Writes (Optimistic Concurrency Control) using `ConditionExpression`. If the version mismatches, the request is rejected with `400`.

Global Tables

For multi-region active-active replication, we use Last Writer Wins timestamps. Writes are propagated asynchronously via DO Alarms to other regions. Conflicts are resolved deterministically based on wall-clock time.

Throughput Bottlenecks

The hard limit is the single-threaded event loop of a Durable Object. Approx 2k writes/sec per partition. To scale beyond, you MUST design your schema to spread writes across PKs.

// Conditional Write Example
// Fail if someone else updated it
await client.send(new PutItemCommand({
  TableName: "Counter",
  Item: {
    PK: { S: "cnt" },
    val: { N: "11" },
    ver: { N: "2" }
  },
  ConditionExpression: "ver = :v",
  ExpressionAttributeValues: {
    ":v": { N: "1" }
  }
}));

DemystifyingDynamoDB