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

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.