【Java】DBCP2配置详细说明（中文翻译）

迈不过友情╰ 2022-08-18 13:26 312阅读 0赞

[common-dbcp2数据库连接池参数说明][common-dbcp2]

由于commons-dbcp所用的连接池出现版本升级，因此commons-dbcp2中的数据库池连接配置也发生了变化，具体的参数配置说明如下：

--------------------

**参数                             描述**

<table> 
 <tbody> 
  <tr> 
   <td style="border-color:#999999;">username<br> （用户名）</td> 
   <td style="border-color:#999999;">通过JDBC建立一个连接所需的用户名</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;">password<br> （密码）</td> 
   <td style="border-color:#999999;">通过JDBC建立一个连接所需的密码</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;">url<br> （JDBC连接串）</td> 
   <td style="border-color:#999999;">通过JDBC建立一个连接所需的URL</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;">driverClassName<br> （JDBC驱动程序）</td> 
   <td style="border-color:#999999;">所使用的JDBC驱动的类全名</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;">connectionProperties<br> （连接属性）</td> 
   <td style="border-color:#999999;">连接参数是在建立一个新连接时发送给JDBC驱动的<br> 字符串的格式必须是[参数名=参数值;]<br> 提示：用户名和密码属性是需要明确指出的，所以这两个参数不需要包含在这里</td> 
  </tr> 
 </tbody> 
</table>

--------------------

**参数                                       缺省值           描述**

<table> 
 <tbody> 
  <tr> 
   <td style="border-color:#999999;width:151px;">defaultAutoCommit<br> （自动提交）</td> 
   <td style="border-color:#999999;width:105px;">JDBC驱动的缺省值</td> 
   <td style="border-color:#999999;">通过这个池创建连接的默认自动提交状态。如果不设置，则setAutoCommit&nbsp;方法将不被调用。</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:151px;">defaultReadOnly<br> （只读设置）</td> 
   <td style="border-color:#999999;width:105px;">JDBC驱动的缺省值</td> 
   <td style="border-color:#999999;">通过这个池创建连接的默认只读状态。如果不设置，则setReadOnly&nbsp;&nbsp;方法将不被调用。（部分驱动不支持只读模式，如：Informix）</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:151px;">defaultTransactionIsolation<br> （事务隔离级别）</td> 
   <td style="border-color:#999999;width:105px;">JDBC驱动的缺省值</td> 
   <td style="border-color:#999999;">通过这个池创建连接的默认事务隔离策略，设置值为下列中的某一个：&nbsp;(参考&nbsp;<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Connection.html#field_summary" rel="nofollow">javadoc</a>)<strong><span style="color:#ff0000;">(看笔记中另外一篇事务属性小结)</span></strong> 
    <ul style="margin-left:0px;"> 
     <li>NONE</li> 
     <li>READ_COMMITTED</li> 
     <li>READ_UNCOMMITTED</li> 
     <li>REPEATABLE_READ</li> 
     <li>SERIALIZABLE</li> 
    </ul></td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:151px;">defaultCatalog<br> （目录，类似于与模式名，但比模式名更加抽象，Oracle、MySQL不支持，其他，MS SQL Server = 数据库名）</td> 
   <td style="border-color:#999999;width:105px;">&nbsp;</td> 
   <td style="border-color:#999999;">通过这个池创建连接的默认缺省的catalog&nbsp;</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:151px;">cacheState<br> （缓存状态）</td> 
   <td style="border-color:#999999;width:105px;">true</td> 
   <td style="border-color:#999999;">如果设置为true，池化的连接将在第一次读或写，以及随后的写的时候缓存当前的只读状态和自动提交设置。这样就省去了对getter的任何进一步的调用时对数据库的额外查询。如果直接访问底层连接，只读状态和/或自动提交设置改变缓存值将不会被反映到当前的状态，在这种情况下，应该将该属性设置为false以禁用缓存。</td> 
  </tr> 
 </tbody> 
</table>

<table style="width:699px;"> 
 <tbody> 
  <tr> 
   <td style="border-color:#bbbbbb;width:232px;"><span style="color:#333333;">defaultQueryTimeout<br> （查询超时时间）</span></td> 
   <td style="border-color:#bbbbbb;width:232px;"><span style="color:#333333;">null</span></td> 
   <td style="border-color:#bbbbbb;width:232px;"><span style="color:#333333;">如果值不为null，指定一个整数值，用于</span><span style="color:#333333;">在创建Statement时，指定为</span><span style="color:#333333;">查询超时时间。如果设置为null，</span><span style="color:#333333;">则使用驱动程序默认设置。</span></td> 
  </tr> 
  <tr> 
   <td style="border-color:#bbbbbb;width:232px;"><span style="color:#333333;">enableAutocommitOnReturn<br> （连接归还到池时，设置为自动提交）</span></td> 
   <td style="border-color:#bbbbbb;width:232px;"><span style="color:#333333;">true</span></td> 
   <td style="border-color:#bbbbbb;width:232px;"><span style="color:#333333;">如果设置为true，则连接被归还到连接池时，会指定设置为autoCommit = true</span></td> 
  </tr> 
  <tr> 
   <td style="border-color:#bbbbbb;width:232px;"><span style="color:#333333;">rollbackOnReturn<br> （</span><span style="color:#333333;">连接归还到池时，回滚所有操作</span><span style="color:#333333;">）</span></td> 
   <td style="border-color:#bbbbbb;width:232px;"><span style="color:#333333;">true</span></td> 
   <td style="border-color:#bbbbbb;width:232px;"><span style="color:#333333;">如果设置为true，则连接被归还到连接池时，会自动执行一次rollback()；前提是自动提交 = true and 非只读。</span></td> 
  </tr> 
 </tbody> 
</table>

--------------------

**参数                         缺省值                 描述**

<table> 
 <tbody> 
  <tr> 
   <td style="border-color:#999999;width:116px;">initialSize<br> （初始连接数）</td> 
   <td style="border-color:#999999;width:104px;">0</td> 
   <td style="border-color:#999999;">当这个池被启动时初始化的创建的连接个数，起始生效版本：1.2</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:116px;">maxTotal<br> （最大活动连接数）</td> 
   <td style="border-color:#999999;width:104px;">8</td> 
   <td style="border-color:#999999;">可以在这个池中同一时刻被分配的有效连接数的最大值，如设置为负数，则不限制</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:116px;">maxIdle<br> （最大空闲连接数）</td> 
   <td style="border-color:#999999;width:104px;">8</td> 
   <td style="border-color:#999999;">在池中，可以保持空闲状态的最大连接数，超出设置值之外的空闲连接<span style="color:#ff0000;">在归还到连接池时</span>将被释放，如设置为负数，则不限制</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:116px;">minIdle<br> （最小空闲连接数）</td> 
   <td style="border-color:#999999;width:104px;">0</td> 
   <td style="border-color:#999999;">可以在池中保持空闲的最小连接数，低于设置值时，空闲连接将被创建，以努力保持最小空闲连接数&gt;=minIdle，如设置为0，则不创建<br> 这里设置的数值生效的前提是：<span style="color:#ff0000;">timeBetweenEvictionRunsMillis</span><span style="color:#ff0000;">（空闲对象驱逐线程运行时的休眠毫秒数</span><span style="color:#ff0000;">）被设置为正数。</span></td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:116px;">maxWaitMillis<br> （从连接池获取一个连接时，最大的等待时间）</td> 
   <td style="border-color:#999999;width:104px;">indefinitely<br> （不确定）</td> 
   <td style="border-color:#999999;">设置为-1时，如果没有可用连接，连接池会一直无限期等待，直到获取到连接为止。<br> 如果设置为N（毫秒），则连接池会等待N毫秒，等待不到，则抛出异常。</td> 
  </tr> 
 </tbody> 
</table>

提示: 如果在高负载的系统中将maxIdle的值设置的很低，则你可能会发现在一个新的连接刚刚被创建的时候就立即被关闭了。这是活跃的线程及时关闭连接要比那些打开连接的线程要快，导致空闲的连接数大于maxIdle。高负载系统中maxIdle的最合适的配置值是多样的，但是缺省值是一个好的开始点。

--------------------

**参数                                               缺省值          描述**

<table> 
 <tbody> 
  <tr> 
   <td style="border-color:#999999;width:186px;">validationQuery<br> （确认查询SQL）<br><br><br><br><br><br> validationQueryTimeout<br> （确认查询SQL的超时时间）</td> 
   <td style="border-color:#999999;width:94px;">&nbsp;<br><br><br><br><br><br> no timeout</td> 
   <td style="border-color:#999999;">在连接池返回连接给调用者前用来进行连接校验的查询sql。如果指定，则这个查询必须是一个至少返回一行数据的SQL SELECT语句。如果没有指定，则连接将通过调用isValid()&nbsp;方法进行校验。<br><br><br><br> 确认连接有效SQL的执行查询超时时间（秒）。如果设置为正数，那么会传递给JDBC驱动的setQueryTimeOut()方法，这个设置对执行【确认有效查询SQL】起作用。</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">testOnCreate<br> （连接创建后，马上验证有效性）</td> 
   <td style="border-color:#999999;width:94px;">false</td> 
   <td style="border-color:#999999;">指明对象在创建后是否需要验证是否有效，如果对象验证失败，则触发对象创建的租借尝试将失败。</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">testOnBorrow<br> （从连接池获取一个连接时，验证有效性）</td> 
   <td style="border-color:#999999;width:94px;">true</td> 
   <td style="border-color:#999999;">指明在从池中租借对象时是否要进行验证有效，如果对象验证失败，则对象将从池子释放，然后我们将尝试租借另一个</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">testOnReturn<br> （连接被归还到连接池时，验证有效性）</td> 
   <td style="border-color:#999999;width:94px;">false</td> 
   <td style="border-color:#999999;">指明在将对象归还给连接池前是否需要校验。</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">testWhileIdle<br> （连接空闲时，验证有效性）</td> 
   <td style="border-color:#999999;width:94px;">false</td> 
   <td style="border-color:#999999;">指明对象是否需要通过对象驱逐者进行校验（如果有的话），假如一个对象验证失败，则对象将被从池中释放。</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;"><span style="color:#ff0000;">timeBetweenEvictionRunsMillis<br> （空闲对象驱逐线程运行时的休眠毫秒数）</span></td> 
   <td style="border-color:#999999;width:94px;"><span style="color:#ff0000;">-1</span></td> 
   <td style="border-color:#999999;"><span style="color:#ff0000;">空闲对象驱逐线程运行时的休眠毫秒数，如果设置为非正数，则不运行空闲对象驱逐线程。</span></td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">numTestsPerEvictionRun<br> （在每个空闲对象驱逐线程运行过程中中进行检查的对象个数）</td> 
   <td style="border-color:#999999;width:94px;">3</td> 
   <td style="border-color:#999999;">在每个空闲对象驱逐线程运行过程中中进行检查的对象个数。（如果有的话）</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">minEvictableIdleTimeMillis<br> （空闲的连接最低要待N毫秒后，才会被释放）</td> 
   <td style="border-color:#999999;width:94px;">1000 * 60 * 30<br> （30分）</td> 
   <td style="border-color:#999999;">符合对象驱逐条件的对象在池中最小空闲毫秒总数（如果有的话）</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">softMiniEvictableIdleTimeMillis<br> （空闲的连接最低要待N毫秒后，才会被释放，但有额外条件）</td> 
   <td style="border-color:#999999;width:94px;">-1</td> 
   <td style="border-color:#999999;">符合对象驱逐条件的对象在池中最小空闲毫秒总数，额外的条件是池中至少保留有minIdle所指定的个数的连接。当miniEvictableIdleTimeMillis&nbsp;被设置为一个正数，空闲连接驱逐者首先检测miniEvictableIdleTimeMillis，当空闲连接被驱逐者访问时，首先与miniEvictableIdleTimeMillis&nbsp;所指定的值进行比较（而不考虑当前池中的空闲连接数），然后比较softMinEvictableIdleTimeMillis所指定的连接数，包括minIdle条件。</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">maxConnLifetimeMillis<br> （一个连接的最大存活毫秒数）</td> 
   <td style="border-color:#999999;width:94px;">-1</td> 
   <td style="border-color:#999999;">一个连接的最大存活毫秒数。如果超过这个时间，则连接在下次激活、钝化、校验时都将会失败。如果设置为0或小于0的值，则连接的存活时间是无限的。</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">connectionInitSqls<br> （连接被第一次创建时，执行的初始化SQL）</td> 
   <td style="border-color:#999999;width:94px;">null</td> 
   <td style="border-color:#999999;">在第一次创建时用来初始化物理连接的SQL语句集合。这些语句只在配置的连接工厂创建连接时被执行一次。</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:186px;">lifo<br> （后进先出）</td> 
   <td style="border-color:#999999;width:94px;">true</td> 
   <td style="border-color:#999999;">设置为true表明连接池（如果池中有可用的空闲连接时）将返回最后一次使用的租借对象（最后进入）。<br> 设置为false则表明池将表现为FIFO队列（先进先出）—将会按照它们被归还的顺序从空闲连接实例池中获取连接</td> 
  </tr> 
 </tbody> 
</table>

<table style="width:699px;"> 
 <tbody> 
  <tr> 
   <td style="border-color:#bbbbbb;">logExpiredConnections<br> （一个过期的连接被连接池关闭时，写日志标识）</td> 
   <td style="border-color:#bbbbbb;">true</td> 
   <td style="border-color:#bbbbbb;">如果连接存货时间超过maxConnLifetimeMillis，连接将被连接池会抽，此时默认输出日志。如果设置为false，这不会写日志。</td> 
  </tr> 
 </tbody> 
</table>

--------------------

**参数                                             缺省值                 描述**

<table> 
 <tbody> 
  <tr> 
   <td style="border-color:#999999;width:187px;">poolPreparedStatements<br> （设置该连接池的预处理语句池是否生效）</td> 
   <td style="border-color:#999999;width:94px;">false</td> 
   <td style="border-color:#999999;">设置该连接池的预处理语句池是否生效</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:187px;">maxOpenPreparedStatements<br> （可以在语句池中同时分配的最大语句数）</td> 
   <td style="border-color:#999999;width:94px;">unlimited</td> 
   <td style="border-color:#999999;">可以在语句池中同时分配的最大语句数。设置为负数则不限制。</td> 
  </tr> 
 </tbody> 
</table>

这个设置同时作用于预处理语句池. 当一个可用的语句池被创建给每一个连接时，通过以下方法创建的预处理语句将被池化。

*  public PreparedStatement prepareStatement(String sql)
 *  public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency)

提示 -要确保你的连接会留下一些资源给其他语句。池化预处理语句可能会在数据库中保持他们的游标，可能会引起连接的游标越界，尤其是maxOpenPreparedStatements的值被设置为默认值（无限的），而且一个应用程序可能会为每个连接打开大量不同的预处理语句。为了避免这个问题maxOpenPreparedStatements应该被设置为一个小于连接可以打开的最大游标数的值。

--------------------

**参数                                                         缺省值     描述**

<table> 
 <tbody> 
  <tr> 
   <td style="border-color:#999999;width:235px;">accessToUnderlyingConnectionAllowed<br> （控制PoolGuard是否可以访问底层连接&nbsp;）</td> 
   <td style="border-color:#999999;width:63px;">false</td> 
   <td style="border-color:#999999;">控制PoolGuard是否可以访问底层连接&nbsp;</td> 
  </tr> 
 </tbody> 
</table>

如果允许访问的话，使用如下代码结构：

Connection conn = ds.getConnection();
        Connection dconn =((DelegatingConnection) conn).getInnermostDelegate();
        ...
        conn.close()

默认值为false，这是一个有着潜在风险的操作，使用不当可能会导致非常严重的后果。（在守护连接已被关闭的情况下，关闭底层连接或者继续使用它），只有在你需要直接访问驱动的特有扩展是可以谨慎使用。

NOTE: 除了最原始那个之外，不要关闭底层连接

--------------------

**参数                                       缺省值         描述**

<table> 
 <tbody> 
  <tr> 
   <td style="border-color:#999999;width:168px;">removeAbandonedOnMaintenance<br> removeAbandonedOnBorrow<br> （）</td> 
   <td style="border-color:#999999;width:71px;">false</td> 
   <td style="border-color:#999999;">标记是否删除超过removeAbandonedTimout所指定时间的被遗弃的连接。<br> 如果设置为true，则一个连接在超过removeAbandonedTimeout所设定的时间未使用即被认为是应该被抛弃并应该被移除的。<br> 创建一个语句，预处理语句，可调用语句或使用它们其中的一个执行查询（使用执行方法中的某一个）会重新设置其父连接的lastUsed&nbsp;属性。<br> 在写操作较少的应用程序中将该参数设置为true可以将数据库连接从连接关闭失败中恢复。</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:168px;">removeAbandonedTimeout<br> （一个被抛弃连接可以被移除的超时时间）</td> 
   <td style="border-color:#999999;width:71px;">300（秒）</td> 
   <td style="border-color:#999999;">一个被抛弃连接可以被移除的超时时间，单位为秒</td> 
  </tr> 
  <tr> 
   <td style="border-color:#999999;width:168px;">logAbandoned</td> 
   <td style="border-color:#999999;width:71px;">false</td> 
   <td style="border-color:#999999;">标志是否为应用程序中遗弃语句或连接的代码开启日志堆栈追踪。<br> 因为一个堆栈跟踪已被创建，被抛弃的语句和连接相关的日志将被覆盖到打开每个连接或者创建一个Statement时</td> 
  </tr> 
 </tbody> 
</table>

如果你启用了removeAbandoned，则一个连接被池回收再利用是可能的，因为它被认为是已遗弃 在(getNumIdle() < 2) and (getNumActive() > getMaxTotal() - 3)成立时，这个机制将被触发。

例如, maxTotal=20 ，这里有18个活跃连接，一个限制连接，将触发 "removeAbandoned"。但是只有在活动连接超过 "removeAbandonedTimeout" 所指定的秒数内未使用才会被删除（默认为300秒）。遍历一个结果集并不被统计为被使用，创建一个语句，预处理语句，可调用语句或使用它们其中的一个执行查询（使用执行方法中的某一个）会重新设置其父连接的lastUsed 属性。

<table> 
 <tbody> 
  <tr> 
   <th style="vertical-align:top;">Parameter</th> 
   <th style="vertical-align:top;">Default</th> 
   <th style="vertical-align:top;">Description</th> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;">fastFailValidation<br> （验证快速失败）</td> 
   <td style="vertical-align:top;">false</td> 
   <td style="vertical-align:top;">如果发生致命的异常，验证语句会快速失败。而不会再执行isValid()，也不再去执行验证查询语句。致命的异常码（SQL_STATE）指以下： 
    <ul style="margin-left:25px;"> 
     <li>57P01 (ADMIN SHUTDOWN)</li> 
     <li>57P02 (CRASH SHUTDOWN)</li> 
     <li>57P03 (CANNOT CONNECT NOW)</li> 
     <li>01002 (SQL92 disconnect error)</li> 
     <li>JZ0C0 (Sybase disconnect error)</li> 
     <li>JZ0C1 (Sybase disconnect error)</li> 
     <li>Any SQL_STATE code that starts with "08"</li> 
    </ul> 想覆盖异常码，请参看&nbsp;disconnectionSqlCodes&nbsp;</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;">disconnectionSqlCodes<br> （异常码）</td> 
   <td style="vertical-align:top;">null</td> 
   <td style="vertical-align:top;">以逗号分割的SQL_STATE码，fastFailValidation&nbsp;为true时，才会生效。 <p>&nbsp;</p> </td> 
  </tr> 
 </tbody> 
</table>

[common-dbcp2]: http://bsr1983.iteye.com/blog/2092467