221 lines
5.3 KiB
Plaintext
221 lines
5.3 KiB
Plaintext
$PostgreSQL: pgsql/contrib/dblink/doc/cursor,v 1.6 2006/03/11 04:38:29 momjian Exp $
|
|
==================================================================
|
|
Name
|
|
|
|
dblink_open -- Opens a cursor on a remote database
|
|
|
|
Synopsis
|
|
|
|
dblink_open(text cursorname, text sql [, bool fail_on_error])
|
|
dblink_open(text connname, text cursorname, text sql [, bool fail_on_error])
|
|
|
|
Inputs
|
|
|
|
connname
|
|
if three arguments are present, the first is taken as the specific
|
|
connection name to use; otherwise the unnamed connection is assumed
|
|
|
|
cursorname
|
|
|
|
a reference name for the cursor
|
|
|
|
sql
|
|
|
|
sql statement that you wish to execute on the remote host
|
|
e.g. "select * from pg_class"
|
|
|
|
fail_on_error
|
|
|
|
If true (default when not present) then an ERROR thrown on the remote side
|
|
of the connection causes an ERROR to also be thrown locally. If false, the
|
|
remote ERROR is locally treated as a NOTICE, and the return value is set
|
|
to 'ERROR'.
|
|
|
|
Outputs
|
|
|
|
Returns status = "OK"
|
|
|
|
Note
|
|
1) dblink_connect(text connstr) must be executed first
|
|
2) dblink_open starts an explicit transaction. If, after using dblink_open,
|
|
you use dblink_exec to change data, and then an error occurs or you use
|
|
dblink_disconnect without a dblink_close first, your change *will* be
|
|
lost. Also, using dblink_close explicitly ends the transaction and thus
|
|
effectively closes *all* open cursors.
|
|
|
|
Example usage
|
|
|
|
test=# select dblink_connect('dbname=postgres');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select dblink_open('foo','select proname, prosrc from pg_proc');
|
|
dblink_open
|
|
-------------
|
|
OK
|
|
(1 row)
|
|
|
|
==================================================================
|
|
Name
|
|
|
|
dblink_fetch -- Returns a set from an open cursor on a remote database
|
|
|
|
Synopsis
|
|
|
|
dblink_fetch(text cursorname, int32 howmany [, bool fail_on_error])
|
|
dblink_fetch(text connname, text cursorname, int32 howmany [, bool fail_on_error])
|
|
|
|
Inputs
|
|
|
|
connname
|
|
if three arguments are present, the first is taken as the specific
|
|
connection name to use; otherwise the unnamed connection is assumed
|
|
|
|
cursorname
|
|
|
|
The reference name for the cursor
|
|
|
|
howmany
|
|
|
|
Maximum number of rows to retrieve. The next howmany rows are fetched,
|
|
starting at the current cursor position, moving forward. Once the cursor
|
|
has positioned to the end, no more rows are produced.
|
|
|
|
fail_on_error
|
|
|
|
If true (default when not present) then an ERROR thrown on the remote side
|
|
of the connection causes an ERROR to also be thrown locally. If false, the
|
|
remote ERROR is locally treated as a NOTICE, and no rows are returned.
|
|
|
|
Outputs
|
|
|
|
Returns setof record
|
|
|
|
Note
|
|
|
|
On a mismatch between the number of return fields as specified in the FROM
|
|
clause, and the actual number of fields returned by the remote cursor, an
|
|
ERROR will be thrown. In this event, the remote cursor is still advanced
|
|
by as many rows as it would have been if the ERROR had not occurred.
|
|
|
|
Example usage
|
|
|
|
test=# select dblink_connect('dbname=postgres');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select dblink_open('foo','select proname, prosrc from pg_proc where proname like ''bytea%''');
|
|
dblink_open
|
|
-------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select * from dblink_fetch('foo',5) as (funcname name, source text);
|
|
funcname | source
|
|
----------+----------
|
|
byteacat | byteacat
|
|
byteacmp | byteacmp
|
|
byteaeq | byteaeq
|
|
byteage | byteage
|
|
byteagt | byteagt
|
|
(5 rows)
|
|
|
|
test=# select * from dblink_fetch('foo',5) as (funcname name, source text);
|
|
funcname | source
|
|
-----------+-----------
|
|
byteain | byteain
|
|
byteale | byteale
|
|
bytealike | bytealike
|
|
bytealt | bytealt
|
|
byteane | byteane
|
|
(5 rows)
|
|
|
|
test=# select * from dblink_fetch('foo',5) as (funcname name, source text);
|
|
funcname | source
|
|
------------+------------
|
|
byteanlike | byteanlike
|
|
byteaout | byteaout
|
|
(2 rows)
|
|
|
|
test=# select * from dblink_fetch('foo',5) as (funcname name, source text);
|
|
funcname | source
|
|
----------+--------
|
|
(0 rows)
|
|
|
|
==================================================================
|
|
Name
|
|
|
|
dblink_close -- Closes a cursor on a remote database
|
|
|
|
Synopsis
|
|
|
|
dblink_close(text cursorname [, bool fail_on_error])
|
|
dblink_close(text connname, text cursorname [, bool fail_on_error])
|
|
|
|
Inputs
|
|
|
|
connname
|
|
if two arguments are present, the first is taken as the specific
|
|
connection name to use; otherwise the unnamed connection is assumed
|
|
|
|
cursorname
|
|
|
|
a reference name for the cursor
|
|
|
|
fail_on_error
|
|
|
|
If true (default when not present) then an ERROR thrown on the remote side
|
|
of the connection causes an ERROR to also be thrown locally. If false, the
|
|
remote ERROR is locally treated as a NOTICE, and the return value is set
|
|
to 'ERROR'.
|
|
|
|
Outputs
|
|
|
|
Returns status = "OK"
|
|
|
|
Note
|
|
dblink_connect(text connstr) or dblink_connect(text connname, text connstr)
|
|
must be executed first.
|
|
|
|
Example usage
|
|
|
|
test=# select dblink_connect('dbname=postgres');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select dblink_open('foo','select proname, prosrc from pg_proc');
|
|
dblink_open
|
|
-------------
|
|
OK
|
|
(1 row)
|
|
|
|
test=# select dblink_close('foo');
|
|
dblink_close
|
|
--------------
|
|
OK
|
|
(1 row)
|
|
|
|
select dblink_connect('myconn','dbname=regression');
|
|
dblink_connect
|
|
----------------
|
|
OK
|
|
(1 row)
|
|
|
|
select dblink_open('myconn','foo','select proname, prosrc from pg_proc');
|
|
dblink_open
|
|
-------------
|
|
OK
|
|
(1 row)
|
|
|
|
select dblink_close('myconn','foo');
|
|
dblink_close
|
|
--------------
|
|
OK
|
|
(1 row)
|