iqdb 1.0.0

Embedded vector database for Rust. Exact and approximate (HNSW/IVF) similarity search with durable storage, over the iqdb crate family.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# iqdb v0.7.0 — Durability Tuning (alpha)

**Choose your durability / throughput trade-off.** v0.7.0 opens the alpha line by exposing the two durable-storage knobs that `iqdb-persist` already supports — the write-ahead-log fsync cadence and snapshot compression — through `IqdbConfig`. Additive: the default behaviour (fsync every acknowledged write, no compression) is unchanged, and the in-memory backend ignores both.

## What is iqdb?

An embedded vector database for Rust: exact and approximate similarity search, declarative filters, durable storage, an optional result cache, and an opt-in async surface — the integration layer over the iqdb crate family, all behind one small handle.

## What's new in 0.7.0

### `IqdbConfig::fsync` — pick the WAL sync cadence

The file-backed path logs every write to a write-ahead log. By default it `fsync`s on every acknowledged write (`FsyncPolicy::Always`), so a power cut loses nothing. For write-heavy workloads that can tolerate a bounded loss window, `Periodic` `fsync`s at most once per interval; `Never` is for tests and tmpfs-backed paths.

```rust,ignore
use iqdb::{DistanceMetric, FsyncPolicy, Iqdb, IqdbConfig};
use std::time::Duration;

let cfg = IqdbConfig::new(128, DistanceMetric::Cosine)
    .fsync(FsyncPolicy::Periodic(Duration::from_millis(50)));
let db = Iqdb::open_with("./data/vectors.iqdb", cfg)?;
# let _ = db; Ok::<(), iqdb::Error>(())
```

### `IqdbConfig::compression` — shrink the snapshot

Snapshots can be compressed with Zstandard or LZ4. The codecs are gated behind the `zstd` / `lz4` cargo features; selecting one whose feature is not compiled in fails cleanly at open with `Error::Persist`, never a panic or a silent fallback.

```rust,ignore
use iqdb::{Compression, DistanceMetric, Iqdb, IqdbConfig};

let cfg = IqdbConfig::new(128, DistanceMetric::Cosine)
    .compression(Compression::Zstd { level: 3 }); // requires the `zstd` feature
let db = Iqdb::open_with("./data/vectors.iqdb", cfg)?;
# let _ = db; Ok::<(), iqdb::Error>(())
```

`FsyncPolicy` and `Compression` are re-exported from `iqdb-persist`.

### Fixed: the compression features are now reachable

v0.5.0 declared the `zstd` and `lz4` cargo features (forwarding to `iqdb-persist`), but the durable open path always used `Compression::None`, so enabling them had no runtime effect. `IqdbConfig::compression` closes that gap — the features now do what they advertise.

## Breaking changes

**None.** Durability and compression default to the prior behaviour (`FsyncPolicy::Always`, `Compression::None`), so existing callers are unaffected. The new knobs are additive `IqdbConfig` methods.

## Verification

Run on Windows x86_64 and on WSL2 Ubuntu (Rust stable); the same commands run in the configured CI matrix on Linux, macOS, and Windows:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --all-features
cargo test --features zstd --test persistence
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.87 build
```

All green. Test counts with `--all-features`: 38 unit + 3 async + 12 persistence + 2 property + 3 recall + 21 doctests. The default build is unchanged, and the relaxed-fsync, compressed round-trip, and feature-rejection paths are covered by integration tests.

## What's next

- **v0.8.x (beta) → v0.9.x (RC).** Broader testing against real consumers, final benchmarks, doc polish.
- **v1.0.0 — stable.** API and on-disk format frozen, migration guide from 0.x.

## Installation

```toml
[dependencies]
iqdb = "0.7"

# Snapshot compression and the async surface are opt-in
iqdb = { version = "0.7", features = ["zstd", "async"] }
```

MSRV: Rust 1.87.

## Documentation

- [README](https://github.com/jamesgober/iqdb/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/iqdb/blob/main/docs/API.md)
- [Standards (REPS)](https://github.com/jamesgober/iqdb/blob/main/REPS.md)
- [CHANGELOG](https://github.com/jamesgober/iqdb/blob/main/CHANGELOG.md)
- [docs.rs/iqdb](https://docs.rs/iqdb)

---

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