<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>
    If untrusted users have access to a database that has not adopted a
    <link linkend="ddl-schemas-patterns">secure schema usage pattern</link>,
    begin each session by removing publicly-writable schemas from
    <varname>search_path</varname>.  One could, for example,
    add <literal>options=-csearch_path=</literal> to
    <parameter>connstr</parameter>.  This consideration is not specific
    to <filename>dblink</filename>; it applies to every interface for
    executing arbitrary SQL commands.
   </para>

   <para>
    The foreign-data wrapper <filename>dblink_fdw</filename> has an additional
    Boolean option <literal>use_scram_passthrough</literal> that controls
    whether <filename>dblink</filename> will use the SCRAM pass-through
    authentication to connect to the remote database.  With SCRAM pass-through
    authentication, <filename>dblink</filename> uses SCRAM-hashed secrets
    instead of plain-text user passwords to connect to the remote server. This
    avoids storing plain-text user passwords in PostgreSQL system catalogs.
    See the documentation of the equivalent <link
    linkend="postgres-fdw-option-use-scram-passthrough"><literal>use_scram_passthrough</literal></link>
    option of postgres_fdw for further details and restrictions.
   </para>

   <para>
    Only superusers may use <function>dblink_connect</function> to create
    connections that use neither password authentication, SCRAM pass-through,
    nor GSSAPI-authentication.
    If non-superusers need this capability, use
    <function>dblink_connect_u</function> instead.
   </para>

   <para>
    It is unwise to choose connection names that contain equal signs,
    as this opens a risk of confusion with connection info strings
    in other <filename>dblink</filename> functions.
   </para>
  </refsect1>

  <refsect1>
   <title>Examples</title>

<screen>
SELECT dblink_connect('dbname=postgres options=-csearch_path=');
 dblink_connect
----------------
 OK
(1 row)

SELECT dblink_connect('myconn', 'dbname=postgres options=-csearch_path=');
 dblink_connect
----------------
 OK
(1 row)

-- FOREIGN DATA WRAPPER functionality
-- Note: local connections that don't use SCRAM pass-through require password
--       authentication for this to work properly. Otherwise, you will receive
--       the following error from dblink_connect():
--       ERROR:  password is required
--       DETAIL:  Non-superuser cannot connect if the server does not request a password.
--       HINT:  Target server's authentication method must be changed.

CREATE SERVER fdtest FOREIGN DATA WRAPPER dblink_fdw OPTIONS (hostaddr '127.0.0.1', dbname 'contrib_regression');

CREATE USER regress_dblink_user WITH PASSWORD 'secret';
CREATE USER MAPPING FOR regress_dblink_user SERVER fdtest OPTIONS (user 'regress_dblink_user', password 'secret');
GRANT USAGE ON FOREIGN SERVER fdtest TO regress_dblink_user;
GRANT SELECT ON TABLE foo TO regress_dblink_user;

\set ORIGINAL_USER