3.3.4.1 升级到 MySQL Connector/J 8.0

将为 Connector/J 5.1 开发的应用程序升级为使用 Connector/J 8.0 可能需要对您的代码或其运行环境进行某些更改。以下是 Connector/J 从 5.1 到 8.0 的一些变化，可能需要进行调整：

3.3.4.1.1 Java 8平台运行

Connector/J 8.0 是专门为在 Java 8 平台上运行而创建的。虽然众所周知 Java 8 与早期 Java 版本高度兼容，但确实存在不兼容性，设计用于 Java 7 的代码可能需要在运行 Java 8 之前进行调整。开发人员应参考 Oracle 提供 的不兼容性信息。

3.3.4.1.2 连接属性的变化

Connector/J 8.0 连接属性的完整列表在 第 3.5.3 节“配置属性”中可用。以下是从 Connector/J 5.1 到 8.0 已更改（删除、添加、更改名称或更改默认值）的连接属性。

已删除的属性（不要在连接期间使用它们）：

  • useDynamicCharsetInfo

  • useBlobToStoreUTF8OutsideBMP、、 utf8OutsideBmpExcludedColumnNamePattern和 utf8OutsideBmpIncludedColumnNamePattern：MySQL 5.6 及更高版本支持 utf8mb4 字符集，这是 Connector/J 应用程序应该使用的字符集，用于支持超出 Unicode 版本 3 的基本多语言平面 (BMP) 的字符。

  • useJvmCharsetConverters: 现在所有情况下都使用 JVM 字符集转换

  • 以下日期和时间属性：

    • dynamicCalendars

    • noTzConversionForTimeType

    • noTzConversionForDateType

    • cacheDefaultTimezone

    • useFastIntParsing

    • useFastDateParsing

    • useJDBCCompliantTimezoneShift

    • useLegacyDatetimeCode

    • useSSPSCompatibleTimezoneShift

    • useTimezone

    • useGmtMillisForDatetimes

  • dumpMetadataOnColumnNotFound

  • relaxAutoCommit

  • strictFloatingPoint

  • runningCTS13

  • retainStatementAfterResultSetClose

  • nullNamePatternMatchesAll（从 8.0.9 版开始删除）

已添加的属性：

  • mysqlx.useAsyncProtocol（自 8.0.22 版起已弃用）

已更改名称的属性：

  • com.mysql.jdbc.faultInjection.serverCharsetIndex 变成 com.mysql.cj.testsuite.faultInjection.serverCharsetIndex

  • loadBalanceEnableJMX至 ha.enableJMX

  • replicationEnableJMX至 ha.enableJMX

默认值已更改的属性：

  • nullCatalogMeansCurrent现在 false默认

3.3.4.1.3 连接器/J API 的变化

本节介绍从版本 5.1 到 8.0 对 Connector/J API 的一些更重要的更改。您可能需要相应地调整 API 调用：

  • 在 MySQL Connector/J中实现的类的名称 java.sql.Driver已从 更改 com.mysql.jdbc.Driver为 com.mysql.cj.jdbc.Driver. 旧的类名已被弃用。

  • 这些常用类和接口的名称也已更改：

    • 异常拦截器：从 com.mysql.jdbc.ExceptionInterceptor 到 com.mysql.cj.exceptions.ExceptionInterceptor

    • 语句拦截器：从 com.mysql.jdbc.StatementInterceptorV2 到 com.mysql.cj.interceptors.QueryInterceptor

    • 连接生命周期拦截器：从 com.mysql.jdbc.ConnectionLifecycleInterceptor 到 com.mysql.cj.jdbc.interceptors.ConnectionLifecycleInterceptor

    • AuthenticationPlugin：从 com.mysql.jdbc.AuthenticationPlugin 到 com.mysql.cj.protocol.AuthenticationPlugin

    • 平衡策略：从 com.mysql.jdbc.BalanceStrategy 到 com.mysql.cj.jdbc.ha.BalanceStrategy

    • MysqlDataSource：从 com.mysql.jdbc.jdbc2.optional.MysqlDataSource 到 com.mysql.cj.jdbc.MysqlDataSource

    • MysqlDataSourceFactory：从 com.mysql.jdbc.jdbc2.optional.MysqlDataSourceFactory 到 com.mysql.cj.jdbc.MysqlDataSourceFactory

    • MysqlConnectionPoolDataSource：从 com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource 到 com.mysql.cj.jdbc.MysqlConnectionPoolDataSource

    • MysqlXADataSource：从 com.mysql.jdbc.jdbc2.optional.MysqlXADataSource 到 com.mysql.cj.jdbc.MysqlXADataSource

    • MysqlXid：从 com.mysql.jdbc.jdbc2.optional.MysqlXid 到com.mysql.cj.jdbc.MysqlXid

3.3.4.1.4 构建属性的更改

许多用于从源代码构建 Connector/J 的 Ant 属性 已重命名；请参阅 表 3.1，“构建属性从 Connector/J 5.1 到 8.0 的变化”

表 3.1 构建属性从 Connector/J 5.1 到 8.0 的变化

旧名 新名字
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 测试属性的变化

许多用于测试 Connector/J 的 Ant 属性 已被重命名或删除；请参阅 表 3.2，“测试属性从 Connector/J 5.1 到 8.0 的变化”

表 3.2 测试属性从 Connector/J 5.1 到 8.0 的变化

旧名 新名字
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 删除
com.mysql.jdbc.testsuite.driver 删除
com.mysql.jdbc.testsuite.url.default 删除。不再需要，因为多 JVM 测试已从测试套件中删除。

3.3.4.1.6 异常变化

从 5.1 版到 8.0 版的 Connector/J 中删除了一些例外情况。用于捕获已删除异常的应用程序现在应该捕获下 表 3.3中列出的相应异常 。

笔记

其中一些 Connector/J 5.1 异常在 com.mysql.jdbc.exception.jdbc4 包中是重复的；在表 3.3中它们的名称 中用“ [jdbc4.] ”表示。

表 3.3 Connector/J 5.1 到 8.0 的异常变化

删除了 Connector/J 5.1 中的异常 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 其他变化

以下是 Connector/J 8.0 的其他变化：

  • 删除ReplicationDriver。您现在无需使用单独的驱动程序，只需使用该 jdbc:mysql:replication://方案即可获得用于复制设置的连接。

  • 有关 Connector/J 8.0 工作所需的 第三方库， 请参阅第 3.3 节“Connector/J 安装”。

  • 对于 Connector/J 8.0.22 及更早版本： Connector/J 8.0 始终对日期时间值执行时间偏移调整，并且调整需要满足以下条件之一：

    • MySQL 服务器配置了 Java 可识别的规范时区（例如 Europe/Paris、Etc/GMT-5、UTC 等）

    • 通过设置 Connector/J 连接属性 serverTimezone （例如， serverTimezone=Europe/Paris）覆盖服务器的时区。

    笔记

    自 8.0.23 版以来，Connector/J 在这方面的行为发生了变化。有关详细信息，请参阅 第 3.5.6.1 节，“保存时间点”。serverTimezone现在是连接属性的别名 connectionTimeZone，它已被替换 serverTimezone。