Implement an optimistic version conflict in JPA

Update an order status only if it still has the version the client read. The representation exposes a version and the update receives that expected version. A stale update must change no rows and return a conflict response. The successful update increments the version atomically.

client A reads version 4
client B updates version 4 -> version becomes 5
client A updates expected 4 -> 409/412, no overwrite

• Keep a JPA @Version field on the entity.
• Do not reload the current entity and then discard the client's original version.
• Use one atomic conditional update for this command.
• Increment the version in the same SQL statement.
• Map zero affected rows to the documented not-found or conflict policy.

1. Expose the version in the read model or an ETag.
2. Require the original version on the update request.
3. Execute an update whose WHERE clause includes both ID and expected version.
4. Check the affected-row count before returning success.
5. Return the new version and make the client re-read before retrying a conflicting edit.

@jakarta.persistence.Entity
class Order {
    @jakarta.persistence.Id private Long id;
    @jakarta.persistence.Version private long version;
    @jakarta.persistence.Enumerated(jakarta.persistence.EnumType.STRING)
    private OrderStatus status;
}

interface OrderRepository extends org.springframework.data.jpa.repository.JpaRepository<Order, Long> {
    @org.springframework.data.jpa.repository.Modifying(clearAutomatically = true, flushAutomatically = true)
    @org.springframework.data.jpa.repository.Query("""
        update Order o
           set o.status = :status, o.version = o.version + 1
         where o.id = :id and o.version = :expectedVersion
        """)
    int updateStatus(long id, long expectedVersion, OrderStatus status);
}

@org.springframework.stereotype.Service
class OrderCommands {
    private final OrderRepository orders;

    @org.springframework.transaction.annotation.Transactional
    long changeStatus(long id, long expectedVersion, OrderStatus status) {
        int changed = orders.updateStatus(id, expectedVersion, status);
        if (changed == 0) {
            if (!orders.existsById(id)) throw new OrderNotFound();
            throw new StaleOrderVersion(expectedVersion);
        }
        return expectedVersion + 1;
    }
}

The conditional update and existence check are indexed O(log n). Only the conflict path needs the second query; success uses one update.

• Deleting the row and changing its version both produce zero updated rows; the API chooses whether to distinguish them.
• A bulk JPQL update bypasses normal managed-entity synchronization, so the persistence context is cleared.
• A version protects this row, not an invariant spanning several rows.
• Automatic retries can overwrite user intent and are inappropriate without a merge policy.

• Run two updates with the same expected version and assert exactly one succeeds.
• Verify the winner increments the version by one.
• Verify a stale request leaves status and version unchanged.
• Verify a missing ID follows the documented 404 policy.

• Loading the newest entity and saving it ignores the stale version the client actually edited.
• Checking the version in Java before an unconditional update leaves a race.
• Forgetting to increment version makes the next stale write appear current.
• Blindly retrying a user edit hides the conflict instead of resolving it.