Documentation for transaction retries is misleading #10077
TiDB's documentation repeatedly claims to offer snapshot isolation. However, two automatic retry mechanisms (#10075, #10076), invalidate this claim. The first mechanism is partly documented, but the documentation is confusing. The second is undocumented. Until these mechanisms can be disabled or fixed, I suggest updating the documentation in the following ways:
This paragraph should explain that
Optimistic transactions do execute differently than pessimistic ones, and users commonly ask questions about the semantics of conflicts and retries in optimistic databases. In addition, many MVCC databases do provide an automatic transaction retry mechanism which does not violate snapshot isolation. These factors could lead users to misinterpret this documentation, failing to realize that the retry mechanism invalidates fundamental properties of TiDB's transactional model.
Since these are properties specifically of TiDB's retry mechanism, and not optimistic transactions in general, you might consider changing the section title from "Description of optimistic transactions" to "Transactional anomalies caused by automatic retries". I also suggest changing language like "automatic retry cannot guarantee the final result is expected" to "automatic retry can violate snapshot isolation, causing lost updates."
The text was updated successfully, but these errors were encountered:
Thank you for reporting this issue!
We are discussing a longer-term fix to (#10075, #10076), so as you suggest I will interpret this issue as for the documentation specifically. I have created pingcap/docs#1027 - I believe I have updated all the cases you mentioned, but appreciate a review too :-)
* Warn about transaction retry From pingcap/tidb#10077 * Add warning about transaction retry * Additional changes to clarify retry * fix anchor link * Add note that SI needs context * Use TRUE consistently Helps communicate it is a boolean even if mysql is flexible. * Consistent spacing * Add further clarification * Improve case to match style