M.EventBrokerSlim.PersistentEvents.Sqlite 1.0.0

M.EventBrokerSlim.PersistentEvents.Sqlite

SQLite storage backend for EventBrokerSlim persistent events - durable, at-least-once event delivery that survives process restarts. No database server required.

For the design rationale behind persistent events, see the architecture document and ADRs.

Prerequisites

• .NET 8.0 or later
• M.EventBrokerSlim (pulled automatically as a dependency)
• SQLite is embedded — no database server installation required

Installation

dotnet add package M.EventBrokerSlim.PersistentEvents.Sqlite

Database Setup

The package requires a table and indexes in your SQLite database file. There are two ways to set them up:

Option 1: Programmatic

Call CreateEventsTable() on a DatabaseSettings instance:

var databaseSettings = new DatabaseSettings
{
    ConnectionString = "Data Source=events.db",
    Table = "events"
};

databaseSettings.CreateEventsTable();

The call is idempotent - it uses CREATE TABLE IF NOT EXISTS and is safe to run on every startup in development. It also enables WAL (Write-Ahead Logging) mode for better concurrent read/write performance.

Option 2: Manual SQL script

Apply the initialize_db.sql script included in the package source. The default table name is events - replace it with a unique name if running multiple event broker instances against the same database file.

Quick Start

1. Define events and handlers

public record OrderPlaced(string OrderId, decimal Amount);

public class OrderPlacedHandler : IEventHandler<OrderPlaced>
{
    public async Task Handle(OrderPlaced @event, IRetryPolicy retryPolicy, CancellationToken cancellationToken)
    {
        // process the event - must be idempotent
    }

    public async Task OnError(Exception exception, OrderPlaced @event, IRetryPolicy retryPolicy, CancellationToken cancellationToken)
    {
        // optionally retry
        retryPolicy.RetryAfter(TimeSpan.FromSeconds(5));
    }
}

Alternative: delegate handler

public record OrderPlaced(string OrderId, decimal Amount);

IPipeline pipeline = PipelineBuilder.Create()
    .NewPipeline()
    .Execute(static async (IRetryPolicy retryPolicy, INext next) =>
    {
        try
        {
            await next.RunAsync();
        }
        catch(Exception exception)
        {
            retryPolicy.RetryAfter(TimeSpan.FromSeconds(5));
        }
    })
    .Execute(static async (OrderPlaced @event, ISomeService service, CancellationToken ct) =>
    {
        await service.ProcessOrder(@event, ct);
    })
    .Build()
    .Pipelines[0];

2. Register the event registry

Map each event type to a stable string name. The name is stored in the database - it must not change between deployments:

var eventRegistry = new EventRegistry()
    .Add<OrderPlaced>("OrderPlaced");

serviceCollection.AddSingleton(eventRegistry);

3. Register handlers with persistent names

Only handlers registered with a handlerName participate in fan-out:

serviceCollection.AddTransientEventHandler<OrderPlaced, OrderPlacedHandler>(
    handlerName: "OrderPlacedHandler");

Or using the options API:

serviceCollection.AddTransientEventHandler<OrderPlaced, OrderPlacedHandler>(o => o
    .WithHandlerName("OrderPlacedHandler"));

Alternative: delegate handler

serviceCollection.AddEventHandlerPipeline<OrderPlaced>(pipeline,
    handlerName: "OrderPlacedHandler");

4. Configure the event broker with SQLite persistence

serviceCollection.AddEventBroker(x => x
    .WithMaxConcurrentHandlers(3)
    .WithSqlitePersistence((db, settings) =>
    {
        db.ConnectionString = "Data Source=events.db";
        db.Table = "events";
        db.CreateEventsTable();
        settings.PollingInterval = TimeSpan.FromSeconds(10);
        settings.ProcessingTimeout = TimeSpan.FromMinutes(5);
    }));

5. Start the persistent event broker

var serviceProvider = serviceCollection.BuildServiceProvider();
serviceProvider.UsePersistentEventBroker(throwOnValidationErrors: true);

6. Publish events

await eventBroker.Publish(new OrderPlaced("order-123", 49.99m));

Configuration Reference

DatabaseSettings

PersistentEventBrokerSettings

Important Considerations

Single-instance scope. SQLite is an embedded database. It targets single-process deployments where durability (crash survival) is needed but multi-instance horizontal scale-out is not required. For multi-instance deployments, consider suitable backend.

At-least-once delivery. A crash after claiming a record but before completing it may cause duplicate processing. Handlers must be idempotent.

WAL mode. CreateEventsTable() enables WAL (Write-Ahead Logging) journal mode, which allows concurrent reads while writing. This is important for the polling loop and publisher operating concurrently.

Escaped exceptions are dead-lettered. If an exception escapes the handler pipeline unhandled, the record is immediately dead-lettered. Handle exceptions inside the pipeline to use retries.

Name stability. Changing a handlerName or an EventRegistry name is a breaking change - in-flight records under the old name will never be claimed.

Serialization. Events are serialized using System.Text.Json with camelCase property naming, no indentation, and null values omitted. Event types must be serializable under these settings.

Not event sourcing. The store is a delivery mechanism, not an event log. Completed records are deleted according to CompletedRecordTtl.

Not a transactional outbox. The event write to SQLite is not atomic with the caller's own database transaction.

Database Schema

The package creates the following schema (default table name events):

Events Table

Indexes

License

MIT