How to Configure Universal Connection Pool in Hibernate Applications

Hibernate ORM is an object/relational framework for mapping Java application domain objects to/from RDBMS tables. Out-of-box, Hibernate supports open-source connection pools such as C3P0 and Proxool.

The Universal Connection Pool (UCP) is an Oracle Database 23ai feature-rich Java connection pool. In addition to the standard/traditional connection pooling features, UCP has been designed for seamless support for Cloud database services (Autonomous databases, BaseDB), scalability (Multi-tenant, Sharded databases) and high-availability during planned and unplanned database downtimes (Oracle Real Application Clusters (RAC) and Active Data Guard (ADG)).

Hibernate version 6.5 and higher supports UCP natively. This blog post walks you through how to configure UCP in standalone Java applications. 

The UCP properties must be configured in the hibernate.properties file with the “hibernate.oracleucp” prefix or in hibernate.cfg.xml file with the “oracleucp” prefix. Either file can be used to configure UCP, the result is the same.

Note: UCP properties must be provided in addition to hibernate connection properties.

Maven Dependency:

Add the hibernate-ucp, ojdbc and ucp dependencies to the maven project.

<dependency>
  <groupId>com.oracle.database.jdbc</groupId>
  <artifactId>ojdbc11</artifactId>
  <version>23.4.0.24.05</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>com.oracle.database.jdbc</groupId>
  <artifactId>ucp11</artifactId>
  <version>23.4.0.24.05</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-ucp</artifactId>
  <version>6.5.0.Final</version>
</dependency>

UCP configuration sample through hibernate.properties:

# mandatory properties to configure UCP
hibernate.connection.url=url
hibernate.connection.username=user
hibernate.connection.password=password
hibenrate.connection.driver_class=oracle.jdbc.OracleDriver
hibernate.oracleucp.connectionFactoryClassName=oracle.jdbc.datasource.impl.OracleDataSource

# all the following properties are optional, should be configured based on the requirement
hibernate.oracleucp.initialPoolSize=3
hibernate.oracleucp.minPoolSize=3
hibernate.oracleucp.maxPoolSize=5
hibernate.oracleucp.connectionPoolName=testucppool
hibernate.oracleucp.dataSourceName=myDatabaseSource1

# this syntax has to be followed for properties
hibernate.oracleucp.connectionProperties={autoCommit=false} 
#hibernate.oracleucp.connectionFactoryProperties={prop1=val1, prop2=val2, propN=valN}

hibernate.oracleucp.fastConnectionFailoverEnabled=false
hibernate.oracleucp.validateConnectionOnBorrow=true
hibernate.oracleucp.secondsToTrustIdleConnection=120
hibernate.oracleucp.inactiveConnectionTimeout=180
hibernate.oracleucp.maxStatements=20
hibernate.oracleucp.connectionWaitTimeout=30

Code sample

import org.hibernate.HibernateException;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.boot.Metadata;
import org.hibernate.boot.MetadataSources;
import org.hibernate.boot.registry.StandardServiceRegistry;
import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
import org.hibernate.jdbc.Work;

import java.sql.Connection;
import java.sql.SQLException;

public class HibernateUCPSample {

  public static void main( String[] args ) throws HibernateException {
    StandardServiceRegistry ssr = new StandardServiceRegistryBuilder().build();
    Metadata meta = new MetadataSources(ssr).getMetadataBuilder().build();

    SessionFactory factory = meta.getSessionFactoryBuilder().build();
    Session session = factory.openSession();
    
    session.doWork(new Work() {
      public void execute(Connection con) throws SQLException {
        // Prints the UCP proxy classname indicating that UCP is configured properly.
        System.out.println("Connection class: " + con.getClass());
      }
    });

    factory.close();
    session.close();
  }
}

Conclusion:

This guide covered configuring UCP with Java apps using Hibernate version 6.5 and above, including Maven setup, property configuration, and code sample. A sample code implementation of the same can be found in “oracle-db-examples” github repo. UCP ensures efficient pooling, optimizing resource usage for modern enterprise needs. With its robust features, UCP elevates reliability, scalability, and performance, making it a valuable asset for Hibernate applications across diverse deployment scenarios.