MySQL Bugs: #34599: MySQLD Option and Variable Reference need to be consistent in formatting!

Bug #34599	MySQLD Option and Variable Reference need to be consistent in formatting!
Submitted:	15 Feb 2008 16:14	Modified:	16 May 2010 20:47
Reporter:	Jonathan Miller	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server	Severity:	S3 (Non-critical)
Version:	5.1	OS:	Any
Assigned to:		CPU Architecture:	Any

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

Please take a moment to review the above link ^.

You will notice that there is many different variations in variable formatting. Not being consistent in naming conventions for server variables make us look like we are not ready for enterprise. 

I feel that we should come up with a standard and that all server related options should be corrected to follow that standard.

There is issue with backwards computability, therefore, if this is implemented efforts to ensure that upgrade customer will not be affected will need to be taken.

Examples:

Aborted_clients
abort-slave-event-count
bulk_insert_buffer_size

   

How to repeat:
N/A see above

Suggested fix:
all variables follow one standard

1) either all uppercase or all lowercase, but should not be both or a mix
2) either all dashes or all underlined, but should not be both or a mix

 

examples

VAR-NAME-OPT
VAR_NAME_OPT
var-name-opt
var_name_opt

documentation issue.
command line options (like --abort-slave-event-count) use lowercase, dashes.
server variables (like bulk_insert_buffer_size, accessible as @@var_name) use lowercase, underscore.
status variables (visible in SHOW STATUS) use first letter uppercase, underscore.

The manual puts them all in one table, which create that inconsistent look you're complaining about.

I must beg to differe: There *are* server options that use underscores, e.g. it's --ndb_autoincrement_prefetch_sz and not --ndb-autoincrement-prefetch-sz (which really ought to be "--ndb-autoincrement-prefetch-size" as there's no reason to abbreviate a 4-letter word).

In addition, there are some settings which can be made via a command-line option but not as a server variable, and some which can be set as a server variable but not as a command-line option, and in many cases, there appears to be no rhyme or reason for this, other than "That's just the way it is".

These are not documentation issues.

Additional issues:

In cases where a setting can be made as either a command-line option or a server variable, which of these should be the canonical form that appears in the docs?

We're aware of the conventions, but (a) these are not always followed in the server; and (b) when we suggest putting these in the docs, people complain that it's too difficult to remember them without being told explicitly (e.g.) "the mysqld option is '--auto-increment-offset' but the server variable is 'auto_increment_offset'". Seriously!

Finally, I'd like to point out that, in the latest 6.0, there are 288 status variables, 308 system variables, and $__DEITY__ knows how many server options. It's about time that we started supporting some kind of namespaces for all of these.

cheers

jon.

it's --ndb-autoincrement-prefetch-sz as far as I can see:

% mysqld --help|grep t-prefetch
  --ndb-autoincrement-prefetch-sz=# 
ndb-autoincrement-prefetch-sz     1

Although, indeed, I'd prefer mysqld --help to print all option names with dashes
(auto-converting them in my_print_help and my_print_variables). I'll submit a separate feature request about it, let's keep this one what it was, about http://dev.mysql.com/doc/refman/5.1/en/mysqld-option-tables.html

bug#34635

Jeb: Setting this to !Bg because, as Serg pointed out, the table you're referring to just *looks* inconsistent while it apparently isn't. If you still feel we (Docs) should do anything about it, please explicitly say what we should do (e.g. split the table into multiple ones), and change this bug to a feature request.

There are also a number of InnoDB *options* that use underscores in the names, which you can confirm by inspection of the option structure in sql/mysqld.cc or by running mysqld --verbose --help.

That too is inconsistent with the general convention that dashes are used in option names. The documentation can't be consistent if it is to follow the server's help text and that help text isn't consistent.

paul: it's a part of bug#34635

Work log open for this issue

https://intranet.mysql.com/worklog/Server-Sprint/?tid=4277

will be fixed in WL#4738

Pushed into 5.5.3-m3 (revid:alik@sun.com-20100306103849-hha31z2enhh7jwt3) (version source revid:vvaintroub@fedora12-20091225154921-x25a5pyw1pxiwobv) (merge vers: 5.5.99) (pib:16)

After thinking about this report for some time, it's not clear to me that a lot can be done. The table needs to have names in some column, and the items in that column cannot be all the same time:

* There are command-line options that have no corresponding system variable, so the item named must be the option.

* There are system variables that have no corresponding command-line option, so the item named must be the variable.

* Status variables do not correspond to command-line options, so the item named must be the variable.

System and status variable names always use underscores. We are consistent about this.

Option names normally use dashes; a few use underscores. They can be specified either way at server startup; the server understands dash and underscore the same way in options. This is a *display* inconsistency that we can address and I will change the table to use dashes in option names consistently.

Other than that, I am not sure what other changes can be made here.

See changelog entry regarding processing of system variables and command-line options at:

http://dev.mysql.com/doc/refman/5.5/en/news-5-5-3.html