Update README.md

README.md

@@ -12,7 +12,7 @@ DBCP and C3P0 are old and slow and I don't know why anyone would use them.
 ##### MixedBench #####
 This is the so called "Mixed" benchmark, and it executes a representative array of JDBC
 operations in a realistic mix.  We think *median* is the number to pay attention to, rather
-than average (which can get skewed).  *Median* meaning 50% of the iterations were slower, %50 were faster.  200 threads we started, and the underlying connection pool contained 100
+than average (which can get skewed).  *Median* meaning 50% of the iterations were slower, %50 were faster.  200 threads were started, and the underlying connection pool contained 100
 connections.
 
 | Pool     |  Med (ms) |  Avg (ms) |  Max (ms) |
@@ -68,7 +68,9 @@ One example of *subjective* incorrectness -- being my personal opinion -- is tha
 BoneCP does not test a ``Connection`` immediately before dispatching it from the pool.  It is
 through this mechanism that it achives some of it's speed.  In my opinion, this one "flaw"
 (or "feature") renders BoneCP insuitable for Production use.  The number one responsibility of
-a connection pool is to **not** give out possibly bad connections.
+a connection pool is to **not** give out possibly bad connections.  If you have ever run a
+load-balancer in front of read-slaves, or have ever needed to bounce the DB while the
+application was running, you certainly didn't do it with BoneCP.
 
 Over on the BoneCP site, you can find a comparison of BoneCP vs. DBCP and C3P0.  DBCP and C3P0,
 as poor as they are, at least are performing aliveness tests before dispatching connections.
@@ -87,3 +89,44 @@ Microseconds):
 | HikariCP | 76        | 65        | 112       |
 
 The times are per-thread reflecting 100 getConnection()/close() operations with no wait between.
+
+#### Knobs ####
+Where are all the knobs?  You know, the ones used to tune and tweak the connection pool?  
+HikariCP has plenty of "knobs" as you can see in the configuration section below, but
+comparatively less than some other pools.  This was a design decision, not lack of development resources or foresight.
+
+##### ***Missing Knobs*** #####
+Some knobs and features were intentionally left out.  Here are the reasons.
+
+**Statement Cache**<br/>
+Many (most?) major database JDBC drivers already have a PreparedStatement cache that can be
+configured (Oracle, MySQL, PostgreSQL, Derby, etc).  A cache in the pool would add unneeded
+weight, no additional functionality, and possibly incorrect behavior...
+
+JDBC drivers have a special relationship with the remote database in that they are directly
+connected and can share internal state that is synchronized with the backend.  **It is
+inherently unsafe to cache PreparedStatements outside of the driver.**  Why?  Again, drivers
+have a special relationship with the database.
+
+Take for example DDL, this is from a real world application I encountered (using BoneCP btw).
+Data was inserted into a table lets call X1.  Every night, programatically X1 was renamed to X2, and a new X1 was created with identical structure.  Basically, the application was
+"rolling" tables over daily (while running).  In spite of the structure of X1 being identical
+after rolling, the database considered a PreparedStatement compiled against the old table to be
+invalid (probably there were some kind of UUID contained within).  When the statement pool
+returned one of these statements, the application blew up.  Turning off the cache in the
+connection pool, and enabling it in the driver fixed the issue.  How?  It is only speculation,
+but it seems likely that driver in this case checks with the DB to ensure the statement is
+still valid and if not recompiles it transparently.
+
+Regardless of correctness or not (I'm sure it varies by DB vendor), it is unnecessary with
+modern databases.
+
+**Log Statement Text**<br/>
+Like Statement caching, most major database vendors support statement logging through
+properties of their own driver.  This includes Oracle, MySQL, Derby, MSSQL.  For those few
+databases that do not support it, [log4jdbc](https://code.google.com/p/log4jdbc/) is a good option.  Actually *log4jdbc* provides some nice additional stuff like various timings, and
+PreparedStatement bound parameter logging.
+
+HikariCP is focused (primarily) on performance in a Production environment, so it is doubtful
+that we will ever implement this feature given inherent driver support and alternative
+solutions.