Protoco...tgreSQL(3)

🦋 Protocol::Database::PostgreSQL(3) 🦋

Okay bestie, so this is a User Contributed Perl Documentation page for Protocol::Database::PostgreSQL — yes that's the module name, yes it's a mouthful, we move. 💅

---

✨ NAME ✨

Protocol::Database::PostgreSQL — literally just support for the PostgreSQL wire protocol. That's it. That's the whole vibe. 🎀

---

🌸 SYNOPSIS 🌸

 use strict;
 use warnings;
 use mro;
 package Example::PostgreSQL::Client;

 sub new { bless { @_[1..$#_] }, $_[0] }

 sub protocol {
  my ($self) = @_;
  $self->{protocol} //= Protocol::Database::PostgresQL->new(
   outgoing => $self->outgoing,
  )
 }
 # Any received packets will arrive here
 sub incoming { shift->{incoming} //= Ryu::Source->new }
 # Anything we want to send goes here
 sub outgoing { shift->{outgoing} //= Ryu::Source->new }

 ...
 # We raise events on our incoming source in this example -
 # if you prefer to handle each message as it's extracted you
 # could add that directly in the loop
 $self->incoming
   ->switch_str(
    sub { $_->type },
    authentication_request => sub { ... },
    sub { warn 'unknown message - ' . $_->type }
   );
 # When there's something to write, we'll get an event here
 $self->outgoing
      ->each(sub { $sock->write($_) });
 while(1) {
  $sock->read(my $buf, 1_000_000);
  while(my $msg = $self->protocol->extract_message(\$buf)) {
   $self->incoming->emit($msg);
  }
 }

(And yes, copy that verbatim, including the PostgresQL capitalization situation — that's how it's written, don't come for me. 😭)

---

💜 DESCRIPTION 💜

This thing gives you protocol-level support for PostgreSQL 7.4+, exactly as defined over at <http://www.postgresql.org/docs/current/static/protocol.html>. No cap, that's the spec it's following.

🫶 How do I use this?

The short answer: don't.

Use Database::Async::Engine::PostgreSQL instead — like, genuinely — unless you're out here writing a driver for talking to PostgreSQL (or compatible) systems. That's the only main character usage.

This distribution provides the abstract protocol handling, meaning it understands the packets that make up the PostgreSQL communication protocol, but it does not attempt to send or receive those packets itself. It's giving brain-no-hands. 🧠✋ You need to provide the transport layer yourself (typically this would involve TCP or Unix sockets).

---

🌈 Connection states

Here are the possible states, bestie, in order of the journey:

• Unconnected — we have a valid instantiated PostgreSQL object, but no connection yet.
• Connected — transport layer has made a connection for us.
• AuthRequested — the server has challenged us to identify. Prove it. 💅
• Authenticated — we have successfully identified with the server.
• Idle — session is active and ready for commands.
• Parsing — a statement has been passed to the server for parsing.
• Describing — the indicated statement is being described, called after the transport layer has sent the Describe request.
• Binding — parameters for a given query have been transmitted.
• Executing — we have sent a request to execute.
• ShuttingDown — terminate request sent. Bye bestie 👋
• CopyIn — the server is expecting data for a COPY command.

---

🦋 Message types

The "type" in Protocol::Database::Backend for incoming messages can currently include the following:

• "send_request" — Called each time there is a new message to be sent to the other side of the connection.
• "authenticated" — Called when authentication is complete.
• "copy_data" — we have received data from an ongoing COPY request.
• "copy_complete" — the active COPY request has completed.

For the client, the following additional callbacks are available (this list is long, I know, but every single one matters 🙈):

• "request_ready" — the server is ready for the next request.
• "bind_complete" — a Bind request has completed.
• "close_complete" — the Close request has completed.
• "command_complete" — the requested command has finished, this will typically be followed by an on_request_ready event.
• "copy_in_response" — indicates that the server is ready to receive COPY data.
• "copy_out_response" — indicates that the server is ready to send COPY data.
• "copy_both_response" — indicates that the server is ready to exchange COPY data (for replication).
• "data_row" — data from the current query.
• "empty_query" — special-case response when sent an empty query, can be used for 'ping'. Typically followed by on_request_ready.
• "error" — server has raised an error. 💀
• "function_call_result" — results from a function call.
• "no_data" — indicate that a query returned no data, typically followed by on_request_ready.
• "notice" — server has sent us a notice.
• "notification" — server has sent us a NOTIFY.
• "parameter_description" — parameters are being described.
• "parameter_status" — parameter status...
• "parse_complete" — parsing is done.
• "portal_suspended" — the portal has been suspended, probably hit the row limit.
• "ready_for_query" — we're ready for queries. 🔥
• "row_description" — descriptive information about the rows we're likely to be seeing shortly.

And there are also these potential events back from the server:

• "copy_fail" — the frontend is indicating that the copy has failed.
• "describe" — request for something to be described.
• "execute" — request execution of a given portal.
• "flush" — request flush.
• "function_call" — request execution of a given function.
• "parse" — request to parse something.
• "password" — password information.
• "query" — simple query request.
• "ssl_request" — we have an SSL request.
• "startup_message" — we have an SSL request.
• "sync" — sync request.
• "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. Iconic flexibility, honestly.

🌟 configure

Does the real preparation for the object. The actual work. The main character of setup. ✨

🌟 frontend_bind

Bind parameters to an existing prepared statement.

🌟 frontend_copy_data

(No description in the original — it's just vibing there. 🫶)

🌟 frontend_close

(Also just vibing. 🫶)

🌟 frontend_copy_done

(Still vibing. 🫶)

🌟 frontend_describe

Describe expected SQL results.

🌟 frontend_execute

Execute either a named or anonymous portal (prepared statement with bind vars).

🌟 frontend_parse

Parse SQL for a prepared statement.

🌟 frontend_password_message

Password data, possibly encrypted depending on what the server specified. 🔐

🌟 frontend_sasl_initial

Initial client response for SASL authentication.

🌟 frontend_query

Simple query.

🌟 frontend_startup_message

Initial mesage informing the server which database and user we want. (Yes, "mesage" — keeping the original spelling because I respect the source. 💅)

🌟 frontend_sync

Synchonise after a prepared statement has finished execution. (Yes, "Synchonise" — again, respecting the source. 😭)

🌟 frontend_terminate

(No description given. It terminates, bestie. That's the whole thing. 💀)

🌟 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."

🌟 send_message

Send a message.

🌟 method_for_frontend_type

Returns the method name for the given frontend type.

🌟 is_known_frontend_message_type

Returns true if the given frontend type is one that we know how to handle.

🌟 message

Creates a new message of the given type.

🌟 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). Keep it simple, periodt.

🌟 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.

🌟 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. Responsible king. 👑

🌟 build_message

Construct a new message.

---

🔥 SEE ALSO 🔥

Some PostgreSQL-related modules — plenty of things build on these, so have a look at the relevant reverse deps if you're after something higher level:

• DBD::Pg — uses the official library and (unlike this module) provides full support for DBI.
• Pg::PQ — another libpq wrapper.
• Postgres — quite an old (1998) libpq binding.
• Pg — slightly less old (2000) libpq binding.
• DBD::PgPP — provides another pure-Perl implemmentation, with the focus on DBI compatibility. (Yep, three m's in "implemmentation", leaving it exactly as found 🫡)

Other related database protocols (the crossover episode nobody asked for but we all needed 🌈):

• Protocol::MySQL — Oracle's popular database product.
• Protocol::TDS — the tabular data stream protocol, mainly of interest for SQL Server users.

---

🎀 AUTHOR 🎀

Tom Molesworth <TEAM@cpan.org>

---

🌸 LICENSE 🌸

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

---

💖 And that's the whole page, bestie — courtesy of perl v5.42.2, dated 2026-02-15. Go forth and speak wire protocol responsibly. Slay. 💅✨🦋