Replay

Replaying a stream in Litebase means retrieving past events in the exact order they were originally committed. This is useful for recovery, backfilling, debugging, or applying new logic to old data.

This guide walks you through how to replay events, how to scope your replay window, and how to integrate it with your systems.

1. Understand replay semantics

Every event in Litebase is immutable, timestamped, and versioned. Replaying doesn't alter the original stream — it simply reads events from the append-only log.

You can replay:

• From the beginning of the stream
• From a specific point in time
• From a known transaction ID

This allows you to rebuild state, re-run workflows, or apply updated business logic without modifying live systems.

2. Choose a stream and replay scope

Replays are scoped to a single stream. Use stream names to select the channel you want to reprocess.

You can then choose your starting point:

• from=beginning — all events from the start
• from=2025-04-01T00:00:00Z — events from a specific ISO 8601 timestamp
• since=tx_7a29d1a3 — events after a known transaction ID

3. Fetch historical events

To replay events, send an HTTP GET request to the stream’s replay endpoint:

curl "https://api.litebase.io/v1/streams/user.signup/replay?from=2025-04-01T00:00:00Z" \
  -H "Authorization: Bearer $LITEBASE_API_KEY"

This returns a JSON array of events in the order they were committed:

[
  {
    "time": "2025-04-01T08:00:00Z",
    "tx": "tx_a1",
    "stream": "user.signup",
    "data": {
      "user_id": "u001",
      "email": "[email protected]"
    }
  },
  {
    "time": "2025-04-01T08:05:00Z",
    "tx": "tx_a2",
    "stream": "user.signup",
    "data": {
      "user_id": "u002",
      "email": "[email protected]"
    }
  }
]

The response is paginated. Use the next cursor (if provided) to fetch additional pages.

4. Process events safely

Replayed events are delivered in commit order. Unlike subscriptions, they do not fire in real time.

When reprocessing:

• Ensure your logic is idempotent
• Track which transaction IDs you've handled
• Use batching to control throughput

You can combine replay with storage reads for deeper insights — every event's tx links it to any writes in the same transaction.

5. Use cases for replay

Replaying is useful for:

• Debugging: Diagnose system behavior or investigate issues
• Backfilling: Populate new databases or indexes
• State rebuilds: Reconstruct derived views or caches
• Logic upgrades: Apply new business rules to past data
• Audit trails: Review a full history of changes

Because Litebase Streams are append-only and versioned, every event is a reliable source of truth.