0
# HikariCP
1

2
HikariCP is a high-performance JDBC connection pool library designed for production environments. It provides a lightweight (approximately 90KB), zero-overhead connection pool that focuses on speed, simplicity, and reliability. HikariCP offers comprehensive connection management with features including connection timeout handling, pool size configuration, connection validation, metrics integration with Dropwizard and Prometheus, leak detection, and JMX monitoring capabilities.
3

4
## Package Information
5

6
- **Package Name**: HikariCP-java7
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>com.zaxxer</groupId>
13
      <artifactId>HikariCP-java7</artifactId>
14
      <version>2.4.13</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.zaxxer.hikari.HikariConfig;
22
import com.zaxxer.hikari.HikariDataSource;
23
```
24

25
For JMX management:
26
```java
27
import com.zaxxer.hikari.HikariConfigMXBean;
28
import com.zaxxer.hikari.HikariPoolMXBean;
29
```
30

31
For metrics integration:
32
```java
33
import com.zaxxer.hikari.metrics.MetricsTracker;
34
import com.zaxxer.hikari.metrics.MetricsTrackerFactory;
35
import com.zaxxer.hikari.metrics.PoolStats;
36
```
37

38
For framework integration:
39
```java
40
import com.zaxxer.hikari.hibernate.HikariConnectionProvider;
41
import com.zaxxer.hikari.HikariJNDIFactory;
42
```
43

44
Standard Java imports needed:
45
```java
46
import java.sql.Connection;
47
import java.sql.SQLException;
48
import java.sql.SQLFeatureNotSupportedException;
49
import java.io.PrintWriter;
50
import java.io.Closeable;
51
import java.util.Properties;
52
import java.util.concurrent.ScheduledExecutorService;
53
import java.util.concurrent.ThreadFactory;
54
import javax.sql.DataSource;
55
```
56

57
## Basic Usage
58

59
```java
60
import com.zaxxer.hikari.HikariConfig;
61
import com.zaxxer.hikari.HikariDataSource;
62
import java.sql.Connection;
63
import java.sql.SQLException;
64

65
// Configuration-based setup (recommended)
66
HikariConfig config = new HikariConfig();
67
config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
68
config.setUsername("user");
69
config.setPassword("password");
70
config.setMaximumPoolSize(20);
71
config.setMinimumIdle(5);
72
config.setConnectionTestQuery("SELECT 1");
73

74
HikariDataSource dataSource = new HikariDataSource(config);
75

76
// Get connections from the pool
77
try (Connection connection = dataSource.getConnection()) {
78
    // Use the connection for database operations
79
    // Connection is automatically returned to pool when closed
80
}
81

82
// Clean shutdown
83
dataSource.close();
84
```
85

86
## Architecture
87

88
HikariCP is built around several key components:
89

90
- **HikariDataSource**: Main pooled DataSource implementation extending standard JDBC DataSource
91
- **HikariConfig**: Comprehensive configuration class with all pool settings and validation
92
- **Connection Pool Management**: High-performance connection pool with configurable sizing and timeouts
93
- **JMX Integration**: Runtime monitoring and management through HikariPoolMXBean and HikariConfigMXBean
94
- **Metrics Integration**: Pluggable metrics system supporting Dropwizard Metrics and Prometheus
95
- **Leak Detection**: Built-in connection leak detection and reporting
96
- **Framework Integration**: Native integration with Hibernate and JNDI environments
97

98
## Capabilities
99

100
### Connection Pool Management
101

102
Core connection pooling functionality providing high-performance JDBC connection management with configurable pool sizing and connection lifecycle management.
103

104
```java { .api }
105
public class HikariDataSource extends HikariConfig implements DataSource, Closeable {
106
    // Constructors
107
    public HikariDataSource();
108
    public HikariDataSource(HikariConfig configuration);
109
    
110
    // DataSource methods
111
    public Connection getConnection() throws SQLException;
112
    public Connection getConnection(String username, String password) throws SQLException;
113
    public PrintWriter getLogWriter() throws SQLException;
114
    public void setLogWriter(PrintWriter out) throws SQLException;
115
    public void setLoginTimeout(int seconds) throws SQLException;
116
    public int getLoginTimeout() throws SQLException;
117
    public java.util.logging.Logger getParentLogger() throws SQLFeatureNotSupportedException;
118
    public <T> T unwrap(Class<T> iface) throws SQLException;
119
    public boolean isWrapperFor(Class<?> iface) throws SQLException;
120
    
121
    // Pool management and lifecycle
122
    public void close();
123
    public boolean isClosed();
124
    public void evictConnection(Connection connection);
125
    @Deprecated
126
    public void suspendPool();
127
    @Deprecated
128
    public void resumePool();
129
    @Deprecated
130
    public void shutdown();
131
    
132
    // JMX and monitoring
133
    public HikariPoolMXBean getHikariPoolMXBean();
134
    public HikariConfigMXBean getHikariConfigMXBean();
135
    
136
    // Metrics configuration
137
    public void setMetricRegistry(Object metricRegistry);
138
    public void setMetricsTrackerFactory(MetricsTrackerFactory metricsTrackerFactory);
139
    public void setHealthCheckRegistry(Object healthCheckRegistry);
140
}
141
```
142

143
[Connection Pool Management](./connection-pool.md)
144

145
### Configuration Management
146

147
Comprehensive configuration system with over 30 configuration properties for fine-tuning pool behavior, connection settings, and performance optimization.
148

149
```java { .api }
150
public class HikariConfig implements HikariConfigMXBean {
151
    // Constructors
152
    public HikariConfig();
153
    public HikariConfig(Properties properties);
154
    public HikariConfig(String propertyFileName);
155
    
156
    // Essential configuration setters
157
    public void setJdbcUrl(String jdbcUrl);
158
    public void setDataSourceClassName(String className);
159
    public void setUsername(String username);
160
    public void setPassword(String password);
161
    public void setDataSource(DataSource dataSource);
162
    public void setDataSourceJNDI(String jndiDataSource);
163
    public void setDriverClassName(String driverClassName);
164
    
165
    // Essential configuration getters
166
    public String getJdbcUrl();
167
    public String getDataSourceClassName();
168
    public String getUsername();
169
    public String getPassword();
170
    public DataSource getDataSource();
171
    public String getDataSourceJNDI();
172
    public String getDriverClassName();
173
    
174
    // Pool sizing
175
    public void setMaximumPoolSize(int maxPoolSize);
176
    public void setMinimumIdle(int minIdle);
177
    public int getMaximumPoolSize();
178
    public int getMinimumIdle();
179
    
180
    // Timeouts
181
    public void setConnectionTimeout(long connectionTimeoutMs);
182
    public void setValidationTimeout(long validationTimeoutMs);
183
    public void setIdleTimeout(long idleTimeoutMs);
184
    public void setMaxLifetime(long maxLifetimeMs);
185
    public void setLeakDetectionThreshold(long leakDetectionThresholdMs);
186
    public void setInitializationFailTimeout(long initializationFailTimeout);
187
    public long getConnectionTimeout();
188
    public long getValidationTimeout();
189
    public long getIdleTimeout();
190
    public long getMaxLifetime();
191
    public long getLeakDetectionThreshold();
192
    public long getInitializationFailTimeout();
193
    
194
    // Connection settings
195
    public void setAutoCommit(boolean isAutoCommit);
196
    public void setReadOnly(boolean readOnly);
197
    public void setCatalog(String catalog);
198
    public void setTransactionIsolation(String isolationLevel);
199
    public void setConnectionTestQuery(String connectionTestQuery);
200
    public void setConnectionInitSql(String connectionInitSql);
201
    public boolean isAutoCommit();
202
    public boolean isReadOnly();
203
    public String getCatalog();
204
    public String getTransactionIsolation();
205
    public String getConnectionTestQuery();
206
    public String getConnectionInitSql();
207
    
208
    // Pool management
209
    public void setAllowPoolSuspension(boolean isAllowPoolSuspension);
210
    public void setIsolateInternalQueries(boolean isolate);
211
    public void setRegisterMbeans(boolean register);
212
    public void setPoolName(String poolName);
213
    public boolean isAllowPoolSuspension();
214
    public boolean isIsolateInternalQueries();
215
    public boolean isRegisterMbeans();
216
    public String getPoolName();
217
    
218
    // Threading and scheduling
219
    public void setThreadFactory(ThreadFactory threadFactory);
220
    public void setScheduledExecutor(ScheduledExecutorService executor);
221
    public ThreadFactory getThreadFactory();
222
    public ScheduledExecutorService getScheduledExecutor();
223
    
224
    // Metrics and monitoring
225
    public void setMetricsTrackerFactory(MetricsTrackerFactory metricsTrackerFactory);
226
    public void setMetricRegistry(Object metricRegistry);
227
    public void setHealthCheckRegistry(Object healthCheckRegistry);
228
    public void setHealthCheckProperties(Properties healthCheckProperties);
229
    public MetricsTrackerFactory getMetricsTrackerFactory();
230
    public Object getMetricRegistry();
231
    public Object getHealthCheckRegistry();
232
    public Properties getHealthCheckProperties();
233
    
234
    // DataSource properties
235
    public void setDataSourceProperties(Properties dsProperties);
236
    public void addDataSourceProperty(String propertyName, Object value);
237
    public void addHealthCheckProperty(String key, String value);
238
    public Properties getDataSourceProperties();
239
    
240
    // Validation and utility
241
    public void validate();
242
    public void copyState(HikariConfig other);
243
}
244
```
245

246
[Configuration Management](./configuration.md)
247

248
### JMX Management and Monitoring
249

250
Runtime monitoring and management capabilities through JMX beans, providing pool statistics and runtime configuration changes.
251

252
```java { .api }
253
public interface HikariPoolMXBean {
254
    // Pool statistics
255
    int getIdleConnections();
256
    int getActiveConnections();
257
    int getTotalConnections();
258
    int getThreadsAwaitingConnection();
259
    
260
    // Pool control
261
    void suspendPool();
262
    void resumePool();
263
    void softEvictConnections();
264
}
265

266
public interface HikariConfigMXBean {
267
    // Runtime configuration setters
268
    void setConnectionTimeout(long connectionTimeoutMs);
269
    void setValidationTimeout(long validationTimeoutMs);
270
    void setIdleTimeout(long idleTimeoutMs);
271
    void setMaximumPoolSize(int maxPoolSize);
272
    void setMinimumIdle(int minIdle);
273
    void setLeakDetectionThreshold(long leakDetectionThresholdMs);
274
    void setMaxLifetime(long maxLifetimeMs);
275
    void setPassword(String password);
276
    void setUsername(String username);
277
    
278
    // Runtime configuration getters
279
    long getConnectionTimeout();
280
    long getValidationTimeout();
281
    long getIdleTimeout();
282
    long getLeakDetectionThreshold();
283
    long getMaxLifetime();
284
    int getMinimumIdle();
285
    int getMaximumPoolSize();
286
    String getPoolName();
287
}
288
```
289

290
[JMX Management](./jmx-management.md)
291

292
### Metrics Integration
293

294
Pluggable metrics system supporting popular metrics frameworks including Dropwizard Metrics and Prometheus for comprehensive pool monitoring.
295

296
```java { .api }
297
public class MetricsTracker implements AutoCloseable {
298
    // Constructor
299
    public MetricsTracker();
300
    
301
    // Metrics recording methods
302
    public void recordConnectionAcquiredNanos(long elapsedAcquiredNanos);
303
    public void recordConnectionUsageMillis(long elapsedBorrowedMillis);
304
    public void recordConnectionTimeout();
305
    
306
    // AutoCloseable implementation
307
    public void close();
308
}
309

310
public interface MetricsTrackerFactory {
311
    MetricsTracker create(String poolName, PoolStats poolStats);
312
}
313

314
// Configuration methods in HikariConfig/HikariDataSource
315
public void setMetricsTrackerFactory(MetricsTrackerFactory metricsTrackerFactory);
316
public void setMetricRegistry(Object metricRegistry);
317
public void setHealthCheckRegistry(Object healthCheckRegistry);
318
public MetricsTrackerFactory getMetricsTrackerFactory();
319
public Object getMetricRegistry();
320
public Object getHealthCheckRegistry();
321
```
322

323
[Metrics Integration](./metrics.md)
324

325
### Framework Integration
326

327
Native integration with popular Java frameworks including Hibernate ORM and JNDI environments for seamless adoption in enterprise applications.
328

329
```java { .api }
330
// Hibernate Integration
331
public class HikariConnectionProvider implements ConnectionProvider, Configurable, Stoppable {
332
    // Constructor
333
    public HikariConnectionProvider();
334
    
335
    // ConnectionProvider methods
336
    public Connection getConnection() throws SQLException;
337
    public void closeConnection(Connection conn) throws SQLException;
338
    public boolean supportsAggressiveRelease();
339
    public boolean isUnwrappableAs(Class unwrapType);
340
    public <T> T unwrap(Class<T> unwrapType);
341
    
342
    // Configurable implementation
343
    public void configure(Map props) throws HibernateException;
344
    
345
    // Stoppable implementation
346
    public void stop();
347
}
348

349
// JNDI Integration  
350
public class HikariJNDIFactory implements ObjectFactory {
351
    public synchronized Object getObjectInstance(Object obj, Name name, Context nameCtx, 
352
                                               Hashtable<?, ?> environment) throws Exception;
353
}
354
```
355

356
[Framework Integration](./framework-integration.md)
357

358
## Types
359

360
```java { .api }
361
// Core configuration properties interface
362
public interface HikariConfigMXBean {
363
    long getConnectionTimeout();
364
    long getValidationTimeout();
365
    long getIdleTimeout();
366
    long getLeakDetectionThreshold();
367
    long getMaxLifetime();
368
    int getMinimumIdle();
369
    int getMaximumPoolSize();
370
    String getPoolName();
371
}
372

373
// Pool statistics and control interface
374
public interface HikariPoolMXBean {
375
    int getIdleConnections();
376
    int getActiveConnections();
377
    int getTotalConnections();
378
    int getThreadsAwaitingConnection();
379
    void softEvictConnections();
380
    void suspendPool();
381
    void resumePool();
382
}
383

384
// Base class for metrics tracking
385
public abstract class PoolStats {
386
    protected PoolStats(long timeoutMs);
387
    public int getTotalConnections();
388
    public int getIdleConnections();
389
    public int getActiveConnections();
390
    public int getPendingThreads();
391
    
392
    // Abstract method to be implemented by subclasses
393
    protected abstract void update();
394
}
395
```