3.3.4.1 Upgrading to MySQL Connector/J 8.0

Upgrading an application developed for Connector/J 5.1 to use Connector/J 8.0 might require certain changes to your code or the environment in which it runs. Here are some changes for Connector/J going from 5.1 to 8.0, for which adjustments might be required:

3.3.4.1.1 Running on the Java 8 Platform

Connector/J 8.0 is created specifically to run on the Java 8 platform. While Java 8 is known to be strongly compatible with earlier Java versions, incompatibilities do exist, and code designed to work on Java 7 might need to be adjusted before being run on Java 8. Developers should refer to the incompatibility information provided by Oracle.

3.3.4.1.2 Changes in Connection Properties

A complete list of Connector/J 8.0 connection properties are available in connector-j-reference-set-config. The following are connection properties that have been changed (removed, added, have their names changed, or have their default values changed) going from Connector/J 5.1 to 8.0.

Properties that have been removed (do not use them during connection):

• useDynamicCharsetInfo

• useBlobToStoreUTF8OutsideBMP , utf8OutsideBmpExcludedColumnNamePattern, and utf8OutsideBmpIncludedColumnNamePattern: MySQL 5.6 and later supports the utf8mb4 character set, which is the character set that should be used by Connector/J applications for supporting characters beyond the Basic Multilingual Plane (BMP) of Unicode Version 3.

• useJvmCharsetConverters: JVM character set conversion is now used in all cases

• The following date and time properties:

  • dynamicCalendars

  • noTzConversionForTimeType

  • noTzConversionForDateType

  • cacheDefaultTimezone

  • useFastIntParsing

  • useFastDateParsing

  • useJDBCCompliantTimezoneShift

  • useLegacyDatetimeCode

  • useSSPSCompatibleTimezoneShift

  • useTimezone

  • useGmtMillisForDatetimes

• dumpMetadataOnColumnNotFound

• relaxAutoCommit

• strictFloatingPoint

• runningCTS13

• retainStatementAfterResultSetClose

• nullNamePatternMatchesAll (removed since release 8.0.9)

Properties that have been added:

• mysqlx.useAsyncProtocol

Property that has its name changed:

• com.mysql.jdbc.faultInjection.serverCharsetIndex changed to com.mysql.cj.testsuite.faultInjection.serverCharsetIndex

• loadBalanceEnableJMX to ha.enableJMX

• replicationEnableJMX to ha.enableJMX

Properties that have their default values changed:

• nullCatalogMeansCurrent is now false by default

3.3.4.1.3 Changes in the Connector/J API

This section describes some of the more important changes to the Connector/J API going from version 5.1 to 8.0. You might need to adjust your API calls accordingly:

• The name of the class that implements java.sql.Driver in MySQL Connector/J has changed from com.mysql.jdbc.Driver to com.mysql.cj.jdbc.Driver. The old class name has been deprecated.

• The names of these commonly-used classes and interfaces have also been changed:

  • ExceptionInterceptor: from com.mysql.jdbc.ExceptionInterceptor to com.mysql.cj.exceptions.ExceptionInterceptor

  • StatementInterceptor: from com.mysql.jdbc.StatementInterceptorV2 to com.mysql.cj.interceptors.QueryInterceptor

  • ConnectionLifecycleInterceptor: from com.mysql.jdbc.ConnectionLifecycleInterceptor to com.mysql.cj.jdbc.interceptors.ConnectionLifecycleInterceptor

  • AuthenticationPlugin: from com.mysql.jdbc.AuthenticationPlugin to com.mysql.cj.protocol.AuthenticationPlugin

  • BalanceStrategy: from com.mysql.jdbc.BalanceStrategy to com.mysql.cj.jdbc.ha.BalanceStrategy

  • MysqlDataSource: from com.mysql.jdbc.jdbc2.optional.MysqlDataSource to com.mysql.cj.jdbc.MysqlDataSource

  • MysqlDataSourceFactory: from com.mysql.jdbc.jdbc2.optional.MysqlDataSourceFactory to com.mysql.cj.jdbc.MysqlDataSourceFactory

  • MysqlConnectionPoolDataSource: from com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource to com.mysql.cj.jdbc.MysqlConnectionPoolDataSource

  • MysqlXADataSource: from com.mysql.jdbc.jdbc2.optional.MysqlXADataSource to com.mysql.cj.jdbc.MysqlXADataSource

  • MysqlXid: from com.mysql.jdbc.jdbc2.optional.MysqlXid to com.mysql.cj.jdbc.MysqlXid

3.3.4.1.4 Changes for Build Properties

A number of Ant properties for building Connector/J from source have been renamed; see Table 3.2, “Changes with the Build Properties from Connector/J 5.1 to 8.0”

Table 3.2 Changes with the Build Properties from Connector/J 5.1 to 8.0

Old name	New name
com.mysql.jdbc.extra.libs	com.mysql.cj.extra.libs
com.mysql.jdbc.jdk	com.mysql.cj.build.jdk
debug.enable	com.mysql.cj.build.addDebugInfo
com.mysql.jdbc.noCleanBetweenCompiles	com.mysql.cj.build.noCleanBetweenCompiles
com.mysql.jdbc.commercialBuild	com.mysql.cj.build.commercial
com.mysql.jdbc.filterLicense	com.mysql.cj.build.filterLicense
com.mysql.jdbc.noCryptoBuild	com.mysql.cj.build.noCrypto
com.mysql.jdbc.noSources	com.mysql.cj.build.noSources
com.mysql.jdbc.noMavenSources	com.mysql.cj.build.noMavenSources
major_version	com.mysql.cj.build.driver.version.major
minor_version	com.mysql.cj.build.driver.version.minor
subminor_version	com.mysql.cj.build.driver.version.subminor
version_status	com.mysql.cj.build.driver.version.status
extra.version	com.mysql.cj.build.driver.version.extra
snapshot.version	com.mysql.cj.build.driver.version.snapshot
version	com.mysql.cj.build.driver.version
full.version	com.mysql.cj.build.driver.version.full
prodDisplayName	com.mysql.cj.build.driver.displayName
prodName	com.mysql.cj.build.driver.name
fullProdName	com.mysql.cj.build.driver.fullName
buildDir	com.mysql.cj.build.dir
buildDriverDir	com.mysql.cj.build.dir.driver
mavenUploadDir	com.mysql.cj.build.dir.maven
distDir	com.mysql.cj.dist.dir
toPackage	com.mysql.cj.dist.dir.prepare
packageDest	com.mysql.cj.dist.dir.package
com.mysql.jdbc.docs.sourceDir	com.mysql.cj.dist.dir.prebuilt.docs

3.3.4.1.5 Change for Test Properties

A number of Ant properties for testing Connector/J have been renamed or removed; see Table 3.3, “Changes with the Test Properties from Connector/J 5.1 to 8.0”

Table 3.3 Changes with the Test Properties from Connector/J 5.1 to 8.0

Old name	New name
buildTestDir	com.mysql.cj.testsuite.build.dir
junit.results	com.mysql.cj.testsuite.junit.results
com.mysql.jdbc.testsuite.jvm	com.mysql.cj.testsuite.jvm
test	com.mysql.cj.testsuite.test.class
methods	com.mysql.cj.testsuite.test.methods
com.mysql.jdbc.testsuite.url	com.mysql.cj.testsuite.url
com.mysql.jdbc.testsuite.admin-url	com.mysql.cj.testsuite.url.admin
com.mysql.jdbc.testsuite.ClusterUrl	com.mysql.cj.testsuite.url.cluster
com.mysql.jdbc.testsuite.url.sha256default	com.mysql.cj.testsuite.url.openssl
com.mysql.jdbc.testsuite.cantGrant	com.mysql.cj.testsuite.cantGrant
com.mysql.jdbc.testsuite.no-multi-hosts-tests	com.mysql.cj.testsuite.disable.multihost.tests
com.mysql.jdbc.test.ds.host	com.mysql.cj.testsuite.ds.host
com.mysql.jdbc.test.ds.port	com.mysql.cj.testsuite.ds.port
com.mysql.jdbc.test.ds.db	com.mysql.cj.testsuite.ds.db
com.mysql.jdbc.test.ds.user	com.mysql.cj.testsuite.ds.user
com.mysql.jdbc.test.ds.password	com.mysql.cj.testsuite.ds.password
com.mysql.jdbc.test.tabletype	com.mysql.cj.testsuite.loadstoreperf.tabletype
com.mysql.jdbc.testsuite.loadstoreperf.useBigResults	com.mysql.cj.testsuite.loadstoreperf.useBigResults
com.mysql.jdbc.testsuite.MiniAdminTest.runShutdown	com.mysql.cj.testsuite.miniAdminTest.runShutdown
com.mysql.jdbc.testsuite.noDebugOutput	com.mysql.cj.testsuite.noDebugOutput
com.mysql.jdbc.testsuite.retainArtifacts	com.mysql.cj.testsuite.retainArtifacts
com.mysql.jdbc.testsuite.runLongTests	com.mysql.cj.testsuite.runLongTests
com.mysql.jdbc.test.ServerController.basedir	com.mysql.cj.testsuite.serverController.basedir
com.mysql.jdbc.ReplicationConnection.isSlave	com.mysql.cj.testsuite.replicationConnection.isSlave
com.mysql.jdbc.test.isLocalHostnameReplacement	Removed
com.mysql.jdbc.testsuite.driver	Removed
com.mysql.jdbc.testsuite.url.default	Removed. No longer needed, as multi-JVM tests have been removed from the test suite.

3.3.4.1.6 Changes for Exceptions

Some exceptions have been removed from Connector/J going from version 5.1 to 8.0. Applications that used to catch the removed exceptions should now catch the corresponding exceptions listed in Table 3.4 below.

Note

Some of these Connector/J 5.1 exceptions are duplicated in the com.mysql.jdbc.exception.jdbc4 package; that is indicated by “[jdbc4.]” in their names in Table 3.4.

Table 3.4 Changes for Exceptions from Connector/J 5.1 to 8.0

Removed Exception in Connector/J 5.1	Exception to Catch in Connector/J 8.0
com.mysql.jdbc.exceptions.jdbc4.CommunicationsException	com.mysql.cj.jdbc.exceptions.CommunicationsException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLDataException	java.sql.SQLDataException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLIntegrityConstraintViolationException	java.sql.SQLIntegrityConstraintViolationException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLInvalidAuthorizationSpecException	java.sql.SQLInvalidAuthorizationSpecException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLNonTransientConnectionException	java.sql.SQLNonTransientConnectionException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLNonTransientException	java.sql.SQLNonTransientException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLQueryInterruptedException	com.mysql.cj.jdbc.exceptions.MySQLQueryInterruptedException
com.mysql.jdbc.exceptions.MySQLStatementCancelledException	com.mysql.cj.jdbc.exceptions.MySQLStatementCancelledException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLSyntaxErrorException	java.sql.SQLSyntaxErrorException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTimeoutException	java.sql.SQLTimeoutException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTransactionRollbackException	java.sql.SQLTransactionRollbackException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTransientConnectionException	java.sql.SQLTransientConnectionException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTransientException	java.sql.SQLTransientException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLIntegrityConstraintViolationException	java.sql.SQLIntegrityConstraintViolationException

3.3.4.1.7 Other Changes

Here are other changes with Connector/J 8.0:

• Removed ReplicationDriver. Instead of using a separate driver, you can now obtain a connection for a replication setup just by using the jdbc:mysql:replication:// scheme.

• See Section 3.3, “Connector/J Installation” for third-party libraries required for Connector/J 8.0 to work.

• Connector/J 8.0 always performs time offset adjustments on date-time values, and the adjustments require one of the following to be true:

  • The MySQL server is configured with a canonical time zone that is recognizable by Java (for example, Europe/Paris, Etc/GMT-5, UTC, etc.)

  • The server's time zone is overridden by setting the Connector/J connection property serverTimezone (for example, serverTimezone=Europe/Paris).