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 * parse/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-2002, PostgreSQL Global Development Group
40 * Portions Copyright (c) 1994, Regents of the University of California
42 * $Id: portal.h,v 1.45 2003/08/04 00:43:32 momjian Exp $
44 *-------------------------------------------------------------------------
49 #include "executor/execdesc.h"
50 #include "nodes/memnodes.h"
51 #include "utils/tuplestore.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_UTIL_SELECT: the portal contains a utility statement that returns
67 * a SELECT-like result (for example, EXPLAIN or SHOW). On first execution,
68 * we run the statement and dump its results into the portal tuplestore;
69 * the results are then returned to the client as demanded.
71 * PORTAL_MULTI_QUERY: all other cases. Here, we do not support partial
72 * execution: the portal's queries will be run to completion on first call.
75 typedef enum PortalStrategy
83 * Note: typedef Portal is declared in tcop/dest.h as
84 * typedef struct PortalData *Portal;
87 typedef struct PortalData
89 /* Bookkeeping data */
90 const char *name; /* portal's name */
91 MemoryContext heap; /* subsidiary memory for portal */
92 void (*cleanup) (Portal portal, bool isError); /* cleanup hook */
93 TransactionId createXact; /* the xid of the creating xact */
95 /* The query or queries the portal will execute */
96 const char *sourceText; /* text of query, if known (may be NULL) */
97 const char *commandTag; /* command tag for original query */
98 List *parseTrees; /* parse tree(s) */
99 List *planTrees; /* plan tree(s) */
100 MemoryContext queryContext; /* where the above trees live */
103 * Note: queryContext effectively identifies which prepared statement
104 * the portal depends on, if any. The queryContext is *not* owned by
105 * the portal and is not to be deleted by portal destruction. (But
106 * for a cursor it is the same as "heap", and that context is deleted
107 * by portal destruction.)
109 ParamListInfo portalParams; /* params to pass to query */
111 /* Features/options */
112 PortalStrategy strategy; /* see above */
113 int cursorOptions; /* DECLARE CURSOR option bits */
116 bool portalReady; /* PortalStart complete? */
117 bool portalUtilReady; /* PortalRunUtility complete? */
118 bool portalActive; /* portal is running (can't delete it) */
119 bool portalDone; /* portal is finished (don't re-run it) */
121 /* If not NULL, Executor is active; call ExecutorEnd eventually: */
122 QueryDesc *queryDesc; /* info needed for executor invocation */
124 /* If portal returns tuples, this is their tupdesc: */
125 TupleDesc tupDesc; /* descriptor for result tuples */
126 /* and these are the format codes to use for the columns: */
127 int16 *formats; /* a format code for each column */
130 * Where we store tuples for a held cursor or a PORTAL_UTIL_SELECT
131 * query. (A cursor held past the end of its transaction no longer has
132 * any active executor state.)
134 Tuplestorestate *holdStore; /* store for holdable cursors */
135 MemoryContext holdContext; /* memory containing holdStore */
138 * atStart, atEnd and portalPos indicate the current cursor position.
139 * portalPos is zero before the first row, N after fetching N'th row
140 * of query. After we run off the end, portalPos = # of rows in
141 * query, and atEnd is true. If portalPos overflows, set posOverflow
142 * (this causes us to stop relying on its value for navigation). Note
143 * that atStart implies portalPos == 0, but not the reverse (portalPos
144 * could have overflowed).
154 * True iff portal is valid.
156 #define PortalIsValid(p) PointerIsValid(p)
159 * Access macros for Portal ... use these in preference to field access.
161 #define PortalGetQueryDesc(portal) ((portal)->queryDesc)
162 #define PortalGetHeapMemory(portal) ((portal)->heap)
165 /* Prototypes for functions in utils/mmgr/portalmem.c */
166 extern void EnablePortalManager(void);
167 extern void AtCommit_Portals(void);
168 extern void AtAbort_Portals(void);
169 extern void AtCleanup_Portals(void);
170 extern Portal CreatePortal(const char *name, bool allowDup, bool dupSilent);
171 extern Portal CreateNewPortal(void);
172 extern void PortalDrop(Portal portal, bool isError);
173 extern void DropDependentPortals(MemoryContext queryContext);
174 extern Portal GetPortalByName(const char *name);
175 extern void PortalDefineQuery(Portal portal,
176 const char *sourceText,
177 const char *commandTag,
180 MemoryContext queryContext);
181 extern void PortalCreateHoldStore(Portal portal);
183 #endif /* PORTAL_H */