Home Explore Blog CI



postgresql

45th chunk of `doc/src/sgml/plpgsql.sgml`
1f89229b6830d50916631d18782ba11af2f410708c6b8cac0000000100000fa6
 specifying <literal>NEXT</literal>.
     In the forms using a <replaceable>count</replaceable>,
     the <replaceable>count</replaceable> can be any integer-valued
     expression (unlike the SQL <command>FETCH</command> command,
     which only allows an integer constant).
     <replaceable>direction</replaceable> values that require moving
     backward are likely to fail unless the cursor was declared or opened
     with the <literal>SCROLL</literal> option.
    </para>

    <para>
     <replaceable>cursor</replaceable> must be the name of a <type>refcursor</type>
     variable that references an open cursor portal.
    </para>

    <para>
     Examples:
<programlisting>
FETCH curs1 INTO rowvar;
FETCH curs2 INTO foo, bar, baz;
FETCH LAST FROM curs3 INTO x, y;
FETCH RELATIVE -2 FROM curs4 INTO x;
</programlisting>
       </para>
     </sect3>

    <sect3 id="plpgsql-cursor-using-move">
     <title><literal>MOVE</literal></title>

<synopsis>
MOVE <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <replaceable>cursor</replaceable>;
</synopsis>

    <para>
     <command>MOVE</command> repositions a cursor without retrieving
     any data. <command>MOVE</command> works like the
     <command>FETCH</command> command, except it only repositions the
     cursor and does not return the row moved to.
     The <replaceable>direction</replaceable> clause can be any of the
     variants allowed in the SQL <xref linkend="sql-fetch"/>
     command, including those that can fetch more than one row;
     the cursor is positioned to the last such row.
     (However, the case in which the <replaceable>direction</replaceable>
     clause is simply a <replaceable>count</replaceable> expression with
     no key word is deprecated in <application>PL/pgSQL</application>.
     That syntax is ambiguous with the case where
     the <replaceable>direction</replaceable> clause is omitted
     altogether, and hence it may fail if
     the <replaceable>count</replaceable> is not a constant.)
     As with <command>SELECT
     INTO</command>, the special variable <literal>FOUND</literal> can
     be checked to see whether there was a row to move to.  If there is no
     such row, the cursor is positioned after the last row or before the
     first row, depending on the movement direction.
    </para>

    <para>
     Examples:
<programlisting>
MOVE curs1;
MOVE LAST FROM curs3;
MOVE RELATIVE -2 FROM curs4;
MOVE FORWARD 2 FROM curs4;
</programlisting>
       </para>
     </sect3>

    <sect3 id="plpgsql-cursor-using-update-delete">
     <title><literal>UPDATE/DELETE WHERE CURRENT OF</literal></title>

<synopsis>
UPDATE <replaceable>table</replaceable> SET ... WHERE CURRENT OF <replaceable>cursor</replaceable>;
DELETE FROM <replaceable>table</replaceable> WHERE CURRENT OF <replaceable>cursor</replaceable>;
</synopsis>

       <para>
        When a cursor is positioned on a table row, that row can be updated
        or deleted using the cursor to identify the row.  There are
        restrictions on what the cursor's query can be (in particular,
        no grouping) and it's best to use <literal>FOR UPDATE</literal> in the
        cursor.  For more information see the
        <xref linkend="sql-declare"/>
        reference page.
       </para>

       <para>
        An example:
<programlisting>
UPDATE foo SET dataval = myval WHERE CURRENT OF curs1;
</programlisting>
       </para>
     </sect3>

    <sect3 id="plpgsql-cursor-using-close">
     <title><literal>CLOSE</literal></title>

<synopsis>
CLOSE <replaceable>cursor</replaceable>;
</synopsis>

       <para>
        <command>CLOSE</command> closes the portal underlying an open
        cursor.  This can be used to release resources earlier than end of
        transaction, or to free up the cursor variable to be opened again.
       </para>

       <para>
        An example:
<programlisting>
CLOSE curs1;
</programlisting>
       </para>
     </sect3>

    <sect3 id="plpgsql-cursor-returning">

Title: Using Cursors: MOVE, UPDATE/DELETE WHERE CURRENT OF, CLOSE
Summary
This section details more cursor operations in PL/pgSQL. The MOVE command repositions a cursor without retrieving data, similar to FETCH but without returning the row. UPDATE/DELETE WHERE CURRENT OF allows updating or deleting the row the cursor is currently positioned on, with certain restrictions on the cursor's query. The CLOSE command closes the portal underlying an open cursor, releasing resources.