Home Explore Blog CI



postgresql

9th chunk of `doc/src/sgml/dblink.sgml`
97c110e1196d5816b0cf52d047434759d7987236f49f908c0000000100000fa3
 <literal>OK</literal> or <literal>ERROR</literal>.
   </para>
  </refsect1>

  <refsect1>
   <title>Notes</title>

   <para>
    Since a cursor can only persist within a transaction,
    <function>dblink_open</function> starts an explicit transaction block
    (<command>BEGIN</command>) on the remote side, if the remote side was
    not already within a transaction.  This transaction will be
    closed again when the matching <function>dblink_close</function> is
    executed.  Note that if
    you use <function>dblink_exec</function> to change data between
    <function>dblink_open</function> and <function>dblink_close</function>,
    and then an error occurs or you use <function>dblink_disconnect</function> before
    <function>dblink_close</function>, your change <emphasis>will be
    lost</emphasis> because the transaction will be aborted.
   </para>
  </refsect1>

  <refsect1>
   <title>Examples</title>

<screen>
SELECT dblink_connect('dbname=postgres options=-csearch_path=');
 dblink_connect
----------------
 OK
(1 row)

SELECT dblink_open('foo', 'select proname, prosrc from pg_proc');
 dblink_open
-------------
 OK
(1 row)
</screen>
  </refsect1>
 </refentry>

 <refentry id="contrib-dblink-fetch">
  <indexterm>
   <primary>dblink_fetch</primary>
  </indexterm>

  <refmeta>
   <refentrytitle>dblink_fetch</refentrytitle>
   <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
   <refname>dblink_fetch</refname>
   <refpurpose>returns rows from an open cursor in a remote database</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
<synopsis>
dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) returns setof record
dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) returns setof record
</synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_fetch</function> fetches rows from a cursor previously
    established by <function>dblink_open</function>.
   </para>
  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>connname</parameter></term>
     <listitem>
      <para>
       Name of the connection to use; omit this parameter to use the
       unnamed connection.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>cursorname</parameter></term>
     <listitem>
      <para>
       The name of the cursor to fetch from.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>howmany</parameter></term>
     <listitem>
      <para>
       The maximum number of rows to retrieve. The next <parameter>howmany</parameter>
       rows are fetched, starting at the current cursor position, moving
       forward. Once the cursor has reached its end, no more rows are produced.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>fail_on_error</parameter></term>
     <listitem>
      <para>
       If true (the default when omitted) 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 reported as a NOTICE,
       and the function returns no rows.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

  <refsect1>
   <title>Return Value</title>

   <para>
    The function returns the row(s) fetched from the cursor.  To use this
    function, you will need to specify the expected set of columns,
    as previously discussed for <function>dblink</function>.
   </para>
  </refsect1>

  <refsect1>
   <title>Notes</title>

   <para>
    On a mismatch between the number of return columns specified in the
    <literal>FROM</literal> clause, and the actual number of columns 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.  The

Title: dblink_fetch: Retrieving Rows from a Remote Cursor
Summary
This section describes the `dblink_fetch` function, which is used to retrieve rows from a cursor that was previously opened in a remote database using `dblink_open`. The function fetches a specified number of rows starting from the current cursor position. The section details the function's syntax, arguments (`connname`, `cursorname`, `howmany`, and `fail_on_error`), and how to specify the expected set of columns for the returned rows. It also notes that mismatches between the number of specified return columns and the actual number of columns returned by the remote cursor will result in an error.