0
# Configuration Management
1

2
HikariCP provides comprehensive configuration management through the HikariConfig class, supporting property files, programmatic configuration, and runtime tuning through JMX.
3

4
## Capabilities
5

6
### HikariConfig Class
7

8
Main configuration class with validation, property loading, and comprehensive pool settings.
9

10
```java { .api }
11
/**
12
 * Configuration class for HikariCP connection pools
13
 */
14
public class HikariConfig implements HikariConfigMXBean {
15
    // Constructors
16
    public HikariConfig();
17
    public HikariConfig(Properties properties);
18
    public HikariConfig(String propertyFileName);
19
    
20
    // JDBC Connection Settings
21
    public String getJdbcUrl();
22
    public void setJdbcUrl(String jdbcUrl);
23
    public String getUsername();
24
    public void setUsername(String username);
25
    public String getPassword();
26
    public void setPassword(String password);
27
    public String getDriverClassName();
28
    public void setDriverClassName(String driverClassName);
29
    
30
    // DataSource Configuration
31
    public DataSource getDataSource();
32
    public void setDataSource(DataSource dataSource);
33
    public String getDataSourceClassName();
34
    public void setDataSourceClassName(String className);
35
    public String getDataSourceJNDI();
36
    public void setDataSourceJNDI(String jndiDataSource);
37
    public Properties getDataSourceProperties();
38
    public void setDataSourceProperties(Properties dsProperties);
39
    public void addDataSourceProperty(String propertyName, Object value);
40
    
41
    // Pool Sizing
42
    public int getMaximumPoolSize();
43
    public void setMaximumPoolSize(int maxPoolSize);
44
    public int getMinimumIdle();
45
    public void setMinimumIdle(int minIdle);
46
    
47
    // Timeouts (milliseconds)
48
    public long getConnectionTimeout();
49
    public void setConnectionTimeout(long connectionTimeoutMs);
50
    public long getIdleTimeout();
51
    public void setIdleTimeout(long idleTimeoutMs);
52
    public long getMaxLifetime();
53
    public void setMaxLifetime(long maxLifetimeMs);
54
    public long getValidationTimeout();
55
    public void setValidationTimeout(long validationTimeoutMs);
56
    public long getInitializationFailTimeout();
57
    public void setInitializationFailTimeout(long initializationFailTimeout);
58
    public long getLeakDetectionThreshold();
59
    public void setLeakDetectionThreshold(long leakDetectionThresholdMs);
60
    public long getKeepaliveTime();
61
    public void setKeepaliveTime(long keepaliveTimeMs);
62
    
63
    // Connection Behavior
64
    public boolean isAutoCommit();
65
    public void setAutoCommit(boolean isAutoCommit);
66
    public boolean isReadOnly();
67
    public void setReadOnly(boolean readOnly);
68
    public String getTransactionIsolation();
69
    public void setTransactionIsolation(String isolationLevel);
70
    public String getCatalog();
71
    public void setCatalog(String catalog);
72
    public String getSchema();
73
    public void setSchema(String schema);
74
    
75
    // Connection Testing
76
    public String getConnectionTestQuery();
77
    public void setConnectionTestQuery(String connectionTestQuery);
78
    public String getConnectionInitSql();
79
    public void setConnectionInitSql(String connectionInitSql);
80
    
81
    // Pool Management
82
    public String getPoolName();
83
    public void setPoolName(String poolName);
84
    public boolean isAllowPoolSuspension();
85
    public void setAllowPoolSuspension(boolean isAllowPoolSuspension);
86
    public boolean isIsolateInternalQueries();
87
    public void setIsolateInternalQueries(boolean isolate);
88
    public boolean isRegisterMbeans();
89
    public void setRegisterMbeans(boolean register);
90
    
91
    // Advanced Configuration
92
    public ThreadFactory getThreadFactory();
93
    public void setThreadFactory(ThreadFactory threadFactory);
94
    public ScheduledExecutorService getScheduledExecutor();
95
    public void setScheduledExecutor(ScheduledExecutorService executor);
96
    public String getExceptionOverrideClassName();
97
    public void setExceptionOverrideClassName(String exceptionOverrideClassName);
98
    
99
    // Metrics and Health Checks
100
    public MetricsTrackerFactory getMetricsTrackerFactory();
101
    public void setMetricsTrackerFactory(MetricsTrackerFactory metricsTrackerFactory);
102
    public Object getMetricRegistry();
103
    public void setMetricRegistry(Object metricRegistry);
104
    public Object getHealthCheckRegistry();
105
    public void setHealthCheckRegistry(Object healthCheckRegistry);
106
    public Properties getHealthCheckProperties();
107
    public void setHealthCheckProperties(Properties healthCheckProperties);
108
    public void addHealthCheckProperty(String key, String value);
109
    
110
    // Configuration Management
111
    public void validate();
112
    public void copyStateTo(HikariConfig other);
113
}
114
```
115

116
**Usage Examples:**
117

118
### Programmatic Configuration
119

120
```java
121
import com.zaxxer.hikari.HikariConfig;
122
import com.zaxxer.hikari.HikariDataSource;
123

124
// Basic configuration
125
HikariConfig config = new HikariConfig();
126
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
127
config.setUsername("dbuser");
128
config.setPassword("dbpass");
129
config.setMaximumPoolSize(20);
130
config.setMinimumIdle(5);
131
config.setConnectionTimeout(30000);      // 30 seconds
132
config.setIdleTimeout(600000);           // 10 minutes
133
config.setMaxLifetime(1800000);          // 30 minutes
134
config.setPoolName("MyAppPool");
135

136
// Advanced settings
137
config.setAutoCommit(false);
138
config.setConnectionTestQuery("SELECT 1");
139
config.setLeakDetectionThreshold(60000); // 1 minute
140

141
HikariDataSource dataSource = new HikariDataSource(config);
142
```
143

144
### Property File Configuration
145

146
```java
147
// Load from classpath
148
HikariConfig config = new HikariConfig("/database.properties");
149

150
// Load from file system
151
HikariConfig config = new HikariConfig("/path/to/database.properties");
152
```
153

154
Example property file content:
155
```properties
156
jdbcUrl=jdbc:mysql://localhost:3306/mydb
157
username=dbuser
158
password=dbpass
159
maximumPoolSize=20
160
minimumIdle=5
161
connectionTimeout=30000
162
idleTimeout=600000
163
maxLifetime=1800000
164
poolName=MyAppPool
165
```
166

167
### Properties Object Configuration
168

169
```java
170
Properties props = new Properties();
171
props.setProperty("jdbcUrl", "jdbc:mysql://localhost:3306/mydb");
172
props.setProperty("username", "dbuser");
173
props.setProperty("password", "dbpass");
174
props.setProperty("maximumPoolSize", "20");
175

176
HikariConfig config = new HikariConfig(props);
177
```
178

179
### DataSource Configuration
180

181
```java
182
// Using existing DataSource
183
HikariConfig config = new HikariConfig();
184
config.setDataSource(existingDataSource);
185
config.setMaximumPoolSize(15);
186

187
// Using DataSource class name
188
HikariConfig config = new HikariConfig();
189
config.setDataSourceClassName("com.mysql.cj.jdbc.MysqlDataSource");
190
config.addDataSourceProperty("serverName", "localhost");
191
config.addDataSourceProperty("port", "3306");
192
config.addDataSourceProperty("databaseName", "mydb");
193
config.addDataSourceProperty("user", "dbuser");
194
config.addDataSourceProperty("password", "dbpass");
195
```
196

197
## Configuration Validation
198

199
HikariConfig provides comprehensive validation to ensure pool settings are valid and compatible:
200

201
```java
202
HikariConfig config = new HikariConfig();
203
// Set configuration properties...
204

205
try {
206
    config.validate();
207
    System.out.println("Configuration is valid");
208
} catch (IllegalArgumentException e) {
209
    System.err.println("Configuration error: " + e.getMessage());
210
}
211
```
212

213
## Configuration Best Practices
214

215
### Pool Sizing
216
- **maximumPoolSize**: Start with 10, tune based on load
217
- **minimumIdle**: Set to same as maximumPoolSize for stable performance
218
- Use `minimumIdle < maximumPoolSize` only if connection acquisition is fast
219

220
### Timeouts
221
- **connectionTimeout**: 30 seconds is usually sufficient
222
- **idleTimeout**: 10 minutes prevents excessive connection churn
223
- **maxLifetime**: 30 minutes handles connection refreshing
224
- **validationTimeout**: Should be less than connectionTimeout
225

226
### Connection Testing
227
- Use `connectionTestQuery` only if driver doesn't support JDBC 4.0
228
- Prefer `SELECT 1` for MySQL, `SELECT 1 FROM DUAL` for Oracle
229

230
### Leak Detection
231
- Set `leakDetectionThreshold` in development/test environments
232
- Typical value: 60000ms (1 minute) for leak detection
233

234
## Types
235

236
```java { .api }
237
// Supporting interfaces and types
238
public interface HikariConfigMXBean {
239
    // Runtime configuration methods (subset of HikariConfig)
240
    long getConnectionTimeout();
241
    void setConnectionTimeout(long connectionTimeoutMs);
242
    long getValidationTimeout();
243
    void setValidationTimeout(long validationTimeoutMs);
244
    long getIdleTimeout();
245
    void setIdleTimeout(long idleTimeoutMs);
246
    long getLeakDetectionThreshold();
247
    void setLeakDetectionThreshold(long leakDetectionThresholdMs);
248
    long getMaxLifetime();
249
    void setMaxLifetime(long maxLifetimeMs);
250
    int getMinimumIdle();
251
    void setMinimumIdle(int minIdle);
252
    int getMaximumPoolSize();
253
    void setMaximumPoolSize(int maxPoolSize);
254
    void setPassword(String password);
255
    void setUsername(String username);
256
    String getPoolName();
257
    String getCatalog();
258
    void setCatalog(String catalog);
259
}
260
```