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
table_name%ROWTYPE
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
PostgreSQL whether you write %ROWTYPE or not. But the form with
%ROWTYPE is more portable.)
variable, or list of scalar variables. This is done by:
-SELECT INTO target expressions FROM ...;
+SELECT INTO target select_expressions FROM ...;
where target can be a record variable, a row
variable, or a comma-separated list of simple variables and
- record/row fields.
+ record/row fields. The select_expressions
+ and the remainder of the command are the same as in regular SQL.
The results from SELECT commands are discarded
by EXECUTE, and SELECT INTO
is not currently supported within EXECUTE.
- So, the only way to extract a result from a dynamically-created
- SELECT is to use the FOR-IN-EXECUTE form
- described later.
+ There are two ways to extract a result from a dynamically-created
+ SELECT: one is to use the FOR-IN-EXECUTE
+ loop form described in ,
+ and the other is to use a cursor with OPEN-FOR-EXECUTE, as
+ described in .
quote_literal(text).
quote_identuse
in
- in PL/pgSQL Variables containing column and table
- identifiers should be passed to function
+ in PL/pgSQL For safety, variables containing column and
+ table identifiers should be passed to function
quote_ident. Variables containing values
that should be literal strings in the constructed command should
be passed to quote_literal. Both take the
There are several ways to determine the effect of a command. The
- first method is to use the GET DIAGNOSTICS,
- which has the form:
+ first method is to use the GET DIAGNOSTICS
+ command, which has the form:
GET DIAGNOSTICS variable = item , ... ;
An example:
-GET DIAGNOSTICS var_integer = ROW_COUNT;
+GET DIAGNOSTICS integer_var = ROW_COUNT;
- The second method to determine the effects of a command is the
- special variable named FOUND of
+ The second method to determine the effects of a command is to check the
+ special variable named FOUND, which is of
type boolean. FOUND starts out
- false within each
PL/pgSQL function.
+ false within each
PL/pgSQL function
call.
It is set by each of the following types of statements:
A PERFORM statement sets FOUND
- 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.
RETURN with an expression terminates the
function and returns the value of
expression to the caller. This form
- is to be used for
PL/pgSQL functions that does+ is to be used for
PL/pgSQL functions that do not return a set.
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 RETURN statement, a run-time
- error will occur. Note that if you have declared the function to
+ error will occur.
+
+
+ If you have declared the function to
return void, a RETURN statement
- must still be specified; the expression following
- RETURN is, however, optional and will be ignored in
- any case.
+ must still be specified; but in this case the expression following
+ RETURN is optional and will be ignored if present.
to follow is slightly different. In that case, the individual
items to return are specified in RETURN NEXT
commands, and then a final RETURN 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. RETURN NEXT 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 table
of results will be returned.
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
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
sort_mem configuration variable. Administrators
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;
For example:
-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 FOR loops:
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;
- 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 REVERSE case), the loop body is not
+ executed at all. No error is raised.
declared as a record or row variable. If not, it's presumed to be
an integer FOR loop. This can cause rather nonintuitive error
messages when the true problem is, say, that one has
- misspelled the variable name after the FOR.
+ misspelled the variable name after the FOR. Typically
+ the complaint will be something like missing ".." at end of SQL
+ expression.
rows. (However,
PL/pgSQL users do not normally need to worry about that, since 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.
Before a cursor can be used to retrieve rows, it must be
opened. (This is the equivalent action to the SQL
command
DECLARE CURSOR.) PL/pgSQL has- three forms of the OPEN statement, two of which use unbound cursor
- variables and the other uses a bound cursor variable.
+ three forms of the OPEN statement, two of which use unbound
+ cursor variables while the third uses a bound cursor variable.
- CLOSE closes the Portal underlying an open
+ 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.
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.
- 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 refcursor variable before
+ opening it. The string value of the refcursor variable
+ will be used by OPEN as the name of the underlying portal.
+ However, if the refcursor variable is NULL,
+ OPEN automatically generates a name that does not
+ conflict with any existing portal, and assigns it to the
+ refcursor variable.
+
+
+
+ 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.
+
+
+
+ The following example shows one way a cursor name can be supplied by
+ the caller:
CREATE TABLE test (col text);
PL/pgSQL can be used to define trigger
procedures. A trigger procedure is created with the
- CREATE FUNCTION command as a function with no
- arguments and a return type of trigger. Note that
+ CREATE FUNCTION command, declaring it as a function with
+ no arguments and a return type of trigger. Note that
the function must be declared with no arguments even if it expects
to receive arguments specified in CREATE TRIGGER ---
trigger arguments are passed via TG_ARGV, as described
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 BEFORE or AFTER statement-level
- trigger or an 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.
Row-level triggers fired 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
- INSERT/UPDATE/DELETE does not occur for this row). If a nonnull
+ INSERT/UPDATE/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 NEW alters the row that will be inserted or updated. It is
- possible to replace single values directly in NEW and return NEW,
+ of NEW alters the row that will be inserted or updated
+ (but has no direct effect in the DELETE case).
+ To alter the row to be stored, it is possible to replace single values
+ directly in NEW and return the modified NEW,
or to build a complete new record/row to return.
+ The return value of a BEFORE or AFTER
+ statement-level trigger or an 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.
+
+
shows an example of a
trigger procedure in
PL/pgSQL.
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.
This section explains differences between
language and Oracle's
PL/SQL language,
- to help developers that port applications from Oracle to
+ to help developers who port applications from Oracle to
- EXECUTE works similar to the
+ EXECUTE works similarly to the
PL/SQL version, but you have to remember to use
quote_literal(text) and
quote_string(text) as described in
projects / postgresql.git / commitdiff