MySQL Connector/J 5.1 Developer Guide
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
statements, SQLState
codes returned in
error messages by the server and various performance
enhancements that can be enabled or disabled using
configuration properties.
Unicode Character Sets:
See the next section, as well as
Character Sets, Collations, Unicode, 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=false
in 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
useServerPrepStmts=false
.
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 NULL
when 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
zeroDateTimeBehavior
configuration
property. The permissible values are:
exception
(the default), which
throws an SQLException with an SQLState of
S1009
.
convertToNull
, which returns
NULL
instead of the date.
round
, which rounds the date to the
nearest closest value which is
0001-01-01
.
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
noDatetimeStringSync
and
useTimezone
at 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 useSqlStateCodes=false
.
ResultSet.getString()
:
Calling ResultSet.getString()
on a
BLOB
column will now return
the address of the byte[]
array that
represents it, instead of a String
representation of the BLOB
.
BLOB
values have no
character set, so they cannot be converted to
java.lang.String
s without data loss or
corruption.
To store strings in MySQL with LOB behavior, use one of
the TEXT
types, which the
driver will treat as a java.sql.Clob
.
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
version
-bin-g.jarmysql-connector-java-
.
version
-bin.jar
Starting with Connector/J 3.1.9, we do not ship the
.class
files 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.jar
file that comes
with the Connector/J distribution.