Struct RedbStorage 

pub struct RedbStorage { /* private fields */ }

redb storage engine wrapper.

This struct holds the redb database handle and cached metadata. It implements StorageEngine for use with PulseDB.

Thread Safety

RedbStorage is Send + Sync. redb handles internal synchronization using MVCC for readers and exclusive locking for writers.

Implementations

impl RedbStorage

pub fn open(path: impl AsRef<Path>, config: &Config) -> Result<Self>

Opens or creates a database at the given path.

If the database doesn’t exist, it will be created and initialized with the configuration settings. If it exists, the configuration will be validated against the stored metadata.

Arguments

• path - Path to the database file
• config - Database configuration

Errors

Returns an error if:

• The database file is corrupted
• The database is locked by another process
• Schema version doesn’t match
• Embedding dimension doesn’t match (for existing databases)

Example

use pulsedb::{Config, storage::RedbStorage};

let storage = RedbStorage::open(dir.path().join("test.db"), &Config::default())?;

pub fn embedding_dimension(&self) -> EmbeddingDimension

Returns the embedding dimension configured for this database.

Trait Implementations

impl Debug for RedbStorage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl StorageEngine for RedbStorage

fn metadata(&self) -> &DatabaseMetadata

Returns the database metadata.

fn close(self: Box<Self>) -> Result<()>

Closes the storage engine, flushing any pending writes.

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

Returns the path to the database file, if applicable.

fn save_collective(&self, collective: &Collective) -> Result<()>

Saves a collective to storage.

fn get_collective(&self, id: CollectiveId) -> Result<Option<Collective>>

Retrieves a collective by ID.

fn list_collectives(&self) -> Result<Vec<Collective>>

Lists all collectives in the database.

fn delete_collective(&self, id: CollectiveId) -> Result<bool>

Deletes a collective by ID.

fn count_experiences_in_collective(&self, id: CollectiveId) -> Result<u64>

Counts experiences belonging to a collective.

fn delete_experiences_by_collective(&self, id: CollectiveId) -> Result<u64>

Deletes all experiences and related index entries for a collective.

fn list_experience_ids_in_collective( &self, id: CollectiveId, ) -> Result<Vec<ExperienceId>>

Lists all experience IDs belonging to a collective.

fn get_recent_experience_ids( &self, collective_id: CollectiveId, limit: usize, ) -> Result<Vec<(ExperienceId, Timestamp)>>

Retrieves the most recent experience IDs in a collective.

fn save_experience(&self, experience: &Experience) -> Result<()>

Saves an experience and its embedding to storage.

fn get_experience(&self, id: ExperienceId) -> Result<Option<Experience>>

Retrieves an experience by ID, including its embedding.

fn update_experience( &self, id: ExperienceId, update: &ExperienceUpdate, ) -> Result<bool>

Updates mutable fields of an experience.

fn delete_experience(&self, id: ExperienceId) -> Result<bool>

Permanently deletes an experience and its embedding.

fn reinforce_experience(&self, id: ExperienceId) -> Result<Option<u32>>

Atomically increments the applications counter for an experience.

fn save_embedding(&self, id: ExperienceId, embedding: &[f32]) -> Result<()>

Saves an embedding vector to storage.

fn get_embedding(&self, id: ExperienceId) -> Result<Option<Vec<f32>>>

Retrieves an embedding vector by experience ID.

fn save_relation(&self, relation: &ExperienceRelation) -> Result<()>

Saves a relation and its index entries atomically.

fn get_relation(&self, id: RelationId) -> Result<Option<ExperienceRelation>>

Retrieves a relation by ID.

fn delete_relation(&self, id: RelationId) -> Result<bool>

Deletes a relation and its index entries atomically.

fn get_relation_ids_by_source( &self, experience_id: ExperienceId, ) -> Result<Vec<RelationId>>

Finds all relation IDs where the given experience is the source.

fn get_relation_ids_by_target( &self, experience_id: ExperienceId, ) -> Result<Vec<RelationId>>

Finds all relation IDs where the given experience is the target.

fn delete_relations_for_experience( &self, experience_id: ExperienceId, ) -> Result<u64>

Deletes all relations where the given experience is source or target.

fn relation_exists( &self, source_id: ExperienceId, target_id: ExperienceId, relation_type: RelationType, ) -> Result<bool>

Checks if a relation with the same (source, target, type) already exists.

fn save_insight(&self, insight: &DerivedInsight) -> Result<()>

Saves a derived insight and its index entries atomically.

fn get_insight(&self, id: InsightId) -> Result<Option<DerivedInsight>>

Retrieves a derived insight by ID.

fn delete_insight(&self, id: InsightId) -> Result<bool>

Deletes a derived insight and its index entries atomically.

fn list_insight_ids_in_collective( &self, id: CollectiveId, ) -> Result<Vec<InsightId>>

Lists all insight IDs belonging to a collective.

fn delete_insights_by_collective(&self, id: CollectiveId) -> Result<u64>

Deletes all insights belonging to a collective.

fn save_activity(&self, activity: &Activity) -> Result<()>

Saves an agent activity to storage (upsert).

fn get_activity( &self, agent_id: &str, collective_id: CollectiveId, ) -> Result<Option<Activity>>

Retrieves an agent activity by agent ID and collective.

fn delete_activity( &self, agent_id: &str, collective_id: CollectiveId, ) -> Result<bool>

Deletes an agent activity.

fn list_activities_in_collective( &self, collective_id: CollectiveId, ) -> Result<Vec<Activity>>

Lists all activities in a collective.

fn delete_activities_by_collective( &self, collective_id: CollectiveId, ) -> Result<u64>

Deletes all activities belonging to a collective.

fn list_experience_ids_paginated( &self, collective_id: CollectiveId, limit: usize, offset: usize, ) -> Result<Vec<ExperienceId>>

Lists experience IDs in a collective with pagination.

fn list_relations_in_collective( &self, collective_id: CollectiveId, limit: usize, offset: usize, ) -> Result<Vec<ExperienceRelation>>

Lists all relations in a collective with pagination.

fn list_insight_ids_paginated( &self, collective_id: CollectiveId, limit: usize, offset: usize, ) -> Result<Vec<InsightId>>

Lists insight IDs in a collective with pagination.

fn get_wal_sequence(&self) -> Result<u64>

Returns the current WAL sequence number.

fn poll_watch_events( &self, since_seq: u64, limit: usize, ) -> Result<(Vec<WatchEventRecord>, u64)>

Retrieves watch events with sequence numbers greater than since_seq.

fn poll_sync_events( &self, since_seq: u64, limit: usize, ) -> Result<Vec<(u64, WatchEventRecord)>>

Available on crate feature sync only.

Retrieves ALL watch events (all entity types) with their sequence numbers.

fn instance_id(&self) -> InstanceId

Available on crate feature sync only.

Returns the persistent instance ID for this database.

fn save_sync_cursor(&self, cursor: &SyncCursor) -> Result<()>

Available on crate feature sync only.

Saves a sync cursor for a peer instance.

fn load_sync_cursor( &self, instance_id: &InstanceId, ) -> Result<Option<SyncCursor>>

Available on crate feature sync only.

Loads the sync cursor for a specific peer instance.

fn list_sync_cursors(&self) -> Result<Vec<SyncCursor>>

Available on crate feature sync only.

Lists all saved sync cursors.

fn compact_wal_events(&self, up_to_seq: u64) -> Result<u64>

Available on crate feature sync only.

Compacts the WAL by deleting events with sequence <= up_to_seq.