postgresql/contrib/dblink/doc/cursor

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