<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.26 2003/09/12 22:17:23 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.27 2003/09/23 19:58:50 tgl Exp $
-->
<chapter id="plpgsql">
<para>
That means that your client application must send each query to
- the database server, wait for it to process it, receive the
+ the database server, wait for it to be processed, receive the
results, do some computation, then send other queries to the
server. All this incurs interprocess communication and may also
incur network overhead if your client is on a different machine
an existing table or view, by using the
<replaceable>table_name</replaceable><literal>%ROWTYPE</literal>
notation; or it can be declared by giving a composite type's name.
- (Since every table has an associated datatype of the same name,
+ (Since every table has an associated composite type of the same name,
it actually does not matter in <productname>PostgreSQL</> whether you
write <literal>%ROWTYPE</literal> or not. But the form with
<literal>%ROWTYPE</literal> is more portable.)
variable, or list of scalar variables. This is done by:
<synopsis>
-SELECT INTO <replaceable>target</replaceable> <replaceable>expressions</replaceable> FROM ...;
+SELECT INTO <replaceable>target</replaceable> <replaceable>select_expressions</replaceable> FROM ...;
</synopsis>
where <replaceable>target</replaceable> can be a record variable, a row
variable, or a comma-separated list of simple variables and
- record/row fields.
+ record/row fields. The <replaceable>select_expressions</replaceable>
+ and the remainder of the command are the same as in regular SQL.
</para>
<para>
The results from <command>SELECT</command> commands are discarded
by <command>EXECUTE</command>, and <command>SELECT INTO</command>
is not currently supported within <command>EXECUTE</command>.
- So, the only way to extract a result from a dynamically-created
- <command>SELECT</command> is to use the <command>FOR-IN-EXECUTE</> form
- described later.
+ There are two ways to extract a result from a dynamically-created
+ <command>SELECT</command>: one is to use the <command>FOR-IN-EXECUTE</>
+ loop form described in <xref linkend="plpgsql-records-iterating">,
+ and the other is to use a cursor with <command>OPEN-FOR-EXECUTE</>, as
+ described in <xref linkend="plpgsql-cursor-opening">.
</para>
<para>
<function>quote_literal(<type>text</type>)</function>.<indexterm><primary>quote_ident</><secondary>use
in
PL/pgSQL</></indexterm><indexterm><primary>quote_literal</><secondary>use
- in PL/pgSQL</></indexterm> Variables containing column and table
- identifiers should be passed to function
+ in PL/pgSQL</></indexterm> For safety, variables containing column and
+ table identifiers should be passed to function
<function>quote_ident</function>. Variables containing values
that should be literal strings in the constructed command should
be passed to <function>quote_literal</function>. Both take the
<para>
There are several ways to determine the effect of a command. The
- first method is to use the <command>GET DIAGNOSTICS</command>,
- which has the form:
+ first method is to use the <command>GET DIAGNOSTICS</command>
+ command, which has the form:
<synopsis>
GET DIAGNOSTICS <replaceable>variable</replaceable> = <replaceable>item</replaceable> <optional> , ... </optional> ;
<para>
An example:
<programlisting>
-GET DIAGNOSTICS var_integer = ROW_COUNT;
+GET DIAGNOSTICS integer_var = ROW_COUNT;
</programlisting>
</para>
<para>
- The second method to determine the effects of a command is the
- special variable named <literal>FOUND</literal> of
+ The second method to determine the effects of a command is to check the
+ special variable named <literal>FOUND</literal>, which is of
type <type>boolean</type>. <literal>FOUND</literal> starts out
- false within each <application>PL/pgSQL</application> function.
+ false within each <application>PL/pgSQL</application> function call.
It is set by each of the following types of statements:
<itemizedlist>
<listitem>
<listitem>
<para>
A <command>PERFORM</> statement sets <literal>FOUND</literal>
- true if it produces (discards) a row, false if no row is
+ true if it produces (and discards) a row, false if no row is
produced.
</para>
</listitem>
<command>RETURN</command> with an expression terminates the
function and returns the value of
<replaceable>expression</replaceable> to the caller. This form
- is to be used for <application>PL/pgSQL</> functions that does
+ is to be used for <application>PL/pgSQL</> functions that do
not return a set.
</para>
The return value of a function cannot be left undefined. If
control reaches the end of the top-level block of the function
without hitting a <command>RETURN</command> statement, a run-time
- error will occur. Note that if you have declared the function to
+ error will occur.
+ </para>
+
+ <para>
+ If you have declared the function to
return <type>void</type>, a <command>RETURN</command> statement
- must still be specified; the expression following
- <command>RETURN</command> is, however, optional and will be ignored in
- any case.
+ must still be specified; but in this case the expression following
+ <command>RETURN</command> is optional and will be ignored if present.
</para>
</sect3>
to follow is slightly different. In that case, the individual
items to return are specified in <command>RETURN NEXT</command>
commands, and then a final <command>RETURN</command> command
- with no arguments is used to indicate that the function has
+ with no argument is used to indicate that the function has
finished executing. <command>RETURN NEXT</command> can be used
- with both scalar and composite data types; in the later case, an
+ with both scalar and composite data types; in the latter case, an
entire <quote>table</quote> of results will be returned.
</para>
written to disk to avoid memory exhaustion, but the function
itself will not return until the entire result set has been
generated. A future version of <application>PL/pgSQL</> may
- allow users to allow users to define set-returning functions
+ allow users to define set-returning functions
that do not have this limitation. Currently, the point at
which data begins being written to disk is controlled by the
<varname>sort_mem</> configuration variable. Administrators
<programlisting>
LOOP
-- some computations
- IF count > 0 THEN
+ IF count > 0 THEN
EXIT; -- exit loop
END IF;
END LOOP;
LOOP
-- some computations
- EXIT WHEN count > 0;
+ EXIT WHEN count > 0; -- same result as previous example
END LOOP;
BEGIN
-- some computations
- IF stocks > 100000 THEN
+ IF stocks > 100000 THEN
EXIT; -- invalid; cannot use EXIT outside of LOOP
END IF;
END;
<para>
For example:
<programlisting>
-WHILE amount_owed > 0 AND gift_certificate_balance > 0 LOOP
+WHILE amount_owed > 0 AND gift_certificate_balance > 0 LOOP
-- some computations here
END LOOP;
Some examples of integer <literal>FOR</> loops:
<programlisting>
FOR i IN 1..10 LOOP
- -- some expressions here
+ -- some computations here
RAISE NOTICE ''i is %'', i;
END LOOP;
FOR i IN REVERSE 10..1 LOOP
- -- some expressions here
+ -- some computations here
END LOOP;
</programlisting>
</para>
<para>
- If the lower bound is greater than the upper bound, the loop body is not
- executed at all, but no error is raised.
+ If the lower bound is greater than the upper bound (or less than,
+ in the <literal>REVERSE</> case), the loop body is not
+ executed at all. No error is raised.
</para>
</sect3>
</sect2>
declared as a record or row variable. If not, it's presumed to be
an integer <literal>FOR</> loop. This can cause rather nonintuitive error
messages when the true problem is, say, that one has
- misspelled the variable name after the <literal>FOR</>.
+ misspelled the variable name after the <literal>FOR</>. Typically
+ the complaint will be something like <literal>missing ".." at end of SQL
+ expression</>.
</para>
</note>
</sect2>
rows. (However, <application>PL/pgSQL</> users do not normally need
to worry about that, since <literal>FOR</> loops automatically use a cursor
internally to avoid memory problems.) A more interesting usage is to
- return a reference to a cursor that it has created, allowing the
+ return a reference to a cursor that a function has created, allowing the
caller to read the rows. This provides an efficient way to return
large row sets from functions.
</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
- three forms of the <command>OPEN</> statement, two of which use unbound cursor
- variables and the other uses a bound cursor variable.
+ three forms of the <command>OPEN</> statement, two of which use unbound
+ cursor variables while the third uses a bound cursor variable.
</para>
<sect3>
</synopsis>
<para>
- <command>CLOSE</command> closes the Portal underlying an open
+ <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>
<application>PL/pgSQL</> functions can return cursors to the
- caller. This is used to return multiple rows or columns from
- the function. To do this, the function opens the cursor and returns the
- cursor name to the caller. The caller can then
- fetch rows from the cursor. The cursor can
- be closed by the caller, or it will be closed automatically
+ caller. This is useful to return multiple rows or columns,
+ especially with very large result sets. To do this, the function
+ opens the cursor and returns the cursor name to the caller (or simply
+ opens the cursor using a portal name specified by or otherwise known
+ to the caller). The caller can then fetch rows from the cursor. The
+ cursor can be closed by the caller, or it will be closed automatically
when the transaction closes.
</para>
<para>
- The cursor name returned by the function can be specified by the
- caller or automatically generated. The following example shows
- how a cursor name can be supplied by the caller:
+ The portal name used for a cursor can be specified by the
+ programmer or automatically generated. To specify a portal name,
+ simply assign a string to the <type>refcursor</> variable before
+ opening it. The string value of the <type>refcursor</> variable
+ will be used by <command>OPEN</> as the name of the underlying portal.
+ However, if the <type>refcursor</> variable is NULL,
+ <command>OPEN</> automatically generates a name that does not
+ conflict with any existing portal, and assigns it to the
+ <type>refcursor</> variable.
+ </para>
+
+ <note>
+ <para>
+ A bound cursor variable is initialized to the string value
+ representing its name, so that the portal name is the same as
+ the cursor variable name, unless the programmer overrides it
+ by assignment before opening the cursor. But an unbound cursor
+ variable defaults to an initial value of NULL, so it will receive
+ an automatically-generated unique name, unless overridden.
+ </para>
+ </note>
+
+ <para>
+ The following example shows one way a cursor name can be supplied by
+ the caller:
<programlisting>
CREATE TABLE test (col text);
<para>
<application>PL/pgSQL</application> can be used to define trigger
procedures. A trigger procedure is created with the
- <command>CREATE FUNCTION</> command as a function with no
- arguments and a return type of <type>trigger</type>. Note that
+ <command>CREATE FUNCTION</> command, declaring it as a function with
+ no arguments and a return type of <type>trigger</type>. Note that
the function must be declared with no arguments even if it expects
to receive arguments specified in <command>CREATE TRIGGER</> ---
trigger arguments are passed via <varname>TG_ARGV</>, as described
<para>
A trigger function must return either null or a record/row value
having exactly the structure of the table the trigger was fired
- for. The return value of a <literal>BEFORE</> or <literal>AFTER</> statement-level
- trigger or an <literal>AFTER</> row-level trigger is ignored; it may as well
- be null. However, any of these types of triggers can still
- abort the entire trigger operation by raising an error.
+ for.
</para>
<para>
Row-level triggers fired <literal>BEFORE</> may return null to signal the
trigger manager to skip the rest of the operation for this row
(i.e., subsequent triggers are not fired, and the
- <command>INSERT</>/<command>UPDATE</>/<command>DELETE</> does not occur for this row). If a nonnull
+ <command>INSERT</>/<command>UPDATE</>/<command>DELETE</> does not occur
+ for this row). If a nonnull
value is returned then the operation proceeds with that row value.
Returning a row value different from the original value
- of <varname>NEW</> alters the row that will be inserted or updated. It is
- possible to replace single values directly in <varname>NEW</> and return <varname>NEW</>,
+ of <varname>NEW</> alters the row that will be inserted or updated
+ (but has no direct effect in the <command>DELETE</> case).
+ To alter the row to be stored, it is possible to replace single values
+ directly in <varname>NEW</> and return the modified <varname>NEW</>,
or to build a complete new record/row to return.
</para>
+ <para>
+ The return value of a <literal>BEFORE</> or <literal>AFTER</>
+ statement-level trigger or an <literal>AFTER</> row-level trigger is
+ always ignored; it may as well be null. However, any of these types of
+ triggers can still abort the entire operation by raising an error.
+ </para>
+
<para>
<xref linkend="plpgsql-trigger-example"> shows an example of a
trigger procedure in <application>PL/pgSQL</application>.
<para>
This example trigger ensures that any time a row is inserted or updated
in the table, the current user name and time are stamped into the
- row. And it ensures that an employee's name is given and that the
+ row. And it checks that an employee's name is given and that the
salary is a positive value.
</para>
This section explains differences between
<productname>PostgreSQL</>'s <application>PL/pgSQL</application>
language and Oracle's <application>PL/SQL</application> language,
- to help developers that port applications from Oracle to
+ to help developers who port applications from Oracle to
<productname>PostgreSQL</>.
</para>
<para>
The <application>PL/pgSQL</> version of
- <command>EXECUTE</command> works similar to the
+ <command>EXECUTE</command> works similarly to the
<application>PL/SQL</> version, but you have to remember to use
<function>quote_literal(text)</function> and
<function>quote_string(text)</function> as described in <xref
projects / postgresql / commitdiff