Crate trine_kv 

Trine KV is an embedded LSM MVCC key-value database.

Use Trine KV when an application needs a local key/value store with persistent storage, atomic batches, snapshots, range scans, prefix scans, and optimistic transactions. The primary API is async-first; synchronous callers use the explicit *_sync adapters.

Quick start

Db::open and Db::open_sync are path-first. Passing a path opens a persistent database. Use DbOptions::memory() when the database should live only in memory.

use trine_kv::Db;

let db = Db::open_sync("target/doc-example-basic")?;
db.put_sync(b"user:1", b"Ada")?;

let value = db.get_sync(b"user:1")?;
assert_eq!(value, Some(b"Ada".to_vec()));

Core concepts

• Db is the database handle. Direct Db read and write methods operate on the built-in default bucket.
• Bucket is a handle for an optional named bucket with its own options, memtables, tables, filters, and compaction state.
• WriteBatch groups puts, point deletes, and range deletes into one atomic commit.
• ReadVersion is the application-facing cursor for a committed database state. Snapshot pins one so repeated reads see a stable view while newer writes continue.
• Transaction records reads and stages writes, then rejects commit if a later committed write conflicts with the read set.

Durability

Persistent databases default to safety-first durability for confirmed writes. Lower durability modes such as DurabilityMode::Buffered are available through WriteOptions for data that can tolerate losing recent confirmed writes after a crash.

Platform I/O features

The async API works without feature flags. Enable platform-io when native-file storage should complete through Trine’s portable platform I/O boundary, backed by a bounded Trine-owned thread pool. Enable platform-io-native when Trine should prefer audited native async backends and use the same thread-pool backend for unsupported operation rows.

After enabling either feature, select the platform I/O runtime for a database:

use trine_kv::{Db, DbOptions, RuntimeOptions};

let mut options = DbOptions::new("target/doc-example-platform-io");
options.runtime = RuntimeOptions::platform_io();

let db = Db::open(options).await?;
db.put(b"k", b"v").await?;
db.flush().await?;

Use DbStats::storage_platform_io_operations to inspect whether each Trine operation completed as true native async, partial native async, thread-pool managed async, fallback, or unsupported work.

Re-exports

pub use branch::Branch;

pub use branch::BranchInfo;

pub use branch::BranchRange;

pub use bucket::Bucket;

pub use bucket::BucketName;

pub use bucket::BucketReader;

pub use db::Db;

pub use db::IntoOpenOptions;

pub use db::MaintenanceBudget;

pub use db::MaintenanceOutcome;

pub use error::Error;

pub use error::Result;

pub use iterator::Direction;

pub use iterator::Iter;

pub use iterator::LazyIter;

pub use iterator::LazyKeyValue;

pub use iterator::LazyValue;

pub use object_store::ETag;

pub use object_store::InMemoryObjectStore;

pub use object_store::ObjectClient;

pub use object_store::ObjectFuture;

pub use object_store::ObjectMeta;

pub use object_store::Precondition;

pub use object_store::PutIf;

pub use object_store::verify_object_client_contract;

pub use options::BlobGcRatio;

pub use options::BlobLevelMergePolicy;

pub use options::BucketOptions;

pub use options::CompressionProfile;

pub use options::DbOptions;

pub use options::DurabilityMode;

pub use options::FailOnCorruptionPolicy;

pub use options::FilterDepthCurve;

pub use options::FilterPolicy;

pub use options::HostStorageBackend;

pub use options::IndexSearchPolicy;

pub use options::ObjectClientTrustMode;

pub use options::PrefixFilterPolicy;

pub use options::StorageMode;

pub use options::WalShardPolicy;

pub use options::WriteOptions;

pub use prefix::PrefixExtractor;

pub use recovery::RecoveryReport;

pub use runtime::CancellationToken;

pub use runtime::RuntimeCapabilities;

pub use runtime::RuntimeMode;

pub use runtime::RuntimeOptions;

pub use snapshot::Snapshot;

pub use stats::CompactionSkip;

pub use stats::CompactionSkipStats;

pub use stats::CompactionTrigger;

pub use stats::CompactionTriggerStats;

pub use stats::DbStats;

pub use stats::FilterStats;

pub use stats::LevelFilterStats;

pub use stats::LevelStats;

pub use stats::PlatformIoClassCounters;

pub use stats::PlatformIoOperationStats;

pub use transaction::Transaction;

pub use transaction::TransactionOptions;

pub use types::CommitInfo;

pub use types::KeyRange;

pub use types::KeyValue;

pub use types::ReadVersion;

pub use types::Value;

pub use write_batch::WriteBatch;

Modules

branch

Copy-on-write branches and time travel, built over the existing MVCC read API and named buckets so the LSM read/write hot path is untouched — a database that never branches pays nothing (see docs/branching.md).

bucket

Bucket handles and bucket-bound readers.

db

Database open, read, write, scan, and maintenance APIs.

error

Error and result types returned by Trine KV.

iterator

Forward and reverse iterators over committed rows.

object_store

Provider-agnostic object-store client (“bring your own object store”): the ObjectClient trait, its ETag/conditional-write types, and an in-memory fake. Implement it for S3 (or use the s3 feature) and open with Db::open_object_store. Provider-agnostic object-store client and an in-memory fake.

options

Database, bucket, write, storage, runtime, and durability options.

prefix

Prefix extraction policies used by prefix filters.

recovery

Startup recovery helpers and recovery reports.

runtime

Runtime selection, capabilities, and cancellation support.

search

Search policy helpers for table indexes.

snapshot

Snapshot handles for repeatable reads.

stats

Live database statistics exposed to callers.

transaction

Optimistic transaction API.

types

Core key, value, range, read-version, and commit types.

write_batch

Atomic write batch types.

Structs

PointValue

Value returned by BucketReader::get.

Functions

is_wal_object_key

Whether an object-store key names a write-ahead-log object: a trine.wal shard, WAL rewrite temp, confirmed-marker file, or remote object-store WAL segment, as opposed to an SSTable, blob, manifest, or lease object.