I got tired of writing C-like code in my Perl programs using the Pg package,
so I wrote a new and improved interface that is more Perl-like.  It is loosely
based on the way the MsqlPerl module works, so it should make for easy porting
of those programs (which is also one of the reasons I wrote this...)

Below is the documentation for the module as generated by pod2text.

To fetch your very own copy, get the file PostgresPerl-N.N.tar.gz from your
closest CPAN, unpack it, then run "perl Makefile.PL; make".

To test it, set the environment variable PGHOST to the host of the server
running postgres (if other than the machine which you are on) and then "make
test".  Then all that's necessary is a make install and you've got yourself a
nice perl interface to Postgres95!  It does, however, require Perl 5.002 or
newer.

Note: It has been reported that the following line needs to be added to
the Makefile.PL to make it run on some systems, such as HP/UX and Linux.

     'MYEXTLIB' => ' /usr/local/postgres95/lib/libpq.so.1',

but I have no way to verify this directly.

When compiling, expect the following warnings (line numbers may be off):

 /usr/local/postgres95/include/c.h:61: warning: useless keyword or type name
					in empty declaration
 /usr/local/postgres95/include/c.h:61: warning: empty declaration
 Postgres.c: In function `XS_QUERYPtr_query_oidStatus':
 Postgres.c:684: warning: assignment discards `const' from pointer target type

These are caused by the Postgres95 header files.

This module has been tested with Perl 5.003 and Postgres95 1.09.

If anyone wishes to take over maintenance of this module, please feel
free.  I am no longer interested or capable of doing so, as I am not
using Postgres any longer.



NAME
    Postgres - Perl interface to the Postgres95 SQL database engine

SYNOPSIS
     use Postgres;

     $conn = db_connect($database,$host,$port)
       or die "could not connect -- $Postgres::error";

     The parameters $host and $port are optional (or may be undef).
     This will use the default Postgres95 values for them.

     print "Connected Database: ", $conn->db();
     print "Connected Host: ", $conn->host();
     print "Connection Options: ", $conn->options();
     print "Connected Port: ", $conn->port();
     print "Connected tty: ", $conn->tty();
     print "Connection Error Message: ", $conn->errorMessage();


    This method is identical to PQreset(conn)

     $conn->reset();


    This method executes an SQL statement or query.

     $query = $conn->execute($sql_statement)
       or die "Error -- $Postgres::error";


    Retrieve the values from a SELECT query.

     @array = $query->fetchrow();


    Get information from the results of the last query.

     $val = $query->cmdStatus();
     $val = $query->oidStatus();


    Calling the following functions on a result handle that is not from a
    SELECT is undefined.

     $val = $query->ntuples();
     $val = $query->nfields();
     $val = $query->fname($column_index);
     $val = $query->fnumber($column_name);
     $val = $query->ftype($column_index);
     $val = $query->fsize($column_index);


    These functions are provided for completeness but are not intended to be
    used. The fetchrow() method will return `undef' for a field which is
    null.

     $val = $query->getvalue($tuple_index,$column_index);
     $val = $query->getlength($tuple_index,$column_index);
     $val = $query->getisnull($tuple_index,$column_index);


    The putline() and getline() functions are called as follows:

     $query->putline($string);
     $value = $query->getline();
     $query->endcopy();


DESCRIPTION
    This package is designed as close as possible to its C API counterpart,
    but be more like Perl in how you interact with the API. The C Programmer
    Guide that comes with Postgres describes most things you need.

    The following functions are currently not implemented: PQtrace(),
    PQendtrace(), and the asynchronous notification. I do not believe that
    binary cursors will work, either.

    Once you db_connect() to a database, you can then issue commands to the
    execute() method. If either of them returns an error from the underlying
    API, the value returned will be `undef' and the variable
    `$Postgres::error' will contain the error message from the database. The
    `$port' parameter to db_connect() is optional and will use the default
    port if not specified. All environment variables used by the PQsetdb()
    function are honored.

    The method fetchrow() returns an array of the values from the next row
    fetched from the server. It returns an empty list when there is no more
    data available. Fields which have a NULL value return `undef' as their
    value in the array. Calling fetchrow() or the other tuple-related
    functions on a statement handle which is not from a SELECT statement has
    undefined behavior, and may well crash your program. Other functions
    work identically to their similarly-named C API functions.

  No finish or clear statements

    Whenever the scalar that holds the statement or connection handle loses
    its value, the underlying data structures will be freed and appropriate
    connections closed. This can be accomplished by performing one of these
    actions:

    undef the handle
    use the handle for another purpose
    let the handle run out of scope
    exit the program.

  Error messages

    A global variable `$Postgres::error' always holds the last error
    message. It is never reset except on the next error. The only time it
    holds a valid message is after execute() or db_connect() returns
    `undef'.

PREREQUISITES
    You need to have the Postgres95 database server installed and configured
    on your system to use this module.

    Be sure to set the proper directory locations in the `Makefile.PL' file
    for your installation.

AUTHOR
    Vivek Khera (`vivek@khera.org'). Many ideas were taken from the MsqlPerl
    module.  I am no longer maintaining this module.  If you would
    like to take over, please let me know.