pg: Module rename + more docs

FU/Pg.pm

@@ -0,0 +1,515 @@
+package FU::Pg 0.1;
+use v5.36;
+use FU::XS;
+
+_load_libpq();
+
+package FU::Pg::conn {
+    sub lib_version { FU::Pg::lib_version() }
+};
+
+package FU::Pg::error {
+    use overload '""' => sub($e, @) { $e->{full_message} };
+}
+
+1;
+__END__
+
+=head1 NAME
+
+FU::Pg - The Ultimate (synchronous) Interface to PostgreSQL
+
+=head1 SYNOPSYS
+
+  my $conn = FU::Pg->connect("dbname=test user=test password=nottest");
+
+  $conn->exec('CREATE TABLE books (id SERIAL, title text, read bool)');
+
+  $conn->q('INSERT INTO books (title) VALUES ($1)', 'Revelation Space')->exec;
+  $conn->q('INSERT INTO books (title) VALUES ($1)', 'The Invincible')->exec;
+
+  for my ($id, $title) ($conn->q('SELECT * FROM books')->flat->@*) {
+    print "$id:  $title\n";
+  }
+
+=head1 DESCRIPTION
+
+FU::Pg is a client module for PostgreSQL with a convenient high-level API and
+support for flexible and complex type conversions. This module interfaces
+directly with C<libpq>.
+
+=head2 Connection setup
+
+=over
+
+=item B<< FU::Pg->connect($string) >>
+
+Connect to the PostgreSQL server and return a new C<FU::Pg::conn> object.
+C<$string> can either be in key=value format or a URI, refer to L<the
+PostgreSQL
+documentation|https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>
+for the full list of supported formats and options. You may also pass an empty
+string and leave the configuration up L<environment
+variables|https://www.postgresql.org/docs/current/libpq-envars.html>.
+
+=item B<< $conn->server_version >>
+
+Returns the version of the PostgreSQL server as an integer in the format of
+C<$major * 10000 + $minor>. For example, returns 170002 for PostgreSQL 17.2.
+
+=item B<< $conn->lib_version >>
+
+Returns the libpq version in the same format as the C<server_version> method.
+Also available directly as C<FU::Pg::lib_version()>.
+
+=item B<< $conn->status >>
+
+Returns a string indicating the status of the connection. Note that this method
+does not verify that the connection is still alive, the status is updated after
+each command. Possible return values:
+
+=over
+
+=item idle
+
+Awaiting commands, not in a transaction.
+
+=item txn_idle
+
+Awaiting commands, inside a transaction.
+
+=item txn_done
+
+Idle, but a transaction object still exists. The connection is unusable until
+that object goes out of scope.
+
+=item txn_error
+
+Inside a transaction that is in an error state. The transaction must be rolled
+back in order to recover to a usable state. This happens automatically when the
+transaction object goes out of scope.
+
+=item bad
+
+Connection is dead or otherwise unusable.
+
+=back
+
+=item B<< $conn->cache($enable) >>
+
+=item B<< $conn->text_params($enable) >>
+
+=item B<< $conn->text_results($enable) >>
+
+=item B<< $conn->text($enable) >>
+
+Set the default settings for new statements created with B<< $conn->q() >>.
+
+=item B<< $conn->disconnect >>
+
+Close the connection. Any active transactions are rolled back and any further
+attempts to use C<$conn> throw an error.
+
+=back
+
+=head2 Querying
+
+=over
+
+=item B<< $conn->exec($sql) >>
+
+Execute one or more SQL commands, separated by a semicolon. Returns the number
+of rows affected by the last statement or I<undef> if that information is not
+available for the given command (like with C<CREATE TABLE>).
+
+=item B<< $conn->q($sql, @params) >>
+
+Create a new SQL statement with the given C<$sql> string and an optional list
+of bind parameters. C<$sql> can only hold a single statement.
+
+Parameters can be referenced from C<$sql> with numbered placeholders, where
+C<$1> refers to the first parameter, C<$2> to the second, etc. Be careful to
+not accidentally interpolate perl's C<$1> and C<$2>. Using a question mark for
+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
+prepared or executed until the appropriate statement methods (see below) are
+used.
+
+=back
+
+Statement objects returned by C<< $conn->q() >> support the following
+configuration parameters:
+
+=over
+
+=item B<< $st->cache($enable) >>
+
+Enable or disable caching of the prepared statement for this particular query.
+
+=item B<< $st->text_params($enable) >>
+
+Enable or disable sending bind parameters in the text format.
+
+=item B<< $st->text_results($enable) >>
+
+Enable or disable receiving query results in the text format.
+
+=item B<< $st->text($enable) >>
+
+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 B<< $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 B<< $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:
+
+=over
+
+=item B<< $st->exec >>
+
+Execute the query and return the number of rows affected. Similar to C<<
+$conn->exec >>.
+
+  my $v = $conn->q('UPDATE books SET read = true WHERE id = 1')->exec;
+  # $v = 1
+
+=item B<< $st->val >>
+
+Return the first column of the first row. Throws an error if the query does not
+return exactly one column, or if multiple rows are returned. Returns I<undef>
+if no rows are returned or if its value is I<NULL>.
+
+  my $v = $conn->q('SELECT COUNT(*) FROM books')->val;
+  # $v = 2
+
+=item B<< $st->rowl >>
+
+Return the first row as a list. Throws an error if the query does not return
+exactly one row.
+
+  my($id, $title) = $conn->q('SELECT id, title FROM books LIMIT 1')->rowl;
+  # ($id, $title) = (1, 'Revelation Space');
+
+=item B<< $st->rowa >>
+
+Return the first row as an arrayref, equivalent to C<< [$st->rowl] >> but
+might be slightly more efficient.
+
+  my $row = $conn->q('SELECT id, title FROM books LIMIT 1')->rowa;
+  # $row = [1, 'Revelation Space'];
+
+=item B<< $st->rowh >>
+
+Return the first row as a hashref. Also throws an error if the query returns
+multiple columns with the same name.
+
+  my $row = $conn->q('SELECT id, title FROM books LIMIT 1')->rowh;
+  # $row = { id => 1, title => 'Revelation Space' };
+
+=item B<< $st->alla >>
+
+Return all rows as an arrayref of arrayrefs.
+
+  my $data = $conn->q('SELECT id, title FROM books')->alla;
+  # $data = [
+  #   [ 1, 'Revelation Space' ],
+  #   [ 2, 'The Invincible' ],
+  # ];
+
+=item B<< $st->allh >>
+
+Return all rows as an arrayref of hashrefs. Throws an error if the query
+returns multiple columns with the same name.
+
+  my $data = $conn->q('SELECT id, title FROM books')->allh;
+  # $data = [
+  #   { id => 1, title => 'Revelation Space' },
+  #   { id => 2, title => 'The Invincible' },
+  # ];
+
+=item B<< $st->flat >>
+
+Return an arrayref with all rows flattened.
+
+  my $data = $conn->q('SELECT id, title FROM books')->flat;
+  # $data = [
+  #   1, 'Revelation Space',
+  #   2, 'The Invincible',
+  # ];
+
+=item B<< $st->kvv >>
+
+Return a hashref where the first result column is used as key and the second
+column as value. If the query only returns a single column, C<true> is used as
+value instead. An error is thrown if the query returns 3 or more columns.
+
+  my $data = $conn->q('SELECT id, title FROM books')->kvv;
+  # $data = {
+  #   1 => 'Revelation Space',
+  #   2 => 'The Invincible',
+  # };
+
+=item B<< $st->kva >>
+
+Return a hashref where the first result column is used as key and the remaining
+columns are stored as arrayref.
+
+  my $data = $conn->q('SELECT id, title, read FROM books')->kva;
+  # $data = {
+  #   1 => [ 'Revelation Space', true ],
+  #   2 => [ 'The Invincible', false ],
+  # };
+
+=item B<< $st->kvh >>
+
+Return a hashref where the first result column is used as key and the remaining
+columns are stored as hashref.
+
+  my $data = $conn->q('SELECT id, title, read FROM books')->kvh;
+  # $data = {
+  #   1 => { title => 'Revelation Space', read => true },
+  #   2 => { title => 'The Invincible', read => false },
+  # };
+
+=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:
+
+  my $data = $conn->q('SELECT a, b FROM table')->cache(0)->text->alla;
+
+
+=head2 Transactions
+
+This module provides a convenient and safe API for I<scoped transactions> and
+I<subtransactions>. A new transaction can be started with C<< $conn->txn >>,
+which returns an object that can be used to run commands inside the transaction
+and control its fate. When the object goes out of scope, the transaction is
+automatically rolled back if no explicit C<< $txn->commit >> has been
+performed. Any attempts to run queries on the parent C<< $conn >> object will
+fail while a transaction object is alive.
+
+  {
+    # start a new transaction
+    my $txn = $conn->txn;
+
+    # run queries
+    $txn->q('DELETE FROM books WHERE id = $1', 1)->exec;
+
+    # run commands in a subtransaction
+    {
+      my $subtxn = $txn->txn;
+      # ...
+    }
+
+    # commit
+    $txn->commit;
+
+    # If $txn->commit has not been called, the transaction will be rolled back
+    # automatically when it goes out of scope.
+  }
+
+Transaction methods:
+
+=over
+
+=item B<< $txn->exec(..) >>
+
+=item B<< $txn->q(..) >>
+
+Run a query inside the transaction. These work the same as the respective
+methods on the parent C<$conn> object.
+
+=item B<< $txn->commit >>
+
+=item B<< $txn->rollback >>
+
+Commit or abort the transaction. Any attempts to run queries on this
+transaction object after this call will throw an error.
+
+Calling C<rollback> is optional, the transaction is automatically rolled back
+when the object goes out of scope.
+
+=item B<< $txn->cache($enable) >>
+
+=item B<< $txn->text_params($enable) >>
+
+=item B<< $txn->text_results($enable) >>
+
+=item B<< $txn->text($enable) >>
+
+Set the default settings for new statements created with B<< $txn->q() >>.
+
+These settings are inherited from the main connection when the transaction is
+created. Subtransactions inherit these settings from their parent transaction.
+Changing these settings within a transaction does not affect the main
+connection or any already existing subtransactions.
+
+=item B<< $txn->txn >>
+
+Create a subtransaction within the current transaction. A subtransaction works
+exactly the same as a top-level transaction, except any changes remain
+invisible to other sessions until the top-level transaction has been committed.
+
+=item B<< $txn->status >>
+
+Like C<< $conn->status >>, but with the following status codes:
+
+=over
+
+=item idle
+
+Current transaction is active and awaiting commands.
+
+=item done
+
+Current transaction has either been committed or rolled back, further commands
+will throw an error.
+
+=item error
+
+Current transaction is in error state and must be rolled back.
+
+=item txn_idle
+
+A subtransaction is active and awaiting commands. The current transaction is
+not usable until the subtransaction goes out of scope.
+
+(This status code is also returned when the subtransaction is 'done', the
+current implementation does not track subtransactions that closely)
+
+=item txn_error
+
+A subtransaction is in error state and awaiting to be rolled back.
+
+=item bad
+
+Connection is dead or otherwise unusable.
+
+=back
+
+=back
+
+Of course, if you prefer the old-fashioned manual approach to transaction
+handling, that is still available:
+
+  $conn->exec('BEGIN');
+  # We're now inside a transaction
+  $conn->exec('COMMIT') or $conn->exec('ROLLBACK');
+
+Just don't try to use transaction objects and manual transaction commands at
+the same time, that won't end well.
+
+
+=head2 Formats and Types
+
+I<TODO>
+
+=head2 Errors
+
+I<TODO>
+
+=head1 LIMITATIONS
+
+=over
+
+=item * Does not support older versions of libpq or PostgreSQL. Currently only
+tested with version 17, but versions a bit older than that ought to work fine
+as well.  Much older versions will certainly not work fine.
+
+=item * (Probably) not thread-safe.
+
+=item * Only supports the UTF-8 encoding for all text strings sent to and
+received from the PostgreSQL server. The encoding is assumed to be UTF-8 by
+default, but if this may not be the case in your situation, setting
+`client_encoding=utf8` as part of the connection string or manually switching
+to it after C<connect()> is always safe:
+
+  my $conn = FU::Pg->connect('');
+  $conn->exec('SET client_encoding=utf8');
+
+=item * Only works with blocking (synchronous) calls, not very suitable for use
+in asynchronous frameworks unless you know your queries are fast and you have a
+low-latency connection with the Postgres server.
+
+=back
+
+Missing features:
+
+=over
+
+=item COPY support
+
+I hope to implement this someday.
+
+=item LISTEN support
+
+Would be nice to have, most likely doable without going full async.
+
+=item Asynchronous calls
+
+Probably won't happen. Perl's async story is slightly awkward in general, and
+fully supporting async operation might require a fundamental redesign of how
+this module works. It certainly won't I<simplify> the implementation.
+
+=item Pipelining
+
+I have some ideas for an API, but doubt I'll ever implement it. Suffers from
+the same awkwardness and complexity as asynchronous calls.
+
+=back
+
+
+=head1 SEE ALSO
+
+=over
+
+=item L<DBD::Pg>
+
+The venerable Postgres driver for DBI. More stable, portable and battle-tested
+than this module, but type conversions may leave things to be desired.
+
+=item L<Pg::PQ>
+
+Thin wrapper around libpq. Lacks many higher-level conveniences and doesn't do
+any type conversions for you.
+
+=item L<DBIx::Simple>
+
+Popular DBI wrapper with some API conveniences. I may have taken some
+inspiration from it in the design of this module's API.
+
+=back