MySQL Bugs: #40616: "mysql_install_db" + "mysql_upgrade" need more documentation

Bug #40616	"mysql_install_db" + "mysql_upgrade" need more documentation
Submitted:	10 Nov 2008 14:54	Modified:	17 Nov 2008 18:05
Reporter:	Joerg Bruehe	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.0 and up	OS:	Any
Assigned to:	Paul DuBois	CPU Architecture:	Any

Description:
Documentation about "mysql_install_db" and "mysql_upgrade" should get some improvements:

1) Index entries are missing.

2) The split of tasks between the two programs isn't really obvious.

3) "mysql_upgrade" is also needed for downgrade actions.

=== Index entries:

For "mysql_install_db":
In 5.1, the only pointer is to "5.1/en/programs-overview.html" which lists the program but then refers to "5.1/en/unix-post-installation.html" and "5.1/en/mysql-install-db.html".
Especially the latter should be indexed directly.
(In 5.0, the situation is the same.)

For "mysql_upgrade", the index points to the "overview" but then has entries about the individual options which point to the section about "mysql_upgrade", that looks good.

=== Split of tasks

For tests, I installed 5.0.72 on a machine that had had 5.1.29, both as RPMs.
During the install of 5.0, I got an error message about table structure problems which I attributed to different structures in 5.1 and 5.0. It took me some searching to find that "mysql_upgrade" is the program to ruin, but no "mysql_install_db".

=== Downgrade

The section "5.0/en/downgrading.html" should get an addition that explicitly tells users to run "mysql_upgrade" to adapt the user table structure, even if they downgrade.
 

How to repeat:
Run smoke tests and collect the necessary info.

Suggested fix:
See description.

re: "1) Index entries are missing."

The index entries actually were present, but it turned out that the document preprocessing step was not passing through the primary entries for each program. Fixing ...

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.

re: "The section "5.0/en/downgrading.html" should get an addition that explicitly tells users
to run "mysql_upgrade" to adapt the user table structure, even if they downgrade."

This cannot be done in general. mysql_upgrade from the older version won't know about new features in the new version, and it cannot correct for them. The strategy of using mysqldump to dump before downgrading and reloading the dump file after downgrading should be used.

I also added some notes in the downgrading section to watch out for changes in the system tables that might require some adjustments.