Bug #113411 Clarification on setting innodb_fast_shutdown during major version Upgrades
Submitted: 13 Dec 2023 20:20 Modified: 14 Dec 2023 4:51
Reporter: Mershad Irani Email Updates:
Status: Verified Impact on me:
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:8.0 OS:Any
Assigned to: CPU Architecture:Any

[13 Dec 2023 20:20] Mershad Irani
We have 3 docs that explain about shutdowns during upgrades. 

i. Upgrading MySQL Binary or Package-based Installations on Unix/Linux - https://dev.mysql.com/doc/refman/8.0/en/upgrade-binary-package.html

ii.  Preparing Your Installation for Upgrade - https://dev.mysql.com/doc/refman/8.0/en/upgrade-prerequisites.html

iii. Variable - sysvar_innodb_fast_shutdown - https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_fast_shutdown

From doc i. 
If you normally run your MySQL server configured with innodb_fast_shutdown set to 2 (cold shutdown), configure it to perform a fast or slow shutdown by executing either of these statements:

SET GLOBAL innodb_fast_shutdown = 1; -- fast shutdown
SET GLOBAL innodb_fast_shutdown = 0; -- slow shutdown
With a fast or slow shutdown, InnoDB leaves its undo logs and data files in a state that can be dealt with in case of file format differences between releases.

It does not specifically talk about doing slow shutdowns for major version upgrades to 8.0. 

From doc ii. 
If upgrade to MySQL 8.0 fails due to any of the issues outlined above, the server reverts all changes to the data directory. In this case, remove all redo log files and restart the MySQL 5.7 server on the existing data directory to address the errors. The redo log files (ib_logfile*) reside in the MySQL data directory by default. After the errors are fixed, perform a slow shutdown (by setting innodb_fast_shutdown=0) before attempting the upgrade again.

Again, the above does not mention  slow shutdown as a pre-requisite for major version upgrades. It instead mentions about setting the parameter if upgrade fails. 

From doc iii. 
Use the slow shutdown technique before upgrading or downgrading between MySQL major releases, so that all data files are fully prepared in case the upgrade process updates the file format.
So we have doc iii. clearly mentioning about using upgrades for slow shutdowns. However, there is no explicit mentions of them in docs i. or ii. 

Ask:  Clarify and have consistent messaging on all 3 docs mentioned above if innodb_fast_shutdown is a mandatory requirement for major version upgrades. 

How to repeat:
[13 Dec 2023 21:29] Mershad Irani
Just to be specific, "clarify and have consistent messaging on all 3 docs mentioned above if slow shutdown is a mandatory requirement for major version upgrades."
[14 Dec 2023 4:51] MySQL Verification Team
Hello Mershad,

Thank you for the report and feedback.