Configuration Management

/**
 * Configuration class for HikariCP with comprehensive pool settings
 */
public class HikariConfig implements HikariConfigMXBean {
    /**
     * Default constructor. Loads configuration from system property 'hikaricp.configurationFile' if set.
     */
    public HikariConfig();
    
    /**
     * Construct a HikariConfig from the specified properties object.
     * @param properties the properties to configure from
     */
    public HikariConfig(Properties properties);
    
    /**
     * Construct a HikariConfig from the specified property file name.
     * propertyFileName will first be treated as a path in the file-system,
     * and if that fails Class.getResourceAsStream(propertyFileName) will be tried.
     * @param propertyFileName the name of the property file
     */
    public HikariConfig(String propertyFileName);
}

// Default constructor
HikariConfig config = new HikariConfig();

// From properties file
Properties props = new Properties();
props.setProperty("jdbcUrl", "jdbc:postgresql://localhost:5432/mydb");
props.setProperty("username", "user");
props.setProperty("password", "password");
HikariConfig config = new HikariConfig(props);

// From property file
HikariConfig config = new HikariConfig("/path/to/hikari.properties");

/**
 * Set the JDBC URL for DriverManager-based configuration
 * @param jdbcUrl the JDBC URL
 */
public void setJdbcUrl(String jdbcUrl);
public String getJdbcUrl();

/**
 * Set the DataSource class name provided by the JDBC driver
 * @param className the fully qualified DataSource class name
 */
public void setDataSourceClassName(String className);
public String getDataSourceClassName();

/**
 * Set a DataSource instance to be wrapped by the pool
 * @param dataSource a specific DataSource to be wrapped by the pool
 */
public void setDataSource(DataSource dataSource);
public DataSource getDataSource();

/**
 * Set the JNDI name for DataSource lookup
 * @param jndiDataSource the JNDI name
 */
public void setDataSourceJNDI(String jndiDataSource);
public String getDataSourceJNDI();

/**
 * Set the JDBC driver class name (may be needed with older drivers)
 * @param driverClassName the fully qualified driver class name
 */
public void setDriverClassName(String driverClassName);
public String getDriverClassName();

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

// DataSource class approach
config.setDataSourceClassName("org.postgresql.ds.PGSimpleDataSource");
config.addDataSourceProperty("serverName", "localhost");
config.addDataSourceProperty("portNumber", "5432");
config.addDataSourceProperty("databaseName", "mydb");

// Existing DataSource wrapping
DataSource existingDs = // ... obtain from somewhere
config.setDataSource(existingDs);

/**
 * Set the default username used for DataSource.getConnection(username, password) calls
 * @param username the database username
 */
public void setUsername(String username);
public String getUsername();

/**
 * Set the default password used for DataSource.getConnection(username, password) calls
 * @param password the database password
 */
public void setPassword(String password);
public String getPassword();

/**
 * Set the maximum size that the pool is allowed to reach, including both idle and in-use connections.
 * When the pool reaches this size, and no idle connections are available, calls to getConnection()
 * will block for up to connectionTimeout milliseconds before timing out.
 * @param maxPoolSize the maximum number of connections in the pool
 */
public void setMaximumPoolSize(int maxPoolSize);
public int getMaximumPoolSize();

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

// Typical pool sizing for a web application
config.setMaximumPoolSize(20);  // Max 20 connections
config.setMinimumIdle(5);       // Keep at least 5 idle connections

// High-throughput application
config.setMaximumPoolSize(50);
config.setMinimumIdle(10);

// Single-user application
config.setMaximumPoolSize(5);
config.setMinimumIdle(1);

/**
 * Set the maximum number of milliseconds that a client will wait for a connection from the pool.
 * If this time is exceeded without a connection becoming available, a SQLException will be thrown.
 * @param connectionTimeoutMs the connection timeout in milliseconds
 */
public void setConnectionTimeout(long connectionTimeoutMs);
public long getConnectionTimeout();

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

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

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

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

// Typical timeout configuration
config.setConnectionTimeout(30000);      // 30 seconds to get connection
config.setValidationTimeout(5000);       // 5 seconds to validate connection
config.setIdleTimeout(600000);           // 10 minutes idle timeout
config.setMaxLifetime(1800000);          // 30 minutes max connection lifetime
config.setLeakDetectionThreshold(60000); // 1 minute leak detection

// High-performance configuration (shorter timeouts)
config.setConnectionTimeout(1000);       // 1 second
config.setValidationTimeout(250);        // 250ms validation
config.setIdleTimeout(300000);           // 5 minutes idle
config.setMaxLifetime(900000);           // 15 minutes max lifetime

/**
 * Set the default auto-commit behavior of connections in the pool
 * @param isAutoCommit the desired auto-commit default for connections
 */
public void setAutoCommit(boolean isAutoCommit);
public boolean isAutoCommit();

/**
 * Set the default read-only behavior of connections in the pool
 * @param readOnly the desired read-only default for connections  
 */
public void setReadOnly(boolean readOnly);
public boolean isReadOnly();

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

/**
 * Set the default catalog name to be set on connections
 * @param catalog the catalog name, or null
 */
public void setCatalog(String catalog);
public String getCatalog();

// Typical OLTP configuration
config.setAutoCommit(true);
config.setReadOnly(false);
config.setTransactionIsolation("TRANSACTION_READ_COMMITTED");

// Read-only reporting configuration
config.setAutoCommit(false);
config.setReadOnly(true);
config.setTransactionIsolation("TRANSACTION_READ_UNCOMMITTED");

// Database-specific catalog
config.setCatalog("production_catalog");

/**
 * Set the SQL query to be executed to test the validity of connections.
 * Using the JDBC4 Connection.isValid() method to test connection validity can be more efficient.
 * @param connectionTestQuery a SQL query string
 */
public void setConnectionTestQuery(String connectionTestQuery);
public String getConnectionTestQuery();

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

// Database-specific connection testing
config.setConnectionTestQuery("SELECT 1");              // MySQL/PostgreSQL
config.setConnectionTestQuery("SELECT 1 FROM DUAL");    // Oracle
config.setConnectionTestQuery("VALUES 1");              // DB2

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

/**
 * Set whether or not pool suspension is allowed. There is a performance impact when pool suspension is enabled.
 * @param isAllowPoolSuspension the desired pool suspension allowance
 */
public void setAllowPoolSuspension(boolean isAllowPoolSuspension);
public boolean isAllowPoolSuspension();

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

/**
 * Set whether or not JMX MBeans are registered
 * @param register whether to register JMX MBeans
 */
public void setRegisterMbeans(boolean register);
public boolean isRegisterMbeans();

/**
 * Set the name of the connection pool for MBean uniqueness and logging
 * @param poolName the name of the connection pool
 */
public void setPoolName(String poolName);
public String getPoolName();

/**
 * Set the thread factory to be used to create threads
 * @param threadFactory the thread factory (setting to null causes the default thread factory to be used)
 */
public void setThreadFactory(ThreadFactory threadFactory);
public ThreadFactory getThreadFactory();

/**
 * Set the ScheduledExecutorService used for housekeeping
 * @param executor the ScheduledExecutorService
 */
public void setScheduledExecutor(ScheduledExecutorService executor);
public ScheduledExecutorService getScheduledExecutor();

/**
 * Add a property to be set on the DataSource
 * @param propertyName the property name
 * @param value the property value
 */
public void addDataSourceProperty(String propertyName, Object value);

/**
 * Get all DataSource properties
 * @return Properties object containing all DataSource properties
 */
public Properties getDataSourceProperties();

/**
 * Set DataSource properties from a Properties object
 * @param dsProperties Properties containing DataSource configuration
 */
public void setDataSourceProperties(Properties dsProperties);

// PostgreSQL DataSource properties
config.setDataSourceClassName("org.postgresql.ds.PGSimpleDataSource");
config.addDataSourceProperty("serverName", "localhost");
config.addDataSourceProperty("portNumber", 5432);
config.addDataSourceProperty("databaseName", "mydb");
config.addDataSourceProperty("user", "dbuser");
config.addDataSourceProperty("password", "dbpass");

// MySQL DataSource properties
config.setDataSourceClassName("com.mysql.cj.jdbc.MysqlDataSource");
config.addDataSourceProperty("serverName", "localhost");
config.addDataSourceProperty("port", 3306);
config.addDataSourceProperty("databaseName", "mydb");
config.addDataSourceProperty("useSSL", false);

/**
 * Set the pool initialization failure timeout. This setting applies to pool initialization
 * when HikariDataSource is constructed with a HikariConfig, or when HikariDataSource is
 * constructed using the no-arg constructor and getConnection() is called.
 * @param initializationFailTimeout the number of milliseconds before pool initialization fails
 */
public void setInitializationFailTimeout(long initializationFailTimeout);
public long getInitializationFailTimeout();

/**
 * @deprecated see setInitializationFailTimeout(long)
 */
@Deprecated
public void setInitializationFailFast(boolean failFast);

/**
 * @deprecated see getInitializationFailTimeout()
 */
@Deprecated
public boolean isInitializationFailFast();

/**
 * Validate the configuration. This method checks for common configuration errors
 * and applies default values where appropriate.
 */
public void validate();

/**
 * Copy the state of this HikariConfig to another HikariConfig instance
 * @param other the target HikariConfig to copy state to
 */
public void copyState(HikariConfig other);

// Configuration validation
HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
config.setUsername("user");
config.setPassword("password");

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

// Configuration copying
HikariConfig template = new HikariConfig();
template.setMaximumPoolSize(20);
template.setConnectionTimeout(30000);

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