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

dblink_open -- Opens a cursor on a remote database

Synopsis

dblink_open(text cursorname, text sql)

Inputs

  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)

Inputs

  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

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=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)

Inputs

  cursorname

    a reference name for the cursor

Outputs

  Returns status = "OK"

Note
  dblink_connect(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)

