Answer to the question
Akka Persistence does not ship a built‑in hash‑verification mechanism for journal backups. The recommended pattern is to compute a deterministic digest of the journal’s persistent representation after a backup, store that digest in a sidecar metadata file, and compare it during the next startup. The feature can be toggled with a configuration flag so it does not affect normal operation when disabled.
Recommended approach
- Backup the journal while the node is stopped. Copy the files, tables, or column families that represent the event log.
- Compute a hash. For LevelDB use
sha256sum persistence-id.journal; for Cassandra run nodetool get_digest (or a lightweight query of the column family digest); for JDBC execute a SELECT CHECKSUM(*) FROM events or a custom aggregate that traverses the table in a deterministic order.
- Store the hash. Write the value to a file named
persistence-id.journal.hash next to the backup artefact. The file should contain only the hash string and a timestamp.
- Restore the journal. Copy the backup artefact back into the persistence directory or table.
- Verify on startup. Add a small Akka component that, during pre‑start, reads the stored hash, recomputes the digest of the live journal, and aborts startup (or logs an error) if the values differ. This check is performed before any event replay occurs.
Interaction with back‑ends
| Backend | How to compute digest | Notes |
|---|
| LevelDB | File‑level SHA‑256 of the journal file | Deterministic as long as the file is not modified |
| Cassandra | nodetool get_digest or lightweight query of the column family digest | Requires a consistent read under the same consistency level |
| JDBC | SELECT CHECKSUM(*) or custom aggregate over the events table | Must order rows deterministically (e.g., by sequence number) |
Relation to Snapshot Verification
The akka.persistence.snapshot.verification.enabled flag verifies the integrity of snapshot files only. Journal hash verification is orthogonal: it protects the event log itself from corruption or tampering. Both checks can be enabled simultaneously without conflict.
Suggested Akka configuration
akka.persistence.journal.hash-verification.enabled = on
akka.persistence.journal.hash-verification.dir = "${user.home}/.akka/backup-hashes"
When enabled, Akka will look for a *.hash file in the configured directory during startup and compare it against the computed digest. If the values differ, the actor system will terminate with a clear error message.
What Akka should expose
- A single configuration flag to toggle hash verification.
- An API for the persistence plugin to expose the digest of the current journal state.
- Documentation on how to generate and store the hash during backup for each supported backend.
Providing these hooks keeps the feature lightweight and backend‑agnostic while giving administrators a straightforward way to integrate hash verification into their existing backup workflows.
Diagnostic question
To fine‑tune the implementation, could you confirm whether you perform hot backups (while the node is running) or only cold backups (node stopped)? The choice influences how the hash is computed and validated.
akka