Struct DbCore

pub struct DbCore { /* private fields */ }

The main concurrent time-series database core struct.

Implementations

impl DbCore

pub fn with_config(config: DbConfig) -> Result<Self, DbError>

Creates a new DbCore instance with the provided configuration.

This sets up the in-memory storage, write buffer, and (if enabled) persistence mechanisms such as the Write-Ahead Log (WAL) and snapshotting. It also spawns the background flush thread, which periodically flushes staged writes to storage and handles snapshot creation.

Arguments

• config - The database configuration to use.

Returns

• Ok(DbCore) if initialization succeeds.
• Err(DbError) if any component fails to initialize (e.g., WAL or snapshotter).

Errors

Returns an error if persistence components cannot be initialized.

pub fn new(flush_interval: Duration) -> Self

Creates a new DbCore instance with default configuration, but with a custom flush interval.

This is a convenience constructor for quickly creating a database with a specific flush interval. All other configuration options use their default values.

Arguments

• flush_interval - The interval between automatic buffer flushes.

Panics

Panics if the database cannot be initialized with the default configuration.

pub fn recover(&mut self) -> Result<(), DbError>

Recovers the database state from disk using the latest snapshot and any newer WAL entries.

This method should be called after constructing the database if you want to restore persisted data. It loads the most recent snapshot (if enabled), then applies any WAL entries that occurred after the snapshot.

Returns

• Ok(()) if recovery succeeds or if persistence is not enabled.
• Err(DbError) if recovery fails.

Errors

Returns an error if loading the snapshot or WAL fails.

pub fn insert( &self, series: &str, timestamp: Timestamp, value: Value, tags: TagSet, ) -> Result<(), DbError>

Inserts a data point into the specified time series.

This method is thread-safe and can be called concurrently from multiple threads. The data point is first staged in the write buffer and will be flushed to storage either automatically (by the background thread) or manually (via flush()). If WAL is enabled, the insert is also logged for durability.

Arguments

• series - Name of the time series.
• timestamp - Timestamp of the data point.
• value - Value to insert.
• tags - Associated tags for the data point.

Returns

• Ok(()) if the data point is staged successfully.
• Err(DbError) if staging or logging fails.

Errors

Returns an error if the WAL or write buffer cannot be accessed.

pub fn query( &self, series: &str, time_range: Range<Timestamp>, tag_filter: Option<&TagSet>, ) -> Result<Vec<(Timestamp, Value)>, DbError>

Queries data points from a specific time series within a given time range, optionally filtering by a set of tags.

This method is thread-safe and allows concurrent queries. It acquires a read lock on the storage and the relevant series chunk, then executes the query in parallel.

Arguments

• series - The name of the time series to query.
• time_range - The time range for the query (start inclusive, end exclusive).
• tag_filter - An optional set of tags to filter by. Only points matching all tags are returned.

Returns

• Ok(Vec<(Timestamp, Value)>) with all matching data points.
• Err(DbError) if the series does not exist or a lock cannot be acquired.

Errors

Returns an error if the series is not found or if a lock is poisoned.

pub fn flush(&self) -> Result<(), DbError>

Triggers an immediate flush of the write buffer to storage.

This sends a command to the background flush thread to flush all staged data points to the in-memory storage. Useful for testing or ensuring data is persisted before shutdown.

Returns

• Ok(()) if the flush command is sent successfully.
• Err(DbError) if the command cannot be sent.

Errors

Returns an error if the background thread cannot be reached.

pub fn snapshot(&self) -> Result<(), DbError>

Triggers an immediate snapshot of the current database state.

This sends a command to the background flush thread to create a snapshot of all in-memory data. Snapshots are only available if enabled in the configuration.

Returns

• Ok(()) if the snapshot command is sent successfully.
• Err(DbError) if snapshots are not enabled or the command cannot be sent.

Errors

Returns an error if snapshots are disabled or if the background thread cannot be reached.

pub fn get_config(&self) -> &DbConfig

Returns a reference to the current database configuration.

This allows inspection of the configuration used to initialize the database.

Returns

• A reference to the DbConfig struct.

Trait Implementations

impl Debug for DbCore

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

Formats the value using the given formatter.

impl Default for DbCore

Default implementation uses a 1-second flush interval.

fn default() -> Self

Returns the “default value” for a type.

impl Drop for DbCore

Implement Drop to gracefully shut down the background flush thread.

fn drop(&mut self)

Executes the destructor for this type.