DECLARE -- Defines a new cursor.


DECLARE cursorname 
    CURSOR FOR query
    [ FOR { READ ONLY | UPDATE [ OF column [, ...] } ]



Use this parameter to specify the name of the new cursor.


Pass this keyword to cause the cursor to fetch data in binary format, rather than the default text format.


Pass this keyword to specify that all data retrieved from the cursor will be unchanged by updates from other processes (and other cursors). This is unneeded when using PostgreSQL, as the database handles all cursor operations encapsulated within transactions.


This keyword allows data to be retrieved in multiple rows per FETCH operation; however, passing it will have no effect, as PostgreSQL already allows the functionality implicitly.


Use this parameter to supply the SQL query that will provide the new cursor with rows. For information on how to construct this query, see SELECT.


This keyword specifies that the cursor will be used only to read data (read-only mode); however, using this keyword has no effect, as PostgreSQL only provides read-only access for use with cursors.


This keyword specifies that the cursor will be used to update tables; however, updates from cursors are not supported as of PostgreSQL 7.1.x (the current version at the printing of this book).


This parameter takes the names of columns to be updated; however, cursor updates are not currently supported as of PostgreSQL 7.1.x (the current version at the printing of this book).



This message is displayed if the SELECT query is run successfully.

NOTICE: Closing pre-existing portal "cursorname"

This message is displayed if a cursor with the name you specified had already been declared within the current transaction block. If this happens, the previously declared cursor is automatically discarded.

ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks

This error is displayed if you attempt to declare a cursor outside of a transaction block. You must be within a transaction block to use cursors.


Use the DECLARE command to create a cursor within a transaction block, which can then be used to retrieve data from large queries. Returned data can be in either text or binary format. The use of cursors is only supported within transaction blocks. You will receive an error if you attempt to use them without starting a transaction block.


Use binary cursors with caution, as not all clients support their use.

PostgreSQL does not require you to explicitly open a cursor; the cursor is opened when you declare it. However, the use of explicit OPEN commands is supported by the preprocessor, ecpg, for use with embedded or interactive SQL applications.


The following example declares a cursor named cur_publisher and fetches 2 rows.

DECLARE cur_publisher CURSOR FOR SELECT * FROM publishers;
FETCH FORWARD 2 IN cur_publisher;