0
# Configuration and Setup
1

2
Core classes and methods for configuring and creating HikariCP connection pools, including comprehensive configuration options for database connectivity, pool behavior, timeouts, and performance tuning.
3

4
## Capabilities
5

6
### HikariDataSource
7

8
The main entry point for HikariCP providing a pooled DataSource implementation that manages database connections efficiently.
9

10
```java { .api }
11
public class HikariDataSource extends HikariConfig implements DataSource, Closeable {
12
    /**
13
     * Default constructor with lazy initialization.
14
     * Pool creation is deferred until first getConnection() call.
15
     */
16
    public HikariDataSource();
17
    
18
    /**
19
     * Construct DataSource with specific configuration.
20
     * 
21
     * @param configuration HikariConfig instance with pool settings
22
     */
23
    public HikariDataSource(HikariConfig configuration);
24
    
25
    /**
26
     * Get a connection from the pool.
27
     * 
28
     * @return Connection from the pool
29
     * @throws SQLException if connection cannot be obtained
30
     */
31
    public Connection getConnection() throws SQLException;
32
    
33
    /**
34
     * Get connection with credentials (deprecated - credentials ignored).
35
     * 
36
     * @param username ignored parameter
37
     * @param password ignored parameter
38
     * @return Connection from the pool
39
     * @throws SQLException if connection cannot be obtained
40
     * @deprecated This method is deprecated in the underlying implementation
41
     */
42
    @Deprecated
43
    public Connection getConnection(String username, String password) throws SQLException;
44
    
45
    /**
46
     * Get the log writer for the DataSource.
47
     * 
48
     * @return PrintWriter for logging
49
     * @throws SQLException on error
50
     */
51
    public PrintWriter getLogWriter() throws SQLException;
52
    
53
    /**
54
     * Set the log writer for the DataSource.
55
     * 
56
     * @param out PrintWriter for logging
57
     * @throws SQLException on error
58
     */
59
    public void setLogWriter(PrintWriter out) throws SQLException;
60
    
61
    /**
62
     * Set login timeout in seconds.
63
     * 
64
     * @param seconds timeout in seconds
65
     * @throws SQLException on error
66
     */
67
    public void setLoginTimeout(int seconds) throws SQLException;
68
    
69
    /**
70
     * Get login timeout in seconds.
71
     * 
72
     * @return timeout in seconds
73
     * @throws SQLException on error
74
     */
75
    public int getLoginTimeout() throws SQLException;
76
    
77
    /**
78
     * Get parent logger (always throws SQLFeatureNotSupportedException).
79
     * 
80
     * @return never returns normally
81
     * @throws SQLFeatureNotSupportedException always thrown
82
     */
83
    public java.util.logging.Logger getParentLogger() throws SQLFeatureNotSupportedException;
84
    
85
    /**
86
     * Unwrap to specified interface.
87
     * 
88
     * @param iface target interface class
89
     * @return unwrapped instance
90
     * @throws SQLException if unwrapping fails
91
     */
92
    public <T> T unwrap(Class<T> iface) throws SQLException;
93
    
94
    /**
95
     * Check if wrapper for specified interface.
96
     * 
97
     * @param iface target interface class
98
     * @return true if wrapper for interface
99
     * @throws SQLException on error
100
     */
101
    public boolean isWrapperFor(Class<?> iface) throws SQLException;
102
    
103
    /**
104
     * Set Codahale MetricRegistry for metrics collection.
105
     * 
106
     * @param metricRegistry MetricRegistry instance or null
107
     */
108
    public void setMetricRegistry(Object metricRegistry);
109
    
110
    /**
111
     * Set Codahale HealthCheckRegistry for health monitoring.
112
     * 
113
     * @param healthCheckRegistry HealthCheckRegistry instance or null
114
     */
115
    public void setHealthCheckRegistry(Object healthCheckRegistry);
116
    
117
    /**
118
     * Evict a specific connection from the pool.
119
     * 
120
     * @param connection connection to evict
121
     */
122
    public void evictConnection(Connection connection);
123
    
124
    /**
125
     * Suspend connection allocation from the pool.
126
     * Existing connections continue to work but no new connections are allocated.
127
     */
128
    public void suspendPool();
129
    
130
    /**
131
     * Resume connection allocation after suspension.
132
     */
133
    public void resumePool();
134
    
135
    /**
136
     * Close the DataSource and shutdown the connection pool.
137
     * Synonym for shutdown().
138
     */
139
    public void close();
140
    
141
    /**
142
     * Shutdown the DataSource and connection pool.
143
     * Waits for active connections to be returned.
144
     */
145
    public void shutdown();
146
    
147
    /**
148
     * String representation of the DataSource.
149
     * 
150
     * @return string describing the DataSource
151
     */
152
    public String toString();
153
}
154
```
155

156
### HikariConfig
157

158
Configuration class for HikariCP connection pool settings with support for Properties-based configuration.
159

160
```java { .api }
161
public class HikariConfig extends AbstractHikariConfig {
162
    /**
163
     * Default constructor.
164
     */
165
    public HikariConfig();
166
    
167
    /**
168
     * Construct from Properties object.
169
     * Property keys should match configuration property names.
170
     * 
171
     * @param properties Properties containing configuration
172
     */
173
    public HikariConfig(Properties properties);
174
    
175
    /**
176
     * Construct from property file.
177
     * 
178
     * @param propertyFileName path to properties file
179
     */
180
    public HikariConfig(String propertyFileName);
181
    
182
    /**
183
     * Load properties from file (protected method for subclass use).
184
     * Attempts to load from filesystem first, then from classpath.
185
     * 
186
     * @param propertyFileName path to properties file
187
     * @throws IllegalArgumentException if property file not found
188
     * @throws RuntimeException if error loading properties
189
     */
190
    protected void loadProperties(String propertyFileName);
191
}
192
```
193

194
### AbstractHikariConfig
195

196
Base configuration class containing all configuration properties and their accessors with comprehensive validation and default values.
197

198
```java { .api }
199
public abstract class AbstractHikariConfig implements HikariConfigMXBean {
200
    /**
201
     * Default constructor.
202
     */
203
    public AbstractHikariConfig();
204
    
205
    /**
206
     * Construct from Properties object.
207
     * 
208
     * @param properties Properties containing configuration
209
     */
210
    public AbstractHikariConfig(Properties properties);
211
    
212
    /**
213
     * Construct from property file.
214
     * 
215
     * @param propertyFileName path to properties file
216
     */
217
    public AbstractHikariConfig(String propertyFileName);
218
}
219
```
220

221
### Database Connection Configuration
222

223
Configure database connectivity and authentication.
224

225
```java { .api }
226
// JDBC URL configuration
227
public String getJdbcUrl();
228
public void setJdbcUrl(String jdbcUrl);
229

230
// Authentication
231
public String getUsername();
232
public void setUsername(String username);
233
public String getPassword();
234
public void setPassword(String password);
235

236
// Driver configuration
237
public String getDriverClassName();
238
public void setDriverClassName(String driverClassName);
239

240
// DataSource alternatives
241
public DataSource getDataSource();
242
public void setDataSource(DataSource dataSource);
243
public String getDataSourceClassName();
244
public void setDataSourceClassName(String className);
245
public String getDataSourceJNDI();
246
public void setDataSourceJNDI(String jndiDataSource);
247

248
// DataSource properties
249
public Properties getDataSourceProperties();
250
public void setDataSourceProperties(Properties dsProperties);
251
public void addDataSourceProperty(String propertyName, Object value);
252
```
253

254
### Pool Size Configuration
255

256
Configure connection pool sizing and behavior.
257

258
```java { .api }
259
// Pool sizing
260
public int getMaximumPoolSize();
261
public void setMaximumPoolSize(int maxPoolSize);
262
public int getMinimumIdle();
263
public void setMinimumIdle(int minIdle);
264

265
// Pool identification
266
public String getPoolName();
267
public void setPoolName(String poolName);
268
```
269

270
### Timeout Configuration
271

272
Configure various timeout settings for optimal performance and reliability.
273

274
```java { .api }
275
// Connection acquisition timeout (default: 30 seconds)
276
public long getConnectionTimeout();
277
public void setConnectionTimeout(long connectionTimeoutMs);
278

279
// Connection validation timeout (default: 5 seconds)
280
public long getValidationTimeout();
281
public void setValidationTimeout(long validationTimeoutMs);
282

283
// Idle connection timeout (default: 10 minutes)
284
public long getIdleTimeout();
285
public void setIdleTimeout(long idleTimeoutMs);
286

287
// Maximum connection lifetime (default: 30 minutes)
288
public long getMaxLifetime();
289
public void setMaxLifetime(long maxLifetimeMs);
290

291
// Connection leak detection threshold (default: 0 - disabled)
292
public long getLeakDetectionThreshold();
293
public void setLeakDetectionThreshold(long leakDetectionThresholdMs);
294
```
295

296
### Connection Behavior Configuration
297

298
Configure connection-level behavior and properties.
299

300
```java { .api }
301
// Auto-commit behavior
302
public boolean isAutoCommit();
303
public void setAutoCommit(boolean isAutoCommit);
304

305
// Read-only mode
306
public boolean isReadOnly();
307
public void setReadOnly(boolean readOnly);
308

309
// Transaction isolation level
310
public String getTransactionIsolation();
311
public void setTransactionIsolation(String isolationLevel);
312

313
// Default catalog
314
public String getCatalog();
315
public void setCatalog(String catalog);
316

317
// Connection initialization SQL
318
public String getConnectionInitSql();
319
public void setConnectionInitSql(String connectionInitSql);
320
```
321

322
### Connection Testing Configuration
323

324
Configure connection validation and health checking.
325

326
```java { .api }
327
// Connection test query
328
public String getConnectionTestQuery();
329
public void setConnectionTestQuery(String connectionTestQuery);
330

331
// JDBC4 connection test (deprecated)
332
public boolean isJdbc4ConnectionTest();
333
public void setJdbc4ConnectionTest(boolean useIsValid);
334

335
// Internal query isolation
336
public boolean isIsolateInternalQueries();
337
public void setIsolateInternalQueries(boolean isolate);
338
```
339

340
### Advanced Configuration
341

342
Configure advanced pool features and integrations.
343

344
```java { .api }
345
// Pool suspension support
346
public boolean isAllowPoolSuspension();
347
public void setAllowPoolSuspension(boolean isAllowPoolSuspension);
348

349
// Fail-fast initialization
350
public boolean isInitializationFailFast();
351
public void setInitializationFailFast(boolean failFast);
352

353
// JMX MBean registration
354
public boolean isRegisterMbeans();
355
public void setRegisterMbeans(boolean register);
356

357
// Custom thread factory
358
public ThreadFactory getThreadFactory();
359
public void setThreadFactory(ThreadFactory threadFactory);
360

361
// Metrics integration
362
public Object getMetricRegistry();
363
public void setMetricRegistry(Object metricRegistry);
364

365
// Health check integration
366
public Object getHealthCheckRegistry();
367
public void setHealthCheckRegistry(Object healthCheckRegistry);
368
public Properties getHealthCheckProperties();
369
public void setHealthCheckProperties(Properties healthCheckProperties);
370
public void addHealthCheckProperty(String key, String value);
371

372
// Connection customization (deprecated)
373
@Deprecated
374
public String getConnectionCustomizerClassName();
375
@Deprecated
376
public void setConnectionCustomizerClassName(String connectionCustomizerClassName);
377
@Deprecated
378
public IConnectionCustomizer getConnectionCustomizer();
379
@Deprecated
380
public void setConnectionCustomizer(IConnectionCustomizer customizer);
381
```
382

383
### Configuration Validation and Management
384

385
Validate and manage configuration state.
386

387
```java { .api }
388
/**
389
 * Validate the current configuration.
390
 * Throws IllegalArgumentException for invalid configurations.
391
 */
392
public void validate();
393

394
/**
395
 * Copy configuration state from another config instance.
396
 * 
397
 * @param other source configuration to copy from
398
 */
399
public void copyState(AbstractHikariConfig other);
400
```
401

402
## Usage Examples
403

404
### Basic Configuration
405

406
```java
407
HikariConfig config = new HikariConfig();
408
config.setJdbcUrl("jdbc:postgresql://localhost/test");
409
config.setUsername("postgres");
410
config.setPassword("password");
411
config.setDriverClassName("org.postgresql.Driver");
412

413
HikariDataSource ds = new HikariDataSource(config);
414
```
415

416
### Properties-Based Configuration
417

418
```java
419
Properties props = new Properties();
420
props.setProperty("jdbcUrl", "jdbc:mysql://localhost:3306/mydb");
421
props.setProperty("username", "user");
422
props.setProperty("password", "pass");
423
props.setProperty("maximumPoolSize", "20");
424
props.setProperty("connectionTimeout", "30000");
425

426
HikariConfig config = new HikariConfig(props);
427
HikariDataSource ds = new HikariDataSource(config);
428
```
429

430
### File-Based Configuration
431

432
```java
433
// Load from hikari.properties file
434
HikariConfig config = new HikariConfig("hikari.properties");
435
HikariDataSource ds = new HikariDataSource(config);
436
```
437

438
### DataSource Configuration
439

440
```java
441
// Using existing DataSource
442
HikariConfig config = new HikariConfig();
443
config.setDataSource(existingDataSource);
444
config.setMaximumPoolSize(15);
445

446
// Or by class name
447
config.setDataSourceClassName("com.mysql.jdbc.jdbc2.optional.MysqlDataSource");
448
config.addDataSourceProperty("url", "jdbc:mysql://localhost:3306/mydb");
449
config.addDataSourceProperty("user", "username");
450
config.addDataSourceProperty("password", "password");
451
```
452

453
### Performance Tuning
454

455
```java
456
HikariConfig config = new HikariConfig();
457
config.setJdbcUrl("jdbc:postgresql://localhost/highload");
458
config.setUsername("postgres");
459
config.setPassword("password");
460

461
// Pool sizing for high-load application
462
config.setMaximumPoolSize(50);
463
config.setMinimumIdle(10);
464

465
// Optimize timeouts
466
config.setConnectionTimeout(20000);      // 20 seconds
467
config.setIdleTimeout(300000);          // 5 minutes
468
config.setMaxLifetime(1200000);         // 20 minutes
469

470
// Enable leak detection
471
config.setLeakDetectionThreshold(60000); // 1 minute
472

473
// Performance optimizations
474
config.setAutoCommit(true);
475
config.setTransactionIsolation("TRANSACTION_READ_COMMITTED");
476

477
HikariDataSource ds = new HikariDataSource(config);
478
```