40.7. 游标

40.7.2.1. OPEN FOR query

OPEN unbound_cursorvar [ [ NO ] SCROLL ] FOR query;

该游标变量打开并且执行给出的查询。游标不能是已经打开的， 并且它必需是声明为一个未绑定的游标(也就是声明为一个简单的refcursor变量)。 查询必须是一条SELECT或者其它返回行的东西(比如EXPLAIN)。 查询是和其它在PL/pgSQL里的SQL命令平等对待的：先代换PL/pgSQL的变量名， 而且执行计划为将来可能的复用缓存起来。 当一个PL/pgSQL变量被替换到游标查询中时， 被替换的值是在OPEN时它所具有的值。 后续的改变不会影响游标的动作，对于一个已经绑定的游标来说， SCROLL和NO SCROLL这两个选项具有相同的含义。

一个例子：

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

40.7.2.2. OPEN FOR EXECUTE

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

打开游标变量并且执行给出的查询。游标不能是已打开的， 并且必须声明为一个未绑定的游标(也就是一个简单的refcursor变量)。 命令是用和那些用于EXECUTE命令一样的方法声明的字符串表达式， 这样，就有了命令可以在两次运行间发生变化的灵活性。 参阅第 40.10.2 节）这也意味着在命令字符串上不能进行变量替换。 跟EXECUTE一起，通过使用USING，参数值可以被插入到动态命令中。 对于一个已经绑定的游标来说，SCROLL和NO SCROLL这两个选项具有相同的含义。

一个例子：

OPEN curs1 FOR EXECUTE 'SELECT * FROM ' || quote_ident(tabname)
                                        || ' WHERE col1 = $1' USING keyvalue;

在这个例子中，表名被插入到文本查询中， 因此使用quote_ident()时要注意SQL注入。 通过USING参数对插入的col1进行比较值，因此不需要使用引号。

40.7.2.3. 打开一个绑定的游标

OPEN bound_cursorvar [ ( [ argument_name := ] argument_value [, ...] ) ];

这种形式的OPEN用于打开一个游标变量， 该游标变量的命令是在声明的时候和它绑定在一起的。游标不能是已经打开的。 当且仅当该游标声明为接受参数的时候，语句中才必需出现一个实际参数值表达式的列表。 这些值将代换到命令中。

一个绑定的游标的命令计划总是认为可缓冲的，这种情况下没有等效的EXECUTE。 需要注意的是SCROLL和NO SCROLL不能在OPEN中被声明， 因为游标的滚动动作已经被定义了。

参数值可以使用positional或者named符号传递。 在位置符号中，所有的参数以顺序指定。 在命名法中，每个参数的名称使用:=声明以 从参数表达式中分开。类似于调用函数，在第 4.3 节中描述， 它也允许混合位置和命名法。

例子（以上使用游标声明的例子）:

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

因为在绑定游标查询上做了变量替换，有两种方法将值传递到游标：要么 使用明确参数到OPEN，或者隐式地在查询中引用PL/pgSQL变量。 然而，只有在绑定游标之前声明的变量将取代它。在这两种情况下 可以在OPEN时决定将被传递的值。例如，另一种方式来获得相同的效果 如curs3上面的例子

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

40.7.3.1. FETCH

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

FETCH从游标中检索下一行到目标中， 目标可以是一个行变量、记录变量、逗号分隔的普通变量列表， 就像SELECT INTO一样， 如果下一行中没有，目标会设为NULL。如同SELECT INTO， 可以使用特殊变量FOUND来检查是否检索出一个行。

direction子句可以是任何 一个SQL FETCH命令允许的变量， 除了那些可以抓取不止一行的；形如：NEXT, PRIOR，FIRST，LAST， ABSOLUTE count， RELATIVE count， FORWARD或者BACKWARD。 忽略direction作为声明的NEXT是相同的。 direction值需要往后移动可能会失败，除非声明的或者打开的 游标带有SCROLL选项。

cursor必须是一个指向一个 打开的游标的refcursor变量的名字。

一个例子：

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

40.7.3.2. MOVE

MOVE [ direction { FROM | IN } ] cursor;

MOVE重新定位一个游标，而不需要检索任何数据。 MOVE的工作方式与FETCH及其相似， 除了它只是重新定位游标并且不返回至移动到的行。 在进行SELECT INTO命令时， 声明的FOUND变量可以用来检查下一个需要移动到的行是否存在。

direction可以是任何一个SQL FETCH 命令允许的变量，如下NEXT, PRIOR， FIRST， LAST， ABSOLUTE count, RELATIVE count, ALL， FORWARD [ count | ALL ] 或者BACKWARD [ count | ALL ]。 忽略direction作为声明的NEXT是相同的。 direction值需要往后移动可能会失败，除非声明的或者打开的 游标带有SCROLL选项。

例如：

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

40.7.3.3. UPDATE/DELETE WHERE CURRENT OF

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

当一个游标被定位到一个表的行上，那么通过使用该游标来识别该行， 从而进行更新或删除操作。当然，对于如何定义游标查询（特别是没有分组时）是存在一定限制的； 在游标中使用FOR UPDATE是个不错的主意。更多信息可参阅DECLARE。

例如：

UPDATE foo SET dataval = myval WHERE CURRENT OF curs1;

40.7.3.4. CLOSE

CLOSE cursor;

CLOSE关闭支撑在一个打开的游标下面的信使。 这样就可以在事务结束之前释放资源， 或者释放掉该游标变量，用于稍后再次打开。

例如：

CLOSE curs1;

40.7.3.5. 返回游标

PL/pgSQL函数可以向调用者返回游标这个功能用于从函数里返回多行或多列， 特别是巨大的结果集。要想这么做，该函数必须打开游标并且把该游标的名字返回给调用者， 或者简单的使用指定的入口名或调用者已知的名字打开游标。 调用者然后从游标里抓取行。游标可以由调用者关闭，或者是在事务结束的时候自动关闭。

函数返回的游标名可以由调用者声明或者自动生成。 要声明一个信使的名字，只要在打开游标之前，给refcursor变量赋予一个字符串就可以了。 refcursor变量的字符串值将被OPEN当作下层的信使的名字使用。 不过，如果refcursor变量是空， 那么OPEN将自动生成一个和现有信使不冲突的名字， 然后将它赋予refcursor变量。

下面的例子显示了一个调用者声明游标名字的方法：

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;

下面的例子使用了自动生成的游标名：

CREATE FUNCTION reffunc2() RETURNS refcursor AS '
DECLARE
    ref refcursor;
BEGIN
    OPEN ref FOR SELECT col FROM test;
    RETURN ref;
END;
' LANGUAGE plpgsql;
-- 需要在一个事务中使用游标。
BEGIN;
SELECT reffunc2();

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

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

下面的例子显示了从一个函数里返回多个游标的方法：

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;
-- 需要在事务里使用游标。
BEGIN;

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

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