1/*-------------------------------------------------------------------------
2 *
3 * portal.h
4 * POSTGRES portal definitions.
5 *
6 * A portal is an abstraction which represents the execution state of
7 * a running or runnable query. Portals support both SQL-level CURSORs
8 * and protocol-level portals.
9 *
10 * Scrolling (nonsequential access) and suspension of execution are allowed
11 * only for portals that contain a single SELECT-type query. We do not want
12 * to let the client suspend an update-type query partway through! Because
13 * the query rewriter does not allow arbitrary ON SELECT rewrite rules,
14 * only queries that were originally update-type could produce multiple
15 * plan trees; so the restriction to a single query is not a problem
16 * in practice.
17 *
18 * For SQL cursors, we support three kinds of scroll behavior:
19 *
20 * (1) Neither NO SCROLL nor SCROLL was specified: to remain backward
21 * compatible, we allow backward fetches here, unless it would
22 * impose additional runtime overhead to do so.
23 *
24 * (2) NO SCROLL was specified: don't allow any backward fetches.
25 *
26 * (3) SCROLL was specified: allow all kinds of backward fetches, even
27 * if we need to take a performance hit to do so. (The planner sticks
28 * a Materialize node atop the query plan if needed.)
29 *
30 * Case #1 is converted to #2 or #3 by looking at the query itself and
31 * determining if scrollability can be supported without additional
32 * overhead.
33 *
34 * Protocol-level portals have no nonsequential-fetch API and so the
35 * distinction doesn't matter for them. They are always initialized
36 * to look like NO SCROLL cursors.
37 *
38 *
39 * Portions Copyright (c) 1996-2019, PostgreSQL Global Development Group
40 * Portions Copyright (c) 1994, Regents of the University of California
41 *
42 * src/include/utils/portal.h
43 *
44 *-------------------------------------------------------------------------
45 */
46#ifndef PORTAL_H
47#define PORTAL_H
48
49#include "datatype/timestamp.h"
50#include "executor/execdesc.h"
51#include "utils/plancache.h"
52#include "utils/resowner.h"
53
54/*
55 * We have several execution strategies for Portals, depending on what
56 * query or queries are to be executed. (Note: in all cases, a Portal
57 * executes just a single source-SQL query, and thus produces just a
58 * single result from the user's viewpoint. However, the rule rewriter
59 * may expand the single source query to zero or many actual queries.)
60 *
61 * PORTAL_ONE_SELECT: the portal contains one single SELECT query. We run
62 * the Executor incrementally as results are demanded. This strategy also
63 * supports holdable cursors (the Executor results can be dumped into a
64 * tuplestore for access after transaction completion).
65 *
66 * PORTAL_ONE_RETURNING: the portal contains a single INSERT/UPDATE/DELETE
67 * query with a RETURNING clause (plus possibly auxiliary queries added by
68 * rule rewriting). On first execution, we run the portal to completion
69 * and dump the primary query's results into the portal tuplestore; the
70 * results are then returned to the client as demanded. (We can't support
71 * suspension of the query partway through, because the AFTER TRIGGER code
72 * can't cope, and also because we don't want to risk failing to execute
73 * all the auxiliary queries.)
74 *
75 * PORTAL_ONE_MOD_WITH: the portal contains one single SELECT query, but
76 * it has data-modifying CTEs. This is currently treated the same as the
77 * PORTAL_ONE_RETURNING case because of the possibility of needing to fire
78 * triggers. It may act more like PORTAL_ONE_SELECT in future.
79 *
80 * PORTAL_UTIL_SELECT: the portal contains a utility statement that returns
81 * a SELECT-like result (for example, EXPLAIN or SHOW). On first execution,
82 * we run the statement and dump its results into the portal tuplestore;
83 * the results are then returned to the client as demanded.
84 *
85 * PORTAL_MULTI_QUERY: all other cases. Here, we do not support partial
86 * execution: the portal's queries will be run to completion on first call.
87 */
88typedef enum PortalStrategy
89{
90 PORTAL_ONE_SELECT,
91 PORTAL_ONE_RETURNING,
92 PORTAL_ONE_MOD_WITH,
93 PORTAL_UTIL_SELECT,
94 PORTAL_MULTI_QUERY
95} PortalStrategy;
96
97/*
98 * A portal is always in one of these states. It is possible to transit
99 * from ACTIVE back to READY if the query is not run to completion;
100 * otherwise we never back up in status.
101 */
102typedef enum PortalStatus
103{
104 PORTAL_NEW, /* freshly created */
105 PORTAL_DEFINED, /* PortalDefineQuery done */
106 PORTAL_READY, /* PortalStart complete, can run it */
107 PORTAL_ACTIVE, /* portal is running (can't delete it) */
108 PORTAL_DONE, /* portal is finished (don't re-run it) */
109 PORTAL_FAILED /* portal got error (can't re-run it) */
110} PortalStatus;
111
112typedef struct PortalData *Portal;
113
114typedef struct PortalData
115{
116 /* Bookkeeping data */
117 const char *name; /* portal's name */
118 const char *prepStmtName; /* source prepared statement (NULL if none) */
119 MemoryContext portalContext; /* subsidiary memory for portal */
120 ResourceOwner resowner; /* resources owned by portal */
121 void (*cleanup) (Portal portal); /* cleanup hook */
122
123 /*
124 * State data for remembering which subtransaction(s) the portal was
125 * created or used in. If the portal is held over from a previous
126 * transaction, both subxids are InvalidSubTransactionId. Otherwise,
127 * createSubid is the creating subxact and activeSubid is the last subxact
128 * in which we ran the portal.
129 */
130 SubTransactionId createSubid; /* the creating subxact */
131 SubTransactionId activeSubid; /* the last subxact with activity */
132
133 /* The query or queries the portal will execute */
134 const char *sourceText; /* text of query (as of 8.4, never NULL) */
135 const char *commandTag; /* command tag for original query */
136 List *stmts; /* list of PlannedStmts */
137 CachedPlan *cplan; /* CachedPlan, if stmts are from one */
138
139 ParamListInfo portalParams; /* params to pass to query */
140 QueryEnvironment *queryEnv; /* environment for query */
141
142 /* Features/options */
143 PortalStrategy strategy; /* see above */
144 int cursorOptions; /* DECLARE CURSOR option bits */
145 bool run_once; /* portal will only be run once */
146
147 /* Status data */
148 PortalStatus status; /* see above */
149 bool portalPinned; /* a pinned portal can't be dropped */
150 bool autoHeld; /* was automatically converted from pinned to
151 * held (see HoldPinnedPortals()) */
152
153 /* If not NULL, Executor is active; call ExecutorEnd eventually: */
154 QueryDesc *queryDesc; /* info needed for executor invocation */
155
156 /* If portal returns tuples, this is their tupdesc: */
157 TupleDesc tupDesc; /* descriptor for result tuples */
158 /* and these are the format codes to use for the columns: */
159 int16 *formats; /* a format code for each column */
160
161 /*
162 * Where we store tuples for a held cursor or a PORTAL_ONE_RETURNING or
163 * PORTAL_UTIL_SELECT query. (A cursor held past the end of its
164 * transaction no longer has any active executor state.)
165 */
166 Tuplestorestate *holdStore; /* store for holdable cursors */
167 MemoryContext holdContext; /* memory containing holdStore */
168
169 /*
170 * Snapshot under which tuples in the holdStore were read. We must keep a
171 * reference to this snapshot if there is any possibility that the tuples
172 * contain TOAST references, because releasing the snapshot could allow
173 * recently-dead rows to be vacuumed away, along with any toast data
174 * belonging to them. In the case of a held cursor, we avoid needing to
175 * keep such a snapshot by forcibly detoasting the data.
176 */
177 Snapshot holdSnapshot; /* registered snapshot, or NULL if none */
178
179 /*
180 * atStart, atEnd and portalPos indicate the current cursor position.
181 * portalPos is zero before the first row, N after fetching N'th row of
182 * query. After we run off the end, portalPos = # of rows in query, and
183 * atEnd is true. Note that atStart implies portalPos == 0, but not the
184 * reverse: we might have backed up only as far as the first row, not to
185 * the start. Also note that various code inspects atStart and atEnd, but
186 * only the portal movement routines should touch portalPos.
187 */
188 bool atStart;
189 bool atEnd;
190 uint64 portalPos;
191
192 /* Presentation data, primarily used by the pg_cursors system view */
193 TimestampTz creation_time; /* time at which this portal was defined */
194 bool visible; /* include this portal in pg_cursors? */
195} PortalData;
196
197/*
198 * PortalIsValid
199 * True iff portal is valid.
200 */
201#define PortalIsValid(p) PointerIsValid(p)
202
203
204/* Prototypes for functions in utils/mmgr/portalmem.c */
205extern void EnablePortalManager(void);
206extern bool PreCommit_Portals(bool isPrepare);
207extern void AtAbort_Portals(void);
208extern void AtCleanup_Portals(void);
209extern void PortalErrorCleanup(void);
210extern void AtSubCommit_Portals(SubTransactionId mySubid,
211 SubTransactionId parentSubid,
212 ResourceOwner parentXactOwner);
213extern void AtSubAbort_Portals(SubTransactionId mySubid,
214 SubTransactionId parentSubid,
215 ResourceOwner myXactOwner,
216 ResourceOwner parentXactOwner);
217extern void AtSubCleanup_Portals(SubTransactionId mySubid);
218extern Portal CreatePortal(const char *name, bool allowDup, bool dupSilent);
219extern Portal CreateNewPortal(void);
220extern void PinPortal(Portal portal);
221extern void UnpinPortal(Portal portal);
222extern void MarkPortalActive(Portal portal);
223extern void MarkPortalDone(Portal portal);
224extern void MarkPortalFailed(Portal portal);
225extern void PortalDrop(Portal portal, bool isTopCommit);
226extern Portal GetPortalByName(const char *name);
227extern void PortalDefineQuery(Portal portal,
228 const char *prepStmtName,
229 const char *sourceText,
230 const char *commandTag,
231 List *stmts,
232 CachedPlan *cplan);
233extern PlannedStmt *PortalGetPrimaryStmt(Portal portal);
234extern void PortalCreateHoldStore(Portal portal);
235extern void PortalHashTableDeleteAll(void);
236extern bool ThereAreNoReadyPortals(void);
237extern void HoldPinnedPortals(void);
238
239#endif /* PORTAL_H */
240