1 /*-------------------------------------------------------------------------
4 * POSTGRES portal definitions.
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.
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
18 * For SQL cursors, we support three kinds of scroll behavior:
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.
24 * (2) NO SCROLL was specified: don't allow any backward fetches.
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.)
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
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.
39 * Portions Copyright (c) 1996-2014, PostgreSQL Global Development Group
40 * Portions Copyright (c) 1994, Regents of the University of California
42 * src/include/utils/portal.h
44 *-------------------------------------------------------------------------
49 #include "datatype/timestamp.h"
50 #include "executor/execdesc.h"
51 #include "utils/plancache.h"
52 #include "utils/resowner.h"
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.)
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).
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.)
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.
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.
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.
88 typedef enum PortalStrategy
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.
102 typedef enum PortalStatus
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) */
112 typedef struct PortalData *Portal;
114 typedef struct PortalData
116 /* Bookkeeping data */
117 const char *name; /* portal's name */
118 const char *prepStmtName; /* source prepared statement (NULL if none) */
119 MemoryContext heap; /* subsidiary memory for portal */
120 ResourceOwner resowner; /* resources owned by portal */
121 void (*cleanup) (Portal portal); /* cleanup hook */
122 SubTransactionId createSubid; /* the ID of the creating subxact */
125 * if createSubid is InvalidSubTransactionId, the portal is held over from
126 * a previous transaction
129 /* The query or queries the portal will execute */
130 const char *sourceText; /* text of query (as of 8.4, never NULL) */
131 const char *commandTag; /* command tag for original query */
132 List *stmts; /* PlannedStmts and/or utility statements */
133 CachedPlan *cplan; /* CachedPlan, if stmts are from one */
135 ParamListInfo portalParams; /* params to pass to query */
137 /* Features/options */
138 PortalStrategy strategy; /* see above */
139 int cursorOptions; /* DECLARE CURSOR option bits */
142 PortalStatus status; /* see above */
143 bool portalPinned; /* a pinned portal can't be dropped */
145 /* If not NULL, Executor is active; call ExecutorEnd eventually: */
146 QueryDesc *queryDesc; /* info needed for executor invocation */
148 /* If portal returns tuples, this is their tupdesc: */
149 TupleDesc tupDesc; /* descriptor for result tuples */
150 /* and these are the format codes to use for the columns: */
151 int16 *formats; /* a format code for each column */
154 * Where we store tuples for a held cursor or a PORTAL_ONE_RETURNING or
155 * PORTAL_UTIL_SELECT query. (A cursor held past the end of its
156 * transaction no longer has any active executor state.)
158 Tuplestorestate *holdStore; /* store for holdable cursors */
159 MemoryContext holdContext; /* memory containing holdStore */
162 * atStart, atEnd and portalPos indicate the current cursor position.
163 * portalPos is zero before the first row, N after fetching N'th row of
164 * query. After we run off the end, portalPos = # of rows in query, and
165 * atEnd is true. If portalPos overflows, set posOverflow (this causes us
166 * to stop relying on its value for navigation). Note that atStart
167 * implies portalPos == 0, but not the reverse (portalPos could have
175 /* Presentation data, primarily used by the pg_cursors system view */
176 TimestampTz creation_time; /* time at which this portal was defined */
177 bool visible; /* include this portal in pg_cursors? */
182 * True iff portal is valid.
184 #define PortalIsValid(p) PointerIsValid(p)
187 * Access macros for Portal ... use these in preference to field access.
189 #define PortalGetQueryDesc(portal) ((portal)->queryDesc)
190 #define PortalGetHeapMemory(portal) ((portal)->heap)
191 #define PortalGetPrimaryStmt(portal) PortalListGetPrimaryStmt((portal)->stmts)
194 /* Prototypes for functions in utils/mmgr/portalmem.c */
195 extern void EnablePortalManager(void);
196 extern bool PreCommit_Portals(bool isPrepare);
197 extern void AtAbort_Portals(void);
198 extern void AtCleanup_Portals(void);
199 extern void AtSubCommit_Portals(SubTransactionId mySubid,
200 SubTransactionId parentSubid,
201 ResourceOwner parentXactOwner);
202 extern void AtSubAbort_Portals(SubTransactionId mySubid,
203 SubTransactionId parentSubid,
204 ResourceOwner parentXactOwner);
205 extern void AtSubCleanup_Portals(SubTransactionId mySubid);
206 extern Portal CreatePortal(const char *name, bool allowDup, bool dupSilent);
207 extern Portal CreateNewPortal(void);
208 extern void PinPortal(Portal portal);
209 extern void UnpinPortal(Portal portal);
210 extern void MarkPortalDone(Portal portal);
211 extern void MarkPortalFailed(Portal portal);
212 extern void PortalDrop(Portal portal, bool isTopCommit);
213 extern Portal GetPortalByName(const char *name);
214 extern void PortalDefineQuery(Portal portal,
215 const char *prepStmtName,
216 const char *sourceText,
217 const char *commandTag,
220 extern Node *PortalListGetPrimaryStmt(List *stmts);
221 extern void PortalCreateHoldStore(Portal portal);
222 extern void PortalHashTableDeleteAll(void);
223 extern bool ThereAreNoReadyPortals(void);
225 #endif /* PORTAL_H */