Spring Data Cassandra @Version: a conflict is not a merge

Protect the observed row

Two planners load the same dispatch rule at version 4. One lowers the route cap; the other edits the destination zone. Without a conflict check, a full-row save may erase the first decision. @Version adds the observed version to the mutation condition and raises an optimistic-locking failure when another writer has changed it. The mechanism relies on a lightweight transaction. Conditional insert uses the same family of database coordination.

Keep the command meaningful

After conflict, reload the rule and re-evaluate the requested change. Replaying the stale object until it saves can reinstate an old cap. Do not assume batch operations enforce the entity's version: Spring Data Cassandra documents optimistic locking for single-entity operations. For a bulk import, write an explicit reconciliation and conflict report.

Prove both writers

Load two copies in an integration test, save one and require the second to fail. Assert the winning rule remains intact. Repeat through any custom CQL path, because a direct update that omits the version condition can bypass the application's expected boundary.

Implementation sketch

@Table("dispatch_rules")
class DispatchRule {
    @PrimaryKey String ruleId;
    String tenantId;
    int maxRoutes;
    String destinationZone;
    @Version Long version;
}

Cost and verification

Each versioned write pays conditional-operation latency. High contention can make retries expensive; split unrelated rules or serialize commands when they repeatedly collide.

Common Mistakes

• Do not retry the same stale entity without re-evaluating the command.
• Do not expect batch writes to enforce entity optimistic locking.
• Do not bypass the version predicate in a custom CQL update.

Read next

Spring Data Cassandra conditional insert: reserve one key once, Spring Data Cassandra consistency: budget availability and staleness per operation, Spring JPA optimistic locking: reject a stale stock update.