MySQL Bugs: #31138: Option & Variable Reference errors

Bug #31138	Option & Variable Reference errors
Submitted:	21 Sep 2007 18:52	Modified:	14 Dec 2007 16:39
Reporter:	Baron Schwartz (Basic Quality Contributor)	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:		OS:	Any
Assigned to:	MC Brown	CPU Architecture:	Any

Description:
I use the option and variable reference so frequently that I thought it would be good to write a script to test its accuracy against any given MySQL version.  I found a lot of discrepancies.  I'll attach the script -- basically what it does is check the documentation for accuracy in existence, scope and dynamism of system variables.

It doesn't check the scope of SHOW STATUS, but it does check some other things about SHOW STATUS.  (I couldn't think of a way to check scope.  Maybe there's a way).

How to repeat:
Here's the output against the pre-installed server on my Ubuntu laptop.  It only prints things that don't look accurate, so the following is a list of possible problems:

Testing table for 5.0 against MySQL 5.0.38Undocumented system variable have_ssl
Undocumented system variable large_page_size
Undocumented system variable myisam_recover_options
Undocumented system variable pid_file
Undocumented status variable Com_show_innodb_status
Undocumented status variable Com_show_logs
Undocumented status variable Com_show_ndb_status
Undocumented status variable Prepared_stmt_count
Undocumented status variable Ssl_accept_renegotiates
Undocumented status variable Ssl_accepts
Undocumented status variable Ssl_callback_cache_hits
Undocumented status variable Ssl_cipher
Undocumented status variable Ssl_cipher_list
Undocumented status variable Ssl_client_connects
Undocumented status variable Ssl_connect_renegotiates
Undocumented status variable Ssl_ctx_verify_depth
Undocumented status variable Ssl_ctx_verify_mode
Undocumented status variable Ssl_default_timeout
Undocumented status variable Ssl_finished_accepts
Undocumented status variable Ssl_finished_connects
Undocumented status variable Ssl_session_cache_hits
Undocumented status variable Ssl_session_cache_misses
Undocumented status variable Ssl_session_cache_mode
Undocumented status variable Ssl_session_cache_overflows
Undocumented status variable Ssl_session_cache_size
Undocumented status variable Ssl_session_cache_timeouts
Undocumented status variable Ssl_sessions_reused
Undocumented status variable Ssl_used_session_cache_entries
Undocumented status variable Ssl_verify_depth
Undocumented status variable Ssl_verify_mode
Undocumented status variable Ssl_version
No such status variable Com_alter_event
No such status variable Com_backup
No such status variable Com_call_procedure
No such status variable Com_create_event
No such status variable Com_drop_event
No such status variable Com_restore
No such status variable Com_show_create_event
No such status variable Com_show_engine_logs
No such status variable Com_show_engine_mutex
No such status variable Com_show_engine_status
No such status variable Com_show_events
No such status variable Com_show_plugins
System variable Master_Log_File is not a global variable
System variable Master_Log_File is not a session variable
No such system variable Master_Log_File
System variable Master_SSL_Allowed is not a global variable
System variable Master_SSL_Allowed is not a session variable
No such system variable Master_SSL_Allowed
System variable Master_SSL_CA_File is not a global variable
System variable Master_SSL_CA_File is not a session variable
No such system variable Master_SSL_CA_File

... (too many lines -- I'll attach the results).

Results on my laptop

Attachment: results (application/octet-stream, text), 36.65 KiB.

Script to test the option tables against some MySQL server

Attachment: test-option-tables.pl (application/x-perl, text), 8.28 KiB.

I realized I forgot to say what I'm testing.  It's this manual page:

http://dev.mysql.com/doc/refman/5.0/en/mysqld-option-tables.html

(PS: If I could make a request -- repeating the table headers every 30 rows would be helpful.  Don't know if that's easy to do).

Thank you for the bug report.

There are some problems here. For example, Com_alter_event, Com_create_event, and Com_drop_event are defined in 5.1, but not before (the Event Scheduler was implemented in 5.1.6).

Sure.  But if you run the script against a 5.1 server, it will download the 5.1 version of the manual page, and it won't complain about that.  It's complaining because the 5.0 manual page mentions those values.

Hi Baron, that was exactly my point. :)

Baron,

We did have an issue yesterday where the table was being output incorrectly - that is, we output a table that included all options/variables for all versions even though it only appeared in the 5.0 manual. 

That doesn't mean you don't have a valid point on some entries (In fact, quite the opposite, I think you have a very valid point!), but certainly some of the errors reported here will be addressed by us just outputting the correct version of the table. 

I'll re-run your script and check the results across different versions so I can determine the problems that ned to be addressed.

You know, I wonder if the easiest thing to do would be add another column containing the version(s) in which the item first appeared, and then output the same table for all manual versions.  I don't know if that's something you'd want to do, but it seems like it would make things a lot easier, and it would be very helpful when reading the table.  I can update the script to respect this column if you wish, so there'll still be an easy way to test the table.

I think we'd like to keep the version-specific information in the corresponding manual version. The table itself is generated from a different resource (we are not manually updating the table), so including a version specific of the table is not an issue. Unless, as in this instance, there was a bug which made the wrong table information be output. 

We have a version of the table that covers all versions of the server and includes introduced and deprecated information and links to the corresponding manual in which you can find a more detailed description. That will be a separate standalone document to be used as a kind of 'cheat sheet'.

I noticed this script actually messes up the server's configuration by doing SET @@var := @@var, which apparently loses some fidelity.  I advise not to run the attached script against a server you care about.  Details are at bug #31177.

We have addressed a huge list of issues related to the problems raised in this bug report (many of which we knew already). 

This should have fixed issues, even on a version by version basis, as we now compare the current information with discovered information on a release automatically. 

There may still be minor cases, in which case, please feel free to report another bug.