All variables, rows and records 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.fieldname%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 non-NULL 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 when the function was
precompiled.
Examples:
quantity INTEGER DEFAULT 32;
url varchar := ''http://mysite.com'';
user_id CONSTANT INTEGER := 10;
name ALIAS FOR $n;
Parameters passed to functions are named with the identifiers
$1, $2,
etc. Optionally, aliases can be declared for $n
parameter names for increased readability. Either the alias or the
numeric identifier can then be used to refer to the parameter value.
Some examples:
CREATE FUNCTION sales_tax(REAL) RETURNS REAL AS '
DECLARE
subtotal ALIAS FOR $1;
BEGIN
return subtotal * 0.06;
END;
' LANGUAGE 'plpgsql';
CREATE FUNCTION instr(VARCHAR,INTEGER) RETURNS INTEGER AS '
DECLARE
v_string ALIAS FOR $1;
index ALIAS FOR $2;
BEGIN
-- Some computations here
END;
' LANGUAGE 'plpgsql';
CREATE FUNCTION use_many_fields(tablename) RETURNS TEXT AS '
DECLARE
in_t ALIAS FOR $1;
BEGIN
RETURN in_t.f1 || in_t.f3 || in_t.f5 || in_t.f7;
END;
' LANGUAGE 'plpgsql';
name tablename%ROWTYPE;
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.
Presently, a row variable can only be declared using the
%ROWTYPE notation; although one might expect a
bare table name to work as a type declaration, it won't be accepted
within PL/pgSQL functions.
Parameters to a function can be
composite types (complete table rows). In that case, the
corresponding identifier $n will be a row variable, and fields can
be selected from it, for example $1.user_id.
Only the user-defined attributes of a table row are accessible in a
row-type variable, not OID or other system attributes (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).
CREATE FUNCTION use_two_tables(tablename) RETURNS TEXT AS '
DECLARE
in_t ALIAS FOR $1;
use_t table2name%ROWTYPE;
BEGIN
SELECT * INTO use_t FROM table2name WHERE ... ;
RETURN in_t.f1 || use_t.f3 || in_t.f5 || use_t.f7;
END;
' LANGUAGE 'plpgsql';
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.
Using the %TYPE and %ROWTYPE
attributes, you can declare variables with the same
data type or structure as another database item (e.g: a
table field).
- variable%TYPE
%TYPE provides the data type of a
variable or database 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 important, if the data type of the
referenced item changes in the future (e.g: you
change your table definition of user_id from INTEGER to
REAL), you may not need to change your function
definition.
- table%ROWTYPE
%ROWTYPE provides the composite data type corresponding
to a whole row of the specified table.
table must be an existing
table or view name of the database.
DECLARE
users_rec users%ROWTYPE;
user_id users.user_id%TYPE;
BEGIN
user_id := users_rec.user_id;
...
CREATE FUNCTION does_view_exist(INTEGER) RETURNS bool AS '
DECLARE
key ALIAS FOR $1;
table_data cs_materialized_views%ROWTYPE;
BEGIN
SELECT INTO table_data * FROM cs_materialized_views
WHERE sort_key=key;
IF NOT FOUND THEN
RETURN false;
END IF;
RETURN true;
END;
' LANGUAGE 'plpgsql';
RENAME oldname TO newname;
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;
Note: 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.
