What it is
store-io replaces fsys as the only code in a database stack that touches files and devices. It is built for:
- Write-ahead logs and commit layers — small, sector-aligned, positioned writes at low queue depth, durable on completion on power-safe devices and with the minimum barrier cost on volatile-cache devices; exact receipts with out-of-order completion; raw, uninterpreted recovery reads.
- Columnar and page stores — large vectored writes, dependent writes across files and devices with at most one flush per device, release on compaction, clone for backup.
- Buffer pools — batched direct reads into caller-owned aligned frames, explicit cancellable prefetch, per-range errors.
- Backup and replication shipping — streaming direct-read copies with bounded memory.
- Embedded deployments — one portable container file, unprivileged, with zero idle wakeups.
What it is not
- Not a general-purpose file manager. It does not replace
std::fsfor ordinary files. - Not a log or a database. It has no frames, sequence numbers, payload checksums, commit windows or recovery policy: those belong to the caller.
- Not an async runtime. The core has none; async adapters live in separate crates.
Design rules
- Durability classes from evidence. Power-safe, flush-required, unverified or unsafe, decided per path and per device. Operating-system cache toggles and vendor tables never promote a device.
- Unforgeable receipts. Positions, write tickets and receipts are distinct opaque types. A sequence number never type-checks as a byte position, and a barrier is never a silent no-op.
- Fail-stop. A failed write or flush poisons the device's barrier domain. A flush is never retried, and success is never reported after a failed one.
- Opens modify nothing. No open, scan or lock acquisition ever changes caller bytes, sizes, timestamps or directory entries.
- No hidden latency. No timers, no polling threads, no group-commit windows, no idle wakeups.
- Measured, not claimed. Every performance number names the device, durability class, filesystem, OS and kernel, and fsync status, and is gated against fio on the same box.
Quick start
use ;
// First run: create (the device is probed; unsafe devices are refused).
let store = create?;
let wal = store.provision_append_region?;
// Durable when this returns: one write, one flush.
let = wal.append_durable?;
println!;
// Many records: packed into the device's own buffers, one write, one flush.
let mut batch = wal.batch;
batch.append?;
batch.append?;
let = batch.commit?;
Documentation
| Document | What it covers |
|---|---|
docs/GUIDE.md |
A walk through store-io: receipts, regions, batches, many writers, small objects, recovery, the device report, errors, space, recycling, tuning. |
docs/API.md |
Every public item, grouped by purpose. |
docs/DURABILITY.md |
The durability model: classes, evidence, trust, receipts, flush sharing, fail-stop. |
docs/PLATFORMS.md |
What store-io does on Windows and Linux, and the known limits of each. |
docs/FORMAT.md |
The on-disk format of a store. |
CHANGELOG.md |
Every change. |
Installation
[]
= "0.4"
The store-io command-line tool (store-io probe <dir>, store-io info <store>) is behind the cli feature.
Contributing
See dev/DIRECTIVES.md for engineering standards and the definition of done, and REPS.md for the Rust Efficiency & Performance Standards. Before a PR: cargo fmt --all, cargo clippy --workspace --all-targets --all-features -- -D warnings, and cargo test --workspace --all-features must be clean.