The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Protocol::PostgreSQL::Statement - prepared statement handling

VERSION

version 0.008

SYNOPSIS

 use Protocol::PostgreSQL;
 my %cache;
 # Helper method to apply the returned values
 my $set_cache = sub {
        my ($sth, $row) = @_;
        my ($k, $v) = map { $row->[$_]{data} } 0..1;
        warn "Set $k to $v\n";
        $cache{$k} = $v;
 };
 # Prepared statement to insert a new value, called when no existing value was found
 my $add_sth = Protocol::PostgreSQL::Statement->new(
        dbh => $dbh,
        sql => 'insert into sometable (name) values $1 returning id, name',
        on_data_row     => $set_cache,
        on_no_data      => sub {
                die "Had no response when trying to add value";
        }
 );
 # Find existing value from table
 my $find_sth = Protocol::PostgreSQL::Statement->new(
        dbh => $dbh,
        sql => 'select id, name from sometable where id = ?',
        on_data_row     => $set_cache,
        on_no_data      => sub {
                my ($sth) = shift;
                warn "No data found, inserting\n";
                $add_sth->execute($sth->current_bind_values);
        }
 );
 $find_sth->execute(471, "some data");
 print "Value for 471 was " . $cache{471};

DESCRIPTION

Provides prepared-statement support for Protocol::PostgreSQL.

Sequence of events for a prepared statement:

  • Parse - check the supplied SQL, generate a prepared statement

  • Bind - binds values to a statement to generate a portal ('' is the empty portal)

  • Execute - execute a given portal

  • Sync - inform the server we're done and that we want to go back to "ReadyForQuery" in Protocol::PostgreSQL state.

Once an execute is running, we avoid sending anything else to the server until we get a ReadyForQuery response.

On instantiation, the statement will be parsed immediately. When this is complete, we are able to bind then execute. Any requests to bind or execute before the statement is ready will be queued.

METHODS

new

Instantiate a new object, takes the following named parameters:

  • dbh - Protocol::PostgreSQL-compatible object for the parent database handle

  • sql - actual SQL query to run, with placeholders specified as ?

  • statement - name to assign to this statement

Will send the parse request immediately.

parse_complete

Callback when parsing is complete.

execute

Bind variables to the current statement.

current_bind_values

Returns the bind values from the currently-executing query, suitable for passing to "execute".

data_row

Callback when we have a data row.

Maintains a running count of how many rows we've seen, and passes the data on to the data_row callback if defined.

command_complete

Callback for end of statement. We'll hit this if we completed without error and there's no more data available to read.

Will call the no_data callback if we had no rows, and the command_complete callback in either case.

bind_complete

Called when the bind is complete. Since our bind+execute handling is currently combined, this doesn't do anything at the moment.

_execute

Execute this query.

describe

Describe this query. Causes PostgreSQL to send RowDescription response indicating what we expect to get back from the server. Beats trying to parse the query for ourselves although it incurs an extra send/receive for each statement.

row_description

Accessor to return or update the internal row description information.

on_ready

Called when we've finished parsing and describing this query.

finish

Finish the current statement.

Should issue a Sync to trigger a ReadyForQuery response, but that's now handled elsewhere.

dbh

Accessor for the database handle (Protocol::PostgreSQL object).

sap

Generate a callback with weakened copy of $self.

AUTHOR

Tom Molesworth <cpan@entitymodel.com>

LICENSE

Copyright Tom Molesworth 2010-2011. Licensed under the same terms as Perl itself.