Document :pool_index (#303)

lib/db_connection.ex

@@ -389,9 +389,9 @@ defmodule DBConnection do
     random exponential (default: `:rand_exp`)
     * `:configure` - A function to run before every connect attempt to
     dynamically configure the options, either a 1-arity fun,
-    `{module, function, args}` with options prepended to `args` or `nil` where
-    only returned options are passed to connect callback (default: `nil`). This
-    function is called *in the connection process*.
+    `{module, function, args}` or `nil`. This function is called
+    *in the connection process*. For more details, see
+    [Connection Configuration Callback](#start_link/2-connection-configuration-callback)
     * `:after_connect` - A function to run on connect using `run/3`, either
     a 1-arity fun, `{module, function, args}` with `t:DBConnection.t/0` prepended
     to `args` or `nil` (default: `nil`)
@@ -524,6 +524,27 @@ defmodule DBConnection do
   This feature is available since v2.6.0. Before this version `:connection_listeners` only
   accepted a list of listener processes.
 
+  ## Connection Configuration Callback
+
+  The `:configure` function will be called before each individual connection to the
+  database is made. It receives all of the options provided to `start_link/2` as well
+  as an additional generated value named `:pool_index`. The returned value will be
+  passed as the options into the appropriate `:connect` callback. This provides a way
+  for the user to dynamically configure the connection options.
+
+  `:pool_index` is an integer in `1..pool_size` that represents the current connection's
+  place in the enumeration of all of the pool's connections. It can be used, for example,
+  to configure a unique database per connection when asynchronous tests cannot be performed
+  on a single database.
+
+  The allowed callbacks are:
+
+    * A 1-arity function that recieves the options from `start_link/2` as well as
+      `:pool_index`
+    * `{module, function, args}` where the options from `start_link/2` as well as
+      `:pool_index` are prepended to `args` before the function is called
+    * `nil` if you do not want to modify the existing options
+
   ## Telemetry
 
   A `[:db_connection, :connection_error]` event is published whenever a