src/include/executor/spi.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * spi.h
   4  *                              Server Programming Interface public declarations
   5  *
   6  * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
   7  * Portions Copyright (c) 1994, Regents of the University of California
   8  *
   9  * src/include/executor/spi.h
  10  *
  11  *-------------------------------------------------------------------------
  12  */
  13 #ifndef SPI_H
  14 #define SPI_H
  15
  16 #include "commands/trigger.h"
  17 #include "lib/ilist.h"
  18 #include "parser/parser.h"
  19 #include "utils/portal.h"
  20
  21
  22 typedef struct SPITupleTable
  23 {
  24         /* Public members */
  25         TupleDesc       tupdesc;                /* tuple descriptor */
  26         HeapTuple  *vals;                       /* array of tuples */
  27         uint64          numvals;                /* number of valid tuples */
  28
  29         /* Private members, not intended for external callers */
  30         uint64          alloced;                /* allocated length of vals array */
  31         MemoryContext tuptabcxt;        /* memory context of result table */
  32         slist_node      next;                   /* link for internal bookkeeping */
  33         SubTransactionId subid;         /* subxact in which tuptable was created */
  34 } SPITupleTable;
  35
  36 /* Optional arguments for SPI_prepare_extended */
  37 typedef struct SPIPrepareOptions
  38 {
  39         ParserSetupHook parserSetup;
  40         void       *parserSetupArg;
  41         RawParseMode parseMode;
  42         int                     cursorOptions;
  43 } SPIPrepareOptions;
  44
  45 /* Optional arguments for SPI_execute[_plan]_extended */
  46 typedef struct SPIExecuteOptions
  47 {
  48         ParamListInfo params;
  49         bool            read_only;
  50         bool            allow_nonatomic;
  51         bool            must_return_tuples;
  52         uint64          tcount;
  53         DestReceiver *dest;
  54         ResourceOwner owner;
  55 } SPIExecuteOptions;
  56
  57 /* Optional arguments for SPI_cursor_parse_open */
  58 typedef struct SPIParseOpenOptions
  59 {
  60         ParamListInfo params;
  61         int                     cursorOptions;
  62         bool            read_only;
  63 } SPIParseOpenOptions;
  64
  65 /* Plans are opaque structs for standard users of SPI */
  66 typedef struct _SPI_plan *SPIPlanPtr;
  67
  68 #define SPI_ERROR_CONNECT               (-1)
  69 #define SPI_ERROR_COPY                  (-2)
  70 #define SPI_ERROR_OPUNKNOWN             (-3)
  71 #define SPI_ERROR_UNCONNECTED   (-4)
  72 #define SPI_ERROR_CURSOR                (-5)    /* not used anymore */
  73 #define SPI_ERROR_ARGUMENT              (-6)
  74 #define SPI_ERROR_PARAM                 (-7)
  75 #define SPI_ERROR_TRANSACTION   (-8)
  76 #define SPI_ERROR_NOATTRIBUTE   (-9)
  77 #define SPI_ERROR_NOOUTFUNC             (-10)
  78 #define SPI_ERROR_TYPUNKNOWN    (-11)
  79 #define SPI_ERROR_REL_DUPLICATE (-12)
  80 #define SPI_ERROR_REL_NOT_FOUND (-13)
  81
  82 #define SPI_OK_CONNECT                  1
  83 #define SPI_OK_FINISH                   2
  84 #define SPI_OK_FETCH                    3
  85 #define SPI_OK_UTILITY                  4
  86 #define SPI_OK_SELECT                   5
  87 #define SPI_OK_SELINTO                  6
  88 #define SPI_OK_INSERT                   7
  89 #define SPI_OK_DELETE                   8
  90 #define SPI_OK_UPDATE                   9
  91 #define SPI_OK_CURSOR                   10
  92 #define SPI_OK_INSERT_RETURNING 11
  93 #define SPI_OK_DELETE_RETURNING 12
  94 #define SPI_OK_UPDATE_RETURNING 13
  95 #define SPI_OK_REWRITTEN                14
  96 #define SPI_OK_REL_REGISTER             15
  97 #define SPI_OK_REL_UNREGISTER   16
  98 #define SPI_OK_TD_REGISTER              17
  99
 100 #define SPI_OPT_NONATOMIC               (1 << 0)
 101
 102 /* These used to be functions, now just no-ops for backwards compatibility */
 103 #define SPI_push()      ((void) 0)
 104 #define SPI_pop()       ((void) 0)
 105 #define SPI_push_conditional()  false
 106 #define SPI_pop_conditional(pushed) ((void) 0)
 107 #define SPI_restore_connection()        ((void) 0)
 108
 109 extern PGDLLIMPORT uint64 SPI_processed;
 110 extern PGDLLIMPORT SPITupleTable *SPI_tuptable;
 111 extern PGDLLIMPORT int SPI_result;
 112
 113 extern int      SPI_connect(void);
 114 extern int      SPI_connect_ext(int options);
 115 extern int      SPI_finish(void);
 116 extern int      SPI_execute(const char *src, bool read_only, long tcount);
 117 extern int      SPI_execute_extended(const char *src,
 118                                                                  const SPIExecuteOptions *options);
 119 extern int      SPI_execute_plan(SPIPlanPtr plan, Datum *Values, const char *Nulls,
 120                                                          bool read_only, long tcount);
 121 extern int      SPI_execute_plan_extended(SPIPlanPtr plan,
 122                                                                           const SPIExecuteOptions *options);
 123 extern int      SPI_execute_plan_with_paramlist(SPIPlanPtr plan,
 124                                                                                         ParamListInfo params,
 125                                                                                         bool read_only, long tcount);
 126 extern int      SPI_exec(const char *src, long tcount);
 127 extern int      SPI_execp(SPIPlanPtr plan, Datum *Values, const char *Nulls,
 128                                           long tcount);
 129 extern int      SPI_execute_snapshot(SPIPlanPtr plan,
 130                                                                  Datum *Values, const char *Nulls,
 131                                                                  Snapshot snapshot,
 132                                                                  Snapshot crosscheck_snapshot,
 133                                                                  bool read_only, bool fire_triggers, long tcount);
 134 extern int      SPI_execute_with_args(const char *src,
 135                                                                   int nargs, Oid *argtypes,
 136                                                                   Datum *Values, const char *Nulls,
 137                                                                   bool read_only, long tcount);
 138 extern SPIPlanPtr SPI_prepare(const char *src, int nargs, Oid *argtypes);
 139 extern SPIPlanPtr SPI_prepare_cursor(const char *src, int nargs, Oid *argtypes,
 140                                                                          int cursorOptions);
 141 extern SPIPlanPtr SPI_prepare_extended(const char *src,
 142                                                                            const SPIPrepareOptions *options);
 143 extern SPIPlanPtr SPI_prepare_params(const char *src,
 144                                                                          ParserSetupHook parserSetup,
 145                                                                          void *parserSetupArg,
 146                                                                          int cursorOptions);
 147 extern int      SPI_keepplan(SPIPlanPtr plan);
 148 extern SPIPlanPtr SPI_saveplan(SPIPlanPtr plan);
 149 extern int      SPI_freeplan(SPIPlanPtr plan);
 150
 151 extern Oid      SPI_getargtypeid(SPIPlanPtr plan, int argIndex);
 152 extern int      SPI_getargcount(SPIPlanPtr plan);
 153 extern bool SPI_is_cursor_plan(SPIPlanPtr plan);
 154 extern bool SPI_plan_is_valid(SPIPlanPtr plan);
 155 extern const char *SPI_result_code_string(int code);
 156
 157 extern List *SPI_plan_get_plan_sources(SPIPlanPtr plan);
 158 extern CachedPlan *SPI_plan_get_cached_plan(SPIPlanPtr plan);
 159
 160 extern HeapTuple SPI_copytuple(HeapTuple tuple);
 161 extern HeapTupleHeader SPI_returntuple(HeapTuple tuple, TupleDesc tupdesc);
 162 extern HeapTuple SPI_modifytuple(Relation rel, HeapTuple tuple, int natts,
 163                                                                  int *attnum, Datum *Values, const char *Nulls);
 164 extern int      SPI_fnumber(TupleDesc tupdesc, const char *fname);
 165 extern char *SPI_fname(TupleDesc tupdesc, int fnumber);
 166 extern char *SPI_getvalue(HeapTuple tuple, TupleDesc tupdesc, int fnumber);
 167 extern Datum SPI_getbinval(HeapTuple tuple, TupleDesc tupdesc, int fnumber, bool *isnull);
 168 extern char *SPI_gettype(TupleDesc tupdesc, int fnumber);
 169 extern Oid      SPI_gettypeid(TupleDesc tupdesc, int fnumber);
 170 extern char *SPI_getrelname(Relation rel);
 171 extern char *SPI_getnspname(Relation rel);
 172 extern void *SPI_palloc(Size size);
 173 extern void *SPI_repalloc(void *pointer, Size size);
 174 extern void SPI_pfree(void *pointer);
 175 extern Datum SPI_datumTransfer(Datum value, bool typByVal, int typLen);
 176 extern void SPI_freetuple(HeapTuple pointer);
 177 extern void SPI_freetuptable(SPITupleTable *tuptable);
 178
 179 extern Portal SPI_cursor_open(const char *name, SPIPlanPtr plan,
 180                                                           Datum *Values, const char *Nulls, bool read_only);
 181 extern Portal SPI_cursor_open_with_args(const char *name,
 182                                                                                 const char *src,
 183                                                                                 int nargs, Oid *argtypes,
 184                                                                                 Datum *Values, const char *Nulls,
 185                                                                                 bool read_only, int cursorOptions);
 186 extern Portal SPI_cursor_open_with_paramlist(const char *name, SPIPlanPtr plan,
 187                                                                                          ParamListInfo params, bool read_only);
 188 extern Portal SPI_cursor_parse_open(const char *name,
 189                                                                         const char *src,
 190                                                                         const SPIParseOpenOptions *options);
 191 extern Portal SPI_cursor_find(const char *name);
 192 extern void SPI_cursor_fetch(Portal portal, bool forward, long count);
 193 extern void SPI_cursor_move(Portal portal, bool forward, long count);
 194 extern void SPI_scroll_cursor_fetch(Portal, FetchDirection direction, long count);
 195 extern void SPI_scroll_cursor_move(Portal, FetchDirection direction, long count);
 196 extern void SPI_cursor_close(Portal portal);
 197
 198 extern int      SPI_register_relation(EphemeralNamedRelation enr);
 199 extern int      SPI_unregister_relation(const char *name);
 200 extern int      SPI_register_trigger_data(TriggerData *tdata);
 201
 202 extern void SPI_start_transaction(void);
 203 extern void SPI_commit(void);
 204 extern void SPI_commit_and_chain(void);
 205 extern void SPI_rollback(void);
 206 extern void SPI_rollback_and_chain(void);
 207
 208 extern void SPICleanup(void);
 209 extern void AtEOXact_SPI(bool isCommit);
 210 extern void AtEOSubXact_SPI(bool isCommit, SubTransactionId mySubid);
 211 extern bool SPI_inside_nonatomic_context(void);
 212
 213 #endif                                                  /* SPI_H */