kurwadb a distributed set · elixir / beam bóbr, kurwa

A key is its own payload

Keys and nothing else. No values, no scans, no queries, no leader — one constraint, and everything downstream of it gets simpler.

A B C
keys landing on the ring, lighting the three replicas that own them
What it is for

Holding back the things you have already seen

Every job this store is good at is the same job: a flood arrives, and only the ones you have not seen before should get through. That is a dam built out of keys.

the set order:1029 order:1017 ✕ order:1031
arrived 128 already seen 41 passed 87
Deduplication
A message bus redelivers. Ask the set whether this event id has been handled, once, from any consumer on any node.
Idempotency keys
The client retried the payment. The second attempt has to find its own key already there — and if the store cannot tell you, it must say so rather than guess.
Rate limits
One key per caller per window, with a TTL the size of the window. The key deletes itself when the window closes.
Blocklists and frontiers
Blocked addresses, revoked tokens, URLs the crawler has already fetched. Membership is the whole question.
The record

What is missing is the point

a key-value store {key, value, version…}

Two writes disagree about the value, so something has to choose: vector clocks and siblings, a merge function, or a silent loss.

kurwadb {key, lamport, node, alive?, wall, expires_at}

Nothing to disagree about but existence, so the merge is a comparison of two numbers. There is no room for a value, and that is the feature.

Try it

Kill a node and watch what does not happen

The replica set for a key does not move when a node goes down — it keeps its share of the keyspace, and the writes it misses are kept for it. Click a node.

n = 3 · r = 2 · w = 2
:ok — 3 of 3 replicas took the write

A simulation of the behaviour the cluster tests assert, not a live cluster. Counters are illustrative.

Why

The chain

  1. A key has no contents.
  2. Two concurrent writes cannot disagree about anything but existence.
  3. Merging replicas is comparing {lamport, node}. A total order.
  4. So no vector clocks, no siblings, no merge function in the application.
  5. And no leader: any node coordinates any key.
What it buys

Six properties this was all for

No leader
Nothing to elect, no pause on failover. Losing a node costs capacity, not availability.
Self-healing
A node that was away keeps its share of the ring, and the writes it missed are kept durably and replayed when it returns — and a background pass compares replicas and fixes what drifted even when nobody read the keys. Nobody asks the beaver to repair the dam; it turns up with the logs.
Error ≠ absent
An unreachable quorum is a 503, never a false. This is exactly where cache-based deduplication lies to you.
339 ns
A local membership check is one :ets.lookup in the caller's own process — no mailbox, no copy.
Keys expire
A TTL becomes an absolute instant once, so every replica reaches the same verdict on its own. An expired key needs no tombstone to stay gone.
3 bytes per key
The on-disk engine keeps a Bloom filter in RAM instead of the keys — ten times less memory than Redis, and a key that is not there is answered in 200 ns without touching the disk, and one that is in 3.6 µs. That check is the one function written in Rust.
It mounts
The core knows nothing about protocols, so the store also speaks 9P: ls, cat, stat instead of admin endpoints.
API

Four operations

Kurwa.add("order:1029")      #=> :ok
Kurwa.member?("order:1029")  #=> true
Kurwa.delete("order:1029")   #=> :ok
Kurwa.count()                   #=> {:ok, %{approximate: 1, ...}}

Kurwa.add("seen:event:88", ttl: :timer.minutes(10))

Plus named sets and algebra over them, resolved at read time and copying nothing: member_any?(["blacklist", "greylist"], key). The sets themselves can be listed, because a set name is just a key in a reserved set — so it replicates and repairs itself like everything else.

Measured

Speed is part of the contract

A release that is slower than the one before it is a broken release. The regression is the bug, not the new baseline.

Which is only worth saying if it can be checked, so every figure here comes from a script in bench/, every version gets a column in PERFORMANCE.md, and when two versions are compared they are measured on the same day, in turns, so the machine's mood lands on both. 0.17.0 was held back twice by that rule: counters for the dashboard cost 7% on reads and 20% on PostgreSQL until they did not.

350 nsa local membership check
98 600/squorum reads, 3 nodes, 64 clients
136 500/sGET /k/:key, one node
544 000/skeys through POST /batch
3.0 BRAM per key, on-disk engine

Release over release

Reads a second across three nodes with a quorum of two, 64 concurrent clients, each version measured with bench/cluster.exs:

0.1.059 100
0.4.060 900
0.8.048 000 *
0.9.068 600
0.11.067 700
0.17.067 800
0.18.098 600

* measured after an OS update that slowed every version on this machine; 0.4.0 re-measured the same day read 44 300. 0.9.0 started one process per quorum instead of two; 0.18.0 stopped asking replicas it did not need.

And one key, in-process, on one node - Kurwa.member?, lower is better:

0.1.03.15 µs
0.4.02.94 µs
0.9.02.23 µs
0.11.01.24 µs
0.17.01.03 µs

0.11.0 answers inline when the only replica is the node itself; 0.17.0 reads its settings from :persistent_term instead of Application.get_env, five or six times a request.

Why 0.18.0 reads half again as fast

A quorum read needs r answers. Until 0.18.0 the coordinator asked all n replicas and kept the first r; but any r replicas overlap every write's w, because r + w > n, so the extra answers were only traffic. Now it asks r - itself first when it holds a copy, since it answers inline - and the rest only if those are slower than 10 ms. Same answer, a third of the messages:

A client reads a key through node A, which holds a copy; asking all n, A also asks B and C; asking r, only B clienthas(key) node Acoordinator+ its copy node Breplica node Creplica
replicas asked over the network per read: 1 · reads/s, 3 nodes, 64 clients: 98 600

Measured both ways the same day with KURWA_READ_FANOUT=all against the default: reads under load 63 900 → 98 600 a second (+54%), one read alone 39.7 → 36.7 µs, writes unchanged - they still go to all n, as they must. kurwadb's own JavaScript and Go clients compute the ring and send each key to one of its replicas, which on five nodes takes reads from 44 500 to 55 400 a second.

Every protocol, one path

One node, 64 clients, the protocol's own benchmark tool driving it. They land close together because none of them is what a request costs - the path behind the wire is the same for all of them:

ProtocolDriven byMembership checks / sec
HTTPab ×4, keep-alive136 500
PostgreSQL, preparedpgbench135 700 – 146 700
MySQLmysqlslap128 400 – 133 200
Redis (RESP)redis-benchmark110 700 – 129 000
MongoDBNode.js driver75 500 – 79 500
SQL Server, over TLStedious45 700 – 55 400

MongoDB and SQL Server read lower for their clients' sake, not the server's: a Node.js driver is one thread per process, and tedious does TLS in JavaScript. On the server, one findOne is 5.7 µs and one sp_executesql lookup about the same.

Against Redis, on the same machine

Not our numbers against someone's published ones - Redis 8.0.3 built here, both servers run one at a time, and since kurwadb speaks RESP the same redis-benchmark drives both: four threads, 64 connections, runs on 6 and 9 October 2026. bench/versus.sh reproduces it.

1M keys, 13 bytes eachRAM per keySISMEMBER/secpipelined ×16
Redis 8.0.330.2 B129–160k1.31–1.83M
kurwadb in-memory, RESP128.1 B111–129k0.61–0.91M
kurwadb in-memory, HTTP + JSON128.1 B124–137k—
kurwadb on-disk, hit from disk3.0 B93k—
kurwadb on-disk, miss3.0 B119k—
kurwadb, 3-node quorum (0.18.0)—99k—

Redis is 4× more memory-efficient than the in-memory engine - part of that is the Lamport stamp, origin, tombstone flag and expiry we store and it does not, the rest is BEAM overhead. The on-disk engine is 10× better than Redis, because what it keeps in RAM is a Bloom filter rather than the keys. On throughput Redis is the faster single server: 10–20% one request at a time, 1.5–2× pipelined, with the same client and protocol on both sides, so it is the cost of a request inside kurwadb, not the wire. A three-node kurwadb, every read confirmed by two machines, now answers at three quarters of single-node Redis.

So the case for it is not speed on one node. It is a set that outgrows RAM and is still answered exactly, writes acknowledged by two machines instead of one, and no primary to fail over from - the long version.

Apple M4, 10 cores; all three nodes share that one CPU, n=3 r=2 w=2. 128 bytes for a 13-byte key, 152 for a 36-byte one — jaki gruby, and measured rather than guessed.

Inside

How it fits together

Component stack: HTTP and 9P frontends over the key and named-set API, the extractor cache, a leaderless coordinator holding placement, quorum and handoff, and three replicas each with an ETS table and a write-ahead log
Every cost on the diagram was measured, not estimated.
Sequence diagram of a write: the coordinator stamps one record, sends it to two reachable replicas, answers ok once two acknowledge, and keeps a hint for the third
A write with one replica down, and the hint that heals it.
Sequence diagram of a read: the cache answers hits without touching the network, a miss becomes one quorum read, answers merge by highest lamport, and the replica that was behind is repaired
A read: cache, merge, and repair of whoever was behind.
9P

The database as a filesystem

stat is the membership check, create is the add, remove is the delete. Not a metaphor — the same data model.

9p -a localhost:564 ls /
ctl  stats  ring  keys  b64  sets

9p -a localhost:564 read ring
member [email protected] up
member [email protected] up
member [email protected] down

echo compact | 9p -a localhost:564 write ctl

No SDK, no vendor CLI. The key directories deliberately refuse to be listed: there are no scans here, and an empty listing would be a lie.

PostgreSQL

psql, mysql, sqlcmd, mongosh, redis-cli, and the driver you already have

kurwadb speaks the PostgreSQL wire protocol. A set is a table with one column, key, and the queries are the ones a set can answer without a scan.

INSERT INTO seen VALUES ('order:1'), ('order:2');
INSERT 0 2

SELECT key FROM seen WHERE key IN ('order:1', 'order:3');
 key
---------
 order:1
(1 row)

DELETE FROM seen WHERE key = 'order:1';
DELETE 1

SELECT * FROM seen;
ERROR:  SELECT from seen without WHERE key = ... would be a scan, and there are none

Prepared statements and binary results, so psycopg and node-postgres work as they are; \dt lists sets and \d describes one. There are no transactions — BEGIN is accepted because drivers send it unasked, and ROLLBACK says nothing was rolled back. Around 140,000 prepared statements a second under pgbench, on one node.

CREATE SCHEMA analytics, and analytics.events is the set named analytics.events. The catalogs are modelled well enough for a GUI: DBeaver's navigator lists schemas, tables and the key column, and its table designer is told at CREATE TABLE that the one column is called key, rather than finding out on the first insert.

The same tables answer over the MySQL protocol, to mysql, mariadb and the MySQL connectors — INSERT IGNORE, prepared statements, SHOW TABLES, columns named the way MySQL names them — around 130,000 queries a second.

And SQL Server: sqlcmd, ODBC and tedious connect over TLS, as they do by default, T-SQL's IF NOT EXISTS (…) INSERT is an insert with one winner, and stored procedures run from .sql files deployed with the node. SQL Server Management Studio connects too, and its Object Explorer shows kurwadb beside the system databases with every set as a table. SSMS does not ask a server what it is in a few queries: it runs dozens of generated batches across sys.* views and reads every column by type. So its answers were recorded once against a real SQL Server, with their exact types, and kurwadb replays them with its own databases, schemas and sets in the rows - all 60 of a recorded session match.

And MongoDB: a collection is a set, a document is {_id: key}, a second insert of an _id is E11000 with one winner, and every node answers as a mongos, so a driver given several nodes fails over between them on its own.

It speaks RESP too. Redis sets are named sets, Redis keys are the default set, and the idempotency check works as it does against Redis:

SET order:1 x EX 3600 NX     OK
SET order:1 x EX 3600 NX     (nil)
SADD seen:orders a b         (integer) 2
GET order:1                  ERR kurwadb stores keys without values

There are no values, so GET refuses rather than invent one. SET NX has one winner among concurrent callers, as on Redis — not from a single thread but from a majority of replicas, and WATCH aborts an EXEC when a watched key changed.

Watch

See the requests move

Every node serves a dashboard at /dashboard: each node's frontends, coordinator, replica layer and shards, with requests drawn travelling between them - from a client into a frontend, down to a shard, across to the other replicas - and every open connection named by the application it said it was. The counters behind it are one atomic add per layer per request, and the release that added them was held until it was no slower than the one before.

Open the live demo

The demo runs on simulated data in your browser: three nodes, a dozen clients, and a node that fails every couple of minutes so you can watch its clients move.

Clients

Its own clients, for when a driver is not enough

Any PostgreSQL, Redis or MongoDB driver works, but a generic driver talks to one address. kurwadb's own clients - JavaScript, no dependencies, and Go, standard library only - learn every node from one, rebuild the ring bit for bit, send each key to one of its replicas, and move off a node that fails.

const db = await connect({ nodes: ["10.0.0.1:6379"], password })
await db.addNew("payment:7f3a")   // true for exactly one caller, cluster-wide
await db.has("payment:7f3a")      // true, from a node that holds a copy
Limits

When not to take this

  • One node, and the set fits in RAM. Redis is simpler, has a decade in production and an ecosystem, is 10–20% faster on one server, and uses four times less memory than the in-memory engine. Take it.
  • False positives are acceptable and you never delete. A Bloom filter costs 1.2 bytes per key against the on-disk engine's 3.0.
  • You need scans, listings or queries. There are none, by construction, and that will not change.
  • You need the on-disk engine to be mature. It exists and passes the same test suite, but it is younger than the in-memory one and compaction is crude.
  • Zero hours in production. One author, two young client libraries, no TLS between nodes.
Start

Three nodes on your laptop

git clone https://github.com/holooloo/kurwadb
cd kurwadb && mix deps.get
scripts/cluster.sh                 # 4040, 4041, 4042

curl -X PUT localhost:4040/k/order:1029
curl -i   localhost:4041/k/order:1029   # 200 — read from a different node