fetched and the time they are updated.  Without <literal>FOR UPDATE</literal>,
     a subsequent <literal>WHERE CURRENT OF</literal> command will have no effect if
     the row was changed since the cursor was created.
    </para>

    <para>
     Another reason to use <literal>FOR UPDATE</literal> is that without it, a
     subsequent <literal>WHERE CURRENT OF</literal> might fail if the cursor query
     does not meet the SQL standard's rules for being <quote>simply
     updatable</quote> (in particular, the cursor must reference just one table
     and not use grouping or <literal>ORDER BY</literal>).  Cursors
     that are not simply updatable might work, or might not, depending on plan
     choice details; so in the worst case, an application might work in testing
     and then fail in production.  If <literal>FOR UPDATE</literal> is
     specified, the cursor is guaranteed to be updatable.
    </para>

    <para>
     The main reason not to use <literal>FOR UPDATE</literal> with <literal>WHERE
     CURRENT OF</literal> is if you need the cursor to be scrollable, or to be
     isolated from concurrent updates (that is, continue to show the old
     data).  If this is a requirement, pay close heed to the caveats shown
     above.
    </para>
   </caution>

   <para>
    The SQL standard only makes provisions for cursors in embedded
    <acronym>SQL</acronym>.  The <productname>PostgreSQL</productname>
    server does not implement an <command>OPEN</command> statement for
    cursors; a cursor is considered to be open when it is declared.
    However, <application>ECPG</application>, the embedded SQL
    preprocessor for <productname>PostgreSQL</productname>, supports
    the standard SQL cursor conventions, including those involving
    <command>DECLARE</command> and <command>OPEN</command> statements.
   </para>

   <para>
    The server data structure underlying an open cursor is called a
    <firstterm>portal</firstterm>.  Portal names are exposed in the
    client protocol: a client can fetch rows directly from an open
    portal, if it knows the portal name.  When creating a cursor with
    <command>DECLARE</command>, the portal name is the same as the
    cursor name.
   </para>

   <para>
    You can see all available cursors by querying the <link
    linkend="view-pg-cursors"><structname>pg_cursors</structname></link>
    system view.
   </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   To declare a cursor:
<programlisting>
DECLARE liahona CURSOR FOR SELECT * FROM films;
</programlisting>
   See <xref linkend="sql-fetch"/> for more
   examples of cursor usage.
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   The SQL standard allows cursors only in embedded
   <acronym>SQL</acronym> and in modules. <productname>PostgreSQL</productname>
   permits cursors to be used interactively.
  </para>

  <para>
   According to the SQL standard, changes made to insensitive cursors by
   <literal>UPDATE ... WHERE CURRENT OF</literal> and <literal>DELETE
   ... WHERE CURRENT OF</literal> statements are visible in that same
   cursor.  <productname>PostgreSQL</productname> treats these statements like
   all other data changing statements in that they are not visible in
   insensitive cursors.
  </para>

  <para>
   Binary cursors are a <productname>PostgreSQL</productname>
   extension.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-close"/></member>
   <member><xref linkend="sql-fetch"/></member>
   <member><xref linkend="sql-move"/></member>
  </simplelist>
 </refsect1>
</refentry>