codekingpro/portable-devtools

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!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 — connect to other PostgreSQL databases">Up</a></td><th width="60%" align="center">F.12. dblink — connect to other PostgreSQL databases</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 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.22.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">3dblink_open(text cursorname, text sql [, bool fail_on_error]) returns text4dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) returns text5</pre></div><div class="refsect1" id="id-1.11.7.22.10.5"><h2>Description</h2><p>6    <code class="function">dblink_open()</code> opens a cursor in a remote database.7    The cursor can subsequently be manipulated with8    <code class="function">dblink_fetch()</code> and <code class="function">dblink_close()</code>.9   </p></div><div class="refsect1" id="id-1.11.7.22.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>10       Name of the connection to use; omit this parameter to use the11       unnamed connection.12      </p></dd><dt><span class="term"><em class="parameter"><code>cursorname</code></em></span></dt><dd><p>13       The name to assign to this cursor.14      </p></dd><dt><span class="term"><em class="parameter"><code>sql</code></em></span></dt><dd><p>15       The <code class="command">SELECT</code> statement that you wish to execute in the remote16       database, for example <code class="literal">select * from pg_class</code>.17      </p></dd><dt><span class="term"><em class="parameter"><code>fail_on_error</code></em></span></dt><dd><p>18       If true (the default when omitted) then an error thrown on the19       remote side of the connection causes an error to also be thrown20       locally. If false, the remote error is locally reported as a NOTICE,21       and the function's return value is set to <code class="literal">ERROR</code>.22      </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.22.10.7"><h2>Return Value</h2><p>23    Returns status, either <code class="literal">OK</code> or <code class="literal">ERROR</code>.24   </p></div><div class="refsect1" id="id-1.11.7.22.10.8"><h2>Notes</h2><p>25    Since a cursor can only persist within a transaction,26    <code class="function">dblink_open</code> starts an explicit transaction block27    (<code class="command">BEGIN</code>) on the remote side, if the remote side was28    not already within a transaction.  This transaction will be29    closed again when the matching <code class="function">dblink_close</code> is30    executed.  Note that if31    you use <code class="function">dblink_exec</code> to change data between32    <code class="function">dblink_open</code> and <code class="function">dblink_close</code>,33    and then an error occurs or you use <code class="function">dblink_disconnect</code> before34    <code class="function">dblink_close</code>, your change <span class="emphasis"><em>will be35    lost</em></span> because the transaction will be aborted.36   </p></div><div class="refsect1" id="id-1.11.7.22.10.9"><h2>Examples</h2><pre class="screen">37SELECT dblink_connect('dbname=postgres options=-csearch_path=');38 dblink_connect39----------------40 OK41(1 row)42 43SELECT dblink_open('foo', 'select proname, prosrc from pg_proc');44 dblink_open45-------------46 OK47(1 row)48</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 — connect to other PostgreSQL databases">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 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_fetch</td></tr></table></div></body></html>