MySQL Bugs: #113401: Manual on locking reads inaccurately describes use case

Bug #113401	Manual on locking reads inaccurately describes use case
Submitted:	12 Dec 2023 16:17	Modified:	12 Dec 2023 18:05
Reporter:	Bill Karwin (Candidate Quality Contributor) (OCA)	Email Updates:
Status:	Verified	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	8.2	OS:	Any
Assigned to:		CPU Architecture:	Any

Description:
The manual page 15.7.2.4 Locking Reads contains the following paragraph:

--- quote ---
These clauses are primarily useful when dealing with tree-structured or graph-structured data, either in a single table or split across multiple tables. You traverse edges or tree branches from one place to another, while reserving the right to come back and change any of these “pointer” values. 
--- unquote ---

I think this paragraph is misleading to readers, and it adds nothing to a reference manual.

This may be a possible use of locking reads, but it's hard to believe this is their _primary_ use.

The reference manual seldom describes use cases for features.

How to repeat:
Read the manual page.

Suggested fix:
Remove that paragraph from the manual page.

HI Mr. Karwin,

Thank you for your bug report.

However, this is their primary use ......

Can you let us know how would you like us to describe the locking reads, instead ???

We are waiting on your feedback.

Mr. Karwin,

Simply, what should our Manual describe as the primary use of the locking reads ?????

Thanks in advance.

I would describe the use of locking reads this way:

You can use locking reads to avoid race conditions, by serializing read or write access to rows that your session needs. You can implement pessimistic locking on a case by case basis, instead of using coarse solutions such as table locks.

Hi Mr. Karwin,

We fully agree with your description.

This report is now a verified Documentation bug.

Thank you for your contribution !