连接池配置指南 | Connection Pool Guide

中文

基本配置

DruidDataSource 是 Druid 的核心连接池实现。以下是完整的配置参数说明：

必选参数

参数	说明	示例
`url`	JDBC 连接 URL	`jdbc:mysql://localhost:3306/mydb`
`username`	数据库用户名	`root`
`password`	数据库密码	`password`

连接池容量

参数	默认值	说明
`initialSize`	0	初始化时创建的物理连接数
`maxActive`	8	最大连接池数量
`minIdle`	0	最小空闲连接数
`maxWait`	-1	获取连接最大等待时间（毫秒），-1 表示无限等待

连接检测

参数	默认值	说明
`validationQuery`	-	连接有效性检测 SQL（如 `SELECT 1`）
`validationQueryTimeout`	-1	检测超时时间（秒）
`testOnBorrow`	false	获取连接时检测有效性
`testOnReturn`	false	归还连接时检测有效性
`testWhileIdle`	true	空闲时检测有效性（推荐开启）

连接回收

参数	默认值	说明
`timeBetweenEvictionRunsMillis`	60000	回收线程执行间隔（毫秒）
`minEvictableIdleTimeMillis`	1800000	连接最小空闲时间，超过则可被回收（30分钟）
`maxEvictableIdleTimeMillis`	25200000	连接最大空闲时间，超过则强制回收（7小时）
`keepAlive`	false	是否对空闲连接发送心跳保活
`keepAliveBetweenTimeMillis`	120000	KeepAlive 间隔时间（毫秒）

PreparedStatement 缓存

参数	默认值	说明
`poolPreparedStatements`	false	是否启用 PSCache
`maxPoolPreparedStatementPerConnectionSize`	10	每个连接的 PSCache 大小

提示： 调用 setMaxPoolPreparedStatementPerConnectionSize(n)（n > 0）会自动开启 poolPreparedStatements = true，无需手动设置。

配置示例

Java 代码配置

java

DruidDataSource dataSource = new DruidDataSource();

// 基本配置
dataSource.setUrl("jdbc:mysql://localhost:3306/mydb?useUnicode=true&characterEncoding=utf8");
dataSource.setUsername("root");
dataSource.setPassword("password");

// 连接池容量
dataSource.setInitialSize(5);
dataSource.setMaxActive(20);
dataSource.setMinIdle(5);
dataSource.setMaxWait(60000);

// 连接检测
dataSource.setValidationQuery("SELECT 1");
dataSource.setTestWhileIdle(true);
dataSource.setTestOnBorrow(false);
dataSource.setTestOnReturn(false);

// 连接回收
dataSource.setTimeBetweenEvictionRunsMillis(60000);
dataSource.setMinEvictableIdleTimeMillis(1800000);

// KeepAlive
dataSource.setKeepAlive(true);
dataSource.setKeepAliveBetweenTimeMillis(120000);

// PSCache（MySQL 建议关闭，Oracle/DB2/PostgreSQL 建议开启）
dataSource.setPoolPreparedStatements(false);

// Filter
dataSource.setFilters("stat,wall");

// 初始化
dataSource.init();

Spring Boot 配置（application.yml）

yaml

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb?useUnicode=true&characterEncoding=utf8
    username: root
    password: password
    druid:
      initial-size: 5
      max-active: 20
      min-idle: 5
      max-wait: 60000
      validation-query: SELECT 1
      test-while-idle: true
      test-on-borrow: false
      test-on-return: false
      time-between-eviction-runs-millis: 60000
      min-evictable-idle-time-millis: 1800000
      keep-alive: true
      filters: stat,wall

最佳实践

1. 连接池大小

根据应用并发量合理设置：

场景	initialSize	minIdle	maxActive
小型应用（< 50 QPS）	2	2	10
中型应用（50-500 QPS）	5	5	20
大型应用（> 500 QPS）	10	10	50

经验公式： maxActive ≈ 数据库可承载最大连接数 / 应用节点数，同时确保 maxActive >= 单节点最大并发线程数

2. 连接检测策略

推荐启用 testWhileIdle — 在空闲检测时验证连接，性能开销最小
生产环境慎用 testOnBorrow — 每次获取连接都会执行检测 SQL，高并发下有性能影响
必须设置 validationQuery — 否则连接检测无法生效

3. 超时配置

yaml

# 获取连接等待超时（避免无限等待）
max-wait: 60000

# 防止连接泄漏（开发环境推荐）
remove-abandoned: true
remove-abandoned-timeout: 300
log-abandoned: true

4. MySQL 特定配置

yaml

spring:
  datasource:
    url: jdbc:mysql://host:3306/db?useUnicode=true&characterEncoding=utf8&autoReconnect=true&failOverReadOnly=false
    druid:
      validation-query: SELECT 1
      pool-prepared-statements: false  # MySQL 不建议开启 PSCache

5. Oracle 特定配置

yaml

spring:
  datasource:
    url: jdbc:oracle:thin:@host:1521:sid
    druid:
      validation-query: SELECT 1 FROM DUAL
      pool-prepared-statements: true   # Oracle 建议开启 PSCache
      max-pool-prepared-statement-per-connection-size: 20

连接泄漏检测

当应用存在连接泄漏（获取连接后未正确关闭）时，可启用 RemoveAbandoned 功能：

java

dataSource.setRemoveAbandoned(true);
dataSource.setRemoveAbandonedTimeout(300); // 300 秒
dataSource.setLogAbandoned(true);          // 记录泄漏连接的堆栈

注意： removeAbandoned 仅建议在开发和测试环境使用。生产环境应通过代码审查和测试确保连接正确关闭。

English

Basic Configuration

DruidDataSource is Druid's core connection pool implementation.

Required Parameters

Parameter	Description	Example
`url`	JDBC connection URL	`jdbc:mysql://localhost:3306/mydb`
`username`	Database username	`root`
`password`	Database password	`password`

Pool Capacity

Parameter	Default	Description
`initialSize`	0	Number of physical connections created at initialization
`maxActive`	8	Maximum number of connections in the pool
`minIdle`	0	Minimum number of idle connections
`maxWait`	-1	Maximum wait time (ms) to get a connection; -1 means infinite

Connection Validation

Parameter	Default	Description
`validationQuery`	-	SQL used to validate connections (e.g., `SELECT 1`)
`testOnBorrow`	false	Validate on connection acquisition
`testOnReturn`	false	Validate on connection return
`testWhileIdle`	true	Validate idle connections (recommended)

Connection Eviction

Parameter	Default	Description
`timeBetweenEvictionRunsMillis`	60000	Eviction thread interval (ms)
`minEvictableIdleTimeMillis`	1800000	Minimum idle time before eviction (30 min)
`maxEvictableIdleTimeMillis`	25200000	Maximum idle time, force eviction (7 hours)
`keepAlive`	false	Send heartbeats to idle connections

Best Practices

Enable testWhileIdle — lowest overhead validation strategy
Always set validationQuery — required for validation to work
Set maxWait — avoid infinite waits in high-concurrency scenarios
Disable poolPreparedStatements for MySQL — enable for Oracle/DB2/PostgreSQL. Note: calling setMaxPoolPreparedStatementPerConnectionSize(n) with n > 0 auto-enables PSCache
Use removeAbandoned in dev/test — helps detect connection leaks