Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

sql.postgres.messages

import sql.postgres.messages

sql does not re-export this module, so it is reached only by importing it directly.

Framing for the PostgreSQL wire protocol, version 3.

Every message is a one byte tag, a four byte big-endian length that counts itself, and then the body. The one exception is the startup message, which has no tag because the server has not yet been told which protocol version is in use.

Constants

AUTHENTICATION

sql.postgres.messages.AUTHENTICATION = 'R'

Messages the server sends, by tag.

BACKEND_KEY_DATA

sql.postgres.messages.BACKEND_KEY_DATA = 'K'

BIND_COMPLETE

sql.postgres.messages.BIND_COMPLETE = '2'

CLOSE_COMPLETE

sql.postgres.messages.CLOSE_COMPLETE = '3'

COMMAND_COMPLETE

sql.postgres.messages.COMMAND_COMPLETE = 'C'

COPY_IN_RESPONSE

sql.postgres.messages.COPY_IN_RESPONSE = 'G'

COPY_OUT_RESPONSE

sql.postgres.messages.COPY_OUT_RESPONSE = 'H'

COPY_DATA

sql.postgres.messages.COPY_DATA = 'd'

COPY_DONE

sql.postgres.messages.COPY_DONE = 'c'

DATA_ROW

sql.postgres.messages.DATA_ROW = 'D'

EMPTY_QUERY_RESPONSE

sql.postgres.messages.EMPTY_QUERY_RESPONSE = 'I'

ERROR_RESPONSE

sql.postgres.messages.ERROR_RESPONSE = 'E'

NO_DATA

sql.postgres.messages.NO_DATA = 'n'

NOTICE_RESPONSE

sql.postgres.messages.NOTICE_RESPONSE = 'N'

NOTIFICATION_RESPONSE

sql.postgres.messages.NOTIFICATION_RESPONSE = 'A'

PARAMETER_DESCRIPTION

sql.postgres.messages.PARAMETER_DESCRIPTION = 't'

PARAMETER_STATUS

sql.postgres.messages.PARAMETER_STATUS = 'S'

PARSE_COMPLETE

sql.postgres.messages.PARSE_COMPLETE = '1'

PORTAL_SUSPENDED

sql.postgres.messages.PORTAL_SUSPENDED = 's'

READY_FOR_QUERY

sql.postgres.messages.READY_FOR_QUERY = 'Z'

ROW_DESCRIPTION

sql.postgres.messages.ROW_DESCRIPTION = 'T'

AUTH_OK

sql.postgres.messages.AUTH_OK = 0

Authentication requests, by the number that follows the tag.

AUTH_CLEARTEXT

sql.postgres.messages.AUTH_CLEARTEXT = 3

AUTH_MD5

sql.postgres.messages.AUTH_MD5 = 5

AUTH_SASL

sql.postgres.messages.AUTH_SASL = 10

AUTH_SASL_CONTINUE

sql.postgres.messages.AUTH_SASL_CONTINUE = 11

AUTH_SASL_FINAL

sql.postgres.messages.AUTH_SASL_FINAL = 12

PROTOCOL_VERSION

sql.postgres.messages.PROTOCOL_VERSION = 196608

The protocol version this adapter speaks: 3.0, as a single number with the major version in the high half.

SSL_REQUEST

sql.postgres.messages.SSL_REQUEST = 80877103

The number the server recognises as a request to start TLS. It takes the place of a protocol version in a startup-shaped message.

Functions

read_cstring()

sql.postgres.messages.read_cstring(payload, at: number) -> dict

Splits a run of zero-terminated strings.

Several messages are built this way, including the error report, where each field is a one byte code followed by its text.

Parameters

  • payload (bytes)
  • at (number) — Where to start.

Returns dict — { value, next }

Classes

Writer

class sql.postgres.messages.Writer

Builds one outgoing message.

Bytes accumulate in a list and frame() puts the tag and length on the front, since the length cannot be known until the body is finished.

Writer.byte()

sql.postgres.messages.Writer.byte(value: number) -> Writer

Appends one byte.

Parameters

  • value (number)

Returns Writer — This writer, so calls chain.

Writer.int16()

sql.postgres.messages.Writer.int16(value: number) -> Writer

Appends a big-endian 16 bit integer.

Parameters

  • value (number)

Returns Writer

Writer.int32()

sql.postgres.messages.Writer.int32(value: number) -> Writer

Appends a big-endian 32 bit integer.

Parameters

  • value (number)

Returns Writer

Writer.cstring()

sql.postgres.messages.Writer.cstring(value: string) -> Writer

Appends a string and the zero byte that ends it.

Parameters

  • value (string)

Returns Writer

Writer.raw()

sql.postgres.messages.Writer.raw(values: list) -> Writer

Appends raw bytes.

Parameters

  • values (list)

Returns Writer

Writer.length()

sql.postgres.messages.Writer.length() -> number

How many bytes the body holds so far.

Returns number

Writer.frame()

sql.postgres.messages.Writer.frame(tag) -> bytes

The finished message, ready to send.

Parameters

  • tag (string|nil) — The message’s tag, or nil for a startup message, which has none.

Returns bytes

Reader

class sql.postgres.messages.Reader

Reads framed messages from a connected stream.

Works over a plain TcpStream or a TlsStream without caring which, since both read the same way.

Constructor

sql.postgres.messages.Reader(stream)

Parameters

  • stream (TcpStream|TlsStream) — An already-connected stream.

Reader.upgrade()

sql.postgres.messages.Reader.upgrade(stream)

Swaps the stream, for the point in the handshake where a plain connection becomes a TLS one.

Parameters

  • stream (TlsStream)

Reader.read_exact()

sql.postgres.messages.Reader.read_exact(count: number) -> bytes

Reads exactly count bytes, waiting for as many as it takes.

Parameters

  • count (number)

Returns bytes

Raises ConnectionError if the server closes first.

Reader.read_message()

sql.postgres.messages.Reader.read_message() -> dict

Reads the next message.

Returns dict — { tag, payload }

2026, Richard Ore and Zuri contributors