protocol

Documentation

Index

• Constants
• Variables
• type Message
  • func BackendKeyData(pid int32, secret int32) Message
  • func CommandComplete(tag string) Message
  • func DataRow(vals []string) Message
  • func ErrorResponse(err error) Message
  • func ParameterStatus(name, value string) Message
  • func RowDescription(cols, types []string) Message
  • func TLSResponse(supported bool) Message
  • func (m Message) CancelKeyData() (int32, int32, error)
  • func (m *Message) CreatesTransaction() bool
  • func (m *Message) EndsTransaction() bool
  • func (m Message) IsCancel() bool
  • func (m Message) IsTLSRequest() bool
  • func (m Message) IsTerminate() bool
  • func (m Message) QueryText() (string, error)
  • func (m Message) StartupArgs() (map[string]interface{}, error)
  • func (m Message) StartupVersion() (string, error)
  • func (m Message) Type() byte
• type MessageReadWriter
• type Transport
  • func NewTransport(r io.Reader, w io.Writer) *Transport
  • func (t *Transport) NextMessage() (msg Message, err error)
  • func (t *Transport) Read() (Message, error)
  • func (t *Transport) StartUp() (Message, error)
  • func (t *Transport) Write(m Message) error

Constants

const (
	Query     = 'Q'
	Terminate = 'X'
	Parse     = 'P'
	Bind      = 'B'
	Describe  = 'D'
	Execute   = 'E'
	Sync      = 'S'
)

frontend message types

Variables

var BindComplete = []byte{'2', 0, 0, 0, 4}

BindComplete is sent when backend prepared a portal and finished planning the query

var ParseComplete = []byte{'1', 0, 0, 0, 4}

ParseComplete is sent when backend parsed a prepared statement successfully

var ReadyForQuery = []byte{'Z', 0, 0, 0, 5, 'I'}

ReadyForQuery is sent whenever the backend is ready for a new query cycle.

var TypesOid = map[string]int{
	"BOOL":       16,
	"BYTEA":      17,
	"CHAR":       18,
	"INT8":       20,
	"INT2":       21,
	"INT4":       23,
	"TEXT":       25,
	"JSON":       114,
	"XML":        142,
	"FLOAT4":     700,
	"FLOAT8":     701,
	"VARCHAR":    1043,
	"DATE":       1082,
	"TIME":       1083,
	"TIMESTAMP":  1114,
	"TIMESTAMPZ": 1184,
	"INTERVAL":   1186,
	"NUMERIC":    1700,
	"JSONB":      3802,
	"ANY":        2276,
}

TypesOid maps between a type name to its corresponding OID

Types

type Message

type Message []byte

Message is just an alias for a slice of bytes that exposes common operations on Postgres' client-server protocol messages. see: https://www.postgresql.org/docs/current/protocol-message-formats.html for postgres specific list of message formats

func BackendKeyData

func BackendKeyData(pid int32, secret int32) Message

BackendKeyData creates a new message providing the client with a process ID and secret key that it can later use to cancel running queries

func CommandComplete

func CommandComplete(tag string) Message

CommandComplete is sent when query was fully executed and cursor reached the end of the row set

func DataRow

func DataRow(vals []string) Message

DataRow is sent for every row of resulted row set

func ErrorResponse

func ErrorResponse(err error) Message

ErrorResponse is sent whenever error has occurred

func ParameterStatus

func ParameterStatus(name, value string) Message

ParameterStatus creates a new message providing parameter name and value

func RowDescription

func RowDescription(cols, types []string) Message

RowDescription is a message indicating that DataRow messages are about to be transmitted and delivers their schema (column names/types)

func TLSResponse

func TLSResponse(supported bool) Message

TLSResponse creates a new single byte message indicating if the server supports TLS or not. If it does, the client must immediately proceed to initiate the TLS handshake

func (Message) CancelKeyData

func (m Message) CancelKeyData() (int32, int32, error)

CancelKeyData returns the key data of a cancel message

func (*Message) CreatesTransaction

func (m *Message) CreatesTransaction() bool

CreatesTransaction tells weather this is a frontend message that should start/continue a transaction

func (*Message) EndsTransaction

func (m *Message) EndsTransaction() bool

EndsTransaction tells weather this is a frontend message that should end the current transaction

func (Message) IsCancel

func (m Message) IsCancel() bool

IsCancel returns whether the message is a cancel message or not

func (Message) IsTLSRequest

func (m Message) IsTLSRequest() bool

IsTLSRequest determines if this startup message is actually a request to open a TLS connection, in which case the version number is a special, predefined value of "1234.5679"

func (Message) IsTerminate

func (m Message) IsTerminate() bool

IsTerminate determines if the current message is a notification that the client has terminated the connection upon user-request.

func (Message) QueryText

func (m Message) QueryText() (string, error)

QueryText returns the SQL query string from a Query or Parse message

func (Message) StartupArgs

func (m Message) StartupArgs() (map[string]interface{}, error)

StartupArgs parses the arguments delivered in the Startup and returns them as a key-value map. Startup messages contains a map of arguments, like the requested database name, user name, charset and additional connection defaults that may be used by the server. These arguments are encoded as pairs of key-values, terminated by a NULL character.

func (Message) StartupVersion

func (m Message) StartupVersion() (string, error)

StartupVersion returns the protocol version supported by the client. The version is encoded by two consecutive 2-byte integers, one for the major version, and the other for the minor version. Currently version 3.0 is the only valid version.

func (Message) Type

func (m Message) Type() byte

Type returns a string (single-char) representing the message type. The full list of available types is available in the aforementioned documentation.

type MessageReadWriter

type MessageReadWriter interface {
	Write(m Message) error
	Read() (Message, error)
}

MessageReadWriter describes objects that handle client-server communication. Objects implementing this interface are used by logic operations to send Message objects to frontend and receive Message back from it

type Transport

type Transport struct {
	R io.Reader
	W io.Writer
	// contains filtered or unexported fields
}

Transport manages the underlying wire protocol between backend and frontend.

func NewTransport

func NewTransport(r io.Reader, w io.Writer) *Transport

NewTransport creates a protocol

func (*Transport) NextMessage

func (t *Transport) NextMessage() (msg Message, err error)

NextMessage reads and returns a single message from the connection when available. if within a transaction, the transaction will read from the connection, otherwise a ReadyForQuery message will first be sent to the frontend and then reading a single message from the connection will happen

NextMessage expects to be called only after a call to StartUp without an error response otherwise, an error is returned

func (*Transport) Read

func (t *Transport) Read() (Message, error)

Read reads and returns a single message from the connection.

func (*Transport) StartUp

func (t *Transport) StartUp() (Message, error)

StartUp handles the very first messages exchange between frontend and backend of new session

func (*Transport) Write

func (t *Transport) Write(m Message) error

Write writes the provided message to the client connection