MySQL Bugs: #81343: variable documentation incorrect

Bug #81343	variable documentation incorrect
Submitted:	7 May 2016 2:11	Modified:	25 Jan 2018 13:36
Reporter:	Trey Raymond	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	lots	OS:	Any
Assigned to:		CPU Architecture:	Any

Description:
http://dev.mysql.com/doc/refman/5.6/en/replication-options-binary-log.html#sysvar_log_bin_...

Default	datadir + '/' + hostname + '-bin'

log_bin_basename is inherited from log_bin if an argument is passed in my.cnf.  however, the default (if no argument is passed) is actually inherited from the [trimmed] pid file name.  Here it is in the code:
https://github.com/mysql/mysql-server/blob/5.6/sql/mysqld.cc#L4787-L4815

Now, on to the pid file documentation:
http://dev.mysql.com/doc/refman/5.6/en/server-options.html#option_mysqld_pid-file
This claims no default, but the default is actually data_dir/$HOSTNAME.pid - that behavior is definitely desirable, but it should be documented.

How to repeat:
read docs.  this probably went undetected if test hosts left pid at defaults, and noticed lob_bin_basename inherited it, which would be the hostname.  but it caused hours of headaches on a host using non-default pid until I realized the doc was just wrong.  try it with my.cnf:

pid-file=/tmp/test.pid
log_bin
# no arg to log_bin

Suggested fix:
correct default for log_bin_basename to be inherited from pid-file instead of hostname
correct default for pid-file to be datadir/hostname.pid instead of nothing

Hello Trey Raymond,

Thank you for the report.

Thanks,
Umesh

Posted by developer:

Thanks for this report, which was passed over to me recently. This issue with the PID file came up when we were working on making binary logging the default for MySQL 8.0.3 (WL #10470). I didn't have time then to investigate what was going on with that in earlier releases, but I have spent some time on it now.

As you say, the binary log name was based on the PID file in 5.6, but documented as being based on the host name. log_bin_basename was introduced by WL #5465 System variables: paths to relay log and binary log files, and in the code it was based on the PID file name. I found that early in 5.7 the behavior was changed to match the documentation by Bug #11753843 / Bug #45359: BINARY AND RELAY LOG FILE NAMES DEPEND ON PID FILE NAME. So in 5.7 the binary log name is based on the host name. In 8.0 the usage of the --log-bin option has changed, and the new default binary log name is "binlog", but with a compatibility version based on the host name as in 5.7 if the --log-bin option is specified without a value.

I did not manage to find out why the documentation discrepancy occurred here. A comment by Eric Bergen in Bug #11753843 / Bug #45359 says he thinks the name dependency was changed from hostname to pid file name in 5.0.38. The 5.0.38 release notes have an item "Added the read-only hostname system variable, which the server sets at startup to the server host name", which might be connected to this. Unfortunately there was no reference number so I was unable to trace that in searches of the worklog archive and the trail went cold there.

The 5.6 documentation now reads as follows, or will soon when the builds update:

--log-bin
If you supply a value for the --log-bin option, the value is used as the base name for the log sequence. The server creates binary log files in sequence by adding a numeric suffix to the base name. In MySQL 5.6, the default base name is the name of the process ID file, with the suffix -bin. That name can be set with the --pid-file option, and it defaults to the name of the host machine. It is recommended that you specify a base name using the --log-bin option, so that you can continue to use the same binary log file names regardless of changes to the default name. The default location for binary log files is the data directory.

--log-bin-basename
Holds the base name and path for the binary log files, which can be set with the --log-bin server option. In MySQL 5.6, the default base name is the name of the process ID file, with the suffix -bin. That name can be set with the --pid-file option, and it defaults to the name of the host machine. The default location for the binary log files is the data directory.

pid_file and --pid-file
The path name of the process ID file. This variable can be set with the --pid-file option. The server creates the file in the data directory unless an absolute path name is given to specify a different directory. If you specify the --pid-file option, you must specify a value. If you do not specify the --pid-file option, MySQL uses a default value of host_name.pid, where host_name is the name of the host machine.

I also updated the 5.7 documentation to clarify the default there. Thanks again for pointing this out!