protocol

Documentation

Index

• Constants
• Variables
• type Handshake
  • func NewHandshake(rw io.ReadWriter) *Handshake
  • func (h *Handshake) Init() (res Message, err error)
  • func (h *Handshake) Read() (Message, error)
  • func (h *Handshake) Write(m Message) error
• 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 ParameterDescription(ps *nodes.PrepareStmt) (Message, error)
  • 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) ErrorResponse() (res *pgproto3.ErrorResponse, err error)
  • func (m Message) IsCancel() bool
  • func (m Message) IsError() bool
  • func (m Message) IsTLSRequest() bool
  • func (m Message) IsTerminate() bool
  • func (m Message) StartupArgs() (map[string]interface{}, error)
  • func (m Message) StartupVersion() (string, error)
  • func (m Message) Type() byte
• type MessageReadWriter
• type TransactionState
• type Transport
  • func NewTransport(rw io.ReadWriter) *Transport
  • func (t *Transport) NextFrontendMessage() (msg pgproto3.FrontendMessage, ts TransactionState, err error)
  • func (t *Transport) Write(m Message) error

Constants

const (
	DescribeStatement = 'S'
	DescribePortal    = 'P'
)

Describe message object types

const (
	Terminate = 'X'
)

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 Handshake

type Handshake struct {
	// contains filtered or unexported fields
}

Handshake handles the very first message passing of the protocol

func NewHandshake

func NewHandshake(rw io.ReadWriter) *Handshake

NewHandshake crates an Handshake

func (*Handshake) Init

func (h *Handshake) Init() (res Message, err error)

Init receives and validates the very first message from the frontend per session. it may send message back to the frontend if needed to skip SSL request since it currently not supported.

once done, Init must not be called again, or error will be returned.

func (*Handshake) Read

func (h *Handshake) Read() (Message, error)

Read implements MessageReadWriter

func (*Handshake) Write

func (h *Handshake) Write(m Message) error

Write implements MessageReadWriter

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 ParameterDescription

func ParameterDescription(ps *nodes.PrepareStmt) (Message, error)

ParameterDescription is sent when backend received Describe message from frontend with ObjectType = 'S' - requesting to describe prepared statement with a provided name

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) ErrorResponse

func (m Message) ErrorResponse() (res *pgproto3.ErrorResponse, err error)

ErrorResponse parses message of type error and returns an object describes it

func (Message) IsCancel

func (m Message) IsCancel() bool

IsCancel returns whether the message is a cancel message or not

func (Message) IsError

func (m Message) IsError() bool

IsError determines if the message is an ErrorResponse

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) 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 TransactionState

type TransactionState int

TransactionState is used as a return with every message read for commit and rollback implementation

const (
	// TransactionUnknown is the default/unset value of this enum
	TransactionUnknown TransactionState = iota
	// NotInTransaction states that transaction is not active and operations should auto-commit
	NotInTransaction
	// InTransaction states that transaction is active and operations should not commit
	InTransaction
	// TransactionEnded states that the current transaction has finished and has to commit
	TransactionEnded
	// TransactionFailed states that the current transaction has failed and has to roll-back
	TransactionFailed
)

type Transport

type Transport struct {
	// contains filtered or unexported fields
}

Transport manages the underlying wire protocol between backend and frontend.

func NewTransport

func NewTransport(rw io.ReadWriter) *Transport

NewTransport creates a Transport

func (*Transport) NextFrontendMessage

func (t *Transport) NextFrontendMessage() (msg pgproto3.FrontendMessage, ts TransactionState, err error)

NextFrontendMessage 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

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

func (*Transport) Write

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

Write writes the provided message to the client connection