HikariCP 的全部配置介绍来自其首页,主要分为必填项和可选项,对于大部分配置项,HikariCP会有默认设置,官方建议在使用时无需过多的调整。 一些非必要属性的配置说明来自《HikariCP数据库连接池实战》。
相比其他数据库连接池,HikariCP会少一些配置项,作者的原话是:
In keeping with the simple is better or less is more design philosophy, some configuration axis are intentionally left out.
必填配置
需填写三项:
dataSourceClassName、jdbcUrl 二选一
username
password
dataSourceClassName
顾名思义,该属性就是 JDBC 驱动中DataSource
的名称。dataSourceClassName
和jdbcUrl
都是可以的,但作者更推荐 dataSourceClassName(DataSource-based
),不过对于使用 Spring Boot 自动装配的用户,还是需使用jdbcUrl 配置。此外,MySQL DataSource 并不支持网络超按时,建议使用 jdbcUrl 的方式。
jdbcUrl
表明 HikariCP 使用的是传统的DriverManager-based
配置。虽然作者认为基于 dataSourceClassName 的配置更加优越,但在实际部署上两种方式并没有差别。当使用某些老的驱动程序时,可能还需要设置 driverClassName 属性,但首先尝试不使用该属性。
username & password
从驱动中获取连接时使用到的身份认证用户名和密码。对于 DataSource,其使用 DataSouce.getConnection(String username, String password),但对于 DriverManager,由于每个 Driver 特征不同,HikariCP 会将 username 和 password属性配置在 Properties 文件中,使用的是getConnection(String url, java.util.Properties info)
方法。当然也可也以跳过此步,使用addDataSourceProperty("username", ...)
及addDataSourceProperty("pass", ...)
。
可选配置
常用配置
autoCommit
控制从池中返回的连接的默认自动提交行为。Default: true
connectionTimeout(重要)
控制客户端等待池中连接的最长毫秒数,如果在没有连接可用的情况下超过此时间,则抛出SQLException,最低可接受的连接超时为250ms,Default: 30000 (30s)。
idleTimeout
控制连接允许被闲置在池中的最大时间(此设置仅适用于minimumIdle定义为比maximumPoolSize小)。当整个连接池数量在 minimumIdle 时,空闲连接将不会退役。空闲连接在这个超时时间之前不可能退役。该值为 0 表示空闲连接永远不可能从连接池中移除。该值允许的最小值是:10000(10s),Default: 600000(10min)。
原文中还有一句
Whether a connection is retired as idle or not is subject to a maximum variation of +30 seconds, and average variation of +15 seconds.
并不太好理解其含义。可能是指在达到 idleTimeout 后还需要的部分时间(比如检测任务的间隔时间)进行辨别。
maxLifeTime(重要)
控制池中连接的最大生命周期,使用中的连接永远不会退役,只有当它在关闭后在会被移除。作者强烈建议用户设置此值,并且它应该比任何数据源的连接源的连接限制短几秒。值为0表示无限期生存,Default: 1800000(30min)。
有些使用MySQL的应用会报如下的错误:
The last packet sent successfully to the server was 0 milliseconds ago. The driver has not received any packets from the server.
这个问题分两种情况来看,是立即发生还是一段时间以后发生?如果是一段时间以后发生,在数据库的wait_timeout短于HikariCP的maxLifetime值的时候,发生的情况并不少见。一般来说,可以将maxLifetime设置缩短到900000毫秒(15分钟)然而更好的方法是,确定MySQL配置的wait_timeout值是什么,并将HikariCP设置为比maxLifetime短几分钟。
connectionTestQuery
作者强烈建议,如果驱动支持 JDBC4,请不要使用这个属性。这适用于不支持 JDBC4 的 Connection.isValid()
的驱动。该属性是一个检测查询,在数据库连接池给出连接之前进行查询,以验证与数据库的连接是否仍然存在且有效。
如果追求极致性能,建议不设置此值,当不配置此值时会通过ping命令进行检测,性能会更好。 Default: none
minimumIdle
控制HikariCP尝试在池中维护的最小空闲连接数,若空闲连接数低于此值且池中的总连接数小于maximumPoolSize,则HikariCP将尽最大努力有效添加其他连接。
为了最大提高性能和对峰值需求的响应能力,作者不建议设置此值,而是让HikariCP充当一个固定大小连接池。若该参数未设置,则置为 maximumPoolSize,当连接关闭时,将会在池中被替换。如果设置了此值,那 HikariCP 就是一个大小可变的池,即使使用情况上下浮动,连接池也会保持 minimumIdle 连接可用。Default: same as maximumPoolSize
maximumPoolSize
控制连接池到达的最大大小,包括空闲的和正在使用的连接,由此值控制后端的实际连接的最大数量。当池到达此大小且没有空闲连接可使用时,对 getConnection 的调用将阻塞至超时前 connectionTimeout 毫秒。
metricRegistry
允许用户指定池使用的 MetricRegistry 示例,记录各种指标度量值。
healthCheckRegistry
允许用户指定池使用的 HealthCheckRegistry 示例,报告当前系统的健康信息。(Micrometer不支持)
poolName
标识连接池的用户定义名称,主要用于显示在日志记录和JMX管理控制台上。Default: auto-generated
非常用配置
initializationFailTimeout
如果池无法成功初始化连接,则此属性控制池是否“快速失败”。任何正数都被认为是尝试获取初始连接的毫秒数;在此期间,应用程序线程将被阻塞。如果在超时发生之前无法获取连接,则将引发异常。initializationFailTimeout超时发生在connectionTimeout阶段之后。如果值为0,HikariCP将尝试获取并验证连接。如果获得连接但验证失败,则抛出异常,而不会启动池。但是,如果无法获得连接,则池将启动,但稍后获取连接的尝试会失败。小于0的值将绕过任何初始连接尝试,并且池将在尝试在后台获取连接时立即启动。因此,以后获得连接的尝试可能会失败。默认值:1。
感觉官网说的还是比较晦涩,建议看
HikariPool#checkFailFast
源码。
isolateInternalQueries
此属性决定HikariCP是否在自己的事务中隔离内部池查询,例如连接存活测试。由于这些通常是只读查询,因此很少有必要将它们封装在自己的事务中。此属性仅在autoCommit禁用时适用。默认值:false。
allowPoolSuspension
此属性控制池是否可以通过JMX挂起和恢复。这对某些故障转移自动化方案很有用。当池被挂起时,调用getConnection()将不会超时,并将一直保持到池恢复为止。默认值:false。
readOnly
此属性控制默认情况下从池中获取的Connections是否处于只读模式。请注意,某些数据库不支持只读模式的概念,而其他数据库在Connection设置为只读时提供查询优化。是否需要此属性将在很大程度上取决于那的应用程序和数据库。默认值:false。
registerMbeans
此属性控制是否注册JMX管理Bean(“MBean”)。默认值:false。
catalog
此属性为支持catalog的数据库设置默认catalog。如果未指定此属性,则使用JDBC驱动程序定义的默认catalog。默认值:driver default。
connectionInitSql
此属性设置一个SQL语句,该语句将在每次创建新连接之后执行,然后再将该连接添加到池中。如果此SQL无效或抛出异常,它将被视为连接失败,并将遵循标准重试逻辑。默认值:无。
driverClassName
HikariCP将尝试仅基于jdbcUrl通过DriverManager解析驱动程序,但对于某些较旧的驱动程序必须指定driverClassName。除非用户收到明显的错误消息,表明未找到驱动程序,否则可忽略此属性。默认值:无。
transactionIsolation
此属性控制从池返回的连接的默认事务隔离级别。若未指定,则用JDBC驱动程序定义的默认事务隔离级别。仅当有针对所有查询的特定隔离需求时,才使用此属性。此属性的值是Connection类的常量名,如TRANSACTION_READ_COMMITTED、TRANSACTION_REPEATABLE_READ等。默认值:driver default。
validationTimeout
此属性控制连接测试活性的最长时间。该值必须小于connectionTimeout。最低可接受的验证超时为250毫秒。默认值:5000。
leakDetectionThreshold
此属性控制连接在记录一条指示可能连接泄漏的消息之前流出池的时间。值为0表示禁用泄漏检测。启用泄漏检测的最低可接受值是2000(2秒)。默认值:0。
schema
该属性为支持schema概念数据库设置默认schema。如果未指定此属性,则使用JDBC驱动程序定义的默认模式。默认值:driver default。
threadFactory
此属性仅可通过编程配置或IoC容器获得。此属性允许设置java.util.concurrent.ThreadFactory将用于创建池使用的所有线程的实例。在注入线程只能通过应用程序容器提供的ThreadFactory创建的某些受限执行环境中使用它。默认值:无。
scheduledExecutor
仅可通过编程配置或IoC容器获得。允许设置java.util.concurrent.Scheduled-ExecutorService用于各种内部调度任务的实例。如果向HikariCP提供ScheduledThread-PoolExecutor实例,建议设置setRemoveOnCancelPolicy(true)。默认值:无。