Crate storage_kit 

Portable database and transactional state-store abstractions.

Built-in databases are opened with Database::connect, while built-in state stores are opened with StateStore::connect. Caller-defined roots implement DatabaseBackend or StateStoreBackend directly. Associated state transactions remain owned by their parent backend.

Supporting request, response, and configuration types live in the functional database and state modules.

Database owns application data and retrieval. StateStore owns revisioned control-plane records, with a unique transaction for atomic writes. A StateStore transaction cannot include Database effects. Bring the relevant backend traits into scope to invoke behavior on the supplied handles.

Choose a workflow

• Application builders: collection writes, filtered/vector retrieval and index cleanup, then transactions and durable reopen.
• Custom implementers: concrete Database composition and associated StateStore/Transaction composition. These examples delegate real storage semantics without an erased ingress.

Transactional state

This example runs against process-local Lance and requires no service:

use storage_kit::{StateStore, StateStoreBackend, StateTransactionBackend};
use storage_kit::state::{
    config::{LanceStateStoreConfig, StateStoreConfig},
    record::{StateKey, StateRecord},
};
let store = StateStore::connect(StateStoreConfig::lance(LanceStateStoreConfig::memory())).await?;
let key = StateKey::new("workflow", "run/1")?;
let mut transaction = store.begin_transaction().await?;
transaction.put(StateRecord::new(key.clone(), serde_json::json!({"status": "ready"}))).await?;
transaction.commit().await?;
let observed = store.load(key).await?.expect("committed record");
assert_eq!(observed.revision.get(), 1);

Conditional writes must read their precondition through the same transaction that commits them. Separate reads or listing pages do not establish a fence or historical snapshot. After an uncertain commit result, reconcile durable application state before retrying; losing a reply does not establish rollback.

Application data

This example opens an in-memory LanceDB instance and performs a catalog read:

use storage_kit::{Database, DatabaseBackend};
use storage_kit::database::{
    config::{DatabaseConfig, LanceConfig},
    catalog::{CatalogRequest, CatalogResponse, ListCollectionsRequest},
};
let database = Database::connect(DatabaseConfig::lance(LanceConfig::embedded_path("memory://"))).await?;
let response = database.catalog(CatalogRequest::ListCollections(ListCollectionsRequest {
    namespace: Vec::new(), limit: Some(10), start_after: None,
})).await?;
assert!(matches!(response, CatalogResponse::Collections(_)));

Use database::catalog for collections and schemas, database::data for records and writes, database::query for retrieval, and database::index for index lifecycle. Optional capabilities describe supported families; operation results remain authoritative for each request.

Features

LanceDB Database and the embedded Lance StateStore are always compiled as distinct products. Cargo defaults are empty (default = []). Alternative backends require explicit redb, postgres, sqlite, or surrealdb features. Default and no-default builds both provide Lance alone.

Static composition

Advanced DTOs are intentionally absent from the crate root:

use storage_kit::DataRecord;

Each StateStoreBackend returns its own associated transaction type. The built-in StateTransaction remains a unique owner:

let _ = storage_kit::StateTransaction::from_backend;

fn require_clone<T: Clone>() {}
require_clone::<storage_kit::StateTransaction>();

RPITIT backend traits are implemented directly rather than exposed as public trait objects:

fn accept_erased(_: &dyn storage_kit::DatabaseBackend) {}

Modules

database

Collection storage, retrieval, and index request/response types.

state

Revisioned control-plane state and owned transactions.

Structs

Database

Cloneable opaque database handle.

StateStore

Cloneable opaque state-store handle.

StateTransaction

Unique, lifetime-free opaque state transaction.

Enums

StateStoreError

Portable state-store error.

StorageError

Portable error type returned by the storage Kit.

Traits

DatabaseBackend

Portable data, catalog, query, and index behavior.

StateStoreBackend

Transactional control-plane storage with caller-owned associated transactions.

StateTransactionBackend

A unique, lifetime-free transaction; commit and rollback consume the owner.