Struct RedDB 

pub struct RedDB { /* private fields */ }

RedDB - Unified Database with Best-in-Class DevX

Single entry point for Tables, Graphs, and Vectors with full metadata support and cross-referencing.

Implementations

impl RedDB

pub fn quorum_coordinator(&self) -> Option<&Arc<QuorumCoordinator>>

Access the quorum coordinator (Phase 2.6 PG parity).

None when this instance is not a primary. Write paths call quorum.wait_for_quorum(lsn) after the primary WAL commit to block until the configured replica quorum has acked; Async mode (default) returns instantly so no behavioural change.

pub fn wait_for_replication_quorum( &self, target_lsn: u64, ) -> Result<(), QuorumError>

Wait for the configured replica quorum on a given LSN.

Convenience wrapper that returns Ok(()) when:

• there is no quorum coordinator (non-primary instance), OR
• the coordinator is in Async mode (historical behaviour).

Callers in the write path (INSERT/UPDATE/DELETE dispatch) invoke this after logging the commit record. Returning Err signals that replication did NOT reach quorum — the primary still has the record but the client ack should be deferred or rejected.

impl RedDB

pub fn table_ref(&self, table: impl Into<String>, row_id: u64) -> TableRef

Create a reference to a table row

pub fn node_ref( &self, collection: impl Into<String>, node_id: EntityId, ) -> NodeRef

Create a reference to a graph node

pub fn vector_ref( &self, collection: impl Into<String>, vector_id: EntityId, ) -> VectorRef

Create a reference to a vector

pub fn query(&self) -> QueryBuilder

Start building a query

pub fn similar( &self, collection: &str, vector: &[f32], k: usize, ) -> Vec<SimilarResult>

Quick vector similarity search.

For collections with >= 100 vectors a lazily-built HNSW index is used for fast approximate nearest-neighbor lookup. Smaller collections fall back to an exact brute-force scan so that the overhead of building an index is avoided when it would not pay off.

pub fn get(&self, id: EntityId) -> Option<UnifiedEntity>

Get entity by ID from any collection

pub fn get_with_collection( &self, id: EntityId, ) -> Option<(String, UnifiedEntity)>

Get entity with its collection name

pub fn batch_get(&self, ids: &[EntityId]) -> Vec<Option<UnifiedEntity>>

Batch get multiple entities by ID. More efficient than N individual get() calls.

pub fn batch(&self) -> BatchBuilder

Start a batch operation for bulk inserts

pub fn add_preprocessor(&mut self, preprocessor: Box<dyn Preprocessor>)

Add a preprocessor hook

pub fn linked_from(&self, id: EntityId) -> Vec<LinkedEntity>

Get all entities linked FROM the given entity

pub fn linked_to(&self, id: EntityId) -> Vec<LinkedEntity>

Get all entities linked TO the given entity

pub fn store(&self) -> Arc<UnifiedStore>

Get the underlying store (for advanced operations)

pub fn ml_runtime(&self) -> &MlRuntime

Lazily-initialised ML runtime. First caller wins; subsequent callers observe the same instance. The runtime is created with an in-memory persistence backend by default — production deployments that need durable model state will swap this for a store-backed backend when the persistence integration lands.

pub fn semantic_cache(&self) -> &Arc<SemanticCache>

Shared semantic cache for SEMANTIC_CACHE_* scalars. Uses default config until a SET SEMANTIC_CACHE admin surface lands.

pub fn hypertables(&self) -> &Arc<HypertableRegistry>

Lazily-initialised hypertable registry. Populated by CREATE HYPERTABLE DDL; consumed by chunk routing + retention.

pub fn continuous_aggregates(&self) -> &Arc<ContinuousAggregateEngine>

Lazily-initialised continuous-aggregate engine. Populated by CA_REGISTER and read by CA_REFRESH / CA_STATE scalars.

impl RedDB

pub fn new() -> Self

Construct an ephemeral RedDB instance backed by a unique tempfile.

There is no longer a true in-memory execution mode — this simply opens a persistent database at a temp path so all code paths run through the same storage pipeline.

pub fn open(path: impl AsRef<Path>) -> Result<Self, Box<dyn Error>>

Open or create a RedDB instance with persistence

pub fn open_with_options(options: &RedDBOptions) -> Result<Self, Box<dyn Error>>

Open using the crate-level runtime options.

pub fn flush(&self) -> Result<(), Box<dyn Error>>

Flush changes to disk (if persistence is enabled). Consolidates all pending EC transactions before persisting.

Two-phase: local fsync first, then optional remote upload. The runtime gates the remote phase on serverless writer-lease state (PLAN.md Phase 5 / W6) — losing the lease must not silently blast over a peer’s snapshot. Callers that need lease-fenced behaviour use flush_local_only() + upload_to_remote_backend() separately so the gate fits between the two halves.

pub fn flush_local_only(&self) -> Result<(), Box<dyn Error>>

Local fsync without touching the remote backend. Used by shutdown / checkpoint paths where the runtime decides whether the remote upload is allowed (lease, dry-run, read-only).

pub fn embedded_pending_wal_records(&self) -> Option<u64>

pub fn upload_to_remote_backend(&self) -> Result<(), Box<dyn Error>>

Push the on-disk database file to the configured remote backend. Caller is responsible for any lease / role / read-only check that gates the upload — this is a raw side-effect. No-op when the runtime is in-memory or no remote backend is configured.

pub fn collections(&self) -> Vec<String>

List all collections in the store

pub fn path(&self) -> Option<&Path>

Get path to the current persistent database, if any.

pub fn options(&self) -> &RedDBOptions

Get the options used to construct this database.

pub fn is_paged(&self) -> bool

Whether this database is backed by the page-based storage backend.

pub fn stats(&self) -> StoreStats

Return aggregated store statistics.

pub fn expected_native_header(&self) -> Option<PhysicalFileHeader>

Project the expected native file header from the current persisted physical metadata.

pub fn inspect_native_header(&self) -> Option<NativeHeaderInspection>

Compare the page-0 native header against the persisted physical metadata.

pub fn native_collection_roots(&self) -> Option<BTreeMap<String, u64>>

Read native collection roots persisted in the paged file, when available.

pub fn native_manifest_summary(&self) -> Option<NativeManifestSummary>

Read native manifest summary persisted in the paged file, when available.

pub fn native_registry_summary(&self) -> Option<NativeRegistrySummary>

Read native operational registry summary persisted in the paged file, when available.

pub fn native_recovery_summary(&self) -> Option<NativeRecoverySummary>

Read native snapshot/export summary persisted in the paged file, when available.

pub fn native_catalog_summary(&self) -> Option<NativeCatalogSummary>

Read native catalog summary persisted in the paged file, when available.

pub fn native_metadata_state_summary( &self, ) -> Option<NativeMetadataStateSummary>

Read native metadata status persisted in the paged file, when available.

pub fn native_physical_state(&self) -> Option<NativePhysicalState>

Read the consolidated native physical publication state from the paged file.

pub fn native_vector_artifact_pages( &self, ) -> Option<Vec<NativeVectorArtifactPageSummary>>

Read native vector artifact pages persisted in the paged file, when available.

pub fn inspect_native_vector_artifact( &self, collection: &str, artifact_kind: Option<&str>, ) -> Result<NativeVectorArtifactInspection, String>

pub fn warmup_native_vector_artifact( &self, collection: &str, artifact_kind: Option<&str>, ) -> Result<NativeVectorArtifactInspection, String>

pub fn inspect_native_vector_artifacts( &self, ) -> Result<NativeVectorArtifactBatchInspection, String>

pub fn warmup_native_vector_artifacts( &self, ) -> Result<NativeVectorArtifactBatchInspection, String>

pub fn physical_authority_status(&self) -> PhysicalAuthorityStatus

Inspect which physical source is currently authoritative for operational recovery.

pub fn native_header_repair_policy(&self) -> Option<NativeHeaderRepairPolicy>

Decide how to reconcile page-0 native state against persisted physical metadata.

pub fn repair_native_header_from_metadata( &self, ) -> Result<NativeHeaderRepairPolicy, Box<dyn Error>>

Repair the native header from persisted physical metadata when it is safe to do so.

pub fn repair_native_physical_state_from_metadata( &self, ) -> Result<bool, Box<dyn Error>>

Republish the full native physical publication state from the current physical metadata view.

pub fn catalog_snapshot(&self) -> CatalogSnapshot

Provide a compact catalog snapshot for management/runtime layers.

pub fn catalog_model_snapshot(&self) -> CatalogModelSnapshot

Full logical catalog snapshot including inferred collection models and indices.

pub fn catalog_consistency_report(&self) -> CatalogConsistencyReport

pub fn readiness_for_query(&self) -> bool

pub fn readiness_for_query_serverless(&self) -> bool

pub fn readiness_for_write(&self) -> bool

pub fn readiness_for_write_serverless(&self) -> bool

pub fn readiness_for_repair(&self) -> bool

pub fn readiness_for_repair_serverless(&self) -> bool

impl RedDB

pub fn health(&self) -> HealthReport

impl RedDB

pub fn ec_add( &self, collection: &str, field: &str, target_id: EntityId, value: f64, ) -> Result<EntityId, Box<dyn Error>>

Add a value to a field via eventual consistency. In Sync mode, consolidates immediately. In Async mode, queues for background consolidation.

pub fn ec_sub( &self, collection: &str, field: &str, target_id: EntityId, value: f64, ) -> Result<EntityId, Box<dyn Error>>

Subtract a value from a field via eventual consistency.

pub fn ec_set( &self, collection: &str, field: &str, target_id: EntityId, value: f64, ) -> Result<EntityId, Box<dyn Error>>

Set a field to a specific value via eventual consistency (overrides previous adds/subs).

pub fn ec_consolidate( &self, collection: &str, field: &str, target_id: Option<u64>, ) -> Result<ConsolidationResult, Box<dyn Error>>

Consolidate all pending transactions for a field (or a specific entity).

pub fn ec_consolidate_all(&self) -> Result<u64, Box<dyn Error>>

Consolidate ALL registered EC fields. Useful before flush().

pub fn ec_status( &self, collection: &str, field: &str, target_id: u64, ) -> EcStatus

Get the consolidation status for a specific entity’s field.

pub fn ec_register(&self, config: EcFieldConfig)

Register a field for eventual consistency.

impl RedDB

pub fn is_replica_role(&self) -> bool

pub fn enforce_retention_policy(&self) -> Result<(), Box<dyn Error>>

pub fn replica_allows_entity_at_read( &self, collection: &str, entity: &UnifiedEntity, ) -> bool

pub fn node( &self, collection: impl Into<String>, label: impl Into<String>, ) -> NodeBuilder

Start building a graph node

Example

let host = db.node("hosts", "Host")
    .property("ip", "192.168.1.1")
    .save()?;

pub fn edge( &self, collection: impl Into<String>, label: impl Into<String>, ) -> EdgeBuilder

Start building a graph edge

Example

let edge = db.edge("connections", "CONNECTS_TO")
    .from(host_a)
    .to(host_b)
    .weight(0.95)
    .property("protocol", "TCP")
    .save()?;

pub fn vector(&self, collection: impl Into<String>) -> VectorBuilder

Start building a vector entry

Example

let vec = db.vector("embeddings")
    .dense(embedding)
    .content("Original text content")
    .metadata("source", "document.pdf")
    .save()?;

pub fn row( &self, table: impl Into<String>, columns: Vec<(&str, Value)>, ) -> RowBuilder

Start building a table row

Example

let row = db.row("scans", vec![
    ("timestamp", Value::Timestamp(now)),
    ("target", Value::text("192.168.1.0/24")),
    ("findings", Value::Integer(42)),
]).save()?;

pub fn doc(&self, collection: impl Into<String>) -> DocumentBuilder

Start building a document

Documents are stored as enriched table rows with a full JSON body field and flattened top-level keys for filtering.

Example

let doc = db.doc("articles")
    .field("title", "Hello World")
    .field("views", 42)
    .metadata("source", "web")
    .save()?;

pub fn kv( &self, collection: impl Into<String>, key: impl Into<String>, value: Value, ) -> KvBuilder

Start building a key-value pair

KV pairs are stored as table rows with named fields key and value.

Example

let id = db.kv("config", "theme", Value::text("dark"))
    .metadata("updated_by", "admin")
    .save()?;

pub fn get_kv(&self, collection: &str, key: &str) -> Option<(Value, EntityId)>

Get a key-value pair by key, returning the value and entity id

Clone only the selected value. Legacy positional rows without an indexed key use their collection schema in the borrowed fallback scan.

pub fn delete_kv(&self, collection: &str, key: &str) -> Result<bool, DevXError>

Delete a key-value pair by key, returning whether it was found and removed

pub fn rebuild_physical_metadata_from_native_state( &self, ) -> Result<bool, Box<dyn Error>>

Rebuild the external physical metadata view from the native state published in the paged database file.

impl RedDB

pub fn tree_definitions(&self) -> Vec<PhysicalTreeDefinition>

pub fn tree_definition( &self, collection: &str, name: &str, ) -> Option<PhysicalTreeDefinition>

pub fn save_tree_definition( &self, definition: PhysicalTreeDefinition, ) -> Result<PhysicalTreeDefinition, Box<dyn Error>>

pub fn remove_tree_definition( &self, collection: &str, name: &str, ) -> Result<Option<PhysicalTreeDefinition>, Box<dyn Error>>

pub fn collection_default_ttl_ms(&self, collection: &str) -> Option<u64>

pub fn set_collection_default_ttl_ms( &self, collection: impl Into<String>, ttl_ms: u64, )

pub fn clear_collection_default_ttl_ms(&self, collection: &str)

pub fn collection_contracts(&self) -> Vec<CollectionContract>

pub fn collection_contract( &self, collection: &str, ) -> Option<CollectionContract>

pub fn collection_contract_arc( &self, collection: &str, ) -> Option<Arc<CollectionContract>>

Arc-bumping variant — callers that only need read access skip the per-call full CollectionContract clone. Deep clones cost ~200-400 ns each (vec of declared columns + string allocs); the UPDATE fast path hits this 2-3× per mutation.

pub fn save_collection_contract( &self, contract: CollectionContract, ) -> Result<CollectionContract, Box<dyn Error>>

pub fn remove_collection_contract( &self, collection: &str, ) -> Result<Option<CollectionContract>, Box<dyn Error>>

pub fn run_maintenance(&self) -> Result<(), Box<dyn Error>>

pub fn metadata_path(&self) -> Option<PathBuf>

Path to the physical metadata sidecar, if persistent.

pub fn physical_metadata(&self) -> Option<PhysicalMetadataFile>

Inspect the current physical metadata view without publishing repairs.

pub fn physical_indexes(&self) -> Vec<PhysicalIndexState>

Physical index registry derived for the current database state.

pub fn exports(&self) -> Vec<ExportDescriptor>

List registered named exports from the current physical metadata view.

pub fn snapshots(&self) -> Vec<SnapshotDescriptor>

List recorded snapshots from the current physical metadata view.

pub fn graph_projections(&self) -> Vec<PhysicalGraphProjection>

List persisted named graph projections from the current physical metadata view.

pub fn declared_graph_projections(&self) -> Vec<PhysicalGraphProjection>

List graph projections declared in the catalog view.

pub fn operational_graph_projections(&self) -> Vec<PhysicalGraphProjection>

List graph projections currently observed in the operational view.

pub fn analytics_jobs(&self) -> Vec<PhysicalAnalyticsJob>

List persisted analytics job metadata from the current physical metadata view.

pub fn declared_analytics_jobs(&self) -> Vec<PhysicalAnalyticsJob>

List analytics jobs declared in the catalog view.

pub fn operational_analytics_jobs(&self) -> Vec<PhysicalAnalyticsJob>

List analytics jobs currently observed in the operational view.

pub fn declared_indexes(&self) -> Vec<PhysicalIndexState>

List indexes declared in the catalog view.

pub fn operational_indexes(&self) -> Vec<PhysicalIndexState>

List indexes currently observed in the operational view.

pub fn index_statuses(&self) -> Vec<CatalogIndexStatus>

List reconciled index status entries from the catalog snapshot.

pub fn index_status(&self, name: &str) -> Option<CatalogIndexStatus>

Resolve one index status entry from the catalog snapshot.

pub fn save_graph_projection( &self, name: impl Into<String>, node_labels: Vec<String>, node_types: Vec<String>, edge_labels: Vec<String>, source: impl Into<String>, ) -> Result<PhysicalGraphProjection, Box<dyn Error>>

Upsert a named graph projection in the persisted physical metadata.

pub fn materialize_graph_projection( &self, name: &str, ) -> Result<Option<PhysicalGraphProjection>, Box<dyn Error>>

Mark a declared graph projection as materialized in the current physical metadata.

pub fn mark_graph_projection_materializing( &self, name: &str, ) -> Result<Option<PhysicalGraphProjection>, Box<dyn Error>>

Mark a declared graph projection as materializing.

pub fn fail_graph_projection( &self, name: &str, ) -> Result<Option<PhysicalGraphProjection>, Box<dyn Error>>

Mark a graph projection as failed.

pub fn mark_graph_projection_stale( &self, name: &str, ) -> Result<Option<PhysicalGraphProjection>, Box<dyn Error>>

Mark a graph projection as stale while preserving any last materialized sequence.

pub fn save_analytics_job( &self, kind: impl Into<String>, projection: Option<String>, metadata_entries: BTreeMap<String, String>, ) -> Result<PhysicalAnalyticsJob, Box<dyn Error>>

Declare or update analytics job metadata without marking it as executed.

pub fn record_analytics_job( &self, kind: impl Into<String>, projection: Option<String>, metadata_entries: BTreeMap<String, String>, ) -> Result<PhysicalAnalyticsJob, Box<dyn Error>>

Record or update analytics job metadata in the persisted physical metadata.

pub fn queue_analytics_job( &self, kind: impl Into<String>, projection: Option<String>, metadata_entries: BTreeMap<String, String>, ) -> Result<PhysicalAnalyticsJob, Box<dyn Error>>

Mark a declared analytics job as running.

pub fn start_analytics_job( &self, kind: impl Into<String>, projection: Option<String>, metadata_entries: BTreeMap<String, String>, ) -> Result<PhysicalAnalyticsJob, Box<dyn Error>>

Mark a declared analytics job as running.

pub fn fail_analytics_job( &self, kind: impl Into<String>, projection: Option<String>, metadata_entries: BTreeMap<String, String>, ) -> Result<PhysicalAnalyticsJob, Box<dyn Error>>

Mark a declared analytics job as failed.

pub fn mark_analytics_job_stale( &self, kind: impl Into<String>, projection: Option<String>, metadata_entries: BTreeMap<String, String>, ) -> Result<PhysicalAnalyticsJob, Box<dyn Error>>

Mark a declared analytics job as stale.

pub fn create_named_export( &self, name: impl Into<String>, ) -> Result<ExportDescriptor, Box<dyn Error>>

Create a named export by copying the current database file and metadata sidecar.

pub fn set_index_enabled( &self, name: &str, enabled: bool, ) -> Result<Option<PhysicalIndexState>, Box<dyn Error>>

Enable or disable a physical index entry in the persisted registry.

pub fn mark_index_building( &self, name: &str, ) -> Result<Option<PhysicalIndexState>, Box<dyn Error>>

Mark a declared physical index as building in the persisted registry.

pub fn fail_index( &self, name: &str, ) -> Result<Option<PhysicalIndexState>, Box<dyn Error>>

Mark a declared physical index as failed in the persisted registry.

pub fn mark_index_stale( &self, name: &str, ) -> Result<Option<PhysicalIndexState>, Box<dyn Error>>

Mark a declared physical index as stale in the persisted registry.

pub fn mark_index_ready( &self, name: &str, ) -> Result<Option<PhysicalIndexState>, Box<dyn Error>>

Mark a declared physical index as ready in the persisted registry.

pub fn warmup_index( &self, name: &str, ) -> Result<Option<PhysicalIndexState>, Box<dyn Error>>

Mark a physical index as warmed up/refreshed in the persisted registry.

pub fn rebuild_index_registry( &self, collection: Option<&str>, ) -> Result<Vec<PhysicalIndexState>, Box<dyn Error>>

Rebuild physical index metadata from the current catalog, optionally restricted to one collection.

Trait Implementations

impl Default for RedDB

fn default() -> Self

Returns the “default value” for a type.

impl Drop for RedDB

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.