0
# Configuration
1

2
Comprehensive configuration system with validation, property loading, and runtime management capabilities.
3

4
## Capabilities
5

6
### HikariConfig
7

8
Main configuration class providing all connection pool settings and validation.
9

10
```java { .api }
11
/**
12
 * Configuration class for HikariCP connection pool
13
 * Implements HikariConfigMXBean for JMX management
14
 */
15
public class HikariConfig implements HikariConfigMXBean {
16
    
17
    /**
18
     * Default constructor - loads from system property hikaricp.configurationFile if set
19
     */
20
    public HikariConfig();
21
    
22
    /**
23
     * Constructor from Properties object
24
     * @param properties Properties containing configuration
25
     */
26
    public HikariConfig(Properties properties);
27
    
28
    /**
29
     * Constructor from property file path
30
     * @param propertyFileName Path to properties file (filesystem or classpath)
31
     */
32
    public HikariConfig(String propertyFileName);
33
    
34
    /**
35
     * Validate the configuration and apply defaults
36
     * @throws IllegalArgumentException if configuration is invalid
37
     */
38
    public void validate();
39
    
40
    /**
41
     * Copy configuration state to another HikariConfig instance
42
     * @param other Target configuration instance
43
     */
44
    public void copyStateTo(HikariConfig other);
45
}
46
```
47

48
### Database Connection Settings
49

50
Core database connection configuration properties.
51

52
```java { .api }
53
/**
54
 * JDBC URL for database connection
55
 */
56
public String getJdbcUrl();
57
public void setJdbcUrl(String jdbcUrl);
58

59
/**
60
 * Database username and password
61
 */
62
public String getUsername();
63
public void setUsername(String username);
64
public String getPassword();
65
public void setPassword(String password);
66

67
/**
68
 * Set username and password atomically
69
 */
70
public Credentials getCredentials();
71
public void setCredentials(Credentials credentials);
72

73
/**
74
 * JDBC driver class name (optional if using DataSource)
75
 */
76
public String getDriverClassName();
77
public void setDriverClassName(String driverClassName);
78

79
/**
80
 * DataSource class name for DataSource-based configuration
81
 */
82
public String getDataSourceClassName();
83
public void setDataSourceClassName(String className);
84

85
/**
86
 * Direct DataSource instance
87
 */
88
public DataSource getDataSource();
89
public void setDataSource(DataSource dataSource);
90

91
/**
92
 * JNDI name for DataSource lookup
93
 */
94
public String getDataSourceJNDI();
95
public void setDataSourceJNDI(String jndiDataSource);
96
```
97

98
**Configuration Examples:**
99

100
```java
101
// JDBC URL approach
102
HikariConfig config = new HikariConfig();
103
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb?useSSL=false");
104
config.setUsername("dbuser");
105
config.setPassword("dbpass");
106
config.setDriverClassName("com.mysql.cj.jdbc.Driver");
107

108
// DataSource class approach
109
config.setDataSourceClassName("com.mysql.cj.jdbc.MysqlDataSource");
110
config.addDataSourceProperty("serverName", "localhost");
111
config.addDataSourceProperty("port", "3306");
112
config.addDataSourceProperty("databaseName", "mydb");
113
config.addDataSourceProperty("user", "dbuser");
114
config.addDataSourceProperty("password", "dbpass");
115

116
// JNDI approach
117
config.setDataSourceJNDI("java:comp/env/jdbc/MyDataSource");
118

119
// Direct DataSource
120
DataSource customDataSource = new MyCustomDataSource();
121
config.setDataSource(customDataSource);
122
```
123

124
### Pool Size Configuration
125

126
Connection pool sizing and behavior settings.
127

128
```java { .api }
129
/**
130
 * Maximum number of connections in the pool (default: 10)
131
 */
132
public int getMaximumPoolSize();
133
public void setMaximumPoolSize(int maxPoolSize);
134

135
/**
136
 * Minimum number of idle connections to maintain (default: same as maximumPoolSize)
137
 */
138
public int getMinimumIdle();
139
public void setMinimumIdle(int minIdle);
140
```
141

142
**Pool Sizing Examples:**
143

144
```java
145
// Fixed pool size (all connections always available)
146
config.setMaximumPoolSize(20);
147
config.setMinimumIdle(20);
148

149
// Variable pool size (scales based on demand)
150
config.setMaximumPoolSize(20);
151
config.setMinimumIdle(5);
152

153
// Default behavior (fixed pool of 10)
154
// Uses defaults: maxPoolSize=10, minIdle=10
155
```
156

157
### Timeout Configuration
158

159
Various timeout settings for connection management.
160

161
```java { .api }
162
/**
163
 * Maximum time to wait for connection from pool (default: 30 seconds)
164
 */
165
public long getConnectionTimeout();
166
public void setConnectionTimeout(long connectionTimeoutMs);
167

168
/**
169
 * Maximum time for connection validation (default: 5 seconds)
170
 */
171
public long getValidationTimeout();
172
public void setValidationTimeout(long validationTimeoutMs);
173

174
/**
175
 * Maximum idle time before connection is retired (default: 10 minutes, 0=disabled)
176
 */
177
public long getIdleTimeout();
178
public void setIdleTimeout(long idleTimeoutMs);
179

180
/**
181
 * Maximum lifetime of connection in pool (default: 30 minutes, 0=infinite)
182
 */
183
public long getMaxLifetime();
184
public void setMaxLifetime(long maxLifetimeMs);
185

186
/**
187
 * Connection leak detection threshold (default: 0=disabled)
188
 */
189
public long getLeakDetectionThreshold();
190
public void setLeakDetectionThreshold(long leakDetectionThresholdMs);
191

192
/**
193
 * Keepalive interval for idle connections (default: 0=disabled)
194
 */
195
public long getKeepaliveTime();
196
public void setKeepaliveTime(long keepaliveTimeMs);
197
```
198

199
**Timeout Configuration Examples:**
200

201
```java
202
// Production settings
203
config.setConnectionTimeout(20000);      // 20 seconds
204
config.setValidationTimeout(3000);       // 3 seconds  
205
config.setIdleTimeout(600000);           // 10 minutes
206
config.setMaxLifetime(1800000);          // 30 minutes
207
config.setLeakDetectionThreshold(60000); // 1 minute
208

209
// Development settings (more lenient)
210
config.setConnectionTimeout(30000);      // 30 seconds
211
config.setLeakDetectionThreshold(300000); // 5 minutes
212
config.setIdleTimeout(0);                // Disabled
213
```
214

215
### Connection Behavior Settings
216

217
Settings that control connection behavior and database interaction.
218

219
```java { .api }
220
/**
221
 * Default auto-commit mode for connections (default: true)
222
 */
223
public boolean isAutoCommit();
224
public void setAutoCommit(boolean isAutoCommit);
225

226
/**
227
 * Default read-only mode for connections (default: false)
228
 */
229
public boolean isReadOnly();
230
public void setReadOnly(boolean readOnly);
231

232
/**
233
 * Default transaction isolation level
234
 */
235
public String getTransactionIsolation();
236
public void setTransactionIsolation(String isolationLevel);
237

238
/**
239
 * Default catalog for connections
240
 */
241
public String getCatalog();
242
public void setCatalog(String catalog);
243

244
/**
245
 * Default schema for connections
246
 */
247
public String getSchema();
248
public void setSchema(String schema);
249

250
/**
251
 * SQL to execute on new connections
252
 */
253
public String getConnectionInitSql();
254
public void setConnectionInitSql(String connectionInitSql);
255

256
/**
257
 * SQL query to test connection validity (JDBC4 Connection.isValid() preferred)
258
 */
259
public String getConnectionTestQuery();
260
public void setConnectionTestQuery(String connectionTestQuery);
261
```
262

263
**Connection Behavior Examples:**
264

265
```java
266
// Read-only replica configuration
267
config.setReadOnly(true);
268
config.setTransactionIsolation("TRANSACTION_READ_COMMITTED");
269

270
// Connection initialization
271
config.setConnectionInitSql("SET SESSION sql_mode = 'STRICT_TRANS_TABLES'");
272

273
// Custom validation (prefer JDBC4 isValid() when possible)
274
config.setConnectionTestQuery("SELECT 1");
275

276
// Schema/catalog defaults
277
config.setSchema("myapp");
278
config.setCatalog("production");
279
```
280

281
### Advanced Configuration
282

283
Advanced pool behavior and integration settings.
284

285
```java { .api }
286
/**
287
 * Pool name for logging and JMX (auto-generated if not set)
288
 */
289
public String getPoolName();
290
public void setPoolName(String poolName);
291

292
/**
293
 * Allow pool suspension for maintenance (default: false)
294
 */
295
public boolean isAllowPoolSuspension();
296
public void setAllowPoolSuspension(boolean isAllowPoolSuspension);
297

298
/**
299
 * Isolate internal queries in separate transactions (default: false)
300
 */
301
public boolean isIsolateInternalQueries();
302
public void setIsolateInternalQueries(boolean isolate);
303

304
/**
305
 * Register MXBeans with JMX (default: false)
306
 */
307
public boolean isRegisterMbeans();
308
public void setRegisterMbeans(boolean register);
309

310
/**
311
 * Pool initialization failure timeout (default: 1ms)
312
 */
313
public long getInitializationFailTimeout();
314
public void setInitializationFailTimeout(long initializationFailTimeout);
315

316
/**
317
 * Custom thread factory for pool threads
318
 */
319
public ThreadFactory getThreadFactory();
320
public void setThreadFactory(ThreadFactory threadFactory);
321

322
/**
323
 * Custom scheduled executor for housekeeping
324
 */
325
public ScheduledExecutorService getScheduledExecutor();
326
public void setScheduledExecutor(ScheduledExecutorService executor);
327
```
328

329
**Advanced Configuration Examples:**
330

331
```java
332
// Production monitoring setup
333
config.setPoolName("MyApp-DB-Pool");
334
config.setRegisterMbeans(true);
335
config.setAllowPoolSuspension(true);
336

337
// Custom exception handling
338
config.setExceptionOverrideClassName("com.myapp.CustomSQLExceptionOverride");
339

340
// Fail-fast initialization (good for health checks)
341
config.setInitializationFailTimeout(2000); // 2 seconds
342

343
// Background initialization (good for startup performance)
344
config.setInitializationFailTimeout(-1); // Skip validation
345
```
346

347
### DataSource Properties
348

349
Configure underlying DataSource or Driver properties.
350

351
```java { .api }
352
/**
353
 * Add property for DataSource or Driver configuration
354
 * @param propertyName Property name (converted to setter for DataSource)
355
 * @param value Property value
356
 */
357
public void addDataSourceProperty(String propertyName, Object value);
358

359
/**
360
 * Get all DataSource properties
361
 */
362
public Properties getDataSourceProperties();
363

364
/**
365
 * Set DataSource properties in bulk
366
 */
367
public void setDataSourceProperties(Properties dsProperties);
368
```
369

370
**DataSource Properties Examples:**
371

372
```java
373
// MySQL DataSource properties
374
config.setDataSourceClassName("com.mysql.cj.jdbc.MysqlDataSource");
375
config.addDataSourceProperty("cachePrepStmts", "true");
376
config.addDataSourceProperty("prepStmtCacheSize", "250");
377
config.addDataSourceProperty("prepStmtCacheSqlLimit", "2048");
378
config.addDataSourceProperty("useServerPrepStmts", "true");
379
config.addDataSourceProperty("useLocalSessionState", "true");
380
config.addDataSourceProperty("rewriteBatchedStatements", "true");
381

382
// PostgreSQL DataSource properties
383
config.setDataSourceClassName("org.postgresql.ds.PGSimpleDataSource");
384
config.addDataSourceProperty("applicationName", "MyApplication");
385
config.addDataSourceProperty("loggerLevel", "INFO");
386

387
// Connection properties via JDBC URL (alternative approach)
388
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb?cachePrepStmts=true&prepStmtCacheSize=250");
389
```
390

391
### Property File Configuration
392

393
Load configuration from properties files.
394

395
**Example hikari.properties:**
396

397
```properties
398
# Database connection
399
jdbcUrl=jdbc:mysql://localhost:3306/mydb
400
username=dbuser
401
password=dbpass
402

403
# Pool settings
404
maximumPoolSize=20
405
minimumIdle=5
406

407
# Timeouts
408
connectionTimeout=30000
409
idleTimeout=600000
410
maxLifetime=1800000
411

412
# Other settings
413
poolName=MyApp-Pool
414
registerMbeans=true
415
leakDetectionThreshold=60000
416

417
# DataSource properties (when using dataSourceClassName)
418
dataSource.cachePrepStmts=true
419
dataSource.prepStmtCacheSize=250
420
```
421

422
**Usage:**
423

424
```java
425
// Load from file
426
HikariConfig config = new HikariConfig("/path/to/hikari.properties");
427

428
// Or from classpath
429
HikariConfig config = new HikariConfig("hikari.properties");
430

431
// Or using system property
432
System.setProperty("hikaricp.configurationFile", "hikari.properties");
433
HikariConfig config = new HikariConfig(); // Automatically loads file
434
```
435

436
### Configuration Validation
437

438
HikariCP validates configuration and applies sensible defaults.
439

440
```java
441
// Validation is automatically called by HikariDataSource constructor
442
HikariConfig config = new HikariConfig();
443
config.setJdbcUrl("jdbc:mysql://localhost:3306/test");
444
// Missing username/password will cause validation error
445

446
// Explicit validation
447
try {
448
    config.validate();
449
    System.out.println("Configuration is valid");
450
} catch (IllegalArgumentException e) {
451
    System.err.println("Configuration error: " + e.getMessage());
452
}
453
```
454

455
**Common Validation Rules:**
456

457
- Either `jdbcUrl` + optional `driverClassName`, or `dataSourceClassName`, or `dataSource` must be set
458
- `maxPoolSize` must be >= 1
459
- `connectionTimeout` and `validationTimeout` must be >= 250ms
460
- `maxLifetime` should be >= 30 seconds if set
461
- `leakDetectionThreshold` should be >= 2 seconds if set
462
- Pool name cannot contain ':' when JMX is enabled