DECLARE name [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
CURSOR [ { WITH | WITHOUT } HOLD ] FOR query
[ FOR { READ ONLY | UPDATE [ OF column [, ...] ] } ]DECLAREによって、ユーザは巨大な問い合わせの中から一度に少数の行を取り出すために使用できるカーソルを作成することができます。 FETCHを使用して、カーソルからテキストもしくはバイナリのどちらかの形式でデータを取り出すことができます。
通常のカーソルは、SELECTの出力同様のテキスト形式でデータを返します。 元のデータは固有のバイナリ形式で保存されていますので、システムはテキスト形式を生成するために変換を行なう必要があります。 情報がテキスト形式で返されると、クライアントアプリケーションは情報を処理するためにバイナリ形式に変換する必要になることがあります。 また、テキスト形式の場合、対応するバイナリ形式よりもそのサイズが大きくなることがよくあります。 BINARYカーソルによって、固有のバイナリ表現でデータを返すことができ、より簡単に操作することができます。 それにも関わらず、とにかくデータをテキストとして表示する予定であるのならば、テキスト形式でデータを取り出すことにより、クライアント側の処理を軽減させることになります。
例えば、問い合わせが整数の列から1の値を返す場合、デフォルトのカーソルでは1という文字列を入手することになりますが、バイナリ形式のカーソルの場合はその値の内部表現から成る4バイトの値を(ビッグエンディアンのバイトオーダで)入手することになります。
バイナリ形式のカーソルは注意して使わなければなりません。 psqlのような多くのアプリケーションは、バイナリ形式のカーソルを扱うようにはなっていず、データはテキスト形式で返されるものとみなしています。
注意: クライアントアプリケーションが"拡張問い合わせ"プロトコルを使用してFETCHコマンドを発行する場合、バインドプロトコルメッセージは、テキスト形式かバイナリ形式かいずれかでデータを受け取るかを指定します。 この選択は、カーソル定義での指定を上書きします。 こういったバイナリカーソルの概念は、全てのカーソルはテキストとしてもバイナリとしても扱うことができる拡張問い合わせプロトコルでは旧式なものです。
作成されるカーソルの名前です。
カーソルによるデータの取得が、テキスト形式ではなくバイナリ形式になります。
カーソルから取り出されたデータが、そのカーソルが存在する間、その背後にあるテーブルの更新の影響を受けないことを示します。 PostgreSQLでは、カーソルは全て更新の影響を受けません。 このキーワードを使用しても効果はなく、標準SQLとの互換性のために存在するものです。
SCROLLは、そのカーソルは順序通りでない方法(例えば後方)で行を取り出すことができることを指定します。 問い合わせの実行計画の複雑さに依存して、SCROLL指定は、問い合わせの実行時間において、性能的なペナルティが課せられる可能性があります。 NO SCROLLは、カーソルは順序通りでない方法では行を取り出すことができないことを指定します。
WITH HOLDは、カーソルを生成したトランザクションが終了した後でもそのカーソルを続行できることを指定します。 WITHOUT HOLDは、カーソルを生成したトランザクションの外部では、そのカーソルを使用できないことを指定します。 WITH HOLDもWITHOUT HOLDも指定されない場合、WITHOUT HOLDがデフォルトとなります。
カーソルによって返される行を提供するSELECTコマンドです。 有効な問い合わせについての詳細は、SELECTを参照してください。
FOR READ ONLYは、カーソルが読み取り専用モードで使用されることを示します。 FOR UPDATEは、カーソルがテーブルを更新するために使用されることを示します。 現時点ではPostgreSQLはカーソルでの更新をサポートしていませんので、FOR UPDATEはエラーメッセージを表示し、また、FOR READ ONLYの指定は効果がありません。
カーソルによって更新される列(複数可)です。 現時点ではPostgreSQLはカーソルでの更新をサポートしていませんので、FOR UPDATE句はエラーメッセージを誘発します。
BINARY、INSENSITIVE、SCROLLキーワードは任意の順番で指定することができます。
WITH HOLDが指定されなければ、このコマンドで生成されるカーソルは現在のトランザクションの中でのみ使用することができます。 従って、WITH HOLDの無いDECLAREはトランザクションブロックの外側では意味がありません。 その場合カーソルはこの文が完了するまでのみ有効です。 そのため、PostgreSQLはトランザクションブロックの外部でこのコマンドが使用された場合エラーを報告します。 トランザクションブロックを定義するには、BEGIN、COMMIT、ROLLBACKを使用してください。
WITH HOLDが指定され、カーソルを作成したトランザクションのコミットに成功した場合、同一セッション内でその後のトランザクションでもそのカーソルにアクセスすることができます。 (しかし、トランザクションがアボートした場合、そのカーソルは削除されます。) WITH HOLD付きで作成されたカーソルは、そのカーソルに対して明示的なCLOSEが発行された場合やセッションが終了した時に閉ざされます。 現在の実装では、保持されたカーソルで表される行は、その後のトランザクションでも利用できるように、一時ファイルかメモリ領域にコピーされます。
定義するカーソルが後方向に取り出すために使用する時には、SCROLLオプションを指定しなければなりません。 これは標準SQLで要求されています。 しかし、以前のバージョンとの互換性のために、PostgreSQLでは、カーソルの問い合わせ計画が単純でそのサポートに余計なオーバーヘッドが必要無い場合、 SCROLL無しでも後方向に取り出すことができます。 しかし、アプリケーション開発者にはSCROLL無しで作成されたカーソルからの後方向の取り出しができることに依存しないことを勧めます。 NO SCROLLを指定した場合は、後方向取り出しはどのような場合でも行うことができません。
標準SQLでは、組み込みSQLにおけるカーソルのみ規定されています。 PostgreSQLサーバはカーソル用のOPEN文を実装していません。 カーソルは宣言された時に開いたものとみなされています。 しかし、PostgreSQL用の埋め込みSQLプリプロセッサであるECPGでは、DECLAREとOPEN文などを含め、標準SQLのカーソル規定をサポートしています。