Connector/J 3.1 is designed to be backward-compatible with
Connector/J 3.0 as much as possible. Major changes are
isolated to new functionality exposed in MySQL-4.1 and newer,
which includes Unicode character sets, server-side prepared
SQLState codes returned in
error messages by the server and various performance
enhancements that can be enabled or disabled using
Unicode Character Sets: See the next section, as well as Character Set Support, for information on this MySQL feature. If you have something misconfigured, it will usually show up as an error with a message similar to
Illegal mix of collations.
Server-side Prepared Statements: Connector/J 3.1 will automatically detect and use server-side prepared statements when they are available (MySQL server version 4.1.0 and newer).
Starting with version 3.1.7, the driver scans SQL you are preparing using all variants of
Connection.prepareStatement()to determine if it is a supported type of statement to prepare on the server side, and if it is not supported by the server, it instead prepares it as a client-side emulated prepared statement. You can disable this feature by passing
emulateUnsupportedPstmts=falsein your JDBC URL.
If your application encounters issues with server-side prepared statements, you can revert to the older client-side emulated prepared statement code that is still presently used for MySQL servers older than 4.1.0 with the connection property
Datetimes with all-zero components (
0000-00-00 ...): These values cannot be represented reliably in Java. Connector/J 3.0.x always converted them to
NULLwhen being read from a ResultSet.
Connector/J 3.1 throws an exception by default when these values are encountered, as this is the most correct behavior according to the JDBC and SQL standards. This behavior can be modified using the
zeroDateTimeBehaviorconfiguration property. The permissible values are:
exception(the default), which throws an SQLException with an SQLState of
convertToNull, which returns
NULLinstead of the date.
round, which rounds the date to the nearest closest value which is
Starting with Connector/J 3.1.7,
ResultSet.getString()can be decoupled from this behavior using
noDatetimeStringSync=true(the default value is
false) so that you can retrieve the unaltered all-zero value as a String. Note that this also precludes using any time zone conversions, therefore the driver will not allow you to enable
useTimezoneat the same time.
New SQLState Codes: Connector/J 3.1 uses SQL:1999 SQLState codes returned by the MySQL server (if supported), which are different from the legacy X/Open state codes that Connector/J 3.0 uses. If connected to a MySQL server older than MySQL-4.1.0 (the oldest version to return SQLStates as part of the error code), the driver will use a built-in mapping. You can revert to the old mapping by using the configuration property
BLOBcolumn will now return the address of the
bytearray that represents it, instead of a
Stringrepresentation of the
BLOBvalues have no character set, so they cannot be converted to
java.lang.Strings without data loss or corruption.
To store strings in MySQL with LOB behavior, use one of the
TEXTtypes, which the driver will treat as a
Debug builds: Starting with Connector/J 3.1.8 a debug build of the driver in a file named
mysql-connector-java-is shipped alongside the normal binary jar file that is named
Starting with Connector/J 3.1.9, we do not ship the
.classfiles unbundled, they are only available in the JAR archives that ship with the driver.
Do not use the debug build of the driver unless instructed to do so when reporting a problem or bug, as it is not designed to be run in production environments, and will have adverse performance impact when used. The debug binary also depends on the Aspect/J runtime library, which is located in the
src/lib/aspectjrt.jarfile that comes with the Connector/J distribution.