RETURN expresión;

RETURN con una expresión termina la función y devuelve el valor de expresión al llamador. Esta forma se utiliza para funciones de PL/pgSQL que no devuelven un conjunto (set).

En una función que devuelve un tipo escalar, el resultado de la expresión se convertirá automáticamente al tipo de retorno de la función, como se describe para las asignaciones. Pero para devolver un valor compuesto (fila), debes escribir una expresión que entregue exactamente el conjunto de columnas solicitado. Esto puede requerir el uso de una conversión explícita.

Si declaraste la función con parámetros de salida, escribe simplemente RETURN sin expresión. Se devolverán los valores actuales de las variables de los parámetros de salida.

Si declaraste la función para que devuelva void, se puede usar una instrucción RETURN para salir de la función antes de tiempo; pero no escribas una expresión después de RETURN.

El valor de retorno de una función no puede dejarse indefinido. Si el control llega al final del bloque de nivel superior de la función sin encontrar una instrucción RETURN, se producirá un error en tiempo de ejecución. Sin embargo, esta restricción no se aplica a las funciones con parámetros de salida ni a las funciones que devuelven void. En esos casos, se ejecuta automáticamente una instrucción RETURN si finaliza el bloque de nivel superior.

Algunos ejemplos:

-- funciones que devuelven un tipo escalar
RETURN 1 + 2;
RETURN scalar_var;

-- funciones que devuelven un tipo compuesto
RETURN composite_type_var;
RETURN (1, 2, 'three'::text);  -- se deben convertir las columnas a los tipos correctos

RETURN NEXT expresión;
RETURN QUERY consulta;
RETURN QUERY EXECUTE cadena_comando [ USING expresión [, ... ] ];

Cuando una función de PL/pgSQL se declara para devolver SETOF sometipo, el procedimiento a seguir es ligeramente diferente. En ese caso, los elementos individuales a devolver se especifican mediante una secuencia de comandos RETURN NEXT o RETURN QUERY, y luego se utiliza un comando RETURN final sin argumento para indicar que la función ha terminado de ejecutarse. RETURN NEXT se puede utilizar tanto con tipos de datos escalares como compuestos; con un tipo de resultado compuesto, se devolverá una “tabla” completa de resultados. RETURN QUERY añade los resultados de ejecutar una consulta al conjunto de resultados de la función. RETURN NEXT y RETURN QUERY se pueden mezclar libremente en una sola función que devuelva un conjunto, en cuyo caso sus resultados se concatenarán.

RETURN NEXT y RETURN QUERY en realidad no retornan de la función — simplemente añaden cero o más filas al conjunto de resultados de la función. La ejecución continúa con la siguiente instrucción en la función de PL/pgSQL. A medida que se ejecutan comandos sucesivos RETURN NEXT o RETURN QUERY, el conjunto de resultados se va construyendo. Un RETURN final, que no debe tener ningún argumento, hace que el control salga de la función (o puedes simplemente dejar que el control llegue al final de la función).

RETURN QUERY tiene una variante RETURN QUERY EXECUTE, que especifica la consulta a ejecutar dinámicamente. Las expresiones de parámetros se pueden insertar en la cadena de consulta calculada a través de USING, exactamente de la misma manera que en el comando EXECUTE.

Si declaraste la función con parámetros de salida, escribe simplemente RETURN NEXT sin expresión. En cada ejecución, los valores actuales de las variables de los parámetros de salida se guardarán para su eventual retorno como una fila del resultado. Ten en cuenta que debes declarar que la función devuelve SETOF record cuando hay múltiples parámetros de salida, o SETOF sometipo cuando hay solo un parámetro de salida de tipo sometipo, con el fin de crear una función que devuelva un conjunto con parámetros de salida.

Aquí tienes un ejemplo de una función que utiliza RETURN NEXT:

CREATE TABLE foo (fooid INT, foosubid INT, fooname TEXT);
INSERT INTO foo VALUES (1, 2, 'three');
INSERT INTO foo VALUES (4, 5, 'six');

CREATE OR REPLACE FUNCTION get_all_foo() RETURNS SETOF foo AS
$BODY$
DECLARE
    r foo%rowtype;
BEGIN
    FOR r IN
        SELECT * FROM foo WHERE fooid > 0
    LOOP
        -- se puede realizar algún procesamiento aquí
        RETURN NEXT r; -- devolver la fila actual de SELECT
    END LOOP;
    RETURN;
END;
$BODY$
LANGUAGE plpgsql;

SELECT * FROM get_all_foo();

Aquí tienes un ejemplo de una función que utiliza RETURN QUERY:

CREATE FUNCTION get_available_flightid(date) RETURNS SETOF integer AS
$BODY$
BEGIN
    RETURN QUERY SELECT flightid
                   FROM flight
                  WHERE flightdate >= $1
                    AND flightdate < ($1 + 1);

    -- Como la ejecución no ha terminado, podemos comprobar si se devolvieron filas
    -- y lanzar una excepción si no es así.
    IF NOT FOUND THEN
        RAISE EXCEPTION 'No hay vuelos en %.', $1;
    END IF;

    RETURN;
 END;
$BODY$
LANGUAGE plpgsql;

-- Devuelve vuelos disponibles o lanza una excepción si no hay vuelos disponibles.
SELECT * FROM get_available_flightid(CURRENT_DATE);

IF boolean-expression THEN
    statements
END IF;

IF-THEN statements are the simplest form of IF. The statements between THEN and END IF will be executed if the condition is true. Otherwise, they are skipped.

Example:

IF v_user_id <> 0 THEN
    UPDATE users SET email = v_email WHERE user_id = v_user_id;
END IF;

IF boolean-expression THEN
    statements
ELSE
    statements
END IF;

Las instrucciones IF-THEN-ELSE añaden funcionalidad a IF-THEN al permitirte especificar un conjunto alternativo de instrucciones que se deben ejecutar si la condición no es verdadera. (Ten en cuenta que esto incluye el caso en el que la condición se evalúa como NULL).

Ejemplos:

IF parentid IS NULL OR parentid = ''
THEN
    RETURN fullname;
ELSE
    RETURN hp_true_filename(parentid) || '/' || fullname;
END IF;

IF v_count > 0 THEN
    INSERT INTO users_count (count) VALUES (v_count);
    RETURN 't';
ELSE
    RETURN 'f';
END IF;

IF boolean-expression THEN
    statements
[ ELSIF boolean-expression THEN
    statements
[ ELSIF boolean-expression THEN
    statements
    ...
]
]
[ ELSE
    statements ]
END IF;

A veces hay más de dos alternativas. IF-THEN-ELSIF proporciona un método conveniente para comprobar varias alternativas una tras otra. Las condiciones IF se prueban sucesivamente hasta encontrar la primera que sea verdadera. Luego se ejecutan las instrucciones asociadas, tras lo cual el control pasa a la siguiente instrucción después de END IF. (Las condiciones IF subsiguientes no se evalúan). Si ninguna de las condiciones IF es verdadera, se ejecuta el bloque ELSE (si existe).

Aquí tienes un ejemplo:

IF number = 0 THEN
    result := 'zero';
ELSIF number > 0 THEN
    result := 'positive';
ELSIF number < 0 THEN
    result := 'negative';
ELSE
    -- hmm, la única otra posibilidad es que number sea null
    result := 'NULL';
END IF;

La palabra clave ELSIF también se puede escribir como ELSEIF.

Una forma alternativa de lograr la misma tarea es anidar instrucciones IF-THEN-ELSE, como en el siguiente ejemplo:

IF demo_row.sex = 'm' THEN
    pretty_sex := 'man';
ELSE
    IF demo_row.sex = 'f' THEN
        pretty_sex := 'woman';
    END IF;
END IF;

Sin embargo, este método requiere escribir un END IF correspondiente para cada IF, por lo que es mucho más engorroso que usar ELSIF cuando hay muchas alternativas.

CASE search-expression
    WHEN expression [, expression [ ... ]] THEN
      statements
  [ WHEN expression [, expression [ ... ]] THEN
      statements
    ... ]
  [ ELSE
      statements ]
END CASE;

La forma simple de CASE proporciona una ejecución condicional basada en la igualdad de los operandos. La search-expression se evalúa (una vez) y se compara sucesivamente con cada expression en las cláusulas WHEN. Si se encuentra una coincidencia, se ejecutan las correspondientes statements, y luego el control pasa a la siguiente instrucción después de END CASE. (Las expresiones WHEN subsiguientes no se evalúan). Si no se encuentra ninguna coincidencia, se ejecutan las statements de ELSE; pero si no hay ELSE, se lanza una excepción CASE_NOT_FOUND.

Aquí tienes un ejemplo simple:

CASE x
    WHEN 1, 2 THEN
        msg := 'one or two';
    ELSE
        msg := 'other value than one or two';
END CASE;

CASE
    WHEN boolean-expression THEN
      statements
  [ WHEN boolean-expression THEN
      statements
    ... ]
  [ ELSE
      statements ]
END CASE;

La forma de búsqueda de CASE proporciona una ejecución condicional basada en la veracidad de expresiones booleanas. La boolean-expression de cada cláusula WHEN se evalúa a su vez, hasta encontrar una que resulte verdadera (true). Luego se ejecutan las correspondientes statements, y luego el control pasa a la siguiente instrucción después de END CASE. pero si no hay ELSE, se lanza una excepción CASE_NOT_FOUND.

[ <<label>> ]
LOOP
    statements
END LOOP [ label ];

LOOP define un bucle incondicional que se repite indefinidamente hasta que termina mediante una instrucción EXIT o RETURN. La etiqueta opcional label puede ser utilizada por las instrucciones EXIT y CONTINUE dentro de bucles anidados para especificar a qué bucle se refieren esas instrucciones.

EXIT [ label ] [ WHEN boolean-expression ];

Si no se proporciona ninguna label, se termina el bucle más interno y se ejecuta a continuación la instrucción que sigue a END LOOP. Si se proporciona una label, esta debe ser la etiqueta del bucle o bloque actual o de algún nivel externo de bucles o bloques anidados. Luego, se termina el bucle o bloque nombrado y el control continúa con la instrucción que sigue al END correspondiente del bucle/bloque.

Si se especifica WHEN, la salida del bucle ocurre solo si boolean-expression es verdadera. De lo contrario, el control pasa a la instrucción que sigue a EXIT.

EXIT se puede usar con todo tipo de bucles; no está limitado al uso con bucles incondicionales.

Cuando se usa con un bloque BEGIN, EXIT pasa el control a la siguiente instrucción después del final del bloque. Ten en cuenta que se debe utilizar una etiqueta para este propósito; un EXIT sin etiqueta nunca se considerará que coincide con un bloque BEGIN. (Este es un cambio con respecto a las versiones anteriores a la 8.4 de PostgreSQL, que permitían que un EXIT sin etiqueta coincidiera con un bloque BEGIN).

Ejemplos:

LOOP
    -- algunos cálculos
    IF count > 0 THEN
        EXIT;  -- salir del bucle
    END IF;
END LOOP;

LOOP
    -- algunos cálculos
    EXIT WHEN count > 0;  -- mismo resultado que el ejemplo anterior
END LOOP;

<<ablock>>
BEGIN
    -- algunos cálculos
    IF stocks > 100000 THEN
        EXIT ablock;  -- provoca la salida del bloque BEGIN
    END IF;
    -- los cálculos aquí se omitirán cuando stocks > 100000
END;

CONTINUE [ label ] [ WHEN boolean-expression ];

Si no se proporciona ninguna label, se comienza la siguiente iteración del bucle más interno. Es decir, se omiten todas las instrucciones restantes en el cuerpo del bucle y el control vuelve a la expresión de control del bucle (si existe) para determinar si se necesita otra iteración del bucle. Si la label está presente, especifica la etiqueta del bucle cuya ejecución continuará.

Si se especifica WHEN, la siguiente iteración del bucle comienza solo si boolean-expression es verdadera. De lo contrario, el control pasa a la instrucción después de CONTINUE.

CONTINUE se puede usar con todo tipo de bucles; no está limitado al uso con bucles incondicionales.

Ejemplos:

LOOP
    -- algunos cálculos
    EXIT WHEN count > 100;
    CONTINUE WHEN count < 50;
    -- algunos cálculos para count EN [50 .. 100]
END LOOP;

[ <<label>> ]
WHILE boolean-expression LOOP
    statements
END LOOP [ label ];

La instrucción WHILE repite una secuencia de instrucciones mientras la boolean-expression se evalúe como verdadera. La expresión se comprueba justo antes de cada entrada al cuerpo del bucle.

Por ejemplo:

WHILE amount_owed > 0 AND gift_certificate_balance > 0 LOOP
    -- algunos cálculos aquí
END LOOP;

WHILE NOT done LOOP
    -- algunos cálculos aquí
END LOOP;

[ <<label>> ]
FOR name IN [ REVERSE ] expression .. expression [ BY expression ] LOOP
    statements
END LOOP [ label ];

Esta forma de FOR crea un bucle que itera sobre un rango de valores enteros. La variable name se define automáticamente como tipo integer y existe solo dentro del bucle (cualquier definición existente del nombre de la variable se ignora dentro del bucle). Las dos expresiones que dan los límites inferior y superior del rango se evalúan una vez al entrar al bucle. Si no se especifica la cláusula BY, el paso de iteración es 1; de lo contrario, es el valor especificado en la cláusula BY, que nuevamente se evalúa una vez al entrar al bucle. Si se especifica REVERSE, el valor del paso se resta, en lugar de sumarse, después de cada iteración.

Algunos ejemplos de bucles FOR de enteros:

FOR i IN 1..10 LOOP
    -- i tomará los valores 1,2,3,4,5,6,7,8,9,10 dentro del bucle
END LOOP;

FOR i IN REVERSE 10..1 LOOP
    -- i tomará los valores 10,9,8,7,6,5,4,3,2,1 dentro del bucle
END LOOP;

FOR i IN REVERSE 10..1 BY 2 LOOP
    -- i tomará los valores 10,8,6,4,2 dentro del bucle
END LOOP;

Si el límite inferior es mayor que el límite superior (o menor, en el caso de REVERSE), el cuerpo del bucle no se ejecuta en absoluto. No se genera ningún error.

Si se adjunta una label al bucle FOR, se puede hacer referencia a la variable del bucle entero con un nombre calificado, utilizando esa label.

Los manejadores de excepciones a menudo necesitan identificar el error específico que ocurrió. Hay dos formas de obtener información sobre la excepción actual en PL/pgSQL: variables especiales y el comando

Dentro de un manejador de excepciones, la variable especial SQLSTATE contiene el código de error que corresponde a la excepción lanzada (consulta la Table A.1 para ver una lista de los posibles códigos de error). La variable especial SQLERRM contiene el mensaje de error asociado a la excepción. Estas variables no están definidas fuera de los manejadores de excepciones.

Dentro de un manejador de excepciones, también puedes obtener información sobre la excepción actual mediante el comando GET STACKED DIAGNOSTICS, que tiene la forma:

GET STACKED DIAGNOSTICS variable { = | := } item [ , ... ];

Cada item es una palabra clave que identifica un valor de estado que será asignado a la variable especificada (que debe ser del tipo de datos adecuado para recibirlo). Los elementos de estado actualmente disponibles se muestran en Table 41.2.

Si la excepción no estableció un valor para un elemento, se devolverá una cadena vacía.

Aquí tienes un ejemplo:

DECLARE
  text_var1 text;
  text_var2 text;
  text_var3 text;
BEGIN
  -- algún procesamiento que podría causar una excepción
  ...
EXCEPTION WHEN OTHERS THEN
  GET STACKED DIAGNOSTICS text_var1 = MESSAGE_TEXT,
                          text_var2 = PG_EXCEPTION_DETAIL,
                          text_var3 = PG_EXCEPTION_HINT;
END;