NAME

Pg::Simple - simple OO interface to PostgreSQL

SYNOPSIS

  use Pg::Simple;

  my $db = new Pg::Simple;
  $db->connect( { DB => 'spectral' } );

  my $db = new Pg::Simple( { DB => 'spectral' } );

  $db->execute( SQL command or query ) or die;

  while ( $db->fetch( \$field1, \$field2 ) )
  { 
    print "$field1 $field2\n"
  }

  # or

  while ( $hash = $db->fetchhash and keys %$hash )
  {
    print $hash->{some_key};
  }

  $db->finish;

DESCRIPTION

Pg::Simple is a very simple interface to PostgreSQL. It is patterned after the DBI interface. Why not use the DBI interface instead? The main reason is that it does not yet support cursors. This module does. When the DBI Postgres interface supports cursors, one should use that instead.

This module is designed primarily to ease reading data from a database. All statements are executed within a transaction. Normally the AutoCommit flag is set, meaning that after each execution of the do or execute method, the backend is sent a commit directive. If AutoCursor is set, execute will not perform a commit, as it would destroy the cursor.

Usually one uses the do method for directives which do not return any data. The execute and finish pair should be used when data is to be returned. The main difference is that execute will create a cursor if AutoCursor is set, while do won't. finish is required to close the cursor.

Object action methods

new [ \%attr ]

This method creates a new Pg::Simple object. It returns undef upon error. The optional hash of attributes may include any of the following:

AutoCursor

If set, the execute method always creates a cursor before sending the command to the backend. This defaults to on.

AutoCommit

If set, a commit directive will be sent to the backend after each do is performed. In order not to abort selections performed via execute, a commit directive will not be sent to the backend by execute if AutoCursor is set. It will be sent by the finish method. If not set, use the commit method to commit any changes. There is no need to start a new transaction; that is done automatically.

RaiseError

If set, errors will result in an exception being thrown ( via croak), rather. If not set, errors will result in a message being printed to STDERR and an error value returned to the caller. It defaults to on.

Verbose

If set, Pg::Simple will say a few things about what it is doing (to STDERR).

NFetch

The number of tuples to fetch from the cursor at once. This defaults to 1000.

Name

A symbolic name to assign to the connection. This is used to differentiate output when Verbose is set.

Trace

If set (to a stream glob, i.e. \*STDERR), the underlying Pg interface will send debugging information to that stream. Defaults to off.

DB

The name of the database to which to connect. If this is set, Pg::Simple will attempt to make a connection. Alternatively, see the connect method.

Host

The host to which to connect. This defaults to the value of the PGHOST environmental variable, if that exists, else the undefined value.

Port

The port to which to connect. This defaults to the value of the PGPORT environmental variable, if that exists, else 5432.

User

The database user id.

Password

The password to pass to the backend. Required only if the database requires password authentication. If not specified, the value of the PGPASSWORD environmental variable is used.

connect([\%attr])

This method will connect to a database. It takes an optional hash which may contain the following attributes:

DB

The name of the database to which to connect. If this is set, Pg::Simple will attempt to make a connection. Alternatively, see the connect method.

Host

The host to which to connect. This defaults to the value of the PGHOST environmental variable, if that exists, else the undefined value.

Port

The port to which to connect. This defaults to the value of the PGPORT environmental variable, if that exists, else 5432.

User

The database user id.

Password

The password to pass to the backend. Required only if the database requires password authentication. If not specified, the value of the PGPASSWORD environmental variable is used.

It returns undef upon error, else something else.

execute( command [, \%attr] )

This method will pass a command or query to the backend. It may be passed a hash containing the following attributes:

AutoCursor

If set, the execute method always creates a cursor before sending the command to the backend. This defaults to on.

RaiseError

If set, errors will result in an exception being thrown ( via croak), rather. If not set, errors will result in a message being printed to STDERR and an error value returned to the caller. It defaults to on.

The attributes apply to this method call only.

It returns undef upon error.

do( command [, \%attr] )

This method sends the command to the backend. It does not create a cursor. It may be passed a hash containing the following attributes:

RaiseError

If set, errors will result in an exception being thrown ( via croak), rather. If not set, errors will result in a message being printed to STDERR and an error value returned to the caller. It defaults to on.

The attributes apply to this method call only.

It returns undef upon error.

ntuples

The number of tuples returned by the last query. It returns -1 if it can't access that information.

fetch( \$field1, \$field2, ... )

Returns the next tuple of data generated by a previous call to execute. If the AutoCursor attribute was set, it will internally fetch NFetch tuples at a time. It stores the returned fields in the scalars referenced by the passed arguments. It is an error if there are fewer passed references than fields requested by the select.

It returns 0 if there are no more tuples, undef upon error.

fetch_hashref

  $hash = $db->fetch_hasherf

Returns the next tuple of data generated by a previous call to execute. If the AutoCursor attribute was set, it will internally fetch NFetch tuples at a time. It returns the row as a hashref.

It returns an empty hash if there are no more tuples, undef upon error.

commit

This should be called to commit any changes to the database.

abort

This should be called to abort the current transaction

finish

This should be called after all fetchs have been completed for a select statement. It closes the cursor (if AutoCursor was specified).

LICENSE

This software is released under the GNU General Public License. You may find a copy at

   http://www.fsf.org/copyleft/gpl.html

AUTHOR

Diab Jerius ( djerius@cpan.org )