# bison-db v0.8.0 — Release candidate: head-to-head

**The numbers, measured.** v0.8.0 is the release candidate, and it delivers the
one thing the beta deferred: a controlled head-to-head benchmark against a peer
embedded engine, run for real and reported honestly. No code changed — the API
and on-disk format remain frozen.

## What is bison-db?

An embedded, document-oriented database for Rust: store schemaless documents
entirely in-process, with no server, no network, and no external services. The
whole database is one file, writes are appended to a checksummed log, and a crash
never leaves a half-written record behind.

## What's new in 0.8.0

### Head-to-head vs redb

The closest single peer to bison-db's storage engine is
[`redb`](https://github.com/cberner/redb) — a pure-Rust, actively-maintained,
ACID embedded key/value store. The new [`benchmarks/`](https://github.com/jamesgober/bison-db/tree/main/benchmarks)
crate runs both engines through the same workload.

**Crucially, it is a standalone crate detached from the package** (its own
empty `[workspace]`), so redb never enters bison-db's dependency tree, its
`cargo audit`/`cargo deny` surface, or CI — and the published crate excludes it.
A database library should not ship a peer database in its dependency graph just
to benchmark against it.

**Workload:** 100,000 records, 64-byte payload, keyed `1..=N`; bulk insert with
one durability sync per engine (no per-operation `fsync` on either side), then
100,000 random point reads after a cold reopen. Median of three trials,
Linux/WSL2, x86_64, Rust 1.95, release.

| Metric | bison-db | redb | Result |
|--------|---------:|-----:|--------|
| Insert (records/s) | **~1.9 M** | ~1.1 M | bison-db ~1.85× faster |
| Read (per op) | ~285 ns | **~215 ns** | redb ~1.3× faster |
| File size | **~10.9 MB** | ~17.0 MB | bison-db ~35% smaller |

### Reading the result honestly

bison-db wins bulk writes and disk footprint; redb wins point reads. The split is
architectural, not accidental:

- **Writes** — bison-db's log-structured append is one sequential write per
  record, with no page management or B-tree rebalancing, so it loads faster.
- **Disk** — bison-db's compact tagged encoding packs the same data smaller than
  redb's paged B-tree layout here.
- **Reads** — redb is memory-mapped, so a point read is a pointer chase in cached
  pages; bison-db does a positional `read` syscall per `get` and decodes a **full
  typed document** (redb returns raw bytes). Being only ~1.3× behind while doing
  strictly more work per read is a reasonable showing, and the gap is a known,
  honest optimization avenue — a read cache or memory-mapped reads — for a
  post-1.0 release. It is not a design limit, and it does not touch the frozen API
  or format.

The honest takeaway: bison-db is **competitive with a respected pure-Rust
engine** — ahead on writes and size, modestly behind on reads — while offering a
richer document model on top. And against a *networked* document database
(MongoDB and the like), the in-process advantage is structural and far larger —
a read is a ~0.3 µs function call, not a serialized socket round trip; see
[`docs/PERFORMANCE.md`](https://github.com/jamesgober/bison-db/blob/main/docs/PERFORMANCE.md)
for that analysis in full.

## Breaking changes

**None.** This release adds a detached benchmark crate and documentation; no
public item, and no on-disk byte, changed.

## Verification

The library is unchanged and still green on Windows x86_64 and Linux (WSL2
Ubuntu), Rust stable 1.95.x, across the CI matrix (Linux, macOS, Windows; stable
and MSRV 1.85):

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --all-features
cargo build --no-default-features
cargo build --examples
cargo audit
cargo deny check
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
```

All green; `cargo audit`/`cargo deny` clean and unchanged (redb is not in the
library's tree). The benchmark crate builds and runs separately with
`cd benchmarks && cargo run --release`.

## What's next

- **v0.9.0 → 1.0.0 — Final soak / Stable.** A soak against real usage, then
  publish 1.0 with the API and format already frozen. No further API or format
  changes are planned before 1.0.

## Installation

```toml
[dependencies]
bison-db = "0.8"

# With serde support for the document model:
bison-db = { version = "0.8", features = ["serde"] }
```

MSRV: Rust 1.85 (2024 edition).

## Documentation

- [README](https://github.com/jamesgober/bison-db/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/bison-db/blob/main/docs/API.md)
- [On-disk Format](https://github.com/jamesgober/bison-db/blob/main/docs/FORMAT.md)
- [Performance](https://github.com/jamesgober/bison-db/blob/main/docs/PERFORMANCE.md)
- [Roadmap](https://github.com/jamesgober/bison-db/blob/main/dev/ROADMAP.md)
- [CHANGELOG](https://github.com/jamesgober/bison-db/blob/main/CHANGELOG.md)

---

**Full diff:** [`v0.7.0...v0.8.0`](https://github.com/jamesgober/bison-db/compare/v0.7.0...v0.8.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/bison-db/blob/main/CHANGELOG.md#080---2026-06-08).
