KoutenDB v0.9.0

KoutenDB v0.9.0 is a locality and validation release. It adds a more realistic related-data read benchmark, improves bounded stellar/subring reads, and records the large local validation results that drove the storage-path changes.

Release:

https://github.com/puffball1567/koutendb/releases/tag/v0.9.0

What Changed

  • Added examples/subring_bundle_bench.nim.
  • Added examples/subring_bundle_postgres_bench.sh.
  • Added per-subring limit and sort validation for stellar reads.
  • Optimized readStellar by preparing projection state once and reusing it across subrings.
  • Added a bounded ring-window read path for simple embedded reads with empty filters, positive limits, and id or time sorting.
  • Added cached disk segment read streams for disk-backed segment reads.
  • Updated benchmark documentation with the latest local PostgreSQL and KoutenDB related-data bundle comparison.
  • Updated effect-validation documentation with the completed 13.5M-record local stress result.

Why This Matters

This release focuses on a practical shape that appears in ordinary applications: a detail endpoint that needs a root entity plus several related collections, where each collection has its own limit and sort order.

In KoutenDB this can be expressed as nearby subrings:

kouten get --ring=users/<id> \
  --subring=profile,addresses,career,preferences,orders,notifications \
  --subring-limit=profile:1,addresses:3,career:2,preferences:1,orders:10,notifications:5 \
  --subring-rsort=orders:time,notifications:time

The goal is not to claim that KoutenDB is universally faster than PostgreSQL or Redis. The goal is narrower and more important for KoutenDB’s design: when the application already has useful locality, KoutenDB should retrieve the nearby working set directly, without turning the request into a broad scan or a response-shaping query.

Local Benchmark Result

Measured on 2026-07-21 with AMD Ryzen 5 5600H, Linux 6.8, Nim 2.2.10, and PostgreSQL 14.23. The helper creates fresh temporary KoutenDB and PostgreSQL data directories.

Reproduce:

N=10000 READS=1000 examples/subring_bundle_postgres_bench.sh

Result:

Users Logical records Group Query shape Returned records read latency us
10,000 1,050,000 KoutenDB users/<id>/* stellar read with per-subring limits/sorts 22 across 6 rings 196.859
10,000 1,050,000 PostgreSQL 14.23 six indexed SELECT statements 22 515
10,000 1,050,000 PostgreSQL 14.23 one JSON aggregate query over indexed limited subqueries 1 JSON bundle 236

This is a specific related-data bundle workload, not a universal PostgreSQL claim. PostgreSQL can express the result with indexed limited subqueries and JSON aggregation, but the query shape is no longer a plain join. KoutenDB expresses the access pattern as bounded nearby subrings.

Large Effect Validation

The generated scale-1000 effect-validation path also completed locally with 13,500,000 documents in the largest standard case. The measured result is documented in docs/effect-validation.md.

Summary:

  • small-balanced: 168000 -> 24000 scanned records, 692 -> 260 estimated tokens.
  • near-distractors: 1860000 -> 120000 scanned records, 1730 -> 433 estimated tokens.
  • medium-noisy: 13500000 -> 500000 scanned records, 2595 -> 692 estimated tokens.

The largest case also exposed a useful follow-up target: post-import segment packing is much faster than the earlier unbuffered path, but still large enough to keep optimizing.

Verification

This release state was verified with:

  • nim check src/kouten/store.nim
  • nim check src/koutendb.nim
  • nim check src/koutencli.nim
  • nim check tests/tapi.nim
  • nim c --nimcache:/tmp/nimcache_kouten_tapi -r tests/tapi.nim
  • scripts/test_all_smoke.sh
  • nimble check
  • git diff --check

The large generated benchmark is intentionally manual and is not part of the default CI smoke suite.