0
# Connection Pool Management
1

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

4
## Capabilities
5

6
### HikariDataSource
7

8
Main pooled DataSource implementation that extends HikariConfig and implements the standard JDBC DataSource interface.
9

10
```java { .api }
11
/**
12
 * The HikariCP pooled DataSource providing high-performance connection pooling
13
 */
14
public class HikariDataSource extends HikariConfig implements DataSource, Closeable {
15
    /**
16
     * Default constructor with lazy initialization. Setters must be used to configure the pool.
17
     * Using this constructor results in slightly lower getConnection() performance due to lazy checks.
18
     */
19
    public HikariDataSource();
20
    
21
    /**
22
     * Construct a HikariDataSource with the specified configuration.
23
     * @param configuration a HikariConfig instance with validated settings
24
     */
25
    public HikariDataSource(HikariConfig configuration);
26
}
27
```
28

29
**Usage Examples:**
30

31
```java
32
// Lazy initialization (slightly lower performance)
33
HikariDataSource dataSource = new HikariDataSource();
34
dataSource.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
35
dataSource.setUsername("user");
36
dataSource.setPassword("password");
37

38
// Eager initialization (recommended for production)
39
HikariConfig config = new HikariConfig();
40
config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
41
config.setUsername("user");
42
config.setPassword("password");
43
config.setMaximumPoolSize(20);
44
HikariDataSource dataSource = new HikariDataSource(config);
45
```
46

47
### Connection Acquisition
48

49
Standard JDBC DataSource methods for obtaining connections from the pool.
50

51
```java { .api }
52
/**
53
 * Obtain a connection from the pool. If the pool is closed, throws SQLException.
54
 * Blocks for up to connectionTimeout milliseconds if no connections are available.
55
 * @return a Connection from the pool
56
 * @throws SQLException if the DataSource is closed or connection timeout is reached
57
 */
58
public Connection getConnection() throws SQLException;
59

60
/**
61
 * This method is not supported and throws SQLFeatureNotSupportedException
62
 * @param username not used
63
 * @param password not used
64
 * @throws SQLFeatureNotSupportedException always thrown
65
 */
66
public Connection getConnection(String username, String password) throws SQLException;
67
```
68

69
**Usage Examples:**
70

71
```java
72
// Basic connection usage
73
try (Connection conn = dataSource.getConnection()) {
74
    PreparedStatement stmt = conn.prepareStatement("SELECT * FROM users WHERE id = ?");
75
    stmt.setInt(1, userId);
76
    ResultSet rs = stmt.executeQuery();
77
    // Process results
78
} // Connection automatically returned to pool
79

80
// Connection with timeout handling
81
try {
82
    Connection conn = dataSource.getConnection();
83
    // Use connection
84
    conn.close(); // Return to pool
85
} catch (SQLException e) {
86
    if (e.getMessage().contains("timeout")) {
87
        // Handle connection timeout
88
    }
89
}
90
```
91

92
### Pool Lifecycle Management
93

94
Methods for managing the overall lifecycle of the connection pool.
95

96
```java { .api }
97
/**
98
 * Shutdown the DataSource and its associated pool. This method is idempotent.
99
 * All connections will be closed and the pool will be shut down gracefully.
100
 */
101
public void close();
102

103
/**
104
 * Determine whether the HikariDataSource has been closed.
105
 * @return true if the HikariDataSource has been closed, false otherwise
106
 */
107
public boolean isClosed();
108

109
/**
110
 * @deprecated This method has been deprecated, please use close() instead
111
 */
112
@Deprecated
113
public void shutdown();
114
```
115

116
**Usage Examples:**
117

118
```java
119
// Graceful shutdown
120
if (!dataSource.isClosed()) {
121
    dataSource.close();
122
}
123

124
// Application shutdown hook
125
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
126
    if (!dataSource.isClosed()) {
127
        dataSource.close();
128
    }
129
}));
130
```
131

132
### Connection Eviction
133

134
Advanced pool management for controlling individual connections in the pool.
135

136
```java { .api }
137
/**
138
 * Evict a connection from the pool. If the connection has already been closed (returned to the pool)
139
 * this may result in a "soft" eviction; the connection will be evicted sometime in the future if it is
140
 * currently in use. If the connection has not been closed, the eviction is immediate.
141
 * @param connection the connection to evict from the pool
142
 */
143
public void evictConnection(Connection connection);
144

145
/**
146
 * @deprecated Call the HikariPoolMXBean.suspendPool() method on the HikariPoolMXBean
147
 *             obtained by getHikariPoolMXBean() or JMX lookup.
148
 */
149
@Deprecated
150
public void suspendPool();
151

152
/**
153
 * @deprecated Call the HikariPoolMXBean.resumePool() method on the HikariPoolMXBean
154
 *             obtained by getHikariPoolMXBean() or JMX lookup.
155
 */
156
@Deprecated
157
public void resumePool();
158
```
159

160
**Usage Examples:**
161

162
```java
163
// Evict a problematic connection
164
Connection conn = dataSource.getConnection();
165
try {
166
    // If connection test fails, evict it
167
    if (!conn.isValid(1)) {
168
        dataSource.evictConnection(conn);
169
    }
170
} finally {
171
    conn.close();
172
}
173

174
// Pool suspension (use JMX methods instead)
175
HikariPoolMXBean poolBean = dataSource.getHikariPoolMXBean();
176
poolBean.suspendPool();
177
// Perform maintenance
178
poolBean.resumePool();
179
```
180

181
### Management Bean Access
182

183
Access to JMX management beans for monitoring and control.
184

185
```java { .api }
186
/**
187
 * Get the HikariPoolMXBean for this HikariDataSource instance. If this method is called on
188
 * a HikariDataSource that has been constructed without a HikariConfig instance,
189
 * and before an initial call to getConnection(), the return value will be null.
190
 * @return the HikariPoolMXBean instance, or null
191
 */
192
public HikariPoolMXBean getHikariPoolMXBean();
193

194
/**
195
 * Get the HikariConfigMXBean for this HikariDataSource instance.
196
 * @return the HikariConfigMXBean instance
197
 */
198
public HikariConfigMXBean getHikariConfigMXBean();
199
```
200

201
**Usage Examples:**
202

203
```java
204
// Monitor pool statistics
205
HikariPoolMXBean poolBean = dataSource.getHikariPoolMXBean();
206
if (poolBean != null) {
207
    System.out.println("Active connections: " + poolBean.getActiveConnections());
208
    System.out.println("Idle connections: " + poolBean.getIdleConnections());
209
    System.out.println("Total connections: " + poolBean.getTotalConnections());
210
    System.out.println("Threads awaiting: " + poolBean.getThreadsAwaitingConnection());
211
}
212

213
// Runtime configuration changes
214
HikariConfigMXBean configBean = dataSource.getHikariConfigMXBean();
215
configBean.setMaximumPoolSize(30); // Increase pool size at runtime
216
```
217

218
### DataSource Wrapper Methods
219

220
Standard JDBC wrapper methods for accessing underlying DataSource implementations.
221

222
```java { .api }
223
/**
224
 * Return an object that implements the given interface to allow access to non-standard methods,
225
 * or standard methods not exposed by the proxy.
226
 * @param iface the interface that the result will implement
227
 * @return an object that implements the interface
228
 * @throws SQLException if no object found that implements the interface
229
 */
230
public <T> T unwrap(Class<T> iface) throws SQLException;
231

232
/**
233
 * Returns true if this either implements the interface argument or is directly or indirectly
234
 * a wrapper for an object that does.
235
 * @param iface the interface to check
236
 * @return true if this implements the interface or wraps an object that does
237
 * @throws SQLException if an error occurs while determining whether this is a wrapper
238
 */
239
public boolean isWrapperFor(Class<?> iface) throws SQLException;
240
```
241

242
### LogWriter Methods
243

244
Standard JDBC DataSource logging methods.
245

246
```java { .api }
247
/**
248
 * Gets the log writer for this DataSource object.
249
 * @return the log writer for this data source or null if logging is disabled
250
 * @throws SQLException if a database access error occurs
251
 */
252
public PrintWriter getLogWriter() throws SQLException;
253

254
/**
255
 * Sets the log writer for this DataSource object.
256
 * @param out the new log writer; to disable logging, set to null
257
 * @throws SQLException if a database access error occurs
258
 */
259
public void setLogWriter(PrintWriter out) throws SQLException;
260

261
/**
262
 * Sets the maximum time in seconds that this data source will wait while attempting to connect.
263
 * @param seconds the data source login time limit in seconds; zero means there is no limit
264
 * @throws SQLException if a database access error occurs
265
 */
266
public void setLoginTimeout(int seconds) throws SQLException;
267

268
/**
269
 * Gets the maximum time in seconds that this data source can wait while attempting to connect.
270
 * @return the data source login time limit in seconds, or zero if there is no limit
271
 * @throws SQLException if a database access error occurs
272
 */
273
public int getLoginTimeout() throws SQLException;
274

275
/**
276
 * Return the parent Logger of all the Loggers used by this data source.
277
 * @return the parent Logger for this data source
278
 * @throws SQLFeatureNotSupportedException always thrown as this feature is not supported
279
 */
280
public java.util.logging.Logger getParentLogger() throws SQLFeatureNotSupportedException;
281
```