NimbusKV - a reactive, lock-free key-value store

Optimistic-concurrency core with lock-free reads always, and lock-free writes on Python's free-threaded runtime (3.13t/3.14t) - same code path either way. Built so you don't have to reimplement TTLs, locking, or reactive hooks across projects.

Why NimbusKV?

Most apps reinvent the same small-but-critical pieces: TTL bookkeeping, safe concurrent updates, and reactive hooks. NimbusKV packages those into a single drop-in - an immutable-snapshot store where reads never block and writers retry instead of locking - with optional durability through SQLite, Redis, MySQL, or PostgreSQL. Minimal API, maximum control.

When to use it

Session storage with automatic expiry
One-time tokens / OTPs and temporary secrets
Coordinating threads or workers without a polling loop (wait_for)
High-concurrency counters and shared state on free-threaded Python
Real-time workflows that react to key changes or expiry

Quick usage

# quick example (python)
from nimbuskv import NimbusKV

ld = NimbusKV()  # in-memory, default
ld.set('foo', 123)
print(ld.get('foo'))  # 123

# reactive, no polling
ld.subscribe(lambda k, e, old, new: print(k, e, old, '->', new))
ld.atomic('counter', lambda v: (v or 0) + 1)  # safe under concurrent writers

View on GitHub Docs

Core features

Automatic TTL
Set a TTL and forget it - keys expire reliably, with a distinct "expire" event so you can tell it apart from a manual delete.
Free-Threaded Ready
Lock-free reads, always. On Python 3.13t/3.14t, writes get true lock-free parallelism too - same code path, detected automatically.
Genuinely Reactive
subscribe() pushes every change to you. wait_for() blocks a thread until a condition holds - no polling loop, ever.
Atomic, Lock-Free Writes
atomic() and mset() give you safe compound updates - counters, multi-key transactions - without ever holding a lock.
Pluggable Persistence
Memory, SQLite, Redis, MySQL, or PostgreSQL. Write-through only - reads always come from memory, backends never sit on the hot path.
Real Async
aget/aset are genuinely non-blocking for in-memory data - no thread spawned pretending to be async work that was never I/O.

Implementation note: State lives as an immutable persistent snapshot (HAMT). Writers build a new snapshot and swap it in atomically, retrying on conflict instead of blocking - readers never wait on a lock, ever.

Design philosophy

Keep the API tiny, make the primitives composable, and optimise the common path. NimbusKV gives you TTLs, reactive subscriptions, and lock-free atomic updates - and leaves the rest to your application.

Contribute

Bug reports, PRs, and ideas are welcome. Submit them on GitHub and tag them help wanted.

Report an issue on GitHub →