NAME
Protocol::PostgreSQL - support for the PostgreSQL wire protocol
VERSION
version 0.001
SYNOPSIS
use strict; use warnings;
package PostgreSQL::Client;
use parent q{Protocol::PostgreSQL::Client};
sub new { my $self = shift->SUPER::new(@_); $self->{socket} = $self->connect(...); $self }
sub on_send_request { shift->socket->send(@_) }
sub socket { shift->{socket} }
sub connect { ... } # provide a method to connect to the server
sub incoming { shift->socket->read(@_) } # provide a method which passes on data from server
package main;
my $client = PostgreSQL::Client->new(user => ..., server => ..., database => ...);
$client->query(sql => q{select * from table}, on_data_row => sub {
my ($client, %args) = @_;
my @cols = $args{row};
print join(',', @cols) . "\n";
});DESCRIPTION
Provides protocol-level support for PostgreSQL 7.4+, as defined in http://www.postgresql.org/docs/current/static/protocol.html.
CALLBACKS
The following callbacks can be provided either as parameters to "new" or as methods in subclasses:
on_send_request - Called each time there is a new message to be sent to the other side of the connection.
on_authenticated - Called when authentication is complete
on_copy_data - we have received data from an ongoing COPY request
on_copy_complete - the active COPY request has completed
For the client, the following additional callbacks are available:
on_request_ready - the server is ready for the next request
on_bind_complete - a Bind request has completed
on_close_complete - the Close request has completed
on_command_complete - the requested command has finished, this will typically be followed by an on_request_ready event
on_copy_in_response - indicates that the server is ready to receive COPY data
on_copy_out_response - indicates that the server is ready to send COPY data
on_copy_both_response - indicates that the server is ready to exchange COPY data (for replication)
on_data_row - data from the current query
on_empty_query - special-case response when sent an empty query, can be used for 'ping'. Typically followed by on_request_ready
on_error - server has raised an error
on_function_call_result - results from a function call
on_no_data - indicate that a query returned no data, typically followed by on_request_ready
on_notice - server has sent us a notice
on_notification - server has sent us a NOTIFY
on_parameter_description - parameters are being described
on_parameter_status - parameter status...
on_parse_complete - parsing is done
on_portal_suspended - the portal has been suspended, probably hit the row limit
on_ready_for_query - we're ready for queries
on_row_description - descriptive information about the rows we're likely to be seeing shortly
And the server can send these events:
on_copy_fail - the frontend is indicating that the copy has failed
on_describe - request for something to be described
on_execute - request execution of a given portal
on_flush - request flush
on_function_call - request execution of a given function
on_parse - request to parse something
on_password - password information
on_query - simple query request
on_ssl_request - we have an SSL request
on_startup_message - we have an SSL request
on_sync - sync request
on_terminate - termination request
METHODS
new
Instantiate a new object.
is_authenticated
Returns true if we are authenticated (and can start sending real data).
is_first_message
Returns true if this is the first message, as per http://developer.postgresql.org/pgdocs/postgres/protocol-overview.html:
"For historical reasons, the very first message sent by the client (the startup message) has no initial message-type byte."initial_request
send_message
message
Creates a new message of the given type.
attach_event
Attach new handler(s) to the given event(s).
debug
Helper method to report debug information.
handle_message
message_length
Returns the length of the given message.
simple_query
backend_state
Accessor for current backend state.
row_description
Accessor for row description.
_event
Calls the given event callback if we have one.
_build_message
Construct a new message.
SEE ALSO
DBD::Pg, which uses the official library and (unlike this module) provides full support for DBI.
AUTHOR
Tom Molesworth <cpan@entitymodel.com>
LICENSE
Copyright Tom Molesworth 2010-2011. Licensed under the same terms as Perl itself.