MySQL Connector/J 8.0 Release Notes
Version 8.0.23 is the latest General Availability release of the 8.0 series of MySQL Connector/J. It is suitable for use with MySQL Server versions 8.0, 5.7, and 5.6. It supports the Java Database Connectivity (JDBC) 4.2 API, and implements the X DevAPI.
As an implementation of the MySQL Terminology Updates, connection properties and public method names have been adjusted in the following manners:
Changing "master" to "source": For example, the connection
property queriesBeforeRetryMaster
becomes
queriesBeforeRetrySource
, and the method
isMasterConnection()
becomes
isSourceConnection()
Changing "slave" to "replica": For example, the connection
property allowSlavesDownConnections
becomes allowReplicaDownConnections
, and
the method getSlaveHosts()
becomes
getReplicaHosts()
Changing "blacklist" to "blocklist": For example, the
connection property
loadBalanceBlacklistTimeout
becomes
loadBalanceBlocklistTimeout
.
Old names have been deprecated—though they are still usable for now, they are to be removed eventually in future releases; users are therefore encouraged to switch to the new names.
See the MySQL Connector/J 8.0 Developer Guide, the Connector/J API documentation (generated by Javadoc), and the MySQL Connector/J X DevAPI Reference available at Connectors and APIs for information on any new property and method names.
Important Change: A new mechanism has been introduced for users to configure how time zone conversions should occur when time instants are saved to or retrieved from a server by Connector/J. Three new connection properties, preserveInstants, connectionTimeZone, and forceConnectionTimeZoneToSession, control the new mechanism—see Preserving Time Instants for details.
To preserve the default behavior of Connector/J 8.0.22 and
earlier to query the session time zone from the server and
then convert a timestamp between that and the JVM time zone,
set the new connection property
connectionTimeZone
to SERVER
, and leave the other two new
properties at their default values
(i.e.,preserveInstants=true
and
forceConnectionTimeZoneToSession=false).
Users who had
serverTimeZone=
and keep it the same, without configuring the new connection
properties, can expect the same behavior as before, but
testing is recommended.
user-defined-time-zone
Also, with the implementation of the new mechanism, a
getObject(columnIndex)
call on a
DATETIME
column returns a
LocalDateTime
object now instead of a
String
. To receive a
String
like before, use
getObject(columnIndex, String.class)
instead.
While a java.sql.TIME
instance, according to
the JDBC specification, is not supposed to contain fractional
seconds by design, because java.sql.TIME
is a
wrapper around java.util.Date
, it is possible
to store fractional seconds in a
java.sql.TIME
instance. However, when
Connector/J inserted a java.sql.TIME
into the
server as a MySQL TIME
value, the fractional
seconds were always truncated. To allow the fractional seconds
to be sent to the server, a new connection property,
sendFractionalSecondsForTime,
has been introduced: when the property is
true
(which is the default value), the
fractional seconds for java.sql.TIME
are sent
to the server; otherwise, the fractional seconds are truncated.
Also, the connection property sendFractionalSeconds has been changed into a global control for the sending of fractional seconds for ALL date-time types. As a result, if sendFractionalSeconds=false, fractional seconds are not sent irrespective of the value of sendFractionalSecondsForTime.
(Bug #20959249, Bug #76775)
Connector/J now supports the following authentication methods for LDAP Pluggable Authentication with the MySQL Enterprise Server:
The GSSAPI/Kerberos Authentication Method: A new connection property, ldapServerHostname, has been introduced for specifying the LDAP service host principal as configured in the Kerberos key distribution centre (KDC). See the description for ldapServerHostname in the MySQL Connector/J 8.0 Developer Guide for details.
The SCRAM-SHA-256
method.
Storing a java.time.LocalDateTime
object onto
the server as a TIMESTAMP
value using a
batched PreparedStatement
failed with the
complaint that java.time.LocalDateTime
could
not be cast to java.sql.Timestamp
. With this
fix, the casting works again.
(Bug #32099505, Bug #101413)
Using the setObject()
method to set a
ByteArrayInputStream
instance for a
PreparedStatement
resulted in a
SQLException
.
(Bug #32046007, Bug #101242)
The returned value for a TIMESTAMP
was
incorrect when a temporal
interval expression was used in the SQL statement for the
query.
(Bug #31074051, Bug #99013)
After upgrading from Connector/J 5.1 to 8.0, the results of
saving and then retrieving DATETIME
and
TIMESTAMP
values became different sometimes.
It was because while Connector/J 5.1 does not preserve a time
instant by default, Connector/J 8.0.22 and earlier tried to do
so by converting a timestamp to the server's session time zone
before sending its value to the server. In this release, new
mechanisms for controlling timezone conversion has been
introduced—see Preserving Time Instants
for details. Under this new mechanism, the default behavior of
Connector/J 5.1 in this respect is preserved by setting the
connection property
preserveInstants=false.
(Bug #30962953, Bug #98695, Bug #30573281, Bug #95644)
Conversion of a MySQL DATETIME
or
TIMESTAMP
value to a Java
OffsetDateTime
using the
getObject(i, OffsetDateTime.class)
method
failed with a "Conversion not supported for type ..." error. It
was because the OffsetDateTime.parse()
method
on DATETIME
and TIMESTAMP
values yielded an unexpected string format. With this patch,
conversions between OffsetDateTime
and the
DATE
, TIME
,
DATETIME
, TIMESTAMP
, and
YEAR
data types are now possible, and an
instant point on the timeline is preserved as such during a
conversion, when possible—see
Preserving Time Instants for details.
(Bug #29402209, Bug #94457)
When the server's session time zone setting was not
understandable by Connector/J (for example, it was set to
CEST
), a connection could not be established
with the server unless Connector/J specified the correct IANA
time zone name in the serverTimezone
connection property. This happened even if there was actually no
need to use any date-time functionality in Connector/J. The
issue was fixed by the new connection properties for Connector/J
that control date-time handling—see
Preserving Time Instants for details. The
following now happens with respect to the above-mentioned
situation:
If the new connection property
connectionTimeZone
is set to LOCAL
or a specified time zone,
the time_zone
variable on
the server is no longer checked
If
connectionTimeZone=SERVER,
the check for the time_zone
variable is
delayed until date-time driver functionality is first
invoked, so that an unrecognizable server time zone does not
prevent connection to be established. However, when
date-time functionality is invoked and the value of
time_zone
cannot be recognized by
Connector/J, an exception is thrown.
(Bug #21789378)