0
# HikariCP
1
2
HikariCP is a high-performance, zero-overhead production-ready JDBC connection pool for Java applications. At roughly 165KB, this library provides a fast, simple, and reliable connection pooling solution that emphasizes simplicity as a prerequisite for reliability.
3
4
## Package Information
5
6
- **Package Name**: com.zaxxer:HikariCP
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven `pom.xml`:
10
11
```xml
12
<dependency>
13
<groupId>com.zaxxer</groupId>
14
<artifactId>HikariCP</artifactId>
15
<version>6.3.0</version>
16
</dependency>
17
```
18
19
Gradle:
20
```gradle
21
implementation 'com.zaxxer:HikariCP:6.3.0'
22
```
23
24
## Core Imports
25
26
```java
27
import com.zaxxer.hikari.HikariConfig;
28
import com.zaxxer.hikari.HikariDataSource;
29
```
30
31
For metrics integration:
32
```java
33
import com.zaxxer.hikari.metrics.MetricsTrackerFactory;
34
import com.zaxxer.hikari.metrics.micrometer.MicrometerMetricsTrackerFactory;
35
```
36
37
For Hibernate integration:
38
```java
39
import com.zaxxer.hikari.hibernate.HikariConnectionProvider;
40
```
41
42
## Basic Usage
43
44
```java
45
import com.zaxxer.hikari.HikariConfig;
46
import com.zaxxer.hikari.HikariDataSource;
47
import java.sql.Connection;
48
import java.sql.SQLException;
49
50
// Method 1: Using HikariConfig
51
HikariConfig config = new HikariConfig();
52
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
53
config.setUsername("myuser");
54
config.setPassword("mypassword");
55
config.setMaximumPoolSize(20);
56
57
HikariDataSource dataSource = new HikariDataSource(config);
58
59
// Method 2: Using property file
60
HikariConfig config = new HikariConfig("/path/to/hikari.properties");
61
HikariDataSource dataSource = new HikariDataSource(config);
62
63
// Method 3: Default constructor with programmatic configuration
64
HikariDataSource dataSource = new HikariDataSource();
65
dataSource.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
66
dataSource.setUsername("myuser");
67
dataSource.setPassword("mypassword");
68
69
// Getting connections
70
try (Connection connection = dataSource.getConnection()) {
71
// Use the connection for database operations
72
// Connection is automatically returned to pool when closed
73
}
74
75
// Shutdown the pool when application terminates
76
dataSource.close();
77
```
78
79
## Architecture
80
81
HikariCP is built around several key components:
82
83
- **Connection Pool**: Fast, lightweight connection pooling with minimal overhead
84
- **Configuration System**: Comprehensive configuration with validation and runtime management
85
- **JMX Management**: Runtime monitoring and management through MXBeans
86
- **Metrics Integration**: Pluggable metrics support for monitoring frameworks
87
- **Proxy Layer**: JDBC proxy implementations for connection leak detection and management
88
- **Validation System**: Connection validation with configurable test queries and timeouts
89
90
## Capabilities
91
92
### Core Connection Pooling
93
94
Primary connection pool functionality for creating and managing database connections efficiently.
95
96
```java { .api }
97
public class HikariDataSource extends HikariConfig implements DataSource, Closeable {
98
public HikariDataSource();
99
public HikariDataSource(HikariConfig configuration);
100
public Connection getConnection() throws SQLException;
101
public void close();
102
public boolean isClosed();
103
public boolean isRunning();
104
}
105
```
106
107
[Connection Pooling](./connection-pooling.md)
108
109
### Configuration Management
110
111
Comprehensive configuration system with validation, property loading, and runtime management capabilities.
112
113
```java { .api }
114
public class HikariConfig implements HikariConfigMXBean {
115
public HikariConfig();
116
public HikariConfig(Properties properties);
117
public HikariConfig(String propertyFileName);
118
119
// Core connection settings
120
public void setJdbcUrl(String jdbcUrl);
121
public void setUsername(String username);
122
public void setPassword(String password);
123
public void setMaximumPoolSize(int maxPoolSize);
124
public void setMinimumIdle(int minIdle);
125
126
// Timeout configurations
127
public void setConnectionTimeout(long connectionTimeoutMs);
128
public void setIdleTimeout(long idleTimeoutMs);
129
public void setMaxLifetime(long maxLifetimeMs);
130
131
public void validate();
132
}
133
```
134
135
[Configuration](./configuration.md)
136
137
### JMX Management
138
139
Runtime monitoring and management through JMX MBeans for operational visibility and control.
140
141
```java { .api }
142
public interface HikariPoolMXBean {
143
int getIdleConnections();
144
int getActiveConnections();
145
int getTotalConnections();
146
int getThreadsAwaitingConnection();
147
void softEvictConnections();
148
void suspendPool();
149
void resumePool();
150
}
151
152
public interface HikariConfigMXBean {
153
long getConnectionTimeout();
154
void setConnectionTimeout(long connectionTimeoutMs);
155
int getMaximumPoolSize();
156
void setMaximumPoolSize(int maxPoolSize);
157
// ... other runtime configuration methods
158
}
159
```
160
161
[JMX Management](./jmx-management.md)
162
163
### Metrics Integration
164
165
Pluggable metrics system supporting Micrometer, Dropwizard/Codahale, and Prometheus monitoring frameworks.
166
167
```java { .api }
168
public interface MetricsTrackerFactory {
169
IMetricsTracker create(String poolName, PoolStats poolStats);
170
}
171
172
public interface IMetricsTracker extends AutoCloseable {
173
default void recordConnectionCreatedMillis(long connectionCreatedMillis) {}
174
default void recordConnectionAcquiredNanos(long elapsedAcquiredNanos) {}
175
default void recordConnectionUsageMillis(long elapsedBorrowedMillis) {}
176
default void recordConnectionTimeout() {}
177
}
178
179
// Micrometer integration
180
public class MicrometerMetricsTrackerFactory implements MetricsTrackerFactory;
181
182
// Dropwizard integration
183
public class CodahaleMetricsTrackerFactory implements MetricsTrackerFactory;
184
public class Dropwizard5MetricsTrackerFactory implements MetricsTrackerFactory;
185
186
// Prometheus integration
187
public class PrometheusMetricsTrackerFactory implements MetricsTrackerFactory;
188
public class PrometheusHistogramMetricsTrackerFactory implements MetricsTrackerFactory;
189
```
190
191
[Metrics Integration](./metrics-integration.md)
192
193
### Hibernate Integration
194
195
Seamless integration with Hibernate ORM for connection provider implementation.
196
197
```java { .api }
198
public class HikariConnectionProvider
199
implements ConnectionProvider, Configurable, Stoppable, ServiceRegistryAwareService {
200
// Hibernate ConnectionProvider implementation
201
}
202
203
public class HikariConfigurationUtil {
204
// Utility methods for Hibernate configuration
205
}
206
```
207
208
[Hibernate Integration](./hibernate-integration.md)
209
210
### Utility Classes
211
212
Supporting utility classes for credentials management, JNDI integration, and advanced connection handling.
213
214
```java { .api }
215
public final class Credentials {
216
public static Credentials of(String username, String password);
217
public Credentials(String username, String password);
218
public String getUsername();
219
public String getPassword();
220
}
221
222
public class HikariJNDIFactory implements ObjectFactory {
223
public Object getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?, ?> environment);
224
}
225
226
public interface SQLExceptionOverride {
227
enum Override { CONTINUE_EVICT, DO_NOT_EVICT, MUST_EVICT }
228
default Override adjudicate(SQLException sqlException);
229
}
230
```
231
232
[Utilities](./utilities.md)
233
234
## Types
235
236
```java { .api }
237
// Configuration credentials holder
238
public final class Credentials {
239
public static Credentials of(String username, String password);
240
public String getUsername();
241
public String getPassword();
242
}
243
244
// Pool statistics base class
245
public abstract class PoolStats {
246
public PoolStats(long timeoutMs);
247
public int getTotalConnections();
248
public int getIdleConnections();
249
public int getActiveConnections();
250
public int getPendingThreads();
251
public int getMaxConnections();
252
public int getMinConnections();
253
}
254
255
// SQL exception override control
256
public enum SQLExceptionOverride.Override {
257
CONTINUE_EVICT, // Continue with default eviction logic
258
DO_NOT_EVICT, // Do not evict the connection
259
MUST_EVICT // Force eviction regardless of exception
260
}
261
```