begriffs open source - ai-pg/blob - full-docs/man7/DECLARE.7

   1 '\" t
   2 .\"     Title: DECLARE
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "DECLARE" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 DECLARE \- define a cursor
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 DECLARE \fIname\fR [ BINARY ] [ ASENSITIVE | INSENSITIVE ] [ [ NO ] SCROLL ]
  36     CURSOR [ { WITH | WITHOUT } HOLD ] FOR \fIquery\fR
  37 .fi
  38 .SH "DESCRIPTION"
  39 .PP
  40 \fBDECLARE\fR
  41 allows a user to create cursors, which can be used to retrieve a small number of rows at a time out of a larger query\&. After the cursor is created, rows are fetched from it using
  42 \fBFETCH\fR\&.
  43 .if n \{\
  44 .sp
  45 .\}
  46 .RS 4
  47 .it 1 an-trap
  48 .nr an-no-space-flag 1
  49 .nr an-break-flag 1
  50 .br
  51 .ps +1
  52 \fBNote\fR
  53 .ps -1
  54 .br
  55 .PP
  56 This page describes usage of cursors at the SQL command level\&. If you are trying to use cursors inside a
  57 PL/pgSQL
  58 function, the rules are different \(em see
  59 Section\ \&41.7\&.
  60 .sp .5v
  61 .RE
  62 .SH "PARAMETERS"
  63 .PP
  64 \fIname\fR
  65 .RS 4
  66 The name of the cursor to be created\&. This must be different from any other active cursor name in the session\&.
  67 .RE
  68 .PP
  69 BINARY
  70 .RS 4
  71 Causes the cursor to return data in binary rather than in text format\&.
  72 .RE
  73 .PP
  74 ASENSITIVE
  75 .br
  76 INSENSITIVE
  77 .RS 4
  78 Cursor sensitivity determines whether changes to the data underlying the cursor, done in the same transaction, after the cursor has been declared, are visible in the cursor\&.
  79 INSENSITIVE
  80 means they are not visible,
  81 ASENSITIVE
  82 means the behavior is implementation\-dependent\&. A third behavior,
  83 SENSITIVE, meaning that such changes are visible in the cursor, is not available in
  84 PostgreSQL\&. In
  85 PostgreSQL, all cursors are insensitive; so these key words have no effect and are only accepted for compatibility with the SQL standard\&.
  86 .sp
  87 Specifying
  88 INSENSITIVE
  89 together with
  90 FOR UPDATE
  91 or
  92 FOR SHARE
  93 is an error\&.
  94 .RE
  95 .PP
  96 SCROLL
  97 .br
  98 NO SCROLL
  99 .RS 4
 100 SCROLL
 101 specifies that the cursor can be used to retrieve rows in a nonsequential fashion (e\&.g\&., backward)\&. Depending upon the complexity of the query\*(Aqs execution plan, specifying
 102 SCROLL
 103 might impose a performance penalty on the query\*(Aqs execution time\&.
 104 NO SCROLL
 105 specifies that the cursor cannot be used to retrieve rows in a nonsequential fashion\&. The default is to allow scrolling in some cases; this is not the same as specifying
 106 SCROLL\&. See
 107 Notes
 108 below for details\&.
 109 .RE
 110 .PP
 111 WITH HOLD
 112 .br
 113 WITHOUT HOLD
 114 .RS 4
 115 WITH HOLD
 116 specifies that the cursor can continue to be used after the transaction that created it successfully commits\&.
 117 WITHOUT HOLD
 118 specifies that the cursor cannot be used outside of the transaction that created it\&. If neither
 119 WITHOUT HOLD
 120 nor
 121 WITH HOLD
 122 is specified,
 123 WITHOUT HOLD
 124 is the default\&.
 125 .RE
 126 .PP
 127 \fIquery\fR
 128 .RS 4
 129 A
 130 \fBSELECT\fR
 131 or
 132 \fBVALUES\fR
 133 command which will provide the rows to be returned by the cursor\&.
 134 .RE
 135 .PP
 136 The key words
 137 ASENSITIVE,
 138 BINARY,
 139 INSENSITIVE, and
 140 SCROLL
 141 can appear in any order\&.
 142 .SH "NOTES"
 143 .PP
 144 Normal cursors return data in text format, the same as a
 145 \fBSELECT\fR
 146 would produce\&. The
 147 BINARY
 148 option specifies that the cursor should return data in binary format\&. This reduces conversion effort for both the server and client, at the cost of more programmer effort to deal with platform\-dependent binary data formats\&. As an example, if a query returns a value of one from an integer column, you would get a string of
 149 1
 150 with a default cursor, whereas with a binary cursor you would get a 4\-byte field containing the internal representation of the value (in big\-endian byte order)\&.
 151 .PP
 152 Binary cursors should be used carefully\&. Many applications, including
 153 psql, are not prepared to handle binary cursors and expect data to come back in the text format\&.
 154 .if n \{\
 155 .sp
 156 .\}
 157 .RS 4
 158 .it 1 an-trap
 159 .nr an-no-space-flag 1
 160 .nr an-break-flag 1
 161 .br
 162 .ps +1
 163 \fBNote\fR
 164 .ps -1
 165 .br
 166 .PP
 167 When the client application uses the
 168 \(lqextended query\(rq
 169 protocol to issue a
 170 \fBFETCH\fR
 171 command, the Bind protocol message specifies whether data is to be retrieved in text or binary format\&. This choice overrides the way that the cursor is defined\&. The concept of a binary cursor as such is thus obsolete when using extended query protocol \(em any cursor can be treated as either text or binary\&.
 172 .sp .5v
 173 .RE
 174 .PP
 175 Unless
 176 WITH HOLD
 177 is specified, the cursor created by this command can only be used within the current transaction\&. Thus,
 178 \fBDECLARE\fR
 179 without
 180 WITH HOLD
 181 is useless outside a transaction block: the cursor would survive only to the completion of the statement\&. Therefore
 182 PostgreSQL
 183 reports an error if such a command is used outside a transaction block\&. Use
 184 \fBBEGIN\fR
 185 and
 186 \fBCOMMIT\fR
 187 (or
 188 \fBROLLBACK\fR) to define a transaction block\&.
 189 .PP
 190 If
 191 WITH HOLD
 192 is specified and the transaction that created the cursor successfully commits, the cursor can continue to be accessed by subsequent transactions in the same session\&. (But if the creating transaction is aborted, the cursor is removed\&.) A cursor created with
 193 WITH HOLD
 194 is closed when an explicit
 195 \fBCLOSE\fR
 196 command is issued on it, or the session ends\&. In the current implementation, the rows represented by a held cursor are copied into a temporary file or memory area so that they remain available for subsequent transactions\&.
 197 .PP
 198 WITH HOLD
 199 may not be specified when the query includes
 200 FOR UPDATE
 201 or
 202 FOR SHARE\&.
 203 .PP
 204 The
 205 SCROLL
 206 option should be specified when defining a cursor that will be used to fetch backwards\&. This is required by the SQL standard\&. However, for compatibility with earlier versions,
 207 PostgreSQL
 208 will allow backward fetches without
 209 SCROLL, if the cursor\*(Aqs query plan is simple enough that no extra overhead is needed to support it\&. However, application developers are advised not to rely on using backward fetches from a cursor that has not been created with
 210 SCROLL\&. If
 211 NO SCROLL
 212 is specified, then backward fetches are disallowed in any case\&.
 213 .PP
 214 Backward fetches are also disallowed when the query includes
 215 FOR UPDATE
 216 or
 217 FOR SHARE; therefore
 218 SCROLL
 219 may not be specified in this case\&.
 220 .if n \{\
 221 .sp
 222 .\}
 223 .RS 4
 224 .it 1 an-trap
 225 .nr an-no-space-flag 1
 226 .nr an-break-flag 1
 227 .br
 228 .ps +1
 229 \fBCaution\fR
 230 .ps -1
 231 .br
 232 .PP
 233 Scrollable cursors may give unexpected results if they invoke any volatile functions (see
 234 Section\ \&36.7)\&. When a previously fetched row is re\-fetched, the functions might be re\-executed, perhaps leading to results different from the first time\&. It\*(Aqs best to specify
 235 NO SCROLL
 236 for a query involving volatile functions\&. If that is not practical, one workaround is to declare the cursor
 237 SCROLL WITH HOLD
 238 and commit the transaction before reading any rows from it\&. This will force the entire output of the cursor to be materialized in temporary storage, so that volatile functions are executed exactly once for each row\&.
 239 .sp .5v
 240 .RE
 241 .PP
 242 If the cursor\*(Aqs query includes
 243 FOR UPDATE
 244 or
 245 FOR SHARE, then returned rows are locked at the time they are first fetched, in the same way as for a regular
 246 \fBSELECT\fR
 247 command with these options\&. In addition, the returned rows will be the most up\-to\-date versions\&.
 248 .if n \{\
 249 .sp
 250 .\}
 251 .RS 4
 252 .it 1 an-trap
 253 .nr an-no-space-flag 1
 254 .nr an-break-flag 1
 255 .br
 256 .ps +1
 257 \fBCaution\fR
 258 .ps -1
 259 .br
 260 .PP
 261 It is generally recommended to use
 262 FOR UPDATE
 263 if the cursor is intended to be used with
 264 \fBUPDATE \&.\&.\&. WHERE CURRENT OF\fR
 265 or
 266 \fBDELETE \&.\&.\&. WHERE CURRENT OF\fR\&. Using
 267 FOR UPDATE
 268 prevents other sessions from changing the rows between the time they are fetched and the time they are updated\&. Without
 269 FOR UPDATE, a subsequent
 270 WHERE CURRENT OF
 271 command will have no effect if the row was changed since the cursor was created\&.
 272 .PP
 273 Another reason to use
 274 FOR UPDATE
 275 is that without it, a subsequent
 276 WHERE CURRENT OF
 277 might fail if the cursor query does not meet the SQL standard\*(Aqs rules for being
 278 \(lqsimply updatable\(rq
 279 (in particular, the cursor must reference just one table and not use grouping or
 280 ORDER BY)\&. Cursors that are not simply updatable might work, or might not, depending on plan choice details; so in the worst case, an application might work in testing and then fail in production\&. If
 281 FOR UPDATE
 282 is specified, the cursor is guaranteed to be updatable\&.
 283 .PP
 284 The main reason not to use
 285 FOR UPDATE
 286 with
 287 WHERE CURRENT OF
 288 is if you need the cursor to be scrollable, or to be isolated from concurrent updates (that is, continue to show the old data)\&. If this is a requirement, pay close heed to the caveats shown above\&.
 289 .sp .5v
 290 .RE
 291 .PP
 292 The SQL standard only makes provisions for cursors in embedded
 293 SQL\&. The
 294 PostgreSQL
 295 server does not implement an
 296 \fBOPEN\fR
 297 statement for cursors; a cursor is considered to be open when it is declared\&. However,
 298 ECPG, the embedded SQL preprocessor for
 299 PostgreSQL, supports the standard SQL cursor conventions, including those involving
 300 \fBDECLARE\fR
 301 and
 302 \fBOPEN\fR
 303 statements\&.
 304 .PP
 305 The server data structure underlying an open cursor is called a
 306 portal\&. Portal names are exposed in the client protocol: a client can fetch rows directly from an open portal, if it knows the portal name\&. When creating a cursor with
 307 \fBDECLARE\fR, the portal name is the same as the cursor name\&.
 308 .PP
 309 You can see all available cursors by querying the
 310 pg_cursors
 311 system view\&.
 312 .SH "EXAMPLES"
 313 .PP
 314 To declare a cursor:
 315 .sp
 316 .if n \{\
 317 .RS 4
 318 .\}
 319 .nf
 320 DECLARE liahona CURSOR FOR SELECT * FROM films;
 321 .fi
 322 .if n \{\
 323 .RE
 324 .\}
 325 .sp
 326 See
 327 \fBFETCH\fR(7)
 328 for more examples of cursor usage\&.
 329 .SH "COMPATIBILITY"
 330 .PP
 331 The SQL standard allows cursors only in embedded
 332 SQL
 333 and in modules\&.
 334 PostgreSQL
 335 permits cursors to be used interactively\&.
 336 .PP
 337 According to the SQL standard, changes made to insensitive cursors by
 338 UPDATE \&.\&.\&. WHERE CURRENT OF
 339 and
 340 DELETE \&.\&.\&. WHERE CURRENT OF
 341 statements are visible in that same cursor\&.
 342 PostgreSQL
 343 treats these statements like all other data changing statements in that they are not visible in insensitive cursors\&.
 344 .PP
 345 Binary cursors are a
 346 PostgreSQL
 347 extension\&.
 348 .SH "SEE ALSO"
 349 \fBCLOSE\fR(7), \fBFETCH\fR(7), \fBMOVE\fR(7)