0
# Hibernate Integration
1

2
Native integration with Hibernate ORM framework, providing seamless connection pooling for Hibernate applications with automatic property mapping, lifecycle management, and support for Hibernate 4.3+ ConnectionProvider interface.
3

4
## Capabilities
5

6
### HikariConnectionProvider
7

8
Hibernate 4.3+ ConnectionProvider implementation that integrates HikariCP as the connection pool for Hibernate applications.
9

10
```java { .api }
11
public class HikariConnectionProvider implements ConnectionProvider, Configurable, Stoppable {
12
    /**
13
     * Default constructor.
14
     */
15
    public HikariConnectionProvider();
16
    
17
    /**
18
     * Configure the connection provider from Hibernate properties.
19
     * Properties with prefix "hibernate.hikari." are mapped to HikariConfig.
20
     * 
21
     * @param props Hibernate configuration properties (raw Map type)
22
     * @throws HibernateException on configuration error
23
     */
24
    @SuppressWarnings("rawtypes")
25
    public void configure(Map props) throws HibernateException;
26
    
27
    /**
28
     * Get connection from the HikariCP pool.
29
     * 
30
     * @return Connection from the pool
31
     * @throws SQLException if connection cannot be obtained
32
     */
33
    public Connection getConnection() throws SQLException;
34
    
35
    /**
36
     * Close/return connection to the pool.
37
     * 
38
     * @param conn connection to close
39
     * @throws SQLException on error
40
     */
41
    public void closeConnection(Connection conn) throws SQLException;
42
    
43
    /**
44
     * Returns false - HikariCP does not support aggressive connection release.
45
     * 
46
     * @return false
47
     */
48
    public boolean supportsAggressiveRelease();
49
    
50
    /**
51
     * Check if the provider can be unwrapped to the specified type.
52
     * 
53
     * @param unwrapType target type
54
     * @return true if unwrapping is supported
55
     */
56
    public boolean isUnwrappableAs(Class unwrapType);
57
    
58
    /**
59
     * Unwrap the provider to the specified type.
60
     * 
61
     * @param unwrapType target type
62
     * @return unwrapped instance
63
     */
64
    public <T> T unwrap(Class<T> unwrapType);
65
    
66
    /**
67
     * Stop the connection provider and shutdown the connection pool.
68
     */
69
    public void stop();
70
}
71
```
72

73
### HikariConfigurationUtil
74

75
Utility class for mapping Hibernate properties to HikariCP configuration with proper property name translation and type conversion.
76

77
```java { .api }
78
public class HikariConfigurationUtil {
79
    /**
80
     * Configuration property prefix for HikariCP properties in Hibernate configuration.
81
     */
82
    public static final String CONFIG_PREFIX = "hibernate.hikari.";
83
    
84
    /**
85
     * Configuration property prefix for DataSource properties in Hibernate configuration.
86
     */
87
    public static final String CONFIG_PREFIX_DATASOURCE = "hibernate.hikari.dataSource.";
88
    
89
    /**
90
     * Create HikariConfig from Hibernate properties map.
91
     * Processes properties with "hibernate.hikari." prefix and maps them
92
     * to corresponding HikariConfig properties.
93
     * 
94
     * @param props Hibernate properties map (raw Map type)
95
     * @return configured HikariConfig instance
96
     */
97
    @SuppressWarnings("rawtypes")
98
    public static HikariConfig loadConfiguration(Map props);
99
}
100
```
101

102
## Usage Examples
103

104
### Basic Hibernate Configuration
105

106
#### hibernate.cfg.xml Configuration
107

108
```xml
109
<?xml version="1.0" encoding="UTF-8"?>
110
<!DOCTYPE hibernate-configuration PUBLIC 
111
    "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
112
    "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
113

114
<hibernate-configuration>
115
    <session-factory>
116
        <!-- Use HikariCP as connection provider -->
117
        <property name="hibernate.connection.provider_class">
118
            com.zaxxer.hikari.hibernate.HikariConnectionProvider
119
        </property>
120
        
121
        <!-- Database connection settings -->
122
        <property name="hibernate.hikari.jdbcUrl">jdbc:postgresql://localhost/mydb</property>
123
        <property name="hibernate.hikari.username">user</property>
124
        <property name="hibernate.hikari.password">password</property>
125
        <property name="hibernate.hikari.driverClassName">org.postgresql.Driver</property>
126
        
127
        <!-- Pool configuration -->
128
        <property name="hibernate.hikari.maximumPoolSize">20</property>
129
        <property name="hibernate.hikari.minimumIdle">5</property>
130
        <property name="hibernate.hikari.connectionTimeout">20000</property>
131
        <property name="hibernate.hikari.idleTimeout">300000</property>
132
        <property name="hibernate.hikari.maxLifetime">1200000</property>
133
        <property name="hibernate.hikari.poolName">HibernatePool</property>
134
        
135
        <!-- Hibernate settings -->
136
        <property name="hibernate.dialect">org.hibernate.dialect.PostgreSQLDialect</property>
137
        <property name="hibernate.show_sql">false</property>
138
        <property name="hibernate.hbm2ddl.auto">validate</property>
139
    </session-factory>
140
</hibernate-configuration>
141
```
142

143
#### hibernate.properties Configuration
144

145
```properties
146
# Connection provider
147
hibernate.connection.provider_class=com.zaxxer.hikari.hibernate.HikariConnectionProvider
148

149
# Database configuration
150
hibernate.hikari.jdbcUrl=jdbc:mysql://localhost:3306/myapp
151
hibernate.hikari.username=appuser
152
hibernate.hikari.password=apppass
153
hibernate.hikari.driverClassName=com.mysql.jdbc.Driver
154

155
# Pool sizing
156
hibernate.hikari.maximumPoolSize=25
157
hibernate.hikari.minimumIdle=5
158

159
# Timeouts (in milliseconds)
160
hibernate.hikari.connectionTimeout=30000
161
hibernate.hikari.idleTimeout=600000
162
hibernate.hikari.maxLifetime=1800000
163

164
# Pool management
165
hibernate.hikari.poolName=MyAppHibernatePool
166
hibernate.hikari.registerMbeans=true
167
hibernate.hikari.leakDetectionThreshold=60000
168

169
# DataSource properties (for DataSource-based configuration)
170
hibernate.hikari.dataSource.url=jdbc:mysql://localhost:3306/myapp
171
hibernate.hikari.dataSource.user=appuser
172
hibernate.hikari.dataSource.password=apppass
173
hibernate.hikari.dataSource.cachePrepStmts=true
174
hibernate.hikari.dataSource.prepStmtCacheSize=250
175
hibernate.hikari.dataSource.prepStmtCacheSqlLimit=2048
176

177
# Hibernate ORM settings
178
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
179
hibernate.show_sql=false
180
hibernate.format_sql=true
181
hibernate.hbm2ddl.auto=validate
182
```
183

184
### Programmatic Configuration
185

186
```java
187
import org.hibernate.SessionFactory;
188
import org.hibernate.cfg.Configuration;
189
import com.zaxxer.hikari.hibernate.HikariConnectionProvider;
190

191
// Create Hibernate Configuration
192
Configuration configuration = new Configuration();
193

194
// Set HikariCP as connection provider
195
configuration.setProperty("hibernate.connection.provider_class", 
196
    HikariConnectionProvider.class.getName());
197

198
// Database settings
199
configuration.setProperty("hibernate.hikari.jdbcUrl", "jdbc:h2:mem:testdb");
200
configuration.setProperty("hibernate.hikari.username", "sa");
201
configuration.setProperty("hibernate.hikari.password", "");
202
configuration.setProperty("hibernate.hikari.driverClassName", "org.h2.Driver");
203

204
// Pool configuration
205
configuration.setProperty("hibernate.hikari.maximumPoolSize", "10");
206
configuration.setProperty("hibernate.hikari.minimumIdle", "2");
207
configuration.setProperty("hibernate.hikari.connectionTimeout", "20000");
208
configuration.setProperty("hibernate.hikari.poolName", "H2TestPool");
209

210
// Hibernate settings
211
configuration.setProperty("hibernate.dialect", "org.hibernate.dialect.H2Dialect");
212
configuration.setProperty("hibernate.hbm2ddl.auto", "create-drop");
213
configuration.setProperty("hibernate.show_sql", "true");
214

215
// Add entity classes
216
configuration.addAnnotatedClass(User.class);
217
configuration.addAnnotatedClass(Order.class);
218

219
// Build SessionFactory
220
SessionFactory sessionFactory = configuration.buildSessionFactory();
221
```
222

223
### Spring Framework Integration
224

225
```java
226
import org.springframework.context.annotation.Bean;
227
import org.springframework.context.annotation.Configuration;
228
import org.springframework.orm.hibernate5.LocalSessionFactoryBean;
229
import javax.sql.DataSource;
230
import java.util.Properties;
231

232
@Configuration
233
public class HibernateConfig {
234
    
235
    @Bean
236
    public LocalSessionFactoryBean sessionFactory() {
237
        LocalSessionFactoryBean sessionFactory = new LocalSessionFactoryBean();
238
        
239
        // Set packages to scan for entities
240
        sessionFactory.setPackagesToScan("com.myapp.entities");
241
        
242
        // Configure Hibernate properties
243
        Properties hibernateProperties = new Properties();
244
        
245
        // Use HikariCP connection provider
246
        hibernateProperties.setProperty("hibernate.connection.provider_class",
247
            "com.zaxxer.hikari.hibernate.HikariConnectionProvider");
248
        
249
        // Database connection
250
        hibernateProperties.setProperty("hibernate.hikari.jdbcUrl", 
251
            "jdbc:postgresql://localhost/myapp");
252
        hibernateProperties.setProperty("hibernate.hikari.username", "appuser");
253
        hibernateProperties.setProperty("hibernate.hikari.password", "apppass");
254
        
255
        // Pool configuration
256
        hibernateProperties.setProperty("hibernate.hikari.maximumPoolSize", "20");
257
        hibernateProperties.setProperty("hibernate.hikari.minimumIdle", "5");
258
        hibernateProperties.setProperty("hibernate.hikari.connectionTimeout", "30000");
259
        hibernateProperties.setProperty("hibernate.hikari.poolName", "SpringHibernatePool");
260
        hibernateProperties.setProperty("hibernate.hikari.registerMbeans", "true");
261
        
262
        // Hibernate configuration
263
        hibernateProperties.setProperty("hibernate.dialect", 
264
            "org.hibernate.dialect.PostgreSQLDialect");
265
        hibernateProperties.setProperty("hibernate.show_sql", "false");
266
        hibernateProperties.setProperty("hibernate.hbm2ddl.auto", "validate");
267
        
268
        sessionFactory.setHibernateProperties(hibernateProperties);
269
        
270
        return sessionFactory;
271
    }
272
}
273
```
274

275
### Advanced Configuration with DataSource Properties
276

277
```java
278
// Configure MySQL-specific DataSource properties for optimal performance
279
Properties hibernateProps = new Properties();
280

281
// Connection provider
282
hibernateProps.setProperty("hibernate.connection.provider_class",
283
    "com.zaxxer.hikari.hibernate.HikariConnectionProvider");
284

285
// Basic connection settings
286
hibernateProps.setProperty("hibernate.hikari.dataSourceClassName",
287
    "com.mysql.jdbc.jdbc2.optional.MysqlDataSource");
288

289
// DataSource-specific properties for MySQL optimization
290
hibernateProps.setProperty("hibernate.hikari.dataSource.url", 
291
    "jdbc:mysql://localhost:3306/myapp?useSSL=false&serverTimezone=UTC");
292
hibernateProps.setProperty("hibernate.hikari.dataSource.user", "appuser");
293
hibernateProps.setProperty("hibernate.hikari.dataSource.password", "apppass");
294

295
// MySQL connection optimization
296
hibernateProps.setProperty("hibernate.hikari.dataSource.cachePrepStmts", "true");
297
hibernateProps.setProperty("hibernate.hikari.dataSource.prepStmtCacheSize", "250");
298
hibernateProps.setProperty("hibernate.hikari.dataSource.prepStmtCacheSqlLimit", "2048");
299
hibernateProps.setProperty("hibernate.hikari.dataSource.useServerPrepStmts", "true");
300
hibernateProps.setProperty("hibernate.hikari.dataSource.useLocalSessionState", "true");
301
hibernateProps.setProperty("hibernate.hikari.dataSource.rewriteBatchedStatements", "true");
302
hibernateProps.setProperty("hibernate.hikari.dataSource.cacheResultSetMetadata", "true");
303
hibernateProps.setProperty("hibernate.hikari.dataSource.cacheServerConfiguration", "true");
304
hibernateProps.setProperty("hibernate.hikari.dataSource.elideSetAutoCommits", "true");
305
hibernateProps.setProperty("hibernate.hikari.dataSource.maintainTimeStats", "false");
306

307
// Pool configuration for high-load application
308
hibernateProps.setProperty("hibernate.hikari.maximumPoolSize", "50");
309
hibernateProps.setProperty("hibernate.hikari.minimumIdle", "10");
310
hibernateProps.setProperty("hibernate.hikari.connectionTimeout", "20000");
311
hibernateProps.setProperty("hibernate.hikari.idleTimeout", "300000");
312
hibernateProps.setProperty("hibernate.hikari.maxLifetime", "1200000");
313
hibernateProps.setProperty("hibernate.hikari.poolName", "HighLoadAppPool");
314
hibernateProps.setProperty("hibernate.hikari.registerMbeans", "true");
315
hibernateProps.setProperty("hibernate.hikari.leakDetectionThreshold", "120000");
316
```
317

318
### Property Name Mapping
319

320
HikariCP properties are prefixed with `hibernate.hikari.` in Hibernate configuration:
321

322
| HikariConfig Property | Hibernate Property |
323
|----------------------|-------------------|
324
| `jdbcUrl` | `hibernate.hikari.jdbcUrl` |
325
| `username` | `hibernate.hikari.username` |
326
| `password` | `hibernate.hikari.password` |
327
| `maximumPoolSize` | `hibernate.hikari.maximumPoolSize` |
328
| `minimumIdle` | `hibernate.hikari.minimumIdle` |
329
| `connectionTimeout` | `hibernate.hikari.connectionTimeout` |
330
| `idleTimeout` | `hibernate.hikari.idleTimeout` |
331
| `maxLifetime` | `hibernate.hikari.maxLifetime` |
332
| `poolName` | `hibernate.hikari.poolName` |
333
| `registerMbeans` | `hibernate.hikari.registerMbeans` |
334
335
DataSource properties use the `hibernate.hikari.dataSource.` prefix:
336

337
| DataSource Property | Hibernate Property |
338
|--------------------|-------------------|
339
| `url` | `hibernate.hikari.dataSource.url` |
340
| `user` | `hibernate.hikari.dataSource.user` |
341
| `password` | `hibernate.hikari.dataSource.password` |
342
| `cachePrepStmts` | `hibernate.hikari.dataSource.cachePrepStmts` |
343
344
### Monitoring Hibernate Connection Usage
345

346
```java
347
import org.hibernate.SessionFactory;
348
import org.hibernate.engine.jdbc.connections.spi.ConnectionProvider;
349
import com.zaxxer.hikari.hibernate.HikariConnectionProvider;
350
import com.zaxxer.hikari.HikariDataSource;
351

352
// Access HikariDataSource from Hibernate SessionFactory
353
SessionFactory sessionFactory = // ... your session factory
354
ConnectionProvider connectionProvider = sessionFactory.getSessionFactoryOptions()
355
    .getServiceRegistry()
356
    .getService(ConnectionProvider.class);
357

358
if (connectionProvider instanceof HikariConnectionProvider) {
359
    HikariConnectionProvider hikariProvider = (HikariConnectionProvider) connectionProvider;
360
    
361
    // Unwrap to get HikariDataSource for monitoring
362
    HikariDataSource dataSource = hikariProvider.unwrap(HikariDataSource.class);
363
    
364
    // Access pool statistics via JMX or direct monitoring
365
    String poolName = dataSource.getPoolName();
366
    System.out.println("Hibernate using HikariCP pool: " + poolName);
367
}
368
```
369

370
### Troubleshooting
371

372
Common configuration issues and solutions:
373

374
```java
375
// Issue: Connection pool not being used
376
// Solution: Ensure correct provider class name
377
hibernateProps.setProperty("hibernate.connection.provider_class",
378
    "com.zaxxer.hikari.hibernate.HikariConnectionProvider");  // Correct
379
// NOT: "com.zaxxer.hikari.HikariConnectionProvider"          // Incorrect
380

381
// Issue: Properties not being applied
382
// Solution: Use correct property prefix
383
hibernateProps.setProperty("hibernate.hikari.maximumPoolSize", "20");  // Correct
384
// NOT: "hikari.maximumPoolSize"                                       // Incorrect
385

386
// Issue: DataSource properties ignored
387
// Solution: Use dataSource prefix for vendor-specific properties
388
hibernateProps.setProperty("hibernate.hikari.dataSource.cachePrepStmts", "true");  // Correct
389
// NOT: "hibernate.hikari.cachePrepStmts"                                          // Incorrect
390

391
// Issue: Pool not shutting down properly
392
// Solution: Ensure proper SessionFactory lifecycle management
393
sessionFactory.close();  // This will trigger HikariConnectionProvider.stop()
394
```