Skip to content

Verifying Store Integrity

This guide explains how to verify the internal integrity of an EventSourcingDB instance. It covers how to trigger a full validation of stored events and indexes and how to interpret the results.

Overview

EventSourcingDB provides a verification endpoint that performs a complete integrity check of the event store. It recalculates all event hashes from scratch, validates the consistency of stored data, and verifies all internal indexes.

This operation can help detect data corruption, storage issues, or index inconsistencies.

Running a Store Verification

To start a store verification, send an HTTP POST request to /api/v1/verify-store:

curl -i \
  -X POST \
  -H "Authorization: Bearer <API_TOKEN>" \
  http://localhost:3000/api/v1/verify-store

The server responds with a stream of newline-delimited JSON. While the verification is still running, the server sends heartbeat lines to keep the connection open; the final line carries the result:

{"type":"result","payload":{"errors":[],"warnings":[]}}

An empty errors list indicates that no inconsistencies were found. The warnings list may contain additional notices, but does not necessarily indicate a failure.

Each check reports every inconsistency it finds, up to 100; beyond that, a further line says how many more it found. Only the hash chain cannot be followed past a break: the error names the event where it breaks, and the events after it are not checked against the chain.

Reads and writes go on while the store is verified. The verification checks the store as of the latest event at its start; events written meanwhile are checked by the next verification.

If the verification itself cannot run to completion – say the store cannot be read – the stream ends with an error line instead:

{"type":"error","payload":{"error":"..."}}

If the database shuts down while the verification runs, the line says database is shutting down: try again later; verify the store again once it is back.

The status code is already 200 by the time the first line goes out, so the last line is what tells you whether the verification finished. Treat an error line as an aborted check, not as a clean one.

Typical Use Cases

Store verification is useful in the following scenarios:

  • After recovering from disk failures or system crashes.
  • As part of regular maintenance procedures.
  • Before migrating data to a new instance.
  • To investigate unexpected read or write issues.

A successful store verification provides assurance that the event store is internally consistent and fully operational.

Impact on Performance

Running a full store verification can be resource-intensive, especially for large datasets: it reads every event and every index file. Reads and writes go on meanwhile, but compete with it for the disk, so prefer low-traffic periods.