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-2025, 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
22typedef 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 */
37typedef struct SPIPrepareOptions
38{
44
45/* Optional arguments for SPI_execute[_plan]_extended */
46typedef struct SPIExecuteOptions
47{
56
57/* Optional arguments for SPI_cursor_parse_open */
58typedef struct SPIParseOpenOptions
59{
64
65/* Plans are opaque structs for standard users of SPI */
66typedef 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#define SPI_OK_MERGE_RETURNING 19
101
102#define SPI_OPT_NONATOMIC (1 << 0)
103
106extern PGDLLIMPORT int SPI_result;
107
108extern int SPI_connect(void);
109extern int SPI_connect_ext(int options);
110extern int SPI_finish(void);
111extern int SPI_execute(const char *src, bool read_only, long tcount);
112extern int SPI_execute_extended(const char *src,
114extern int SPI_execute_plan(SPIPlanPtr plan, Datum *Values, const char *Nulls,
115 bool read_only, long tcount);
119 ParamListInfo params,
120 bool read_only, long tcount);
121extern int SPI_exec(const char *src, long tcount);
122extern int SPI_execp(SPIPlanPtr plan, Datum *Values, const char *Nulls,
123 long tcount);
125 Datum *Values, const char *Nulls,
126 Snapshot snapshot,
127 Snapshot crosscheck_snapshot,
128 bool read_only, bool fire_triggers, long tcount);
129extern int SPI_execute_with_args(const char *src,
130 int nargs, Oid *argtypes,
131 Datum *Values, const char *Nulls,
132 bool read_only, long tcount);
133extern SPIPlanPtr SPI_prepare(const char *src, int nargs, Oid *argtypes);
134extern SPIPlanPtr SPI_prepare_cursor(const char *src, int nargs, Oid *argtypes,
135 int cursorOptions);
136extern SPIPlanPtr SPI_prepare_extended(const char *src,
138extern SPIPlanPtr SPI_prepare_params(const char *src,
140 void *parserSetupArg,
141 int cursorOptions);
142extern int SPI_keepplan(SPIPlanPtr plan);
144extern int SPI_freeplan(SPIPlanPtr plan);
145
146extern Oid SPI_getargtypeid(SPIPlanPtr plan, int argIndex);
150extern const char *SPI_result_code_string(int code);
151
154
155extern HeapTuple SPI_copytuple(HeapTuple tuple);
157extern HeapTuple SPI_modifytuple(Relation rel, HeapTuple tuple, int natts,
158 int *attnum, Datum *Values, const char *Nulls);
159extern int SPI_fnumber(TupleDesc tupdesc, const char *fname);
160extern char *SPI_fname(TupleDesc tupdesc, int fnumber);
161extern char *SPI_getvalue(HeapTuple tuple, TupleDesc tupdesc, int fnumber);
162extern Datum SPI_getbinval(HeapTuple tuple, TupleDesc tupdesc, int fnumber, bool *isnull);
163extern char *SPI_gettype(TupleDesc tupdesc, int fnumber);
164extern Oid SPI_gettypeid(TupleDesc tupdesc, int fnumber);
165extern char *SPI_getrelname(Relation rel);
166extern char *SPI_getnspname(Relation rel);
167extern void *SPI_palloc(Size size);
168extern void *SPI_repalloc(void *pointer, Size size);
169extern void SPI_pfree(void *pointer);
170extern Datum SPI_datumTransfer(Datum value, bool typByVal, int typLen);
171extern void SPI_freetuple(HeapTuple tuple);
172extern void SPI_freetuptable(SPITupleTable *tuptable);
173
174extern Portal SPI_cursor_open(const char *name, SPIPlanPtr plan,
175 Datum *Values, const char *Nulls, bool read_only);
176extern Portal SPI_cursor_open_with_args(const char *name,
177 const char *src,
178 int nargs, Oid *argtypes,
179 Datum *Values, const char *Nulls,
180 bool read_only, int cursorOptions);
182 ParamListInfo params, bool read_only);
183extern Portal SPI_cursor_parse_open(const char *name,
184 const char *src,
186extern Portal SPI_cursor_find(const char *name);
187extern void SPI_cursor_fetch(Portal portal, bool forward, long count);
188extern void SPI_cursor_move(Portal portal, bool forward, long count);
189extern void SPI_scroll_cursor_fetch(Portal, FetchDirection direction, long count);
190extern void SPI_scroll_cursor_move(Portal, FetchDirection direction, long count);
191extern void SPI_cursor_close(Portal portal);
192
194extern int SPI_unregister_relation(const char *name);
195extern int SPI_register_trigger_data(TriggerData *tdata);
196
197extern void SPI_start_transaction(void);
198extern void SPI_commit(void);
199extern void SPI_commit_and_chain(void);
200extern void SPI_rollback(void);
201extern void SPI_rollback_and_chain(void);
202
203extern void AtEOXact_SPI(bool isCommit);
204extern void AtEOSubXact_SPI(bool isCommit, SubTransactionId mySubid);
205extern bool SPI_inside_nonatomic_context(void);
206
207#endif /* SPI_H */
static bool Nulls[MAXATTR]
Definition: bootstrap.c:152
#define PGDLLIMPORT
Definition: c.h:1277
uint32 SubTransactionId
Definition: c.h:613
uint64_t uint64
Definition: c.h:489
size_t Size
Definition: c.h:562
static struct @162 value
void(* ParserSetupHook)(struct ParseState *pstate, void *arg)
Definition: params.h:108
FetchDirection
Definition: parsenodes.h:3391
RawParseMode
Definition: parser.h:38
int16 attnum
Definition: pg_attribute.h:74
#define plan(x)
Definition: pg_regress.c:161
uintptr_t Datum
Definition: postgres.h:69
unsigned int Oid
Definition: postgres_ext.h:32
static pg_noinline void Size size
Definition: slab.c:607
void AtEOSubXact_SPI(bool isCommit, SubTransactionId mySubid)
Definition: spi.c:482
List * SPI_plan_get_plan_sources(SPIPlanPtr plan)
Definition: spi.c:2057
void SPI_commit(void)
Definition: spi.c:320
SPIPlanPtr SPI_prepare_cursor(const char *src, int nargs, Oid *argtypes, int cursorOptions)
Definition: spi.c:866
int SPI_execute_plan_with_paramlist(SPIPlanPtr plan, ParamListInfo params, bool read_only, long tcount)
Definition: spi.c:733
void SPI_cursor_move(Portal portal, bool forward, long count)
Definition: spi.c:1821
PGDLLIMPORT uint64 SPI_processed
Definition: spi.c:44
void SPI_freetuple(HeapTuple tuple)
Definition: spi.c:1379
int SPI_fnumber(TupleDesc tupdesc, const char *fname)
Definition: spi.c:1175
bool SPI_plan_is_valid(SPIPlanPtr plan)
Definition: spi.c:1948
void SPI_commit_and_chain(void)
Definition: spi.c:326
bool SPI_is_cursor_plan(SPIPlanPtr plan)
Definition: spi.c:1910
char * SPI_gettype(TupleDesc tupdesc, int fnumber)
Definition: spi.c:1268
void * SPI_repalloc(void *pointer, Size size)
Definition: spi.c:1347
SPIPlanPtr SPI_prepare_extended(const char *src, const SPIPrepareOptions *options)
Definition: spi.c:902
Oid SPI_gettypeid(TupleDesc tupdesc, int fnumber)
Definition: spi.c:1308
void SPI_scroll_cursor_fetch(Portal, FetchDirection direction, long count)
Definition: spi.c:1835
HeapTupleHeader SPI_returntuple(HeapTuple tuple, TupleDesc tupdesc)
Definition: spi.c:1074
int SPI_freeplan(SPIPlanPtr plan)
Definition: spi.c:1025
const char * SPI_result_code_string(int code)
Definition: spi.c:1972
void SPI_rollback_and_chain(void)
Definition: spi.c:419
Portal SPI_cursor_find(const char *name)
Definition: spi.c:1794
int SPI_unregister_relation(const char *name)
Definition: spi.c:3331
bool SPI_inside_nonatomic_context(void)
Definition: spi.c:581
int SPI_connect(void)
Definition: spi.c:94
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:773
int SPI_execute_plan_extended(SPIPlanPtr plan, const SPIExecuteOptions *options)
Definition: spi.c:711
SPIPlanPtr SPI_prepare_params(const char *src, ParserSetupHook parserSetup, void *parserSetupArg, int cursorOptions)
Definition: spi.c:938
SPIPlanPtr SPI_saveplan(SPIPlanPtr plan)
Definition: spi.c:1003
void SPI_cursor_fetch(Portal portal, bool forward, long count)
Definition: spi.c:1806
Portal SPI_cursor_parse_open(const char *name, const char *src, const SPIParseOpenOptions *options)
Definition: spi.c:1533
int SPI_finish(void)
Definition: spi.c:182
int SPI_execute_plan(SPIPlanPtr plan, Datum *Values, const char *Nulls, bool read_only, long tcount)
Definition: spi.c:672
Datum SPI_datumTransfer(Datum value, bool typByVal, int typLen)
Definition: spi.c:1361
CachedPlan * SPI_plan_get_cached_plan(SPIPlanPtr plan)
Definition: spi.c:2076
PGDLLIMPORT int SPI_result
Definition: spi.c:46
int SPI_register_trigger_data(TriggerData *tdata)
Definition: spi.c:3364
Portal SPI_cursor_open_with_paramlist(const char *name, SPIPlanPtr plan, ParamListInfo params, bool read_only)
Definition: spi.c:1525
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:1472
void SPI_freetuptable(SPITupleTable *tuptable)
Definition: spi.c:1386
Portal SPI_cursor_open(const char *name, SPIPlanPtr plan, Datum *Values, const char *Nulls, bool read_only)
Definition: spi.c:1445
struct SPIPrepareOptions SPIPrepareOptions
PGDLLIMPORT SPITupleTable * SPI_tuptable
Definition: spi.c:45
int SPI_exec(const char *src, long tcount)
Definition: spi.c:630
int SPI_register_relation(EphemeralNamedRelation enr)
Definition: spi.c:3297
HeapTuple SPI_modifytuple(Relation rel, HeapTuple tuple, int natts, int *attnum, Datum *Values, const char *Nulls)
Definition: spi.c:1106
SPIPlanPtr SPI_prepare(const char *src, int nargs, Oid *argtypes)
Definition: spi.c:860
int SPI_keepplan(SPIPlanPtr plan)
Definition: spi.c:976
void SPI_cursor_close(Portal portal)
Definition: spi.c:1862
void SPI_pfree(void *pointer)
Definition: spi.c:1354
int SPI_connect_ext(int options)
Definition: spi.c:100
int SPI_execp(SPIPlanPtr plan, Datum *Values, const char *Nulls, long tcount)
Definition: spi.c:704
char * SPI_getvalue(HeapTuple tuple, TupleDesc tupdesc, int fnumber)
Definition: spi.c:1220
char * SPI_getnspname(Relation rel)
Definition: spi.c:1332
struct _SPI_plan * SPIPlanPtr
Definition: spi.h:66
int SPI_execute_extended(const char *src, const SPIExecuteOptions *options)
Definition: spi.c:637
void SPI_rollback(void)
Definition: spi.c:413
struct SPIParseOpenOptions SPIParseOpenOptions
struct SPIExecuteOptions SPIExecuteOptions
void SPI_scroll_cursor_move(Portal, FetchDirection direction, long count)
Definition: spi.c:1850
void * SPI_palloc(Size size)
Definition: spi.c:1338
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:812
void SPI_start_transaction(void)
Definition: spi.c:222
HeapTuple SPI_copytuple(HeapTuple tuple)
Definition: spi.c:1047
int SPI_getargcount(SPIPlanPtr plan)
Definition: spi.c:1890
void AtEOXact_SPI(bool isCommit)
Definition: spi.c:428
int SPI_execute(const char *src, bool read_only, long tcount)
Definition: spi.c:596
Datum SPI_getbinval(HeapTuple tuple, TupleDesc tupdesc, int fnumber, bool *isnull)
Definition: spi.c:1252
char * SPI_getrelname(Relation rel)
Definition: spi.c:1326
char * SPI_fname(TupleDesc tupdesc, int fnumber)
Definition: spi.c:1198
Oid SPI_getargtypeid(SPIPlanPtr plan, int argIndex)
Definition: spi.c:1875
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