-
PL/pgSQL - <span class="marked">SQL</span> Procedural Language
+
PL/pgSQL - <span class="marked"><acronym>SQL</acronym></span> Procedural Language
PL/pgSQL is a loadable procedural language for the
For all expressions and
SQL statements used in
the function, the PL/pgSQL bytecode interpreter creates a
- prepared execution plan using the SPI manager's SPI_prepare() and
- SPI_saveplan() functions. This is done the first time the individual
+ prepared execution plan using the
SPI manager's SPI_prepare() and
+ SPI_saveplan() functions. This is done the first time the individual
statement is processed in the PL/pgSQL function. Thus, a function with
conditional code that contains many statements for which execution
plans would be required, will only prepare and save those plans
PL/pgSQL is a block oriented language. A block is defined as
-[<<label>>]
-[DECLARE
- declarations]
+>
+<<label>>
+DECLARE
+ declarations
BEGIN
statements
END;
- >
+>
Comments
- There are two types of comments in PL/pgSQL. A double dash '--'
- starts a comment that extends to the end of the line. A '/*'
- starts a block comment that extends to the next occurrence of '*/'.
+ There are two types of comments in PL/pgSQL. A double dash --
+ starts a comment that extends to the end of the line. A /*
+ starts a block comment that extends to the next occurrence of */.
Block comments cannot be nested, but double dash comments can be
enclosed into a block comment and a double dash can hide
- the block comment delimiters '/*' and '*/'.
+ the block comment delimiters /* and */.
sub-blocks must be declared in the declarations section of a block,
except for the loop variable of a FOR-loop iterating over a range
of integer values. Parameters given to a PL/pgSQL function are
- automatically declared with the usual identifiers $n.
+ automatically declared with the usual identifiers $1, $2, etc.
The declarations have the following syntax:
-name [ CONSTANT ]
-type [ NOT NULL ] [ DEFAULT | :=
- value ];
+name CONSTANT
+type NOT NULL DEFAULT | :=
+ value ;
The default value is evaluated every time the block is entered. So
- assigning 'now' to a variable of type
+ assigning 'now' to a variable of type
timestamp causes the variable to have the
time of the actual function call, not when the function was
precompiled into its bytecode.
The fields of the rowtype inherit the table's field sizes
- or precision for char() etc. data types.
+ or precision for char() etc. data types.
This aliasing is required for composite types given as arguments to
- a function. The dot notation $1.salary as in SQL functions is not
+ a function. The dot notation $1.salary as in
SQL functions is not
allowed in PL/pgSQL.
Using the table.field%TYPE
causes PL/pgSQL to look up the attributes definitions at the
first call to the function during the lifetime of a backend.
- Suppose we have a table with a char(20) attribute and some PL/pgSQL functions
+ Suppose we have a table with a char(20) attribute and some PL/pgSQL functions
that deal with its content in local variables. Now someone
- decides that char(20) isn't enough, dumps the table, drops it,
+ decides that char(20) is not enough, dumps the table, drops it,
recreates it now with the attribute in question defined as
- char(40) and restores the data. Ha - he forgot about the
+ char(40) and restores the data. Hah - he forgot about the
functions. The computations inside them will truncate the values
to 20 characters. But if they are defined using the
table.field%TYPE
declarations, they will automagically handle the size change or
- if the new table schema defines the attribute as text type.
+ if the new table schema defines the attribute as text type.
All expressions used in PL/pgSQL statements are processed using
the backend's executor. Expressions that appear to contain
- constants may in fact require run-time evaluation (e.g. 'now' for the
+ constants may in fact require runtime evaluation (e.g., 'now' for the
timestamp type) so
it is impossible for the PL/pgSQL parser
to identify real constant values other than the NULL keyword. All
expressions are evaluated internally by executing a query
- SELECT expression
- >
- using the SPI manager. In the expression, occurrences of variable
+>
+SELECT expression
+>
+ using the
SPI manager. In the expression, occurrences of variable
identifiers are substituted by parameters and the actual values from
the variables are passed to the executor in the parameter array. All
expressions used in a PL/pgSQL function are only prepared and
effects to the interpretation of constant values. In detail there
is a difference between what the two functions
CREATE FUNCTION logfunc1 (text) RETURNS timestamp AS '
DECLARE
logtxt ALIAS FOR $1;
RETURN ''now'';
END;
' LANGUAGE 'plpgsql';
-
+
and
CREATE FUNCTION logfunc2 (text) RETURNS timestamp AS '
DECLARE
logtxt ALIAS FOR $1;
RETURN curtime;
END;
' LANGUAGE 'plpgsql';
-
-
- do. In the case of logfunc1(), the
Postgres- main parser
- knows when preparing the plan for the INSERT, that the string 'now'
- should be interpreted as timestamp because the target field of logtable
- is of that type. Thus, it will make a constant from it at this time
- and this constant value is then used in all invocations of logfunc1()
- during the lifetime of the backend. Needless to say that this isn't what the
- programmer wanted.
+
+
+ do. In the case of logfunc1(), the
+
Postgres main parser knows when
+ preparing the plan for the INSERT, that the string
+ 'now' should be interpreted as
+ timestamp because the target field of logtable is of
+ that type. Thus, it will make a constant from it at this time and
+ this constant value is then used in all invocations of
+ logfunc1() during the lifetime of the
+ backend. Needless to say that this isn't what the programmer
+ wanted.
- In the case of
logfunc2(), the
Postgres + In the case of
logfunc2(), the
Postgres main parser does not know
- what type 'now' should become and therefore it returns a data type of
- text containing the string 'now'. During the assignment
+ what type 'now' should become and therefore it returns a data type of
+ text containing the string 'now'. During the assignment
to the local variable curtime, the PL/pgSQL interpreter casts this
- string to the timestamp type by calling the text_out() and timestamp_in()
+ string to the timestamp type by calling the text_out() and timestamp_in()
functions for the conversion.
This type checking done by the
Postgres main
parser got implemented after PL/pgSQL was nearly done.
It is a difference between 6.3 and 6.4 and affects all functions
- using the prepared plan feature of the SPI manager.
+ using the prepared plan feature of the
SPI manager.
Using a local
variable in the above manner is currently the only way in PL/pgSQL to get
those values interpreted correctly.
An assignment of a value to a variable or row/record field is
written as
- identifier := expression;
- >
+>
+identifier := expression;
+>
If the expressions result data type doesn't match the variables
data type, or the variable has a size/precision that is known
- (as for char(20)), the result value will be implicitly casted by
+ (as for char(20)), the result value will be implicitly cast by
the PL/pgSQL bytecode interpreter using the result types output- and
the variables type input-functions. Note that this could potentially
result in runtime errors generated by the types input functions.
An assignment of a complete selection into a record or row can
be done by
+>
SELECT INTO target expressions FROM ...;
- >
+>
target can be a record, a row variable or a
comma separated list of variables and record-/row-fields. Note that
this is quite different from Postgres' normal interpretation of
grouping, sorting etc. that can be given for a SELECT statement.
- There is a special variable named FOUND of type bool that can be used
+ There is a special variable named FOUND of type boolean that can be used
immediately after a SELECT INTO to check if an assignment had success.
SELECT INTO myrec * FROM EMP WHERE empname = myname;
IF NOT FOUND THEN
RAISE EXCEPTION ''employee % not found'', myname;
END IF;
-
+
If the selection returns multiple rows, only the first is moved
into the target fields. All others are silently discarded.
is to execute a SELECT query or doing an assignment (resulting
in a PL/pgSQL internal SELECT). But there are cases where someone
is not interested in the function's result.
+>
PERFORM query
- >
- executes a 'SELECT query' over the
- SPI manager and discards the result. Identifiers like local
+>
+ executes a SELECT query over the
+
SPI manager and discards the result. Identifiers like local
variables are still substituted into parameters.
Executing dynamic queries
-
- EXECUTE
-
-
- where query-string is a string
- of type TEXT containing the query to be executed.
+
+EXECUTE query-string
+
+ where query-string is a string of
+ type text containing the query to be
+ executed.
Obtaining other results status
-GET DIAGNOSTICS variable = item [ , ... ]
- >
+>
+GET DIAGNOSTICS variable = item , ...
+>
This command allows retrieval of system status indicators. Each
item is a keyword identifying a state
value to be assigned to the specified variable (which should be of
the right datatype to receive it). The currently available status
- items are <keyword>ROW_COUNT, the number of rows processed by
- the last SQL query sent down to the SQL engine; and
- <keyword>RESULT_OID, the Oid of the last row inserted by the
- most recent SQL query. Note that >RESULT_OID is only
+ items are <varname>ROW_COUNT, the number of rows processed by
+ the last
SQL query sent down to the SQL engine; and
+ <varname>RESULT_OID, the Oid of the last row inserted by the
+ most recent
SQL query. Note that >RESULT_OID is only useful after an INSERT query.
Returning from the function
+>
RETURN expression
- >
+>
The function terminates and the value of expression
will be returned to the upper executor. The return value of a function
cannot be undefined. If control reaches the end of the top-level block
As indicated in the above examples there is a RAISE statement that
can throw messages into the
Postgres elog mechanism.
-RAISE level 'format' [, identifier [...]];
- >
- Inside the format, "%" is used as a placeholder for the
+>
+RAISE level 'format' , identifier ...;
+>
+ Inside the format, % is used as a placeholder for the
subsequent comma-separated identifiers. Possible levels are
DEBUG (silently suppressed in production running databases), NOTICE
(written into the database log and forwarded to the client application)
Conditionals
+>
IF expression THEN
statements
-[ELSE
- statements]
+ELSE
+ statements
END IF;
- >
+>
The expression must return a value that
- is a boolean or can be casted into a boolean.
+ is of type boolean or can be casted to a boolean.
There are multiple types of loops.
-[<<label>>]
+>
+<<label>>
LOOP
statements
END LOOP;
- >
+>
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
nesting should be terminated.
-[<<label>>]
+>
+<<label>>
WHILE expression LOOP
statements
END LOOP;
- >
+>
A conditional loop that is executed as long as the evaluation
of expression is true.
-[<<label>>]
-FOR name IN [ REVERSE ] expression .. expression LOOP
+>
+<<label>>
+FOR name IN REVERSE expression .. expression LOOP
statements
END LOOP;
- >
+>
A loop that iterates over a range of integer values. The variable
name is automatically created as type
integer and exists only inside the loop. The two expressions giving
the lower and upper bound of the range are evaluated only when entering
the loop. The iteration step is always 1.
-[<<label>>]
+>
+<<label>>
FOR record | row IN select_clause LOOP
statements
END LOOP;
- >
+>
The record or row is assigned all the rows resulting from the select
clause and the loop body is executed for each row. If the loop is
terminated with an EXIT statement, the last assigned row is still
accessible after the loop.
-[<<label>>]
+>
+<<label>>
FOR record | row IN EXECUTE text_expression LOOP
statements
END LOOP;
- >
+>
This is like the previous form, except that the source SELECT
statement is specified as a string expression, which is evaluated
and re-planned on each entry to the FOR loop. This allows the
programmer to choose the speed of a pre-planned query or the
flexibility of a dynamic query, just as with a plain EXECUTE
statement.
-EXIT [ label ] [ WHEN expression ];
- >
+>
+EXIT label WHEN expression ;
+>
If no label given,
the innermost loop is terminated and the
statement following END LOOP is executed next.
- NEW
+ NEW
Data type RECORD; variable holding the new database row on INSERT/UPDATE
- OLD
+ OLD
Data type RECORD; variable holding the old database row on UPDATE/DELETE
- TG_NAME
+ TG_NAME
- Data type name; variable that contains the name of the trigger actually
+ Data type name; variable that contains the name of the trigger actually
fired.
- TG_WHEN
+ TG_WHEN
- Data type text; a string of either 'BEFORE' or 'AFTER' depending on the
+ Data type text; a string of either 'BEFORE' or 'AFTER' depending on the
triggers definition.
- TG_LEVEL
+ TG_LEVEL
- Data type text; a string of either 'ROW' or 'STATEMENT' depending on the
+ Data type text; a string of either 'ROW' or 'STATEMENT' depending on the
triggers definition.
- TG_OP
+ TG_OP
- Data type text; a string of 'INSERT', 'UPDATE' or 'DELETE' telling
+ Data type text; a string of 'INSERT', 'UPDATE', or 'DELETE' telling
for which operation the trigger is actually fired.
- TG_RELID
+ TG_RELID
Data type oid; the object ID of the table that caused the
- TG_RELNAME
+ TG_RELNAME
Data type name; the name of the table that caused the trigger
- TG_NARGS
+ TG_NARGS
Data type integer; the number of arguments given to the trigger
- TG_ARGV[]
+ TG_ARGV[]
- Data type array of text; the arguments from the CREATE TRIGGER statement.
+ Data type array of text; the arguments from the CREATE TRIGGER statement.
The index counts from 0 and can be given as an expression. Invalid
indices (< 0 or >= tg_nargs) result in a NULL value.
Examples
- Here are only a few functions to demonstrate how easy PL/pgSQL
- functions can be written. For more complex examples the programmer
+ Here are only a few functions to demonstrate how easy it is to write PL/pgSQL
+ functions. For more complex examples the programmer
might look at the regression test for PL/pgSQL.
- One painful detail of writing functions in PL/pgSQL is the handling
- of single quotes. The function's source text on CREATE FUNCTION must
+ One painful detail in writing functions in PL/pgSQL is the handling
+ of single quotes. The function's source text in the CREATE FUNCTION command must
be a literal string. Single quotes inside of literal strings must be
either doubled or quoted with a backslash. We are still looking for
an elegant alternative. In the meantime, doubling the single quotes
as in the examples below should be used. Any solution for this
in future versions of
Postgres will be
- upward compatible.
+ forward compatible.
- <sect2>
-
<span class="marked">Some</span> Simple PL/pgSQL Functions
+ <example>
+
<span class="marked">A</span> Simple PL/pgSQL Functions
The following two PL/pgSQL functions are identical to their
counterparts from the C language function discussion.
CREATE FUNCTION add_one (integer) RETURNS integer AS '
BEGIN
RETURN $1 + 1;
END;
' LANGUAGE 'plpgsql';
-
+
CREATE FUNCTION concat_text (text, text) RETURNS text AS '
BEGIN
RETURN $1 || $2;
END;
' LANGUAGE 'plpgsql';
-
+
- sect2>
+ example>
- <sect2>
-
<span class="marked">PL/pgSQL Function on</span> Composite Type
+ <example>
+
<span class="marked">A PL/pgSQL Function on a</span> Composite Type
- Again it is the PL/pgSQL equivalent to the example from
- The C functions.
+ Again, this is the PL/pgSQL equivalent to the example from
+ the C functions.
-CREATE FUNCTION c_overpaid (EMP, integer) RETURNS bool AS '
+CREATE FUNCTION c_overpaid (EMP, integer) RETURNS boolean AS '
DECLARE
emprec ALIAS FOR $1;
sallim ALIAS FOR $2;
RETURN emprec.salary > sallim;
END;
' LANGUAGE 'plpgsql';
-
+
- sect2>
+ example>
- <sect2>
-
PL/pgSQL Trigger Procedure
+ <example>
+
<span class="marked">A </span>PL/pgSQL Trigger Procedure
- This trigger ensures, that any time a row is inserted or updated
+ This 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 employees name is given and that the
salary is a positive value.
CREATE TABLE emp (
empname text,
salary integer,
CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp
FOR EACH ROW EXECUTE PROCEDURE emp_stamp();
-
+
- sect2>
+ example>
projects / postgresql.git / commitdiff