Bug #64823 Connector/J documentation for utf8mb4 support was not updated properly

• Submitted: 31 Mar 2012 8:48
• Modified: 19 Apr 2012 0:25
• Reporter: Sveta Smirnova
• Status: Closed
• Category: Connector / J Documentation
• Severity: S3 (Non-critical)
• Version: 5.1.18
• OS: Any
• Assigned to: John Russell
• CPU Architecture: Any

[31 Mar 2012 8:48] Sveta Smirnova

Description:
Verifying bug #64073 I need to use utf8mb4 character set. If follow intuition and set it as characterEncoding=utf8mb4 my application returns "java.sql.SQLException: Unsupported character encoding 'utf8mb4'." error.

So I opened user manual at http://dev.mysql.com/doc/refman/5.5/en/connector-j-reference-charsets.html and found no mention of utf8mb4 character set.

However c/J perfectly supports it and this described in bug #57694:

----<q>----
To use 4-byte UTF8 with Connector/J configure the MySQL server with
character_set_server=utf8mb4. Connector/J will then use that setting as long as
characterEncoding has not been set in the connection string. This is equivalent to
autodetection of the character set.
----</q>---- 

as well as in 5.1.14 Change Log. But I still think this change introduced new, not intuitive, behavior and should be also documented at http://dev.mysql.com/doc/refman/5.5/en/connector-j-reference-charsets.html

How to repeat:
See description

Suggested fix:
Update http://dev.mysql.com/doc/refman/5.5/en/connector-j-reference-charsets.html

[19 Apr 2012 0:25] John Russell

The documentation did say to use character_set_server for the general case of specifying a Unicode character encoding, but it required following a chain of logic to reach that conclusion ("prior to version 4.1" etc.). I added the tip about using character_set_server=utf8mb4 and omitting characterEncoding in the connection string. I also rearranged and divided the bits on this page to make it clearer what is the current / latest advice rather than always putting the former / obsolete info first.