the function without hitting a RETURN statement, a runtime error
will occur.
</para>
</sect3>
</sect2>
<sect3 id="plpgsql-conditionals">
<title>Conditional Control: IF statements</title>
<sect2 id="plpgsql-conditionals">
<title>Conditionals</title>
<para>
<function>IF</function> statements let you execute commands based on
<function>IF</function> statements let you execute commands based on
certain conditions.
<application>PL/pgSQL</> has four forms of IF: IF-THEN, IF-THEN-ELSE,
IF-THEN-ELSE IF, IF-THEN-ELSIF-THEN-ELSE.
IF-THEN-ELSE IF, and IF-THEN-ELSIF-THEN-ELSE.
</para>
<variablelist>
<varlistentry>
<term>
IF-THEN
</term>
<sect3>
<title>IF-THEN</title>
<listitem>
<para>
<synopsis>
IF <replaceable>boolean-expression</replaceable> THEN
<replaceable>statements</replaceable>
END IF;
</synopsis>
IF-THEN statements are the simplest form of IF. The
statements between THEN and END IF will be executed if
the condition is true. Otherwise, they are skipped.
@ -1074,19 +1090,23 @@ IF v_user_id <> 0 THEN
END IF;
</programlisting>
</para>
</listitem>
</varlistentry>
</sect3>
<varlistentry>
<term>
IF-THEN-ELSE
</term>
<sect3>
<title>IF-THEN-ELSE</title>
<listitem>
<para>
<synopsis>
IF <replaceable>boolean-expression</replaceable> THEN
<replaceable>statements</replaceable>
ELSE
<replaceable>statements</replaceable>
END IF;
</synopsis>
IF-THEN-ELSE statements add to IF-THEN by letting you
specify a group of statements that should be executed if the
condition evaluates to FALSE.
specify an alternative set of statements that should be executed if
the condition evaluates to FALSE.
<programlisting>
IF parentid IS NULL or parentid = ''''
@ -1105,15 +1125,11 @@ ELSE
END IF;
</programlisting>
</para>
</listitem>
</varlistentry>
</sect3>
<varlistentry>
<term>
IF-THEN-ELSE IF
</term>
<sect3>
<title>IF-THEN-ELSE IF</title>
<listitem>
<para>
IF statements can be nested, as in the following example:
<programlisting>
@ -1135,16 +1151,27 @@ END IF;
This is workable but grows tedious when there are many
alternatives to be checked.
</para>
</listitem>
</varlistentry>
</sect3>
<varlistentry>
<term>
IF-THEN-ELSIF-ELSE
</term>
<sect3>
<title>IF-THEN-ELSIF-ELSE</title>
<listitem>
<para>
<synopsis>
IF <replaceable>boolean-expression</replaceable> THEN
<replaceable>statements</replaceable>
<optional> ELSIF <replaceable>boolean-expression</replaceable> THEN
<replaceable>statements</replaceable>
<optional> ELSIF <replaceable>boolean-expression</replaceable> THEN
<replaceable>statements</replaceable>
...
</optional>
</optional>
<optional> ELSE
<replaceable>statements</replaceable> </optional>
END IF;
</synopsis>
IF-THEN-ELSIF-ELSE provides a more convenient method of checking
many alternatives in one statement. Formally it is equivalent
to nested IF-THEN-ELSE-IF-THEN commands, but only one END IF
@ -1158,11 +1185,11 @@ END IF;
IF number = 0 THEN
result := ''zero'';
ELSIF number < 0 THEN
result := ''negative'';
result := ''positive'';
ELSIF number > 0 THEN
result := ''negative'';
ELSE
-- now it seems to be NULL
-- hmm, the only other possibility is that number IS NULL
result := ''NULL'';
END IF;
</programlisting>
@ -1171,29 +1198,22 @@ END IF;
<para>
The final ELSE section is optional.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect3>
</sect2>
<sect3 id="plpgsql-control-structures-loops">
<title>Iterative Control: LOOP, WHILE, FOR and EXIT</title>
<sect2 id="plpgsql-control-structures-loops">
<title>Simple Loops</title>
<para>
With the LOOP, WHILE, FOR and EXIT statements, you can arrange
With the LOOP, EXIT, WHILE and FOR statements, you can arrange
for your <application>PL/pgSQL</application> function to repeat
a series of commands.
</para>
<variablelist>
<varlistentry>
<term>
LOOP
</term>
<sect3>
<title>LOOP</title>
<listitem>
<para>
<synopsis>
<optional><<label>></optional>
@ -1201,37 +1221,36 @@ LOOP
<replaceable>statements</replaceable>
END LOOP;
</synopsis>
An unconditional loop that must be terminated explicitly
by an EXIT statement. The optional label can be used by
EXIT statements of nested loops to specify which level of
LOOP defines an unconditional loop that is repeated indefinitely
until terminated by an EXIT or RETURN statement.
The optional label can be used by
EXIT statements in nested loops to specify which level of
nesting should be terminated.
</para>
</listitem>
</varlistentry>
</sect3>
<varlistentry>
<term>
EXIT
</term>
<sect3>
<title>EXIT</title>
<listitem>
<para>
<synopsis>
EXIT <optional> <replaceable>label</replaceable> </optional> <optional> WHEN <replaceable>expression</replaceable> </optional>;
</synopsis>
If no <replaceable>label</replaceable> is given,
the innermost loop is terminated and the
statement following END LOOP is executed next.
If <replaceable>label</replaceable> is given, it
must be the label of the current or an outer level of nested loop
blocks. Then the named loop or block is terminated and control
must be the label of the current or some outer level of nested loop
or block. Then the named loop or block is terminated and control
continues with the statement after the loop's/block's corresponding
END.
</para>
<para>
If WHEN is present, loop exit occurs only if the specified condition
is true.
is true, otherwise control passes to the statement after EXIT.
</para>
<para>
@ -1257,26 +1276,26 @@ BEGIN
END;
</programlisting>
</para>
</listitem>
</varlistentry>
</sect3>
<varlistentry>
<term>
WHILE
</term>
<sect3>
<title>WHILE</title>
<listitem>
<para>
With the WHILE statement, you can repeat a
sequence of statements so long as the condition expression
evaluates to true. The condition is checked just before
each entry to the loop body.
<synopsis>
<optional><<label>></optional>
WHILE <replaceable>expression</replaceable> LOOP
<replaceable>statements</replaceable>
END LOOP;
</synopsis>
The WHILE statement repeats a
sequence of statements so long as the condition expression
evaluates to true. The condition is checked just before
each entry to the loop body.
</para>
<para>
For example:
<programlisting>
WHILE amount_owed > 0 AND gift_certificate_balance > 0 LOOP
@ -1288,25 +1307,22 @@ WHILE NOT boolean_expression LOOP
END LOOP;
</programlisting>
</para>
</listitem>
</varlistentry>
</sect3>
<varlistentry>
<term>
FOR
</term>
<sect3>
<title>FOR (integer for-loop)</title>
<listitem>
<para>
<synopsis>
<optional><<label>></optional>
FOR <replaceable>name</replaceable> IN <optional> REVERSE </optional> <replaceable>expression</replaceable> .. <replaceable>expression</replaceable> LOOP
<replaceable>statements</replaceable>
END LOOP;
</synopsis>
A loop that iterates over a range of integer values. The variable
<replaceable>name</replaceable> is automatically created as type
This form of FOR creates a loop that iterates over a range of integer
values. The variable
<replaceable>name</replaceable> is automatically defined as type
integer and exists only inside the loop. The two expressions giving
the lower and upper bound of the range are evaluated once when entering
the loop. The iteration step is normally 1, but is -1 when REVERSE is
@ -1327,18 +1343,16 @@ FOR i IN REVERSE 10..1 LOOP
END LOOP;
</programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect3>
</sect2>
<sect3 id="plpgsql-records-iterating">
<title>Iterating Through Records</title>
<sect2 id="plpgsql-records-iterating">
<title>Looping Through Query Results</title>
<para>
Using a different type of FOR loop, you can iterate through
the results of a query and manipulate that data
accordingly. The syntax is as follows:
accordingly. The syntax is:
<synopsis>
<optional><<label>></optional>
FOR <replaceable>record | row</replaceable> IN <replaceable>select_query</replaceable> LOOP
@ -1402,13 +1416,214 @@ END LOOP;
declared as a record/row variable. If not, it's presumed to be
an integer FOR loop. This can cause rather unintuitive error
messages when the true problem is, say, that one has
misspelled the FOR variable.
misspelled the FOR variable name.
</para>
</note>
</sect3>
</sect2>
</sect1>
<sect1 id="plpgsql-cursors">
<title>Cursors</title>
<para>
Rather than executing a whole query at once, it is possible to
set up a <firstterm>cursor</> that encapsulates the query, and
then read the query result a few rows at a time. One reason
for doing this is to avoid memory overrun when the result contains
a large number of rows. (However, <application>PL/pgSQL</> users
don't normally need to worry about that, since FOR loops automatically
use a cursor internally to avoid memory problems.) A more interesting
possibility is that a function can return a reference to a cursor
that it has set up, allowing the caller to read the rows. This
provides one way of returning a rowset from a function.
</para>
<sect2 id="plpgsql-cursor-declarations">
<title>Declaring Cursor Variables</title>
<para>
All access to cursors in <application>PL/pgSQL</> goes through
cursor variables, which are always of the special datatype
<type>refcursor</>. One way to create a cursor variable
is just to declare it as a variable of type <type>refcursor</>.
Another way is to use the cursor declaration syntax,
which in general is:
<synopsis>
<replaceable>name</replaceable> CURSOR <optional> ( <replaceable>arguments</replaceable> ) </optional> FOR <replaceable>select_query</replaceable> ;
</synopsis>
(<literal>FOR</> may be replaced by <literal>IS</> for Oracle
compatibility.) <replaceable>arguments</replaceable>, if any,
are a comma-separated list of <replaceable>name</replaceable>
<replaceable>datatype</replaceable> pairs that define names to
be replaced by parameter values in the given query. The actual
values to substitute for these names will be specified later,
when the cursor is opened.
</para>
<para>
Some examples:
<programlisting>
DECLARE
curs1 refcursor;
curs2 CURSOR FOR SELECT * from tenk1;
curs3 CURSOR (key int) IS SELECT * from tenk1 where unique1 = key;
</programlisting>
All three of these variables have the datatype <type>refcursor</>,
but the first may be used with any query, while the second has
a fully specified query already <firstterm>bound</> to it, and the last
has a parameterized query bound to it. (<literal>key</> will be
replaced by an integer parameter value when the cursor is opened.)
The variable <literal>curs1</>
is said to be <firstterm>unbound</> since it is not bound to
any particular query.
</para>
</sect2>
<sect2 id="plpgsql-cursor-opening">
<title>Opening Cursors</title>
<para>
Before a cursor can be used to retrieve rows, it must be
<firstterm>opened</>. (This is the equivalent action to
the SQL command <command>DECLARE CURSOR</>.)
<application>PL/pgSQL</> has four forms of the OPEN statement,
two of which are for use with unbound cursor variables
and the other two for use with bound cursor variables.
</para>
<sect3>
<title>OPEN FOR SELECT</title>
<para>
<synopsis>
OPEN <replaceable>unbound-cursor</replaceable> FOR SELECT ...;
</synopsis>
The cursor variable is opened and given the specified query
to execute. The cursor cannot be open already, and it must
have been declared as an unbound cursor (that is, as a simple
<type>refcursor</> variable). The SELECT query is treated
in the same way as other SELECTs in <application>PL/pgSQL</>:
<application>PL/pgSQL</> variable names are substituted for,
and the query plan is cached for possible re-use.
<programlisting>
OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey;
</programlisting>
</para>
</sect3>
<sect3>
<title>OPEN FOR EXECUTE</title>
<para>
<synopsis>
OPEN <replaceable>unbound-cursor</replaceable> FOR EXECUTE <replaceable class="command">query-string</replaceable>;
</synopsis>
The cursor variable is opened and given the specified query
to execute. The cursor cannot be open already, and it must
have been declared as an unbound cursor (that is, as a simple
<type>refcursor</> variable). The query is specified as a
string expression in the same way as for the EXECUTE command.
As usual, this gives flexibility for the query to vary
from one run to the next.
<programlisting>
OPEN curs1 FOR EXECUTE ''SELECT * FROM '' || quote_ident($1);
</programlisting>
</para>
</sect3>
<sect3>
<title>OPENing a bound cursor</title>
<para>
<synopsis>
OPEN <replaceable>bound-cursor</replaceable> <optional> ( <replaceable>argument_values</replaceable> ) </optional>;
</synopsis>
This form of OPEN is used to open a cursor variable whose query
was bound to it when it was declared.
The cursor cannot be open already. A list of actual argument
value expressions must appear if and only if the cursor was
declared to take arguments. These values will be substituted
into the query.
The query plan for a bound cursor is always considered
cacheable --- there is no equivalent of EXECUTE in this case.
<programlisting>
OPEN curs2;
OPEN curs3(42);
</programlisting>
</para>
</sect3>
</sect2>
<sect2 id="plpgsql-cursor-using">
<title>Using Cursors</title>
<para>
Once a cursor has been opened, it can be manipulated with the
statements described here.
</para>
<para>
These manipulations need not occur in the same function that
opened the cursor to begin with. You can return a <type>refcursor</>
value out of a function and let the caller operate on the cursor.
(Internally, a <type>refcursor</> value is simply the string name
of a Portal containing the active query for the cursor. This name
can be passed around, assigned to other <type>refcursor</> variables,
and so on, without disturbing the Portal.)
</para>
<para>
All Portals are implicitly closed at end of transaction. Therefore
a <type>refcursor</> value is useful to reference an open cursor
only until the end of the transaction.
</para>
<sect3>
<title>FETCH</title>
<para>
<synopsis>
FETCH <replaceable>cursor</replaceable> INTO <replaceable>target</replaceable>;
</synopsis>
FETCH retrieves the next row from the cursor into a target,
which may be a row variable, a record variable, or a comma-separated
list of simple variables, just as for SELECT INTO. As with
SELECT INTO, the special variable FOUND may be checked to see
whether a row was obtained or not.
<programlisting>
FETCH curs1 INTO rowvar;
FETCH curs2 INTO foo,bar,baz;
</programlisting>
</para>
</sect3>
<sect3>
<title>CLOSE</title>
<para>
<synopsis>
CLOSE <replaceable>cursor</replaceable>;
</synopsis>
CLOSE 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.
Tom Lane
24 years ago