Verifying Store Integrity

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, checks that every stored event schema compiles and describes an object, and verifies all internal indexes.

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

Running a Store Verification#

Changed in 1.3To 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 stops at the first inconsistency it finds, so a list of errors is not necessarily complete. After repairing what it names, verify the store again: further inconsistencies may show up then.

Changed in 1.3If 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":"..."}}

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.

Removed in 1.3Broken in 1.0, fixed in 1.3An event that is older than the event before it is reported as an error that ends in timestamp did not increment monotonically. Such an event comes about when the clock of the server goes back while it writes, for example when NTP corrects it, and since events cannot be changed, every later verification reports it as well.

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.