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.