SpringBoot中从HikariCP迁移到Oracle UCP指南

本博客文章讲述如何从HikariCP迁移到Oracle UCP（通用连接池）迁移，后者是连接到Oracle 数据库时的推荐方法。

HikariCP 简介
HikariCP是与 Spring Boot 应用程序一起使用的 JDBC 连接池。

简而言之，从 Java 开发人员的角度来看，要在 Spring Boot 应用程序中使用 HikariCP 作为连接池，在使用 JDBC 连接池时通常需要执行一些步骤。

如果您使用 Spring Initializr，那么有趣的是，spring-boot-starter-jdbc 或 spring-boot-starter-data-jpa 默认情况下以及在使用这些启动器时包含对 HikariCP 的依赖项。因此，如果您想使用 UCP，建议排除对 HikariCP 的依赖。

如果您需要 HikariCP 的介绍，我建议您查看我同事的博客文章 — HikariCP Best Practices for Oracle Database and Spring Boot，其中介绍了 HikariCP 并使用 Oracle JDBC 版本 19.21（ojdbc8 依赖项）。

本博客文章使用 Oracle JDBC 版本 23.3（ojdbc11 依赖项）。

Oracle UCP 简介
Oracle通用连接池（UCP）是Oracle设计的一个基于Java JDBC的高性能连接池，旨在提高数据库访问的效率和性能。

UCP JDBC 连接池可以使用任何 JDBC 驱动程序来创建物理连接，然后由池维护这些连接。可以配置池并提供一整套属性，用于根据应用程序的性能和可用性要求优化池行为。对于更高级的应用程序，UCP 提供了可用于管理池实例的池管理器。

该池还利用 Oracle Real Application Clusters (Oracle RAC) 数据库提供的许​​多高可用性和性能特性。这些功能包括快速连接故障转移 (FCF)、运行时连接负载平衡 (RLB)、连接亲和性、分片和 Oracle 云基础设施数据库服务（自治数据库、BaseDB）。


下面我们有一个示例 application.properties 文件，其中包含最小的 UCP 属性集作为示例。我们将在剩余部分中详细探讨一些其他属性。

# OCI ORACLE 自治数据库连接
spring.datasource.url =<YOUR_JDBC_CONNECTION_URL> 
spring.datasource.username =<YOUR_DB_USERNAME> 
spring.datasource.password =<YOUR_DB_PASSWORD> 

# UCP 的属性 - 通用连接池 (UCP)。需要 Spring Boot 2.4.0 或更高版本
spring.datasource.type =oracle.ucp.jdbc.PoolDataSource 
spring.datasource.oracleucp.connection-pool-name =connectionPoolName1 
spring.datasource.oracleucp.initial-pool-size = 1 
spring. datasource.oracleucp.min-pool-size = 1 
spring.datasource.oracleucp.max-pool-size = 2 
spring.datasource.oracleucp.connection-factory-class-name =oracle.jdbc.pool.OracleDataSource

从 HikariCP 迁移到 Oracle UCP
现在让我们看看如何从 HikariCP 迁移到 UCP。
以下步骤介绍如何正确配置并允许来自使用Oracle UCP（Oracle 连接池）作为 HikariCP（Spring Boot 中的默认连接池实现）替代方案的 Spring Boot 应用程序的连接。

首先，要将 UCP 添加为 Maven 依赖项，您可以显式添加 ojdbc11 和 ucp11 工件。

 <dependency>
          <groupId>com.oracle.database.jdbc</groupId>
          <artifactId>ojdbc11</artifactId>
          <version>23.3.0.23.09</version>
        </dependency>
        <dependency>
          <groupId>com.oracle.database.jdbc</groupId>
          <artifactId>ucp11</artifactId>
          <version>23.3.0.23.09</version>
        </dependency>

否则，您可以使用适用于 UCP 的 Oracle Spring Boot Starters。

<dependency>
    <groupId>com.oracle.database.spring</groupId>
    <artifactId>oracle-spring-boot-starter-ucp</artifactId>
    <version>23.4.0</version>
</dependency>

此外，为了完整起见，我们还总结并映射了 HikariCP 和 UCP 下面的相关属性，通过 MBean 映射了池属性和度量。

因此，连接池属性有三个部分：

与 UCP 完全等价的 HikariCP 属性

dataSourceClassName：    ConnectionFactoryClassName    (1) ConnectionFactoryClassName also covers java.sql.DriverManager cases.(2) HikariCP doesn't support XA.
jdbcUrl：    URL    
username ：   User    
password ：   Password    
connectionTimeout (ms)：    ConnectionWaitTimeout    UCP 23.2 supports ms and pre-23.2 supports sec. HikariCP lowest acceptable value 250ms.
idleTimeout：    InactiveConnectionTimeout    HikariCP won't drop below minimumIdle.
maxLifeTime ：   MaxConnectionReuseTime    
connectionTestQuery ：   SQLForValidateConnection    
maximumPoolSize ：   MaxPoolSize    
poolName ：   ConnectionPoolName    
driverClassName：    ConnectionFactoryClassName    Not recommended. See dataSourceClassName.
validationTimeout：    ConnectionValidationTimeout    

HikariCP 属性没有相同的 UCP 属性可匹配，但有其他机制，如驱动程序属性或 UCP API

autoCommit    使用 Oracle JDBC 驱动程序连接属性 autoCommit。
registerMbeans    UCP 始终尝试注册。
threadFactory    UCP 支持 setTaskManager（仅 setter API）。
scheduledExecutor    UCP supports setTaskManager instead (setter API only).
keepaliveTime    最接近的方法是使用驱动程序连接属性 oracle.net.keepAlive + oracle.net.TCP_KEEPIDLE，它们适用于所有借用/可用连接。HikariCP 属性只适用于空闲/可用连接，并使用 isValid/query 来保持存活。另一种方法是在 UCP 中为可用连接添加异步验证。
minimumIdle    控制 HikariCP 试图在池中保持的空闲连接的最小数量。

HikariCP 中不存在的UCP旋钮：

如果您使用 Oracle 通用连接池，您可以拥有这些属性。HikariCP 中没有这些属性。

UCP Knob    Description
UCP[XA]ConnectionBuilder.user().password() or PoolDataSource.getConnection(user + password)    UCP 的单个池可容纳多个数据库账户的连接，并可借用某个账户的连接。
UCP[XA]ConnectionBuilder.shardingKey().superShardingKey()    可以使用给定的分片密钥/超级密钥建立连接。
UCP[XA]ConnectionBuilder.connectionWaitTimeout() or UCP[XA]ConnectionBuilder.connectionWaitDuration()    UCP 可以为单独的借用请求和整个 PoolDataSource 设置连接等待超时（以秒为单位或以 Duration（支持毫秒）为单位）。
UCP[XA]ConnectionBuilder.service()    可以借用连接到选定的数据库服务（池可容纳来自不同服务的连接）。
UCP[XA]ConnectionBuilder..labels() or PoolDataSource.getConnection(labels)    可以对 UCP 连接进行标记，并为每个标记分配连接成本。然后就可以根据标签和成本借用连接。
UCP[XA]ConnectionBuilder.pdbRoles()    UCP 支持 Oracle 多租户与多个 PDB 及其角色。
java.sql.Connection UCP[XA]ConnectionBuilder.build() or PoolDataSource.getConnection()    UCP 可通过上述所有按次借用请求属性同步借用连接。
CompletionStage<Connection> UCP[XA]ConnectionBuilder.buildAsyncOracle()    另外，UCP 也可以异步借用连接，返回一个完成阶段。
Publisher<Connection> UCP[XA]ConnectionBuilder.buildConnectionPublisherOracle()    或者，UCP cab 也可以通过 Flow API 异步借用连接，返回一个 Flow.Publisher.Publisher.Publisher.Publisher.Publisher.Publisher.Publisher.Publisher 连接。
PooldataSource and PooXADataSource    UCP 池数据源支持常规和分布式事务。
Pool[XA]DataSource.inactiveConnectionTimeout/maxIdleTime    设置关闭非活动可用连接的超时。
Pool[XA]DataSource.abandonedConnectionTimeout    设置将非活动借用连接（借用但未使用）召回连接池的超时。
Pool[XA]DataSource.timeToLiveConnectionTimeout    Si与 abandonedConnectionTimeout 类似，但它需要借用连接的整个时间。
Pool[XA]DataSource.connectionWaitDuration/connectionWaitTimeout    借用连接的等待时间--以秒或持续时间为单位（包括毫秒）。
Pool[XA]DataSource.fastConnectionjFailoverEnabled    要启用或禁用基于 RAC 的故障切换/运行时负载平衡/连接亲和。
Pool[XA]DataSource.maxStatements    为连接设置最大语句，以便打开或关闭 LRU 语句缓存。
Pool[XA]DataSource.validateConnectionOnBorrow Pool[XA]DataSource.secondsToTrustIdleConnection Pool[XA]DataSource.sqlForValidateConnection Pool[XA]DataSource.connectionValidationTimeout    连接验证的不同模式（验证模式可在驱动程序中切换）；为硬验证模式设置 SQL 语句；设置验证超时；以及设置不对每次借用请求进行连接验证但在指定时间内信任连接有效的模式。
Pool[XA]DataSource.sqlForValidateConnection    Setting SQL for validating a connection
Pool[XA]DataSource.connectionHarvestTriggerCount Pool[XA]DataSource.connectionHarvestMaxCount    Knobs for configuring connection harvesting mechanism - allowing a pool to recall connections back to a pool based on a specified algorithm (for details refer to the UCP Developer's Guide)
Pool[XA]DataSource.connectionLabelingCallback Pool[XA]DataSource.connectionLabelingHighCost Pool[XA]DataSource.HighCostConnectionReuseThreshold    用于配置连接标签机制的旋钮 - 用于设置标签 → 成本对应关系，以便根据成本重新配置连接。
Pool[XA]DataSource.connectionAffinityCallback    旋钮用于配置基于 RAC 的连接亲和性（基于事务的亲和性或基于实例的亲和性）
Pool[XA]DataSource.connectionProperty/connectionProperties    设置连接属性 - 用于 Oracle 驱动程序。
Pool[XA]DataSource.connectionFactoryProperty/connectionFactoryProperties    设置连接工厂属性--与前者类似，但工厂会为将来要创建的每个连接分配这些属性。
Pool[XA]DataSource.maxConnectionReuseTime/maxConnectionReuseCount    根据连接的使用时间或使用次数（借用次数）设置连接生命周期的属性（对防火墙有用）。
Pool[XA]DataSource.connectionInitializationCallback    在连接初始化时调用自定义回调。
Pool[XA]DataSource.connectionCreationConsumer    以调用连接创建时的自定义回调，该回调会在连接创建尝试成功或失败时触发。
Pool[XA]DataSource.connectionRepurposeThreshhold    限制连接再利用的旋钮，只有在达到某个阈值时才允许连接再利用（从一个多租户 PDB 到另一个多租户 PDB）。
Pool[XA]DataSource.maxConnectionsPerService Pool[XA]DataSource..maxConnectionsPerShard   此旋钮限制每个服务的连接数。
Pool[XA]DataSource.sslContext    This knob restricts a number of connection per a shard.
PoolDataSourceFactory.getPool[XA]DataSource(String dataSourceName + InputStream is) PoolDataSourceFactory.getPool[XA]DataSource(Properties config)    该调用允许读取带有多个 PDB 的多租户配置。
UniversalConnectionPoolManager.createConnectionPool UniversalConnectionPoolManager.destroyConnectionPool    池管理器的旋钮，用于创建和销毁具有指定名称的池。
UniversalConnectionPoolManager.startConnection UniversalConnectionPoolManager.stopConnectionPool    池管理器的旋钮，用于启动和停止具有指定名称的池。
UniversalConnectionPoolManager.refreshConnectionPool    Pool Manager's knob to refresh (replace all available connections with fresh ones) a pool with a given name.
UniversalConnectionPoolManager.recycleConnectionPool    Pool Manager's knob to recycle (replace all invalid available connections with fresh ones) a pool with a given name.
UniversalConnectionPoolManager.purgeConnectionPool    Pool Manager's knob to purge (close all connections) a pool with a given name.
UniversalConnectionPoolManager.reconfigureConnectionPool    Read a new pool's configuration and restart a pool with it - for a pool with a given names.
UniversalConnectionPoolManager.getConnectionPoolNames    Get all names of pools that have been created at this point.
UniversalConnectionPoolManager.startMetricsCollection UniversalConnectionPoolManager.stopMetericsCollection UniversalConnectionPoolManager.metricsUpdateInterval    Start/stop/set collect interval for collecting pool metrics with Oracle DMS system.
OracleJDBCConnectionPoolStatistics.successfulAffinityBasedBorrowCount OracleJDBCConnectionPoolStatistics.failedAffinityBasedBorrowCount    Affinity based counters.
OracleJDBCConnectionPoolStatistics.successfulRCLBBasedBorrowCount OracleJDBCConnectionPoolStatistics.failedRCLBBasedBorrowCount    Runtime Load Balanicng counters.
OracleJDBCConnectionPoolStatistics.fcfProcessingInfo    Some Fast Connection Failover statistics summary (Failover events and appropriate conunters and timestamps).
OracleJDBCConnectionPoolStatistics.connectionRepurposeCount    Fo how many times connections have been repurposed from one multi-tenant PDB to another.
OracleJDBCConnectionPoolStatistics.colocationStats    Some colocation tag-based (RAC mechanism) stats.
OracleJDBCConnectionPoolStatistics.totalConnectionsCount OracleJDBCConnectionPoolStatistics.availableConnectionsCount OracleJDBCConnectionPoolStatistics..borrowedConnectionsCount    Some very basic pool counters - how many total/available/borrowed connections in a pool.
OracleJDBCConnectionPoolStatistics.peakConnectionsCount OracleJDBCConnectionPoolStatistics.peakBorrowedConnectionsCount    Some peak connection counters.
OracleJDBCConnectionPoolStatistics.averageBorrowedConnectionsCount    Some average borrowed counts since startup.
OracleJDBCConnectionPoolStatistics.remainingPoolCapacityCount    What is remaining pool's capacity - how many connections is it possible to create.
OracleJDBCConnectionPoolStatistics.labeledConnectionsCount    How many labeled connections in a pool.
OracleJDBCConnectionPoolStatistics.connectionsCreatedCount OracleJDBCConnectionPoolStatistics.connectionsClosedCount    Counters for created and closed connections.
OracleJDBCConnectionPoolStatistics.averageConnectionWaitTime OracleJDBCConnectionPoolStatistics.peakConnectionWaitTime    Avaerage and peak times for a connections waiting to be borrowed.
OracleJDBCConnectionPoolStatistics.abandonedConnectionsCount    Counter for abandoned connections.
OracleJDBCConnectionPoolStatistics.pendingRequestsCount    Number of pending borrow requests at the current moment.
OracleJDBCConnectionPoolStatistics.cumulativeConnectionWaitTime OracleJDBCConnectionPoolStatistics.cumulativeConnectionBorrowedCount OracleJDBCConnectionPoolStatistics.cumulativeConnectionUseTime OracleJDBCConnectionPoolStatistics.cumulativeConnectionReturnedCount OracleJDBCConnectionPoolStatistics.cumulativeSuccessfulConnectionWaitTime OracleJDBCConnectionPoolStatistics.cumulativeSuccessfulConnectionWaitCount OracleJDBCConnectionPoolStatistics.cumulativeFailedConnectionWaitTime OracleJDBCConnectionPoolStatistics.cumulativeFailedConnectionWaitCount OracleJDBCConnectionPoolStatistics.cumulativeConnectionCreationAttemts OracleJDBCConnectionPoolStatistics.connectionCreationAttemptsSinceLastOutage    Various cumulative stats.
OracleJDBCConnectionPoolStatistics.shardConnectionStats

笔记：

  1. oracle.ucp.jdbc.UCP[XA]ConnectionBuilder — 这是 PoolDataSource.getConnection() 的替代方案，但允许为具体连接借用请求提供更多数据。它是使用 PoolDataSource.createConnectionBuilder() 创建的，可以根据需要从一个池数据源创建任意多个构建器，并且可以仅为一个借用请求或多个借用请求创建。
  2. oracle.ucp.jdbc.Pool[XA]DataSource — 标准池数据源。
  3. oracle.ucp.jdbc.PoolDataSourceFactory — 用于创建池数据源的工厂，包括读取 XML 或复杂多租户配置属性的方法。
  4. oracle.ucp.admin.UniversalConnectionPoolManager — UCP 管理器，可以处理一个 Java 应用程序中的多个池。
  5. oracle.ucp.jdbc.oracle.OracleJDBCConnectionPoolStatistics — 保存通用连接池统计信息快照的对象。

池指标映射

HikariCP metrics    UCP Metrics
Number of active connections    BorrowedConnectionsCount
Number of pending connection requests    PendingRequestsCount
Total number of timed-out requests    CumulativeFailedConnectionWaitCount
Time taken to get a connection    PeakConnectionWaitTime / AverageConnectionWaitTime
Current total number of connections    TotalConnectionsCount
Number of idle connections    AvailableConnectionsCount
Max number of connections    PeakConnectionsCount

我们通过定义以下属性来选择使用Oracle UCP（通用连接池）作为本机 Spring 数据源。请注意，此类属性需要高于 2.4.0 的 Spring Boot 版本。

spring.datasource.type=oracle.ucp.jdbc.PoolDataSource
spring.datasource.oracleucp.connection-pool-name=connectionPoolName1
spring.datasource.oracleucp.initial-pool-size=1
spring.datasource.oracleucp.min-pool-size=1
spring.datasource.oracleucp.max-pool-size=2
spring.datasource.oracleucp.connection-factory-class-name=oracle.jdbc.pool.OracleDataSource


我们还必须配置连接 URL、用户名和密码。

spring.datasource.url=<YOUR_JDBC_CONNECTION_URL>
spring.datasource.username=<YOUR_DB_USERNAME>
spring.datasource.password=<YOUR_DB_PASSWORD>

关于具体的UCP连接池设置，Spring Boot使用以下算法来选择具体的实现：
根据文档，HikariCP因其性能和并发性而成为首选。如果HikariCP可用，算法会选择它。

  • · 否则，如果Tomcat JDBC 连接池可用，则会选择它。
  • · 否则，如果Apache Commons DBCP2可用，则会选择它。
  • · 如果HikariCP、Tomcat 和DBCP2都不可用，而Oracle UCP可用，则选择它。

您可以完全绕过该算法并通过设置spring.datasource.type属性来指定要使用的连接池。这正是我们将在从 HikariCP 迁移到 Oracle 通用连接池 (UCP) 时执行的操作。

为此，我们将配置该属性，如下所示。这是从 HikariCP 切换到 Oracle UCP 的关键配置:
spring.datasource.type=oracle.ucp.jdbc.PoolDataSource

鉴于 UCP 提供了许多功能，这些功能将通过其坚如磐石的实现支持带来更好的性能，现在我们列出了可用于在 Spring Boot 中配置 UCP 的所有属性。
我们拥有所有属性的完整列表，您可以使用它来了解 UCP 的灵活性和强大性。
您可以使用示例application.properties文件，其中包含具有最常见 UCP 属性的基本配置。

我不会复制列出的这些 UCP 相关属性的文档。oracle.ucp.jdbc.PoolDataSource解释了这些属性，因此请检查Javadoc。
因此，列出绑定到 Oracle UCP PoolDataSource 实例的 Oracle UCP 特定设置只是为了您的方便，因为上面的 Javadoc 对它们有单独的解释。
PoolDataSource 在内部使用通用连接池，因此它的 setter 方法具有 UCP 池属性及其默认值。

spring.datasource.url
spring.datasource.username
spring.datasource.password
spring.datasource.driver-class-name
spring.datasource.type
spring.datasource.oracleucp.abandoned-connection-timeout
spring.datasource.oracleucp.connection-factory-class-name
spring.datasource.oracleucp.connection-factory-properties
spring.datasource.oracleucp.connection-harvest-max-count
spring.datasource.oracleucp.connection-harvest-trigger-count
spring.datasource.oracleucp.connection-labeling-high-cost
spring.datasource.oracleucp.connection-pool-name
spring.datasource.oracleucp.connection-properties
spring.datasource.oracleucp.connection-repurpose-threshold
spring.datasource.oracleucp.connection-validation-timeout
spring.datasource.oracleucp.connection-wait-timeout
spring.datasource.oracleucp.data-source-name
spring.datasource.oracleucp.database-name
spring.datasource.oracleucp.description
spring.datasource.oracleucp.fast-connection-failover-enabled
spring.datasource.oracleucp.high-cost-connection-reuse-threshold
spring.datasource.oracleucp.inactive-connection-timeout
spring.datasource.oracleucp.initial-pool-size
spring.datasource.oracleucp.login-timeout
spring.datasource.oracleucp.max-connection-reuse-count
spring.datasource.oracleucp.max-connection-reuse-time
spring.datasource.oracleucp.max-connections-per-shard
spring.datasource.oracleucp.max-idle-time
spring.datasource.oracleucp.max-pool-size
spring.datasource.oracleucp.max-statements
spring.datasource.oracleucp.min-pool-size
spring.datasource.oracleucp.network-protocol
spring.datasource.oracleucp.o-n-s-configuration
spring.datasource.oracleucp.pdb-roles
spring.datasource.oracleucp.port-number
spring.datasource.oracleucp.property-cycle
spring.datasource.oracleucp.query-timeout
spring.datasource.oracleucp.read-only-instance-allowed
spring.datasource.oracleucp.role-name
spring.datasource.oracleucp.s-q-l-for-validate-connection
spring.datasource.oracleucp.seconds-to-trust-idle-connection
spring.datasource.oracleucp.server-name
spring.datasource.oracleucp.sharding-mode
spring.datasource.oracleucp.time-to-live-connection-timeout
spring.datasource.oracleucp.timeout-check-interval
spring.datasource.oracleucp.u-r-l
spring.datasource.oracleucp.user
spring.datasource.oracleucp.validate-connection-on-borrow

关于 Spring Boot 3.2.0，以下链接包含记录的所有通用应用程序属性。

  • https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html
  • https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html
  • https://docs.spring.io/spring-boot/docs/3.2.0/reference/html/documentation.html
  • https://docs.spring.io/spring-boot/docs/3.2.0/reference/html/data.html

总结
Oracle通用连接池（UCP）是Oracle设计的一个基于Java JDBC的高性能连接池，旨在提高数据库访问的效率和性能。

UCP 提供了用于缓存 JDBC 连接的连接池实现。数据库密集型Java应用程序使用连接池来提高性能并更好地利用系统资源。UCP JDBC 连接池可以使用任何JDBC 驱动程序来创建物理连接，这令人惊讶，因为它不仅特定于 Oracle DB。

从从 HikariCP 迁移到 Oracle UCP 的角度来看，这篇博文介绍了 Oracle UCP 中可用的完整属性集，用于支持 Java 连接池的迁移和优化。

参考