NAME
Protocol::PostgreSQL - support for the PostgreSQL wire protocol
VERSION
version 0.008
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->simple_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. Blesses an empty hashref and calls "configure", subclasses can bypass this entirely and just call "configure" directly after instantiation.
configure
Does the real preparation for the object.
Takes callbacks as named parameters, including:
on_error
on_data_row
on_ready_for_query
has_queued
Returns number of queued messages.
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
Generate and send the startup request.
send_message
Send a message.
queue
Queue up a message for sending. The message will only be sent when we're in ReadyForQuery mode, which could be immediately or later.
send_next_in_queue
Send the next queued message.
message
Creates a new message of the given type.
attach_event
Attach new handler(s) to the given event(s).
detach_event
Detach handler(s) from the given event(s). Not implemented.
debug
Helper method to report debug information. Can take a string or a coderef.
handle_message
Handle an incoming message from the server.
message_length
Returns the length of the given message.
simple_query
Send a simple query to the server - only supports plain queries (no bind parameters).
copy_data
Send copy data to the server.
copy_done
Indicate that the COPY data from the client is complete.
backend_state
Accessor for current backend state.
active_statement
Returns the currently active Protocol::PostgreSQL::Statement if we have one.
row_description
Accessor for row description.
prepare
Prepare a Protocol::PostgreSQL::Statement. Intended to be mostly compatible with the DBI ->prepare method.
prepare_async
Set up a Protocol::PostgreSQL::Statement allowing callbacks and other options to be provided.
is_ready
Returns true if we're ready to send more data to the server.
send_copy_data
Send COPY data to the server. Takes an arrayref and replaces any reserved characters with quoted versions.
_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.