I released KoutenDB v0.10.0.
Release:
https://github.com/puffball1567/koutendb/releases/tag/v0.10.0
KoutenDB is a ring-oriented document and vector database written in Nim. Its core idea is to make an application's locality boundary part of the read path:
place related data together, select that boundary before retrieval, and avoid making unrelated records candidates in the first place.
That idea needs more than a clean benchmark. A database also has to keep running while it writes persistent state, serves reads, tracks topology state, and eventually shuts down for verification.
For v0.10.0, I ran a local persistent three-node cluster continuously for 72 hours. The result was simple and useful: the run completed with zero client errors, and all three data directories passed offline verification after the servers stopped.
What the endurance run did
The runner started three local TCP nodes with persistence enabled and exercised
a mixed workload every 250 ms for 259,200 seconds.
The workload included:
- TCP writes;
- point reads using IDs returned by earlier writes;
- JSON projection queries;
- bounded ring reads with sort and limit;
- ring-scoped exact vector retrieval;
- metrics collection;
- a final snapshot and offline verification after shutdown.
The runner builds its own copy of the server, CLI, and workload binaries under the run directory before it starts. This matters because rebuilding the source tree during a long run cannot silently change the executable being tested.
The exact run used commit 87c755c9130ec0bbf70a3903c75fd2bdae8b084b.
Final result
| Operation | Completed |
|---|---|
| PUT | 969,281 |
| returned-ID GET | 969,281 |
| projection query | 969,281 |
| bounded ring read | 969,281 |
| ring-scoped retrieve | 96,928 |
| metrics read | 48,464 |
| client errors | 0 |
That is 4,022,516 completed logical client operations across the 72-hour period.
After the workload finished, the runner took its final snapshot, stopped the three nodes, and ran offline kouten verify against every persistent data directory. All three verifications succeeded.
The final operational counters also showed:
- zero pending handoffs;
- zero handoff queue depth;
- zero handoff failures, stale acknowledgements, or queue-full events;
- zero remaining migrations;
- zero universe-sync errors;
- zero global retrieval requests.
The last point is important for KoutenDB's design. The workload used ring-scoped retrieval, and the metrics confirmed that it did not silently fall back to a cluster-wide retrieval path.
Why this is more useful than a startup smoke test
A startup test can show that a server accepts a request. It does not show what happens after hundreds of thousands of persistent writes, repeated read paths, periodic metrics calls, topology bookkeeping, and a full stop-and-reopen boundary.
This run specifically exercised the persistent cluster path over time:
- records were written to disk-backed nodes;
- later requests read data that had been accumulated by the same run;
- cluster handoff and migration counters were observed throughout the run;
- the servers were stopped cleanly;
- the on-disk state was opened and verified offline.
It does establish a concrete baseline: KoutenDB can sustain a mixed, persistent local cluster workload for three days without a client-visible error or an offline integrity failure.
What changed in v0.10.0
The endurance runner is one part of a larger operational hardening release.
- Operational configuration can now be loaded and verified before a server is used.
- Write guardrails, audit events, capacity thresholds, and backup verification provide explicit operational checks.
- Explicit scale-in migration and rolling topology activation add controlled drain, handoff, and progress behavior.
- Cluster retrieval now remains in the requested ring rather than falling back to a cluster-wide scan.
- Physical placement is decoupled from the logical orbit schedule, so a logical orbit boundary does not stall local request processing.
- Handoff I/O is kept off the request loop, and stale handoff replay cannot resurrect an older mutation.
- The optional FAISS backend was removed. Vector retrieval now follows the core KoutenDB model directly: select a ring first, then perform exact cosine ranking over that bounded candidate set.
These are not unrelated features. They move the project from a collection of locality experiments toward an operable persistent service: know what the server is configured to do, constrain unsafe operation, observe background state, and verify the data after a long workload.
Reproducing the run
The runner is included in the repository:
KOUTEN_SOAK_SECONDS=259200 \
KOUTEN_SOAK_WORKDIR=/tmp/koutendb-soak-72h \
examples/soak_72h.sh
It writes JSON Lines progress, node logs, final metrics, a final snapshot, offline verification output, the workload configuration, and a completed.ok marker only after all final verification steps succeed.
The full configuration and scope are documented here:
https://github.com/puffball1567/koutendb/blob/main/docs/soak-testing.md
The run is intentionally not a CI job. A three-day endurance test is useful because it is long enough to observe persistent operational behavior; it would make normal pull-request feedback unusably slow.
The next reliability question
This result validates the current local, disk-backed, buffered-durability cluster mode. The next endurance variants are clear: strong-durability writes, TLS and authenticated transport, Docker/container deployment, and eventually multiple machines.
Those tests extend this baseline rather than replace it. The v0.10.0 result is now a documented, reproducible reference point for future changes to storage, handoff, topology, and retrieval behavior.
Source:
Top comments (0)