From 3a0f74d114fa508d0486e1fbe7e7ad57141e4bba Mon Sep 17 00:00:00 2001 From: Brett Wooldridge Date: Fri, 31 Oct 2014 18:13:40 +0900 Subject: [PATCH] Re-arranging properties --- README.md | 133 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 68 insertions(+), 65 deletions(-) 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 :paperclip: *HikariCP uses milliseconds for all time values.* -:white_check_mark:``autoCommit``
-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``
-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``
+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``
-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``
+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``
-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``
+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``
+This property controls the default auto-commit behavior of connections returned from the pool. +It is a boolean value. *Default: true* :watch:``connectionTimeout``
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``
-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``
-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``
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``
-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``
-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``
-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``
-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``
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``
-This property controls whether or not JMX Management Beans ("MBeans") are registered or not. -*Default: false* - ##### Infrequently used +:watch:``leakDetectionThreshold``
+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``
+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``
+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``
+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``
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``
+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``
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``
+This property controls whether or not JMX Management Beans ("MBeans") are registered or not. +*Default: false* + +:negative_squared_cross_mark:``initializationFailFast``
+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``
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***
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