# txn-db v0.6.0 — Optimization

**The commit hot path got materially cheaper.** v0.6.0 profiles the commit path,
adds a fast path for the dominant single-write transaction, and benchmarks the
contention-scaling behavior. There are no API changes — only faster commits and
documented numbers.

## What is txn-db?

A multi-version concurrency control (MVCC) transaction engine: the layer that
turns a key-value store into a transactional database. Every write produces a new
version tagged with a commit timestamp, so readers get a stable snapshot without
ever blocking writers, and writers detect conflicts at commit time. The version
store is a trait, so the engine composes on top of any backend that can keep
timestamped versions.

## What's new in 0.6.0

### Single-write commit fast path

The general commit path locks every shard a transaction touches, in sorted order,
after building per-key shard-index vectors and a guard vector and mapping keys
back to guards with binary search. That machinery is necessary for a multi-key,
multi-shard commit — but the overwhelmingly common transaction is a *single write
with no read set to validate*, and it needs none of it.

v0.6 adds a fast path for exactly that shape: lock the one shard, validate the one
key, apply it — no intermediate allocations, no sorting, no binary search.
Measured against the v0.5 general path with `criterion --baseline`:

| Benchmark | Change |
|-----------|-------:|
| `commit/single_key` | **−45 %** |
| `batch_commit/1` (one key) | **−41 %** |
| `read_modify_write` | **−37 %** |
| `point_read` | ~0 % (unchanged) |
| `batch_commit/512` | ~0 % (unchanged) |

No benchmark regressed. Single-key commits — the bulk of transactional traffic —
got roughly 40% cheaper, while reads and large multi-key batches were untouched.

### Contention-scaling benchmarks

A new suite, `benches/contention.rs`, measures committed-transaction throughput as
concurrent writers scale across 1, 4, 16, and 64 threads, in three workloads:

- **`disjoint_commits`** — each writer commits to its own keys. Throughput roughly
  doubles from 1 to 4 writers as independent commits land on different shards in
  parallel, then flattens as the per-transaction global bookkeeping (registering a
  reader for garbage collection, advancing the commit watermark) serializes.
- **`contended_commits`** — every writer retries against one shared counter. This
  is the worst case: a single hot key cannot be committed in parallel, so added
  writers only add retries.
- **`begin_drop`** — transactions begun and dropped, isolating the reader-registry
  cost.

The numbers, the methodology to reproduce them, and the known scaling limits are
in [`docs/PERFORMANCE.md`](https://github.com/jamesgober/txn-db/blob/main/docs/PERFORMANCE.md).

## Breaking changes

**None.** v0.6.0 is an optimization release with no API changes.

## Verification

Run on Windows x86_64 (Rust stable 1.95.x and MSRV 1.85) and on Linux (WSL2
Ubuntu); the configured CI matrix runs the same on Linux, macOS, and Windows:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo test                       # default features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.85 clippy --all-targets --all-features -- -D warnings
cargo +1.85 test --all-features
RUSTFLAGS="--cfg loom" cargo test --test loom_txn --release
cargo bench --bench txn_bench
cargo bench --bench contention
cargo deny check
cargo audit
```

All green. The test suite is unchanged from 0.5 — 43 unit + 23 integration + 33
doctests + 2 `loom` model checks — and the commit-path optimization is covered by
the existing correctness tests and the `loom` concurrent-commit checks.

## What's next

- **0.7.0 — Hardening + API freeze.** Adversarial interleavings, edge cases
  (timestamp wraparound, very large transactions, abort storms), long-running
  readers versus aggressive collection, cross-platform re-verification of the
  durable path, and the API formally frozen.

## Installation

```toml
[dependencies]
txn-db = "0.6"

# Opt into serializable isolation and/or a durable commit log:
txn-db = { version = "0.6", features = ["serializable", "durability"] }
```

MSRV: Rust 1.85 (the 2024 edition).

## Documentation

- [README](https://github.com/jamesgober/txn-db/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/txn-db/blob/main/docs/API.md)
- [Performance](https://github.com/jamesgober/txn-db/blob/main/docs/PERFORMANCE.md)
- [CHANGELOG](https://github.com/jamesgober/txn-db/blob/main/CHANGELOG.md)

---

**Full diff:** [`v0.5.0...v0.6.0`](https://github.com/jamesgober/txn-db/compare/v0.5.0...v0.6.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/txn-db/blob/main/CHANGELOG.md#060---2026-06-07).
