MySQL Connector/J 8.0 Developer Guide
All strings sent from the JDBC driver to the server are
converted automatically from native Java Unicode form to the
client character encoding, including all queries sent using
Statement.execute()
,
Statement.executeUpdate()
, and
Statement.executeQuery()
, as well as all
PreparedStatement
and
CallableStatement
parameters,
excluding parameters set using setBytes()
,
setBinaryStream()
,
setAsciiStream()
,
setUnicodeStream()
, and
setBlob()
.
Connector/J supports a single character encoding between client
and server, and any number of character encodings for data
returned by the server to the client in
ResultSets
.
The character encoding between client and server is
automatically detected upon connection (provided that the
Connector/J connection properties
characterEncoding
and
connectionCollation
are not set). You specify
the encoding on the server using the system variable
character_set_server
(for more
information, see Server Character Set and Collation). The driver
automatically uses the encoding specified by the server. For
example, to use the
4-byte UTF-8 character
set with Connector/J, configure the MySQL server with
character_set_server=utf8mb4
,
and leave characterEncoding
and
connectionCollation
out of the Connector/J
connection string. Connector/J will then autodetect the UTF-8
setting.
To override the automatically detected encoding on the client
side, use the characterEncoding
property in
the connection URL to the server. Use Java-style names when
specifying character encodings. The following table lists MySQL
character set names and their corresponding Java-style names:
Table 6.3 MySQL to Java Encoding Name Translations
MySQL Character Set Name | Java-Style Character Encoding Name |
---|---|
ascii |
US-ASCII |
big5 |
Big5 |
gbk |
GBK |
sjis |
SJIS or Cp932 |
cp932 |
Cp932 or MS932 |
gb2312 |
EUC_CN |
ujis |
EUC_JP |
euckr |
EUC_KR |
latin1 |
Cp1252 |
latin2 |
ISO8859_2 |
greek |
ISO8859_7 |
hebrew |
ISO8859_8 |
cp866 |
Cp866 |
tis620 |
TIS620 |
cp1250 |
Cp1250 |
cp1251 |
Cp1251 |
cp1257 |
Cp1257 |
macroman |
MacRoman |
macce |
MacCentralEurope |
For 8.0.12 and earlier:
For 8.0.13 and later:
|
UTF-8 |
ucs2 |
UnicodeBig |
For Connector/J 8.0.12 and earlier: In order to
use the
utf8mb4
character set for the connection, the server MUST be
configured with
character_set_server=utf8mb4
;
if that is not the case, when UTF-8
is used
for characterEncoding
in the connection
string, it will map to the MySQL character set name
utf8
, which is an alias for
utf8mb3
.
For Connector/J 8.0.13 and later:
When UTF-8
is used for
characterEncoding
in the connection
string, it maps to the MySQL character set name
utf8mb4
.
If the connection option
connectionCollation
is also set
alongside characterEncoding
and is
incompatible with it,
characterEncoding
will be overridden
with the encoding corresponding to
connectionCollation
.
Because there is no Java-style character set name for
utfmb3
that you can use with the
connection option charaterEncoding
,
the only way to use utf8mb3
as your
connection character set is to use a
utf8mb3
collation (for example,
utf8_general_ci
) for the connection
option connectionCollation
, which
forces a utf8mb3
character set to be
used, as explained in the last bullet.
Do not issue the query SET NAMES with Connector/J, as the driver will not detect that the character set has been changed by the query, and will continue to use the character set configured when the connection was first set up.