0
# Hibernate Integration
1

2
HikariCP provides native integration with Hibernate ORM through a dedicated connection provider implementation. This enables seamless use of HikariCP as the connection pool in Hibernate applications with proper configuration mapping and lifecycle management.
3

4
## Capabilities
5

6
### Hibernate Connection Provider
7

8
Native Hibernate connection provider implementation that integrates HikariCP connection pooling with Hibernate's connection management.
9

10
```java { .api }
11
/**
12
 * Hibernate connection provider implementation using HikariCP
13
 */
14
public class HikariConnectionProvider implements ConnectionProvider, Configurable, Stoppable {
15
    /**
16
     * Get a connection from the HikariCP pool for Hibernate use
17
     * @return Database connection from the pool
18
     * @throws SQLException If connection cannot be obtained
19
     */
20
    public Connection getConnection() throws SQLException;
21
    
22
    /**
23
     * Return a connection to the HikariCP pool
24
     * @param conn Connection to return to pool
25
     * @throws SQLException If connection cannot be returned
26
     */
27
    public void closeConnection(Connection conn) throws SQLException;
28
    
29
    /**
30
     * Check if this provider supports aggressive connection release
31
     * @return true if aggressive release is supported
32
     */
33
    public boolean supportsAggressiveRelease();
34
    
35
    /**
36
     * Check if provider can be unwrapped to specific type
37
     * @param unwrapType Type to check for unwrapping
38
     * @return true if unwrapping is supported
39
     */
40
    public boolean isUnwrappableAs(Class unwrapType);
41
    
42
    /**
43
     * Unwrap provider to specific type
44
     * @param unwrapType Type to unwrap to
45
     * @return Unwrapped instance
46
     */
47
    public <T> T unwrap(Class<T> unwrapType);
48
    
49
    /**
50
     * Configure the connection provider from Hibernate properties
51
     * @param props Hibernate configuration properties
52
     * @throws HibernateException If configuration fails
53
     */
54
    public void configure(Map props) throws HibernateException;
55
    
56
    /**
57
     * Stop the connection provider and shutdown connection pool
58
     */
59
    public void stop();
60
}
61
```
62

63
### Hibernate Configuration Utility
64

65
Utility class for mapping Hibernate properties to HikariCP configuration, handling property prefixes and type conversions.
66

67
```java { .api }
68
/**
69
 * Utility for mapping Hibernate properties to HikariCP configuration
70
 */
71
public class HikariConfigurationUtil {
72
    /**
73
     * Configuration property prefix for HikariCP settings in Hibernate
74
     */
75
    public static final String CONFIG_PREFIX = "hibernate.hikari.";
76
    
77
    /**
78
     * Configuration property prefix for DataSource properties
79
     */
80
    public static final String CONFIG_PREFIX_DATASOURCE = "hibernate.hikari.dataSource.";
81
    
82
    /**
83
     * Create HikariConfig from Hibernate properties
84
     * @param props Hibernate configuration properties map
85
     * @return Configured HikariConfig instance
86
     */
87
    public static HikariConfig loadConfiguration(Map props);
88
}
89
```
90

91
## Configuration
92

93
### Hibernate Configuration File
94

95
Configure HikariCP as the connection provider in your Hibernate configuration:
96

97
**hibernate.cfg.xml:**
98

99
```xml
100
<?xml version="1.0" encoding="utf-8"?>
101
<!DOCTYPE hibernate-configuration PUBLIC
102
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
103
        "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
104
<hibernate-configuration>
105
    <session-factory>
106
        <!-- HikariCP Connection Provider -->
107
        <property name="hibernate.connection.provider_class">com.zaxxer.hikari.hibernate.HikariConnectionProvider</property>
108
        
109
        <!-- Database connection settings -->
110
        <property name="hibernate.hikari.jdbcUrl">jdbc:mysql://localhost:3306/mydb</property>
111
        <property name="hibernate.hikari.username">dbuser</property>
112
        <property name="hibernate.hikari.password">dbpass</property>
113
        <property name="hibernate.hikari.driverClassName">com.mysql.cj.jdbc.Driver</property>
114
        
115
        <!-- HikariCP pool settings -->
116
        <property name="hibernate.hikari.maximumPoolSize">10</property>
117
        <property name="hibernate.hikari.minimumIdle">5</property>
118
        <property name="hibernate.hikari.connectionTimeout">20000</property>
119
        <property name="hibernate.hikari.idleTimeout">300000</property>
120
        <property name="hibernate.hikari.maxLifetime">1200000</property>
121
        <property name="hibernate.hikari.leakDetectionThreshold">60000</property>
122
        
123
        <!-- DataSource properties -->
124
        <property name="hibernate.hikari.dataSource.cachePrepStmts">true</property>
125
        <property name="hibernate.hikari.dataSource.prepStmtCacheSize">250</property>
126
        <property name="hibernate.hikari.dataSource.prepStmtCacheSqlLimit">2048</property>
127
        
128
        <!-- Other Hibernate settings -->
129
        <property name="hibernate.dialect">org.hibernate.dialect.MySQL8Dialect</property>
130
        <property name="hibernate.show_sql">false</property>
131
        <property name="hibernate.format_sql">true</property>
132
    </session-factory>
133
</hibernate-configuration>
134
```
135

136
### Properties File Configuration
137

138
**hibernate.properties:**
139

140
```properties
141
# Connection provider
142
hibernate.connection.provider_class=com.zaxxer.hikari.hibernate.HikariConnectionProvider
143

144
# Database connection
145
hibernate.hikari.jdbcUrl=jdbc:mysql://localhost:3306/mydb
146
hibernate.hikari.username=dbuser
147
hibernate.hikari.password=dbpass
148
hibernate.hikari.driverClassName=com.mysql.cj.jdbc.Driver
149

150
# Pool configuration
151
hibernate.hikari.maximumPoolSize=10
152
hibernate.hikari.minimumIdle=5
153
hibernate.hikari.connectionTimeout=20000
154
hibernate.hikari.idleTimeout=300000
155
hibernate.hikari.maxLifetime=1200000
156
hibernate.hikari.poolName=HibernatePool
157

158
# DataSource properties
159
hibernate.hikari.dataSource.cachePrepStmts=true
160
hibernate.hikari.dataSource.prepStmtCacheSize=250
161
hibernate.hikari.dataSource.prepStmtCacheSqlLimit=2048
162

163
# Hibernate settings
164
hibernate.dialect=org.hibernate.dialect.MySQL8Dialect
165
hibernate.show_sql=false
166
```
167

168
### Programmatic Configuration
169

170
Configure HikariCP connection provider programmatically:
171

172
```java
173
import org.hibernate.SessionFactory;
174
import org.hibernate.cfg.Configuration;
175

176
// Create Hibernate configuration
177
Configuration configuration = new Configuration();
178

179
// Set connection provider
180
configuration.setProperty("hibernate.connection.provider_class", 
181
    "com.zaxxer.hikari.hibernate.HikariConnectionProvider");
182

183
// Database connection settings
184
configuration.setProperty("hibernate.hikari.jdbcUrl", "jdbc:mysql://localhost:3306/mydb");
185
configuration.setProperty("hibernate.hikari.username", "dbuser");
186
configuration.setProperty("hibernate.hikari.password", "dbpass");
187
configuration.setProperty("hibernate.hikari.driverClassName", "com.mysql.cj.jdbc.Driver");
188

189
// Pool settings
190
configuration.setProperty("hibernate.hikari.maximumPoolSize", "10");
191
configuration.setProperty("hibernate.hikari.minimumIdle", "5");
192
configuration.setProperty("hibernate.hikari.connectionTimeout", "20000");
193
configuration.setProperty("hibernate.hikari.idleTimeout", "300000");
194
configuration.setProperty("hibernate.hikari.maxLifetime", "1200000");
195

196
// DataSource properties
197
configuration.setProperty("hibernate.hikari.dataSource.cachePrepStmts", "true");
198
configuration.setProperty("hibernate.hikari.dataSource.prepStmtCacheSize", "250");
199

200
// Build session factory
201
SessionFactory sessionFactory = configuration.buildSessionFactory();
202
```
203

204
## Property Mapping
205

206
HikariCP properties in Hibernate configuration are prefixed with `hibernate.hikari.` and map directly to HikariConfig properties:
207

208
| Hibernate Property | HikariConfig Property | Description |
209
|---|---|---|
210
| `hibernate.hikari.jdbcUrl` | `jdbcUrl` | JDBC connection URL |
211
| `hibernate.hikari.username` | `username` | Database username |
212
| `hibernate.hikari.password` | `password` | Database password |
213
| `hibernate.hikari.driverClassName` | `driverClassName` | JDBC driver class |
214
| `hibernate.hikari.maximumPoolSize` | `maximumPoolSize` | Maximum pool size |
215
| `hibernate.hikari.minimumIdle` | `minimumIdle` | Minimum idle connections |
216
| `hibernate.hikari.connectionTimeout` | `connectionTimeout` | Connection timeout (ms) |
217
| `hibernate.hikari.idleTimeout` | `idleTimeout` | Idle timeout (ms) |
218
| `hibernate.hikari.maxLifetime` | `maxLifetime` | Max connection lifetime (ms) |
219
| `hibernate.hikari.poolName` | `poolName` | Pool name for monitoring |
220
221
DataSource properties use the `hibernate.hikari.dataSource.` prefix and are passed through to the underlying DataSource implementation.
222

223
## Usage Example
224

225
Complete example of using HikariCP with Hibernate:
226

227
```java
228
import org.hibernate.Session;
229
import org.hibernate.SessionFactory;
230
import org.hibernate.cfg.Configuration;
231
import org.hibernate.query.Query;
232

233
public class HibernateHikariExample {
234
    private SessionFactory sessionFactory;
235
    
236
    public void initHibernate() {
237
        Configuration configuration = new Configuration();
238
        
239
        // Configure HikariCP connection provider
240
        configuration.setProperty("hibernate.connection.provider_class", 
241
            "com.zaxxer.hikari.hibernate.HikariConnectionProvider");
242
        configuration.setProperty("hibernate.hikari.jdbcUrl", 
243
            "jdbc:mysql://localhost:3306/mydb");
244
        configuration.setProperty("hibernate.hikari.username", "dbuser");
245
        configuration.setProperty("hibernate.hikari.password", "dbpass");
246
        configuration.setProperty("hibernate.hikari.maximumPoolSize", "10");
247
        
248
        // Add entity classes
249
        configuration.addAnnotatedClass(User.class);
250
        
251
        // Build session factory
252
        sessionFactory = configuration.buildSessionFactory();
253
    }
254
    
255
    public void performDatabaseOperation() {
256
        try (Session session = sessionFactory.openSession()) {
257
            session.beginTransaction();
258
            
259
            // Perform database operations
260
            Query<User> query = session.createQuery("FROM User", User.class);
261
            List<User> users = query.getResultList();
262
            
263
            session.getTransaction().commit();
264
        }
265
    }
266
    
267
    public void shutdown() {
268
        if (sessionFactory != null) {
269
            sessionFactory.close();
270
        }
271
    }
272
}
273
```
274

275
The HikariCP connection provider automatically handles connection lifecycle management, ensuring connections are properly returned to the pool after Hibernate operations complete.