# bison-db v1.0.0 — Stable

**1.0 is the commitment.** Every roadmap item is delivered, hardened, and
benchmarked. The public API and the on-disk format (version 1) are now stable:
no breaking change until 2.0, per semantic versioning. No code changed from
0.9.0 — this release declares the surface stable and supported.

## What is bison-db?

An embedded, document-oriented database for Rust: store, index, and query
schemaless documents entirely in-process, with no server, no network, and no
external services. The whole database is one file — trivial to ship, copy, and
back up — and every write is appended to a checksummed log, so a crash never
leaves a half-written record behind.

## The 1.0 surface

Everything below is stable and will not change incompatibly before 2.0.

- **Document model** — `Value` (null, bool, `i64`, `f64`, string, bytes, array,
  nested object) and `Document`, an insertion-ordered field map. Optional `serde`
  for any data format; a `no_std` build exposes the model without the store.
- **Single-file store** — `Db::open` / `insert` / `get` / `update` / `delete` /
  `flush`. Log-structured: writes are sequential appends, reads are one index
  lookup plus one positional read.
- **Crash safety** — every record is length-framed and CRC-32C checked; a write
  torn by a crash is detected and truncated on the next open, never misread. The
  byte layout is specified in [`docs/FORMAT.md`](https://github.com/jamesgober/bison-db/blob/main/docs/FORMAT.md).
- **Secondary indexes** — `create_index` / `drop_index` / `indexes`, with `find`
  (equality) and `range` (`RangeBounds<Value>`) queries over any number of
  fields. Queries also work without an index, so an index is a pure speedup.
- **Durability policy** — `SyncPolicy::Always` (fsync per write) or `Manual`
  (fsync on `flush`), selected through `DbOptions`.
- **Compaction** — `Db::compact` reclaims the space left by overwrites and
  deletes via a crash-safe atomic file swap; ids and indexes are preserved.
- **Concurrency** — single-writer, multi-reader; `Db` is `Send + Sync`, shared
  across threads behind `Arc<RwLock<Db>>`.

## How it got here

1.0 is the end of a deliberate, verified path — each step shipped green on
Windows and Linux:

- **0.2** — document model + single-file store + insert/get/delete.
- **0.3** — secondary indexes + field and range queries.
- **0.4** — configurable durability + recovery hardening + **on-disk format freeze**.
- **0.5** — compaction + concurrency model + **public API freeze**.
- **0.6** — fuzz-tested parse/recovery paths (decoder and `open` never panic on
  arbitrary, corrupted, or truncated input).
- **0.7** — randomized soak test against an in-memory model.
- **0.8** — controlled head-to-head benchmark against `redb`.
- **0.9** — sustained-load concurrency soak.

## Performance

Indicative medians (Linux/WSL2, x86_64, Rust 1.95, release), reproducible with
`cargo bench`:

| Operation | Median |
|-----------|-------:|
| `insert` (small doc) | ~0.9 µs |
| `get` (small doc) | ~0.36 µs |
| `find` by indexed field (10k docs) | ~65 ns |
| `find` by full scan (10k docs) | ~1.8 ms |

In a controlled head-to-head against `redb` (a pure-Rust ACID embedded engine),
bison-db is ~1.85× faster on bulk inserts and ~35% smaller on disk, while redb is
~1.3× faster on point reads. Against a networked document database the in-process
advantage is structural — a read is a sub-microsecond function call, not a
serialized socket round trip. Full method, environment, and analysis in
[`docs/PERFORMANCE.md`](https://github.com/jamesgober/bison-db/blob/main/docs/PERFORMANCE.md).

## Stability guarantee

- The public API will not change incompatibly before 2.0.
- The on-disk format is version 1 and frozen; a future incompatible format would
  bump both the format version and the crate's major version.
- Future work (a read cache, persistent indexes) is additive and does not alter
  the 1.0 surface.

## Breaking changes

**None.** The library is byte-for-byte identical to 0.9.0; 1.0.0 is the stability
declaration.

## Verification

Run on Windows x86_64 and Linux (WSL2 Ubuntu), Rust stable 1.95.x; the same
commands run in the CI matrix across Linux, macOS, and Windows on 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` and `cargo deny` clean. Test counts at this tag
(`--all-features`): 54 unit + 9 integration + 4 concurrency + 3 robustness +
3 property + 1 soak + 58 doctests.

## Installation

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

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

MSRV: Rust 1.85 (2024 edition). Platforms: Linux (x86_64, aarch64), macOS
(x86_64, Apple Silicon), Windows (x86_64).

## 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)
- [CHANGELOG](https://github.com/jamesgober/bison-db/blob/main/CHANGELOG.md)

---

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