Documentation

Welcome to shvm-db documentation. This guide will help you connect to your database instance and run your first commands.

Quickstart

All requests to shvm-db follow the DynamoDB JSON protocol. You can use any standard HTTP client or the official AWS SDK.

Using cURL

# Create an item
curl -X POST https://shvm-db.workers.dev/api \
  -H "x-amz-target: DynamoDB_20120810.PutItem" \
  -H "Content-Type: application/x-amz-json-1.0" \
  -d '{
    "TableName": "Users",
    "Item": {
        "PK": {"S": "user_1"},
        "SK": {"S": "profile"},
        "name": {"S": "Alice"}
    }
  }'

Testing Guide

Since shvm-db is API-compatible with DynamoDB, you can run your existing test suites against it by simply changing the endpoint URL.

Local Testing

To run tests against a local instance:

1. Run npm run dev to start the worker locally on port 8787.
2. Configure your client to point to http://localhost:8787/api.

Partitioning Strategy

Our partitioning model is designed to handle extreme scale by dynamically adjusting the range of keys served by each Durable Object.

Recursive Splitting

Every partition starts covering the entire Sort Key range `(-inf, +inf)` for a given Partition Key. As write traffic increases beyond a threshold (e.g., 1000 WCU), the partition splits into two child partitions:

• Child A: `(-inf, split_key)`
• Child B: `(split_key, +inf)`

The splitting is transparent to the client. The Worker Router caches the partition map and directs requests to the correct child Durable Object.

Concurrency Control

Because each partition is single-threaded (JavaScript event loop), writes are naturally serialized. This guarantees Strong Consistency for reads and writes within a partition.

Conditional Writes

We support standard DynamoDB `ConditionExpression` syntax. Internally, this is implemented by checking the condition within the same SQLite transaction as the write operation. This provides atomic check-and-set semantics without explicit locking overhead.