evento-fjall

Fjall embedded key-value store implementation for the evento event sourcing library.

Overview

This crate provides an [Executor] implementation using fjall, an LSM-tree based embedded key-value storage engine. It's ideal for applications that need:

• Embedded storage - No external database server required
• High write throughput - LSM-tree optimized for write-heavy workloads
• Simple deployment - Single binary with no dependencies
• Rust-native - Pure Rust implementation

Installation

Add to your Cargo.toml:

[dependencies]
evento-fjall = "2"
evento-core = "2"
bitcode = "0.6"

Usage

Basic Example

use evento_fjall::Fjall;
use evento::{Executor, metadata::Metadata, cursor::Args, ReadAggregator};

// Define events using an enum
#[evento::aggregator]
pub enum User {
    UserCreated { name: String },
    NameChanged { name: String },
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Open the database
    let executor = Fjall::open("./my-events")?;

    // Create an event
    let id = evento::create()
        .event(&UserCreated { name: "test".into() })
        .metadata(&Metadata::default())
        .commit(&executor)
        .await?;

    // Query events
    let result = executor.read(
        Some(vec![ReadAggregator::id("user/User", &id)]),
        None,
        Args::forward(10, None),
    ).await?;

    println!("Found {} events", result.edges.len());
    Ok(())
}

Custom Configuration

use evento_fjall::Fjall;
use fjall::Config;

// Configure fjall with custom options
let keyspace = Config::new("./events.db")
    .max_write_buffer_size(128 * 1024 * 1024)  // 128MB write buffer
    .open()?;

let executor = Fjall::from_keyspace(keyspace)?;

With Projections

use evento_fjall::Fjall;
use evento::{metadata::Event, projection::Projection};

// Define events
#[evento::aggregator]
pub enum User {
    UserCreated { name: String },
}

#[evento::projection]
struct UserView {
    name: String,
}

#[evento::handler]
async fn on_user_created(
    event: Event<UserCreated>,
    view: &mut UserView,
) -> anyhow::Result<()> {
    view.name = event.data.name.clone();
    Ok(())
}

let executor = Fjall::open("./events")?;

let result = Projection::<_, UserView>::new::<User>(&user_id)
    .handler(on_user_created())
    .execute(&executor)
    .await?;

Data Model

Events are stored across multiple partitions for efficient querying:

Performance Considerations

• Write batching - Events are written atomically in batches
• Async I/O - Blocking fjall operations are wrapped with spawn_blocking
• Persistence - Writes are synced to disk after each batch for durability
• Compression - Consider enabling fjall's compression for large datasets

Comparison with SQL Executors

License

See the LICENSE file in the repository root.