All variables used in a block must be declared in the
declarations section of the block.
(The only exception is that the loop variable of a FOR
loop
iterating over a range of integer values is automatically declared as an
integer variable.)
PL/pgSQL variables can have any SQL data type, such as
integer
, varchar
, and
char
.
Here are some examples of variable declarations:
user_id integer; quantity numeric(5); url varchar; myrow tablename%ROWTYPE; myfield tablename.columnname%TYPE; arow RECORD;
The general syntax of a variable declaration is:
name
[ CONSTANT ]type
[ NOT NULL ] [ { DEFAULT | := }expression
];
The DEFAULT
clause, if given, specifies the initial value assigned
to the variable when the block is entered. If the DEFAULT
clause
is not given then the variable is initialized to the
SQL null value.
The CONSTANT
option prevents the variable from being assigned to,
so that its value remains constant for the duration of the block.
If NOT NULL
is specified, an assignment of a null value results in a run-time
error. All variables declared as NOT NULL
must have a nonnull default value specified.
The default value is evaluated every time the block is entered. So,
for example, assigning now()
to a variable of type
timestamp
causes the variable to have the
time of the current function call, not the time when the function was
precompiled.
Examples:
quantity integer DEFAULT 32; url varchar := 'http://mysite.com'; user_id CONSTANT integer := 10;
Parameters passed to functions are named with the identifiers
$1
, $2
,
etc. Optionally, aliases can be declared for
$
parameter names for increased readability. Either the alias or the
numeric identifier can then be used to refer to the parameter value.
n
There are two ways to create an alias. The preferred way is to give a
name to the parameter in the CREATE FUNCTION
command,
for example:
CREATE FUNCTION sales_tax(subtotal real) RETURNS real AS $$ BEGIN RETURN subtotal * 0.06; END; $$ LANGUAGE plpgsql;
The other way, which was the only way available before PostgreSQL 8.0, is to explicitly declare an alias, using the declaration syntax
name
ALIAS FOR $n
;
The same example in this style looks like
CREATE FUNCTION sales_tax(real) RETURNS real AS $$ DECLARE subtotal ALIAS FOR $1; BEGIN RETURN subtotal * 0.06; END; $$ LANGUAGE plpgsql;
Some more examples:
CREATE FUNCTION instr(varchar, integer) RETURNS integer AS $$ DECLARE v_string ALIAS FOR $1; index ALIAS FOR $2; BEGIN -- some computations using v_string and index here END; $$ LANGUAGE plpgsql; CREATE FUNCTION concat_selected_fields(in_t sometablename) RETURNS text AS $$ BEGIN RETURN in_t.f1 || in_t.f3 || in_t.f5 || in_t.f7; END; $$ LANGUAGE plpgsql;
When a PL/pgSQL function is declared
with output parameters, the output parameters are given
$
names and optional
aliases in just the same way as the normal input parameters. An
output parameter is effectively a variable that starts out NULL;
it should be assigned to during the execution of the function.
The final value of the parameter is what is returned. For instance,
the sales-tax example could also be done this way:
n
CREATE FUNCTION sales_tax(subtotal real, OUT tax real) AS $$ BEGIN tax := subtotal * 0.06; END; $$ LANGUAGE plpgsql;
Notice that we omitted RETURNS real
— we could have
included it, but it would be redundant.
Output parameters are most useful when returning multiple values. A trivial example is:
CREATE FUNCTION sum_n_product(x int, y int, OUT sum int, OUT prod int) AS $$ BEGIN sum := x + y; prod := x * y; END; $$ LANGUAGE plpgsql;
As discussed in Section 33.4.3, “Functions with Output Parameters”, this
effectively creates an anonymous record type for the function's
results. If a RETURNS
clause is given, it must say
RETURNS record
.
When the return type of a PL/pgSQL
function is declared as a polymorphic type (anyelement
or anyarray
), a special parameter $0
is created. Its data type is the actual return type of the function,
as deduced from the actual input types (see Section 33.2.5, “Polymorphic Types”).
This allows the function to access its actual return type
as shown in Section 37.4.2, “Copying Types”.
$0
is initialized to null and can be modified by
the function, so it can be used to hold the return value if desired,
though that is not required. $0
can also be
given an alias. For example, this function works on any data type
that has a +
operator:
CREATE FUNCTION add_three_values(v1 anyelement, v2 anyelement, v3 anyelement) RETURNS anyelement AS $$ DECLARE result ALIAS FOR $0; BEGIN result := v1 + v2 + v3; RETURN result; END; $$ LANGUAGE plpgsql;
The same effect can be had by declaring one or more output parameters as
anyelement
or anyarray
. In this case the
special $0
parameter is not used; the output
parameters themselves serve the same purpose. For example:
CREATE FUNCTION add_three_values(v1 anyelement, v2 anyelement, v3 anyelement, OUT sum anyelement) AS $$ BEGIN sum := v1 + v2 + v3; END; $$ LANGUAGE plpgsql;
variable
%TYPE
%TYPE
provides the data type of a variable or
table column. You can use this to declare variables that will hold
database values. For example, let's say you have a column named
user_id
in your users
table. To declare a variable with the same data type as
users.user_id
you write:
user_id users.user_id%TYPE;
By using %TYPE
you don't need to know the data
type of the structure you are referencing, and most importantly,
if the data type of the referenced item changes in the future (for
instance: you change the type of user_id
from integer
to real
), you may not need
to change your function definition.
%TYPE
is particularly valuable in polymorphic
functions, since the data types needed for internal variables may
change from one call to the next. Appropriate variables can be
created by applying %TYPE
to the function's
arguments or result placeholders.
name
table_name
%ROWTYPE
;name
composite_type_name
;
A variable of a composite type is called a row
variable (or row-type variable). Such a variable
can hold a whole row of a SELECT
or FOR
query result, so long as that query's column set matches the
declared type of the variable.
The individual fields of the row value
are accessed using the usual dot notation, for example
rowvar.field
.
A row variable can be declared to have the same type as the rows of
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 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.)
Parameters to a function can be
composite types (complete table rows). In that case, the
corresponding identifier $
will be a row variable, and fields can
be selected from it, for example n
$1.user_id
.
Only the user-defined columns of a table row are accessible in a
row-type variable, not the OID or other system columns (because the
row could be from a view). The fields of the row type inherit the
table's field size or precision for data types such as
char(
.
n
)
Here is an example of using composite types. table1
and table2
are existing tables having at least the
mentioned fields:
CREATE FUNCTION merge_fields(t_row table1) RETURNS text AS $$ DECLARE t2_row table2%ROWTYPE; BEGIN SELECT * INTO t2_row FROM table2 WHERE ... ; RETURN t_row.f1 || t2_row.f3 || t_row.f5 || t2_row.f7; END; $$ LANGUAGE plpgsql; SELECT merge_fields(t.*) FROM table1 t WHERE ... ;
name
RECORD;
Record variables are similar to row-type variables, but they have no
predefined structure. They take on the actual row structure of the
row they are assigned during a SELECT
or FOR
command. The substructure
of a record variable can change each time it is assigned to.
A consequence of this is that until a record variable is first assigned
to, it has no substructure, and any attempt to access a
field in it will draw a run-time error.
Note that RECORD
is not a true data type, only a placeholder.
One should also realize that when a PL/pgSQL
function is declared to return type record
, this is not quite the
same concept as a record variable, even though such a function may well
use a record variable to hold its result. In both cases the actual row
structure is unknown when the function is written, but for a function
returning record
the actual structure is determined when the
calling query is parsed, whereas a record variable can change its row
structure on-the-fly.
RENAMEoldname
TOnewname
;
Using the RENAME
declaration you can change the
name of a variable, record or row. This is primarily useful if
NEW
or OLD
should be
referenced by another name inside a trigger procedure. See also
ALIAS
.
Examples:
RENAME id TO user_id; RENAME this_var TO that_var;
RENAME
appears to be broken as of
PostgreSQL 7.3. Fixing this is of low priority,
since ALIAS
covers most of the practical uses
of RENAME
.