begriffs open source - ai-pg/blob - full-docs/html/plpgsql-cursors.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>41.7. Cursors</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpgsql-control-structures.html" title="41.6. Control Structures" /><link rel="next" href="plpgsql-transactions.html" title="41.8. Transaction Management" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">41.7. Cursors</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpgsql-control-structures.html" title="41.6. Control Structures">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpgsql.html" title="Chapter 41. PL/pgSQL — SQL Procedural Language">Up</a></td><th width="60%" align="center">Chapter 41. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql-transactions.html" title="41.8. Transaction Management">Next</a></td></tr></table><hr /></div><div class="sect1" id="PLPGSQL-CURSORS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">41.7. Cursors <a href="#PLPGSQL-CURSORS" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-DECLARATIONS">41.7.1. Declaring Cursor Variables</a></span></dt><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-OPENING">41.7.2. Opening Cursors</a></span></dt><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-USING">41.7.3. Using Cursors</a></span></dt><dt><span class="sect2"><a href="plpgsql-cursors.html#PLPGSQL-CURSOR-FOR-LOOP">41.7.4. Looping through a Cursor's Result</a></span></dt></dl></div><a id="id-1.8.8.9.2" class="indexterm"></a><p>
   3     Rather than executing a whole query at once, it is possible to set
   4     up a <em class="firstterm">cursor</em> that encapsulates the query, and then read
   5     the query result a few rows at a time. One reason for doing this is
   6     to avoid memory overrun when the result contains a large number of
   7     rows. (However, <span class="application">PL/pgSQL</span> users do not normally need
   8     to worry about that, since <code class="literal">FOR</code> loops automatically use a cursor
   9     internally to avoid memory problems.) A more interesting usage is to
  10     return a reference to a cursor that a function has created, allowing the
  11     caller to read the rows. This provides an efficient way to return
  12     large row sets from functions.
  13    </p><div class="sect2" id="PLPGSQL-CURSOR-DECLARATIONS"><div class="titlepage"><div><div><h3 class="title">41.7.1. Declaring Cursor Variables <a href="#PLPGSQL-CURSOR-DECLARATIONS" class="id_link">#</a></h3></div></div></div><p>
  14      All access to cursors in <span class="application">PL/pgSQL</span> goes through
  15      cursor variables, which are always of the special data type
  16      <code class="type">refcursor</code>.  One way to create a cursor variable
  17      is just to declare it as a variable of type <code class="type">refcursor</code>.
  18      Another way is to use the cursor declaration syntax,
  19      which in general is:
  20 </p><pre class="synopsis">
  21 <em class="replaceable"><code>name</code></em> [<span class="optional"> [<span class="optional"> NO </span>] SCROLL </span>] CURSOR [<span class="optional"> ( <em class="replaceable"><code>arguments</code></em> ) </span>] FOR <em class="replaceable"><code>query</code></em>;
  22 </pre><p>
  23      (<code class="literal">FOR</code> can be replaced by <code class="literal">IS</code> for
  24      <span class="productname">Oracle</span> compatibility.)
  25      If <code class="literal">SCROLL</code> is specified, the cursor will be capable of
  26      scrolling backward; if <code class="literal">NO SCROLL</code> is specified, backward
  27      fetches will be rejected; if neither specification appears, it is
  28      query-dependent whether backward fetches will be allowed.
  29      <em class="replaceable"><code>arguments</code></em>, if specified, is a
  30      comma-separated list of pairs <code class="literal"><em class="replaceable"><code>name</code></em>
  31      <em class="replaceable"><code>datatype</code></em></code> that define names to be
  32      replaced by parameter values in the given query.  The actual
  33      values to substitute for these names will be specified later,
  34      when the cursor is opened.
  35     </p><p>
  36      Some examples:
  37 </p><pre class="programlisting">
  38 DECLARE
  39     curs1 refcursor;
  40     curs2 CURSOR FOR SELECT * FROM tenk1;
  41     curs3 CURSOR (key integer) FOR SELECT * FROM tenk1 WHERE unique1 = key;
  42 </pre><p>
  43      All three of these variables have the data type <code class="type">refcursor</code>,
  44      but the first can be used with any query, while the second has
  45      a fully specified query already <em class="firstterm">bound</em> to it, and the last
  46      has a parameterized query bound to it.  (<code class="literal">key</code> will be
  47      replaced by an integer parameter value when the cursor is opened.)
  48      The variable <code class="literal">curs1</code>
  49      is said to be <em class="firstterm">unbound</em> since it is not bound to
  50      any particular query.
  51     </p><p>
  52      The <code class="literal">SCROLL</code> option cannot be used when the cursor's
  53      query uses <code class="literal">FOR UPDATE/SHARE</code>.  Also, it is
  54      best to use <code class="literal">NO SCROLL</code> with a query that involves
  55      volatile functions.  The implementation of <code class="literal">SCROLL</code>
  56      assumes that re-reading the query's output will give consistent
  57      results, which a volatile function might not do.
  58     </p></div><div class="sect2" id="PLPGSQL-CURSOR-OPENING"><div class="titlepage"><div><div><h3 class="title">41.7.2. Opening Cursors <a href="#PLPGSQL-CURSOR-OPENING" class="id_link">#</a></h3></div></div></div><p>
  59      Before a cursor can be used to retrieve rows, it must be
  60      <em class="firstterm">opened</em>. (This is the equivalent action to the SQL
  61      command <a class="link" href="sql-declare.html" title="DECLARE"><code class="command">DECLARE
  62      CURSOR</code></a>.)
  63      <span class="application">PL/pgSQL</span> has
  64      three forms of the <code class="command">OPEN</code> statement, two of which use unbound
  65      cursor variables while the third uses a bound cursor variable.
  66     </p><div class="note"><h3 class="title">Note</h3><p>
  67       Bound cursor variables can also be used without explicitly opening the cursor,
  68       via the <code class="command">FOR</code> statement described in
  69       <a class="xref" href="plpgsql-cursors.html#PLPGSQL-CURSOR-FOR-LOOP" title="41.7.4. Looping through a Cursor's Result">Section 41.7.4</a>.
  70       A <code class="command">FOR</code> loop will open the cursor and then
  71       close it again when the loop completes.
  72      </p></div><a id="id-1.8.8.9.5.4" class="indexterm"></a><p>
  73      Opening a cursor involves creating a server-internal data structure
  74      called a <em class="firstterm">portal</em>, which holds the execution
  75      state for the cursor's query.  A portal has a name, which must be
  76      unique within the session for the duration of the portal's existence.
  77      By default, <span class="application">PL/pgSQL</span> will assign a unique
  78      name to each portal it creates.  However, if you assign a non-null
  79      string value to a cursor variable, that string will be used as its
  80      portal name.  This feature can be used as described in
  81      <a class="xref" href="plpgsql-cursors.html#PLPGSQL-CURSOR-RETURNING" title="41.7.3.5. Returning Cursors">Section 41.7.3.5</a>.
  82     </p><div class="sect3" id="PLPGSQL-CURSOR-OPENING-OPEN-FOR-QUERY"><div class="titlepage"><div><div><h4 class="title">41.7.2.1. <code class="command">OPEN FOR</code> <em class="replaceable"><code>query</code></em> <a href="#PLPGSQL-CURSOR-OPENING-OPEN-FOR-QUERY" class="id_link">#</a></h4></div></div></div><pre class="synopsis">
  83 OPEN <em class="replaceable"><code>unbound_cursorvar</code></em> [<span class="optional"> [<span class="optional"> NO </span>] SCROLL </span>] FOR <em class="replaceable"><code>query</code></em>;
  84 </pre><p>
  85         The cursor variable is opened and given the specified query to
  86         execute.  The cursor cannot be open already, and it must have been
  87         declared as an unbound cursor variable (that is, as a simple
  88         <code class="type">refcursor</code> variable).  The query must be a
  89         <code class="command">SELECT</code>, or something else that returns rows
  90         (such as <code class="command">EXPLAIN</code>).  The query
  91         is treated in the same way as other SQL commands in
  92         <span class="application">PL/pgSQL</span>: <span class="application">PL/pgSQL</span>
  93         variable names are substituted, and the query plan is cached for
  94         possible reuse.  When a <span class="application">PL/pgSQL</span>
  95         variable is substituted into the cursor query, the value that is
  96         substituted is the one it has at the time of the <code class="command">OPEN</code>;
  97         subsequent changes to the variable will not affect the cursor's
  98         behavior.
  99         The <code class="literal">SCROLL</code> and <code class="literal">NO SCROLL</code>
 100         options have the same meanings as for a bound cursor.
 101        </p><p>
 102         An example:
 103 </p><pre class="programlisting">
 104 OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey;
 105 </pre><p>
 106        </p></div><div class="sect3" id="PLPGSQL-CURSOR-OPENING-OPEN-FOR-EXECUTE"><div class="titlepage"><div><div><h4 class="title">41.7.2.2. <code class="command">OPEN FOR EXECUTE</code> <a href="#PLPGSQL-CURSOR-OPENING-OPEN-FOR-EXECUTE" class="id_link">#</a></h4></div></div></div><pre class="synopsis">
 107 OPEN <em class="replaceable"><code>unbound_cursorvar</code></em> [<span class="optional"> [<span class="optional"> NO </span>] SCROLL </span>] FOR EXECUTE <em class="replaceable"><code>query_string</code></em>
 108                                      [<span class="optional"> USING <em class="replaceable"><code>expression</code></em> [<span class="optional">, ... </span>] </span>];
 109 </pre><p>
 110           The cursor variable is opened and given the specified query to
 111           execute.  The cursor cannot be open already, and it must have been
 112           declared as an unbound cursor variable (that is, as a simple
 113           <code class="type">refcursor</code> variable).  The query is specified as a string
 114           expression, in the same way as in the <code class="command">EXECUTE</code>
 115           command.  As usual, this gives flexibility so the query plan can vary
 116           from one run to the next (see <a class="xref" href="plpgsql-implementation.html#PLPGSQL-PLAN-CACHING" title="41.11.2. Plan Caching">Section 41.11.2</a>),
 117           and it also means that variable substitution is not done on the
 118           command string. As with <code class="command">EXECUTE</code>, parameter values
 119           can be inserted into the dynamic command via
 120           <code class="literal">format()</code> and <code class="literal">USING</code>.
 121           The <code class="literal">SCROLL</code> and
 122           <code class="literal">NO SCROLL</code> options have the same meanings as for a bound
 123           cursor.
 124          </p><p>
 125         An example:
 126 </p><pre class="programlisting">
 127 OPEN curs1 FOR EXECUTE format('SELECT * FROM %I WHERE col1 = $1',tabname) USING keyvalue;
 128 </pre><p>
 129         In this example, the table name is inserted into the query via
 130         <code class="function">format()</code>.  The comparison value for <code class="literal">col1</code>
 131         is inserted via a <code class="literal">USING</code> parameter, so it needs
 132         no quoting.
 133        </p></div><div class="sect3" id="PLPGSQL-OPEN-BOUND-CURSOR"><div class="titlepage"><div><div><h4 class="title">41.7.2.3. Opening a Bound Cursor <a href="#PLPGSQL-OPEN-BOUND-CURSOR" class="id_link">#</a></h4></div></div></div><pre class="synopsis">
 134 OPEN <em class="replaceable"><code>bound_cursorvar</code></em> [<span class="optional"> ( [<span class="optional"> <em class="replaceable"><code>argument_name</code></em> { := | =&gt; } </span>] <em class="replaceable"><code>argument_value</code></em> [<span class="optional">, ...</span>] ) </span>];
 135 </pre><p>
 136           This form of <code class="command">OPEN</code> is used to open a cursor
 137           variable whose query was bound to it when it was declared.  The
 138           cursor cannot be open already.  A list of actual argument value
 139           expressions must appear if and only if the cursor was declared to
 140           take arguments.  These values will be substituted in the query.
 141          </p><p>
 142           The query plan for a bound cursor is always considered cacheable;
 143           there is no equivalent of <code class="command">EXECUTE</code> in this case.
 144           Notice that <code class="literal">SCROLL</code> and <code class="literal">NO SCROLL</code> cannot be
 145           specified in <code class="command">OPEN</code>, as the cursor's scrolling
 146           behavior was already determined.
 147          </p><p>
 148           Argument values can be passed using either <em class="firstterm">positional</em>
 149           or <em class="firstterm">named</em> notation.  In positional
 150           notation, all arguments are specified in order.  In named notation,
 151           each argument's name is specified using <code class="literal">:=</code>
 152           or <code class="literal">=&gt;</code> to
 153           separate it from the argument expression. Similar to calling
 154           functions, described in <a class="xref" href="sql-syntax-calling-funcs.html" title="4.3. Calling Functions">Section 4.3</a>, it
 155           is also allowed to mix positional and named notation.
 156          </p><p>
 157           Examples (these use the cursor declaration examples above):
 158 </p><pre class="programlisting">
 159 OPEN curs2;
 160 OPEN curs3(42);
 161 OPEN curs3(key := 42);
 162 OPEN curs3(key =&gt; 42);
 163 </pre><p>
 164          </p><p>
 165           Because variable substitution is done on a bound cursor's query,
 166           there are really two ways to pass values into the cursor: either
 167           with an explicit argument to <code class="command">OPEN</code>, or implicitly by
 168           referencing a <span class="application">PL/pgSQL</span> variable in the query.
 169           However, only variables declared before the bound cursor was
 170           declared will be substituted into it.  In either case the value to
 171           be passed is determined at the time of the <code class="command">OPEN</code>.
 172           For example, another way to get the same effect as the
 173           <code class="literal">curs3</code> example above is
 174 </p><pre class="programlisting">
 175 DECLARE
 176     key integer;
 177     curs4 CURSOR FOR SELECT * FROM tenk1 WHERE unique1 = key;
 178 BEGIN
 179     key := 42;
 180     OPEN curs4;
 181 </pre><p>
 182          </p></div></div><div class="sect2" id="PLPGSQL-CURSOR-USING"><div class="titlepage"><div><div><h3 class="title">41.7.3. Using Cursors <a href="#PLPGSQL-CURSOR-USING" class="id_link">#</a></h3></div></div></div><p>
 183      Once a cursor has been opened, it can be manipulated with the
 184      statements described here.
 185     </p><p>
 186      These manipulations need not occur in the same function that
 187      opened the cursor to begin with.  You can return a <code class="type">refcursor</code>
 188      value out of a function and let the caller operate on the cursor.
 189      (Internally, a <code class="type">refcursor</code> value is simply the string name
 190      of the portal containing the active query for the cursor.  This name
 191      can be passed around, assigned to other <code class="type">refcursor</code> variables,
 192      and so on, without disturbing the portal.)
 193     </p><p>
 194      All portals are implicitly closed at transaction end.  Therefore
 195      a <code class="type">refcursor</code> value is usable to reference an open cursor
 196      only until the end of the transaction.
 197     </p><div class="sect3" id="PLPGSQL-CURSOR-USING-FETCH"><div class="titlepage"><div><div><h4 class="title">41.7.3.1. <code class="literal">FETCH</code> <a href="#PLPGSQL-CURSOR-USING-FETCH" class="id_link">#</a></h4></div></div></div><pre class="synopsis">
 198 FETCH [<span class="optional"> <em class="replaceable"><code>direction</code></em> { FROM | IN } </span>] <em class="replaceable"><code>cursor</code></em> INTO <em class="replaceable"><code>target</code></em>;
 199 </pre><p>
 200      <code class="command">FETCH</code> retrieves the next row (in the indicated
 201      direction) from the
 202      cursor into a target, which might be a row variable, a record
 203      variable, or a comma-separated list of simple variables, just like
 204      <code class="command">SELECT INTO</code>.  If there is no suitable row, the
 205      target is set to NULL(s).  As with <code class="command">SELECT
 206      INTO</code>, the special variable <code class="literal">FOUND</code> can
 207      be checked to see whether a row was obtained or not.  If no row is
 208      obtained, the cursor is positioned after the last row or before the
 209      first row, depending on the movement direction.
 210     </p><p>
 211      The <em class="replaceable"><code>direction</code></em> clause can be any of the
 212      variants allowed in the SQL <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a>
 213      command except the ones that can fetch
 214      more than one row; namely, it can be
 215      <code class="literal">NEXT</code>,
 216      <code class="literal">PRIOR</code>,
 217      <code class="literal">FIRST</code>,
 218      <code class="literal">LAST</code>,
 219      <code class="literal">ABSOLUTE</code> <em class="replaceable"><code>count</code></em>,
 220      <code class="literal">RELATIVE</code> <em class="replaceable"><code>count</code></em>,
 221      <code class="literal">FORWARD</code>, or
 222      <code class="literal">BACKWARD</code>.
 223      Omitting <em class="replaceable"><code>direction</code></em> is the same
 224      as specifying <code class="literal">NEXT</code>.
 225      In the forms using a <em class="replaceable"><code>count</code></em>,
 226      the <em class="replaceable"><code>count</code></em> can be any integer-valued
 227      expression (unlike the SQL <code class="command">FETCH</code> command,
 228      which only allows an integer constant).
 229      <em class="replaceable"><code>direction</code></em> values that require moving
 230      backward are likely to fail unless the cursor was declared or opened
 231      with the <code class="literal">SCROLL</code> option.
 232     </p><p>
 233      <em class="replaceable"><code>cursor</code></em> must be the name of a <code class="type">refcursor</code>
 234      variable that references an open cursor portal.
 235     </p><p>
 236      Examples:
 237 </p><pre class="programlisting">
 238 FETCH curs1 INTO rowvar;
 239 FETCH curs2 INTO foo, bar, baz;
 240 FETCH LAST FROM curs3 INTO x, y;
 241 FETCH RELATIVE -2 FROM curs4 INTO x;
 242 </pre><p>
 243        </p></div><div class="sect3" id="PLPGSQL-CURSOR-USING-MOVE"><div class="titlepage"><div><div><h4 class="title">41.7.3.2. <code class="literal">MOVE</code> <a href="#PLPGSQL-CURSOR-USING-MOVE" class="id_link">#</a></h4></div></div></div><pre class="synopsis">
 244 MOVE [<span class="optional"> <em class="replaceable"><code>direction</code></em> { FROM | IN } </span>] <em class="replaceable"><code>cursor</code></em>;
 245 </pre><p>
 246      <code class="command">MOVE</code> repositions a cursor without retrieving
 247      any data. <code class="command">MOVE</code> works like the
 248      <code class="command">FETCH</code> command, except it only repositions the
 249      cursor and does not return the row moved to.
 250      The <em class="replaceable"><code>direction</code></em> clause can be any of the
 251      variants allowed in the SQL <a class="xref" href="sql-fetch.html" title="FETCH"><span class="refentrytitle">FETCH</span></a>
 252      command, including those that can fetch more than one row;
 253      the cursor is positioned to the last such row.
 254      (However, the case in which the <em class="replaceable"><code>direction</code></em>
 255      clause is simply a <em class="replaceable"><code>count</code></em> expression with
 256      no key word is deprecated in <span class="application">PL/pgSQL</span>.
 257      That syntax is ambiguous with the case where
 258      the <em class="replaceable"><code>direction</code></em> clause is omitted
 259      altogether, and hence it may fail if
 260      the <em class="replaceable"><code>count</code></em> is not a constant.)
 261      As with <code class="command">SELECT
 262      INTO</code>, the special variable <code class="literal">FOUND</code> can
 263      be checked to see whether there was a row to move to.  If there is no
 264      such row, the cursor is positioned after the last row or before the
 265      first row, depending on the movement direction.
 266     </p><p>
 267      Examples:
 268 </p><pre class="programlisting">
 269 MOVE curs1;
 270 MOVE LAST FROM curs3;
 271 MOVE RELATIVE -2 FROM curs4;
 272 MOVE FORWARD 2 FROM curs4;
 273 </pre><p>
 274        </p></div><div class="sect3" id="PLPGSQL-CURSOR-USING-UPDATE-DELETE"><div class="titlepage"><div><div><h4 class="title">41.7.3.3. <code class="literal">UPDATE/DELETE WHERE CURRENT OF</code> <a href="#PLPGSQL-CURSOR-USING-UPDATE-DELETE" class="id_link">#</a></h4></div></div></div><pre class="synopsis">
 275 UPDATE <em class="replaceable"><code>table</code></em> SET ... WHERE CURRENT OF <em class="replaceable"><code>cursor</code></em>;
 276 DELETE FROM <em class="replaceable"><code>table</code></em> WHERE CURRENT OF <em class="replaceable"><code>cursor</code></em>;
 277 </pre><p>
 278         When a cursor is positioned on a table row, that row can be updated
 279         or deleted using the cursor to identify the row.  There are
 280         restrictions on what the cursor's query can be (in particular,
 281         no grouping) and it's best to use <code class="literal">FOR UPDATE</code> in the
 282         cursor.  For more information see the
 283         <a class="xref" href="sql-declare.html" title="DECLARE"><span class="refentrytitle">DECLARE</span></a>
 284         reference page.
 285        </p><p>
 286         An example:
 287 </p><pre class="programlisting">
 288 UPDATE foo SET dataval = myval WHERE CURRENT OF curs1;
 289 </pre><p>
 290        </p></div><div class="sect3" id="PLPGSQL-CURSOR-USING-CLOSE"><div class="titlepage"><div><div><h4 class="title">41.7.3.4. <code class="literal">CLOSE</code> <a href="#PLPGSQL-CURSOR-USING-CLOSE" class="id_link">#</a></h4></div></div></div><pre class="synopsis">
 291 CLOSE <em class="replaceable"><code>cursor</code></em>;
 292 </pre><p>
 293         <code class="command">CLOSE</code> closes the portal underlying an open
 294         cursor.  This can be used to release resources earlier than end of
 295         transaction, or to free up the cursor variable to be opened again.
 296        </p><p>
 297         An example:
 298 </p><pre class="programlisting">
 299 CLOSE curs1;
 300 </pre><p>
 301        </p></div><div class="sect3" id="PLPGSQL-CURSOR-RETURNING"><div class="titlepage"><div><div><h4 class="title">41.7.3.5. Returning Cursors <a href="#PLPGSQL-CURSOR-RETURNING" class="id_link">#</a></h4></div></div></div><p>
 302         <span class="application">PL/pgSQL</span> functions can return cursors to the
 303         caller. This is useful to return multiple rows or columns,
 304         especially with very large result sets.  To do this, the function
 305         opens the cursor and returns the cursor name to the caller (or simply
 306         opens the cursor using a portal name specified by or otherwise known
 307         to the caller).  The caller can then fetch rows from the cursor. The
 308         cursor can be closed by the caller, or it will be closed automatically
 309         when the transaction closes.
 310        </p><p>
 311         The portal name used for a cursor can be specified by the
 312         programmer or automatically generated.  To specify a portal name,
 313         simply assign a string to the <code class="type">refcursor</code> variable before
 314         opening it.  The string value of the <code class="type">refcursor</code> variable
 315         will be used by <code class="command">OPEN</code> as the name of the underlying portal.
 316         However, if the <code class="type">refcursor</code> variable's value is null
 317         (as it will be by default), then
 318         <code class="command">OPEN</code> automatically generates a name that does not
 319         conflict with any existing portal, and assigns it to the
 320         <code class="type">refcursor</code> variable.
 321        </p><div class="note"><h3 class="title">Note</h3><p>
 322          Prior to <span class="productname">PostgreSQL</span> 16, bound cursor
 323          variables were initialized to contain their own names, rather
 324          than being left as null, so that the underlying portal name would
 325          be the same as the cursor variable's name by default.  This was
 326          changed because it created too much risk of conflicts between
 327          similarly-named cursors in different functions.
 328         </p></div><p>
 329         The following example shows one way a cursor name can be supplied by
 330         the caller:
 331
 332 </p><pre class="programlisting">
 333 CREATE TABLE test (col text);
 334 INSERT INTO test VALUES ('123');
 335
 336 CREATE FUNCTION reffunc(refcursor) RETURNS refcursor AS '
 337 BEGIN
 338     OPEN $1 FOR SELECT col FROM test;
 339     RETURN $1;
 340 END;
 341 ' LANGUAGE plpgsql;
 342
 343 BEGIN;
 344 SELECT reffunc('funccursor');
 345 FETCH ALL IN funccursor;
 346 COMMIT;
 347 </pre><p>
 348        </p><p>
 349         The following example uses automatic cursor name generation:
 350
 351 </p><pre class="programlisting">
 352 CREATE FUNCTION reffunc2() RETURNS refcursor AS '
 353 DECLARE
 354     ref refcursor;
 355 BEGIN
 356     OPEN ref FOR SELECT col FROM test;
 357     RETURN ref;
 358 END;
 359 ' LANGUAGE plpgsql;
 360
 361 -- need to be in a transaction to use cursors.
 362 BEGIN;
 363 SELECT reffunc2();
 364
 365       reffunc2
 366 --------------------
 367  &lt;unnamed cursor 1&gt;
 368 (1 row)
 369
 370 FETCH ALL IN "&lt;unnamed cursor 1&gt;";
 371 COMMIT;
 372 </pre><p>
 373        </p><p>
 374         The following example shows one way to return multiple cursors
 375         from a single function:
 376
 377 </p><pre class="programlisting">
 378 CREATE FUNCTION myfunc(refcursor, refcursor) RETURNS SETOF refcursor AS $$
 379 BEGIN
 380     OPEN $1 FOR SELECT * FROM table_1;
 381     RETURN NEXT $1;
 382     OPEN $2 FOR SELECT * FROM table_2;
 383     RETURN NEXT $2;
 384 END;
 385 $$ LANGUAGE plpgsql;
 386
 387 -- need to be in a transaction to use cursors.
 388 BEGIN;
 389
 390 SELECT * FROM myfunc('a', 'b');
 391
 392 FETCH ALL FROM a;
 393 FETCH ALL FROM b;
 394 COMMIT;
 395 </pre><p>
 396        </p></div></div><div class="sect2" id="PLPGSQL-CURSOR-FOR-LOOP"><div class="titlepage"><div><div><h3 class="title">41.7.4. Looping through a Cursor's Result <a href="#PLPGSQL-CURSOR-FOR-LOOP" class="id_link">#</a></h3></div></div></div><p>
 397      There is a variant of the <code class="command">FOR</code> statement that allows
 398      iterating through the rows returned by a cursor.  The syntax is:
 399
 400 </p><pre class="synopsis">
 401 [<span class="optional"> &lt;&lt;<em class="replaceable"><code>label</code></em>&gt;&gt; </span>]
 402 FOR <em class="replaceable"><code>recordvar</code></em> IN <em class="replaceable"><code>bound_cursorvar</code></em> [<span class="optional"> ( [<span class="optional"> <em class="replaceable"><code>argument_name</code></em> { := | =&gt; } </span>] <em class="replaceable"><code>argument_value</code></em> [<span class="optional">, ...</span>] ) </span>] LOOP
 403     <em class="replaceable"><code>statements</code></em>
 404 END LOOP [<span class="optional"> <em class="replaceable"><code>label</code></em> </span>];
 405 </pre><p>
 406
 407      The cursor variable must have been bound to some query when it was
 408      declared, and it <span class="emphasis"><em>cannot</em></span> be open already.  The
 409      <code class="command">FOR</code> statement automatically opens the cursor, and it closes
 410      the cursor again when the loop exits.  A list of actual argument value
 411      expressions must appear if and only if the cursor was declared to take
 412      arguments.  These values will be substituted in the query, in just
 413      the same way as during an <code class="command">OPEN</code> (see <a class="xref" href="plpgsql-cursors.html#PLPGSQL-OPEN-BOUND-CURSOR" title="41.7.2.3. Opening a Bound Cursor">Section 41.7.2.3</a>).
 414    </p><p>
 415      The variable <em class="replaceable"><code>recordvar</code></em> is automatically
 416      defined as type <code class="type">record</code> and exists only inside the loop (any
 417      existing definition of the variable name is ignored within the loop).
 418      Each row returned by the cursor is successively assigned to this
 419      record variable and the loop body is executed.
 420     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpgsql-control-structures.html" title="41.6. Control Structures">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpgsql.html" title="Chapter 41. PL/pgSQL — SQL Procedural Language">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql-transactions.html" title="41.8. Transaction Management">Next</a></td></tr><tr><td width="40%" align="left" valign="top">41.6. Control Structures </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 41.8. Transaction Management</td></tr></table></div></body></html>