PostgreSQL Source Code  git master
fdwapi.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * fdwapi.h
4  * API for foreign-data wrappers
5  *
6  * Copyright (c) 2010-2024, PostgreSQL Global Development Group
7  *
8  * src/include/foreign/fdwapi.h
9  *
10  *-------------------------------------------------------------------------
11  */
12 #ifndef FDWAPI_H
13 #define FDWAPI_H
14 
15 #include "access/parallel.h"
16 #include "nodes/execnodes.h"
17 #include "nodes/pathnodes.h"
18 
19 /* To avoid including explain.h here, reference ExplainState thus: */
20 struct ExplainState;
21 
22 
23 /*
24  * Callback function signatures --- see fdwhandler.sgml for more info.
25  */
26 
28  RelOptInfo *baserel,
29  Oid foreigntableid);
30 
32  RelOptInfo *baserel,
33  Oid foreigntableid);
34 
35 typedef ForeignScan *(*GetForeignPlan_function) (PlannerInfo *root,
36  RelOptInfo *baserel,
37  Oid foreigntableid,
38  ForeignPath *best_path,
39  List *tlist,
40  List *scan_clauses,
41  Plan *outer_plan);
42 
44  int eflags);
45 
46 typedef TupleTableSlot *(*IterateForeignScan_function) (ForeignScanState *node);
47 
49  TupleTableSlot *slot);
50 
52 
53 typedef void (*EndForeignScan_function) (ForeignScanState *node);
54 
56  RelOptInfo *joinrel,
57  RelOptInfo *outerrel,
58  RelOptInfo *innerrel,
59  JoinType jointype,
60  JoinPathExtraData *extra);
61 
63  UpperRelationKind stage,
64  RelOptInfo *input_rel,
65  RelOptInfo *output_rel,
66  void *extra);
67 
69  Index rtindex,
70  RangeTblEntry *target_rte,
71  Relation target_relation);
72 
73 typedef List *(*PlanForeignModify_function) (PlannerInfo *root,
75  Index resultRelation,
76  int subplan_index);
77 
79  ResultRelInfo *rinfo,
80  List *fdw_private,
81  int subplan_index,
82  int eflags);
83 
84 typedef TupleTableSlot *(*ExecForeignInsert_function) (EState *estate,
85  ResultRelInfo *rinfo,
86  TupleTableSlot *slot,
87  TupleTableSlot *planSlot);
88 
89 typedef TupleTableSlot **(*ExecForeignBatchInsert_function) (EState *estate,
90  ResultRelInfo *rinfo,
91  TupleTableSlot **slots,
92  TupleTableSlot **planSlots,
93  int *numSlots);
94 
96 
97 typedef TupleTableSlot *(*ExecForeignUpdate_function) (EState *estate,
98  ResultRelInfo *rinfo,
99  TupleTableSlot *slot,
100  TupleTableSlot *planSlot);
101 
102 typedef TupleTableSlot *(*ExecForeignDelete_function) (EState *estate,
103  ResultRelInfo *rinfo,
104  TupleTableSlot *slot,
105  TupleTableSlot *planSlot);
106 
107 typedef void (*EndForeignModify_function) (EState *estate,
108  ResultRelInfo *rinfo);
109 
111  ResultRelInfo *rinfo);
112 
113 typedef void (*EndForeignInsert_function) (EState *estate,
114  ResultRelInfo *rinfo);
115 
117 
119  ModifyTable *plan,
120  Index resultRelation,
121  int subplan_index);
122 
124  int eflags);
125 
126 typedef TupleTableSlot *(*IterateDirectModify_function) (ForeignScanState *node);
127 
129 
131  LockClauseStrength strength);
132 
133 typedef void (*RefetchForeignRow_function) (EState *estate,
134  ExecRowMark *erm,
135  Datum rowid,
136  TupleTableSlot *slot,
137  bool *updated);
138 
140  struct ExplainState *es);
141 
143  ResultRelInfo *rinfo,
144  List *fdw_private,
145  int subplan_index,
146  struct ExplainState *es);
147 
149  struct ExplainState *es);
150 
151 typedef int (*AcquireSampleRowsFunc) (Relation relation, int elevel,
152  HeapTuple *rows, int targrows,
153  double *totalrows,
154  double *totaldeadrows);
155 
156 typedef bool (*AnalyzeForeignTable_function) (Relation relation,
157  AcquireSampleRowsFunc *func,
158  BlockNumber *totalpages);
159 
160 typedef List *(*ImportForeignSchema_function) (ImportForeignSchemaStmt *stmt,
161  Oid serverOid);
162 
163 typedef void (*ExecForeignTruncate_function) (List *rels,
164  DropBehavior behavior,
165  bool restart_seqs);
166 
168  ParallelContext *pcxt);
170  ParallelContext *pcxt,
171  void *coordinate);
173  ParallelContext *pcxt,
174  void *coordinate);
176  shm_toc *toc,
177  void *coordinate);
180  RelOptInfo *rel,
181  RangeTblEntry *rte);
182 typedef List *(*ReparameterizeForeignPathByChild_function) (PlannerInfo *root,
183  List *fdw_private,
184  RelOptInfo *child_rel);
185 
187 
189 
191 
193 
194 /*
195  * FdwRoutine is the struct returned by a foreign-data wrapper's handler
196  * function. It provides pointers to the callback functions needed by the
197  * planner and executor.
198  *
199  * More function pointers are likely to be added in the future. Therefore
200  * it's recommended that the handler initialize the struct with
201  * makeNode(FdwRoutine) so that all fields are set to NULL. This will
202  * ensure that no fields are accidentally left undefined.
203  */
204 typedef struct FdwRoutine
205 {
207 
208  /* Functions for scanning foreign tables */
216 
217  /*
218  * Remaining functions are optional. Set the pointer to NULL for any that
219  * are not provided.
220  */
221 
222  /* Functions for remote-join planning */
224 
225  /* Functions for remote upper-relation (post scan/join) planning */
227 
228  /* Functions for updating foreign tables */
245 
246  /* Functions for SELECT FOR UPDATE/SHARE row locking */
250 
251  /* Support functions for EXPLAIN */
255 
256  /* Support functions for ANALYZE */
258 
259  /* Support functions for IMPORT FOREIGN SCHEMA */
261 
262  /* Support functions for TRUNCATE */
264 
265  /* Support functions for parallelism under Gather node */
272 
273  /* Support functions for path reparameterization. */
275 
276  /* Support functions for asynchronous execution */
282 
283 
284 /* Functions in foreign/foreign.c */
285 extern FdwRoutine *GetFdwRoutine(Oid fdwhandler);
286 extern Oid GetForeignServerIdByRelId(Oid relid);
287 extern FdwRoutine *GetFdwRoutineByServerId(Oid serverid);
288 extern FdwRoutine *GetFdwRoutineByRelId(Oid relid);
289 extern FdwRoutine *GetFdwRoutineForRelation(Relation relation, bool makecopy);
290 extern bool IsImportableForeignTable(const char *tablename,
292 extern Path *GetExistingLocalJoinPath(RelOptInfo *joinrel);
293 
294 #endif /* FDWAPI_H */
uint32 BlockNumber
Definition: block.h:31
unsigned int Index
Definition: c.h:593
size_t Size
Definition: c.h:584
void(* ForeignAsyncConfigureWait_function)(AsyncRequest *areq)
Definition: fdwapi.h:190
int(* AcquireSampleRowsFunc)(Relation relation, int elevel, HeapTuple *rows, int targrows, double *totalrows, double *totaldeadrows)
Definition: fdwapi.h:151
Size(* EstimateDSMForeignScan_function)(ForeignScanState *node, ParallelContext *pcxt)
Definition: fdwapi.h:167
TupleTableSlot *(* IterateForeignScan_function)(ForeignScanState *node)
Definition: fdwapi.h:46
void(* EndForeignScan_function)(ForeignScanState *node)
Definition: fdwapi.h:53
TupleTableSlot **(* ExecForeignBatchInsert_function)(EState *estate, ResultRelInfo *rinfo, TupleTableSlot **slots, TupleTableSlot **planSlots, int *numSlots)
Definition: fdwapi.h:89
TupleTableSlot *(* IterateDirectModify_function)(ForeignScanState *node)
Definition: fdwapi.h:126
void(* BeginForeignModify_function)(ModifyTableState *mtstate, ResultRelInfo *rinfo, List *fdw_private, int subplan_index, int eflags)
Definition: fdwapi.h:78
ForeignScan *(* GetForeignPlan_function)(PlannerInfo *root, RelOptInfo *baserel, Oid foreigntableid, ForeignPath *best_path, List *tlist, List *scan_clauses, Plan *outer_plan)
Definition: fdwapi.h:35
FdwRoutine * GetFdwRoutineByRelId(Oid relid)
Definition: foreign.c:419
bool(* IsForeignPathAsyncCapable_function)(ForeignPath *path)
Definition: fdwapi.h:186
List *(* ReparameterizeForeignPathByChild_function)(PlannerInfo *root, List *fdw_private, RelOptInfo *child_rel)
Definition: fdwapi.h:182
void(* BeginForeignScan_function)(ForeignScanState *node, int eflags)
Definition: fdwapi.h:43
void(* GetForeignUpperPaths_function)(PlannerInfo *root, UpperRelationKind stage, RelOptInfo *input_rel, RelOptInfo *output_rel, void *extra)
Definition: fdwapi.h:62
TupleTableSlot *(* ExecForeignDelete_function)(EState *estate, ResultRelInfo *rinfo, TupleTableSlot *slot, TupleTableSlot *planSlot)
Definition: fdwapi.h:102
Path * GetExistingLocalJoinPath(RelOptInfo *joinrel)
Definition: foreign.c:741
void(* EndForeignModify_function)(EState *estate, ResultRelInfo *rinfo)
Definition: fdwapi.h:107
void(* BeginDirectModify_function)(ForeignScanState *node, int eflags)
Definition: fdwapi.h:123
bool(* AnalyzeForeignTable_function)(Relation relation, AcquireSampleRowsFunc *func, BlockNumber *totalpages)
Definition: fdwapi.h:156
bool(* PlanDirectModify_function)(PlannerInfo *root, ModifyTable *plan, Index resultRelation, int subplan_index)
Definition: fdwapi.h:118
void(* AddForeignUpdateTargets_function)(PlannerInfo *root, Index rtindex, RangeTblEntry *target_rte, Relation target_relation)
Definition: fdwapi.h:68
void(* ForeignAsyncRequest_function)(AsyncRequest *areq)
Definition: fdwapi.h:188
void(* RefetchForeignRow_function)(EState *estate, ExecRowMark *erm, Datum rowid, TupleTableSlot *slot, bool *updated)
Definition: fdwapi.h:133
void(* ExecForeignTruncate_function)(List *rels, DropBehavior behavior, bool restart_seqs)
Definition: fdwapi.h:163
void(* InitializeDSMForeignScan_function)(ForeignScanState *node, ParallelContext *pcxt, void *coordinate)
Definition: fdwapi.h:169
int(* GetForeignModifyBatchSize_function)(ResultRelInfo *rinfo)
Definition: fdwapi.h:95
RowMarkType(* GetForeignRowMarkType_function)(RangeTblEntry *rte, LockClauseStrength strength)
Definition: fdwapi.h:130
FdwRoutine * GetFdwRoutineForRelation(Relation relation, bool makecopy)
Definition: foreign.c:442
FdwRoutine * GetFdwRoutine(Oid fdwhandler)
Definition: foreign.c:325
void(* ShutdownForeignScan_function)(ForeignScanState *node)
Definition: fdwapi.h:178
void(* BeginForeignInsert_function)(ModifyTableState *mtstate, ResultRelInfo *rinfo)
Definition: fdwapi.h:110
List *(* ImportForeignSchema_function)(ImportForeignSchemaStmt *stmt, Oid serverOid)
Definition: fdwapi.h:160
void(* ReScanForeignScan_function)(ForeignScanState *node)
Definition: fdwapi.h:51
void(* ExplainForeignScan_function)(ForeignScanState *node, struct ExplainState *es)
Definition: fdwapi.h:139
bool(* RecheckForeignScan_function)(ForeignScanState *node, TupleTableSlot *slot)
Definition: fdwapi.h:48
void(* GetForeignRelSize_function)(PlannerInfo *root, RelOptInfo *baserel, Oid foreigntableid)
Definition: fdwapi.h:27
bool(* IsForeignScanParallelSafe_function)(PlannerInfo *root, RelOptInfo *rel, RangeTblEntry *rte)
Definition: fdwapi.h:179
Oid GetForeignServerIdByRelId(Oid relid)
Definition: foreign.c:355
void(* ReInitializeDSMForeignScan_function)(ForeignScanState *node, ParallelContext *pcxt, void *coordinate)
Definition: fdwapi.h:172
FdwRoutine * GetFdwRoutineByServerId(Oid serverid)
Definition: foreign.c:377
bool IsImportableForeignTable(const char *tablename, ImportForeignSchemaStmt *stmt)
Definition: foreign.c:482
void(* GetForeignPaths_function)(PlannerInfo *root, RelOptInfo *baserel, Oid foreigntableid)
Definition: fdwapi.h:31
void(* GetForeignJoinPaths_function)(PlannerInfo *root, RelOptInfo *joinrel, RelOptInfo *outerrel, RelOptInfo *innerrel, JoinType jointype, JoinPathExtraData *extra)
Definition: fdwapi.h:55
TupleTableSlot *(* ExecForeignInsert_function)(EState *estate, ResultRelInfo *rinfo, TupleTableSlot *slot, TupleTableSlot *planSlot)
Definition: fdwapi.h:84
TupleTableSlot *(* ExecForeignUpdate_function)(EState *estate, ResultRelInfo *rinfo, TupleTableSlot *slot, TupleTableSlot *planSlot)
Definition: fdwapi.h:97
void(* ExplainDirectModify_function)(ForeignScanState *node, struct ExplainState *es)
Definition: fdwapi.h:148
List *(* PlanForeignModify_function)(PlannerInfo *root, ModifyTable *plan, Index resultRelation, int subplan_index)
Definition: fdwapi.h:73
int(* IsForeignRelUpdatable_function)(Relation rel)
Definition: fdwapi.h:116
struct FdwRoutine FdwRoutine
void(* ExplainForeignModify_function)(ModifyTableState *mtstate, ResultRelInfo *rinfo, List *fdw_private, int subplan_index, struct ExplainState *es)
Definition: fdwapi.h:142
void(* EndDirectModify_function)(ForeignScanState *node)
Definition: fdwapi.h:128
void(* EndForeignInsert_function)(EState *estate, ResultRelInfo *rinfo)
Definition: fdwapi.h:113
void(* ForeignAsyncNotify_function)(AsyncRequest *areq)
Definition: fdwapi.h:192
void(* InitializeWorkerForeignScan_function)(ForeignScanState *node, shm_toc *toc, void *coordinate)
Definition: fdwapi.h:175
#define stmt
Definition: indent_codes.h:59
LockClauseStrength
Definition: lockoptions.h:22
NodeTag
Definition: nodes.h:27
JoinType
Definition: nodes.h:288
DropBehavior
Definition: parsenodes.h:2340
UpperRelationKind
Definition: pathnodes.h:70
#define plan(x)
Definition: pg_regress.c:161
RowMarkType
Definition: plannodes.h:1329
uintptr_t Datum
Definition: postgres.h:64
unsigned int Oid
Definition: postgres_ext.h:31
tree ctl root
Definition: radixtree.h:1886
EstimateDSMForeignScan_function EstimateDSMForeignScan
Definition: fdwapi.h:267
EndForeignInsert_function EndForeignInsert
Definition: fdwapi.h:239
ReScanForeignScan_function ReScanForeignScan
Definition: fdwapi.h:214
BeginForeignInsert_function BeginForeignInsert
Definition: fdwapi.h:238
RecheckForeignScan_function RecheckForeignScan
Definition: fdwapi.h:249
AddForeignUpdateTargets_function AddForeignUpdateTargets
Definition: fdwapi.h:229
InitializeDSMForeignScan_function InitializeDSMForeignScan
Definition: fdwapi.h:268
BeginForeignModify_function BeginForeignModify
Definition: fdwapi.h:231
EndForeignModify_function EndForeignModify
Definition: fdwapi.h:237
BeginDirectModify_function BeginDirectModify
Definition: fdwapi.h:242
PlanForeignModify_function PlanForeignModify
Definition: fdwapi.h:230
PlanDirectModify_function PlanDirectModify
Definition: fdwapi.h:241
ExecForeignInsert_function ExecForeignInsert
Definition: fdwapi.h:232
BeginForeignScan_function BeginForeignScan
Definition: fdwapi.h:212
ForeignAsyncRequest_function ForeignAsyncRequest
Definition: fdwapi.h:278
IterateDirectModify_function IterateDirectModify
Definition: fdwapi.h:243
ExecForeignUpdate_function ExecForeignUpdate
Definition: fdwapi.h:235
RefetchForeignRow_function RefetchForeignRow
Definition: fdwapi.h:248
GetForeignJoinPaths_function GetForeignJoinPaths
Definition: fdwapi.h:223
IsForeignScanParallelSafe_function IsForeignScanParallelSafe
Definition: fdwapi.h:266
NodeTag type
Definition: fdwapi.h:206
ExecForeignBatchInsert_function ExecForeignBatchInsert
Definition: fdwapi.h:233
GetForeignPaths_function GetForeignPaths
Definition: fdwapi.h:210
GetForeignModifyBatchSize_function GetForeignModifyBatchSize
Definition: fdwapi.h:234
GetForeignRelSize_function GetForeignRelSize
Definition: fdwapi.h:209
GetForeignRowMarkType_function GetForeignRowMarkType
Definition: fdwapi.h:247
ExplainForeignScan_function ExplainForeignScan
Definition: fdwapi.h:252
EndForeignScan_function EndForeignScan
Definition: fdwapi.h:215
AnalyzeForeignTable_function AnalyzeForeignTable
Definition: fdwapi.h:257
EndDirectModify_function EndDirectModify
Definition: fdwapi.h:244
ExplainForeignModify_function ExplainForeignModify
Definition: fdwapi.h:253
ReInitializeDSMForeignScan_function ReInitializeDSMForeignScan
Definition: fdwapi.h:269
IsForeignPathAsyncCapable_function IsForeignPathAsyncCapable
Definition: fdwapi.h:277
IterateForeignScan_function IterateForeignScan
Definition: fdwapi.h:213
ForeignAsyncNotify_function ForeignAsyncNotify
Definition: fdwapi.h:280
InitializeWorkerForeignScan_function InitializeWorkerForeignScan
Definition: fdwapi.h:270
ImportForeignSchema_function ImportForeignSchema
Definition: fdwapi.h:260
GetForeignPlan_function GetForeignPlan
Definition: fdwapi.h:211
ShutdownForeignScan_function ShutdownForeignScan
Definition: fdwapi.h:271
ExecForeignDelete_function ExecForeignDelete
Definition: fdwapi.h:236
ExecForeignTruncate_function ExecForeignTruncate
Definition: fdwapi.h:263
ExplainDirectModify_function ExplainDirectModify
Definition: fdwapi.h:254
IsForeignRelUpdatable_function IsForeignRelUpdatable
Definition: fdwapi.h:240
GetForeignUpperPaths_function GetForeignUpperPaths
Definition: fdwapi.h:226
ForeignAsyncConfigureWait_function ForeignAsyncConfigureWait
Definition: fdwapi.h:279
ReparameterizeForeignPathByChild_function ReparameterizeForeignPathByChild
Definition: fdwapi.h:274
Definition: pg_list.h:54