github-forks
/
HikariCP
mirror of https://github.com/brettwooldridge/HikariCP.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Re-arranging properties

Browse Source
pull/192/head
Brett Wooldridge 10 years ago
parent fcec343d4f
commit 3a0f74d114
1 changed files with 68 additions and 65 deletions
Show Stats Download Patch File Download Diff File

133
README.md
Unescape Escape View File

@ -69,29 +69,38 @@ HikariCP comes with *sane* defaults that perform well in most deployments withou
<sup>:paperclip:</sup>&nbsp;*HikariCP uses milliseconds for all time values.*
:white_check_mark:``autoCommit``<br/>
This property controls the default auto-commit behavior of connections returned from the pool.
It is a boolean value. *Default: true*
##### Essentials
:negative_squared_cross_mark:``readOnly``<br/>
This property controls whether *Connections* obtained from the pool are in read-only mode by
default. Note some databases do not support the concept of read-only mode, while others provide
query optimizations when the *Connection* is set to read-only. Whether you need this property
or not will depend largely on your application and database. *Default: false*
:abc:``dataSourceClassName``<br/>
This is the name of the ``DataSource`` class provided by the JDBC driver. Consult the
documentation for your specific JDBC driver to get this class name, or see the [table](https://github.com/brettwooldridge/HikariCP#popular-datasource-class-names) below.
Note XA data sources are not supported. XA requires a real transaction manager like
[bitronix](https://github.com/bitronix/btm). Note that you do not need this property if you are using
``driverClassName`` to wrap an old-school DriverManager-based JDBC driver. The HikariCP team
considers ``dataSourceClassName`` to be a superior method of creating connections compared to
``driverClassName``. *Default: none*
:abc:``transactionIsolation``<br/>
This property controls the default transaction isolation level of connections returned from
the pool. If this property is not specified, the default transaction isolation level defined
by the JDBC driver is used. Typically, the JDBC driver default transaction isolation level
should be used. Only use this property if you have specific isolation requirements that are
common for all queries, otherwise simply set the isolation level manually when creating or
preparing statements. The value of this property is the constant name from the ``Connection``
class such as ``TRANSACTION_READ_COMMITTED``, ``TRANSACTION_REPEATABLE_READ``, etc. *Default: driver default*
:abc:``driverClassName``<br/>
This property allows HikariCP to wrap an old-school JDBC driver as a ``javax.sql.DataSource``.
It is unnecessary when using the ``dataSourceClassName`` property, which is the preferred way
of creating connections in HikariCP. DataSources are provided by all but the oldest JDBC drivers.
If ``driverClassName`` is used, then the ``jdbcUrl`` property must also be set. *Default: none*
:abc:``catalog``<br/>
This property sets the default *catalog* for databases that support the concept of catalogs.
If this property is not specified, the default catalog defined by the JDBC driver is used.
*Default: driver default*
:abc:``jdbcUrl``<br/>
This property is only used when the ``driverClassName`` property is used to wrap an old-school
JDBC driver as a ``javax.sql.DataSource``. While JBDC URLs are popular, HikariCP does not
recommend using them. The *DataSource* implementation provided by your driver provides bean
properties for all the driver parameters that used to be specified in the JDBC URL. Before using
the ``jdbcUrl`` and ``driverClassName`` because that's the way you've always done it, consider
using the more modern and maintainable ``dataSourceClassName`` approach instead. Note that if
this property is used, you may still use *DataSource* properties to configure your driver and
is in fact recommended. *Default: none*
##### Frequently used
:white_check_mark:``autoCommit``<br/>
This property controls the default auto-commit behavior of connections returned from the pool.
It is a boolean value. *Default: true*
:watch:``connectionTimeout``<br/>
This property controls the maximum number of milliseconds that a client (that's you) will wait
@ -113,16 +122,6 @@ recommend setting this value, and using something reasonable like 30 minutes or
value of 0 indicates no maximum lifetime (infinite lifetime), subject of course to the
``idleTimeout`` setting. *Default: 1800000 (30 minutes)*
:watch:``leakDetectionThreshold``<br/>
This property controls 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. Lowest acceptable value for enabling leak detection is 10000 (10 secs). *Default: 0*
:negative_squared_cross_mark:``initializationFailFast``<br/>
This property controls whether the pool will "fail fast" if the pool cannot be seeded with
initial connections successfully. This property has no effect if ``minimumIdle`` is 0.
*Default: false*
:white_check_mark:``jdbc4ConnectionTest``<br/>
This property is a boolean value that determines whether the JDBC4 Connection.isValid() method
is used to check that a connection is still alive. This value is mutually exclusive with the
@ -137,36 +136,6 @@ we strongly recommend not setting this property.** See the ``jdbc4ConnectionTes
for a more efficent alive test. One of either this property or ``jdbc4ConnectionTest`` must
be specified. *Default: none*
:abc:``connectionInitSql``<br/>
This property sets a SQL statement that will be executed after every new connection creation
before adding it to the pool. If this SQL is not valid or throws an exception, it will be
treated as a connection failure and the standard retry logic will be followed. *Default: none*
:abc:``dataSourceClassName``<br/>
This is the name of the ``DataSource`` class provided by the JDBC driver. Consult the
documentation for your specific JDBC driver to get this class name, or see the [table](https://github.com/brettwooldridge/HikariCP#popular-datasource-class-names) below.
Note XA data sources are not supported. XA requires a real transaction manager like
[bitronix](https://github.com/bitronix/btm). Note that you do not need this property if you are using
``driverClassName`` to wrap an old-school DriverManager-based JDBC driver. The HikariCP team
considers ``dataSourceClassName`` to be a superior method of creating connections compared to
``driverClassName``. *Default: none*
:abc:``driverClassName``<br/>
This property allows HikariCP to wrap an old-school JDBC driver as a ``javax.sql.DataSource``.
It is unnecessary when using the ``dataSourceClassName`` property, which is the preferred way
of creating connections in HikariCP. DataSources are provided by all but the oldest JDBC drivers.
If ``driverClassName`` is used, then the ``jdbcUrl`` property must also be set. *Default: none*
:abc:``jdbcUrl``<br/>
This property is only used when the ``driverClassName`` property is used to wrap an old-school
JDBC driver as a ``javax.sql.DataSource``. While JBDC URLs are popular, HikariCP does not
recommend using them. The *DataSource* implementation provided by your driver provides bean
properties for all the driver parameters that used to be specified in the JDBC URL. Before using
the ``jdbcUrl`` and ``driverClassName`` because that's the way you've always done it, consider
using the more modern and maintainable ``dataSourceClassName`` approach instead. Note that if
this property is used, you may still use *DataSource* properties to configure your driver and
is in fact recommended. *Default: none*
:hash:``minimumIdle``<br/>
This property controls 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
@ -206,12 +175,33 @@ skip this method entirely and call ``addDataSourceProperty("pass", ...)``, for e
This property represents a user-defined name for the connection pool and appears mainly
in logging and JMX management consoles to identify pools and pool configurations. *Default: auto-generated*
:negative_squared_cross_mark:``registerMbeans``<br/>
This property controls whether or not JMX Management Beans ("MBeans") are registered or not.
*Default: false*
##### Infrequently used
:watch:``leakDetectionThreshold``<br/>
This property controls 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. Lowest acceptable value for enabling leak detection is 10000 (10 secs). *Default: 0*
:abc:``transactionIsolation``<br/>
This property controls the default transaction isolation level of connections returned from
the pool. If this property is not specified, the default transaction isolation level defined
by the JDBC driver is used. Typically, the JDBC driver default transaction isolation level
should be used. Only use this property if you have specific isolation requirements that are
common for all queries, otherwise simply set the isolation level manually when creating or
preparing statements. The value of this property is the constant name from the ``Connection``
class such as ``TRANSACTION_READ_COMMITTED``, ``TRANSACTION_REPEATABLE_READ``, etc. *Default: driver default*
:abc:``catalog``<br/>
This property sets the default *catalog* for databases that support the concept of catalogs.
If this property is not specified, the default catalog defined by the JDBC driver is used.
*Default: driver default*
:negative_squared_cross_mark:``readOnly``<br/>
This property controls whether *Connections* obtained from the pool are in read-only mode by
default. Note some databases do not support the concept of read-only mode, while others provide
query optimizations when the *Connection* is set to read-only. Whether you need this property
or not will depend largely on your application and database. *Default: false*
:arrow_right:``dataSource``<br/>
This property is only available via programmatic configuration. This property allows you
to directly set the instance of the ``DataSource`` to be wrapped by the pool, rather than
@ -220,18 +210,31 @@ frameworks. When this property is specified, the ``dataSourceClassName`` propert
DataSource-specific properties will be ignored.
*Default: none*
:abc:``connectionInitSql``<br/>
This property sets a SQL statement that will be executed after every new connection creation
before adding it to the pool. If this SQL is not valid or throws an exception, it will be
treated as a connection failure and the standard retry logic will be followed. *Default: none*
:abc: ``connectionCustomizerClassName``<br/>
This property allows you to specify an implementation of the ``IConnectionCustomizer`` interface. The
``customize(Connection)`` method will be invoked on each new connection *before* it is added to the
pool.
:negative_squared_cross_mark:``registerMbeans``<br/>
This property controls whether or not JMX Management Beans ("MBeans") are registered or not.
*Default: false*
:negative_squared_cross_mark:``initializationFailFast``<br/>
This property controls whether the pool will "fail fast" if the pool cannot be seeded with
initial connections successfully. This property has no effect if ``minimumIdle`` is 0.
*Default: false*
:negative_squared_cross_mark:``isolateInternalQueries``<br/>
This property determines whether HikariCP isolates internal pool queries, such as the
connection alive test, in their own transaction. Since these are typically read-only
queries, it is rarely necessary to encapsulate them in their own transaction. This
property only applies if ``autoCommit`` is disabled. *Default: false*
***Missing Knobs***<br/>
HikariCP has plenty of "knobs" to turn as you can see above, but comparatively less than some other pools.
This is a design philosophy. The HikariCP design asthetic is Minimalism. In keeping with the

Write Preview
Loading…
Cancel
Save