Encoders for the messages a client sends to a PostgreSQL server.

Internal to minato. The supported surface is minato_protocol.

Shape

Every message but three is a type byte, a 32 bit length and a payload. The length counts itself and the payload but not the type byte, which is why every encoder here adds four to the payload size.

StartupMessage, SSLRequest and CancelRequest carry no type byte, because they are sent before the connection has agreed what version of the protocol it is speaking. A server tells them apart by the 32 bit code that follows the length: 196608 for protocol 3.0, 80877103 to ask for TLS, and 80877102 to cancel a query on another connection.

Payloads

Strings are null terminated. Counted sequences carry a 16 bit count first. Parameter values in Bind carry a 32 bit length each, and a length of -1 is NULL, which is why null is a parameter value rather than an empty binary. The SASL data in SASLInitialResponse is written the same way, and -1 there means the mechanism sent no data at all.

Format codes are 0 for text and 1 for binary. Bind takes them as lists, and the protocol reads the length of those lists: an empty list means every value is text, a single element applies to every value, and any other length has to match the number of values.

What is not enforced

An encoder writes the message it is given. It does not check that StartupMessage names a user, that a Bind has as many parameters as the statement was parsed with, or that a portal exists. Those belong to whatever drives the exchange, which knows the session; this module only knows bytes.