39.7. カーソル

39.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;

39.7.2.2. OPEN FOR EXECUTE

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

カーソル変数は開かれ、実行するよう指定した問い合わせが付与されます。 既に開いたカーソルを開くことはできず、また、アンバウンドカーソル変数として（つまり、単なるrefcursor変数として）宣言されていなければなりません。 問い合わせは、EXECUTEコマンドと同じ方法による文字列式として指定されます。 通常と同様に、これにより、次回に実行する際に違った問い合わせを計画できる柔軟性が得られます(項39.10.2参照)。 また、変数置換がコマンド文字列上で行われないことも意味します。 EXECUTEと同様にUSINGを介して動的コマンドにパラメータ値を挿入することができます。 SCROLLおよびNO SCROLLオプションの意味はバウンドカーソルと同様です。

以下に例を示します。

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

この例では、テーブル名は問い合わせ内にテキストとして埋め込まれます。 このためSQLインジェクションに対抗するためにquote_ident()の使用を勧めます。 col1との比較値はUSING経由で埋め込まれますので、引用符を付ける必要がありません。

39.7.2.3. バウンドカーソルを開く

OPEN bound_cursorvar [ ( argument_values ) ];

宣言時に問い合わせが結び付いたカーソル変数を開くために使用されるOPENの形式です。 既に開いたカーソルを開くことはできません。 実引数の式のリストはカーソルが引数を取るものと宣言された場合にのみ現れます。 これらの値は問い合わせの中で置き換えられます。 バウンドカーソルの問い合わせ計画は常にキャッシュ可能とみなされます。 この場合、EXECUTEと等価なものはありません。 SCROLLおよびNO SCROLLを指定できないことに注意してください。 カーソル移動の仕様はすでに決まっているからです。

変数の代入はバウンドカーソルの問い合わせで行われるため、カーソルへ値を渡す方法が2つあることに注意してください。 OPENコマンドの明確な引数とするものと、問い合わせにおけるPL/pgSQL変数として暗黙的に参照するものです。 しかし、バウンドカーソルの宣言より前に宣言した変数だけが代入されます。 どちらの場合も、OPENの実行時に変数値が決まります。

例：

OPEN curs2;
OPEN curs3(42);

39.7.3.1. FETCH

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

FETCHはSELECT INTOと同様に、カーソルから次の行を抽出し、対象に格納します。 対象とは、行変数、レコード変数、または単純な変数をカンマで区切ったリストです。 SELECT INTOの場合と同様、特殊なFOUND変数を検査することで、行が入手できたかどうかを確認することができます。

direction句は複数行を取り出すことができるコマンドを除き、SQL FETCHで許可されたどのようなコマンドも可能です。 すなわち、以下のものです。 NEXT、 PRIOR、 FIRST、 LAST、 ABSOLUTE count、 RELATIVE count、 FORWARDまたは BACKWARD。 direction句の省略は、NEXTの指定と同じです。 SCROLLオプションを用いてカーソルを宣言または開かないと、directionの値による逆方向への移動の要求は失敗します。

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;

39.7.3.2. MOVE

MOVE [ direction { FROM | IN } ] cursor;

MOVEコマンドは、データを取り出さないでカーソルの位置を変更します。 移動先の行を返さないでカーソルの位置だけを変更することを除けば、FETCHコマンドと同一の働きをします。 SELECT INTOと同様に、特殊な変数FOUNDを用いて、移動先に行が存在するかどうかを検査できます。

direction句は、FETCH SQLコマンドで許されている以下の値のいずれかを取ることができます。 NEXT、 PRIOR、 FIRST、 LAST、 ABSOLUTE count、 RELATIVE count、 ALL、 FORWARD [ count | ALL ]、または BACKWARD [ count | ALL ] direction句の省略は、NEXTの指定と同じです。 SCROLLオプションを用いてカーソルを宣言または開かないと、directionの値による逆方向への移動の要求は失敗します。

例:

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

39.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;

39.7.3.4. CLOSE

CLOSE cursor;

CLOSEはポータルの背後にあるカーソルを閉じます。 これを使用してトランザクションの終わりよりも前にリソースを解放することができ、また、カーソル変数を解放し、再度開くことができます。

例：

CLOSE curs1;

39.7.3.5. カーソルを返す

PL/pgSQL関数では、呼び出し元にカーソルを返すことができます。 この方法は、関数から複数行または複数列を返す場合、特にその結果集合が非常に大きい場合に有用です。 これを行うには、関数はカーソルを開き、呼び出し元にカーソル名を返します（もしくは、もし呼び出し元でポータル名がわかっていれば、単純に指定されたポータル名を使用してカーソルを開きます）。 これにより、呼び出し元はカーソルから行を取り出すことができるようになります。 カーソルは呼び出し元で閉じることができます。 または、トランザクションが終了した際に自動的に閉じられます。

カーソル用のポータル名は、プログラマが指定するか、または自動的に生成されます。 ポータル名を指定するには、開く前に、単にrefcursor変数に文字列を代入します。 refcursor変数の文字列値はOPENによって、背後のポータル名として使用されます。 しかし、refcursor変数がNULLの場合、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;