HanuDB
A database that lives in a bucket.
A document database for one small machine whose durable home is a bucket.
The idea
Think of a shop with one till. The till keeps a paper roll of every sale. Every evening the roll is photographed and the photos are sent to a safe across town. If the shop burns down, a new till reads the photos and is back in business by lunch. HanuDB is a till that sends its roll away every second, not every evening.
Read the full story →Why it matters
We build apps. None of them needs a big database. But every one of them needs a database.
Document storeObject storageOne small machine
How it works
- Your app
- HanuDBone small machine
- A bucketthe durable home
Read and write → Kept durable → Rebuilt from the bucket
Open sourceThe code is public. Read it, run it, and ask about anything in it.
Explore deeper Each path is a different view of the same work.
Why it exists
Every small app needs a database, and almost none of them needs a big one. A managed database costs more per month than the machine the app runs on. A database file on one machine is cheap, but when the machine goes, the data goes with it.
HanuDB was built for the gap between those two: one small virtual machine, the kind a cloud gives away for free, with the data kept safe somewhere that machine cannot take down.
What it is for
The apps around carebun.com, this site, and the community platform all keep their rows in it. Writes look like a document store, and reads look like a search engine. One process, one binary, one machine, and a bucket.
It is for the team that would rather read one database's source than pay for three services. It is not for the team with a terabyte and a thousand writes a second.
How it works, in one page
Every write goes first to a log on disk, synced in fast batches. From that log two things are fed: a key-value store for lookups by id, and a text index for search. That is why it can answer both kinds of question from one place.
The log is cut into segments, each one hashed and chained to the one before it, and the segments are shipped every second to one or two buckets. A fresh machine with nothing on it can read the segments in order and become the database again. That is the whole trick, and the number to remember is the rebuild time below.
Every change to the engine was measured against a fixed benchmark with hard gates for recovery, memory and cost. The changes that held are in the paper; the ones that did not are kept too, because a result that something does not help is the expensive kind to rediscover.
What was measured
Each number is read from the file named under it. Nothing here is rounded up.
~/apps/hanudb/README.md:43~/apps/hanudb/README.md:48~/apps/hanudb/README.md:50~/apps/hanudb/README.md:239~/apps/hanudb/results.tsvTry it yourself
Five segments of a write-ahead log. Each one's hash is computed over its content and the hash before it. Press a segment to change what is inside it, and watch every segment after it stop matching the chain a fresh machine would expect.
The real engine uses a cryptographic hash, not this toy one, and ships a segment every second. The shape is the same: a change anywhere is visible everywhere after it.
Common questions
Is it a replacement for Postgres?
No. It is for one machine and data that fits on it. It says so in its own README, and the limits are part of the design.
What happens if the machine dies?
A new one reads the bucket and rebuilds. A 4.5 GB snapshot plus its tail rebuilt in 40 seconds in the measured run.
Can I run it?
Yes. It is public under the MIT licence, with a one-line installer and clients for TypeScript, Python and Swift.
Ask a question
Ask about the code, the design or the numbers. Answers come from what is written on this site.
Carry thisA log that is shipped away every second is a backup, a replica and a rebuild plan at once.
live · this site runs on it · MIT