Saturday, July 13, 2013

Fun with Bugs #16 - read the fine MySQL 5.6 manual...

MySQL 5.6 has many new features and some of them change usual DBA procedures and formerly well known facts/limitations. It's important to have all these properly documented now, when MySQL 5.6 is GA for 6 months already and is supposed to be widely used in production. So, I think it's time to check what documentation problems still remain.

Here is the list of active bug reports in Server: Docs category for version 5.6, starting with recently reported:

  • Bug #69717 - "DML statements replicated via RBR are NOT logged in the general query log ". I had to report this while working on customer issue and trying to explain why there are no DML statements in slave's general query log. This feature was new in 5.1 and even somewhat documented at, but I'd prefer to see this explained at also. Moreover, in 5.6 we may be able to log somethings useful, as my colleague Justin Swanhart noted:
    On 5.6 perhaps the general log should log the query event associated with the RBR if it is available?
    So, it seems this is not only about the manual, but also about re-opening good old feature request, Bug #14722 for 5.6+.
  • Bug #69711 - "Explain what operations lead to specific "Waiting for... lock" states", is for 5.5+ actually, where metadata locks were introduced, but it makes sense to mention it in context of 5.6, as I do not want to see major 5.6 new features not entirely documented 2 years from now. This may happen, as the bug report proves, if we'll just keep silence. Use "Affects Me" button at least, please.
  • Bug #69697 - "Manual has not enough details on how to use transportable tablespaces" is a good example of what was missing in 5.6 manual on one of cool new features. It happened so that actual current content of that page, with detailed explanations, was pushed the day before I reported the bug, but was not yet visible. Anyway, explanation of  messages in the error log in the process of "importing" InnoDB tablespace is still missing. Also note that many documentation requests are satisfied almost immediately these days. Check my Bug #69701 for a great example of how it works (and what problems you may get while using transportable tablespace feature). So, keep reporting bugs, even if this is just about the missing phrase in the manual, and let Oracle engineers do their part of the job!
  •  If you upgrade to 5.6 after using 5.5 for a long time on Linux, note that mysql_install_db does NOT read /etc/my.cnf any more. Check Bug #68807 and Bug #69677 for the details and some consequences and workaround. Again, nice to see Oracle MySQL engineers still using public bug database, as in this case. I think for documentation requests it's a must - community should really know what is NOT properly documented yet. This hardly can lead to any security problems...
  • Bug #69630 - "MYSQL_FIELD structure has incorrect information". Even though the bug is still "Open" and may end up without any fix even in the manual, I still think it's a useful reading for people who use MYSQL_FIELD.charsetnr content in their code. Set your expectations according to the reality, please.
  • Bug #69490 - "Memory usage of P_S". I hope you already know that PERFORMANCE_SCHEMA is enables in MySQL 5.6.x by default and that you will have to pay for this with performance decrease (in some cases) and additional memory used (in all cases, like 170K per connection in max_connections, see details in the bug). I'd like to see the details shared by Marc Alff in Bug #68514 clearly mentioned in the manual. I hope I am not alone...
  • Bug #69199 - "STATS_SAMPLE_PAGES not documented in "CREATE TABLE" page". It's clear what is missing, so let's hope it will be fixed soon. Nice new feature that users may not be even aware about.
  • Bug #69135 - it seems that manual should still become more clear on what exactly one should do in MySQL 5.6 to make replication really crash safe.
  • Bug #68097 - "Manual does not explain that some P_S instruments must be enabled at startup". I've reported this almost 7 months ago, when 5.6.9 was released. But now at least there is some work in progress it seems. They say it is not trivial to document...
  • Bug #67023 - "EXPLAIN FORMAT=json output not documented". It would be really nice to see side-by-pside comparison of traditional output and output in JSON format. For me it is still not clear if (or what) additional information one may get from JSON format (and I tried to figure out with simple examples, really). As you can see some MySQL 5.6 documentation requests are not lucky and may hang around in "Verified" state for many months...
  • Bug #66397 - "Docs info on installing on Windows is not updated". Documentation now clearly describes that you get MySQL Installer from while downloading .msi, but I do not see information about two kinds of installers (check or that one may find good old .msi packages on FTP mirrors (not sure, had not checked for a long time). Time to add missing details and close this bug maybe?
  • The last but not the least, tow documentation requests related to new MRR optimizer feature are still just "Verified", since 2011! Check Bug #62676 and Bug #60864. Add to this the fact that default setting mrr=on led to one of few performance regressions in MySQL 5.6 (I had written about it here) and you'll understand my request to have it disabled by default for upcoming Percona Server 5.6 GA better (not that it's going to be satisfied, who knows...)
That's all, folks. Based on number of bug reports, MySQL 5.6 manual seems to be in good enough shape. Do you agree?

1 comment: