Implementing Linearizable Writes with Lightweight Transactions in Apache Cassandra

Desired Outcome

Perform a compare‑and‑set (CAS) write that guarantees linearizable consistency for a single row, using Apache Cassandra’s Lightweight Transactions (LWT) feature. The operation should either apply the change when a condition is met or leave the data unchanged, returning a clear indicator of success.

Prerequisites

• Apache Cassandra 3.0 or later (LWT was introduced in 2.0 and stabilized in 3.x).
• Access to a CQL shell (cqlsh) or a driver that can execute CQL statements.
• A keyspace and table defined with a primary key that identifies the row you intend to update.
• Sufficient permissions to INSERT/UPDATE and to read the system schema for monitoring.
• Understanding that LWT incurs higher latency due to the Paxos prepare/propose/commit phases.

Procedure

1. Choose the consistency level for the transaction. LWT uses a separate serial_consistency setting that defaults to SERIAL (or LOCAL_SERIAL for multi‑datacenter clusters). You can override it per statement if needed.
2. Construct the CQL statement with the appropriate IF clause. Use IF NOT EXISTS for an insert‑only check or IF column = value for a compare‑and‑set update.
3. Execute the statement. Example using cqlsh:

cqlsh> INSERT INTO users (user_id, email, created_at)
    VALUES (uuid(), '[contact removed]', toTimestamp(now()))
    IF NOT EXISTS;

Replace users, column names, and values with your own schema. The uuid() function generates a new UUID for the primary key if you need a fresh row; for an update on an existing row, supply the existing key and use IF on a column.

1. Inspect the result. The statement returns a result set that includes an [applied] boolean column. A value of true means the condition was satisfied and the write was committed; false means the condition failed and no change was made.
2. Verify durability. After a successful LWT, you can read the row with a regular SELECT at any consistency level (e.g., QUORUM) to confirm the data is visible.
3. Monitor for contention. Under high concurrent CAS attempts on the same partition, watch for WriteTimeoutException in the logs or via nodetool tpstats:

nodetool tpstats

Look at the MutationStage and ReadStage metrics; an increase in pending tasks or a drop in completed Paxos operations signals contention.

Expected Checks

• First execution: The returned [applied] column should be true. A subsequent identical statement (same condition) should return false because the condition is no longer satisfied.
• Log inspection: No WriteTimeoutException entries for the LWT under low‑to‑moderate load.
• Thread pool stats: Paxos-related stages (PrepareStage, ProposeStage, CommitStage) show steady completion rates without growing queues.
• Data verification: A SELECT * FROM users WHERE user_id = ?; returns the inserted row with the expected values.

Recovery Options

Because an LWT that returns false

• Execute a compensating DELETE or UPDATE using another LWT (e.g., IF email = '[contact removed]') to revert or correct the row.
• Use a batch with a regular DELETE if you need to remove the row and accept the extra overhead.

Note that compensatory actions also incur LWT overhead and should be used sparingly.

Limitations and Practical Verification

• LWT is designed for low‑contention scenarios. Repeated CAS attempts on the same partition key can cause latency spikes and timeouts.
• Atomicity across multiple partitions requires a BATCH statement, which adds another round‑trip and does not eliminate the Paxos overhead.
• Geographically distributed clusters may experience higher latency because the serial consistency level may involve cross‑datacenter coordination.

To check whether your workload stays within safe limits, run a controlled test:

1. Deploy a simple client that issues INSERT … IF NOT EXISTS on a fixed partition key at a configurable rate.
2. Measure the average latency and the percentage of responses with [applied] = false (indicating contention).
3. If latency exceeds your SLA or the false‑response rate rises above a few percent, consider redesigning the data model to avoid hot partitions or using application‑level locking instead of LWT.