Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 66888f7

Browse files
tglsfdctglsfdc
committed
Expose more cursor-related functionality in SPI: specifically, allow
access to the planner's cursor-related planning options, and provide new FETCH/MOVE routines that allow access to the full power of those commands. Small refactoring of planner(), pg_plan_query(), and pg_plan_queries() APIs to make it convenient to pass the planning options down from SPI. This is the core-code portion of Pavel Stehule's patch for scrollable cursor support in plpgsql; I'll review and apply the plpgsql changes separately.
1 parent fa92d21 commit 66888f7

File tree

15 files changed

+435
-71
lines changed

15 files changed

+435
-71
lines changed

‎doc/src/sgml/spi.sgml

Lines changed: 318 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/spi.sgml,v 1.55 2007/03/25 23:27:59 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/spi.sgml,v 1.56 2007/04/16 01:14:55 tgl Exp $ -->
22

33
<chapter id="spi">
44
<title>Server Programming Interface</title>
@@ -799,6 +799,104 @@ SPIPlanPtr SPI_prepare(const char * <parameter>command</parameter>, int <paramet
799799

800800
<!-- *********************************************** -->
801801

802+
<refentry id="spi-spi-prepare-cursor">
803+
<refmeta>
804+
<refentrytitle>SPI_prepare_cursor</refentrytitle>
805+
</refmeta>
806+
807+
<refnamediv>
808+
<refname>SPI_prepare_cursor</refname>
809+
<refpurpose>prepare a plan for a command, without executing it yet</refpurpose>
810+
</refnamediv>
811+
812+
<indexterm><primary>SPI_prepare_cursor</primary></indexterm>
813+
814+
<refsynopsisdiv>
815+
<synopsis>
816+
SPIPlanPtr SPI_prepare_cursor(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>, int <parameter>cursorOptions</parameter>)
817+
</synopsis>
818+
</refsynopsisdiv>
819+
820+
<refsect1>
821+
<title>Description</title>
822+
823+
<para>
824+
<function>SPI_prepare_cursor</function> is identical to
825+
<function>SPI_prepare</function>, except that it also allows specification
826+
of the planner's <quote>cursor options</> parameter. This is a bitmask
827+
having the values shown in <filename>nodes/parsenodes.h</filename>
828+
for the <structfield>options</> field of <structname>DeclareCursorStmt</>.
829+
<function>SPI_prepare</function> always takes these options as zero.
830+
</para>
831+
</refsect1>
832+
833+
<refsect1>
834+
<title>Arguments</title>
835+
836+
<variablelist>
837+
<varlistentry>
838+
<term><literal>const char * <parameter>command</parameter></literal></term>
839+
<listitem>
840+
<para>
841+
command string
842+
</para>
843+
</listitem>
844+
</varlistentry>
845+
846+
<varlistentry>
847+
<term><literal>int <parameter>nargs</parameter></literal></term>
848+
<listitem>
849+
<para>
850+
number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
851+
</para>
852+
</listitem>
853+
</varlistentry>
854+
855+
<varlistentry>
856+
<term><literal>Oid * <parameter>argtypes</parameter></literal></term>
857+
<listitem>
858+
<para>
859+
pointer to an array containing the <acronym>OID</acronym>s of
860+
the data types of the parameters
861+
</para>
862+
</listitem>
863+
</varlistentry>
864+
865+
<varlistentry>
866+
<term><literal>int <parameter>cursorOptions</parameter></literal></term>
867+
<listitem>
868+
<para>
869+
integer bitmask of cursor options; zero produces default behavior
870+
</para>
871+
</listitem>
872+
</varlistentry>
873+
</variablelist>
874+
</refsect1>
875+
876+
<refsect1>
877+
<title>Return Value</title>
878+
879+
<para>
880+
<function>SPI_prepare_cursor</function> has the same return conventions as
881+
<function>SPI_prepare</function>.
882+
</para>
883+
</refsect1>
884+
885+
<refsect1>
886+
<title>Notes</title>
887+
888+
<para>
889+
Useful bits to set in <parameter>cursorOptions</> include
890+
<symbol>CURSOR_OPT_SCROLL</symbol>,
891+
<symbol>CURSOR_OPT_NO_SCROLL</symbol>, and
892+
<symbol>CURSOR_OPT_FAST_PLAN</symbol>. Note in particular that
893+
<symbol>CURSOR_OPT_HOLD</symbol> is ignored.
894+
</para>
895+
</refsect1>
896+
</refentry>
897+
898+
<!-- *********************************************** -->
899+
802900
<refentry id="spi-spi-getargcount">
803901
<refmeta>
804902
<refentrytitle>SPI_getargcount</refentrytitle>
@@ -1430,7 +1528,9 @@ void SPI_cursor_fetch(Portal <parameter>portal</parameter>, bool <parameter>forw
14301528

14311529
<para>
14321530
<function>SPI_cursor_fetch</function> fetches some rows from a
1433-
cursor. This is equivalent to the SQL command <command>FETCH</>.
1531+
cursor. This is equivalent to a subset of the SQL command
1532+
<command>FETCH</> (see <function>SPI_scroll_cursor_fetch</function>
1533+
for more functionality).
14341534
</para>
14351535
</refsect1>
14361536

@@ -1476,6 +1576,15 @@ void SPI_cursor_fetch(Portal <parameter>portal</parameter>, bool <parameter>forw
14761576
<function>SPI_execute</function> if successful.
14771577
</para>
14781578
</refsect1>
1579+
1580+
<refsect1>
1581+
<title>Notes</title>
1582+
1583+
<para>
1584+
Fetching backward may fail if the cursor's plan was not created
1585+
with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
1586+
</para>
1587+
</refsect1>
14791588
</refentry>
14801589

14811590
<!-- *********************************************** -->
@@ -1503,8 +1612,9 @@ void SPI_cursor_move(Portal <parameter>portal</parameter>, bool <parameter>forwa
15031612

15041613
<para>
15051614
<function>SPI_cursor_move</function> skips over some number of rows
1506-
in a cursor. This is equivalent to the SQL command
1507-
<command>MOVE</>.
1615+
in a cursor. This is equivalent to a subset of the SQL command
1616+
<command>MOVE</> (see <function>SPI_scroll_cursor_move</function>
1617+
for more functionality).
15081618
</para>
15091619
</refsect1>
15101620

@@ -1540,6 +1650,210 @@ void SPI_cursor_move(Portal <parameter>portal</parameter>, bool <parameter>forwa
15401650
</varlistentry>
15411651
</variablelist>
15421652
</refsect1>
1653+
1654+
<refsect1>
1655+
<title>Notes</title>
1656+
1657+
<para>
1658+
Moving backward may fail if the cursor's plan was not created
1659+
with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
1660+
</para>
1661+
</refsect1>
1662+
</refentry>
1663+
1664+
<!-- *********************************************** -->
1665+
1666+
<refentry id="spi-spi-scroll-cursor-fetch">
1667+
<refmeta>
1668+
<refentrytitle>SPI_scroll_cursor_fetch</refentrytitle>
1669+
</refmeta>
1670+
1671+
<refnamediv>
1672+
<refname>SPI_scroll_cursor_fetch</refname>
1673+
<refpurpose>fetch some rows from a cursor</refpurpose>
1674+
</refnamediv>
1675+
1676+
<indexterm><primary>SPI_scroll_cursor_fetch</primary></indexterm>
1677+
1678+
<refsynopsisdiv>
1679+
<synopsis>
1680+
void SPI_scroll_cursor_fetch(Portal <parameter>portal</parameter>, FetchDirection <parameter>direction</parameter>, long <parameter>count</parameter>)
1681+
</synopsis>
1682+
</refsynopsisdiv>
1683+
1684+
<refsect1>
1685+
<title>Description</title>
1686+
1687+
<para>
1688+
<function>SPI_scroll_cursor_fetch</function> fetches some rows from a
1689+
cursor. This is equivalent to the SQL command <command>FETCH</>.
1690+
</para>
1691+
</refsect1>
1692+
1693+
<refsect1>
1694+
<title>Arguments</title>
1695+
1696+
<variablelist>
1697+
<varlistentry>
1698+
<term><literal>Portal <parameter>portal</parameter></literal></term>
1699+
<listitem>
1700+
<para>
1701+
portal containing the cursor
1702+
</para>
1703+
</listitem>
1704+
</varlistentry>
1705+
1706+
<varlistentry>
1707+
<term><literal>FetchDirection <parameter>direction</parameter></literal></term>
1708+
<listitem>
1709+
<para>
1710+
one of <symbol>FETCH_FORWARD</symbol>,
1711+
<symbol>FETCH_BACKWARD</symbol>,
1712+
<symbol>FETCH_ABSOLUTE</symbol> or
1713+
<symbol>FETCH_RELATIVE</symbol>
1714+
</para>
1715+
</listitem>
1716+
</varlistentry>
1717+
1718+
<varlistentry>
1719+
<term><literal>long <parameter>count</parameter></literal></term>
1720+
<listitem>
1721+
<para>
1722+
number of rows to fetch for
1723+
<symbol>FETCH_FORWARD</symbol> or
1724+
<symbol>FETCH_BACKWARD</symbol>; absolute row number to fetch for
1725+
<symbol>FETCH_ABSOLUTE</symbol>; or relative row number to fetch for
1726+
<symbol>FETCH_RELATIVE</symbol>
1727+
</para>
1728+
</listitem>
1729+
</varlistentry>
1730+
</variablelist>
1731+
</refsect1>
1732+
1733+
<refsect1>
1734+
<title>Return Value</title>
1735+
1736+
<para>
1737+
<varname>SPI_processed</varname> and
1738+
<varname>SPI_tuptable</varname> are set as in
1739+
<function>SPI_execute</function> if successful.
1740+
</para>
1741+
</refsect1>
1742+
1743+
<refsect1>
1744+
<title>Notes</title>
1745+
1746+
<para>
1747+
See the SQL <xref linkend="sql-fetch" endterm="sql-fetch-title"> command
1748+
for details of the interpretation of the
1749+
<parameter>direction</parameter> and
1750+
<parameter>count</parameter> parameters.
1751+
</para>
1752+
1753+
<para>
1754+
Direction values other than <symbol>FETCH_FORWARD</symbol>
1755+
may fail if the cursor's plan was not created
1756+
with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
1757+
</para>
1758+
</refsect1>
1759+
</refentry>
1760+
1761+
<!-- *********************************************** -->
1762+
1763+
<refentry id="spi-spi-scroll-cursor-move">
1764+
<refmeta>
1765+
<refentrytitle>SPI_scroll_cursor_move</refentrytitle>
1766+
</refmeta>
1767+
1768+
<refnamediv>
1769+
<refname>SPI_scroll_cursor_move</refname>
1770+
<refpurpose>move a cursor</refpurpose>
1771+
</refnamediv>
1772+
1773+
<indexterm><primary>SPI_scroll_cursor_move</primary></indexterm>
1774+
1775+
<refsynopsisdiv>
1776+
<synopsis>
1777+
void SPI_scroll_cursor_move(Portal <parameter>portal</parameter>, FetchDirection <parameter>direction</parameter>, long <parameter>count</parameter>)
1778+
</synopsis>
1779+
</refsynopsisdiv>
1780+
1781+
<refsect1>
1782+
<title>Description</title>
1783+
1784+
<para>
1785+
<function>SPI_scroll_cursor_move</function> skips over some number of rows
1786+
in a cursor. This is equivalent to the SQL command
1787+
<command>MOVE</>.
1788+
</para>
1789+
</refsect1>
1790+
1791+
<refsect1>
1792+
<title>Arguments</title>
1793+
1794+
<variablelist>
1795+
<varlistentry>
1796+
<term><literal>Portal <parameter>portal</parameter></literal></term>
1797+
<listitem>
1798+
<para>
1799+
portal containing the cursor
1800+
</para>
1801+
</listitem>
1802+
</varlistentry>
1803+
1804+
<varlistentry>
1805+
<term><literal>FetchDirection <parameter>direction</parameter></literal></term>
1806+
<listitem>
1807+
<para>
1808+
one of <symbol>FETCH_FORWARD</symbol>,
1809+
<symbol>FETCH_BACKWARD</symbol>,
1810+
<symbol>FETCH_ABSOLUTE</symbol> or
1811+
<symbol>FETCH_RELATIVE</symbol>
1812+
</para>
1813+
</listitem>
1814+
</varlistentry>
1815+
1816+
<varlistentry>
1817+
<term><literal>long <parameter>count</parameter></literal></term>
1818+
<listitem>
1819+
<para>
1820+
number of rows to move for
1821+
<symbol>FETCH_FORWARD</symbol> or
1822+
<symbol>FETCH_BACKWARD</symbol>; absolute row number to move to for
1823+
<symbol>FETCH_ABSOLUTE</symbol>; or relative row number to move to for
1824+
<symbol>FETCH_RELATIVE</symbol>
1825+
</para>
1826+
</listitem>
1827+
</varlistentry>
1828+
</variablelist>
1829+
</refsect1>
1830+
1831+
<refsect1>
1832+
<title>Return Value</title>
1833+
1834+
<para>
1835+
<varname>SPI_processed</varname> and
1836+
<varname>SPI_tuptable</varname> are set as in
1837+
<function>SPI_execute</function> if successful.
1838+
</para>
1839+
</refsect1>
1840+
1841+
<refsect1>
1842+
<title>Notes</title>
1843+
1844+
<para>
1845+
See the SQL <xref linkend="sql-fetch" endterm="sql-fetch-title"> command
1846+
for details of the interpretation of the
1847+
<parameter>direction</parameter> and
1848+
<parameter>count</parameter> parameters.
1849+
</para>
1850+
1851+
<para>
1852+
Direction values other than <symbol>FETCH_FORWARD</symbol>
1853+
may fail if the cursor's plan was not created
1854+
with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
1855+
</para>
1856+
</refsect1>
15431857
</refentry>
15441858

15451859
<!-- *********************************************** -->

‎src/backend/commands/copy.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
*
99
*
1010
* IDENTIFICATION
11-
* $PostgreSQL: pgsql/src/backend/commands/copy.c,v 1.279 2007/03/29 00:15:38 tgl Exp $
11+
* $PostgreSQL: pgsql/src/backend/commands/copy.c,v 1.280 2007/04/16 01:14:55 tgl Exp $
1212
*
1313
*-------------------------------------------------------------------------
1414
*/
@@ -1023,7 +1023,7 @@ DoCopy(const CopyStmt *stmt, const char *queryString)
10231023
errmsg("COPY (SELECT INTO) is not supported")));
10241024

10251025
/* plan the query */
1026-
plan = planner(query, false, 0, NULL);
1026+
plan = planner(query, 0, NULL);
10271027

10281028
/*
10291029
* Update snapshot command ID to ensure this query sees results of any

0 commit comments

Comments
 (0)