Clarification of comment regarding use of validate-on-match

The 7.3 documentation states regarding validate-on-match:

This setting ... creates the highest load on the database.

This is not necessarily true for multiple reasons:

• If you set the background-validation-millis low enough to reliably reduce the chances of stale connections, this may generate a much higher load on the database than using validate-on-match as individual connections may be validated far more frequently than if using validation only at match/selection.
• The load created by background-validation may be relatively high (compared to validate-on-match) for large pools if many connections are idle/unreserved at a given time.
• The load on the database for validate-on-match is only marginally increased beyond normal application use as most connection use cases involve multiple interactions (SQL command executions) with a connection while it is reserved by the application. Validation adds only a single interaction to a potentially large or more expensive set of other interactions (depending on how and how many times the connection is used before it is returned to the pool) so the actual/measurable impact of validate-on-match may be insignificant.

There are two primary scenarios where validate-on-match may have noticeable impact:

1. If the application is structured to utilize connections in many "single-interaction" workflows the impact might be significant. These would be cases where a connection is taken from the pool outside a transaction, used to create and execute a single SQL command and then immediately returned to the pool. In these cases, the validate-on-match activity doubles the number of interactions. But, the validation "interaction" likely would not nearly double the cost/load as validation is typically much less expensive than running a normal query that may return a result set of any significant size. So, even this may be insignificant (e.g. if the connection interaction is one in which a query that generates a large result set is executed).
2. If connectivity to the database is slow or unreliable, there may be a noticeable delay when the application takes a connection from the pool while one or more connections (more than one if broken connections are found) are validated. Blocking will occur during the validation for each connection so, if it takes a long time (due to latency in the network or due to frequent connection failure as the driver may block much longer while waiting for a failed connection to return), this might become noticeable to users (e.g. there could be a noticeable delay if the connection request is backing some UI activity). An additional factor here is that use of the JDBC4ValidConnectionChecker mechanism for validation can frequently reduce the cost of the validation because the Connection.isValid(int) approach may be optimized compared to a simple query and it also supports a timeout to mitigate the delay during validation that might be encountered using other approaches to validation when failed connections are found in the pool.

As a rule, background-validation should be used as an alternative only if empirical testing determines that validate-on-match noticeably impacts the system. The default choice should be validate-on-match.