← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to contrib/dblink/doc/cursor

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
contrib/dblink/doc/cursor
 
1
==================================================================
 
2
Name
 
3
 
 
4
dblink_open -- Opens a cursor on a remote database
 
5
 
 
6
Synopsis
 
7
 
 
8
dblink_open(text cursorname, text sql [, bool fail_on_error])
 
9
dblink_open(text connname, text cursorname, text sql [, bool fail_on_error])
 
10
 
 
11
Inputs
 
12
 
 
13
  connname
 
14
    if three arguments are present, the first is taken as the specific
 
15
    connection name to use; otherwise the unnamed connection is assumed
 
16
 
 
17
  cursorname
 
18
 
 
19
    a reference name for the cursor
 
20
 
 
21
  sql
 
22
 
 
23
    sql statement that you wish to execute on the remote host
 
24
    e.g. "select * from pg_class"
 
25
 
 
26
  fail_on_error
 
27
 
 
28
    If true (default when not present) then an ERROR thrown on the remote side
 
29
    of the connection causes an ERROR to also be thrown locally. If false, the
 
30
    remote ERROR is locally treated as a NOTICE, and the return value is set
 
31
    to 'ERROR'.
 
32
 
 
33
Outputs
 
34
 
 
35
  Returns status = "OK"
 
36
 
 
37
Note
 
38
  1) dblink_connect(text connstr) must be executed first
 
39
  2) dblink_open starts an explicit transaction. If, after using dblink_open,
 
40
     you use dblink_exec to change data, and then an error occurs or you use
 
41
     dblink_disconnect without a dblink_close first, your change *will* be
 
42
     lost. Also, using dblink_close explicitly ends the transaction and thus
 
43
     effectively closes *all* open cursors.
 
44
 
 
45
Example usage
 
46
 
 
47
test=# select dblink_connect('dbname=template1');
 
48
 dblink_connect
 
49
----------------
 
50
 OK
 
51
(1 row)
 
52
 
 
53
test=# select dblink_open('foo','select proname, prosrc from pg_proc');
 
54
 dblink_open
 
55
-------------
 
56
 OK
 
57
(1 row)
 
58
 
 
59
==================================================================
 
60
Name
 
61
 
 
62
dblink_fetch -- Returns a set from an open cursor on a remote database
 
63
 
 
64
Synopsis
 
65
 
 
66
dblink_fetch(text cursorname, int32 howmany [, bool fail_on_error])
 
67
dblink_fetch(text connname, text cursorname, int32 howmany [, bool fail_on_error])
 
68
 
 
69
Inputs
 
70
 
 
71
  connname
 
72
    if three arguments are present, the first is taken as the specific
 
73
    connection name to use; otherwise the unnamed connection is assumed
 
74
 
 
75
  cursorname
 
76
 
 
77
    The reference name for the cursor
 
78
 
 
79
  howmany
 
80
 
 
81
    Maximum number of rows to retrieve. The next howmany rows are fetched,
 
82
    starting at the current cursor position, moving forward. Once the cursor
 
83
    has positioned to the end, no more rows are produced.
 
84
 
 
85
  fail_on_error
 
86
 
 
87
    If true (default when not present) then an ERROR thrown on the remote side
 
88
    of the connection causes an ERROR to also be thrown locally. If false, the
 
89
    remote ERROR is locally treated as a NOTICE, and no rows are returned.
 
90
 
 
91
Outputs
 
92
 
 
93
  Returns setof record
 
94
 
 
95
Example usage
 
96
 
 
97
test=# select dblink_connect('dbname=template1');
 
98
 dblink_connect
 
99
----------------
 
100
 OK
 
101
(1 row)
 
102
 
 
103
test=# select dblink_open('foo','select proname, prosrc from pg_proc where proname like ''bytea%''');
 
104
 dblink_open
 
105
-------------
 
106
 OK
 
107
(1 row)
 
108
 
 
109
test=# select * from dblink_fetch('foo',5) as (funcname name, source text);
 
110
 funcname |  source
 
111
----------+----------
 
112
 byteacat | byteacat
 
113
 byteacmp | byteacmp
 
114
 byteaeq  | byteaeq
 
115
 byteage  | byteage
 
116
 byteagt  | byteagt
 
117
(5 rows)
 
118
 
 
119
test=# select * from dblink_fetch('foo',5) as (funcname name, source text);
 
120
 funcname  |  source
 
121
-----------+-----------
 
122
 byteain   | byteain
 
123
 byteale   | byteale
 
124
 bytealike | bytealike
 
125
 bytealt   | bytealt
 
126
 byteane   | byteane
 
127
(5 rows)
 
128
 
 
129
test=# select * from dblink_fetch('foo',5) as (funcname name, source text);
 
130
  funcname  |   source
 
131
------------+------------
 
132
 byteanlike | byteanlike
 
133
 byteaout   | byteaout
 
134
(2 rows)
 
135
 
 
136
test=# select * from dblink_fetch('foo',5) as (funcname name, source text);
 
137
 funcname | source
 
138
----------+--------
 
139
(0 rows)
 
140
 
 
141
==================================================================
 
142
Name
 
143
 
 
144
dblink_close -- Closes a cursor on a remote database
 
145
 
 
146
Synopsis
 
147
 
 
148
dblink_close(text cursorname [, bool fail_on_error])
 
149
dblink_close(text connname, text cursorname [, bool fail_on_error])
 
150
 
 
151
Inputs
 
152
 
 
153
  connname
 
154
    if two arguments are present, the first is taken as the specific
 
155
    connection name to use; otherwise the unnamed connection is assumed
 
156
 
 
157
  cursorname
 
158
 
 
159
    a reference name for the cursor
 
160
 
 
161
  fail_on_error
 
162
 
 
163
    If true (default when not present) then an ERROR thrown on the remote side
 
164
    of the connection causes an ERROR to also be thrown locally. If false, the
 
165
    remote ERROR is locally treated as a NOTICE, and the return value is set
 
166
    to 'ERROR'.
 
167
 
 
168
Outputs
 
169
 
 
170
  Returns status = "OK"
 
171
 
 
172
Note
 
173
  dblink_connect(text connstr) or dblink_connect(text connname, text connstr)
 
174
  must be executed first.
 
175
 
 
176
Example usage
 
177
 
 
178
test=# select dblink_connect('dbname=template1');
 
179
 dblink_connect
 
180
----------------
 
181
 OK
 
182
(1 row)
 
183
 
 
184
test=# select dblink_open('foo','select proname, prosrc from pg_proc');
 
185
 dblink_open
 
186
-------------
 
187
 OK
 
188
(1 row)
 
189
 
 
190
test=# select dblink_close('foo');
 
191
 dblink_close
 
192
--------------
 
193
 OK
 
194
(1 row)
 
195
 
 
196
select dblink_connect('myconn','dbname=regression');
 
197
 dblink_connect
 
198
----------------
 
199
 OK
 
200
(1 row)
 
201
 
 
202
select dblink_open('myconn','foo','select proname, prosrc from pg_proc');
 
203
 dblink_open
 
204
-------------
 
205
 OK
 
206
(1 row)
 
207
 
 
208
select dblink_close('myconn','foo');
 
209
 dblink_close
 
210
--------------
 
211
 OK
 
212
(1 row)