# lock-db v1.0.0 — Stable
**1.0, and the API is frozen until 2.0.** lock-db reaches its first stable
release. There are no code changes from v0.5.0 — the feature set was complete at
v0.4.0, frozen and stress-hardened at v0.5.0, and is now promoted to 1.0 with
final benchmarks captured and every quality gate green on Linux, macOS, and
Windows. From here, the public API will not change before a 2.0 major release.
## What is lock-db?
The lock manager for a transactional database: the component that lets many
transactions touch shared data at once without corrupting it, and that notices
when they have deadlocked and breaks the tie. It is the in-memory concurrency-
control layer a transaction or storage engine drives — it assigns no identities,
persists nothing, and runs no transaction lifecycle of its own.
In one paragraph: transactions take locks on resources in one of five
multi-granularity modes (IS, IX, S, SIX, X); a single `const` compatibility
matrix decides every grant; intention locks make a database → table → page → row
hierarchy correct and cheap; key-range locks stop phantoms; and a wait-for graph
detects deadlock cycles and names a victim to abort. The table is sharded so
unrelated resources never contend on the same mutex.
## The stable surface
Frozen until 2.0:
- **Core** (`no_std`): `LockMode`, `KeyRange`, `TxnId`, `ResourceId`,
`LockError`.
- **`std`**: `LockManager`, `Acquisition`, `WaitForGraph`, `VictimPolicy`,
`Deadlock`, and the `prelude`.
`LockManager` is the entry point: `try_acquire` (sharded, non-blocking),
`release` / `release_all`, `try_acquire_range` / `release_range`, the deadlock-
aware `request`, `cancel_wait` / `find_deadlock`, and the `holder_count` /
`mode_held` / `range_count` / `waiting_count` / `shards` accessors.
## How it got here
| v0.1.0 | Scaffold: manifest, CI, lint gates, dual license. |
| v0.2.0 | Lock-table core: S/X modes, compatibility matrix, sharded table, acquire/release/upgrade. |
| v0.3.0 | Multi-granularity (the five MGL modes, lattice upgrades) and key-range locks. |
| v0.4.0 | Wait-for deadlock detection (`request`, `WaitForGraph`); feature freeze. |
| v0.5.0 | Adversarial contention and deadlock-storm stress tests; API freeze. |
| **v1.0.0** | **Final benchmarks, stable.** |
## Quality
- **Correctness** is property-tested against independent reference models: the
point-lock manager and the range-lock facility each agree with a hand-written
model over arbitrary operation sequences, and `WaitForGraph::detect_cycle` is
checked against Kahn's topological sort.
- **Concurrency** is `loom`-verified: mutual exclusion, shared/exclusive
conflict, overlapping-range exclusion, and the classic two-transaction
deadlock are all model-checked across every interleaving — which also proves
the manager's own `waits`/shard lock ordering is deadlock-free.
- **Adversarial load**: a contention stress test verifies mutual exclusion under
eight threads hammering a shared pool, and a deadlock-storm test confirms
detect-and-abort keeps every transaction making progress.
- **No `unsafe`**: the crate is `#![forbid(unsafe_code)]`.
Counts at this tag: 90 unit + 38 doctests + 4 property + 2 stress tests; 26 unit
in the `no_std` core; 4 `loom` model checks. `cargo audit` and `cargo deny check`
are clean.
## Benchmarks
Criterion, development workstation (Windows x86_64). Indicative, not guarantees:
| `try_acquire` + `release`, shared | ~104 ns |
| `try_acquire` + `release`, exclusive | ~106 ns |
| shared → exclusive upgrade | ~121 ns |
| `request` (deadlock-aware) granted | ~117 ns, flat as the wait set grows |
| range acquire + release (lightly populated space) | ~100 ns |
| `release_all`, amortized per lock (4096 locks) | ~147 ns |
`release_all` is proportional to the locks a transaction holds. On disjoint
resources the sharded table scales with threads: eight threads sustain markedly
higher aggregate acquire/release throughput than one, rather than serializing on
a single lock. The range conflict scan is linear in the live ranges per space —
~100 ns at low occupancy, rising to ~550 ns against a thousand live ranges — the
one place where an interval tree would help if a workload ever needs it.
## A note on the 1.0 cut
lock-db is promoted straight to 1.0 rather than through a long alpha/beta soak.
The API was frozen at v0.5.0, the property / `loom` / adversarial suites all
pass, and the first-party consumers that would exercise it in anger (`txn-db`,
`index-db`) are not built yet — so there is no external integration to soak
against. The 1.0 guarantee is the frozen API plus the test and benchmark
evidence above; future integration work will land as patch releases if it
surfaces anything.
## Breaking changes
**None.** Identical code to v0.5.0.
## 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 -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo clippy --no-default-features --all-targets -- -D warnings
cargo test
cargo test --all-features
cargo build --examples
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.85 clippy --all-targets --all-features -- -D warnings
cargo audit
cargo deny check
cargo bench --bench lock_bench
# concurrency model checks (slow; not part of the default run)
RUSTFLAGS="--cfg loom" cargo test --test loom --release
```
All green on both platforms.
## Installation
```toml
[dependencies]
lock-db = "1"
# with serde derives on the public types
lock-db = { version = "1", features = ["serde"] }
```
MSRV: Rust 1.85 (2024 edition).
## Documentation
- [README](https://github.com/jamesgober/lock-db/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/lock-db/blob/main/docs/API.md)
- [CHANGELOG](https://github.com/jamesgober/lock-db/blob/main/CHANGELOG.md)
---
**Full diff:** [`v0.5.0...v1.0.0`](https://github.com/jamesgober/lock-db/compare/v0.5.0...v1.0.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/lock-db/blob/main/CHANGELOG.md#100---2026-06-06).