puffball1567

Posted on Jul 17

RocheDB v0.6.0: Locality Validation, Topology Remapping, and Safer Query Boundaries

#database #ai #rag #showdev

I released RocheDB v0.6.0.

Release:

https://github.com/puffball1567/rochedb/releases/tag/v0.6.0

RocheDB is a ring-oriented NoSQL document and vector database written in Nim.
The project is still a technical preview, but v0.6.0 is an important release
because it moves more of the project from concept and happy-path demos toward
measurable locality behavior.

The main theme of this release is:

If data locality is part of the database model, it should be tested as an
invariant, not only described as an idea.

What Changed

v0.6.0 focuses on five areas:

safer read filters;
topology remapping foundations;
locality validation workloads;
easier operational configuration;
practical use-case recipes.

The release adds typed RocheFilterBuilder helpers so applications can build
read filters without string-concatenating JSON.

It also adds topology remapping primitives:

explicit arc tables;
weighted arcs;
deterministic virtual arcs;
topology validation;
remapFraction.

These do not mean RocheDB has full online dynamic membership or live rebalance
yet. They are lower-level primitives for modeling ownership and remapping
behavior before exposing a larger operational protocol.

Locality As An Invariant

The most interesting part of v0.6.0 is the locality validation work.

RocheDB's thesis is that meaningful placement can reduce unnecessary reads,
transfers, memory pressure, and downstream AI/RAG work. But that claim needs to
survive less friendly workloads than a clean first benchmark.

So v0.6.0 adds workloads for:

random writes;
delete-heavy patterns;
backfill-heavy patterns;
hot/cold data;
interleaved writes;
compaction before/after checks.

The invariant is simple:

The same logical ring query should return the same ID/payload set before and
after compaction, while RocheDB reports locality metrics such as candidate
size and disk-span behavior.

That matters because data-locality systems can look good when data is inserted
cleanly once. Real systems mutate, delete, backfill, and query from odd angles.
This release starts testing that pressure directly.

Why This Matters For AI And RAG

RocheDB is not only for AI workloads, but AI/RAG is one of the clearest places
where locality can matter.

In many retrieval-heavy systems, the expensive part is not always finding one
record. The expensive part is opening too much unrelated data, transferring it,
holding it in memory, reranking it, summarizing it, or passing it downstream as
LLM context.

RocheDB tries to make the application's natural locality part of the retrieval
model.

For example:

docs/japan/support
tenant/acme/orders/2026
users/123/profile

These are not just labels after retrieval. In RocheDB, rings are placement and
read-scope units. A good ring can reduce the candidate set before more
expensive ranking or application logic begins.

v0.6.0 does not claim that RocheDB is universally faster than Redis,
PostgreSQL, MongoDB, Apache Arrow, or a dedicated vector database. The more
careful claim is narrower:

RocheDB is building a database model where locality can be measured,
preserved, and used to reduce unnecessary retrieval work.

Safer Query Boundaries

This release also adds typed filter helpers.

Instead of building filter JSON by concatenating strings, applications can use
structured helper APIs. That is not a flashy database feature, but it matters
for a database that wants to be usable from application code and from multiple
drivers.

The same direction applies to the CLI and C ABI work in recent releases:
RocheDB is trying to keep the public surface small, explicit, and testable.

Operational Configuration

v0.6.0 adds CLI connection config loading through:

roche --config=roche.json health

or:

ROCHE_CONFIG=roche.json roche health

Example:

{
  "peers": ["127.0.0.1:17301"],
  "galaxy": "docs",
  "user": "alice",
  "password": "secret",
  "secretKey": "shared-secret",
  "tls": true,
  "tlsCaFile": "certs/ca.pem",
  "tlsServerName": "rochedb.internal"
}

This makes local demos and small deployments easier to repeat without copying a
long list of flags into every command.

Use-Case Recipes

I also added docs/use-case-recipes.md.

It covers examples such as:

list/detail screens;
membership records;
inventory-style locks;
webhook idempotency;
SaaS tenant isolation;
stellar neighborhood reads;
RAG corpus layout.

The point is to show where RocheDB's model is useful outside benchmark scripts.
RocheDB is not trying to replace every database shape. It is trying to be strong
when data has meaningful locality and when reducing the candidate working set
matters.

Try The Locality Demo

The locality demo can be run with:

examples/locality_layout_demo.sh

It exercises different write patterns, compaction, and logical result checks.

The important output is not just a speed number. It is whether RocheDB can keep
the logical query result stable while reporting how the physical layout changes.

Current Boundaries

RocheDB remains a technical preview.

Some important things are still not finished:

online dynamic membership;
live rebalance;
cluster transaction coordinator redundancy;
full production-grade operational hardening;
larger real-corpus benchmarks.

Universe sync remains an eventual-convergence primitive, not a consensus or
quorum system.

That boundary is intentional. I would rather keep the claims narrow and make
the measurements stronger than present RocheDB as a finished replacement for
existing databases too early.

Links

Repository:

https://github.com/puffball1567/rochedb