dotnet-cqrs/docs/event-streaming/event-replay/README.md

Event Replay

Rebuild projections and reprocess historical events with rate limiting and progress tracking.

Overview

Event replay enables you to rebuild projections, reprocess events after bug fixes, create new read models from historical data, and perform time-travel debugging.

Key Features:

• ✅ Offset-Based Replay - Replay from specific sequence numbers
• ✅ Time-Based Replay - Replay from timestamps
• ✅ Rate Limiting - Control replay speed with token bucket
• ✅ Progress Tracking - Monitor progress with callbacks
• ✅ Event Filtering - Replay only specific event types
• ✅ Batch Processing - Efficient streaming with configurable batches

Quick Start

using Svrnty.CQRS.Events.PostgreSQL;

var builder = WebApplication.CreateBuilder(args);

// Enable event replay
builder.Services.AddPostgresEventReplay();

var app = builder.Build();
app.Run();

Usage

Replay from Offset

var replayService = serviceProvider.GetRequiredService<IEventReplayService>();

await foreach (var @event in replayService.ReplayFromOffsetAsync(
    streamName: "orders",
    startOffset: 1000,
    options: new ReplayOptions
    {
        BatchSize = 100,
        MaxEventsPerSecond = 1000,
        ProgressCallback = progress =>
        {
            Console.WriteLine($"{progress.EventsProcessed} events @ {progress.EventsPerSecond:F0} events/sec");
        }
    }))
{
    await ProcessEventAsync(@event);
}

Replay from Time

await foreach (var @event in replayService.ReplayFromTimeAsync(
    streamName: "orders",
    startTime: DateTimeOffset.UtcNow.AddDays(-7)))
{
    await RebuildProjectionAsync(@event);
}

Features

Replay from Offset

Replay events from specific sequence numbers for rebuilding projections.

Replay from Time

Replay events from specific timestamps for time-travel debugging.

Rate Limiting

Control replay speed with token bucket rate limiting.

Progress Tracking

Monitor progress with metrics and estimated completion times.

Common Use Cases

Rebuild Read Models:

// Reset projection checkpoint
await _checkpointStore.ResetCheckpointAsync("order-summary");

// Replay all events
await foreach (var @event in replayService.ReplayFromOffsetAsync("orders", 0))
{
    await _projection.HandleAsync(@event);
}

Reprocess After Bug Fix:

// Fix deployed, reprocess last 7 days
var sevenDaysAgo = DateTimeOffset.UtcNow.AddDays(-7);

await foreach (var @event in replayService.ReplayFromTimeAsync("orders", sevenDaysAgo))
{
    await ReprocessEventAsync(@event);
}

Create New Projection:

// New projection needs historical data
await foreach (var @event in replayService.ReplayFromOffsetAsync("orders", 0, new ReplayOptions
{
    EventTypeFilter = new[] { "OrderPlacedEvent", "OrderShippedEvent" },
    MaxEventsPerSecond = 5000
}))
{
    await _newProjection.HandleAsync(@event);
}

See Also

• Event Streaming Overview
• Projections
• Persistent Streams