Skip to main content

Revisions

In Kahuna, a revision is a monotonic version number that tracks when a key was last modified. Every time a key is updated or deleted, its revision increments, ensuring strong consistency and strict ordering. It acts as a logical timestamp to resolve stale client operations.

Understanding revisions​

Keys are always created at revision r0:

set `example` 'value1'
r0 set 17ms

Modify the key and revision will change to r1 and then to r2:

set `example` 'value2'
r1 set 12ms

set `example` 'value3'
r2 set 9ms

When querying a key, you can see its current revision. The revision does not change during read operations:

get `example`
r2 value3 10ms

get `example`
r2 value3 9ms

Skipping Historical Revisions​

Some workloads only need the latest value. For example, a pure key/value cache may overwrite the same key frequently and never read older versions. In that case, use SET ... NOREV to skip the historical revision record for that write:

set `cache/user/1001` '{"name":"Ada"}' ex 60000 norev
r0 set 8ms

set `cache/user/1001` '{"name":"Ada Lovelace"}' ex 60000 norev
r1 set 7ms

NOREV does not freeze the revision counter. The current revision still advances, latest reads still return the new value, and compare-revision operations can still protect conditional updates. What changes is the history: the revision produced by a NOREV write is not archived for GET ... AT <revision> or historical snapshot reads.

Use normal SET when you need audit history, debugging timelines, rollbacks, or point-in-time reads. Use SET ... NOREV when reducing memory and disk write amplification matters more than retaining old values.

Querying Previous Revisions​

Kahuna works like a time machine, allowing you to query the value of a key at any particular point-in-time:

get `example` at 0
r0 value1 11ms

get `example` at 1
r1 value2 13ms

This lets you inspect historical data, trace config or state changes historically, debug changes over time, investigate what value caused a bug or revert to stable known-good values.

AT Revision vs AS OF Timestamp​

Kahuna supports two different historical read models:

  • AT <revision> reads one exact archived revision for a key.
  • AS OF <timestamp> reads the value that was visible at a specific HLC snapshot time.

Use AT when you already know the precise revision you want. Use AS OF when you want to answer "what did the cluster see at time T?" across one or more reads.

Examples:

get `example` at 1
get `example` as of 1718392012345
exists `example` as of 1718392012345
get by bucket `services` as of 1718392012345
scan by prefix `services/auth` as of 1718392012345

AS OF is especially useful for debugging incidents, reconstructing historical state, and running consistent read-only scripts against an older snapshot.

Snapshot timestamps must be non-zero. AT and AS OF cannot be combined on the same statement.

For long-lived historical views, use snapshot holds to keep the required persistent revisions from being pruned while the view remains active.

Practical Uses of Retrieving Old Revisions​

While many systems only care about the latest value, Kahuna's ability to retrieve old revisions opens up some powerful, practical use cases, especially in distributed systems, debugging, auditing and observability:

  • Audit Trails and Change History: Kahuna stores each change at a new revision, so you can inspect historical values. Useful for debugging, compliance, or postmortem analysis. With revisions we can see how a config flag looked at a specific point in time. Helps trace misconfigurations or unauthorized changes.
  • Debugging State Changes Over Time: Understand how and why a system entered a bad state. Distributed systems can be hard to debug after the fact and Retrieving old revisions helps you reconstruct the timeline of state changes. It's useful when investigating failures that occurred hours or days ago.
  • Safe Rollbacks of Configuration or State: Roll back to a previous known-good configuration. If a new config breaks the system, you can pull a previous value and restore it. Provides a quick and clean rollback mechanism.
  • Data Versioning for CI/CD or Experiments: Compare previous and current values during deploys or A/B tests. You can track how configs or feature flags evolved over time. Useful for debugging failed deployments or verifying that changes had intended effects.

Kahuna supports two types of durability: ephemeral, which uses only the volatile memory (RAM) of the leader node where the key/value is stored, and persistent, which uses durable disk-based storage. In case of memory pressure, ephemeral keys may be evicted if they haven’t been accessed recently. In the case of ephemeral storage, the server stores a limited number of recent revisions. If you need to store all revisions of a key, you should use persistent storage. Learn more in the supported durabilities section

Summary​

  • Revision tracks when a key was last modified.
  • It updates on every write but stays the same for reads.
  • SET ... NOREV still advances the current revision but skips historical revision storage.
  • Used in leader election, distributed locks and race condition prevention.
  • Essential for Compare-And-Swap (CAS) operations.