AnimusDB

Open source · AGPL-3.0 · Pre-alpha

The DynamoDB API on hardware you control

Keep your AWS SDK and your queries. Point them at AnimusDB and the data stays on your own servers.

Install with Docker Read how it works

The only change in your application:

client = boto3.client(
    "dynamodb",
    region_name="eu-west-1",
    endpoint_url="http://db.internal:7102",
)

Why teams run it

Leaving AWS

Compute and object storage port in weeks. A decade of DynamoDB access patterns does not, which is why the data layer usually blocks the move. AnimusDB takes the same requests, conditional writes and pagination, so it stops blocking it.

Data residency

Pin a dataset to the country or datacentre your regulator names, even where no public cloud region exists. The cluster runs where you put it, on hardware whose owner you can name.

On-prem and edge

Factory floor, ship, forward site, private cloud. It runs where there is no managed service, and keeps running when the link back to head office does not.

If you are happy on DynamoDB and expect to be in five years, AnimusDB is not an upgrade: a managed service has less operational burden. Running it yourself also means capacity planning, upgrades, backups and a pager for the database. Two short articles cover the argument and the bill: why lock-in compounds and what self-hosting actually costs.

How it works

AnimusDB splits each table into tablets. Every tablet is its own Raft group, and its leader can sit on any node, so no node is special and leadership spreads out as the cluster grows. It is one binary per node, with no JVM and no external coordinator.

A write is acknowledged once a quorum of that tablet's replicas holds it, so reads and writes are strongly consistent. A small, separate Raft group keeps the map of which node holds which tablet. It is consulted when the topology changes, not on the path of your reads and writes.

The distributed code runs first in a deterministic simulator that injects partitions, crashes, clock skew and disk faults. Every run is driven by one seed, and a failing run replays exactly from it. That catches bugs early. It does not prove the database correct, because it exercises only the faults we thought to model.

# a simulation test fails and prints its seed; replay that exact history
$ ANIMUS_SEED=8402173355719163220 \
    cargo test linearizable_under_partition

How it works, in full, the architecture and why determinism matters.

Where it stands

Works today

  • Per-tablet Raft replication with linearizable writes
  • Tablet splits, movement and online rebalancing
  • Multi-tablet transactions (2PC, MVCC snapshot reads)
  • Secondary indexes, added and dropped online with backfill
  • Streams and time to live
  • On-demand backup and restore, plus point-in-time recovery to any second
  • Metrics endpoint, admin API and a built-in dashboard
  • Growing a cluster by seed address; drain and decommission to shrink one
  • A Kubernetes operator, smoke-tested in CI on a kind cluster
  • TLS on every port, mutual between cluster members (off by default)
  • Encryption at rest for the WAL, engine files and backups (off by default)
  • SigV4 with credential rotation and per-key allow lists (not full IAM)
  • Versioned on-disk formats, full-cluster and rolling upgrades
  • Zone-aware replica placement on Kubernetes

Not yet

  • Published benchmarks: the harness is built and the methodology disclosed, but there are no numbers yet
  • Multi-Region strongly consistent global tables: simulation-tested only, not run on real multi-Region hardware
  • Eventual-consistency global tables between clusters: simulation-tested only
  • TLS, encryption at rest and SigV4 on by default

Do not store production data in it yet. TLS, encryption at rest and SigV4 exist but are off by default, so do not expose an unconfigured cluster, and do not store data you cannot recreate.

What would end pre-alpha is written down: every item in the beta exit-criteria checklist must be met or explicitly waived. Today most of the soak, chaos, fuzzing, overload, runbook and release-signing items are not met. See full API compatibility, what we know about performance and known limits.

Try it in a minute

One node in Docker, with the DynamoDB endpoint on port 7102, the operator dashboard on 7103 and the data console on 7105. Prefer Cargo? Build from source and run a whole cluster in one process.

$ docker run --rm ghcr.io/animus-db/animusd:latest gen-config --nodes 1 --host 0.0.0.0 > animus.json
$ docker run -d --name animusd \
    -p 7102:7102 -p 7103:7103 -p 7105:7105 \
    -v animus-data:/var/lib/animus \
    -v "$PWD/animus.json:/etc/animus/cluster.json:ro" \
    ghcr.io/animus-db/animusd:latest \
    --config /etc/animus/cluster.json --node 0 --dir /var/lib/animus

Full install guide, including a multi-node cluster and a build from source. To follow the project, subscribe to the releases feed in any RSS reader, or use GitHub's Watch, Custom, Releases. Architecture decisions are written down and argued in the open in the design records; contributions need a DCO sign-off and a CLA (contributing guide).