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:
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.
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
, andutf8OutsideBmpIncludedColumnNamePattern
: 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 casesThe 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 tocom.mysql.cj.testsuite.faultInjection.serverCharsetIndex
loadBalanceEnableJMX
toha.enableJMX
replicationEnableJMX
toha.enableJMX
Properties that have their default values changed:
nullCatalogMeansCurrent
is nowfalse
by default
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 fromcom.mysql.jdbc.Driver
tocom.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
tocom.mysql.cj.exceptions.ExceptionInterceptor
StatementInterceptor: from
com.mysql.jdbc.StatementInterceptorV2
tocom.mysql.cj.interceptors.QueryInterceptor
ConnectionLifecycleInterceptor: from
com.mysql.jdbc.ConnectionLifecycleInterceptor
tocom.mysql.cj.jdbc.interceptors.ConnectionLifecycleInterceptor
AuthenticationPlugin: from
com.mysql.jdbc.AuthenticationPlugin
tocom.mysql.cj.protocol.AuthenticationPlugin
BalanceStrategy: from
com.mysql.jdbc.BalanceStrategy
tocom.mysql.cj.jdbc.ha.BalanceStrategy
MysqlDataSource: from
com.mysql.jdbc.jdbc2.optional.MysqlDataSource
tocom.mysql.cj.jdbc.MysqlDataSource
MysqlDataSourceFactory: from
com.mysql.jdbc.jdbc2.optional.MysqlDataSourceFactory
tocom.mysql.cj.jdbc.MysqlDataSourceFactory
MysqlConnectionPoolDataSource: from
com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource
tocom.mysql.cj.jdbc.MysqlConnectionPoolDataSource
MysqlXADataSource: from
com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
tocom.mysql.cj.jdbc.MysqlXADataSource
MysqlXid: from
com.mysql.jdbc.jdbc2.optional.MysqlXid
tocom.mysql.cj.jdbc.MysqlXid
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”
Table 3.1 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 |
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”
Table 3.2 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.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. |
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.3 below.
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
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.]MySQLNonTransientConnectionExceptio n |
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 |
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 thejdbc: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
).