Module protocol

June 1, 2026 · View on GitHub

⤌ Back

Module protocol

Low-level PostgreSQL frontend/backend wire protocol (version 3.0) implementation. This module is an internal implementation detail. Application code should use Connection or Pool rather than this module directly.

Protocol overview (RFC 9522 / PostgreSQL documentation)

The PostgreSQL wire protocol uses a simple message framing scheme: Backend → Frontend messages (server responses):

  • 1 byte message type tag
  • 4 bytes big-endian int32 length (includes these 4 bytes, not the tag)
  • (length - 4) bytes payload Frontend → Backend messages (client requests):
  • Same layout, except the StartupMessage has no tag byte. All multi-byte integers are big-endian (network byte order).

References

Variables

MSG_AUTHENTICATION

MSG_BACKEND_KEY_DATA

MSG_BIND_COMPLETE

MSG_CLOSE_COMPLETE

MSG_COMMAND_COMPLETE

MSG_COPY_IN_RESPONSE

MSG_COPY_OUT_RESPONSE

MSG_DATA_ROW

MSG_EMPTY_QUERY_RESPONSE

MSG_ERROR_RESPONSE

MSG_NO_DATA

MSG_NOTICE_RESPONSE

MSG_NOTIFICATION_RESPONSE

MSG_PARAMETER_DESCRIPTION

MSG_PARAMETER_STATUS

MSG_PARSE_COMPLETE

MSG_PORTAL_SUSPENDED

MSG_READY_FOR_QUERY

MSG_ROW_DESCRIPTION

AUTH_OK

AUTH_KERBEROS_V5

AUTH_CLEARTEXT_PASSWORD

AUTH_MD5_PASSWORD

AUTH_SCM_CREDENTIAL

AUTH_GSS

AUTH_GSS_CONTINUE

AUTH_SSPI

AUTH_SASL

AUTH_SASL_CONTINUE

AUTH_SASL_FINAL

Classes

class MessageBuffer

Methods

  • MessageBuffer() (Constructor)

  • write_byte(b)

  • write_int16(v)

  • write_int32(v)

  • write_cstring(s)

  • write_bytes(b)

  • to_list()

  • clear()

class MessageReader

Reads and parses framed messages from a PostgreSQL backend socket.

Methods

  • MessageReader(sock, ssl) (Constructor)

  • read_message()

    Reads the next complete message from the backend.

class Protocol

Implements the PostgreSQL frontend/backend wire protocol version 3.0. Manages a single socket connection to a PostgreSQL server and exposes methods corresponding to each frontend message type.

Methods

  • Protocol(sock, registry, ssl_obj) (Constructor)

    Parameters

    • socket.Socket sock The connected TCP socket.

    • TypeRegistry registry Type codec registry to use.

    • ssl|nil ssl_obj Optional SSL object (from ssl module).

  • startup(user, database, password, options)

    Sends the StartupMessage and drives the authentication exchange.

    Parameters

    • string user PostgreSQL username.

    • string database Database name.

    • string password Password (may be nil).

    • dict options Extra startup parameters (application_name, etc.).

  • simple_query(sql)

    Executes a plain-text query and collects all results. Uses the "simple query" protocol sub-protocol.

    Parameters

    • string sql The SQL statement to execute.

  • extended_query(sql, params, param_oids, portal, stmt_name, max_rows)

    Executes a query using the extended query protocol with binary parameter binding and binary result decoding.

    Parameters

    • string sql Parameterised SQL ($1, $2, …).

    • list params Zuri parameter values.

    • list param_oids OIDs for each parameter (may be empty list).

    • string portal Portal name ('' for unnamed).

    • string stmt_name Prepared statement name ('' for unnamed).

    • number max_rows 0 = fetch all; >0 = cursor row limit.

  • prepare(name, sql, param_oids)

    Sends a Parse message to create a named prepared statement.

    Parameters

    • string name Statement name (''' for unnamed).

    • string sql The parameterised SQL.

    • list param_oids OID list (may be empty; server will infer types).

  • execute_prepared(stmt_name, params, param_oids, portal, max_rows)

    Executes a previously prepared statement bound to named portal portal.

    Parameters

    • string stmt_name Statement name.

    • list params Parameter values.

    • list param_oids OID for each parameter.

    • string portal Portal name.

    • number max_rows 0 = all rows.

  • close_statement(name)

    Closes a named prepared statement on the server.

    Parameters

    • string name The statement name.

  • close_portal(name)

    Closes a named portal on the server.

    Parameters

    • string name The portal name.

  • listen(channel)

    Sends a LISTEN command for the given channel.

    Parameters

    • string channel The notification channel name.

  • unlisten(channel)

    Sends an UNLISTEN command.

    Parameters

    • string channel The channel name, or '' for all channels.

  • poll_notification()

    Checks for an available notification without blocking. Returns nil if no notification is available, or a dict { channel, payload, pid } if one is present.

  • terminate()

    Sends the Terminate message and closes the underlying socket.