Skip to main content

Crate khive_db

Crate khive_db 

Source
Expand description

SQLite storage backend for the khive knowledge graph runtime.

Provides entity, note, event, edge, FTS5 text search, and optional sqlite-vec vector storage over a WAL-mode connection pool.

§Terminal write settlement

Pooled, standalone, and lifetime write owners retain their volume lease through rollback or successful owned connection close. If a retired connection remains outside autocommit and close also fails, cleanup reports the path, volume, rollback and close errors, returns a terminal outcome-unknown error, and poisons the pool so it refuses every later write and releases the lease. The process keeps running: the host decides whether to exit.

Re-exports§

pub use backend::StorageBackend;
pub use checkpoint::checkpoint_once;
pub use checkpoint::run_checkpoint_task;
pub use checkpoint::CheckpointConfig;
pub use checkpoint::CheckpointLifecycleOwner;
pub use checkpoint::CheckpointTick;
pub use checkpoint::run_session_sweep_task;
pub use checkpoint::SessionSweepConfig;
pub use checkpoint::SweepBackend;
pub use database_owner_identity::DatabaseOwnerIdentity;
pub use database_owner_identity::DatabaseOwnerIdentityError;
pub use error::SqliteError;
pub use error::SQLITE_WAL_CAPACITY_REFUSED_STAGE;
pub use error::SQLITE_WAL_CAPACITY_UNAVAILABLE_STAGE;
pub use migrations::inspect_integrity;
pub use migrations::inspect_page_accounting;
pub use migrations::inspect_schema_is_current;
pub use migrations::inspect_schema_version;
pub use migrations::query_embedding_models;
pub use migrations::read_schema_version;
pub use migrations::run_migrations;
pub use migrations::run_migrations_with_policy;
pub use migrations::EmbeddingModelRegistryRecord;
pub use migrations::Migration;
pub use migrations::MigrationWritePolicy;
pub use migrations::PageAccounting;
pub use migrations::ServiceSchemaPlan;
pub use migrations::VersionedMigration;
pub use migrations::MIGRATIONS;
pub use pool::CheckpointGuard;
pub use pool::CheckpointResult;
pub use pool::ConnectionPool;
pub use pool::PoolConfig;
pub use pool::ReaderGuard;
pub use pool::ReaderRow;
pub use pool::StandaloneCheckpoint;
pub use pool::WalCeilingPolicy;
pub use pool::WalCeilingSource;
pub use pool::WriterGuard;
pub use sql_bridge::SqlBridge;
pub use writer_task::WriterTaskHandle;

Modules§

authority
Transaction-scoped persistence for shared authority records. Transaction-scoped persistence for shared authority records.
backend
Concrete storage backend providing capability-trait factories. Concrete storage backend providing capability traits.
checkpoint
Periodic WAL checkpoint task. Periodic WAL checkpoint task for the connection pool (ADR-091; dedicated checkpoint connection amendment, see below).
database_owner_identity
Durable database owner identity paired with the opened physical file. Durable ownership evidence captured from the database SQLite opened.
diagnostics
Read-only-by-intent database-integrity and WAL/checkpoint diagnostics. Non-mutating-by-intent database, WAL, and checkpoint diagnostics (read-only operator surface).
env
Environment readers with explicit parse/default and boolean policies. Environment readers shared with lower-level khive-types consumers.
error
Error types for the SQLite layer. Error types for the SQLite storage layer.
events_prune
Bounded prune of expendable polling-dispatch audit rows (ADR-212 §4, operator maintenance). Bounded prune of expendable polling-dispatch audit rows from an events store.
extension
SQLite extension registration (sqlite-vec auto-extension). SQLite extension registration for sqlite-vec.
file_identity
Physical file identity shared by pool admission and backend alias routing. Physical identity of a database file, including SQLite’s opened Windows handle.
graph_lint
Read predicates and transaction assertions for the graph-lint caller. Pure, caller-executed graph-lint reads and exact transaction predicates.
maintenance
Canonical physical store sets for cooperative maintenance metadata. Store-set metadata and declaration publication for cooperative maintenance (ADR-049 Amendment 16).
migrations
Schema migration system (versioned migrations). Schema migration system for the SQLite storage layer.
namespace_census
What a live store’s schema says about namespace (ADR-189). What a live store’s schema says about namespace (ADR-189).
namespace_move
Moving records between namespaces (ADR-189). Moving records between namespaces (ADR-189).
pending_index
Durable deferred entity-index obligations (ADR-014 Amendment 7). Durable obligations for deferred entity indexing (ADR-014 Amendment 7).
pool
WAL-mode connection pool: one writer, N concurrent readers. Connection pool for SQLite: one exclusive writer, N concurrent readers.
sql_bridge
SqlAccess trait bridge to ConnectionPool. SqlAccess bridge: connects ConnectionPool to khive_storage::SqlAccess.
statement_lists
Pure statement-list builders for caller-owned SQL execution. Pure statement builders for caller-owned SQL execution.
stores
Per-substrate store implementations (entity, note, graph, event, text, vectors, sparse). Per-substrate SQLite store implementations.
walpin
Cross-process WAL-pin attribution sidecar (ADR-091 Amendment 2 Plank B). The sidecar write path (heartbeat/beacon) and identity primitives are portable; directory collection (enumerate_live/housekeep_live) is Unix-only — its only caller is the daemon’s checkpoint task, and daemon mode itself requires Unix (see khive-mcp/src/serve.rs). ADR-091 Amendment 2 Plank B: cross-process WAL-pin attribution sidecar.
writer_task
Single-writer task and bounded write queue (ADR-067 Component A).

Structs§

DiskGuardEnvironment
One construction-time snapshot shared by backend opening and config identity. Raw values remain intact so invalid Unicode and overflow fail at validation.
EffectiveDiskGuardConfig
FtsIndexStructure
FtsLevelStructure
FtsMaintenanceCounters
FtsSegmentDiagnostics
ProgressConn
A connection carrying the read-cancellation progress handler and a process-unique identity.
RequestReadDeadline
One absolute request deadline represented on async and blocking clocks.

Enums§

DiskGuardConfigSource
Provenance is diagnostic; daemon compatibility uses only effective numbers.

Constants§

DEFAULT_REQUEST_READ_TIMEOUT_SECS
Default nonzero ceiling for request-owned read work, including compose.
DEFAULT_SQLITE_INTERRUPT_GRACE_MS
Post-deadline window for interrupted read tasks to finalize SQLite and return their connection before a coordinator escalates async cancellation.

Functions§

await_request_read_phase
Await one request-owned read phase under the current absolute deadline.
default_volume_lock_dir
The directory that holds the volume advisory lock files shared by every khive process of one user.
effective_request_read_deadline
Constrain candidate by the current request’s deadline without installing a new scope.
ensure_request_read_active
Refuse to begin another request-owned read phase after cancellation.
fts_maintenance_counters
harness_scoped_process_leases
Whether in-process volume leases are scoped by lock directory, which only the workspace test marker turns on. Read once per process.
inherit_request_read_cancellation
Intention-revealing alias for cancellation-only child tasks.
inherit_request_read_context
Capture the current request read context for a spawned child future.
request_read_is_cancelled
Return whether the current request has stopped its read-only work.
request_read_timeout_from_env
Resolve the operator-visible request-read ceiling from KHIVE_REQUEST_READ_TIMEOUT_SECS.
require_volume_lock_dir
A caller’s optional lock directory, or the configuration error that default_volume_lock_dir reports when no directory can be resolved.
resolve_disk_guard_config
scope_request_read_cancellation
Scope future to an explicit read-cancellation signal.
scope_request_read_deadline
Scope future to one relative read deadline, preserving an earlier outer deadline instead of renewing it.
scope_request_read_deadline_at
Scope future to an already-created absolute read deadline.
sqlite_interrupt_grace_from_env
Resolve the validated SQLite interrupt-settlement grace.
wait_for_request_read_cancellation
Wait until the current request’s read-only work is cancelled or timed out.