RETURN expressão;

RETURN com uma expressão termina a função e retorna o valor da expressão para quem efetuou a chamada. Esta forma é usada em funções PL/pgSQL que não retornam um conjunto.

Em uma função que retorna um tipo de dados escalar, o resultado da expressão será automaticamente convertido no tipo de dados retornado pela função, conforme descrito para atribuições. Mas, para retornar um valor composto (linha), deve ser escrita uma expressão que forneça exatamente o conjunto de colunas especificado, podendo exigir o uso de conversão explícita.

Se a função for declarada com parâmetros de saída, deve ser escrito apenas RETURN sem a expressão. Serão retornados os valores correntes das variáveis dos parâmetros de saída.

Se a função for declarada retornando void pode ser usada uma instrução RETURN para sair da função antecipadamente; mas não deve ser escrita uma expressão após o RETURN.

O valor retornado pela função não pode ser deixado indefinido. Se o controle atingir o final do bloco de nível superior da função sem atingir uma instrução RETURN, ocorrerá um erro de tempo de execução. No entanto, esta restrição não se aplica a funções com parâmetros de saída e funções que retornam void. Nesses casos, uma instrução RETURN é executada automaticamente se o bloco de nível superior terminar.

Alguns exemplos:

-- funções retornando tipo de dados escalar
RETURN 1 + 2;
RETURN variável_escalar;

-- funções retornando tipo de dados composto
RETURN variável_tipo_composto;
RETURN (1, 2, 'três'::text);  -- as colunas devem ser convertidas para os tipos corretos

RETURN NEXT expressão;
RETURN QUERY consulta;
RETURN QUERY EXECUTE cadeia_de_caracteres_de_comando [ USING expressão [, ... ] ];

Quando a função PL/pgSQL é declarada retornando SETOF algumtipo, o procedimento a seguir é um pouco diferente. Neste caso, os itens individuais a serem retornados são especificados por uma sequência de comandos RETURN NEXT ou RETURN QUERY e, em seguida, um comando final RETURN sem nenhum argumento é usado para indicar que a função terminou sua execução. RETURN NEXT pode ser usado com tipos de dados escalares e compostos; com um resultado de tipo composto, será retornada uma “tabela” inteira de resultados. RETURN QUERY anexa os resultados da execução de uma consulta ao conjunto de resultados da função. RETURN NEXT e RETURN QUERY podem ser livremente misturados na mesma função retornando conjunto, caso em que seus resultados são concatenados.

RETURN NEXT e RETURN QUERY, na verdade, não causam o retorno da função — apenas anexam zero ou mais linhas ao conjunto de resultados da função. A execução então prossegue para a próxima instrução da função PL/pgSQL. À medida que sucessivos comandos RETURN NEXT ou RETURN QUERY são executados, o conjunto de resultados é construído. Um RETURN final, que não deve ter nenhum argumento, faz com que o controle saia da função (ou basta apenas deixar o controle chegar ao final da função).

RETURN QUERY possui a variante RETURN QUERY EXECUTE, que especifica a consulta a ser executada dinamicamente. Podem ser inseridas expressões de parâmetro na cadeia de caracteres da consulta computada por meio de USING, da mesma forma que no comando EXECUTE.

Se a função for declarada com parâmetros de saída, deve ser escrito apenas RETURN NEXT, sem expressão. A cada execução, os valores correntes da(s) variável(is) de parâmetro de saída são salvos para retornar no final como uma linha de resultado. Note que se deve declarar a função como retornando SETOF record quando houver vários parâmetros de saída, ou SETOF algumtipo quando houver apenas um parâmetro de saída do tipo algumtipo, para criar uma função que retorna conjunto com parâmetros de saída.

A seguir está um exemplo de função usando RETURN NEXT:

CREATE TABLE foo (fooid INT, foosubid INT, fooname TEXT);
INSERT INTO foo VALUES (1, 2, 'três');
INSERT INTO foo VALUES (4, 5, 'seis');

CREATE OR REPLACE FUNCTION get_all_foo() RETURNS SETOF foo AS
$CORPO$
DECLARE
    r foo%rowtype;
BEGIN
    FOR r IN
        SELECT * FROM foo WHERE fooid > 0
    LOOP
        -- pode ser feito algum processamento aqui
        RETURN NEXT r; -- retornar a linha corrente do SELECT
    END LOOP;
    RETURN;
END;
$CORPO$
LANGUAGE plpgsql;

SELECT * FROM get_all_foo();

 fooid | foosubid | fooname
-------+----------+---------
     1 |        2 | três
     4 |        5 | seis
(2 linhas)

A seguir é mostrado o exemplo de uma função usando RETURN QUERY:

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

    -- Como a execução da função ainda não terminou, pode-se verificar
    -- se foram retornadas linhas e, caso contrário, lançar uma exceção.
    IF NOT FOUND THEN
        RAISE EXCEPTION 'Nenhum voo em %.', $1;
    END IF;

    RETURN;
 END;
$CORPO$
LANGUAGE plpgsql;

-- Retorna os voos disponíveis, ou lança uma
-- exceção caso não haja voos disponíveis.
SELECT * FROM get_available_flightid(CURRENT_DATE);

IF expressão_booleana THEN
    instruções
END IF;

As instruções IF-THEN são a forma mais simples de IF. As instruções entre THEN e END IF são executadas se a condição resultar em verdade. Caso contrário, são ignoradas.

Exemplo:

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

IF expressão_booleana THEN
    instruções
ELSE
    instruções
END IF;

As instruções IF-THEN-ELSE são uma adição ao IF-THEN, permitindo especificar um conjunto alternativo de instruções que devem ser executadas se a condição não resultar em verdade. (Note que isto inclui o caso em que a condição é avaliada como nula.)

Exemplos:

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 expressão_booleana THEN
    instruções
[ ELSIF expressão_booleana THEN
    instruções
[ ELSIF expressão_booleana THEN
    instruções
    ...
]
]
[ ELSE
    instruções ]
END IF;

Às vezes, há mais do que apenas duas alternativas. IF-THEN-ELSIF fornece um método conveniente para verificar várias alternativas sucessivamente. As condições IF são testadas sucessivamente, até que a primeira que resultar em verdade seja encontrada. Em seguida, a(s) instrução(ões) associada(s) são executadas, após o que o controle passa para a próxima instrução após o END IF. (Quaisquer condições IF subsequentes não são testadas.) Se nenhuma das condições IF resultar em verdade, então será executado o bloco ELSE (se houver).

Aqui está um exemplo:

IF number = 0 THEN
    result := 'zero';
ELSIF number > 0 THEN
    result := 'positivo';
ELSIF number < 0 THEN
    result := 'negativo';
ELSE
    -- hmm, a única outra possibilidade é que o número seja nulo
    result := 'NULL';
END IF;

A palavra-chave ELSIF também pode ser escrita como ELSEIF.

Uma maneira alternativa de realizar a mesma tarefa é aninhar instruções IF-THEN-ELSE, como no exemplo a seguir:

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

Entretanto, este método requer que seja escrito um END IF correspondente para cada IF, sendo muito mais complicado do que usar ELSIF quando existem várias alternativas.

CASE expressão_de_procura
    WHEN expressão [, expressão [ ... ]] THEN
      instruções
  [ WHEN expressão [, expressão [ ... ]] THEN
      instruções
    ... ]
  [ ELSE
      instruções ]
END CASE;

A forma simples de CASE permite a execução condicional segundo a igualdade de operandos. A expressão_de_procura é avaliada (uma vez), e comparada sucessivamente a cada expressão nas cláusulas WHEN. Se for encontrada uma correspondência, então as instruções correspondentes serão executadas, e o controle passará para a próxima instrução após o END CASE. (As expressões WHEN subsequentes não são avaliadas.) Se nenhuma correspondência for encontrada, as instruções do ELSE serão executadas; mas se o ELSE não estiver presente, então será lançada a exceção CASE_NOT_FOUND.

Aqui está um exemplo simples:

CASE x
    WHEN 1, 2 THEN
        msg := 'um ou dois';
    ELSE
        msg := 'diferente de um e dois';
END CASE;

CASE
    WHEN expressão_booleana THEN
      instruções
  [ WHEN expressão_booleana THEN
      instruções
    ... ]
  [ ELSE
      instruções ]
END CASE;

A forma com pesquisa de CASE fornece execução condicional baseada na verdade de expressões booleanas. A expressão_booleana de cada cláusula WHEN é avaliada sucessivamente, até que seja encontrada uma que produza true. Em seguida, as instruções correspondentes são executadas, e o controle passa para a próxima instrução após o END CASE. (As expressões WHEN subsequentes não são avaliadas.) Se não for encontrado nenhum resultado verdade, serão executadas as instruções do ELSE; mas se o ELSE não estiver presente, será lançada uma exceção CASE_NOT_FOUND.

A seguir está um exemplo:

DO $$
DECLARE
x int :=21;
msg text;
BEGIN
CASE
    WHEN x BETWEEN 0 AND 10 THEN
        msg := 'o valor está entre zero e dez';
    WHEN x BETWEEN 11 AND 20 THEN
        msg := 'o valor está entre onze e vinte';
END CASE;
END;
$$;
ERROR:  case não foi encontrado
HINT:  comando CASE está faltando a parte ELSE.
CONTEXT:  função PL/pgSQL inline_code_block linha 6 em CASE

Esta forma do CASE é totalmente equivalente a IF-THEN-ELSIF, exceto pela regra onde atingir uma cláusula ELSE omitida resulta em erro, em vez de não fazer nada.

[ <<rótulo>> ]
LOOP
    instruções
END LOOP [ rótulo ];

LOOP define um laço incondicional, repetido indefinidamente até ser terminado por uma instrução EXIT ou RETURN. O rótulo opcional pode ser usado pelas instruções EXIT e CONTINUE dentro de laços aninhados, para especificar a qual laço estas instruções se referem.

EXIT [ rótulo ] [ WHEN expressão_booleana ];

Se nenhum rótulo for fornecido, o laço mais interno é terminado, e a instrução seguinte ao END LOOP é executada em seguida. Se rótulo for especificado, então deve ser o rótulo do laço corrente, ou de algum nível externo de laço ou bloco aninhado. Em seguida, o laço ou bloco especificado é terminado, e o controle continua com a instrução após o END correspondente do laço/bloco.

Se for especificado WHEN, a saída do laço ocorrerá somente se a expressão_booleana resultar em verdade. Caso contrário, o controle passará para a instrução após EXIT.

EXIT pode ser usado com todos os tipos de laço; não está limitado ao uso com laços incondicionais.

Quando usado em um bloco BEGIN, EXIT passa o controle para a próxima instrução após o final do bloco. Note que deve ser usado um rótulo para esta finalidade; um EXIT sem rótulo nunca é considerado correspondendo a um bloco BEGIN. (Esta é uma mudança com relação às versões do PostgreSQL pré-8.4, que permitiam que o EXIT sem rótulo correspondesse a um bloco BEGIN.)

Exemplos:

LOOP
    -- alguns cálculos
    IF count > 0 THEN
        EXIT;  -- sair do laço
    END IF;
END LOOP;

LOOP
    -- alguns cálculos
    EXIT WHEN count > 0;  -- mesmo resultado do exemplo anterior
END LOOP;

<<obloco>>
BEGIN
    -- alguns cálculos
    IF estoque > 100000 THEN
        EXIT obloco;  -- causa a saída do bloco BEGIN
    END IF;
    -- os cálculos aqui são ignorados quando estoque > 100000
END;

CONTINUE [ rótulo ] [ WHEN expressão_booleana ];

Se não for fornecido nenhum rótulo, a próxima iteração do laço mais interno será iniciada. Ou seja, todas as instruções restantes no corpo do laço são ignoradas, e o controle retorna à expressão de controle do laço (se houver) para determinar se é necessária outra iteração do laço. Se rótulo estiver presente, especifica o rótulo do laço cuja execução será continuada.

Se for especificado WHEN, a próxima iteração do laço será iniciada somente se a expressão_booleana resultar em verdade. Caso contrário, o controle passará para a instrução após o CONTINUE.

CONTINUE pode ser usado com todos os tipos de laços; não está limitado ao uso com laços incondicionais.

Exemplos:

LOOP
    -- alguns cálculos
    EXIT WHEN contador > 100;
    CONTINUE WHEN contador < 50;
    -- alguns cálculos para contador IN [50 .. 100]
END LOOP;

[ <<rótulo>> ]
WHILE expressão_booleana LOOP
    instruções
END LOOP [ rótulo ];

A instrução WHILE repete uma sequência de instruções enquanto a expressão_booleana for avaliada como verdade. A expressão é verificada antes de cada entrada no corpo do laço.

Por exemplo:

WHILE montante_devido > 0 AND saldo_vale_presente > 0 LOOP
    -- alguns cálculos
END LOOP;

WHILE NOT terminado LOOP
    -- alguns cálculos
END LOOP;

[ <<rótulo>> ]
FOR nome IN [ REVERSE ] expressão .. expressão [ BY expressão ] LOOP
    instruções
END LOOP [ rótulo ];

Esta forma de FOR cria um laço que itera sobre um intervalo de valores inteiros. A variável nome é definida automaticamente como sendo do tipo integer, existindo apenas dentro do laço (qualquer definição existente do nome da variável é ignorada dentro do laço). As duas expressões que fornecem o limite inferior e superior do intervalo são avaliadas uma vez ao entrar no laço. Se a cláusula BY não for especificada, o passo da iteração é 1, caso contrário é o valor especificado na cláusula BY, que novamente é avaliada uma vez na entrada do laço. Se for especificado REVERSE, o valor do passo será subtraído, em vez de adicionado, após cada iteração.

Alguns exemplos de laços FOR inteiros:

FOR i IN 1..10 LOOP
    -- i assume os valores 1,2,3,4,5,6,7,8,9,10 dentro do laço
END LOOP;

FOR i IN REVERSE 10..1 LOOP
    -- i assume os valores 10,9,8,7,6,5,4,3,2,1 dentro do laço
END LOOP;

FOR i IN REVERSE 10..1 BY 2 LOOP
    -- i assume os valores 10,8,6,4,2 dentro do laço
END LOOP;

Se o limite inferior for maior que o limite superior (ou menor que, no caso REVERSE), o corpo do laço não será executado, e nenhum erro será lançado.

Se for anexado um rótulo ao laço FOR, então a variável inteira do laço poderá ser referenciada com um nome qualificado, usando este rótulo.

Os tratadores de exceção frequentemente precisam identificar o erro específico ocorrido. Existem duas maneiras de obter informações sobre a exceção corrente no PL/pgSQL: variáveis especiais, e o comando GET STACKED DIAGNOSTICS.

Dentro de um tratador de exceção, a variável especial SQLSTATE contém o código de erro que corresponde à exceção que foi levantada (veja a Tabela de códigos de erro do PostgreSQL para obter a lista de possíveis códigos de erro). A variável especial SQLERRM contém a mensagem de erro associada à exceção. Estas variáveis não estão definidas fora dos tratadores de exceção.

Dentro de um tratador de exceção, também é possível obter informações sobre a exceção corrente usando o comando GET STACKED DIAGNOSTICS, que tem a forma:

GET STACKED DIAGNOSTICS variável { = | := } item [ , ... ];

Cada item é uma palavra-chave que identifica um valor de status a ser atribuído à variável especificada (que deve ser do tipo de dados correto para recebê-lo). Os itens de status atualmente disponíveis estão mostrados na Tabela 41.2.

Se a exceção não definir um valor para um item, será retornada uma cadeia de caracteres vazia.

Aqui está um exemplo:

DECLARE
  text_var1 text;
  text_var2 text;
  text_var3 text;
BEGIN
  -- algum processamento que pode causar uma exceção
  ...
EXCEPTION WHEN OTHERS THEN
  GET STACKED DIAGNOSTICS text_var1 = MESSAGE_TEXT,
                          text_var2 = PG_EXCEPTION_DETAIL,
                          text_var3 = PG_EXCEPTION_HINT;
END;