pg_describe_cursor — Get information about a cursor (portal)


pg_describe_cursor conn cursorName


pg_describe_cursor gets information about an open cursor (or portal, the term used by the PostgreSQL documentation). A cursor is created with the SQL DECLARE command. A result structure is returned, for use with pg_result to get information about the cursor.



The handle of the connection on which the cursor is open.


The name of the cursor to get information about.

Return Value

Returns a result handle which can be used with pg_result to obtain information about the cursor.


On success, a result structure which has status PGRES_COMMAND_OK will be returned. The result structure will have no data rows, only attribute (column) information. If no such cursor exists, the result structure will have status PGRES_FATAL_ERROR. A Tcl error may be thrown under other error conditions.

Use pg_result to get information from the returned result structure, and be sure to free the returned result handle with pg_result -clear when you are done with it.

This command uses or emulates the PostgreSQL libpq function PQdescribePortal.

This command was added in pgtclng-1.7.0 and in pgintcl-3.1.0.


Declare a cursor and get the names of its columns:

pg_execute $conn "DECLARE mycursor CURSOR FOR SELECT * FROM mytable"
set result [pg_describe_cursor $conn mycursor]
if {[pg_result $result -status] eq "PGRES_COMMAND_OK"} {
  puts "Cursor columns are: [pg_result $result -attributes]"
} Logo

This version of the manual was produced for the Pgtcl-ng Sourceforge project web service site, which requires the logo on each page.

To download a logo-free copy of the manual, see the Pgtcl-ng project downloads area.