src/include/access/tupdesc.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * tupdesc.h
   4  *        POSTGRES tuple descriptor definitions.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * src/include/access/tupdesc.h
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef TUPDESC_H
  15 #define TUPDESC_H
  16
  17 #include "access/attnum.h"
  18 #include "catalog/pg_attribute.h"
  19 #include "nodes/pg_list.h"
  20
  21
  22 typedef struct AttrDefault
  23 {
  24         AttrNumber      adnum;
  25         char       *adbin;                      /* nodeToString representation of expr */
  26 } AttrDefault;
  27
  28 typedef struct ConstrCheck
  29 {
  30         char       *ccname;
  31         char       *ccbin;                      /* nodeToString representation of expr */
  32         bool            ccvalid;
  33         bool            ccnoinherit;    /* this is a non-inheritable constraint */
  34 } ConstrCheck;
  35
  36 /* This structure contains constraints of a tuple */
  37 typedef struct TupleConstr
  38 {
  39         AttrDefault *defval;            /* array */
  40         ConstrCheck *check;                     /* array */
  41         struct AttrMissing *missing;    /* missing attributes values, NULL if none */
  42         uint16          num_defval;
  43         uint16          num_check;
  44         bool            has_not_null;
  45         bool            has_generated_stored;
  46 } TupleConstr;
  47
  48 /*
  49  * CompactAttribute
  50  *              Cut-down version of FormData_pg_attribute for faster access for tasks
  51  *              such as tuple deformation.  The fields of this struct are populated
  52  *              using the populate_compact_attribute() function, which must be called
  53  *              directly after the FormData_pg_attribute struct is populated or
  54  *              altered in any way.
  55  *
  56  * Currently, this struct is 16 bytes.  Any code changes which enlarge this
  57  * struct should be considered very carefully.
  58  *
  59  * Code which must access a TupleDesc's attribute data should always make use
  60  * the fields of this struct when required fields are available here.  It's
  61  * more efficient to access the memory in CompactAttribute due to it being a
  62  * more compact representation of FormData_pg_attribute and also because
  63  * accessing the FormData_pg_attribute requires an additional calculations to
  64  * obtain the base address of the array within the TupleDesc.
  65  */
  66 typedef struct CompactAttribute
  67 {
  68         int32           attcacheoff;    /* fixed offset into tuple, if known, or -1 */
  69         int16           attlen;                 /* attr len in bytes or -1 = varlen, -2 =
  70                                                                  * cstring */
  71         bool            attbyval;               /* as FormData_pg_attribute.attbyval */
  72         bool            attispackable;  /* FormData_pg_attribute.attstorage !=
  73                                                                  * TYPSTORAGE_PLAIN */
  74         bool            atthasmissing;  /* as FormData_pg_attribute.atthasmissing */
  75         bool            attisdropped;   /* as FormData_pg_attribute.attisdropped */
  76         bool            attgenerated;   /* FormData_pg_attribute.attgenerated != '\0' */
  77         bool            attnotnull;             /* as FormData_pg_attribute.attnotnull */
  78         uint8           attalignby;             /* alignment requirement in bytes */
  79 } CompactAttribute;
  80
  81 /*
  82  * This struct is passed around within the backend to describe the structure
  83  * of tuples.  For tuples coming from on-disk relations, the information is
  84  * collected from the pg_attribute, pg_attrdef, and pg_constraint catalogs.
  85  * Transient row types (such as the result of a join query) have anonymous
  86  * TupleDesc structs that generally omit any constraint info; therefore the
  87  * structure is designed to let the constraints be omitted efficiently.
  88  *
  89  * Note that only user attributes, not system attributes, are mentioned in
  90  * TupleDesc.
  91  *
  92  * If the tupdesc is known to correspond to a named rowtype (such as a table's
  93  * rowtype) then tdtypeid identifies that type and tdtypmod is -1.  Otherwise
  94  * tdtypeid is RECORDOID, and tdtypmod can be either -1 for a fully anonymous
  95  * row type, or a value >= 0 to allow the rowtype to be looked up in the
  96  * typcache.c type cache.
  97  *
  98  * Note that tdtypeid is never the OID of a domain over composite, even if
  99  * we are dealing with values that are known (at some higher level) to be of
 100  * a domain-over-composite type.  This is because tdtypeid/tdtypmod need to
 101  * match up with the type labeling of composite Datums, and those are never
 102  * explicitly marked as being of a domain type, either.
 103  *
 104  * Tuple descriptors that live in caches (relcache or typcache, at present)
 105  * are reference-counted: they can be deleted when their reference count goes
 106  * to zero.  Tuple descriptors created by the executor need no reference
 107  * counting, however: they are simply created in the appropriate memory
 108  * context and go away when the context is freed.  We set the tdrefcount
 109  * field of such a descriptor to -1, while reference-counted descriptors
 110  * always have tdrefcount >= 0.
 111  *
 112  * Beyond the compact_attrs variable length array, the TupleDesc stores an
 113  * array of FormData_pg_attribute.  The TupleDescAttr() function, as defined
 114  * below, takes care of calculating the address of the elements of the
 115  * FormData_pg_attribute array.
 116  *
 117  * The array of CompactAttribute is effectively an abbreviated version of the
 118  * array of FormData_pg_attribute.  Because CompactAttribute is significantly
 119  * smaller than FormData_pg_attribute, code, especially performance-critical
 120  * code, should prioritize using the fields from the CompactAttribute over the
 121  * equivalent fields in FormData_pg_attribute.
 122  *
 123  * Any code making changes manually to and fields in the FormData_pg_attribute
 124  * array must subsequently call populate_compact_attribute() to flush the
 125  * changes out to the corresponding 'compact_attrs' element.
 126  */
 127 typedef struct TupleDescData
 128 {
 129         int                     natts;                  /* number of attributes in the tuple */
 130         Oid                     tdtypeid;               /* composite type ID for tuple type */
 131         int32           tdtypmod;               /* typmod for tuple type */
 132         int                     tdrefcount;             /* reference count, or -1 if not counting */
 133         TupleConstr *constr;            /* constraints, or NULL if none */
 134         /* compact_attrs[N] is the compact metadata of Attribute Number N+1 */
 135         CompactAttribute compact_attrs[FLEXIBLE_ARRAY_MEMBER];
 136 }                       TupleDescData;
 137 typedef struct TupleDescData *TupleDesc;
 138
 139 extern void populate_compact_attribute(TupleDesc tupdesc, int attnum);
 140
 141 /*
 142  * Calculates the base address of the Form_pg_attribute at the end of the
 143  * TupleDescData struct.
 144  */
 145 #define TupleDescAttrAddress(desc) \
 146         (Form_pg_attribute) ((char *) (desc) + \
 147          (offsetof(struct TupleDescData, compact_attrs) + \
 148          (desc)->natts * sizeof(CompactAttribute)))
 149
 150 /* Accessor for the i'th FormData_pg_attribute element of tupdesc. */
 151 static inline FormData_pg_attribute *
 152 TupleDescAttr(TupleDesc tupdesc, int i)
 153 {
 154         FormData_pg_attribute *attrs = TupleDescAttrAddress(tupdesc);
 155
 156         return &attrs[i];
 157 }
 158
 159 #undef TupleDescAttrAddress
 160
 161 #ifdef USE_ASSERT_CHECKING
 162 extern void verify_compact_attribute(TupleDesc, int attnum);
 163 #endif
 164
 165 /*
 166  * Accessor for the i'th CompactAttribute element of tupdesc.
 167  */
 168 static inline CompactAttribute *
 169 TupleDescCompactAttr(TupleDesc tupdesc, int i)
 170 {
 171         CompactAttribute *cattr = &tupdesc->compact_attrs[i];
 172
 173 #ifdef USE_ASSERT_CHECKING
 174
 175         /* Check that the CompactAttribute is correctly populated */
 176         verify_compact_attribute(tupdesc, i);
 177 #endif
 178
 179         return cattr;
 180 }
 181
 182 extern TupleDesc CreateTemplateTupleDesc(int natts);
 183
 184 extern TupleDesc CreateTupleDesc(int natts, Form_pg_attribute *attrs);
 185
 186 extern TupleDesc CreateTupleDescCopy(TupleDesc tupdesc);
 187
 188 extern TupleDesc CreateTupleDescTruncatedCopy(TupleDesc tupdesc, int natts);
 189
 190 extern TupleDesc CreateTupleDescCopyConstr(TupleDesc tupdesc);
 191
 192 #define TupleDescSize(src) \
 193         (offsetof(struct TupleDescData, compact_attrs) + \
 194          (src)->natts * sizeof(CompactAttribute) + \
 195          (src)->natts * sizeof(FormData_pg_attribute))
 196
 197 extern void TupleDescCopy(TupleDesc dst, TupleDesc src);
 198
 199 extern void TupleDescCopyEntry(TupleDesc dst, AttrNumber dstAttno,
 200                                                            TupleDesc src, AttrNumber srcAttno);
 201
 202 extern void FreeTupleDesc(TupleDesc tupdesc);
 203
 204 extern void IncrTupleDescRefCount(TupleDesc tupdesc);
 205 extern void DecrTupleDescRefCount(TupleDesc tupdesc);
 206
 207 #define PinTupleDesc(tupdesc) \
 208         do { \
 209                 if ((tupdesc)->tdrefcount >= 0) \
 210                         IncrTupleDescRefCount(tupdesc); \
 211         } while (0)
 212
 213 #define ReleaseTupleDesc(tupdesc) \
 214         do { \
 215                 if ((tupdesc)->tdrefcount >= 0) \
 216                         DecrTupleDescRefCount(tupdesc); \
 217         } while (0)
 218
 219 extern bool equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2);
 220 extern bool equalRowTypes(TupleDesc tupdesc1, TupleDesc tupdesc2);
 221 extern uint32 hashRowType(TupleDesc desc);
 222
 223 extern void TupleDescInitEntry(TupleDesc desc,
 224                                                            AttrNumber attributeNumber,
 225                                                            const char *attributeName,
 226                                                            Oid oidtypeid,
 227                                                            int32 typmod,
 228                                                            int attdim);
 229
 230 extern void TupleDescInitBuiltinEntry(TupleDesc desc,
 231                                                                           AttrNumber attributeNumber,
 232                                                                           const char *attributeName,
 233                                                                           Oid oidtypeid,
 234                                                                           int32 typmod,
 235                                                                           int attdim);
 236
 237 extern void TupleDescInitEntryCollation(TupleDesc desc,
 238                                                                                 AttrNumber attributeNumber,
 239                                                                                 Oid collationid);
 240
 241 extern TupleDesc BuildDescFromLists(const List *names, const List *types, const List *typmods, const List *collations);
 242
 243 extern Node *TupleDescGetDefault(TupleDesc tupdesc, AttrNumber attnum);
 244
 245 #endif                                                  /* TUPDESC_H */