0
# Configuration Management
1

2
Comprehensive configuration system with over 30 configuration properties for fine-tuning pool behavior, connection settings, and performance optimization.
3

4
## Capabilities
5

6
### HikariConfig Constructor Options
7

8
Multiple ways to create and initialize HikariConfig with various configuration sources.
9

10
```java { .api }
11
/**
12
 * Configuration class for HikariCP with comprehensive pool settings
13
 */
14
public class HikariConfig implements HikariConfigMXBean {
15
    /**
16
     * Default constructor. Loads configuration from system property 'hikaricp.configurationFile' if set.
17
     */
18
    public HikariConfig();
19
    
20
    /**
21
     * Construct a HikariConfig from the specified properties object.
22
     * @param properties the properties to configure from
23
     */
24
    public HikariConfig(Properties properties);
25
    
26
    /**
27
     * Construct a HikariConfig from the specified property file name.
28
     * propertyFileName will first be treated as a path in the file-system,
29
     * and if that fails Class.getResourceAsStream(propertyFileName) will be tried.
30
     * @param propertyFileName the name of the property file
31
     */
32
    public HikariConfig(String propertyFileName);
33
}
34
```
35

36
**Usage Examples:**
37

38
```java
39
// Default constructor
40
HikariConfig config = new HikariConfig();
41

42
// From properties file
43
Properties props = new Properties();
44
props.setProperty("jdbcUrl", "jdbc:postgresql://localhost:5432/mydb");
45
props.setProperty("username", "user");
46
props.setProperty("password", "password");
47
HikariConfig config = new HikariConfig(props);
48

49
// From property file
50
HikariConfig config = new HikariConfig("/path/to/hikari.properties");
51
```
52

53
### Essential Database Connection Configuration
54

55
Core properties required to establish database connectivity.
56

57
```java { .api }
58
/**
59
 * Set the JDBC URL for DriverManager-based configuration
60
 * @param jdbcUrl the JDBC URL
61
 */
62
public void setJdbcUrl(String jdbcUrl);
63
public String getJdbcUrl();
64

65
/**
66
 * Set the DataSource class name provided by the JDBC driver
67
 * @param className the fully qualified DataSource class name
68
 */
69
public void setDataSourceClassName(String className);
70
public String getDataSourceClassName();
71

72
/**
73
 * Set a DataSource instance to be wrapped by the pool
74
 * @param dataSource a specific DataSource to be wrapped by the pool
75
 */
76
public void setDataSource(DataSource dataSource);
77
public DataSource getDataSource();
78

79
/**
80
 * Set the JNDI name for DataSource lookup
81
 * @param jndiDataSource the JNDI name
82
 */
83
public void setDataSourceJNDI(String jndiDataSource);
84
public String getDataSourceJNDI();
85

86
/**
87
 * Set the JDBC driver class name (may be needed with older drivers)
88
 * @param driverClassName the fully qualified driver class name
89
 */
90
public void setDriverClassName(String driverClassName);
91
public String getDriverClassName();
92
```
93

94
**Usage Examples:**
95

96
```java
97
// JDBC URL approach (recommended for most cases)
98
config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
99
config.setDriverClassName("org.postgresql.Driver"); // Usually auto-detected
100

101
// DataSource class approach
102
config.setDataSourceClassName("org.postgresql.ds.PGSimpleDataSource");
103
config.addDataSourceProperty("serverName", "localhost");
104
config.addDataSourceProperty("portNumber", "5432");
105
config.addDataSourceProperty("databaseName", "mydb");
106

107
// Existing DataSource wrapping
108
DataSource existingDs = // ... obtain from somewhere
109
config.setDataSource(existingDs);
110
```
111

112
### Authentication Configuration
113

114
Database authentication and credential settings.
115

116
```java { .api }
117
/**
118
 * Set the default username used for DataSource.getConnection(username, password) calls
119
 * @param username the database username
120
 */
121
public void setUsername(String username);
122
public String getUsername();
123

124
/**
125
 * Set the default password used for DataSource.getConnection(username, password) calls
126
 * @param password the database password
127
 */
128
public void setPassword(String password);
129
public String getPassword();
130
```
131

132
### Pool Sizing Configuration
133

134
Configuration for controlling the size and behavior of the connection pool.
135

136
```java { .api }
137
/**
138
 * Set the maximum size that the pool is allowed to reach, including both idle and in-use connections.
139
 * When the pool reaches this size, and no idle connections are available, calls to getConnection()
140
 * will block for up to connectionTimeout milliseconds before timing out.
141
 * @param maxPoolSize the maximum number of connections in the pool
142
 */
143
public void setMaximumPoolSize(int maxPoolSize);
144
public int getMaximumPoolSize();
145

146
/**
147
 * Set the minimum number of idle connections that HikariCP tries to maintain in the pool.
148
 * If the idle connections dip below this value, HikariCP will make a best effort to restore them quickly.
149
 * @param minIdle the minimum number of idle connections in the pool to maintain
150
 */
151
public void setMinimumIdle(int minIdle);
152
public int getMinimumIdle();
153
```
154

155
**Usage Examples:**
156

157
```java
158
// Typical pool sizing for a web application
159
config.setMaximumPoolSize(20);  // Max 20 connections
160
config.setMinimumIdle(5);       // Keep at least 5 idle connections
161

162
// High-throughput application
163
config.setMaximumPoolSize(50);
164
config.setMinimumIdle(10);
165

166
// Single-user application
167
config.setMaximumPoolSize(5);
168
config.setMinimumIdle(1);
169
```
170

171
### Timeout Configuration
172

173
Various timeout settings controlling connection lifecycle and pool behavior.
174

175
```java { .api }
176
/**
177
 * Set the maximum number of milliseconds that a client will wait for a connection from the pool.
178
 * If this time is exceeded without a connection becoming available, a SQLException will be thrown.
179
 * @param connectionTimeoutMs the connection timeout in milliseconds
180
 */
181
public void setConnectionTimeout(long connectionTimeoutMs);
182
public long getConnectionTimeout();
183

184
/**
185
 * Set the maximum number of milliseconds that the pool will wait for a connection to be validated as alive.
186
 * @param validationTimeoutMs the validation timeout in milliseconds
187
 */
188
public void setValidationTimeout(long validationTimeoutMs);
189
public long getValidationTimeout();
190

191
/**
192
 * Set the maximum amount of time (in milliseconds) that a connection is allowed to sit idle in the pool.
193
 * A value of 0 means that idle connections are never removed from the pool.
194
 * @param idleTimeoutMs the idle timeout in milliseconds
195
 */
196
public void setIdleTimeout(long idleTimeoutMs);
197
public long getIdleTimeout();
198

199
/**
200
 * Set the maximum lifetime of a connection in the pool. When a connection reaches this timeout,
201
 * even if recently used, it will be retired from the pool. An in-use connection will never be retired,
202
 * only when it is idle will it be removed.
203
 * @param maxLifetimeMs the maximum connection lifetime in milliseconds
204
 */
205
public void setMaxLifetime(long maxLifetimeMs);
206
public long getMaxLifetime();
207

208
/**
209
 * Set the amount of time that a connection can be out of the pool before a message is logged
210
 * indicating a possible connection leak. A value of 0 means leak detection is disabled.
211
 * @param leakDetectionThresholdMs the connection leak detection threshold in milliseconds
212
 */
213
public void setLeakDetectionThreshold(long leakDetectionThresholdMs);
214
public long getLeakDetectionThreshold();
215
```
216

217
**Usage Examples:**
218

219
```java
220
// Typical timeout configuration
221
config.setConnectionTimeout(30000);      // 30 seconds to get connection
222
config.setValidationTimeout(5000);       // 5 seconds to validate connection
223
config.setIdleTimeout(600000);           // 10 minutes idle timeout
224
config.setMaxLifetime(1800000);          // 30 minutes max connection lifetime
225
config.setLeakDetectionThreshold(60000); // 1 minute leak detection
226

227
// High-performance configuration (shorter timeouts)
228
config.setConnectionTimeout(1000);       // 1 second
229
config.setValidationTimeout(250);        // 250ms validation
230
config.setIdleTimeout(300000);           // 5 minutes idle
231
config.setMaxLifetime(900000);           // 15 minutes max lifetime
232
```
233

234
### Connection Behavior Configuration
235

236
Settings that control how connections behave and are managed.
237

238
```java { .api }
239
/**
240
 * Set the default auto-commit behavior of connections in the pool
241
 * @param isAutoCommit the desired auto-commit default for connections
242
 */
243
public void setAutoCommit(boolean isAutoCommit);
244
public boolean isAutoCommit();
245

246
/**
247
 * Set the default read-only behavior of connections in the pool
248
 * @param readOnly the desired read-only default for connections  
249
 */
250
public void setReadOnly(boolean readOnly);
251
public boolean isReadOnly();
252

253
/**
254
 * Set the default transaction isolation level. The specified value is the constant name
255
 * from the Connection class, eg. TRANSACTION_REPEATABLE_READ.
256
 * @param isolationLevel the name of the isolation level
257
 */
258
public void setTransactionIsolation(String isolationLevel);
259
public String getTransactionIsolation();
260

261
/**
262
 * Set the default catalog name to be set on connections
263
 * @param catalog the catalog name, or null
264
 */
265
public void setCatalog(String catalog);
266
public String getCatalog();
267
```
268

269
**Usage Examples:**
270

271
```java
272
// Typical OLTP configuration
273
config.setAutoCommit(true);
274
config.setReadOnly(false);
275
config.setTransactionIsolation("TRANSACTION_READ_COMMITTED");
276

277
// Read-only reporting configuration
278
config.setAutoCommit(false);
279
config.setReadOnly(true);
280
config.setTransactionIsolation("TRANSACTION_READ_UNCOMMITTED");
281

282
// Database-specific catalog
283
config.setCatalog("production_catalog");
284
```
285

286
### Connection Testing and Validation
287

288
Configuration for testing and validating connections in the pool.
289

290
```java { .api }
291
/**
292
 * Set the SQL query to be executed to test the validity of connections.
293
 * Using the JDBC4 Connection.isValid() method to test connection validity can be more efficient.
294
 * @param connectionTestQuery a SQL query string
295
 */
296
public void setConnectionTestQuery(String connectionTestQuery);
297
public String getConnectionTestQuery();
298

299
/**
300
 * Set the SQL string that will be executed on all new connections when they are created,
301
 * before they are added to the pool. If this query fails, it will be treated as a failed connection attempt.
302
 * @param connectionInitSql the SQL to execute on new connections
303
 */
304
public void setConnectionInitSql(String connectionInitSql);
305
public String getConnectionInitSql();
306
```
307

308
**Usage Examples:**
309

310
```java
311
// Database-specific connection testing
312
config.setConnectionTestQuery("SELECT 1");              // MySQL/PostgreSQL
313
config.setConnectionTestQuery("SELECT 1 FROM DUAL");    // Oracle
314
config.setConnectionTestQuery("VALUES 1");              // DB2
315

316
// Connection initialization
317
config.setConnectionInitSql("SET SESSION sql_mode='STRICT_TRANS_TABLES'");
318
```
319

320
### Advanced Pool Configuration
321

322
Advanced settings for fine-tuning pool behavior and performance.
323

324
```java { .api }
325
/**
326
 * Set whether or not pool suspension is allowed. There is a performance impact when pool suspension is enabled.
327
 * @param isAllowPoolSuspension the desired pool suspension allowance
328
 */
329
public void setAllowPoolSuspension(boolean isAllowPoolSuspension);
330
public boolean isAllowPoolSuspension();
331

332
/**
333
 * Set whether HikariCP should isolate internal pool queries such as the connection alive test.
334
 * @param isolate whether to isolate internal queries
335
 */
336
public void setIsolateInternalQueries(boolean isolate);
337
public boolean isIsolateInternalQueries();
338

339
/**
340
 * Set whether or not JMX MBeans are registered
341
 * @param register whether to register JMX MBeans
342
 */
343
public void setRegisterMbeans(boolean register);
344
public boolean isRegisterMbeans();
345

346
/**
347
 * Set the name of the connection pool for MBean uniqueness and logging
348
 * @param poolName the name of the connection pool
349
 */
350
public void setPoolName(String poolName);
351
public String getPoolName();
352

353
/**
354
 * Set the thread factory to be used to create threads
355
 * @param threadFactory the thread factory (setting to null causes the default thread factory to be used)
356
 */
357
public void setThreadFactory(ThreadFactory threadFactory);
358
public ThreadFactory getThreadFactory();
359

360
/**
361
 * Set the ScheduledExecutorService used for housekeeping
362
 * @param executor the ScheduledExecutorService
363
 */
364
public void setScheduledExecutor(ScheduledExecutorService executor);
365
public ScheduledExecutorService getScheduledExecutor();
366
```
367

368
### DataSource Properties Configuration
369

370
Configuration for DataSource-specific properties when using dataSourceClassName.
371

372
```java { .api }
373
/**
374
 * Add a property to be set on the DataSource
375
 * @param propertyName the property name
376
 * @param value the property value
377
 */
378
public void addDataSourceProperty(String propertyName, Object value);
379

380
/**
381
 * Get all DataSource properties
382
 * @return Properties object containing all DataSource properties
383
 */
384
public Properties getDataSourceProperties();
385

386
/**
387
 * Set DataSource properties from a Properties object
388
 * @param dsProperties Properties containing DataSource configuration
389
 */
390
public void setDataSourceProperties(Properties dsProperties);
391
```
392

393
**Usage Examples:**
394

395
```java
396
// PostgreSQL DataSource properties
397
config.setDataSourceClassName("org.postgresql.ds.PGSimpleDataSource");
398
config.addDataSourceProperty("serverName", "localhost");
399
config.addDataSourceProperty("portNumber", 5432);
400
config.addDataSourceProperty("databaseName", "mydb");
401
config.addDataSourceProperty("user", "dbuser");
402
config.addDataSourceProperty("password", "dbpass");
403

404
// MySQL DataSource properties
405
config.setDataSourceClassName("com.mysql.cj.jdbc.MysqlDataSource");
406
config.addDataSourceProperty("serverName", "localhost");
407
config.addDataSourceProperty("port", 3306);
408
config.addDataSourceProperty("databaseName", "mydb");
409
config.addDataSourceProperty("useSSL", false);
410
```
411

412
### Pool Initialization Configuration
413

414
Settings controlling how the pool initializes and handles startup failures.
415

416
```java { .api }
417
/**
418
 * Set the pool initialization failure timeout. This setting applies to pool initialization
419
 * when HikariDataSource is constructed with a HikariConfig, or when HikariDataSource is
420
 * constructed using the no-arg constructor and getConnection() is called.
421
 * @param initializationFailTimeout the number of milliseconds before pool initialization fails
422
 */
423
public void setInitializationFailTimeout(long initializationFailTimeout);
424
public long getInitializationFailTimeout();
425

426
/**
427
 * @deprecated see setInitializationFailTimeout(long)
428
 */
429
@Deprecated
430
public void setInitializationFailFast(boolean failFast);
431

432
/**
433
 * @deprecated see getInitializationFailTimeout()
434
 */
435
@Deprecated
436
public boolean isInitializationFailFast();
437
```
438

439
### Configuration Validation and Utility
440

441
Methods for validating configuration and managing configuration state.
442

443
```java { .api }
444
/**
445
 * Validate the configuration. This method checks for common configuration errors
446
 * and applies default values where appropriate.
447
 */
448
public void validate();
449

450
/**
451
 * Copy the state of this HikariConfig to another HikariConfig instance
452
 * @param other the target HikariConfig to copy state to
453
 */
454
public void copyState(HikariConfig other);
455
```
456

457
**Usage Examples:**
458

459
```java
460
// Configuration validation
461
HikariConfig config = new HikariConfig();
462
config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
463
config.setUsername("user");
464
config.setPassword("password");
465

466
try {
467
    config.validate(); // Throws exception if configuration is invalid
468
    HikariDataSource dataSource = new HikariDataSource(config);
469
} catch (IllegalArgumentException e) {
470
    System.err.println("Invalid configuration: " + e.getMessage());
471
}
472

473
// Configuration copying
474
HikariConfig template = new HikariConfig();
475
template.setMaximumPoolSize(20);
476
template.setConnectionTimeout(30000);
477

478
HikariConfig productionConfig = new HikariConfig();
479
template.copyState(productionConfig);
480
productionConfig.setJdbcUrl("jdbc:postgresql://prod-server:5432/proddb");
481
```