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 バイトの値を(ビッグエンディアンのバイトオーダで)入手することになります。
BINARY カーソルは注意して使わなければなりません。 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のカーソル規定をサポートしています。