trine_kv/
lib.rs

1//! Trine KV is an embedded LSM MVCC key-value database.
2//!
3//! Use Trine KV when an application needs a local key/value store with
4//! persistent storage, atomic batches, snapshots, range scans, prefix scans,
5//! and optimistic transactions. The primary API is async-first; synchronous
6//! callers use the explicit `*_sync` adapters.
7//!
8//! # Quick start
9//!
10//! `Db::open` and `Db::open_sync` are path-first. Passing a path opens a
11//! persistent database. Use `DbOptions::memory()` when the database should live
12//! only in memory.
13//!
14//! ```rust
15//! use trine_kv::Db;
16//!
17//! # fn main() -> trine_kv::Result<()> {
18//! let db = Db::open_sync("target/doc-example-basic")?;
19//! db.put_sync(b"user:1", b"Ada")?;
20//!
21//! let value = db.get_sync(b"user:1")?;
22//! assert_eq!(value, Some(b"Ada".to_vec()));
23//! # Ok(())
24//! # }
25//! ```
26//!
27//! # Core concepts
28//!
29//! - [`Db`] is the database handle. Direct `Db` read and write methods operate
30//!   on the built-in default bucket.
31//! - [`Bucket`] is a handle for an optional named bucket with its own options,
32//!   memtables, tables, filters, and compaction state.
33//! - [`WriteBatch`] groups puts, point deletes, and range deletes into one
34//!   atomic commit.
35//! - [`Snapshot`] pins a committed sequence so repeated reads see a stable view
36//!   while newer writes continue.
37//! - [`Transaction`] records reads and stages writes, then rejects commit if a
38//!   later committed write conflicts with the read set.
39//!
40//! # Durability
41//!
42//! Persistent databases default to safety-first durability for confirmed
43//! writes. Lower durability modes such as [`DurabilityMode::Buffered`] are
44//! available through [`WriteOptions`] for data that can tolerate losing recent
45//! confirmed writes after a crash.
46
47#![warn(missing_docs)]
48#![allow(clippy::missing_errors_doc, clippy::module_name_repetitions)]
49
50mod blob;
51mod block;
52/// Bucket handles and bucket-bound readers.
53pub mod bucket;
54#[allow(dead_code)]
55mod cache;
56mod checksum;
57mod codec;
58mod compaction;
59/// Database open, read, write, scan, and maintenance APIs.
60pub mod db;
61mod durability;
62/// Error and result types returned by Trine KV.
63pub mod error;
64#[allow(dead_code)]
65mod filter;
66mod internal_key;
67mod io;
68/// Forward and reverse iterators over committed rows.
69pub mod iterator;
70mod lsm;
71mod manifest;
72#[allow(dead_code)]
73mod memtable;
74#[allow(dead_code)]
75mod mvcc;
76/// Database, bucket, write, storage, runtime, and durability options.
77pub mod options;
78mod point_value;
79/// Prefix extraction policies used by prefix filters.
80pub mod prefix;
81mod range_tombstone;
82/// Startup recovery helpers and recovery reports.
83pub mod recovery;
84/// Runtime selection, capabilities, and cancellation support.
85pub mod runtime;
86/// Search policy helpers for table indexes.
87pub mod search;
88/// Snapshot handles for repeatable reads.
89pub mod snapshot;
90/// Live database statistics exposed to callers.
91pub mod stats;
92mod storage;
93mod table;
94/// Optimistic transaction API.
95pub mod transaction;
96/// Core key, value, range, sequence, and commit types.
97pub mod types;
98mod version;
99mod wal;
100/// Atomic write batch types.
101pub mod write_batch;
102
103pub use bucket::{Bucket, BucketName, BucketReader};
104pub use db::{Db, IntoOpenOptions, MaintenanceBudget, MaintenanceOutcome};
105pub use error::{Error, Result};
106pub use iterator::{Direction, Iter, LazyIter, LazyKeyValue, LazyValue};
107pub use mvcc::SnapshotSequence;
108pub use options::{
109    BlobGcRatio, BlobLevelMergePolicy, BucketOptions, CompressionProfile, DbOptions,
110    DurabilityMode, FailOnCorruptionPolicy, FilterPolicy, HostStorageBackend, IndexSearchPolicy,
111    PrefixFilterPolicy, StorageMode, WriteOptions,
112};
113pub use point_value::PointValue;
114pub use prefix::PrefixExtractor;
115pub use recovery::RecoveryReport;
116pub use runtime::{CancellationToken, RuntimeCapabilities, RuntimeMode, RuntimeOptions};
117pub use snapshot::Snapshot;
118pub use stats::DbStats;
119pub use transaction::{Transaction, TransactionOptions};
120pub use types::{CommitInfo, KeyRange, KeyValue, Sequence, Value};
121pub use write_batch::WriteBatch;
122
123#[cfg(test)]
124mod persistent_wal_tests {
125    use crate as trine_kv;
126
127    include!("../tests/internal/persistent_wal.rs");
128}
trine_kv/lib.rs

trine_kv/
lib.rs
