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 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 enforce_retention_policy(&self) -> Result<(), Box<dyn Error>>

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

Scans the collection for an entity whose named field key matches.

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>

Load the current physical metadata view, bootstrapping from native state when needed.

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.