raw/man7/declare.7

   1 .\\" auto-generated by docbook2man-spec $Revision: 1.1 $
   2 .TH "DECLARE" "7" "2003-11-02" "SQL - Language Statements" "SQL Commands"
   3 .SH NAME
   4 DECLARE \- define a cursor
   5
   6 .SH SYNOPSIS
   7 .sp
   8 .nf
   9 DECLARE \fIname\fR [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
  10     CURSOR [ { WITH | WITHOUT } HOLD ] FOR \fIquery\fR
  11     [ FOR { READ ONLY | UPDATE [ OF \fIcolumn\fR [, ...] ] } ]
  12 .sp
  13 .fi
  14 .SH "DESCRIPTION"
  15 .PP
  16 \fBDECLARE\fR allows a user to create cursors, which
  17 can be used to retrieve
  18 a small number of rows at a time out of a larger query. Cursors can
  19 return data either in text or in binary format using
  20 FETCH [\fBfetch\fR(7)].
  21 .PP
  22 Normal cursors return data in text format, the same as a
  23 \fBSELECT\fR would produce. Since data is stored natively in
  24 binary format, the system must do a conversion to produce the text
  25 format. Once the information comes back in text form, the client
  26 application may need to convert it to a binary format to manipulate
  27 it. In addition, data in the text format is often larger in size
  28 than in the binary format. Binary cursors return the data in a
  29 binary representation that may be more easily manipulated.
  30 Nevertheless, if you intend to display the data as text anyway,
  31 retrieving it in text form will
  32 save you some effort on the client side.
  33 .PP
  34 As an example, if a query returns a value of one from an integer column,
  35 you would get a string of 1 with a default cursor
  36 whereas with a binary cursor you would get
  37 a 4-byte field containing the internal representation of the value
  38 (in big-endian byte order).
  39 .PP
  40 Binary cursors should be used carefully. Many applications,
  41 including \fBpsql\fR, are not prepared to
  42 handle binary cursors and expect data to come back in the text
  43 format.
  44 .sp
  45 .RS
  46 .B "Note:"
  47 When the client application uses the ``extended query'' protocol
  48 to issue a \fBFETCH\fR command, the Bind protocol message
  49 specifies whether data is to be retrieved in text or binary format.
  50 This choice overrides the way that the cursor is defined. The concept
  51 of a binary cursor as such is thus obsolete when using extended query
  52 protocol --- any cursor can be treated as either text or binary.
  53 .RE
  54 .sp
  55 .SH "PARAMETERS"
  56 .TP
  57 \fB\fIname\fB\fR
  58 The name of the cursor to be created.
  59 .TP
  60 \fBBINARY\fR
  61 Causes the cursor to return data in binary rather than in text format.
  62 .TP
  63 \fBINSENSITIVE\fR
  64 Indicates that data retrieved from the cursor should be
  65 unaffected by updates to the tables underlying the cursor while
  66 the cursor exists. In PostgreSQL,
  67 all cursors are insensitive; this key word currently has no
  68 effect and is present for compatibility with the SQL standard.
  69 .TP
  70 \fBSCROLL\fR
  71 .TP
  72 \fBNO SCROLL\fR
  73 SCROLL specifies that the cursor may be used
  74 to retrieve rows in a nonsequential fashion (e.g.,
  75 backward). Depending upon the complexity of the query's
  76 execution plan, specifying SCROLL may impose
  77 a performance penalty on the query's execution time.
  78 NO SCROLL specifies that the cursor cannot be
  79 used to retrieve rows in a nonsequential fashion.
  80 .TP
  81 \fBWITH HOLD\fR
  82 .TP
  83 \fBWITHOUT HOLD\fR
  84 WITH HOLD specifies that the cursor may
  85 continue to be used after the transaction that created it
  86 successfully commits. WITHOUT HOLD specifies
  87 that the cursor cannot be used outside of the transaction that
  88 created it. If neither WITHOUT HOLD nor
  89 WITH HOLD is specified, WITHOUT
  90 HOLD is the default.
  91 .TP
  92 \fB\fIquery\fB\fR
  93 A \fBSELECT\fR command that will provide the rows to be
  94 returned by the cursor. Refer to SELECT [\fBselect\fR(7)] for further information about valid
  95 queries.
  96 .TP
  97 \fBFOR READ ONLY\fR
  98 .TP
  99 \fBFOR UPDATE\fR
 100 FOR READ ONLY indicates that the cursor will
 101 be used in a read-only mode. FOR UPDATE
 102 indicates that the cursor will be used to update tables. Since
 103 cursor updates are not currently supported in
 104 PostgreSQL, specifying FOR
 105 UPDATE will cause an error message and specifying
 106 FOR READ ONLY has no effect.
 107 .TP
 108 \fB\fIcolumn\fB\fR
 109 Column(s) to be updated by the cursor. Since cursor updates are
 110 not currently supported in
 111 PostgreSQL, the FOR
 112 UPDATE clause provokes an error message.
 113 .PP
 114 The key words BINARY,
 115 INSENSITIVE, and SCROLL may
 116 appear in any order.
 117 .PP
 118 .SH "NOTES"
 119 .PP
 120 Unless WITH HOLD is specified, the cursor
 121 created by this command can only be used within the current
 122 transaction. Thus, \fBDECLARE\fR without WITH
 123 HOLD is useless outside a transaction block: the cursor would
 124 survive only to the completion of the statement. Therefore
 125 PostgreSQL reports an error if this
 126 command is used outside a transaction block.
 127 Use
 128 BEGIN [\fBbegin\fR(7)],
 129 COMMIT [\fBcommit\fR(7)]
 130 and
 131 ROLLBACK [\fBrollback\fR(7)]
 132 to define a transaction block.
 133 .PP
 134 If WITH HOLD is specified and the transaction
 135 that created the cursor successfully commits, the cursor can
 136 continue to be accessed by subsequent transactions in the same
 137 session. (But if the creating transaction is aborted, the cursor
 138 is removed.) A cursor created with WITH HOLD
 139 is closed when an explicit \fBCLOSE\fR command is
 140 issued on it, or the session ends. In the current implementation,
 141 the rows represented by a held cursor are copied into a temporary
 142 file or memory area so that they remain available for subsequent
 143 transactions.
 144 .PP
 145 The SCROLL option should be specified when defining a
 146 cursor that will be used to fetch backwards. This is required by
 147 the SQL standard. However, for compatibility with earlier
 148 versions, PostgreSQL will allow
 149 backward fetches without SCROLL, if the cursor's query
 150 plan is simple enough that no extra overhead is needed to support
 151 it. However, application developers are advised not to rely on
 152 using backward fetches from a cursor that has not been created
 153 with SCROLL. If NO SCROLL is
 154 specified, then backward fetches are disallowed in any case.
 155 .PP
 156 The SQL standard only makes provisions for cursors in embedded
 157 SQL. The PostgreSQL
 158 server does not implement an \fBOPEN\fR statement for
 159 cursors; a cursor is considered to be open when it is declared.
 160 However, \fBECPG\fR, the embedded SQL
 161 preprocessor for PostgreSQL, supports
 162 the standard SQL cursor conventions, including those involving
 163 \fBDECLARE\fR and \fBOPEN\fR statements.
 164 .SH "EXAMPLES"
 165 .PP
 166 To declare a cursor:
 167 .sp
 168 .nf
 169 DECLARE liahona CURSOR FOR SELECT * FROM films;
 170 .sp
 171 .fi
 172 See FETCH [\fBfetch\fR(7)] for more
 173 examples of cursor usage.
 174 .SH "COMPATIBILITY"
 175 .PP
 176 The SQL standard allows cursors only in embedded
 177 SQL and in modules. PostgreSQL
 178 permits cursors to be used interactively.
 179 .PP
 180 The SQL standard allows cursors to update table data. All
 181 PostgreSQL cursors are read only.
 182 .PP
 183 Binary cursors are a PostgreSQL
 184 extension.