MySQL Bugs: #64187: Unclear Documentation for some mysql variables

Bug #64187	Unclear Documentation for some mysql variables
Submitted:	1 Feb 2012 0:00	Modified:	9 Mar 2013 1:44
Reporter:	Simon Mudd (OCA)	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	All	OS:	Any
Assigned to:	John Russell	CPU Architecture:	Any
Tags:	windmill

Description:
Pages like http://dev.mysql.com/doc/refman/5.5/en/server-system-variables.html#sysvar_read_buffer_siz... mention read_buffer_size.

It appears that this variable is _only_ used by MyISAM engines yet this is not apparent in the documentation. So people who just read the documentation may set this to a large value expecting "better" behaviour. In this particular case this is a per-thread buffer so this larger setting gets magnified according to the number of running threads.

This may well affect other variables too.

I'm sure a lot of this is due to history and MyISAM being the main engine. That's changed now and InnoDB is the default engine in 5.5 and later so it's best if possible to avoid this sort of confusion.

How to repeat:
Read documentation.  Misconfigure the server due to misunderstanding how the settings are used.

Suggested fix:
Please revise configuration settings that may be used on only some engines and if the documentation does not specify this already ensure that it's clear that it's an engine specific setting.  If the setting is used by more than one engine (but not all) then specify this in some way.

Looks like you are right. At least my code review attempts led me to the same conclusions: values of read_buffer_size and read_rnd_buffer_size hardly matter at all for InnoDB tables (non-partitioned ones at least).

It's true that different engines employ this differently (or don't, in some cases), and that it has little or no bearing on InnoDB performance. We're still looking at how best to present this in the documentation.

I'm revisiting some doc bugs that got pushed down in priority due to 5.6 development work.

Still thinking how best to accomplish this goal. It seems like having a big list of server configuration options, then elsewhere a separate list of InnoDB configuration options, gives the impression that whatever in the first list is of primary importance and the InnoDB-specific ones are less relevant. Which is not really true with InnoDB being the default table type. Would it make sense to fold the InnoDB options into the main list on

http://dev.mysql.com/doc/refman/5.5/en/server-system-variables.html

? And/or to separate out MyISAM-specific options into a separate list?

Added details from Sinisa in support about the other engine-independent ways this variable is used. I'm closing the bug now because the rest of the suggestion, to clarify how each variable is or isn't intertwined with InnoDB, is an ongoing work item.