Aerospike Strong Consistency: Stop Stale Reads in Payment Ledgers

The stale balance problem

A payment service writes a deposit to Aerospike, then immediately reads the same key to confirm the funds before crediting a user's wallet. With Aerospike's default consistency model, that read can return the previous balance because the write may not have propagated to every replica yet. For a ledger, that stale read means a customer can see money that has not actually landed, or spend it twice.

Useful takeaway: enable Aerospike Strong Consistency on the bins that represent financial state. Reads and writes go to the master replica and wait for replica acknowledgment, giving you linearizable reads—every read returns the most recent committed write. You trade write speed for that guarantee.

What default consistency means

Aerospike stores each record on a master replica and one or more replica nodes. The replication factor is the total number of copies kept across the cluster. By default, writes are acknowledged after the master applies them, while replicas catch up asynchronously. Reads can be served by any replica. This is eventual consistency: all copies eventually converge, but immediately after a write, a replica may still hold the old value.

Linearizability is the stronger guarantee. It means operations appear to happen in one global order, and once a write completes, every later read sees that write or a newer one.

How Strong Consistency changes the write path

With Strong Consistency enabled, the client sends the write to the master replica. The master waits for acknowledgment from a quorum of replicas before returning success. Reads also go to the master and wait for the same quorum, so a stale replica cannot satisfy the request.

This mode requires a replication factor of at least two and at least three nodes in the cluster. A two-node cluster cannot form a quorum across every replica, so the server rejects the consistency level.

Worked example: client policy and server check

Set the consistency level on the Aerospike client policy:

Policy writePolicy = new Policy();
writePolicy.consistencyLevel = ConsistencyLevel.STRONG;
client.put(writePolicy, key, new Bin("balance", 100));

Policy readPolicy = new Policy();
readPolicy.consistencyLevel = ConsistencyLevel.STRONG;
Record rec = client.get(readPolicy, key);
System.out.println(rec.getValue("balance"));

Enable the mode on each node in /etc/aerospike/aerospike.conf under the service stanza. You need sudo or aerospike-user permissions to edit the file:

service {
    ...
    consistency-level strong
}

After applying the config and restarting the node, verify from a terminal with SSH access to the Aerospike host. Run:

asinfo -v 'get-config:service;consistency-level'

The response should contain strong. If it returns off or errors, the node is not running Strong Consistency or the cluster does not meet quorum requirements. Changing this setting is state-changing: restarting nodes causes brief unavailability for records hosted there, so use a rolling restart during a maintenance window.

Trade-offs and limitations

Strong Consistency adds network round-trips because every write waits for replica acknowledgment. Expect roughly two to three times higher write latency than the default mode, and lower write throughput under load. During a node failure or network partition, operations that cannot reach a quorum may time out or fail.

Enable it selectively. Keep the default model for session caches or recommendation data where occasional staleness is acceptable. Reserve Strong Consistency for balances, ledger entries, and idempotency keys.

Verify before you rely on it

Run a write-then-read check against a test key using the STRONG policy, then stop the master node for that key and confirm the read returns the latest value or fails rather than serving stale data. Compare average write latency with asbench before and after enabling the mode. Measure under your actual concurrency and payload size before rolling back any production traffic.

If the latency increase is unacceptable, consider eventual consistency with asynchronous reconciliation, or move financial state to a dedicated strongly consistent store.