Bug #101216 Suggestions for improved documentation for 13.4.2.1 CHANGE MASTER TO command
Submitted: 17 Oct 2020 9:18 Modified: 18 Oct 2020 5:54
Reporter: Simon Mudd (OCA) Email Updates:
Status: Verified Impact on me:
None 
Category:MySQL Server: Documentation Severity:S4 (Feature request)
Version:8.0.21 OS:Any
Assigned to: CPU Architecture:Any
Tags: change_master_to, defaults, firsts_version, MASTER_CONNECT_RETRY, master_retry_count

[17 Oct 2020 9:18] Simon Mudd
Description:
https://dev.mysql.com/doc/refman/8.0/en/change-master-to.html documents the change master to command.

This command has evolved over time and has many more options than it used to have a few major versions ago. Changes in 8.0 minor releases have also introduced new settings.

Making the command easy to read, and making it easy to find the required information becomes more important for people who may not use this command frequently.

How to repeat:
read the URL provided in Description.

Suggested fix:
Suggested changes are:

1. Ensure that the default values for all parameters are provided

The syntax is provided, but to find the default values you need to read
through all the text looking for the specific value's setting.
It would be easier to have a table with the parameter and its default
setting to make such lookups easier and the text providing these values
in a descriptive manner can be removed.

This table would also provide a location to add when each setting became
available as there are multiple new settings in 8.0 in different minor
releases.

2. List the different options in alphabetical order

While the order you might use when using the CHANGE MASTER command may
not be using the options in alphabetical order it makes looking up the
details of each specific command easier.

3. Add the examples of usage at the end.

The few examples given show "old style" FILE / POSITION settings whereas
currently the recommended practice is to use GTIDs with auto-positioning.

So please provide sample settings using auto-positioning especially as this
is not the DEFAULT option yet.

4. Names

It is probably too late to change the names but they are important
and some of the names used are really not ideal.

Please consider changing:

MASTER_RETRY_COUNT to MASTER_RETRY_LIMIT / MASTER_RETRY_MAX

A count sounds like a metric value, whereas this setting is the limit on the number of retries that will be attempted. The name does not match the usage.

MASTER_CONNECT_RETRY to MASTER_CONNECT_RETRY_INTERVAL

"RETRY" might be understood to mean "do I retry?" "how many retry attempts can I make?". It does not look like an interval between retries so adding something like _INTERVAL would make the meaning clearer.

Allowing the current name but deprecating it would be good.  They are pretty new so most people will not be using them and in "9.0" you could remove the old/current names completely.

5. Channel names.

Most asynchronous replication does not make use of channel names, and it's not clear what the default channel name is.  Most of the newer examples use channel names but for most usages this is probably never used. So if you use a channel name explain under what circumstances this would be and provide examples both not using and using channel names.

Some of these descriptions may be more appropriate in another part of the manual. If that is the case then document elsewhere and refer to the appropriate documentation.

6. Use of alternative replication source servers. (SOURCE_CONNECTION_AUTO_FAILOVER)

This new functionality is really interesting, yet there are no examples of how one  might use this in practice. It might be better to have this in a separate section of the documentation and refer to that.

What's missing is:
* setting SOURCE_CONNECTION_AUTO_FAILOVER = 1 requires use of the metadata configured via asynchronous_connection_failover_add_source(). What happens if that is missing? This is not explicitly defined.
* you require MASTER_AUTO_POSITION = 1 but does can you set the value if MASTER_AUTO_POSITION = 0 ? Again not clear and if you can this is likely to break things so perhaps it should not be possible.

The use of asynchronous_connection_failover_add_source() and asynchronous_connection_failover_delete_source() is surprising as you provide a new configuration mechanism which users have to adapt to.
[17 Oct 2020 9:19] Simon Mudd
As asking for documentation to be improved changed to feature request. I am sure the current documentation is correct.
[17 Oct 2020 10:10] Simon Mudd
Related to: https://bugs.mysql.com/bug.php?id=101217
[17 Oct 2020 11:36] Simon Mudd
Related: https://bugs.mysql.com/bug.php?id=101218
[18 Oct 2020 5:54] MySQL Verification Team
Hello Simon,

Thank you for the documentation enhancement request.

regards,
Umesh