begriffs open source - ai-pg/blob - full-docs/src/sgml/html/contrib-dblink-function.html

   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</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-disconnect.html" title="dblink_disconnect" /><link rel="next" href="contrib-dblink-exec.html" title="dblink_exec" /></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</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="contrib-dblink-disconnect.html" title="dblink_disconnect">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="dblink.html" title="F.11. dblink — connect to other PostgreSQL databases">Up</a></td><th width="60%" align="center">F.11. dblink — connect to other PostgreSQL databases</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="contrib-dblink-exec.html" title="dblink_exec">Next</a></td></tr></table><hr /></div><div class="refentry" id="CONTRIB-DBLINK-FUNCTION"><div class="titlepage"></div><a id="id-1.11.7.21.10.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">dblink</span></h2><p>dblink — executes a query in a remote database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 dblink(text connname, text sql [, bool fail_on_error]) returns setof record
   4 dblink(text connstr, text sql [, bool fail_on_error]) returns setof record
   5 dblink(text sql [, bool fail_on_error]) returns setof record
   6 </pre></div><div class="refsect1" id="id-1.11.7.21.10.5"><h2>Description</h2><p>
   7     <code class="function">dblink</code> executes a query (usually a <code class="command">SELECT</code>,
   8     but it can be any SQL statement that returns rows) in a remote database.
   9    </p><p>
  10     When two <code class="type">text</code> arguments are given, the first one is first
  11     looked up as a persistent connection's name; if found, the command
  12     is executed on that connection.  If not found, the first argument
  13     is treated as a connection info string as for <code class="function">dblink_connect</code>,
  14     and the indicated connection is made just for the duration of this command.
  15    </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>
  16        Name of the connection to use; omit this parameter to use the
  17        unnamed connection.
  18       </p></dd><dt><span class="term"><em class="parameter"><code>connstr</code></em></span></dt><dd><p>
  19        A connection info string, as previously described for
  20        <code class="function">dblink_connect</code>.
  21       </p></dd><dt><span class="term"><em class="parameter"><code>sql</code></em></span></dt><dd><p>
  22        The SQL query that you wish to execute in the remote database,
  23        for example <code class="literal">select * from foo</code>.
  24       </p></dd><dt><span class="term"><em class="parameter"><code>fail_on_error</code></em></span></dt><dd><p>
  25        If true (the default when omitted) then an error thrown on the
  26        remote side of the connection causes an error to also be thrown
  27        locally. If false, the remote error is locally reported as a NOTICE,
  28        and the function returns no rows.
  29       </p></dd></dl></div></div><div class="refsect1" id="id-1.11.7.21.10.7"><h2>Return Value</h2><p>
  30     The function returns the row(s) produced by the query.  Since
  31     <code class="function">dblink</code> can be used with any query, it is declared
  32     to return <code class="type">record</code>, rather than specifying any particular
  33     set of columns.  This means that you must specify the expected
  34     set of columns in the calling query — otherwise
  35     <span class="productname">PostgreSQL</span> would not know what to expect.
  36     Here is an example:
  37
  38 </p><pre class="programlisting">
  39 SELECT *
  40     FROM dblink('dbname=mydb options=-csearch_path=',
  41                 'select proname, prosrc from pg_proc')
  42       AS t1(proname name, prosrc text)
  43     WHERE proname LIKE 'bytea%';
  44 </pre><p>
  45
  46     The <span class="quote">“<span class="quote">alias</span>”</span> part of the <code class="literal">FROM</code> clause must
  47     specify the column names and types that the function will return.
  48     (Specifying column names in an alias is actually standard SQL
  49     syntax, but specifying column types is a <span class="productname">PostgreSQL</span>
  50     extension.)  This allows the system to understand what
  51     <code class="literal">*</code> should expand to, and what <code class="structname">proname</code>
  52     in the <code class="literal">WHERE</code> clause refers to, in advance of trying
  53     to execute the function.  At run time, an error will be thrown
  54     if the actual query result from the remote database does not
  55     have the same number of columns shown in the <code class="literal">FROM</code> clause.
  56     The column names need not match, however, and <code class="function">dblink</code>
  57     does not insist on exact type matches either.  It will succeed
  58     so long as the returned data strings are valid input for the
  59     column type declared in the <code class="literal">FROM</code> clause.
  60    </p></div><div class="refsect1" id="id-1.11.7.21.10.8"><h2>Notes</h2><p>
  61     A convenient way to use <code class="function">dblink</code> with predetermined
  62     queries is to create a view.
  63     This allows the column type information to be buried in the view,
  64     instead of having to spell it out in every query.  For example,
  65
  66 </p><pre class="programlisting">
  67 CREATE VIEW myremote_pg_proc AS
  68   SELECT *
  69     FROM dblink('dbname=postgres options=-csearch_path=',
  70                 'select proname, prosrc from pg_proc')
  71     AS t1(proname name, prosrc text);
  72
  73 SELECT * FROM myremote_pg_proc WHERE proname LIKE 'bytea%';
  74 </pre></div><div class="refsect1" id="id-1.11.7.21.10.9"><h2>Examples</h2><pre class="screen">
  75 SELECT * FROM dblink('dbname=postgres options=-csearch_path=',
  76                      'select proname, prosrc from pg_proc')
  77   AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
  78   proname   |   prosrc
  79 ------------+------------
  80  byteacat   | byteacat
  81  byteaeq    | byteaeq
  82  bytealt    | bytealt
  83  byteale    | byteale
  84  byteagt    | byteagt
  85  byteage    | byteage
  86  byteane    | byteane
  87  byteacmp   | byteacmp
  88  bytealike  | bytealike
  89  byteanlike | byteanlike
  90  byteain    | byteain
  91  byteaout   | byteaout
  92 (12 rows)
  93
  94 SELECT dblink_connect('dbname=postgres options=-csearch_path=');
  95  dblink_connect
  96 ----------------
  97  OK
  98 (1 row)
  99
 100 SELECT * FROM dblink('select proname, prosrc from pg_proc')
 101   AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
 102   proname   |   prosrc
 103 ------------+------------
 104  byteacat   | byteacat
 105  byteaeq    | byteaeq
 106  bytealt    | bytealt
 107  byteale    | byteale
 108  byteagt    | byteagt
 109  byteage    | byteage
 110  byteane    | byteane
 111  byteacmp   | byteacmp
 112  bytealike  | bytealike
 113  byteanlike | byteanlike
 114  byteain    | byteain
 115  byteaout   | byteaout
 116 (12 rows)
 117
 118 SELECT dblink_connect('myconn', 'dbname=regression options=-csearch_path=');
 119  dblink_connect
 120 ----------------
 121  OK
 122 (1 row)
 123
 124 SELECT * FROM dblink('myconn', 'select proname, prosrc from pg_proc')
 125   AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
 126   proname   |   prosrc
 127 ------------+------------
 128  bytearecv  | bytearecv
 129  byteasend  | byteasend
 130  byteale    | byteale
 131  byteagt    | byteagt
 132  byteage    | byteage
 133  byteane    | byteane
 134  byteacmp   | byteacmp
 135  bytealike  | bytealike
 136  byteanlike | byteanlike
 137  byteacat   | byteacat
 138  byteaeq    | byteaeq
 139  bytealt    | bytealt
 140  byteain    | byteain
 141  byteaout   | byteaout
 142 (14 rows)
 143 </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-disconnect.html" title="dblink_disconnect">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dblink.html" title="F.11. dblink — connect to other PostgreSQL databases">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-dblink-exec.html" title="dblink_exec">Next</a></td></tr><tr><td width="40%" align="left" valign="top">dblink_disconnect </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> dblink_exec</td></tr></table></div></body></html>