Bug #101216 Suggestions for improved documentation for 13.4.2.1 CHANGE MASTER TO command
Submitted: 17 Oct 2020 9:18 Modified: 17 Feb 2022 19:44
Reporter: Simon Mudd (OCA) Email Updates:
Status: Closed 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
[17 Feb 2022 19:44] Margaret Fisher
Posted by developer:
 
Thanks very much for these suggestions! I started the work in parallel with the terminology changes, and have now completed it. I hope you find the restructured documentation easier to use.

Specific responses to your points -

1. I put the defaults for the parameters into the descriptions themselves, and did the same with the table of value lengths. I feel this is clearest since users need this information when they go to enter the parameter, and will not necessarily know there is a separate table. I have also added the possible values from the syntax diagram to the parameter names in the text.

2. The options are now in alphabetical order with a description associated with each.

3. The examples are in a section at the end, and I have added an example showing GTID auto-positioning and the use of FOR CHANNEL, plus links to more complex procedures where the statement is used - failover, GTID implementation, multi-source replication setup, and skipping transactions.

4. Following the terminology change I doubt that the development team would be keen to introduce further aliases, but you can always submit a code enhancement request if this is important. I think now that the description of the option is easier to pick out, it should not take long to understand.

5. I have moved the channel material to a more prominent place and added what the default name is. There is a link to the concept documentation for channels and (in the examples) the setup documentation, plus an example with a channel name.

6. SOURCE_CONNECTION_AUTO_FAILOVER is really primarily intended as an underpinning for InnoDB ClusterSet. It is possible to set it up by hand, and we have documented this in the section linked from the parameter description. Its use is not required, and I don't think we need to cover the error cases here - we can assume that if users do set it up by hand they will read all the instructions rather than experimenting on the basis of this statement documentation.  To help with that I've moved the reference to the full docs near the start of the option.