MySQL Bugs: #71005: Documentation needs clarification on upgrading replication setups

Bug #71005	Documentation needs clarification on upgrading replication setups
Submitted:	25 Nov 2013 21:35	Modified:	1 Mar 2022 22:26
Reporter:	James Lucas	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.5+	OS:	Any
Assigned to:		CPU Architecture:	Any
Tags:	documentation, mysql_upgrade, replication

Description:
Section 16.4.3. Upgrading a Replication Setup of the MySQL 5.5 Reference Manual needs further clarification on the process of upgrading replication setups. Specifically, the documentation currently makes no mention of how to handle running mysql_upgrade in a replication environment. In fact, the use of mysql_upgrade is not discussed at all in this section.

How to repeat:
The specific issue I am facing is that I am trying to upgrade a master/slave pair from MySQL 5.5.25a to 5.5.34. The documentation as written is unclear, but seems to imply that master and slave databases should be upgraded completely independently, and that bin log generation must be halted on the master during the process. In this scenario I would need to break replication and run mysql_upgrade on master and slave independently, then restart bin log generation on the master and log apply on the slave.

I have seen other sources that suggest simply performing upgrades of the MySQL binaries on master and slave, and then running mysql_upgrade against the master. Any structure changes would then replicate to the slave. This seems to be a much simpler solution and may be adequate for the common upgrade scenario. Unfortunately the documentation provides no guidance on this subject, either for or against.

Suggested fix:
I'd like to request that section 16.4.3 be examined and clarified with regard to upgrade procedures and what is appropriate in various upgrade scenarios.

Note that other versions of the MySQL Reference Manual are also impacted.

Replication -> mine.

Just wanted to note that I opened an SR with Oracle Support, and was told the proper high level upgrade procedure in my situation would be

<shutdown slave>
<upgrade slave binaries>
<startup slave>
mysql_upgrade -u root -p --skip-write-binlog <on slave>

<shutdown master>
<upgrade master binaries>
<startup master>
mysql_upgrade -u root -p --skip-write-binlog <on master>

Posted by developer:
 
I am going through documentation bugs that have been on the back burner for a while. Thank you for the suggestion and apologies for the delay! I have updated the replication upgrade topics to reorganize them and add the procedure here:

https://dev.mysql.com/doc/refman/5.7/en/replication-upgrade.html
https://dev.mysql.com/doc/refman/8.0/en/replication-upgrade.html

Thanks for helping us improve the documentation!