# wal-db v0.3.1 — Segment rotation
**Bounded segment files.** v0.3.1 lets a log be striped across fixed-size segment
files in a directory instead of one ever-growing file, so recovery time stays
bounded and old, superseded segments can be archived or pruned. It is purely
additive: single-file logs are unchanged, and records, LSNs, and the four-call
API are identical. Opt in with one call.
## What is wal-db?
A write-ahead log primitive for Rust storage engines — the durability substrate
under `lsm-db`, `txn-db`, `raft-io`, and Hive DB. The append path is lock-free,
concurrent commits coalesce into one fsync, durability is platform-correct, and
recovery is provable from a torn write.
## What's new in 0.3.1
### Segments — `Wal::open_segmented`
A log is one continuous byte address space (an `Lsn` is a byte offset). v0.3.1
adds the option to store that space striped across fixed-size segment files
rather than in a single file:
```rust
use wal_db::Wal;
# fn main() -> Result<(), wal_db::WalError> {
# let dir = tempfile::tempdir().map_err(wal_db::WalError::from)?;
// 16 MiB segments in a directory. Everything else is exactly as before.
let wal = Wal::open_segmented(dir.path(), 16 * 1024 * 1024)?;
wal.append(b"striped across files")?;
wal.sync()?;
# Ok(())
# }
```
Because the address space stays contiguous, **records span segment boundaries
freely** — the same scheme PostgreSQL uses for its WAL — and the append,
recovery, and iteration logic is unchanged. A write or read that crosses a
boundary is split across the two files; segments are created lazily as the log
grows; and `sync` flushes only the segments with unwritten changes, not the whole
history. Segment files are named by their zero-padded index
(`00000000000000000000.wal`, `…01.wal`, …); the layout is specified normatively in
[`docs/ON_DISK_FORMAT.md`](../ON_DISK_FORMAT.md) and **frozen for the 1.x line**.
For composition, the backend is also available directly as `SegmentedStore` and
plugs into `Wal::with_store` like any other `WalStore`.
## Breaking changes
**None.** `SegmentedStore` and `Wal::open_segmented` are new; `Wal::open` and the
single-file path are untouched. A log written by 0.3.0 is read by 0.3.1
unchanged.
## Verification
Run on Windows x86_64 and Linux (WSL2 Ubuntu), Rust stable 1.95.x and MSRV
1.85.0; macOS is covered by the CI matrix:
```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo +1.85 clippy --all-targets --all-features -- -D warnings
cargo test --all-features
RUSTFLAGS="--cfg loom" cargo test --test loom_wal
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.85 build --all-features
cargo audit
cargo deny check
```
All green on both platforms. Counts at this tag:
- 47 unit tests (7 new for `SegmentedStore`)
- 10 integration tests (4 round-trip, 4 segmented, 1 torn-write property test,
1 cross-process durability)
- 2 loom model-check tests
- 21 doctests
The segmented integration tests cover records spanning many segments, a single
record larger than a segment, multi-segment recovery on reopen, eight concurrent
writers crossing rotation boundaries, and torn-tail truncation across files.
## What's next
- **0.4.0 — Recovery hardening + `serial-io`.** A `cargo-fuzz` harness for the
recovery path, skip-bad-records recovery policy, and optional typed records via
the `serial-io` feature.
## Installation
```toml
[dependencies]
wal-db = "0.3"
```
MSRV: Rust 1.85.
## Documentation
- [README](https://github.com/jamesgober/wal-db/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/wal-db/blob/main/docs/API.md)
- [On-Disk Format](https://github.com/jamesgober/wal-db/blob/main/docs/ON_DISK_FORMAT.md)
- [CHANGELOG](https://github.com/jamesgober/wal-db/blob/main/CHANGELOG.md)
---
**Full diff:** [`v0.3.0...v0.3.1`](https://github.com/jamesgober/wal-db/compare/v0.3.0...v0.3.1).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/wal-db/blob/main/CHANGELOG.md#031---2026-06-05).