odyssey/POSTGRESQL_PROTOCOL.md

PostgreSQL protocol 3.0 cheatsheet
----------------------------------

startup packet

	u32 len  # len including len
	data[]

header

	u8  type # readable char
	u32 len  # len including len
	data[]

Message flow
------------

STARTUP

	C: SSLRequest
	S: # one byte: 'S', 'N'
	S: 'S' # proceed with SSL
	S: 'N' # not supported
		- maybe close connection

	C: StartupMessage # or CancelRequest
	# { len, version: 0x30000, user...database...options..}

	S: # AUTH require message
	S: AuthenticationClearTextPassword # {'R', 8, 3 }
	C: PasswordMessage # { 'p', len, data }

	S: ErrorResponse # { 'E', len, 'S' ... ,  } 
		- close connection
	S: AuthenticationOk # {'R', 8, 0 }

	# new backend created; server tries to apply startup options
	S: ErrorResponse
		- close connection
	
	S: BackendKeyData # { 'K', 12, u32 pid, u32 key }
		- cancel key

	S: ParameterStatus # { 'S', len, name, value }
		- client_encoding, etc...

	S: NoticeResponse # { 'N', len, ... } same as error
		- just print the message
	
	S: ReadyForQuery # { 'Z', 5, tx }  tx: 'I' inactive, 'T' in tx, 'E' cancelled tx

TERMINATE

	C: Terminate # { 'F', 4 }
		- no wait, close connection

CANCEL

	# new connection required*
	# no reply from server*
	C: CancelRequest # { 16, 80877102, pid, key }

QUERY

	C: Query # { 'Q', len, text }

	S: RowDescription
	S: DataRow
	S: CommandComplete #  can be several

	#  can be repeated several time for reach stmt;stmt

	S: EmptyQueryResponse # in case if text=""
	S: NoticeResponse
	S: ErrorResponse

	# all text stmts processed, ready for next command
	S: ReadyForQuery

EXTENDED QUERY

	C: Parse # { 'P', len, operator_name, query, u16 types_count, ... u32 type }
             #                can be 0                 can be 0         can be 0
             #
             # Parse can have only one query, no ';'.
             #
             # Nameless operator exists till next query.
             #
             # Named operator exists till end of a session, or explicitly destroyed.
             # Named operator available for SQL Prepare and Execute calls.

	S: ParseComplete # { '1', len }
	S: ErrorResponse

	C: Bind # { 'B', len, portal_name, operator_name,
            #	   16  argc_call_arg_types_count, u16[] types,
            #                                   0 or 1
            #    u16 argc, [ i32 len,  bytes],
            #
            #    u16 argc_result_cols_types_count, u16[] types }
            #
            # Named/Nameless Portal exists till transaction ends
            #
            # Named portal avail for SQL Declare, Cursor, Fetch

	S: BindComplete # { '2', len }

	C: Describe # { 'D', len, u8 'S'/'P', operator_or_portal_name }
	C: Execute # { 'E', len, portal_name, u32 limit } 0 - limitless

	S: PortalSuspended # { 's', len }   on execute limit reach

	S: NoData  # { 'n', len } on Describe, when portal has no query
	S: RowDescription  # answer for Describe
	S: DataRow

	S: CommandComplete
	S: EmptyQueryResponse
	S: ErrorResponse # Skips all commands till Sync

	C: Close # { 'C', len, u8 'S'/'P', operator_or_portal }
	C: Sync  # { 'S', len }

	S: ReadyForQuery

FUNCTION CALL
COPY
ASYNC