← Back to branch summary

~ubuntu-branches/ubuntu/hardy/postgresql-8.4/hardy-backports

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/declare.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2009-03-20 12:00:13 UTC
  • Revision ID: james.westby@ubuntu.com-20090320120013-hogj7egc5mjncc5g
Tags: upstream-8.4~0cvs20090328
Import upstream version 8.4~0cvs20090328

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/declare.sgml
 
1
<!--
 
2
$PostgreSQL$
 
3
PostgreSQL documentation
 
4
-->
 
5
 
 
6
<refentry id="SQL-DECLARE">
 
7
 <refmeta>
 
8
  <refentrytitle id="SQL-DECLARE-TITLE">DECLARE</refentrytitle>
 
9
  <manvolnum>7</manvolnum>
 
10
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 
11
 </refmeta>
 
12
 
 
13
 <refnamediv>
 
14
  <refname>DECLARE</refname>
 
15
  <refpurpose>define a cursor</refpurpose>
 
16
 </refnamediv>
 
17
 
 
18
 <indexterm zone="sql-declare">
 
19
  <primary>DECLARE</primary>
 
20
 </indexterm>
 
21
 
 
22
 <indexterm zone="sql-declare">
 
23
  <primary>cursor</primary>
 
24
  <secondary>DECLARE</secondary>
 
25
 </indexterm>
 
26
 
 
27
 <refsynopsisdiv>
 
28
<synopsis>
 
29
DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
 
30
    CURSOR [ { WITH | WITHOUT } HOLD ] FOR <replaceable class="parameter">query</replaceable>
 
31
</synopsis>
 
32
 </refsynopsisdiv>
 
33
 
 
34
 <refsect1>
 
35
  <title>Description</title>
 
36
 
 
37
  <para>
 
38
   <command>DECLARE</command> allows a user to create cursors, which
 
39
   can be used to retrieve
 
40
   a small number of rows at a time out of a larger query.
 
41
   After the cursor is created, rows are fetched from it using
 
42
   <xref linkend="sql-fetch" endterm="sql-fetch-title">.
 
43
  </para>
 
44
 </refsect1>
 
45
 
 
46
 <refsect1>
 
47
  <title>Parameters</title>
 
48
 
 
49
  <variablelist>
 
50
   <varlistentry>
 
51
    <term><replaceable class="parameter">name</replaceable></term>
 
52
    <listitem>
 
53
     <para>
 
54
      The name of the cursor to be created.
 
55
     </para>
 
56
    </listitem>
 
57
   </varlistentry>
 
58
 
 
59
   <varlistentry>
 
60
    <term><literal>BINARY</literal></term>
 
61
    <listitem>
 
62
     <para>
 
63
      Causes the cursor to return data in binary rather than in text format.
 
64
     </para>
 
65
    </listitem>
 
66
   </varlistentry>
 
67
 
 
68
   <varlistentry>
 
69
    <term><literal>INSENSITIVE</literal></term>
 
70
    <listitem>
 
71
     <para>
 
72
      Indicates that data retrieved from the cursor should be
 
73
      unaffected by updates to the table(s) underlying the cursor that occur
 
74
      after the cursor is created.  In <productname>PostgreSQL</productname>,
 
75
      this is the default behavior; so this key word has no
 
76
      effect and is only accepted for compatibility with the SQL standard.
 
77
     </para>
 
78
    </listitem>
 
79
   </varlistentry>
 
80
 
 
81
   <varlistentry>
 
82
    <term><literal>SCROLL</literal></term>
 
83
    <term><literal>NO SCROLL</literal></term>
 
84
    <listitem>
 
85
     <para>
 
86
      <literal>SCROLL</literal> specifies that the cursor can be used
 
87
      to retrieve rows in a nonsequential fashion (e.g.,
 
88
      backward). Depending upon the complexity of the query's
 
89
      execution plan, specifying <literal>SCROLL</literal> might impose
 
90
      a performance penalty on the query's execution time.
 
91
      <literal>NO SCROLL</literal> specifies that the cursor cannot be
 
92
      used to retrieve rows in a nonsequential fashion.  The default is to
 
93
      allow scrolling in some cases; this is not the same as specifying
 
94
      <literal>SCROLL</literal>. See <xref linkend="sql-declare-notes"
 
95
      endterm="sql-declare-notes-title"> for details.
 
96
     </para>
 
97
    </listitem>
 
98
   </varlistentry>
 
99
 
 
100
   <varlistentry>
 
101
    <term><literal>WITH HOLD</literal></term>
 
102
    <term><literal>WITHOUT HOLD</literal></term>
 
103
    <listitem>
 
104
     <para>
 
105
      <literal>WITH HOLD</literal> specifies that the cursor can
 
106
      continue to be used after the transaction that created it
 
107
      successfully commits.  <literal>WITHOUT HOLD</literal> specifies
 
108
      that the cursor cannot be used outside of the transaction that
 
109
      created it. If neither <literal>WITHOUT HOLD</literal> nor
 
110
      <literal>WITH HOLD</literal> is specified, <literal>WITHOUT
 
111
      HOLD</literal> is the default.
 
112
     </para>
 
113
    </listitem>
 
114
   </varlistentry>
 
115
 
 
116
   <varlistentry>
 
117
    <term><replaceable class="parameter">query</replaceable></term>
 
118
    <listitem>
 
119
     <para>
 
120
      A <xref linkend="sql-select" endterm="sql-select-title"> or
 
121
      <xref linkend="sql-values" endterm="sql-values-title"> command
 
122
      which will provide the rows to be returned by the cursor.
 
123
     </para>
 
124
    </listitem>
 
125
   </varlistentry>
 
126
  </variablelist>
 
127
 
 
128
  <para>
 
129
   The key words <literal>BINARY</literal>,
 
130
   <literal>INSENSITIVE</literal>, and <literal>SCROLL</literal> can
 
131
   appear in any order.
 
132
  </para>
 
133
 </refsect1>
 
134
 
 
135
 <refsect1 id="sql-declare-notes">
 
136
  <title id="sql-declare-notes-title">Notes</title>
 
137
 
 
138
  <para>
 
139
   Normal cursors return data in text format, the same as a
 
140
   <command>SELECT</> would produce.  The <literal>BINARY</> option
 
141
   specifies that the cursor should return data in binary format.
 
142
   This reduces conversion effort for both the server and client,
 
143
   at the cost of more programmer effort to deal with platform-dependent
 
144
   binary data formats.
 
145
   As an example, if a query returns a value of one from an integer column,
 
146
   you would get a string of <literal>1</> with a default cursor,
 
147
   whereas with a binary cursor you would get
 
148
   a 4-byte field containing the internal representation of the value
 
149
   (in big-endian byte order).
 
150
  </para>
 
151
 
 
152
  <para>
 
153
   Binary cursors should be used carefully.  Many applications,
 
154
   including <application>psql</application>, are not prepared to
 
155
   handle binary cursors and expect data to come back in the text
 
156
   format.
 
157
  </para>
 
158
 
 
159
  <note>
 
160
   <para>
 
161
    When the client application uses the <quote>extended query</> protocol
 
162
    to issue a <command>FETCH</> command, the Bind protocol message
 
163
    specifies whether data is to be retrieved in text or binary format.
 
164
    This choice overrides the way that the cursor is defined.  The concept
 
165
    of a binary cursor as such is thus obsolete when using extended query
 
166
    protocol &mdash; any cursor can be treated as either text or binary.
 
167
   </para>
 
168
  </note>
 
169
 
 
170
   <para>
 
171
    Unless <literal>WITH HOLD</literal> is specified, the cursor
 
172
    created by this command can only be used within the current
 
173
    transaction.  Thus, <command>DECLARE</> without <literal>WITH
 
174
    HOLD</literal> is useless outside a transaction block: the cursor would
 
175
    survive only to the completion of the statement.  Therefore
 
176
    <productname>PostgreSQL</productname> reports an error if such a
 
177
    command is used outside a transaction block.
 
178
    Use
 
179
    <xref linkend="sql-begin" endterm="sql-begin-title"> and
 
180
    <xref linkend="sql-commit" endterm="sql-commit-title">
 
181
    (or <xref linkend="sql-rollback" endterm="sql-rollback-title">)
 
182
    to define a transaction block.
 
183
   </para>
 
184
 
 
185
   <para>
 
186
    If <literal>WITH HOLD</literal> is specified and the transaction
 
187
    that created the cursor successfully commits, the cursor can
 
188
    continue to be accessed by subsequent transactions in the same
 
189
    session.  (But if the creating transaction is aborted, the cursor
 
190
    is removed.)  A cursor created with <literal>WITH HOLD</literal>
 
191
    is closed when an explicit <command>CLOSE</command> command is
 
192
    issued on it, or the session ends.  In the current implementation,
 
193
    the rows represented by a held cursor are copied into a temporary
 
194
    file or memory area so that they remain available for subsequent
 
195
    transactions.
 
196
   </para>
 
197
 
 
198
   <para>
 
199
    <literal>WITH HOLD</literal> may not be specified when the query
 
200
    includes <literal>FOR UPDATE</> or <literal>FOR SHARE</>.
 
201
   </para>
 
202
 
 
203
   <para>
 
204
    The <literal>SCROLL</> option should be specified when defining a
 
205
    cursor that will be used to fetch backwards.  This is required by
 
206
    the SQL standard.  However, for compatibility with earlier
 
207
    versions, <productname>PostgreSQL</productname> will allow
 
208
    backward fetches without <literal>SCROLL</>, if the cursor's query
 
209
    plan is simple enough that no extra overhead is needed to support
 
210
    it. However, application developers are advised not to rely on
 
211
    using backward fetches from a cursor that has not been created
 
212
    with <literal>SCROLL</literal>.  If <literal>NO SCROLL</> is
 
213
    specified, then backward fetches are disallowed in any case.
 
214
   </para>
 
215
 
 
216
   <para>
 
217
    Backward fetches are also disallowed when the query
 
218
    includes <literal>FOR UPDATE</> or <literal>FOR SHARE</>; therefore
 
219
    <literal>SCROLL</literal> may not be specified in this case.
 
220
   </para>
 
221
 
 
222
   <para>
 
223
    If the cursor's query includes <literal>FOR UPDATE</> or <literal>FOR
 
224
    SHARE</>, then returned rows are locked at the time they are first
 
225
    fetched, in the same way as for a regular
 
226
    <xref linkend="sql-select" endterm="sql-select-title"> command with
 
227
    these options.
 
228
    In addition, the returned rows will be the most up-to-date versions;
 
229
    therefore these options provide the equivalent of what the SQL standard
 
230
    calls a <quote>sensitive cursor</>.  (Specifying <literal>INSENSITIVE</>
 
231
    together with <literal>FOR UPDATE</> or <literal>FOR SHARE</> is an error.)
 
232
   </para>
 
233
 
 
234
   <caution>
 
235
    <para>
 
236
     It is generally recommended to use <literal>FOR UPDATE</> if the cursor
 
237
     is intended to be used with <command>UPDATE ... WHERE CURRENT OF</> or
 
238
     <command>DELETE ... WHERE CURRENT OF</>.  Using <literal>FOR UPDATE</>
 
239
     prevents other sessions from changing the rows between the time they are
 
240
     fetched and the time they are updated.  Without <literal>FOR UPDATE</>,
 
241
     a subsequent <literal>WHERE CURRENT OF</> command will have no effect if
 
242
     the row was changed since the cursor was created.
 
243
    </para>
 
244
 
 
245
    <para>
 
246
     Another reason to use <literal>FOR UPDATE</> is that without it, a
 
247
     subsequent <literal>WHERE CURRENT OF</> might fail if the cursor query
 
248
     does not meet the SQL standard's rules for being <quote>simply
 
249
     updatable</> (in particular, the cursor must reference just one table
 
250
     and not use grouping or <literal>ORDER BY</>).  Cursors
 
251
     that are not simply updatable might work, or might not, depending on plan
 
252
     choice details; so in the worst case, an application might work in testing
 
253
     and then fail in production.
 
254
    </para>
 
255
 
 
256
    <para>
 
257
     The main reason not to use <literal>FOR UPDATE</> with <literal>WHERE
 
258
     CURRENT OF</> is if you need the cursor to be scrollable, or to be
 
259
     insensitive to the subsequent updates (that is, continue to show the old
 
260
     data).  If this is a requirement, pay close heed to the caveats shown
 
261
     above.
 
262
    </para>
 
263
   </caution>
 
264
 
 
265
   <para>
 
266
    The SQL standard only makes provisions for cursors in embedded
 
267
    <acronym>SQL</acronym>.  The <productname>PostgreSQL</productname>
 
268
    server does not implement an <command>OPEN</command> statement for
 
269
    cursors; a cursor is considered to be open when it is declared.
 
270
    However, <application>ECPG</application>, the embedded SQL
 
271
    preprocessor for <productname>PostgreSQL</productname>, supports
 
272
    the standard SQL cursor conventions, including those involving
 
273
    <command>DECLARE</command> and <command>OPEN</command> statements.
 
274
   </para>
 
275
 
 
276
   <para>
 
277
    You can see all available cursors by querying the <link
 
278
    linkend="view-pg-cursors"><structname>pg_cursors</structname></link>
 
279
    system view.
 
280
   </para>
 
281
 </refsect1>
 
282
 
 
283
 <refsect1>
 
284
  <title>Examples</title>
 
285
 
 
286
  <para>
 
287
   To declare a cursor:
 
288
<programlisting>
 
289
DECLARE liahona CURSOR FOR SELECT * FROM films;
 
290
</programlisting>
 
291
   See <xref linkend="sql-fetch" endterm="sql-fetch-title"> for more
 
292
   examples of cursor usage.
 
293
  </para>
 
294
 </refsect1>
 
295
 
 
296
 <refsect1>
 
297
  <title>Compatibility</title>
 
298
 
 
299
  <para>
 
300
   The SQL standard says that it is implementation-dependent whether cursors
 
301
   are sensitive to concurrent updates of the underlying data by default.  In
 
302
   <productname>PostgreSQL</productname>, cursors are insensitive by default,
 
303
   and can be made sensitive by specifying <literal>FOR UPDATE</>.  Other
 
304
   products may work differently.
 
305
  </para>
 
306
 
 
307
  <para>
 
308
   The SQL standard allows cursors only in embedded
 
309
   <acronym>SQL</acronym> and in modules. <productname>PostgreSQL</>
 
310
   permits cursors to be used interactively.
 
311
  </para>
 
312
 
 
313
  <para>
 
314
   Binary cursors are a <productname>PostgreSQL</productname>
 
315
   extension.
 
316
  </para>
 
317
 </refsect1>
 
318
 
 
319
 <refsect1>
 
320
  <title>See Also</title>
 
321
 
 
322
  <simplelist type="inline">
 
323
   <member><xref linkend="sql-close" endterm="sql-close-title"></member>
 
324
   <member><xref linkend="sql-fetch" endterm="sql-fetch-title"></member>
 
325
   <member><xref linkend="sql-move" endterm="sql-move-title"></member>
 
326
  </simplelist>
 
327
 </refsect1>
 
328
</refentry>