Skip to content

connection-pool-guide.md

Latest commit

 

History

History
240 lines (179 loc) · 7.53 KB

connection-pool-guide.md

File metadata and controls

240 lines (179 loc) · 7.53 KB

连接池配置指南 | Connection Pool Guide

English | 中文

中文

基本配置

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 代码配置

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）

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. 超时配置

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

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

4. MySQL 特定配置

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 特定配置

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 功能：

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

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