5.2 Tuple Structure

Heap tuples in table pages are categorized into two types: standard data tuples and TOAST tuples. This section describes the structure of standard data tuples.

A heap tuple comprises three parts: the HeapTupleHeaderData structure defined in htup_details.h, a NULL bitmap, and the user data (Figure 5.2).

The HeapTupleHeaderData and related structures are shown below:

typedef struct HeapTupleFields
{
        TransactionId t_xmin;		   /* inserting xact ID */
        TransactionId t_xmax;              /* deleting or locking xact ID */

        union
        {
                CommandId       t_cid;     /* inserting or deleting command ID, or both */
                TransactionId 	t_xvac;    /* old-style VACUUM FULL xact ID */
        } t_field3;
} HeapTupleFields;

typedef struct DatumTupleFields
{
        int32          datum_len_;          /* varlena header (do not touch directly!) */
        int32          datum_typmod;   	    /* -1, or identifier of a record type */
        Oid            datum_typeid;   	    /* composite type OID, or RECORDOID */

        /*
         * Note: field ordering is chosen with thought that Oid might someday
         * widen to 64 bits.
         */
} DatumTupleFields;

typedef struct HeapTupleHeaderData
{
        union
        {
                HeapTupleFields t_heap;
                DatumTupleFields t_datum;
        } t_choice;

        ItemPointerData t_ctid;         /* current TID of this or newer tuple */

        /* Fields below here must match MinimalTupleData! */
        uint16          t_infomask2;    /* number of attributes + various flags */
        uint16          t_infomask;     /* various flag bits, see below */
        uint8           t_hoff;         /* sizeof header incl. bitmap, padding */
        /* ^ - 23 bytes - ^ */
        bits8           t_bits[1];      /* bitmap of NULLs -- VARIABLE LENGTH */

        /* MORE DATA FOLLOWS AT END OF STRUCT */
} HeapTupleHeaderData;

typedef HeapTupleHeaderData *HeapTupleHeader;

While the HeapTupleHeaderData structure contains several fields, the following four are essential for understanding concurrency control:

t_xmin: Stores the txid of the transaction that inserted the tuple.
t_xmax: Stores the txid of the transaction that deleted or updated the tuple. If the tuple has not been deleted or updated, t_xmax is set to 0 (Invalid).
t_cid: Stores the command ID (cid), representing the number of SQL commands executed before the current command within the same transaction, starting from 0.
For example, in a transaction block containing three INSERT commands: ‘BEGIN;INSERT;INSERT;INSERT;COMMIT’, the tuple inserted by the first command has a t_cid of 0, the second a t_cid of 1, and the third a t_cid of 2.
t_ctid: Stores the tuple identifier (tid), which points either to the tuple itself or to a newer version. As described in Section 1.3, the tid identifies a tuple’s physical location within a table.
When a tuple is updated, its t_ctid is updated to point to the new version of the tuple; otherwise, it points to itself.

5.2 Tuple Structure

Figure 5.2. Tuple structure.