PostgreSQL Source Code  git master
spi.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * spi.h
4  * Server Programming Interface public declarations
5  *
6  * Portions Copyright (c) 1996-2023, 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 */
35 
36 /* Optional arguments for SPI_prepare_extended */
37 typedef struct SPIPrepareOptions
38 {
44 
45 /* Optional arguments for SPI_execute[_plan]_extended */
46 typedef struct SPIExecuteOptions
47 {
49  bool read_only;
52  uint64 tcount;
56 
57 /* Optional arguments for SPI_cursor_parse_open */
58 typedef struct SPIParseOpenOptions
59 {
62  bool read_only;
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 #define SPI_OK_MERGE 18
100 
101 #define SPI_OPT_NONATOMIC (1 << 0)
102 
103 /* These used to be functions, now just no-ops for backwards compatibility */
104 #define SPI_push() ((void) 0)
105 #define SPI_pop() ((void) 0)
106 #define SPI_push_conditional() false
107 #define SPI_pop_conditional(pushed) ((void) 0)
108 #define SPI_restore_connection() ((void) 0)
109 
110 extern PGDLLIMPORT uint64 SPI_processed;
112 extern PGDLLIMPORT int SPI_result;
113 
114 extern int SPI_connect(void);
115 extern int SPI_connect_ext(int options);
116 extern int SPI_finish(void);
117 extern int SPI_execute(const char *src, bool read_only, long tcount);
118 extern int SPI_execute_extended(const char *src,
119  const SPIExecuteOptions *options);
120 extern int SPI_execute_plan(SPIPlanPtr plan, Datum *Values, const char *Nulls,
121  bool read_only, long tcount);
123  const SPIExecuteOptions *options);
125  ParamListInfo params,
126  bool read_only, long tcount);
127 extern int SPI_exec(const char *src, long tcount);
128 extern int SPI_execp(SPIPlanPtr plan, Datum *Values, const char *Nulls,
129  long tcount);
131  Datum *Values, const char *Nulls,
132  Snapshot snapshot,
133  Snapshot crosscheck_snapshot,
134  bool read_only, bool fire_triggers, long tcount);
135 extern int SPI_execute_with_args(const char *src,
136  int nargs, Oid *argtypes,
137  Datum *Values, const char *Nulls,
138  bool read_only, long tcount);
139 extern SPIPlanPtr SPI_prepare(const char *src, int nargs, Oid *argtypes);
140 extern SPIPlanPtr SPI_prepare_cursor(const char *src, int nargs, Oid *argtypes,
141  int cursorOptions);
142 extern SPIPlanPtr SPI_prepare_extended(const char *src,
143  const SPIPrepareOptions *options);
144 extern SPIPlanPtr SPI_prepare_params(const char *src,
146  void *parserSetupArg,
147  int cursorOptions);
148 extern int SPI_keepplan(SPIPlanPtr plan);
150 extern int SPI_freeplan(SPIPlanPtr plan);
151 
152 extern Oid SPI_getargtypeid(SPIPlanPtr plan, int argIndex);
153 extern int SPI_getargcount(SPIPlanPtr plan);
154 extern bool SPI_is_cursor_plan(SPIPlanPtr plan);
155 extern bool SPI_plan_is_valid(SPIPlanPtr plan);
156 extern const char *SPI_result_code_string(int code);
157 
160 
161 extern HeapTuple SPI_copytuple(HeapTuple tuple);
162 extern HeapTupleHeader SPI_returntuple(HeapTuple tuple, TupleDesc tupdesc);
163 extern HeapTuple SPI_modifytuple(Relation rel, HeapTuple tuple, int natts,
164  int *attnum, Datum *Values, const char *Nulls);
165 extern int SPI_fnumber(TupleDesc tupdesc, const char *fname);
166 extern char *SPI_fname(TupleDesc tupdesc, int fnumber);
167 extern char *SPI_getvalue(HeapTuple tuple, TupleDesc tupdesc, int fnumber);
168 extern Datum SPI_getbinval(HeapTuple tuple, TupleDesc tupdesc, int fnumber, bool *isnull);
169 extern char *SPI_gettype(TupleDesc tupdesc, int fnumber);
170 extern Oid SPI_gettypeid(TupleDesc tupdesc, int fnumber);
171 extern char *SPI_getrelname(Relation rel);
172 extern char *SPI_getnspname(Relation rel);
173 extern void *SPI_palloc(Size size);
174 extern void *SPI_repalloc(void *pointer, Size size);
175 extern void SPI_pfree(void *pointer);
176 extern Datum SPI_datumTransfer(Datum value, bool typByVal, int typLen);
177 extern void SPI_freetuple(HeapTuple tuple);
178 extern void SPI_freetuptable(SPITupleTable *tuptable);
179 
180 extern Portal SPI_cursor_open(const char *name, SPIPlanPtr plan,
181  Datum *Values, const char *Nulls, bool read_only);
182 extern Portal SPI_cursor_open_with_args(const char *name,
183  const char *src,
184  int nargs, Oid *argtypes,
185  Datum *Values, const char *Nulls,
186  bool read_only, int cursorOptions);
188  ParamListInfo params, bool read_only);
189 extern Portal SPI_cursor_parse_open(const char *name,
190  const char *src,
192 extern Portal SPI_cursor_find(const char *name);
193 extern void SPI_cursor_fetch(Portal portal, bool forward, long count);
194 extern void SPI_cursor_move(Portal portal, bool forward, long count);
195 extern void SPI_scroll_cursor_fetch(Portal, FetchDirection direction, long count);
196 extern void SPI_scroll_cursor_move(Portal, FetchDirection direction, long count);
197 extern void SPI_cursor_close(Portal portal);
198 
200 extern int SPI_unregister_relation(const char *name);
201 extern int SPI_register_trigger_data(TriggerData *tdata);
202 
203 extern void SPI_start_transaction(void);
204 extern void SPI_commit(void);
205 extern void SPI_commit_and_chain(void);
206 extern void SPI_rollback(void);
207 extern void SPI_rollback_and_chain(void);
208 
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 */
static bool Nulls[MAXATTR]
Definition: bootstrap.c:157
#define PGDLLIMPORT
Definition: c.h:1326
uint32 SubTransactionId
Definition: c.h:645
size_t Size
Definition: c.h:594
static struct @148 value
void(* ParserSetupHook)(struct ParseState *pstate, void *arg)
Definition: params.h:108
FetchDirection
Definition: parsenodes.h:3191
RawParseMode
Definition: parser.h:38
int16 attnum
Definition: pg_attribute.h:74
#define plan(x)
Definition: pg_regress.c:154
uintptr_t Datum
Definition: postgres.h:64
unsigned int Oid
Definition: postgres_ext.h:31
void AtEOSubXact_SPI(bool isCommit, SubTransactionId mySubid)
Definition: spi.c:483
void SPI_commit(void)
Definition: spi.c:321
SPIPlanPtr SPI_prepare_cursor(const char *src, int nargs, Oid *argtypes, int cursorOptions)
Definition: spi.c:864
int SPI_execute_plan_with_paramlist(SPIPlanPtr plan, ParamListInfo params, bool read_only, long tcount)
Definition: spi.c:731
char * SPI_getrelname(Relation rel)
Definition: spi.c:1324
CachedPlan * SPI_plan_get_cached_plan(SPIPlanPtr plan)
Definition: spi.c:2070
void SPI_cursor_move(Portal portal, bool forward, long count)
Definition: spi.c:1819
PGDLLIMPORT uint64 SPI_processed
Definition: spi.c:45
void SPI_freetuple(HeapTuple tuple)
Definition: spi.c:1377
int SPI_fnumber(TupleDesc tupdesc, const char *fname)
Definition: spi.c:1173
bool SPI_plan_is_valid(SPIPlanPtr plan)
Definition: spi.c:1946
void SPI_commit_and_chain(void)
Definition: spi.c:327
bool SPI_is_cursor_plan(SPIPlanPtr plan)
Definition: spi.c:1908
SPIPlanPtr SPI_prepare_extended(const char *src, const SPIPrepareOptions *options)
Definition: spi.c:900
Oid SPI_gettypeid(TupleDesc tupdesc, int fnumber)
Definition: spi.c:1306
void SPI_scroll_cursor_fetch(Portal, FetchDirection direction, long count)
Definition: spi.c:1833
HeapTupleHeader SPI_returntuple(HeapTuple tuple, TupleDesc tupdesc)
Definition: spi.c:1072
int SPI_freeplan(SPIPlanPtr plan)
Definition: spi.c:1023
void SPI_rollback_and_chain(void)
Definition: spi.c:420
Portal SPI_cursor_find(const char *name)
Definition: spi.c:1792
int SPI_unregister_relation(const char *name)
Definition: spi.c:3307
bool SPI_inside_nonatomic_context(void)
Definition: spi.c:582
int SPI_connect(void)
Definition: spi.c:95
struct SPITupleTable SPITupleTable
int SPI_execute_snapshot(SPIPlanPtr plan, Datum *Values, const char *Nulls, Snapshot snapshot, Snapshot crosscheck_snapshot, bool read_only, bool fire_triggers, long tcount)
Definition: spi.c:771
int SPI_execute_plan_extended(SPIPlanPtr plan, const SPIExecuteOptions *options)
Definition: spi.c:709
SPIPlanPtr SPI_prepare_params(const char *src, ParserSetupHook parserSetup, void *parserSetupArg, int cursorOptions)
Definition: spi.c:936
SPIPlanPtr SPI_saveplan(SPIPlanPtr plan)
Definition: spi.c:1001
const char * SPI_result_code_string(int code)
Definition: spi.c:1970
void SPI_cursor_fetch(Portal portal, bool forward, long count)
Definition: spi.c:1804
Portal SPI_cursor_parse_open(const char *name, const char *src, const SPIParseOpenOptions *options)
Definition: spi.c:1531
int SPI_finish(void)
Definition: spi.c:183
int SPI_execute_plan(SPIPlanPtr plan, Datum *Values, const char *Nulls, bool read_only, long tcount)
Definition: spi.c:670
Datum SPI_datumTransfer(Datum value, bool typByVal, int typLen)
Definition: spi.c:1359
PGDLLIMPORT int SPI_result
Definition: spi.c:47
int SPI_register_trigger_data(TriggerData *tdata)
Definition: spi.c:3340
Portal SPI_cursor_open_with_paramlist(const char *name, SPIPlanPtr plan, ParamListInfo params, bool read_only)
Definition: spi.c:1523
Portal SPI_cursor_open_with_args(const char *name, const char *src, int nargs, Oid *argtypes, Datum *Values, const char *Nulls, bool read_only, int cursorOptions)
Definition: spi.c:1470
void SPI_freetuptable(SPITupleTable *tuptable)
Definition: spi.c:1384
Portal SPI_cursor_open(const char *name, SPIPlanPtr plan, Datum *Values, const char *Nulls, bool read_only)
Definition: spi.c:1443
void * SPI_repalloc(void *pointer, Size size)
Definition: spi.c:1345
struct SPIPrepareOptions SPIPrepareOptions
PGDLLIMPORT SPITupleTable * SPI_tuptable
Definition: spi.c:46
int SPI_exec(const char *src, long tcount)
Definition: spi.c:628
int SPI_register_relation(EphemeralNamedRelation enr)
Definition: spi.c:3273
HeapTuple SPI_modifytuple(Relation rel, HeapTuple tuple, int natts, int *attnum, Datum *Values, const char *Nulls)
Definition: spi.c:1104
SPIPlanPtr SPI_prepare(const char *src, int nargs, Oid *argtypes)
Definition: spi.c:858
int SPI_keepplan(SPIPlanPtr plan)
Definition: spi.c:974
void SPI_cursor_close(Portal portal)
Definition: spi.c:1860
void SPI_pfree(void *pointer)
Definition: spi.c:1352
char * SPI_getnspname(Relation rel)
Definition: spi.c:1330
int SPI_connect_ext(int options)
Definition: spi.c:101
int SPI_execp(SPIPlanPtr plan, Datum *Values, const char *Nulls, long tcount)
Definition: spi.c:702
char * SPI_gettype(TupleDesc tupdesc, int fnumber)
Definition: spi.c:1266
struct _SPI_plan * SPIPlanPtr
Definition: spi.h:66
int SPI_execute_extended(const char *src, const SPIExecuteOptions *options)
Definition: spi.c:635
void SPI_rollback(void)
Definition: spi.c:414
List * SPI_plan_get_plan_sources(SPIPlanPtr plan)
Definition: spi.c:2051
struct SPIParseOpenOptions SPIParseOpenOptions
struct SPIExecuteOptions SPIExecuteOptions
void * SPI_palloc(Size size)
Definition: spi.c:1336
void SPI_scroll_cursor_move(Portal, FetchDirection direction, long count)
Definition: spi.c:1848
char * SPI_getvalue(HeapTuple tuple, TupleDesc tupdesc, int fnumber)
Definition: spi.c:1218
int SPI_execute_with_args(const char *src, int nargs, Oid *argtypes, Datum *Values, const char *Nulls, bool read_only, long tcount)
Definition: spi.c:810
char * SPI_fname(TupleDesc tupdesc, int fnumber)
Definition: spi.c:1196
void SPI_start_transaction(void)
Definition: spi.c:223
HeapTuple SPI_copytuple(HeapTuple tuple)
Definition: spi.c:1045
int SPI_getargcount(SPIPlanPtr plan)
Definition: spi.c:1888
void AtEOXact_SPI(bool isCommit)
Definition: spi.c:429
int SPI_execute(const char *src, bool read_only, long tcount)
Definition: spi.c:594
Datum SPI_getbinval(HeapTuple tuple, TupleDesc tupdesc, int fnumber, bool *isnull)
Definition: spi.c:1250
Oid SPI_getargtypeid(SPIPlanPtr plan, int argIndex)
Definition: spi.c:1873
Definition: pg_list.h:54
bool must_return_tuples
Definition: spi.h:51
uint64 tcount
Definition: spi.h:52
ParamListInfo params
Definition: spi.h:48
ResourceOwner owner
Definition: spi.h:54
bool read_only
Definition: spi.h:49
bool allow_nonatomic
Definition: spi.h:50
DestReceiver * dest
Definition: spi.h:53
int cursorOptions
Definition: spi.h:61
ParamListInfo params
Definition: spi.h:60
bool read_only
Definition: spi.h:62
ParserSetupHook parserSetup
Definition: spi.h:39
RawParseMode parseMode
Definition: spi.h:41
void * parserSetupArg
Definition: spi.h:40
int cursorOptions
Definition: spi.h:42
uint64 alloced
Definition: spi.h:30
uint64 numvals
Definition: spi.h:27
TupleDesc tupdesc
Definition: spi.h:25
HeapTuple * vals
Definition: spi.h:26
MemoryContext tuptabcxt
Definition: spi.h:31
slist_node next
Definition: spi.h:32
SubTransactionId subid
Definition: spi.h:33
ParserSetupHook parserSetup
Definition: spi_priv.h:101
Oid * argtypes
Definition: spi_priv.h:100
int nargs
Definition: spi_priv.h:99
void * parserSetupArg
Definition: spi_priv.h:102
const char * name