Document the causality token that forces txn serialization over time

[knz]

Raphael 'kena' Poss (knz) commented:

Users are asking how to ensure that SERIALIZABLE isolation translates to sequential execution over time (i.e. results from a committed txn A are visible from a txn B opened after A commits).

CockroachDB offers a (primitive) mechanism to do so, this was answered on the forum here:

https://forum.cockroachlabs.com/t/strong-consistency/1563/2

• The main explanation should probably be included on the Transactions page: https://www.cockroachlabs.com/docs/stable/transactions.html

• then the explanation should be included on the FAQ page, as answer to the commonly asked question "How to guarantee the ordering of serializable transactions over time?"

We may want to improve the UX of using causality tokens in future versions of CockroachDB (e.g. via an easier to use SQL interface, which does not require the client to know what is the current value of maxoffset), but users should be informed that there is a mechanism already.

cc @bdarnell @justinj @arjunravinarayan

Jira Issue: DOC-169

[bdarnell]

Why is knowledge of the max offset needed here? Just having a higher HLC should be sufficient to observe the first transaction's write.

[knz]

I understand that if it's too close (< + maxoffset) the txn may be bumped with an uncertainty error due to the ts cache?

[bdarnell]

No, the ts cache doesn't consider maxoffset. You may get a ReadWithinUncertainty error due to maxoffset, but this will either leave the timestamp alone or move it forward; by the time the transaction has committed you no longer need to consider maxoffset.

[jseldess]

@sploiselle, you might be able to factor this into your doc work on distributed transactions.

[sploiselle]

@bdarnell Can I get a little clarification on this?

Txn_A:

BEGIN;
SELECT cluster_logical_timestamp();
INSERT INTO kv VALUES (1, a);
COMMIT;

Txn_B:

BEGIN;
SELECT cluster_logical_timestamp();
UPDATE kv SET v = 'b' WHERE k = 1;
COMMIT;

You can ensure that Txn_B will see the write from Txn_A as long as the value returned from Txn_B's SELECT cluster_logical_timestamp() is > Txn_A's, even if the difference is less than the max offset?

Are there additional stipulations here like these transactions must be coming from the same client (so as to be able to share Txn_A's cluster_logical_timestamp with Txn_B)?

[bdarnell]

You can ensure that Txn_B will see the write from Txn_A as long as the value returned from Txn_B's SELECT cluster_logical_timestamp() is > Txn_A's, even if the difference is less than the max offset?

Yes.

Are there additional stipulations here like these transactions must be coming from the same client (so as to be able to share Txn_A's cluster_logical_timestamp with Txn_B)?

No, they don't have to be from the same client.

[knz]

What ben said, also do not forget to mention that as soon as a txn uses cluster_logical_timestamp() that will disable optimizations inside CockroachDB and increase contention and/or retry errors. So clients should avoid wanting to care about this unless they have a very, very good reason to.

[jseldess]

We have closed this issue because it is more than 3 years old. If this issue is still relevant, please add a comment and re-open the issue. Thank you for your contribution to CockroachDB docs!