35.8. Cursores

35.8.2.1. OPEN FOR SELECT

OPEN cursor_desligado FOR SELECT ...;

A variável cursor é aberta e recebe a consulta especificada para executar. O cursor não pode estar aberto, e deve ter sido declarado como um cursor desligado, ou seja, simplesmente como uma variável do tipo refcursor. O comando SELECT é tratado da mesma maneira que nas outras instruções SELECT da linguagem PL/pgSQL: Os nomes das variáveis da linguagem PL/pgSQL são substituídos, e o plano de execução é colocado no cache para uma possível reutilização.

Exemplo:

OPEN curs1 FOR SELECT * FROM foo WHERE chave = minha_chave;

35.8.2.2. OPEN FOR EXECUTE

OPEN cursor_desligado FOR EXECUTE cadeia_de_caracteres_da_consulta;

A variável cursor é aberta e recebe a consulta especificada para executar. O cursor não pode estar aberto, e deve ter sido declarado como um cursor desligado, ou seja, simplesmente como uma variável do tipo refcursor. A consulta é especificada como uma expressão cadeia de caracteres da mesma maneira que no comando EXECUTE. Como habitual, esta forma provê flexibilidade e, portanto, a consulta pode variar entre execuções.

Exemplo:

OPEN curs1 FOR EXECUTE 'SELECT * FROM ' || quote_ident($1);

35.8.2.3. Abertura de cursor ligado

OPEN cursor_ligado [ ( valores_dos_argumentos ) ];

Esta forma do OPEN é utilizada para abrir uma variável cursor cuja consulta foi ligada à mesma ao ser declarada. O cursor não pode estar aberto. Deve estar presente uma lista de expressões com os valores reais dos argumentos se, e somente se, o cursor for declarado como recebendo argumentos. Estes valores são substituídos na consulta. O plano de comando do cursor ligado é sempre considerado como passível de ser colocado no cache; neste caso não há forma EXECUTE equivalente.

Exemplos:

OPEN curs2;
OPEN curs3(42);

35.8.3.1. FETCH

FETCH cursor INTO destino;

A instrução FETCH coloca a próxima linha do cursor no destino, que pode ser uma variável linha, uma variável registro, ou uma lista separada por vírgulas de variáveis simples, da mesma maneira que no SELECT INTO. Como no SELECT INTO, pode ser verificada a variável especial FOUND para ver se foi obtida uma linha, ou não.

Exemplos:

FETCH curs1 INTO variável_linha;
FETCH curs2 INTO foo, bar, baz;

35.8.3.2. CLOSE

CLOSE cursor;

A instrução CLOSE fecha o portal subjacente ao cursor aberto. Pode ser utilizada para liberar recursos antes do fim da transação, ou para liberar a variável cursor para que esta possa ser aberta novamente.

Exemplo:

CLOSE curs1;

35.8.3.3. Retornar cursor

As funções PL/pgSQL podem retornar cursores para quem fez a chamada. É útil para retornar várias linhas ou colunas, especialmente em conjuntos de resultados muito grandes. Para ser feito, a função abre o cursor e retorna o nome do cursor para quem chamou (ou simplesmente abre o cursor utilizando o nome do portal especificado por, ou de outra forma conhecido por, quem chamou). Quem chamou poderá então ler as linhas usando o cursor. O cursor pode ser fechado por quem chamou, ou será fechado automaticamente ao término da transação.

O nome do portal utilizado para o cursor pode ser especificado pelo programador ou gerado automaticamente. Para especificar o nome do portal deve-se, simplesmente, atribuir uma cadeia de caracteres à variável refcursor antes de abri-la. O valor cadeia de caracteres da variável refcursor será utilizado pelo OPEN como o nome do portal subjacente. Entretanto, quando a variável refcursor é nula, o OPEN gera automaticamente um nome que não conflita com nenhum portal existente, e atribui este nome à variável refcursor.

O exemplo a seguir mostra uma maneira de fornecer o nome do cursor por quem chama:

CREATE TABLE teste (col text);
INSERT INTO teste VALUES ('123');

CREATE FUNCTION reffunc(refcursor) RETURNS refcursor AS '
BEGIN
    OPEN $1 FOR SELECT col FROM teste;
    RETURN $1;
END;
' LANGUAGE plpgsql;

BEGIN;
SELECT reffunc('funccursor');

  reffunc
------------
 funccursor
(1 linha)

FETCH ALL IN funccursor;

 col
-----
 123
(1 linha)

COMMIT;

O exemplo a seguir usa a geração automática de nome de cursor:

CREATE FUNCTION reffunc2() RETURNS refcursor AS '
DECLARE
    ref refcursor;
BEGIN
    OPEN ref FOR SELECT col FROM teste;
    RETURN ref;
END;
' LANGUAGE plpgsql;

BEGIN;
SELECT reffunc2();

      reffunc2
--------------------
 <unnamed portal 1>
(1 linha)

FETCH ALL IN "<unnamed cursor 1>";

 col
-----
 123
(1 linha)

COMMIT;

Os exemplos a seguir mostram uma maneira de retornar vários cursores de uma única função:

CREATE FUNCTION minha_funcao(refcursor, refcursor) RETURNS SETOF refcursor AS $$
BEGIN
    OPEN $1 FOR SELECT * FROM tabela_1;
    RETURN NEXT $1;
    OPEN $2 FOR SELECT * FROM tabela_2;
    RETURN NEXT $2;
    RETURN;
END;
$$ LANGUAGE plpgsql;

-- é necessário estar em uma transação para poder usar cursor
BEGIN;

SELECT * FROM minha_funcao('a', 'b');

FETCH ALL FROM a;
FETCH ALL FROM b;
COMMIT;