Bug #67409 Inconsistent Documentation & use of nouns
Submitted: 29 Oct 2012 11:47 Modified: 29 Dec 2012 0:25
Reporter: Clint Priest Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S2 (Serious)
Version:5.5 OS:Linux
Assigned to: John Russell CPU Architecture:Any
Tags: deadlock, innodb, lock_wait_timeout, statements, transactions

[29 Oct 2012 11:47] Clint Priest
Description:
There are documentation inconsistencies within the manual that has lead to some serious problems on our end until we found out the truth of the matter...

This page: http://dev.mysql.com/doc/refman/5.5/en/innodb-error-handling.html
Specifically states:
* that a deadlock rolls back the entire transaction
* that a lock wait timeout rolls back just the statement

That page also links to:
http://dev.mysql.com/doc/refman/5.5/en/innodb-error-codes.html

Which indicates for LOCK_WAIT_TIMEOUT that the transaction was rolled back, which contradicts the previous page.  

It also says for ER_LOCK_DEADLOCK "Transaction Deadlock. Rerun the transaction"

I think the documentation needs to be consistent and also the error definitions be more precise.  For example the LOCK_WAIT_TIMEOUT should read something like "Lock wait timeout expired, statement was rolled back."  Statement being the key change here, not "transaction" because that implies that in a multiple query transaction the entire transaction has been rolled back.

Also, the LOCK_DEADLOCK should be made more explicit, again repeating that the entire transaction was rolled back and needs to be re-run.

How to repeat:
n/a

Suggested fix:
update the documentation to be more explicit and use nouns that make more sense.  I know this is muddied by the fact that in auto_commit=1 mode, 1 transaction = 1 statement.
[29 Oct 2012 13:27] MySQL Verification Team
Thank you for the bug report.
[29 Oct 2012 18:00] Stefan Hinz
There's nothing we (Docs) can do about server error messages, but the doc part can be addressed.
[29 Oct 2012 18:07] Clint Priest
Sounds good... I take it the error messages are embedded w/i the various code libraries in use?
[29 Dec 2012 0:25] John Russell
Enhanced the descriptions for the deadlock and lock wait error codes to be more explicit about whether transaction or statement was being rolled back. Also added some more explanation and links to glossary definitions and related troubleshooting information.