PostgreSQL 7.4beta4 Documentation
Prev | Fast Backward | Chapter 39. PL/pgSQL - SQL Procedural Language | Fast Forward | Next

# 39.6. Basic Statements

In this section and the following ones, we describe all the statement types that are explicitly understood by PL/pgSQL. Anything not recognized as one of these statement types is presumed to be an SQL command and is sent to the main database engine to execute (after substitution of any PL/pgSQL variables used in the statement). Thus, for example, the SQL commands `INSERT`, `UPDATE`, and `DELETE` may be considered to be statements of PL/pgSQL, but they are not specifically listed here.

## 39.6.1. Assignment

An assignment of a value to a variable or row/record field is written as:

    identifier := expression;

As explained above, the expression in such a statement is evaluated by means of an SQL `SELECT` command sent to the main database engine. The expression must yield a single value.

If the expression's result data type doesn't match the variable's data type, or the variable has a specific size/precision (like `char(20)`), the result value will be implicitly converted by the PL/pgSQL interpreter using the result type's output-function and the variable type's input-function. Note that this could potentially result in run-time errors generated by the input function, if the string form of the result value is not acceptable to the input function.

Examples:

    user_id := 20;
    tax := subtotal * 0.06;

## 39.6.2. `SELECT INTO`

The result of a `SELECT` command yielding multiple columns (but only one row) can be assigned to a record variable, row-type variable, or list of scalar variables. This is done by:

    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. The select_expressions and the remainder of the command are the same as in regular SQL.

Note that this is quite different from PostgreSQL's normal interpretation of `SELECT INTO`, where the INTO target is a newly created table. If you want to create a table from a `SELECT` result inside a PL/pgSQL function, use the syntax `CREATE TABLE ... AS SELECT`.

If a row or a variable list is used as target, the selected values must exactly match the structure of the target, or a run-time error occurs. When a record variable is the target, it automatically configures itself to the row type of the query result columns.

Except for the INTO clause, the `SELECT` statement is the same as a normal SQL `SELECT` command and can use its full power.

If the query returns zero rows, null values are assigned to the target(s). If the query returns multiple rows, the first row is assigned to the target(s) and the rest are discarded. (Note that "the first row" is not well-defined unless you've used ORDER BY.)

At present, the INTO clause can appear almost anywhere in the `SELECT` statement, but it is recommended to place it immediately after the SELECT key word as depicted above. Future versions of PL/pgSQL may be less forgiving about placement of the INTO clause.

You can use FOUND immediately after a `SELECT INTO` statement to determine whether the assignment was successful (that is, at least one row was was returned by the query). For example:

    SELECT INTO myrec * FROM emp WHERE empname = myname;
    IF NOT FOUND THEN
        RAISE EXCEPTION ''employee % not found'', myname;
    END IF;

To test for whether a record/row result is null, you can use the IS NULL conditional. There is, however, no way to tell whether any additional rows might have been discarded. Here is an example that handles the case where no rows have been returned:

    DECLARE
        users_rec RECORD;
        full_name varchar;
    BEGIN
        SELECT INTO users_rec * FROM users WHERE user_id=3;

        IF users_rec.homepage IS NULL THEN
            -- user entered no homepage, return "http://"
            RETURN ''http://'';
        END IF;
    END;

## 39.6.3. Executing an Expression or Query With No Result

Sometimes one wishes to evaluate an expression or query but discard the result (typically because one is calling a function that has useful side-effects but no useful result value). To do this in PL/pgSQL, use the `PERFORM` statement:

    PERFORM query;

This executes query, which must be a `SELECT` statement, and discards the result. PL/pgSQL variables are substituted in the query as usual. Also, the special variable FOUND is set to true if the query produced at least one row or false if it produced no rows.

> Note: One might expect that `SELECT` with no INTO clause would accomplish this result, but at present the only accepted way to do it is `PERFORM`.

An example:

    PERFORM create_mv(''cs_session_page_requests_mv'', my_query);

## 39.6.4. Executing Dynamic Commands

Oftentimes you will want to generate dynamic commands inside your PL/pgSQL functions, that is, commands that will involve different tables or different data types each time they are executed. PL/pgSQL's normal attempts to cache plans for commands will not work in such scenarios. To handle this sort of problem, the `EXECUTE` statement is provided:

    EXECUTE command-string;

where command-string is an expression yielding a string (of type `text`) containing the command to be executed. This string is fed literally to the SQL engine.

Note in particular that no substitution of PL/pgSQL variables is done on the command string. The values of variables must be inserted in the command string as it is constructed.

When working with dynamic commands you will have to face escaping of single quotes in PL/pgSQL. Please refer to the overview in Section 39.2.1, which can save you some effort.

Unlike all other commands in PL/pgSQL, a command run by an `EXECUTE` statement is not prepared and saved just once during the life of the session. Instead, the command is prepared each time the statement is run. The command string can be dynamically created within the function to perform actions on variable tables and columns.

The results from `SELECT` commands are discarded by `EXECUTE`, and `SELECT INTO` is not currently supported within `EXECUTE`. 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 Section 39.7.4, and the other is to use a cursor with `OPEN-FOR-EXECUTE`, as described in Section 39.8.2.

An example:

    EXECUTE ''UPDATE tbl SET ''
            || quote_ident(colname)
            || '' = ''
            || quote_literal(newvalue)
            || '' WHERE ...'';

This example shows use of the functions `quote_ident(`text`)` and `quote_literal(`text`)`. 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 appropriate steps to return the input text enclosed in double or single quotes respectively, with any embedded special characters properly escaped.

Here is a much larger example of a dynamic command and `EXECUTE`:

    CREATE FUNCTION cs_update_referrer_type_proc() RETURNS integer AS '
    DECLARE
        referrer_keys RECORD;  -- declare a generic record to be used in a FOR
        a_output varchar(4000);
    BEGIN
        a_output := ''CREATE FUNCTION cs_find_referrer_type(varchar, varchar, varchar)
                      RETURNS varchar AS ''''
                         DECLARE
                             v_host ALIAS FOR $1;
                             v_domain ALIAS FOR $2;
                             v_url ALIAS FOR $3;
                         BEGIN '';

        -- Notice how we scan through the results of a query in a FOR loop
        -- using the FOR <record> construct.

        FOR referrer_keys IN SELECT * FROM cs_referrer_keys ORDER BY try_order LOOP
            a_output := a_output || '' IF v_'' || referrer_keys.kind || '' LIKE ''''''''''
                     || referrer_keys.key_string || '''''''''' THEN RETURN ''''''
                     || referrer_keys.referrer_type || ''''''; END IF;'';
        END LOOP;

        a_output := a_output || '' RETURN NULL; END; '''' LANGUAGE plpgsql;'';

        EXECUTE a_output;
    END;
    ' LANGUAGE plpgsql;

## 39.6.5. Obtaining the Result Status

There are several ways to determine the effect of a command. The first method is to use the `GET DIAGNOSTICS` command, which has the form:

    GET DIAGNOSTICS variable = item [ , ... ] ;

This command allows retrieval of system status indicators. Each item is a key word identifying a state value to be assigned to the specified variable (which should be of the right data type to receive it). The currently available status items are ROW_COUNT, the number of rows processed by the last SQL command sent down to the SQL engine, and RESULT_OID, the OID of the last row inserted by the most recent SQL command. Note that RESULT_OID is only useful after an `INSERT` command.

An example:

    GET DIAGNOSTICS integer_var = ROW_COUNT;

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 call. It is set by each of the following types of statements:

- A `SELECT INTO` statement sets FOUND true if it returns a row, false if no row is returned.

- A `PERFORM` statement sets FOUND true if it produces (and discards) a row, false if no row is produced.

- `UPDATE`, `INSERT`, and `DELETE` statements set FOUND true if at least one row is affected, false if no row is affected.

- A `FETCH` statement sets FOUND true if it returns a row, false if no row is returned.

- A `FOR` statement sets FOUND true if it iterates one or more times, else false. This applies to all three variants of the `FOR` statement (integer `FOR` loops, record-set `FOR` loops, and dynamic record-set `FOR` loops). FOUND is only set when the `FOR` loop exits: inside the execution of the loop, FOUND is not modified by the `FOR` statement, although it may be changed by the execution of other statements within the loop body.

FOUND is a local variable; any changes to it affect only the current PL/pgSQL function.

Prev | Home | Next
Expressions | Up | Control Structures