Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
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."
referenced this issue
Apr 8, 2019
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 :-)