<?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><div xmlns="http://www.w3.org/TR/xhtml1/transitional" 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.10. dblink">Up</a></td><th width="60%" align="center">F.10. dblink</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 11.5 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></hr></div><div class="refentry" id="CONTRIB-DBLINK-OPEN"><div class="titlepage"></div><a id="id-1.11.7.19.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.19.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.19.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.19.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.19.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.19.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">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-fetch.html">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">Home</a></td><td width="40%" align="right" valign="top"> dblink_fetch</td></tr></table></div></body></html>
