postgresql/contrib/dblink/doc/cursor

==================================================================
Name

dblink_open -- Opens a cursor on a remote database

Synopsis

dblink_open(text cursorname, text sql)
dblink_open(text connname, text cursorname, text sql)

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"

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=template1');
 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)
dblink_fetch(text connname, text cursorname, int32 howmany)

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.

Outputs

  Returns setof record

Example usage

test=# select dblink_connect('dbname=template1');
 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)
dblink_close(text connname, text cursorname)

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

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=template1');
 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)