Documentation Home
Connectors and APIs Manual
Download this Manual
PDF (US Ltr) - 4.1Mb
PDF (A4) - 4.1Mb

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 and beyond 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 and beyond, for which adjustments might be required:

3.3.4.1.1 Running on the Java 8 Platform

Connector/J 8.0 and beyond 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 Section 3.5.3, “Configuration Properties”. 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 and beyond.

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 (deprecated since release 8.0.22)

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 and beyond. 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.1, “Changes with the Build Properties from Connector/J 5.1 to 8.0 and Beyond”

Table 3.1 Changes with the Build Properties from Connector/J 5.1 to 8.0 and Beyond

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.2, “Changes with the Test Properties from Connector/J 5.1 to 8.0 and Beyond”

Table 3.2 Changes with the Test Properties from Connector/J 5.1 to 8.0 and Beyond

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.isReplica
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 and beyond. Applications that used to catch the removed exceptions should now catch the corresponding exceptions listed in Table 3.3 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.3.

Table 3.3 Changes for Exceptions from Connector/J 5.1 to 8.0 and Beyond

Removed Exception in Connector/J 5.1 Exception to Catch in Connector/J 8.0 and Beyond
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 and beyond:

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

  • For Connector/J 8.0.22 and earlierr: 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).

    Note

    The Connector/J's behavior in this respect has changed since release 8.0.23. See Section 3.5.6.1, “Preserving Time Instants” for details. serverTimezone is now an alias for the connection property connectionTimeZone, which has replaced serverTimezone.


PREV   HOME   UP   NEXT
Download this Manual
PDF (US Ltr) - 4.1Mb
PDF (A4) - 4.1Mb