OPEN unbound_cursorvar [ [ NO ] SCROLL ] FOR query;

La variable de cursor se abre y se le proporciona la consulta especificada para ejecutar. El cursor no puede estar ya abierto y debe haber sido declarado como una variable de cursor desvinculada (es decir, como una simple variable refcursor). La consulta debe ser un SELECT o alguna otra cosa que devuelva filas (como EXPLAIN). La consulta se trata de la misma manera que otros comandos SQL en PL/pgSQL: se sustituyen los nombres de las variables de PL/pgSQL y el plan de consulta se almacena en caché para su posible reutilización. Cuando una variable de PL/pgSQL se sustituye en la consulta del cursor, el valor que se sustituye es el que tiene en el momento del OPEN; los cambios posteriores en la variable no afectarán al comportamiento del cursor. Las opciones SCROLL y NO SCROLL tienen los mismos significados que para un cursor vinculado.

Un ejemplo:

OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey;

OPEN unbound_cursorvar [ [ NO ] SCROLL ] FOR EXECUTE query_string
                                     [ USING expression [, ... ] ];

La variable de cursor se abre y se le proporciona la consulta especificada para ejecutar. El cursor no puede estar ya abierto y debe haber sido declarado como una variable de cursor desvinculada (es decir, como una simple variable refcursor). La consulta se especifica como una expresión de cadena, de la misma manera que en el comando EXECUTE. Como es habitual, esto proporciona flexibilidad para que el plan de consulta pueda variar de una ejecución a otra (consulta la Section 41.11.2), y también significa que no se realiza la sustitución de variables en la cadena de comando. Al igual que con EXECUTE, los valores de los parámetros se pueden insertar en el comando dinámico a través de format() y USING. Las opciones SCROLL y NO SCROLL tienen los mismos significados que para un cursor vinculado.

Un ejemplo:

OPEN curs1 FOR EXECUTE format('SELECT * FROM %I WHERE col1 = $1',tabname) USING keyvalue;

En este ejemplo, el nombre de la tabla se inserta en la consulta a través de format(). El valor de comparación para col1 se inserta mediante un parámetro USING, por lo que no necesita comillas.

OPEN bound_cursorvar [ ( [ argument_name { := | => } ] argument_value [, ...] ) ];

Esta forma de OPEN se utiliza para abrir una variable de cursor cuya consulta se vinculó a ella cuando se declaró. El cursor no puede estar ya abierto. Debe aparecer una lista de expresiones de valores de argumentos reales si y solo si el cursor fue declarado para recibir argumentos. Estos valores se sustituirán en la consulta.

El plan de consulta para un cursor vinculado siempre se considera almacenable en caché; no hay equivalente de EXECUTE en este caso. Ten en cuenta que SCROLL y NO SCROLL no se pueden especificar en OPEN, ya que el comportamiento de desplazamiento del cursor ya estaba determinado.

Los valores de los argumentos se pueden pasar utilizando notación posicional o nominal. En la notación posicional, todos los argumentos se especifican en orden. En la notación nominal, el nombre de cada argumento se especifica utilizando := o => para separarlo de la expresión del argumento. De manera similar a la llamada a funciones, descrita en Section 4.3, también se permite mezclar la notación posicional y nominal.

Ejemplos (estos utilizan los ejemplos de declaración de cursor anteriores):

OPEN curs2;
OPEN curs3(42);
OPEN curs3(key := 42);
OPEN curs3(key => 42);

Dado que la sustitución de variables se realiza en la consulta de un cursor vinculado, realmente hay dos formas de pasar valores al cursor: con un argumento explícito en OPEN, o implícitamente haciendo referencia a una variable de PL/pgSQL en la consulta. Sin embargo, solo las variables declaradas antes de declarar el cursor vinculado se sustituirán en él. En cualquier caso, el valor a pasar se determina en el momento del OPEN. Por ejemplo, otra forma de obtener el mismo efecto que el ejemplo de curs3 anterior es:

DECLARE
    key integer;
    curs4 CURSOR FOR SELECT * FROM tenk1 WHERE unique1 = key;
BEGIN
    key := 42;
    OPEN curs4;

FETCH [ direction { FROM | IN } ] cursor INTO target;

FETCH recupera la siguiente fila (en la dirección indicada) desde el cursor hacia un objetivo, que puede ser una variable de fila, una variable de registro o una lista de variables simples separadas por comas, al igual que SELECT INTO. Si no hay una fila adecuada, el objetivo se establece en NULL(s). Al igual que con SELECT INTO, la variable especial FOUND se puede comprobar para ver si se obtuvo una fila o no. Si no se obtiene ninguna fila, el cursor se posiciona después de la última fila o antes de la primera fila, según la dirección del movimiento.

La cláusula direction puede ser cualquiera de las variantes permitidas en el comando SQL FETCH, excepto las que pueden recuperar más de una fila; a saber, puede ser NEXT, PRIOR, FIRST, LAST, ABSOLUTE count, RELATIVE count, FORWARD o BACKWARD. Omitir la direction es lo mismo que especificar NEXT. En las formas que utilizan un count, este puede ser cualquier expresión con valor entero (a diferencia del comando SQL FETCH, que solo permite una constante entera). Los valores de direction que requieren moverse hacia atrás probablemente fallarán a menos que el cursor se haya declarado o abierto con la opción SCROLL.

El cursor debe ser el nombre de una variable refcursor que haga referencia a un portal de cursor abierto.

Ejemplos:

FETCH curs1 INTO rowvar;
FETCH curs2 INTO foo, bar, baz;
FETCH LAST FROM curs3 INTO x, y;
FETCH RELATIVE -2 FROM curs4 INTO x;

MOVE [ direction { FROM | IN } ] cursor;

MOVE vuelve a posicionar un cursor sin recuperar ningún dato. MOVE funciona como el comando FETCH, excepto que solo vuelve a posicionar el cursor y no devuelve la fila a la que se movió. La cláusula direction puede ser cualquiera de las variantes permitidas en el comando SQL FETCH, incluyendo aquellas que pueden recuperar más de una fila; el cursor se posiciona en la última de esas filas. (Sin embargo, el caso en el que la cláusula direction es simplemente una expresión count sin palabra clave está en desuso en PL/pgSQL. Esa sintaxis es ambigua con el caso donde la cláusula direction se omite por completo y, por lo tanto, puede fallar si el count no es una constante). Al igual que con SELECT INTO, la variable especial FOUND se puede comprobar para ver si había una fila a la que moverse. Si no existe tal fila, el cursor se posiciona después de la última fila o antes de la primera fila, según la dirección del movimiento.

Ejemplos:

MOVE curs1;
MOVE LAST FROM curs3;
MOVE RELATIVE -2 FROM curs4;
MOVE FORWARD 2 FROM curs4;

UPDATE table SET ... WHERE CURRENT OF cursor;
DELETE FROM table WHERE CURRENT OF cursor;

Cuando un cursor se posiciona en una fila de tabla, esa fila se puede actualizar o eliminar utilizando el cursor para identificarla. Hay restricciones sobre lo que puede ser la consulta del cursor (en particular, no agrupamiento) y es mejor utilizar FOR UPDATE en el cursor. Para obtener más información, consulta la página de referencia de DECLARE.

Un ejemplo:

UPDATE foo SET dataval = myval WHERE CURRENT OF curs1;

CLOSE cursor;

CLOSE cierra el portal subyacente a un cursor abierto. Esto se puede utilizar para liberar recursos antes del final de la transacción, o para liberar la variable de cursor para que se pueda abrir de nuevo.

Un ejemplo:

CLOSE curs1;

Las funciones de PL/pgSQL pueden devolver cursores al llamador. Esto es útil para devolver múltiples filas o columnas, especialmente con conjuntos de resultados muy grandes. Para hacer esto, la función abre el cursor y devuelve el nombre del cursor al llamador (o simplemente abre el cursor utilizando un nombre de portal especificado por o conocido de otra manera por el llamador). El llamador puede entonces recuperar (fetch) filas del cursor. El cursor puede ser cerrado por el llamador, o se cerrará automáticamente cuando se cierre la transacción.

El nombre del portal utilizado para un cursor lo puede especificar el programador o generarse automáticamente. Para especificar un nombre de portal, simplemente asigna una cadena a la variable refcursor antes de abrirla. El valor de cadena de la variable refcursor será utilizado por OPEN como el nombre del portal subyacente. Sin embargo, si el valor de la variable refcursor es nulo (como lo será por defecto), entonces OPEN genera automáticamente un nombre que no entra en conflicto con ningún portal existente y lo asigna a la variable refcursor.

El siguiente ejemplo muestra una forma en que el llamador puede suministrar un nombre de cursor:

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

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

BEGIN;
SELECT reffunc('funccursor');
FETCH ALL IN funccursor;
COMMIT;

El siguiente ejemplo utiliza la generación automática de nombres de cursor:

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

-- se necesita estar en una transacción para usar cursores.
BEGIN;
SELECT reffunc2();

      reffunc2
--------------------
 <unnamed cursor 1>
(1 row)

FETCH ALL IN "<unnamed cursor 1>";
COMMIT;

El siguiente ejemplo muestra una forma de devolver múltiples cursores desde una sola función:

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

-- se necesita estar en una transacción para usar cursores.
BEGIN;

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

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