Bug #80351 Relocation of mysql_install_db is NOT explicitly listed as Incompatible change

• Submitted: 12 Feb 2016 8:40
• Modified: 12 Feb 2016 14:14
• Reporter: Valeriy Kravchuk
• Status: Closed
• Category: MySQL Server: Documentation
• Severity: S3 (Non-critical)
• Version: 5.7.5+
• OS: Any
• CPU Architecture: Any
• Tags: missing manual, mysql_install_db

[12 Feb 2016 8:40] Valeriy Kravchuk

Description:
There is a page in the manual titled "2.11.1.1 Changes Affecting Upgrades to MySQL 5.7", https://dev.mysql.com/doc/refman/5.7/en/upgrading-from-previous-series.html. It says:

"Changes marked as either Known issue or Incompatible change are incompatibilities with earlier versions of MySQL, and may require your attention before you upgrade. Our aim is to avoid these changes, but occasionally they are necessary to correct problems that would be worse than an incompatibility between releases."

Unfortunately the page does NOT list the fact that mysql_install_db is now installed into bin/ subdirectory and scripts/ subdirectory where it was located previously just does not exist any more.

As a side note, I wonder what problem worse than incompatibility was corrected by moving mysql_install_db to bin/ instead of scripts/?

How to repeat:
Let's assume I am a developer who wants to install MySQL database in the process of doing something in my software, and I try to upgrade my software to use MySQL 5.7 GA instead (or in addition to) MySQL 5.6 GA. I read this page to make sure all incompatibilities as of current version (5.7.11 at the moment) are listed in this page. But then I hit something like Bug #80346, as my tools expect to find mysql_install_db binary in scripts/ subdirectory, while it is now in bin/.

Suggested fix:
Please, document the relocation of mysql_install_db explicitly on this manual page as an Incompatible change (if there is no plan to fix Bug #80346). Relying on checking each and every release mentioned at https://dev.mysql.com/doc/relnotes/mysql/5.7/en/ is a bad idea. Hardly every user reads release notes for every intermediate version, especially those before GA.

[12 Feb 2016 14:14] Paul DuBois

Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly.

Added the following item to http://dev.mysql.com/doc/refman/5.7/en/upgrading-from-previous-series.html:

Incompatible change: In MySQL 5.7.5, the executable binary version of
mysql_install_db is located in the bin installation directory,
whereas the Perl version is located in the scripts installation
directory. For upgrades from an older version of MySQL, you may find
a version in both directories. To avoid confusion, remove the version
in the scripts directory. Applications that expect to find
mysql_install_db in the scripts directory should be updated to look
in the bin directory instead.
          
The location of mysql_install_db becomes less material as of MySQL
5.7.6 because as of that version it is deprecated in favor of mysqld
--initialize (or mysqld --initialize-insecure).