summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/contrib-dblink-open.html
blob: c2e22ed2b4081e8f9172c06aa4b3b9c425ecbd13 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>dblink_open</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="contrib-dblink-exec.html" title="dblink_exec" /><link rel="next" href="contrib-dblink-fetch.html" title="dblink_fetch" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">dblink_open</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-exec.html" title="dblink_exec">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><th width="60%" align="center">F.12. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.7 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-fetch.html" title="dblink_fetch">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-OPEN"><div class="titlepage"></div><a id="id-1.11.7.21.10.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink_open</span></h2><p>dblink_open — opens a cursor in a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
dblink_open(text cursorname, text sql [, bool fail_on_error]) returns text
dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) returns text
</pre></div><div class="refsect1" id="id-1.11.7.21.10.5"><h2>Description</h2><p>
    <code class="function">dblink_open()</code> opens a cursor in a remote database.
    The cursor can subsequently be manipulated with
    <code class="function">dblink_fetch()</code> and <code class="function">dblink_close()</code>.
   </p></div><div class="refsect1" id="id-1.11.7.21.10.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connname</code></em></span></dt><dd><p>
       Name of the connection to use; omit this parameter to use the
       unnamed connection.
      </p></dd><dt><span class="term"><em class="parameter"><code>cursorname</code></em></span></dt><dd><p>
       The name to assign to this cursor.
      </p></dd><dt><span class="term"><em class="parameter"><code>sql</code></em></span></dt><dd><p>
       The <code class="command">SELECT</code> statement that you wish to execute in the remote
       database, for example <code class="literal">select * from pg_class</code>.
      </p></dd><dt><span class="term"><em class="parameter"><code>fail_on_error</code></em></span></dt><dd><p>
       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's return value is set to <code class="literal">ERROR</code>.
      </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.10.7"><h2>Return Value</h2><p>
    Returns status, either <code class="literal">OK</code> or <code class="literal">ERROR</code>.
   </p></div><div class="refsect1" id="id-1.11.7.21.10.8"><h2>Notes</h2><p>
    Since a cursor can only persist within a transaction,
    <code class="function">dblink_open</code> starts an explicit transaction block
    (<code class="command">BEGIN</code>) on the remote side, if the remote side was
    not already within a transaction.  This transaction will be
    closed again when the matching <code class="function">dblink_close</code> is
    executed.  Note that if
    you use <code class="function">dblink_exec</code> to change data between
    <code class="function">dblink_open</code> and <code class="function">dblink_close</code>,
    and then an error occurs or you use <code class="function">dblink_disconnect</code> before
    <code class="function">dblink_close</code>, your change <span class="emphasis"><em>will be
    lost</em></span> because the transaction will be aborted.
   </p></div><div class="refsect1" id="id-1.11.7.21.10.9"><h2>Examples</h2><pre class="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)
</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contrib-dblink-exec.html" title="dblink_exec">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.12. dblink">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-fetch.html" title="dblink_fetch">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_exec </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.7 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_fetch</td></tr></table></div></body></html>