mirror of
https://github.com/postgres/postgres.git
synced 2025-07-02 09:02:37 +03:00
Add a new system view, pg_cursors, that displays the currently available
cursors. Patch from Joachim Wieland, review and ediorialization by Neil Conway. The view lists cursors defined by DECLARE CURSOR, using SPI, or via the Bind message of the frontend/backend protocol. This means the view does not list the unnamed portal or the portal created to implement EXECUTE. Because we do list SPI portals, there might be more rows in this view than you might expect if you are using SPI implicitly (e.g. via a procedural language). Per recent discussion on -hackers, the query string included in the view for cursors defined by DECLARE CURSOR is based on debug_query_string. That means it is not accurate if multiple queries separated by semicolons are submitted as one query string. However, there doesn't seem a trivial fix for that: debug_query_string is better than nothing. I also changed SPI_cursor_open() to include the source text for the portal it creates: AFAICS there is no reason not to do this. Update the documentation and regression tests, bump the catversion.
This commit is contained in:
Neil Conway
@ -1,6 +1,6 @@
|
||||
<!--
|
||||
Documentation of the system catalogs, directed toward PostgreSQL developers
|
||||
$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.117 2006/01/16 18:15:30 neilc Exp $
|
||||
$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.118 2006/01/18 06:49:25 neilc Exp $
|
||||
-->
|
||||
|
||||
<chapter id="catalogs">
|
||||
@ -4359,6 +4359,11 @@
|
||||
</thead>
|
||||
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><link linkend="view-pg-cursors"><structname>pg_cursors</structname></link></entry>
|
||||
<entry>open cursors</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><link linkend="view-pg-group"><structname>pg_group</structname></link></entry>
|
||||
<entry>groups of database users</entry>
|
||||
@ -4429,6 +4434,131 @@
|
||||
</table>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="view-pg-cursors">
|
||||
<title><structname>pg_cursors</structname></title>
|
||||
|
||||
<indexterm zone="view-pg-cursors">
|
||||
<primary>pg_cursors</primary>
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
The <structname>pg_cursors</structname> view lists the cursors that
|
||||
are currently available. Cursors can be defined in several ways:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
via the <xref linkend="sql-declare" endterm="sql-declare-title">
|
||||
statement in SQL
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
via the Bind message in the frontend/backend protocol, as
|
||||
described in <xref linkend="protocol-flow-ext-query">
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
via the Server Programming Interface (SPI), as described in
|
||||
<xref linkend="spi-interface">
|
||||
</itemizedlist>
|
||||
|
||||
The <structname>pg_cursors</structname> view displays cursors
|
||||
created by any of these means. Cursors only exist for the duration
|
||||
of the transaction that defines them, unless they have been
|
||||
declared <literal>WITH HOLD</literal>. Therefore non-holdable
|
||||
cursors are only present in the view until the end of their
|
||||
creating transaction.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Cursors are used internally to implement some of the components
|
||||
of <productname>PostgreSQL</>, such as procedural languages.
|
||||
Therefore, the <structname>pg_cursors</> view may include cursors
|
||||
that have not been explicitly created by the user.
|
||||
</para>
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<table>
|
||||
<title><structname>pg_cursors</> Columns</title>
|
||||
|
||||
<tgroup cols=4>
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Name</entry>
|
||||
<entry>Type</entry>
|
||||
<entry>References</entry>
|
||||
<entry>Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><structfield>name</structfield></entry>
|
||||
<entry><type>text</type></entry>
|
||||
<entry></entry>
|
||||
<entry>The name of the cursor</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><structfield>statement</structfield></entry>
|
||||
<entry><type>text</type></entry>
|
||||
<entry></entry>
|
||||
<entry>The verbatim query string submitted to declare this cursor</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><structfield>is_holdable</structfield></entry>
|
||||
<entry><type>boolean</type></entry>
|
||||
<entry></entry>
|
||||
<entry>
|
||||
<literal>true</literal> if the cursor is holdable (that is, it
|
||||
can be accessed after the transaction that declared the cursor
|
||||
has committed); <literal>false</literal> otherwise
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><structfield>is_binary</structfield></entry>
|
||||
<entry><type>boolean</type></entry>
|
||||
<entry></entry>
|
||||
<entry>
|
||||
<literal>true</literal> if the cursor was declared
|
||||
<literal>BINARY</literal>; <literal>false</literal>
|
||||
otherwise
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><structfield>is_scrollable</structfield></entry>
|
||||
<entry><type>boolean</type></entry>
|
||||
<entry></entry>
|
||||
<entry>
|
||||
<literal>true</> if the cursor is scrollable (that is, it
|
||||
allows rows to be retrieved in a nonsequential manner);
|
||||
<literal>false</literal> otherwise
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><structfield>creation_time</structfield></entry>
|
||||
<entry><type>timestamptz</type></entry>
|
||||
<entry></entry>
|
||||
<entry>The time at which the cursor was declared</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<para>
|
||||
The <structname>pg_cursors</structname> view is read only.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="view-pg-group">
|
||||
<title><structname>pg_group</structname></title>
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.62 2005/08/14 22:19:49 petere Exp $ -->
|
||||
<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.63 2006/01/18 06:49:25 neilc Exp $ -->
|
||||
|
||||
<chapter id="protocol">
|
||||
<title>Frontend/Backend Protocol</title>
|
||||
@ -602,7 +602,7 @@
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<sect2 id="protocol-flow-ext-query">
|
||||
<title>Extended Query</title>
|
||||
|
||||
<para>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$PostgreSQL: pgsql/doc/src/sgml/ref/close.sgml,v 1.22 2005/01/04 00:39:53 tgl Exp $
|
||||
$PostgreSQL: pgsql/doc/src/sgml/ref/close.sgml,v 1.23 2006/01/18 06:49:26 neilc Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@ -76,6 +76,11 @@ CLOSE <replaceable class="PARAMETER">name</replaceable>
|
||||
<xref linkend="sql-declare" endterm="sql-declare-title">
|
||||
statement to declare a cursor.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can see all available cursors by querying the
|
||||
<structname>pg_cursors</structname> system view.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$PostgreSQL: pgsql/doc/src/sgml/ref/declare.sgml,v 1.33 2005/01/04 00:39:53 tgl Exp $
|
||||
$PostgreSQL: pgsql/doc/src/sgml/ref/declare.sgml,v 1.34 2006/01/18 06:49:26 neilc Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@ -253,6 +253,11 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
|
||||
the standard SQL cursor conventions, including those involving
|
||||
<command>DECLARE</command> and <command>OPEN</command> statements.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can see all available cursors by querying the
|
||||
<structname>pg_cursors</structname> system view.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
||||
Reference in New Issue
Block a user