diff --git a/README.md b/README.md index 6c9d0cef..fa434125 100644 --- a/README.md +++ b/README.md @@ -69,29 +69,38 @@ HikariCP comes with *sane* defaults that perform well in most deployments withou <sup>:paperclip:</sup> *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