MySQL Bugs: #47293: conflicting incomplete and/or outdated information about configuration file

Bug #47293	conflicting incomplete and/or outdated information about configuration file
Submitted:	13 Sep 2009 12:28	Modified:	7 Jan 2010 0:58
Reporter:	Peter Laursen (Basic Quality Contributor)	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.x	OS:	Windows
Assigned to:	Paul DuBois	CPU Architecture:	Any
Tags:	qc

Description:
1)
output of 'mysqld --verbose -- help'
Default options are read from the following files in the given order:
C:\Windows\my.ini C:\Windows\my.cnf C:\my.ini C:\my.cnf C:\Program Files\MySQL\MySQL Server 5.1\my.ini C:\Program Files\MySQL\MySQL Server 5.1\my.cnf

2)
http://dev.mysql.com/doc/refman/5.1/en/windows-create-option-file.html
"When the MySQL server starts on Windows, it looks for options in two files: the my.ini file in the Windows directory, and the C:\my.cnf file."

If 1) is correct then 2) should list all the same.  Additionally 2) is only true if no defaults-file is specified.

How to repeat:
see above

Suggested fix:
Looks like developer(s) here forgot to communicate recent details to documentation team. Documentation page details were probably not updated since 4.0/early 4.1.

(Besides I think files in installation folder should be looked for first)

at least http://dev.mysql.com/doc/refman/5.1/en/option-files.html seems current :)

hmmm .. http://dev.mysql.com/doc/refman/5.1/en/option-files.html is not perfect either!

"Because the “\\” escape sequence represents a single backslash, you must write each “\” as “\\”. Alternatively, you can specify the value using “/” rather than “\” as the path name separator."

datadir="C:\ProgramData\MySQL\MySQL Server 5.1\Data" works perfectly in my.ini without escaping \ to \\ (but also / does instead of \).  Maybe because of the "quotes" - but you would always to "quote" a file path with a Windows drive: specification with a COLON (or a file path with a SPACE-character) on Windows.

Actually I have had erroneous replies about such need of escaping here before ('documentation lists that .. blahblah ...'). I gave up discussing with the guy as he was not interested in trying it for himself.

But the first page I found and linked to looks both redundant and very outdated.

Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.

Changed http://dev.mysql.com/doc/refman/5.1/en/windows-create-option-file.html to contain a cross reference to the section where all locations are listed:

When the MySQL server starts on Windows, it looks for option files in several locations, such as the Windows directory, C:\, and the MySQL installation directory (for the full list of locations, see Section 4.2.3.3, “Using Option Files”). The Windows directory typically is named something like C:\WINDOWS. You can determine its exact location from the value of the WINDIR environment variable using the following command:

C:\> echo %WINDIR%
MySQL looks for options in each location first in the my.ini file, and then in the my.cnf file.

Regarding escaping in Windows path names, I dug into this with Iggy Galarza's help. Turns out you need to double the backslash only if it'd be followed by a character that would form a valid escape sequence. I've updated http://dev.mysql.com/doc/refman/5.1/en/option-files.html to list the rules like this:

You can use the escape sequences "\b", "\t", "\n", "\r", "\\", and
"\s" in option values to represent the backspace, tab, newline,
carriage return, backslash, and space characters. The escaping rules
in option files are:

* If a backslash is followed by a valid escape sequence character, the
sequence is converted to the character represented by the sequence.
For example, "\s" is converted to a space.

* If a backslash is not followed by a valid escape sequence character,
it remains unchanged. For example, "\S" is retained as is.

The preceding rules mean that a literal backslash can be given as
"\\", or as "\" if it is not followed by a valid escape sequence
character.

The rules for escape sequences in option files differ slightly from
the rules for escape sequences in string literals in SQL statements.
In the latter context, if "x" is not a value escape sequence
character, "\x" becomes "x" rather than "\x".

Windows path name separators path name separators Windows The
escaping rules for option file values are especially pertinent for
Windows path names, which use "\" as a path name separator. A
separator in a Windows path name must be written as "\\" if it is
followed by an escape sequence character. It can be written as "\\"
or "\" if it is not. Alternatively, "\" may be used in Windows path
names and will be treated as "/". Suppose that you want to specify
a base directory of C:\Program Files\MySQL\MySQL Server 5.1 in an
option file. This can be done several ways. Some examples:

basedir="C:\Program Files\MySQL\MySQL Server 5.1"
basedir="C:\\Program Files\\MySQL\\MySQL Server 5.1"
basedir="C:/Program Files/MySQL/MySQL Server 5.1"
basedir=C:\\Program\sFiles\\MySQL\\MySQL\sServer\s5.1

@Paul ..

isn't it much more simple? 
\-character can be used on Windows for specifying a file path it the "file path" is "double quoted"?

I am not sure .. I am asking.  But on Windows everybody would "double quote" a file path with a COLON or a SPACE. Everybody using cmd.exe frequently does per reflex.

I am afraid that nobody will understand your update to http://dev.mysql.com/doc/refman/5.1/en/option-files.html .  Can I enter "c[COLON]\blah\blih\bloh[SPACE)bluh" *without* "double qoutes" in the configuration file on Windows?

Peter,

1) Do you see anything in the update about quote characters affecting escape sequences? No, because quotes don't matter.

2) cmd.exe behavior is not relevant to the issue.

There is a small error in the following statement:

"Alternatively, “\” may be used in Windows path names and will be treated as “/”."

Should be:

"Alternatively, “/” may be used in Windows path names and will be treated as “\”."

As per the example:

basedir="C:/Program Files/MySQL/MySQL Server 5.1"

"/" is used, and it is treated as "\".

Also, in regards the usage or non usage of quotes, based on testing I agree it does not matter whether they are specified or not.

However, it would be good to clarify this in the manual as well. (something like "On Windows, double quotes (") are not required around path names in configuration files, even for path names containing spaces. Specifying them makes no difference however.") - especially since this would be a confusing point for Windows users.

(Bug in similar topic area at bug #50021)

Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.

Fixed the "Alternatively" sentence.

Changed:

opt_name=value

This is equivalent to --opt_name=value on the command line. In an option file, you can have spaces around the “=” character, something that is not true on the command line. You can enclose the value within single quotes or double quotes, which is useful if the value contains a “#” comment character or whitespace.

To:

opt_name=value

This is equivalent to --opt_name=value on the command line. In an option file, you can have spaces around the “=” character, something that is not true on the command line. You can optionally enclose the value within single quotes or double quotes, which is useful if the value contains a “#” comment character.