0
# HikariCP
1

2
HikariCP is a high-performance JDBC connection pool library providing zero-overhead database connection management with a focus on speed, simplicity, and reliability. At approximately 130Kb, it's a lightweight solution that offers comprehensive connection pooling features including connection validation, leak detection, transaction rollback on return, and extensive monitoring capabilities.
3

4
## Package Information
5

6
- **Package Name**: HikariCP
7
- **Package Type**: Maven
8
- **Group ID**: com.zaxxer
9
- **Artifact ID**: HikariCP
10
- **Language**: Java
11
- **Installation**: Add to your Maven or Gradle dependencies
12

13
### Maven
14

15
```xml
16
<dependency>
17
    <groupId>com.zaxxer</groupId>
18
    <artifactId>HikariCP</artifactId>
19
    <version>5.1.0</version>
20
</dependency>
21
```
22

23
### Gradle
24

25
```groovy
26
implementation 'com.zaxxer:HikariCP:5.1.0'
27
```
28

29
## Core Imports
30

31
```java
32
import com.zaxxer.hikari.HikariConfig;
33
import com.zaxxer.hikari.HikariDataSource;
34
```
35

36
## Basic Usage
37

38
```java
39
import com.zaxxer.hikari.HikariConfig;
40
import com.zaxxer.hikari.HikariDataSource;
41
import java.sql.Connection;
42
import java.sql.SQLException;
43

44
// Create configuration
45
HikariConfig config = new HikariConfig();
46
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
47
config.setUsername("user");
48
config.setPassword("password");
49
config.setMaximumPoolSize(10);
50

51
// Create DataSource
52
HikariDataSource dataSource = new HikariDataSource(config);
53

54
// Get connection and use it
55
try (Connection connection = dataSource.getConnection()) {
56
    // Use connection for database operations
57
    // Connection is automatically returned to pool when closed
58
}
59

60
// Shutdown when application terminates
61
dataSource.close();
62
```
63

64
## Architecture
65

66
HikariCP is built around several key components:
67

68
- **HikariConfig**: Configuration management with validation and runtime tuning
69
- **HikariDataSource**: Main DataSource implementation and connection pool interface
70
- **Connection Pool**: High-performance connection management with intelligent algorithms
71
- **JMX Management**: Runtime monitoring and configuration through MBeans
72
- **Metrics Integration**: Support for Dropwizard, Micrometer, and Prometheus metrics
73
- **Framework Integration**: Built-in support for Hibernate and JNDI environments
74

75
## Capabilities
76

77
### Configuration Management
78

79
Comprehensive configuration system with validation, property file support, and runtime tuning capabilities.
80

81
```java { .api }
82
public class HikariConfig implements HikariConfigMXBean {
83
    // Constructors
84
    public HikariConfig();
85
    public HikariConfig(Properties properties);
86
    public HikariConfig(String propertyFileName);
87
    
88
    // Core connection settings
89
    public void setJdbcUrl(String jdbcUrl);
90
    public void setUsername(String username);
91
    public void setPassword(String password);
92
    public void setDriverClassName(String driverClassName);
93
    
94
    // Pool sizing
95
    public void setMaximumPoolSize(int maxPoolSize);
96
    public void setMinimumIdle(int minIdle);
97
    
98
    // Timeouts (in milliseconds)
99
    public void setConnectionTimeout(long connectionTimeoutMs);
100
    public void setIdleTimeout(long idleTimeoutMs);
101
    public void setMaxLifetime(long maxLifetimeMs);
102
    public void setValidationTimeout(long validationTimeoutMs);
103
}
104
```
105

106
[Configuration](./configuration.md)
107

108
### DataSource and Connection Management
109

110
High-performance DataSource implementation with automatic connection lifecycle management, leak detection, and pool monitoring.
111

112
```java { .api }
113
public class HikariDataSource extends HikariConfig implements DataSource, Closeable {
114
    // Constructors
115
    public HikariDataSource();
116
    public HikariDataSource(HikariConfig configuration);
117
    
118
    // DataSource interface
119
    public Connection getConnection() throws SQLException;
120
    
121
    // Pool management
122
    public boolean isRunning();
123
    public void evictConnection(Connection connection);
124
    public void close();
125
    public boolean isClosed();
126
}
127
```
128

129
[DataSource Usage](./datasource.md)
130

131
### JMX Monitoring and Management
132

133
Runtime monitoring and configuration management through JMX MBeans with real-time pool statistics and configuration tuning.
134

135
```java { .api }
136
public interface HikariPoolMXBean {
137
    // Pool statistics
138
    int getIdleConnections();
139
    int getActiveConnections();
140
    int getTotalConnections();
141
    int getThreadsAwaitingConnection();
142
    
143
    // Pool control
144
    void softEvictConnections();
145
    void suspendPool();
146
    void resumePool();
147
}
148

149
public interface HikariConfigMXBean {
150
    // Runtime configuration changes
151
    void setConnectionTimeout(long connectionTimeoutMs);
152
    void setMaximumPoolSize(int maxPoolSize);
153
    void setMinimumIdle(int minIdle);
154
    String getPoolName();
155
}
156
```
157

158
[Monitoring and JMX](./monitoring.md)
159

160
### Metrics Integration
161

162
Built-in support for popular metrics libraries including Dropwizard Metrics, Micrometer, and Prometheus with detailed connection pool telemetry.
163

164
```java { .api }
165
// Dropwizard/Codahale Metrics
166
public class CodahaleMetricsTrackerFactory implements MetricsTrackerFactory {
167
    public CodahaleMetricsTrackerFactory(MetricRegistry registry);
168
}
169

170
// Micrometer Metrics  
171
public class MicrometerMetricsTrackerFactory implements MetricsTrackerFactory {
172
    public MicrometerMetricsTrackerFactory(MeterRegistry registry);
173
}
174

175
// Prometheus Metrics
176
public class PrometheusMetricsTrackerFactory implements MetricsTrackerFactory {
177
    public PrometheusMetricsTrackerFactory();
178
    public PrometheusMetricsTrackerFactory(CollectorRegistry collectorRegistry);
179
}
180
```
181

182
[Metrics Integration](./metrics.md)
183

184
### Hibernate Integration
185

186
Native Hibernate connection provider implementation for seamless integration with Hibernate ORM applications.
187

188
```java { .api }
189
public class HikariConnectionProvider implements ConnectionProvider, Configurable, Stoppable {
190
    public Connection getConnection() throws SQLException;
191
    public void closeConnection(Connection conn) throws SQLException;
192
    public void configure(Map props) throws HibernateException;
193
}
194

195
public class HikariConfigurationUtil {
196
    public static HikariConfig loadConfiguration(Map props);
197
}
198
```
199

200
[Hibernate Integration](./hibernate.md)
201

202
### Advanced Features
203

204
JNDI factory support, custom exception handling, and advanced configuration options for enterprise deployments.
205

206
```java { .api }
207
// JNDI Support
208
public class HikariJNDIFactory implements ObjectFactory {
209
    public synchronized Object getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?, ?> environment) throws Exception;
210
}
211

212
// Custom Exception Handling
213
public interface SQLExceptionOverride {
214
    enum Override { CONTINUE_EVICT, DO_NOT_EVICT }
215
    default Override adjudicate(final SQLException sqlException);
216
}
217
```
218

219
[Advanced Features](./advanced.md)
220

221
## Types
222

223
### Core Configuration Types
224

225
```java { .api }
226
public class HikariConfig implements HikariConfigMXBean {
227
    // Configuration validation
228
    public void validate();
229
    public void copyStateTo(HikariConfig other);
230
    
231
    // Property management
232
    public void addDataSourceProperty(String propertyName, Object value);
233
    public Properties getDataSourceProperties();
234
    public void setDataSourceProperties(Properties dsProperties);
235
}
236
```
237

238
### Metrics Integration Types
239

240
```java { .api }
241
public interface IMetricsTracker extends AutoCloseable {
242
    default void recordConnectionCreatedMillis(long connectionCreatedMillis);
243
    default void recordConnectionAcquiredNanos(final long elapsedAcquiredNanos);
244
    default void recordConnectionUsageMillis(final long elapsedBorrowedMillis);
245
    default void recordConnectionTimeout();
246
    default void close();
247
}
248

249
public interface MetricsTrackerFactory {
250
    IMetricsTracker create(String poolName, PoolStats poolStats);
251
}
252

253
public abstract class PoolStats {
254
    public PoolStats(final long timeoutMs);
255
    public int getTotalConnections();
256
    public int getIdleConnections();
257
    public int getActiveConnections();
258
    public int getPendingThreads();
259
    public int getMaxConnections();
260
    public int getMinConnections();
261
}
262
```