Aerospike Strong Consistency: Configuration, Usage, and Pitfalls

When to enable Aerospike Strong Consistency

Enable Aerospike Strong Consistency (SC) when an application requires linearizable reads and writes—for example, a financial ledger where a balance must never appear stale. SC guarantees that once a write is acknowledged, any subsequent read sees that write, at the cost of higher latency and reduced throughput.

Configuration steps

SC is configured per namespace. The namespace must use a replication factor of exactly two and can be backed by memory or SSD (with defragmentation disabled). Add the following to aerospike.conf:

# aerospike.conf snippet
namespace testns {
        replication-factor 2
        storage-engine memory
        strong-consistency true
}

After saving the file, restart the Aerospike node (or roll the change across the cluster).

Client‑side usage example

To obtain linearizable behavior the client must tell Aerospike to read from the sequential replica. The following Java snippet shows a read‑modify‑write that increments a bin and then reads it back using the same strong‑consistency policy.

import com.aerospike.client.AerospikeClient;
import com.aerospike.client.policy.WritePolicy;
import com.aerospike.client.policy.Policy;
import com.aerospike.client.Bin;
import com.aerospike.client.Operation;
import com.aerospike.client.Key;

public class SCExample {
    public static void main(String[] args) throws Exception {
        AerospikeClient client = new AerospikeClient("host", 3000);
        WritePolicy wp = new WritePolicy();
        wp.replica = Policy.Replica.SEQUENTIAL; // enforce strong consistency
        wp.totalTimeout = 2000; // milliseconds

        Key key = new Key("testns", "demo", "user:123");
        // increment balance by 10
        client.operate(wp, key, Operation.add(new Bin("balance", 10)));

        // immediate read with the same policy
        Record rec = client.get(wp, key);
        long balance = rec.getLong("balance");
        System.out.println("Balance after increment: " + balance);
        client.close();
    }
}

The same policy must be used for any read that needs to see the latest write; otherwise the client may fall back to eventual consistency.

Limits and trade‑offs

• SC only works with a replication factor of exactly two.
• All replicas must be reachable; a missing replica blocks writes until it returns or the operation times out.
• Write latency increases roughly by the network round‑trip time because the coordinator waits for a quorum.
• When the namespace uses the SSD storage engine, SC is disabled if defragmentation is enabled.
• Large binary blobs (>1 MiB) can cause timeouts because each write must be replicated to both nodes before acknowledgment.

Common mistakes to avoid

• Setting strong-consistency true on a namespace with RF=1 leads to write failures.
• Forgetting to set policy.replica=Policy.Replica.SEQUENTIAL results in eventual‑consistency reads, breaking linearizability.
• Mixing SC and eventual‑consistency operations on the same record can create conflicts.
• Using SC for payloads larger than about 1 MiB often exceeds the default timeout.
• Neglecting to monitor the strong-consistency metric; rising values indicate replicas are lagging and writes may block.

Verification steps

1. After the node restarts, inspect aerospike.log for a line such as strong-consistency enabled for namespace testns.
2. Run asinfo -v "strong-consistency:get"; the output should include true for the namespace.
3. Execute a test write‑read cycle as shown in the client example. If the read returns the incremented value, SC is active; a stale or missing value indicates the policy was not applied or SC is disabled.