pg: Add query tracing & prepare/execute time measurements

What I'd really like, in addition to this, is a way to extract a query
from an $st object that can be run in the psql CLI. VNDB has a debugging
feature for that, but it's less trivial to make that work with binary
query parameters.

FU/Pg.pm

@@ -125,9 +125,32 @@ Prepared statements that still have an active C<$st> object are not counted
 towards this number. The cache works as an LRU: when it's full, the statement
 that hasn't been used for the longest time is reclaimed.
 
+=item $conn->query_trace($sub)
+
+Set a subroutine to be called on every query executed on this connection. The
+subroutine is given a statement object, refer to the C<$st> methods below for
+the fields that can be inspected. C<$sub> can be set to C<undef> to disable
+query tracing.
+
+It is important to not hold on to the given C<$st> any longer than strictly
+necessary, because the prepared statement is not closed or reclaimed while the
+object remains alive. If you need information to remain around for longer than
+the duration of the subroutine call, it's best to grab the relevant information
+from the C<$st> methods and save that for later.
+
+Also worth noting that the subroutine is called from the context of the code
+executing the query, but I<before> the query results have been returned.
+
+The subroutine is (currently) only called for queries executed through C<<
+$conn->exec >>, C<< $conn->q >>, C<< $conn->Q >> and their C<$txn> variants;
+internal queries performed by this module (such as for transaction management,
+querying type information, etc) do not trigger the callback. Statements that
+result in an error being thrown during or before execution are also not
+traceable this way. This behavior might change in the future.
+
 =item $conn->disconnect
 
-Close the connection. Any active transactions are rolled back and any further
+Close the connection. Any active transactions are rolled back and further
 attempts to use C<$conn> throw an error.
 
 =back
@@ -154,19 +177,19 @@ placeholders, as is common with L<DBI>, is not supported. An error is thrown
 when attempting to execute a query where the number of C<@params> does not
 match the number of placeholders in C<$sql>.
 
-Note that this method just creates a statement object, the given query is not
+Note that this method just creates a statement object, the query is not
 prepared or executed until the appropriate statement methods (see below) are
 used.
 
 =item $conn->Q(@args)
 
-Same as C<< $conn->q() >> but uses L<FU::SQL> to construct the SQL query and
-bind parameters.
+Same as C<< $conn->q() >> but uses L<FU::SQL> to construct the query and bind
+parameters.
 
 =back
 
 Statement objects returned by C<< $conn->q() >> support the following
-configuration parameters:
+configuration parameters, which can be set before the statement is executed:
 
 =over
 
@@ -190,37 +213,8 @@ Shorthand for setting C<text_params> and C<text_results> at the same time.
 
 =back
 
-Statement objects can be inspected with the following two methods:
-
-=over
-
-=item $st->param_types
-
-Returns an arrayref of integers indicating the type (as I<oid>) of each
-parameter in the given C<$sql> string. Example:
-
-  my $oids = $conn->q('SELECT id FROM books WHERE id = $1 AND title = $2')->param_types;
-  # $oids = [23,25]
-
-  my $oids = $conn->q('SELECT id FROM books')->params;
-  # $oids = []
-
-=item $st->columns
-
-Returns an arrayref of hashrefs describing each column that the statement
-returns.
-
-  my $cols = $conn->q('SELECT id, title FROM books')->columns;
-  # $cols = [
-  #   { name => 'id', oid => 23 },
-  #   { name => 'title', oid => 25 },
-  # ]
-
-
-=back
-
-The statement can be executed with one of the following methods, depending on
-how you'd like to obtain the results:
+To execute the statement, call one (and exactly one) of the following methods,
+depending on how you'd like to obtain the results:
 
 =over
 
@@ -333,11 +327,79 @@ columns are stored as hashref.
 =back
 
 The only time you actually need to assign a statement object to a variable is
-when you want to inspect C<param_types> or C<columns>, in all other cases you
-can chain the methods for more concise code. For example:
+when you want to inspect the statement using one of the methods below, in all
+other cases you can chain the methods for more concise code. For example:
 
   my $data = $conn->q('SELECT a, b FROM table')->cache(0)->text->alla;
 
+Statement objects can be inspected with the following methods (many of which
+only make sense after the query has been executed):
+
+=over
+
+=item $st->query
+
+Returns the SQL query that the statement was created with.
+
+=item $st->param_values
+
+Returns the provided bind parameters as an arrayref.
+
+=item $st->param_types
+
+Returns an arrayref of integers indicating the type (as I<oid>) of each
+parameter in the given C<$sql> string. Example:
+
+  my $oids = $conn->q('SELECT id FROM books WHERE id = $1 AND title = $2')->param_types;
+  # $oids = [23,25]
+
+  my $oids = $conn->q('SELECT id FROM books')->params;
+  # $oids = []
+
+This method can be called before the query has been executed, but will then
+trigger a prepare operation.
+
+=item $st->columns
+
+Returns an arrayref of hashrefs describing each column that the statement
+returns.
+
+  my $cols = $conn->q('SELECT id, title FROM books')->columns;
+  # $cols = [
+  #   { name => 'id', oid => 23 },
+  #   { name => 'title', oid => 25 },
+  # ]
+
+=item $st->nrows
+
+Returns the number of rows the query returned, may return C<undef> for
+C<exec()>-style queries.
+
+=item $st->exec_time
+
+Observed query execution time, in seconds. Includes network round-trip and
+fetching the full query results. Does not include conversion of the query
+results into Perl values.
+
+=item $st->prepare_time
+
+Observed query preparation time, in seconds, including network round-trip.
+Returns 0 if a cached prepared statement was used or C<undef> if the query was
+executed without a separate preparation phase (currently only happens with C<<
+$conn->exec() >>, but support for direct query execution may be added for other
+queries in the future as well).
+
+=item $st->get_cache
+
+=item $st->get_text_params
+
+=item $st->get_text_results
+
+Returns the respective configuration parameters.
+
+=back
+
+
 
 =head2 Transactions