src/include/access/reloptions.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * reloptions.h
   4  *        Core support for relation and tablespace options (pg_class.reloptions
   5  *        and pg_tablespace.spcoptions)
   6  *
   7  * Note: the functions dealing with text-array reloptions values declare
   8  * them as Datum, not ArrayType *, to avoid needing to include array.h
   9  * into a lot of low-level code.
  10  *
  11  *
  12  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
  13  * Portions Copyright (c) 1994, Regents of the University of California
  14  *
  15  * src/include/access/reloptions.h
  16  *
  17  *-------------------------------------------------------------------------
  18  */
  19 #ifndef RELOPTIONS_H
  20 #define RELOPTIONS_H
  21
  22 #include "access/amapi.h"
  23 #include "access/htup.h"
  24 #include "access/tupdesc.h"
  25 #include "nodes/pg_list.h"
  26 #include "storage/lock.h"
  27
  28 /* types supported by reloptions */
  29 typedef enum relopt_type
  30 {
  31         RELOPT_TYPE_BOOL,
  32         RELOPT_TYPE_INT,
  33         RELOPT_TYPE_REAL,
  34         RELOPT_TYPE_ENUM,
  35         RELOPT_TYPE_STRING,
  36 } relopt_type;
  37
  38 /* kinds supported by reloptions */
  39 typedef enum relopt_kind
  40 {
  41         RELOPT_KIND_LOCAL = 0,
  42         RELOPT_KIND_HEAP = (1 << 0),
  43         RELOPT_KIND_TOAST = (1 << 1),
  44         RELOPT_KIND_BTREE = (1 << 2),
  45         RELOPT_KIND_HASH = (1 << 3),
  46         RELOPT_KIND_GIN = (1 << 4),
  47         RELOPT_KIND_GIST = (1 << 5),
  48         RELOPT_KIND_ATTRIBUTE = (1 << 6),
  49         RELOPT_KIND_TABLESPACE = (1 << 7),
  50         RELOPT_KIND_SPGIST = (1 << 8),
  51         RELOPT_KIND_VIEW = (1 << 9),
  52         RELOPT_KIND_BRIN = (1 << 10),
  53         RELOPT_KIND_PARTITIONED = (1 << 11),
  54         /* if you add a new kind, make sure you update "last_default" too */
  55         RELOPT_KIND_LAST_DEFAULT = RELOPT_KIND_PARTITIONED,
  56         /* some compilers treat enums as signed ints, so we can't use 1 << 31 */
  57         RELOPT_KIND_MAX = (1 << 30)
  58 } relopt_kind;
  59
  60 /* reloption namespaces allowed for heaps -- currently only TOAST */
  61 #define HEAP_RELOPT_NAMESPACES { "toast", NULL }
  62
  63 /* generic struct to hold shared data */
  64 typedef struct relopt_gen
  65 {
  66         const char *name;                       /* must be first (used as list termination
  67                                                                  * marker) */
  68         const char *desc;
  69         bits32          kinds;
  70         LOCKMODE        lockmode;
  71         int                     namelen;
  72         relopt_type type;
  73 } relopt_gen;
  74
  75 /* holds a parsed value */
  76 typedef struct relopt_value
  77 {
  78         relopt_gen *gen;
  79         bool            isset;
  80         union
  81         {
  82                 bool            bool_val;
  83                 int                     int_val;
  84                 double          real_val;
  85                 int                     enum_val;
  86                 char       *string_val; /* allocated separately */
  87         }                       values;
  88 } relopt_value;
  89
  90 /* reloptions records for specific variable types */
  91 typedef struct relopt_bool
  92 {
  93         relopt_gen      gen;
  94         bool            default_val;
  95 } relopt_bool;
  96
  97 typedef struct relopt_int
  98 {
  99         relopt_gen      gen;
 100         int                     default_val;
 101         int                     min;
 102         int                     max;
 103 } relopt_int;
 104
 105 typedef struct relopt_real
 106 {
 107         relopt_gen      gen;
 108         double          default_val;
 109         double          min;
 110         double          max;
 111 } relopt_real;
 112
 113 /*
 114  * relopt_enum_elt_def -- One member of the array of acceptable values
 115  * of an enum reloption.
 116  */
 117 typedef struct relopt_enum_elt_def
 118 {
 119         const char *string_val;
 120         int                     symbol_val;
 121 } relopt_enum_elt_def;
 122
 123 typedef struct relopt_enum
 124 {
 125         relopt_gen      gen;
 126         relopt_enum_elt_def *members;
 127         int                     default_val;
 128         const char *detailmsg;
 129         /* null-terminated array of members */
 130 } relopt_enum;
 131
 132 /* validation routines for strings */
 133 typedef void (*validate_string_relopt) (const char *value);
 134 typedef Size (*fill_string_relopt) (const char *value, void *ptr);
 135
 136 /* validation routine for the whole option set */
 137 typedef void (*relopts_validator) (void *parsed_options, relopt_value *vals, int nvals);
 138
 139 typedef struct relopt_string
 140 {
 141         relopt_gen      gen;
 142         int                     default_len;
 143         bool            default_isnull;
 144         validate_string_relopt validate_cb;
 145         fill_string_relopt fill_cb;
 146         char       *default_val;
 147 } relopt_string;
 148
 149 /* This is the table datatype for build_reloptions() */
 150 typedef struct
 151 {
 152         const char *optname;            /* option's name */
 153         relopt_type opttype;            /* option's datatype */
 154         int                     offset;                 /* offset of field in result struct */
 155 } relopt_parse_elt;
 156
 157 /* Local reloption definition */
 158 typedef struct local_relopt
 159 {
 160         relopt_gen *option;                     /* option definition */
 161         int                     offset;                 /* offset of parsed value in bytea structure */
 162 } local_relopt;
 163
 164 /* Structure to hold local reloption data for build_local_reloptions() */
 165 typedef struct local_relopts
 166 {
 167         List       *options;            /* list of local_relopt definitions */
 168         List       *validators;         /* list of relopts_validator callbacks */
 169         Size            relopt_struct_size; /* size of parsed bytea structure */
 170 } local_relopts;
 171
 172 /*
 173  * Utility macro to get a value for a string reloption once the options
 174  * are parsed.  This gets a pointer to the string value itself.  "optstruct"
 175  * is the StdRdOptions struct or equivalent, "member" is the struct member
 176  * corresponding to the string option.
 177  */
 178 #define GET_STRING_RELOPTION(optstruct, member) \
 179         ((optstruct)->member == 0 ? NULL : \
 180          (char *)(optstruct) + (optstruct)->member)
 181
 182 extern relopt_kind add_reloption_kind(void);
 183 extern void add_bool_reloption(bits32 kinds, const char *name, const char *desc,
 184                                                            bool default_val, LOCKMODE lockmode);
 185 extern void add_int_reloption(bits32 kinds, const char *name, const char *desc,
 186                                                           int default_val, int min_val, int max_val,
 187                                                           LOCKMODE lockmode);
 188 extern void add_real_reloption(bits32 kinds, const char *name, const char *desc,
 189                                                            double default_val, double min_val, double max_val,
 190                                                            LOCKMODE lockmode);
 191 extern void add_enum_reloption(bits32 kinds, const char *name, const char *desc,
 192                                                            relopt_enum_elt_def *members, int default_val,
 193                                                            const char *detailmsg, LOCKMODE lockmode);
 194 extern void add_string_reloption(bits32 kinds, const char *name, const char *desc,
 195                                                                  const char *default_val, validate_string_relopt validator,
 196                                                                  LOCKMODE lockmode);
 197
 198 extern void init_local_reloptions(local_relopts *relopts, Size relopt_struct_size);
 199 extern void register_reloptions_validator(local_relopts *relopts,
 200                                                                                   relopts_validator validator);
 201 extern void add_local_bool_reloption(local_relopts *relopts, const char *name,
 202                                                                          const char *desc, bool default_val,
 203                                                                          int offset);
 204 extern void add_local_int_reloption(local_relopts *relopts, const char *name,
 205                                                                         const char *desc, int default_val,
 206                                                                         int min_val, int max_val, int offset);
 207 extern void add_local_real_reloption(local_relopts *relopts, const char *name,
 208                                                                          const char *desc, double default_val,
 209                                                                          double min_val, double max_val,
 210                                                                          int offset);
 211 extern void add_local_enum_reloption(local_relopts *relopts,
 212                                                                          const char *name, const char *desc,
 213                                                                          relopt_enum_elt_def *members,
 214                                                                          int default_val, const char *detailmsg,
 215                                                                          int offset);
 216 extern void add_local_string_reloption(local_relopts *relopts, const char *name,
 217                                                                            const char *desc,
 218                                                                            const char *default_val,
 219                                                                            validate_string_relopt validator,
 220                                                                            fill_string_relopt filler, int offset);
 221
 222 extern Datum transformRelOptions(Datum oldOptions, List *defList,
 223                                                                  const char *namspace, const char *const validnsps[],
 224                                                                  bool acceptOidsOff, bool isReset);
 225 extern List *untransformRelOptions(Datum options);
 226 extern bytea *extractRelOptions(HeapTuple tuple, TupleDesc tupdesc,
 227                                                                 amoptions_function amoptions);
 228 extern void *build_reloptions(Datum reloptions, bool validate,
 229                                                           relopt_kind kind,
 230                                                           Size relopt_struct_size,
 231                                                           const relopt_parse_elt *relopt_elems,
 232                                                           int num_relopt_elems);
 233 extern void *build_local_reloptions(local_relopts *relopts, Datum options,
 234                                                                         bool validate);
 235
 236 extern bytea *default_reloptions(Datum reloptions, bool validate,
 237                                                                  relopt_kind kind);
 238 extern bytea *heap_reloptions(char relkind, Datum reloptions, bool validate);
 239 extern bytea *view_reloptions(Datum reloptions, bool validate);
 240 extern bytea *partitioned_table_reloptions(Datum reloptions, bool validate);
 241 extern bytea *index_reloptions(amoptions_function amoptions, Datum reloptions,
 242                                                            bool validate);
 243 extern bytea *attribute_reloptions(Datum reloptions, bool validate);
 244 extern bytea *tablespace_reloptions(Datum reloptions, bool validate);
 245 extern LOCKMODE AlterTableGetRelOptionsLockLevel(List *defList);
 246
 247 #endif                                                  /* RELOPTIONS_H */