Erlang terms to PostgreSQL wire bytes and back, for both the binary and the text wire format.

This module is pure. It does no I/O, starts no process, reads no ETS table and keeps no state, so a codec can be tested exhaustively without a database and reused wherever the bytes come from.

The two formats

PostgreSQL will send and accept every value in either a binary or a text representation, chosen per parameter and per result column. minato implements both. Binary is what the protocol layer asks for on the types it knows; text is what makes an unknown type still usable, because any value at all can be carried as its text representation.

preferred_format/1 says which format to request for a given OID.

NULL

null is the NULL sentinel in both directions, and it is the only one.

NULL is not a value in the wire format: it is a length of -1 where the bytes would be. encode/4 therefore returns the atom null rather than iodata() when the value is null, and the caller writing the message body turns that into a length of -1. decode/4 accepts null in the same place and returns null.

Errors

Every function in this module either returns a value or raises. A codec failure is error({minato_codec, Report}), where Report is a map with type, reason and value keys.

Raising rather than returning {error, _} is deliberate: decoding a result set calls decode/4 once per cell, and a failure there means the bytes disagree with the OID the server itself announced, which is a bug and not a condition to branch on. One try around a whole row costs nothing, a tagged tuple per cell does.

Options

#{uuid_format => string | binary,
  datetime_format => datetime | microseconds,
  numeric_format => binary | float}

All three are decode-time options; encoding accepts every form regardless.

• numeric_format defaults to binary, giving the exact decimal text PostgreSQL sent. float converts it, which loses exactness and is the right answer for an average or a ratio and the wrong one for money. A client that did this by default would be quietly lossy about the one type chosen for not being lossy, which is why it has to be asked for.
• uuid_format defaults to string, giving the 36 character hyphenated form. binary gives the 16 raw bytes.
• datetime_format defaults to datetime, giving {Hour, Minute, Second} and {{Year, Month, Day}, {Hour, Minute, Second}} tuples with sub-second precision discarded. microseconds is lossless and gives integers. See minato_codec_datetime for exactly how the two differ.

Types covered

bool, bytea, int2, int4, int8, float4, float8, numeric, text, varchar, json, jsonb, uuid, date, time, timestamp, timestamptz, and the array type of each of them.

Examples

1> minato_codec:encode(23, 42, binary).
<<0,0,0,42>>
2> minato_codec:decode(23, <<0,0,0,42>>, binary).
42
3> minato_codec:decode(1009, ~"{a,NULL,\"b,c\"}", text).
[<<"a">>,null,<<"b,c">>]
4> minato_codec:encode(2950, ~"0196f0a9-1c4f-7e21-9b3a-6d2c5e8f1a44", binary).
<<1,150,240,169,28,79,126,33,155,58,109,44,94,143,26,68>>