A Guide to Migrating from HikariCP to Oracle UCP (Universal Connection Pool)

Juarez Junior

Published in

Oracle Developers

7 min readJan 18, 2024

Develop Java applications with Oracle Database

by Juarez Junior

Introduction

It is beyond the scope of this blog post to explain why using a database connection pool is essential. Check Overview of Connection Pool by Oracle to explore all the details about how connection pools work.

The goal of this blog post is to serve as a guide for migrating from HikariCP and the Oracle UCP (Universal Connection Pool) given that it is the recommendable approach when connecting to Oracle Databases.

So, without further ado, let us get started!

An Introduction to HikariCP

HikariCP is a JDBC connection pool used with Spring Boot applications.

From a Java Developer’s standpoint, in a nutshell, to use HikariCP as the connection pool in a Spring Boot application, you typically need to perform a few steps as usual when working with JDBC connection pooling.

If you’re using Spring Initializr, it’s interesting to know that spring-boot-starter-jdbc or spring-boot-starter-data-jpa include the dependency to HikariCP by default and in that when using those starters. So, excluding the dependency on HikariCP is advisable if you want to use UCP.

If you need an introduction to HikariCP, I advise you to check my colleagues’ blog post — HikariCP Best Practices for Oracle Database and Spring Boot, which covers HikariCP and uses Oracle JDBC version 19.21 (ojdbc8 dependency).

This blog post uses Oracle JDBC version 23.3 (ojdbc11 dependency) instead.

An Introduction to Oracle UCP

Oracle Universal Connection Pool (UCP) is a high-performance Java JDBC-based connection pool by Oracle designed to improve the efficiency and performance of database access.

A UCP JDBC connection pool can use any JDBC driver to create physical connections that are then maintained by the pool. The pool can be configured and provides a full set of properties that are used to optimize pool behaviour based on the performance and availability requirements of an application. For more advanced applications, UCP provides a pool manager that can be used to manage a pool instance.

The pool also leverages many high availability and performance features available through an Oracle Real Application Clusters (Oracle RAC) database. These features include Fast Connection Failover (FCF), Run-time connection Load Balancing (RLB), Connection Affinity, Sharding and Oracle Cloud Infrastructure database services (Autonomous Database, BaseDB).

Check the Universal Connection Pool Developer’s Guide for the complete reference and documentation concerning UCP.

Below we have a sample application.properties file with a minimal set of UCP properties as an example. We’ll explore some additional properties in detail in the remaining section.

application.properties

# OCI ORACLE AUTONOMOUS DATABASE connection
spring.datasource.url=<YOUR_JDBC_CONNECTION_URL>
spring.datasource.username=<YOUR_DB_USERNAME>
spring.datasource.password=<YOUR_DB_PASSWORD>

# Properties for UCP - Universal Connection Pool (UCP). Spring Boot 2.4.0 or above is required
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

Migrating from HikariCP to Oracle UCP

Now let’s have a look at how you can migrate from HikariCP to UCP.

The following steps present how to properly configure and allow connections from a Spring Boot application that uses the Oracle UCP (Oracle Connection Pool) as an alternative to HikariCP (default connection pool implementation in Spring Boot).

Firstly, to add UCP as a Maven dependency, you can explicitly add both the ojdbc11 and ucp11 artefacts.

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

Otherwise, you can use the Oracle Spring Boot Starters for UCP instead.

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

Besides, for completeness, we have summarized and mapped the related properties of both HikariCP and UCP beneath, with both pool properties and metrics via MBean.

So, for the connection pool properties, there are three sections:

HikariCP properties that have exact UCP equivalences

HikariCP properties that don’t have identical UCP properties to match but do have other mechanisms like driver properties or UCP APIs

UCP knobs that don’t exist in HikariCP

This is what you can have if you stay with the Oracle Universal Connection Pool. These properties are not available with HikariCP.

NOTES:

oracle.ucp.jdbc.UCP[XA]ConnectionBuilder — this is the alternative for PoolDataSource.getConnection(), but allows to feed more data for a concrete connection borrow request. It is being created with PoolDataSource.createConnectionBuilder(), can be created as many builders from one pool data source as needed, and can be created for just one borrow request or for many ones.
oracle.ucp.jdbc.Pool[XA]DataSource — the standard pool data source.
oracle.ucp.jdbc.PoolDataSourceFactory — factory for creating pool data source, including methods, that reads XML or properties for complex multi-tenant configurations.
oracle.ucp.admin.UniversalConnectionPoolManager — UCP manager that can handle many pools in one Java application.
oracle.ucp.jdbc.oracle.OracleJDBCConnectionPoolStatistics — the object holding a snapshot of Universal Connection Pool statistics.

Pool metrics mappings

Now, the application.properties file is highlighted below along with the section that shows the properties for UCP specifically.

UCP Connection Pool Properties — application.properties file

So, let’s opt for using the Oracle UCP (Universal Connection Pool as a native Spring Datasource by defining the following properties. Note that such properties require a Spring Boot version greater than 2.4.0.

Oracle’s UCP as a native Spring Datasource — application.properties

We also have to configure the connection URL, username, and password.

Oracle Autonomous Database connection details — application.properties

Concerning the specific UCP connection pool settings, Spring Boot uses the following algorithm for choosing a specific implementation:

Per the documentation, HikariCP is the preferred option for its performance and concurrency. If HikariCP is available, the algorithm chooses it.

· Otherwise, if the Tomcat JDBC Connection Pool is available, it gets selected.

· Otherwise, if the Apache Commons DBCP2 is available, it gets selected.

· If none of HikariCP, Tomcat, and DBCP2 are available and if Oracle UCP is available, it gets selected.

You can bypass that algorithm completely and specify the connection pool to use by setting the spring.datasource.type property. That’s exactly what we’ll perform concerning the migration from HikariCP to Oracle Universal Connection Pool (UCP).

In order to do so, we’ll configure the property as shown below. It is a crucial configuration regarding switching from HikariCP to Oracle UCP.

Given that UCP provides many features that will result in better performance supported by its rock-solid implementation, now we have listed all the properties you can use to configure UCP in Spring Boot.

We have the complete list of all the properties you can use to see how flexible and yet powerful the UCP is.

A sample application.properties file is available for you with a basic configuration with the most common UCP properties.

I won’t replicate the documentation for these UCP-related properties listed. The oracle.ucp.jdbc.PoolDataSource explains such properties, so please just check the Javadoc for it.

So, the Oracle UCP-specific settings bound to an instance of Oracle UCP’s PoolDataSource are listed just for your convenience, given that the Javadoc above has separate explanations for them.

PoolDataSource uses Universal Connection Pool internally, so its setter methods have the UCP pool properties and their default values.

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

Concerning Spring Boot 3.2.0, the links below include all the Common Application Properties as documented.

Wrap-up

Oracle Universal Connection Pool (UCP) is a high-performance Java JDBC-based connection pool by Oracle designed to improve the efficiency and performance of database access.

UCP provides a connection pool implementation for caching JDBC connections. Database-intensive Java applications use the connection pool to improve performance and better utilize system resources.
A UCP JDBC connection pool can use any JDBC driver to create physical connections, and that comes as a final surprise as it’s not only Oracle DB specific.

From a migration from HikariCP to Oracle UCP standpoint, this blog post presented the complete set of properties available in Oracle UCP to support migration and optimization of connection pools with Java.

I’d like to express my gratitude for the great feedback and support from my colleagues Jean de Lavarene, Yuri Dolgov, Tong Zhou, Kuassi Mensah, and Fernanda Meheust regarding this blog post and the related technical details.

Lastly, expect very soon a UCP Best Practices for Oracle Database and Spring Boot blog post. Watch the #JavaOracleDB hashtag.

That’s it! I hope you enjoyed this blog post, so stay tuned!

References

Oracle UCP (Universal Connection Pool)

Oracle Spring Boot Starters for UCP

Oracle Spring Boot Starters — GitHub

Using Spring and Spring Boot with Oracle Database

Spring Boot — Common Application Properties

HikariCP — GitHub

HikariCP Best Practices for Oracle Database and Spring Boot

Developers Guide For Oracle JDBC on Maven Central

Develop Java applications with Oracle Database

Oracle Developers and Oracle OCI Free Tier

Join our Oracle Developers channel on Slack to discuss Java, JDK, JDBC, GraalVM, Microservices with Spring Boot, Helidon, Quarkus, Micronaut, Reactive Streams, Cloud, DevOps, IaC, and other topics!

Build, test, and deploy your applications on Oracle Cloud — for free! Get access to OCI Cloud Free Tier!