Practical PostgreSQL

Tuples

The structure of tuples within the binary file is as follows: a 16-bit integer count of the fields within the tuple (this is the same within every tuple), a 16-bit integer typlen word, and the field data for each field. The available options for the typlen field are as follow:

0

NULL; this field contains no data.

>0

A fixed-length data type. The specified number bytes of data follow the typlen word.

-1

A varlena data type. The next four bytes are the varlena header, consisting of the value’s total length (including the length of the header).

<-1

Reserved for possible future use.

To create a convenient way for an application reading this format to check the integrity of incoming binary data, all non-NULL fields have a typlen value, which can be compared against the typlen of the destination column before attempting to insert or update data within PostgreSQL.

A few formatting options were left un-implemented to improve the portability of binary file dumps. Primarily, extra data between fields is not possible (e.g., alignment padding), and there is no distinguishment between data types based on passes by reference, or passes by value.

If OIDs are included in a PostgreSQL binary file, they immediately follow the field count word. OIDs are not included in the field count.