Changes in MySQL Connector/J 8.0.23 (2021-01-18, General Availability)

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 and 5.7. It supports the Java Database Connectivity (JDBC) 4.2 API, and implements the X DevAPI.

• Deprecation and Removal Notes

• Functionality Added or Changed

• Bugs Fixed

Deprecation and Removal Notes

• 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. (WL #14207)

Functionality Added or Changed

• 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.

  Important

  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=user-defined-time-zone and keep it the same, without configuring the new connection properties, can expect the same behavior as before, but testing is recommended.

  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.

  (WL #14206, WL #14274)

Bugs Fixed

• 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)