Bug #56768 Miscellaneous clarifications in replication documentation
Submitted: 14 Sep 2010 9:58 Modified: 22 Jan 2014 17:12
Reporter: Sven Sandberg Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S2 (Serious)
Version: OS:Any
Assigned to: Jon Stephens CPU Architecture:Any

[14 Sep 2010 9:58] Sven Sandberg
Description:
Some requests for clarification:

1. The variable sql_log_bin should be listed at
http://dev.mysql.com/doc/refman/5.6/en/replication-options-table.html
and
http://dev.mysql.com/doc/refman/5.6/en/replication-options-master.html

2. At http://dev.mysql.com/doc/refman/5.6/en/show-slave-status.html , clarify that Replicate_Ignore_Server_Ids filtering is done by the IO thread, not the SQL thread. So the filtered-out events are not even written to the relay log (this is in contrast with other filters, like --replicate-do-*, which apply to the SQL thread)

3. Documentation for SHOW MASTER HOSTS generally does not make sufficiently clear what server it is talking about:

3.1 "Displays a list of replication slaves currently registered with the
    master. The list is displayed on any server (not just the master
    server)."
    The list is displayed in a client, and nothing else :-) What
    we need to say is that SHOW MASTER HOSTS should be executed on a
    server that acts like a replication master, and it displays
    information about servers that are or have been connected as
    replication slaves. Each row of the result set corresponds to one
    slave server.

3.2 "Server_id: The unique server ID of the slave server, as configured
    in the server's option file," 
    The server ID is configured in *that slave server's* option file.

3.3 "Host: The host name of the slave server, as configured in the
    server's option file,"
    Same here: the host name is configured in *that slave server's*
    option file.

3.4 "Port: The port the slave server is listening on."
    Can maybe be clarified as "Port: The port on this master server
    that the slave server is listening on."

3.5 "Master_id: The unique server ID of the master server that the
    slave server is replicating from."
    This is very confusing, but that's mostly because the server is
    doing something very strange. I don't know why it displays its own
    server_id here, this is obviously misplaced. The server_id is
    accessible as a variable, and in SHOW SLAVE HOSTS it gets
    duplicated for each row in the result set.
    So we can perhaps clarify that this is the server ID of the server
    on which "SHOW SLAVE HOSTS" is executed, hence the same value is
    listed for all rows on the result set.

4. SHOW MASTER HOSTS should probably be listed at either
http://dev.mysql.com/doc/refman/5.6/en/replication-slave-sql.html or
http://dev.mysql.com/doc/refman/5.6/en/replication-master-sql.html,
depending on what the statement does.

5. Each of slave-net-timeout, slave-load-tmpdir, and slave-skip-errors is
documented twice on
http://dev.mysql.com/doc/refman/5.6/en/replication-options-slave.html
Can we remove the duplicates?

6. The command line option for slave_compressed_protocol is documented
twice at
http://dev.mysql.com/doc/refman/5.6/en/replication-options-slave.html
: first under the name --slave_compressed_protocol and then under the
name --slave-compressed-protocol. Please remove the duplicate and determine
if the option has dashes or underscores.

7. The --master-bind option is not documented. It is listed both at
http://dev.mysql.com/doc/refman/5.6/en/replication-options-table.html
and at
http://dev.mysql.com/doc/refman/5.6/en/server-system-variables.html
. In both these places, it links to
http://dev.mysql.com/doc/refman/5.6/en/replication-options.html where
the option does not appear. See the documentation for CHANGE MASTER TO MASTER_BIND.

How to repeat:
-
[14 Sep 2010 11:14] MySQL Verification Team
Thank you for the bug report.
[14 Sep 2010 11:25] Sven Sandberg
8. After WL#5177, there is one new field in SHOW SLAVE HOSTS that is still undocumented. The output of SHOW SLAVE HOSTS looks like this:

SHOW SLAVE HOSTS;
Server_id	2
Host	127.0.0.1
Port	10601
Master_id	1
Slave_UUID	78ddce60-bff2-11df-912f-001b388c6832

The field Slave_UUID contains the UUID of the slave.
[16 Sep 2010 9:49] Sven Sandberg
I misspelt SHOW SLAVE HOSTS as SHOW MASTER HOSTS in several places above. Also, I don't know why I reported item 4: SHOW SLAVE HOSTS exists at http://dev.mysql.com/doc/refman/5.6/en/replication-master-sql.html , in all versions of the manual, so please ignore that :-)
[22 Jan 2014 17:12] Jon Stephens
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 in mysqldoc rev 37470, 37473.

Closed.