Bug #44083 Various Replication Documentation Errors
Submitted: 3 Apr 2009 20:01 Modified: 14 Aug 2009 3:47
Reporter: Donna Harmon Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.1 OS:Any
Assigned to: Paul DuBois CPU Architecture:Any

[3 Apr 2009 20:01] Donna Harmon
Description:
1) http://dev.mysql.com/doc/refman/5.1/en/replication-howto-mysqldump.html
There is no statement saying to unlock tables after doing the dump such as there is on this page #3 at bottom http://dev.mysql.com/doc/refman/5.1/en/replication-howto-rawdata.html ( 1a) #2 towards bottom of page s/b Make not Take)  
Should add as 4th bullet on replication-howto-mysqldump.html:
* In the client where you acquired the read lock, free the lock:

mysql> UNLOCK TABLES;

2) http://dev.mysql.com/doc/refman/5.1/en/replication-options-slave.html
In "Important" Section, "Options Deprecated" paragraph it says "Beginning with MySQL 5.2.5" should this be 5.1.5? or 5.1.25?  5.2.5 is mentioned numerous times on this page

"Another importance difference" s/b "Another important difference"

3) http://dev.mysql.com/doc/refman/5.1/en/replication-options-binary-log.html
"at at runtime" s/b "at runtime"

It is recommended that you specify a basename (see Section B.1.8.1, “Open Issues in MySQL”, for the reason).  (I can't find the reason, perhaps link directly to the related bug)

4) http://dev.mysql.com/doc/refman/5.1/en/mysql-ssl-set.html
mysql_ssl_set() does nothing unless OpenSSL support is enabled in the client library.  (THIS should perhaps say "unless yaSSL or OpenSSL is enabled in the client" since both are supported?)

5) http://dev.mysql.com/doc/refman/5.1/en/replication-features-invoked.html
says in the Note:
"In a future MySQL release, we may implement ways for users to indicate that such features are deterministic, so that they can be recognized by the server as “safe” for statement-based replication. (Bug#34597) " (Maybe this note can be changed to say "with the exception of CREATE PROCEDURE which has already implemented this feature")?

According to the following documentation you can specify DETERMINISTIC:
http://dev.mysql.com/doc/refman/5.1/en/stored-programs-logging.html
"When you create a stored function, you must declare either that it is deterministic or that it does not modify data. Otherwise, it may be unsafe for data recovery or replication. "
http://dev.mysql.com/doc/refman/5.1/en/create-procedure.html - mentions DETERMINISTIC option

6) http://dev.mysql.com/doc/refman/5.1/en/replication-faq.html
Shows 17.3.4.# when it should be 16.3.4.#

7) http://dev.mysql.com/doc/refman/5.1/en/replication-problems.html
"Check that networking on the master and slave have not been disabled. Look for the skip-networking option in the configuration file. It should either be commented out or deleted entirely. " 
I believe "and slave have" s/b replaced with "has" removing reference to slave because skip-networking on slave does not cause this problem.  Or, if 1st sentence is referencing networking in a general sense perhaps "on the master" s/b added afer "in the configuration file"

8) http://dev.mysql.com/doc/refman/5.1/en/replication-bugs.html
shell> mysqlbinlog -j log_pos log_file | head
-j is deprecated perhaps sample should show --start-position instead?

9) http://dev.mysql.com/doc/refman/5.1/en/slave-logs.html
"relay.info" s/b "relay-log.info" throughout page

10) http://dev.mysql.com/doc/refman/5.1/en/slave-logs-relaylog.html
trivial typo " shell<" s/b "shell>" in two spots

How to repeat:
View on-line documentation

Suggested fix:
Update documentation
[8 Apr 2009 16:10] 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, and will be included in the next release of the relevant products.

1. Done.

2. The change actually was made in MySQL 5.2.5, but that was part of a transient release series. This causes confusion, so I've changed such references to MySQL 6.0.

"importance" -> "important"

3. Link was to open-bugs, should be to open-bugs-general:
http://dev.mysql.com/doc/refman/5.1/en/open-bugs-general.html

3. Cannot find "at at runtime", I see only "format at runtime".

4. OpenSSL -> SSL

5. Nothing done. DETERMINISTIC can indeed be specified for procedures, but: 1) It's only a hint and doesn't actually make anything deterministic. Suggesting it does so would not be good. 2) It has nothing to do with signalling whether statements are "safe" for replication, so we shouldn't suggest that it does.

6. Done. Congratulations, no one ever noticed this before!

7. Done.

8. Done.

9. Done. This problem occurred elsewhere, too.

10. Done. This problem occurred elsewhere, too.

Thanks for reporting these problems!