<!-- doc/src/sgml/dblink.sgml -->

<sect1 id="dblink" xreflabel="dblink">
 <title>dblink &mdash; connect to other PostgreSQL databases</title>

 <indexterm zone="dblink">
  <primary>dblink</primary>
 </indexterm>

 <para>
  <filename>dblink</filename> is a module that supports connections to
  other <productname>PostgreSQL</productname> databases from within a database
  session.
 </para>

 <para>
  <filename>dblink</filename> can report the following wait events under the wait
  event type <literal>Extension</literal>.
 </para>

 <variablelist>
  <varlistentry>
   <term><literal>DblinkConnect</literal></term>
   <listitem>
    <para>
     Waiting to establish a connection to a remote server.
    </para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term><literal>DblinkGetConnect</literal></term>
   <listitem>
    <para>
     Waiting to establish a connection to a remote server when it could not
     be found in the list of already-opened connections.
    </para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term><literal>DblinkGetResult</literal></term>
   <listitem>
    <para>
     Waiting to receive the results of a query from a remote server.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>

 <para>
  See also <xref linkend="postgres-fdw"/>, which provides roughly the same
  functionality using a more modern and standards-compliant infrastructure.
 </para>

 <refentry id="contrib-dblink-connect">
  <indexterm>
   <primary>dblink_connect</primary>
  </indexterm>

  <refmeta>
   <refentrytitle>dblink_connect</refentrytitle>
   <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
   <refname>dblink_connect</refname>
   <refpurpose>opens a persistent connection to a remote database</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
<synopsis>
dblink_connect(text connstr) returns text
dblink_connect(text connname, text connstr) returns text
</synopsis>
  </refsynopsisdiv>

  <refsect1>
   <title>Description</title>

   <para>
    <function>dblink_connect()</function> establishes a connection to a remote
    <productname>PostgreSQL</productname> database.  The server and database to
    be contacted are identified through a standard <application>libpq</application>
    connection string.  Optionally, a name can be assigned to the
    connection.  Multiple named connections can be open at once, but
    only one unnamed connection is permitted at a time.  The connection
    will persist until closed or until the database session is ended.
   </para>

   <para>
    The connection string may also be the name of an existing foreign
    server.  It is recommended to use the foreign-data wrapper
    <literal>dblink_fdw</literal> when defining the foreign
    server.  See the example below, as well as
    <xref linkend="sql-createserver"/> and
    <xref linkend="sql-createusermapping"/>.
   </para>

  </refsect1>

  <refsect1>
   <title>Arguments</title>

   <variablelist>
    <varlistentry>
     <term><parameter>connname</parameter></term>
     <listitem>
      <para>
       The name to use for this connection; if omitted, an unnamed
       connection is opened, replacing any existing unnamed connection.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><parameter>connstr</parameter></term>
     <listitem>
      <para><application>libpq</application>-style connection info string, for example
       <literal>hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres
       password=mypasswd options=-csearch_path=</literal>.
       For details see <xref linkend="libpq-connstring"/>.
       Alternatively, the name of a foreign server.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>

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

   <para>
    Returns status, which is always <literal>OK</literal> (since any error
    causes the function to throw an error instead of returning).
   </para>
  </refsect1>

  <refsect1>
   <title>Notes</title>

   <para>