pgsql/doc/src/sgml/html/libpq-connect.html - master - Ao/MaxReport

pgsql/doc/src/sgml/html/libpq-connect.html
1 468 строк113 KB
AoAnima
first_commit
13 июл 2026, 17:47
13 июл 2026, 17:47f1a670a
<?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>32.1. Database Connection Control Functions</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="libpq.html" title="Chapter 32. libpq — C Library" /><link rel="next" href="libpq-status.html" title="32.2. Connection Status Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.1. Database Connection Control Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 32. libpq — C Library">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-status.html" title="32.2. Connection Status Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-CONNECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.1. Database Connection Control Functions <a href="#LIBPQ-CONNECT" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-CONNSTRING">32.1.1. Connection Strings</a></span></dt><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">32.1.2. Parameter Key Words</a></span></dt></dl></div><p>
   The following functions deal with making a connection to a
   <span class="productname">PostgreSQL</span> backend server.  An
   application program can have several backend connections open at
   one time.  (One reason to do that is to access more than one
   database.)  Each connection is represented by a
   <code class="structname">PGconn</code><a id="id-1.7.3.8.2.3" class="indexterm"></a> object, which
   is obtained from the function <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>,
   <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, or
   <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a>.  Note that these functions will always
   return a non-null object pointer, unless perhaps there is too
   little memory even to allocate the <code class="structname">PGconn</code> object.
   The <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a> function should be called to check
   the return value for a successful connection before queries are sent
   via the connection object.

   </p><div class="warning"><h3 class="title">Warning</h3><p>
     If untrusted users have access to a database that has not adopted a
     <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.10.6. Usage Patterns">secure schema usage pattern</a>,
     begin each session by removing publicly-writable schemas from
     <code class="varname">search_path</code>.  One can set parameter key
     word <code class="literal">options</code> to
     value <code class="literal">-csearch_path=</code>.  Alternately, one can
     issue <code class="literal">PQexec(<em class="replaceable"><code>conn</code></em>, "SELECT
     pg_catalog.set_config('search_path', '', false)")</code> after
     connecting.  This consideration is not specific
     to <span class="application">libpq</span>; it applies to every interface for
     executing arbitrary SQL commands.
    </p></div><p>

   </p><div class="warning"><h3 class="title">Warning</h3><p>
     On Unix, forking a process with open libpq connections can lead to
     unpredictable results because the parent and child processes share
     the same sockets and operating system resources.  For this reason,
     such usage is not recommended, though doing an <code class="function">exec</code> from
     the child process to load a new executable is safe.
    </p></div><p>

   </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCONNECTDBPARAMS"><span class="term"><code class="function">PQconnectdbParams</code><a id="id-1.7.3.8.2.11.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTDBPARAMS" class="id_link">#</a></dt><dd><p>
       Makes a new connection to the database server.

</p><pre class="synopsis">
PGconn *PQconnectdbParams(const char * const *keywords,
                          const char * const *values,
                          int expand_dbname);
</pre><p>
      </p><p>
       This function opens a new database connection using the parameters taken
       from two <code class="symbol">NULL</code>-terminated arrays. The first,
       <code class="literal">keywords</code>, is defined as an array of strings, each one
       being a key word. The second, <code class="literal">values</code>, gives the value
       for each key word. Unlike <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> below, the parameter
       set can be extended without changing the function signature, so use of
       this function (or its nonblocking analogs <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>
       and <code class="function">PQconnectPoll</code>) is preferred for new application
       programming.
      </p><p>
       The currently recognized parameter key words are listed in
       <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="32.1.2. Parameter Key Words">Section 32.1.2</a>.
      </p><p>
       The passed arrays can be empty to use all default parameters, or can
       contain one or more parameter settings. They must be matched in length.
       Processing will stop at the first <code class="symbol">NULL</code> entry
       in the <code class="literal">keywords</code> array.
       Also, if the <code class="literal">values</code> entry associated with a
       non-<code class="symbol">NULL</code> <code class="literal">keywords</code> entry is
       <code class="symbol">NULL</code> or an empty string, that entry is ignored and
       processing continues with the next pair of array entries.
      </p><p>
       When <code class="literal">expand_dbname</code> is non-zero, the value for
       the first <em class="parameter"><code>dbname</code></em> key word is checked to see
       if it is a <em class="firstterm">connection string</em>.  If so, it
       is <span class="quote">“<span class="quote">expanded</span>”</span> into the individual connection
       parameters extracted from the string.  The value is considered to
       be a connection string, rather than just a database name, if it
       contains an equal sign (<code class="literal">=</code>) or it begins with a
       URI scheme designator.  (More details on connection string formats
       appear in <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">Section 32.1.1</a>.)  Only the first
       occurrence of <em class="parameter"><code>dbname</code></em> is treated in this way;
       any subsequent <em class="parameter"><code>dbname</code></em> parameter is processed
       as a plain database name.
      </p><p>
       In general the parameter arrays are processed from start to end.
       If any key word is repeated, the last value (that is
       not <code class="symbol">NULL</code> or empty) is used.  This rule applies in
       particular when a key word found in a connection string conflicts
       with one appearing in the <code class="literal">keywords</code> array.  Thus,
       the programmer may determine whether array entries can override or
       be overridden by values taken from a connection string.  Array
       entries appearing before an expanded <em class="parameter"><code>dbname</code></em>
       entry can be overridden by fields of the connection string, and in
       turn those fields are overridden by array entries appearing
       after <em class="parameter"><code>dbname</code></em> (but, again, only if those
       entries supply non-empty values).
      </p><p>
       After processing all the array entries and any expanded connection
       string, any connection parameters that remain unset are filled with
       default values.  If an unset parameter's corresponding environment
       variable (see <a class="xref" href="libpq-envars.html" title="32.15. Environment Variables">Section 32.15</a>) is set, its value is
       used.  If the environment variable is not set either, then the
       parameter's built-in default value is used.
      </p></dd><dt id="LIBPQ-PQCONNECTDB"><span class="term"><code class="function">PQconnectdb</code><a id="id-1.7.3.8.2.11.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTDB" class="id_link">#</a></dt><dd><p>
       Makes a new connection to the database server.

</p><pre class="synopsis">
PGconn *PQconnectdb(const char *conninfo);
</pre><p>
      </p><p>
       This function opens a new database connection using the parameters taken
       from the string <code class="literal">conninfo</code>.
      </p><p>
       The passed string can be empty to use all default parameters, or it can
       contain one or more parameter settings separated by whitespace,
       or it can contain a <acronym class="acronym">URI</acronym>.
       See <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">Section 32.1.1</a> for details.
     </p></dd><dt id="LIBPQ-PQSETDBLOGIN"><span class="term"><code class="function">PQsetdbLogin</code><a id="id-1.7.3.8.2.11.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETDBLOGIN" class="id_link">#</a></dt><dd><p>
       Makes a new connection to the database server.
</p><pre class="synopsis">
PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);
</pre><p>
       </p><p>
        This is the predecessor of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> with a fixed
        set of parameters.  It has the same functionality except that the
        missing parameters will always take on default values.  Write <code class="symbol">NULL</code> or an
        empty string for any one of the fixed parameters that is to be defaulted.
      </p><p>
        If the <em class="parameter"><code>dbName</code></em> contains
        an <code class="symbol">=</code> sign or has a valid connection <acronym class="acronym">URI</acronym> prefix, it
        is taken as a <em class="parameter"><code>conninfo</code></em> string in exactly the same way as
        if it had been passed to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and the remaining
        parameters are then applied as specified for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>.
      </p><p>
        <code class="literal">pgtty</code> is no longer used and any value passed will
        be ignored.
      </p></dd><dt id="LIBPQ-PQSETDB"><span class="term"><code class="function">PQsetdb</code><a id="id-1.7.3.8.2.11.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETDB" class="id_link">#</a></dt><dd><p>
   Makes a new connection to the database server.
</p><pre class="synopsis">
PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);
</pre><p>
     </p><p>
      This is a macro that calls <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> with null pointers
      for the <em class="parameter"><code>login</code></em> and <em class="parameter"><code>pwd</code></em> parameters.  It is provided
      for backward compatibility with very old programs.
     </p></dd><dt id="LIBPQ-PQCONNECTSTARTPARAMS"><span class="term"><code class="function">PQconnectStartParams</code><a id="id-1.7.3.8.2.11.5.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQconnectStart</code><a id="id-1.7.3.8.2.11.5.2.2" class="indexterm"></a><br /></span><span class="term" id="LIBPQ-PQCONNECTPOLL"><code class="function">PQconnectPoll</code><a id="id-1.7.3.8.2.11.5.3.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTSTARTPARAMS" class="id_link">#</a></dt><dd><p>
       <a id="id-1.7.3.8.2.11.5.4.1.1" class="indexterm"></a>
       Make a connection to the database server in a nonblocking manner.

</p><pre class="synopsis">
PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *values,
                             int expand_dbname);

PGconn *PQconnectStart(const char *conninfo);

PostgresPollingStatusType PQconnectPoll(PGconn *conn);
</pre><p>
      </p><p>
       These three functions are used to open a connection to a database server such
       that your application's thread of execution is not blocked on remote I/O
       whilst doing so. The point of this approach is that the waits for I/O to
       complete can occur in the application's main loop, rather than down inside
       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a> or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and so the
       application can manage this operation in parallel with other activities.
      </p><p>
       With <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, the database connection is made
       using the parameters taken from the <code class="literal">keywords</code> and
       <code class="literal">values</code> arrays, and controlled by <code class="literal">expand_dbname</code>,
       as described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>.
      </p><p>
       With <code class="function">PQconnectStart</code>, the database connection is made
       using the parameters taken from the string <code class="literal">conninfo</code> as
       described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
      </p><p>
       Neither <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> nor <code class="function">PQconnectStart</code>
       nor <code class="function">PQconnectPoll</code> will block, so long as a number of
       restrictions are met:
       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          The <code class="literal">hostaddr</code> parameter must be used appropriately
          to prevent DNS queries from being made.  See the documentation of
          this parameter in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="32.1.2. Parameter Key Words">Section 32.1.2</a> for details.
         </p></li><li class="listitem"><p>
          If you call <a class="xref" href="libpq-control.html#LIBPQ-PQTRACE"><code class="function">PQtrace</code></a>, ensure that the stream object
          into which you trace will not block.
         </p></li><li class="listitem"><p>
          You must ensure that the socket is in the appropriate state
          before calling <code class="function">PQconnectPoll</code>, as described below.
         </p></li></ul></div><p>
      </p><p>
       To begin a nonblocking connection request,
       call <code class="function">PQconnectStart</code>
       or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>.  If the result is null,
       then <span class="application">libpq</span> has been unable to allocate a
       new <code class="structname">PGconn</code> structure.  Otherwise, a
       valid <code class="structname">PGconn</code> pointer is returned (though not
       yet representing a valid connection to the database).  Next
       call <code class="literal">PQstatus(conn)</code>.  If the result
       is <code class="symbol">CONNECTION_BAD</code>, the connection attempt has already
       failed, typically because of invalid connection parameters.
      </p><p>
       If <code class="function">PQconnectStart</code>
       or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> succeeds, the next stage
       is to poll <span class="application">libpq</span> so that it can proceed with
       the connection sequence.
       Use <code class="function">PQsocket(conn)</code> to obtain the descriptor of the
       socket underlying the database connection.
       (Caution: do not assume that the socket remains the same
       across <code class="function">PQconnectPoll</code> calls.)
       Loop thus: If <code class="function">PQconnectPoll(conn)</code> last returned
       <code class="symbol">PGRES_POLLING_READING</code>, wait until the socket is ready to
       read (as indicated by <code class="function">select()</code>, <code class="function">poll()</code>, or
       similar system function).  Note that <code class="function">PQsocketPoll</code>
       can help reduce boilerplate by abstracting the setup of
       <code class="function">select(2)</code> or <code class="function">poll(2)</code> if it is
       available on your system.
       Then call <code class="function">PQconnectPoll(conn)</code> again.
       Conversely, if <code class="function">PQconnectPoll(conn)</code> last returned
       <code class="symbol">PGRES_POLLING_WRITING</code>, wait until the socket is ready
       to write, then call <code class="function">PQconnectPoll(conn)</code> again.
       On the first iteration, i.e., if you have yet to call
       <code class="function">PQconnectPoll</code>, behave as if it last returned
       <code class="symbol">PGRES_POLLING_WRITING</code>.  Continue this loop until
       <code class="function">PQconnectPoll(conn)</code> returns
       <code class="symbol">PGRES_POLLING_FAILED</code>, indicating the connection procedure
       has failed, or <code class="symbol">PGRES_POLLING_OK</code>, indicating the connection
       has been successfully made.
      </p><p>
       At any time during connection, the status of the connection can be
       checked by calling <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>. If this call returns <code class="symbol">CONNECTION_BAD</code>, then the
       connection procedure has failed; if the call returns <code class="symbol">CONNECTION_OK</code>, then the
       connection is ready.  Both of these states are equally detectable
       from the return value of <code class="function">PQconnectPoll</code>, described above. Other states might also occur
       during (and only during) an asynchronous connection procedure. These
       indicate the current stage of the connection procedure and might be useful
       to provide feedback to the user for example. These statuses are:

       </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CONNECTION-STARTED"><span class="term"><code class="symbol">CONNECTION_STARTED</code></span> <a href="#LIBPQ-CONNECTION-STARTED" class="id_link">#</a></dt><dd><p>
           Waiting for connection to be made.
          </p></dd><dt id="LIBPQ-CONNECTION-MADE"><span class="term"><code class="symbol">CONNECTION_MADE</code></span> <a href="#LIBPQ-CONNECTION-MADE" class="id_link">#</a></dt><dd><p>
           Connection OK; waiting to send.
          </p></dd><dt id="LIBPQ-CONNECTION-AWAITING-RESPONSE"><span class="term"><code class="symbol">CONNECTION_AWAITING_RESPONSE</code></span> <a href="#LIBPQ-CONNECTION-AWAITING-RESPONSE" class="id_link">#</a></dt><dd><p>
           Waiting for a response from the server.
          </p></dd><dt id="LIBPQ-CONNECTION-AUTH-OK"><span class="term"><code class="symbol">CONNECTION_AUTH_OK</code></span> <a href="#LIBPQ-CONNECTION-AUTH-OK" class="id_link">#</a></dt><dd><p>
           Received authentication; waiting for backend start-up to finish.
          </p></dd><dt id="LIBPQ-CONNECTION-SSL-STARTUP"><span class="term"><code class="symbol">CONNECTION_SSL_STARTUP</code></span> <a href="#LIBPQ-CONNECTION-SSL-STARTUP" class="id_link">#</a></dt><dd><p>
           Negotiating SSL encryption.
          </p></dd><dt id="LIBPQ-CONNECTION-GSS-STARTUP"><span class="term"><code class="symbol">CONNECTION_GSS_STARTUP</code></span> <a href="#LIBPQ-CONNECTION-GSS-STARTUP" class="id_link">#</a></dt><dd><p>
           Negotiating GSS encryption.
          </p></dd><dt id="LIBPQ-CONNECTION-CHECK-WRITABLE"><span class="term"><code class="symbol">CONNECTION_CHECK_WRITABLE</code></span> <a href="#LIBPQ-CONNECTION-CHECK-WRITABLE" class="id_link">#</a></dt><dd><p>
           Checking if connection is able to handle write transactions.
          </p></dd><dt id="LIBPQ-CONNECTION-CHECK-STANDBY"><span class="term"><code class="symbol">CONNECTION_CHECK_STANDBY</code></span> <a href="#LIBPQ-CONNECTION-CHECK-STANDBY" class="id_link">#</a></dt><dd><p>
           Checking if connection is to a server in standby mode.
          </p></dd><dt id="LIBPQ-CONNECTION-CONSUME"><span class="term"><code class="symbol">CONNECTION_CONSUME</code></span> <a href="#LIBPQ-CONNECTION-CONSUME" class="id_link">#</a></dt><dd><p>
           Consuming any remaining response messages on connection.
          </p></dd></dl></div><p>

       Note that, although these constants will remain (in order to maintain
       compatibility), an application should never rely upon these occurring in a
       particular order, or at all, or on the status always being one of these
       documented values. An application might do something like this:
</p><pre class="programlisting">
switch(PQstatus(conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
}
</pre><p>
      </p><p>
       The <code class="literal">connect_timeout</code> connection parameter is ignored
       when using <code class="function">PQconnectPoll</code>; it is the application's
       responsibility to decide whether an excessive amount of time has elapsed.
       Otherwise, <code class="function">PQconnectStart</code> followed by a
       <code class="function">PQconnectPoll</code> loop is equivalent to
       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
      </p><p>
       Note that when <code class="function">PQconnectStart</code>
       or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> returns a non-null
       pointer, you must call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> when you are
       finished with it, in order to dispose of the structure and any
       associated memory blocks.  This must be done even if the connection
       attempt fails or is abandoned.
      </p></dd><dt id="LIBPQ-PQSOCKETPOLL"><span class="term"><code class="function">PQsocketPoll</code><a id="id-1.7.3.8.2.11.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSOCKETPOLL" class="id_link">#</a></dt><dd><p>
       <a id="id-1.7.3.8.2.11.6.2.1.1" class="indexterm"></a>
       Poll a connection's underlying socket descriptor retrieved with
       <a class="xref" href="libpq-status.html#LIBPQ-PQSOCKET"><code class="function">PQsocket</code></a>.
       The primary use of this function is iterating through the connection
       sequence described in the documentation of
       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>.
</p><pre class="synopsis">
typedef int64_t pg_usec_time_t;

int PQsocketPoll(int sock, int forRead, int forWrite,
                 pg_usec_time_t end_time);
</pre><p>
      </p><p>
       This function performs polling of a file descriptor, optionally with
       a timeout.
       If <em class="parameter"><code>forRead</code></em> is nonzero, the
       function will terminate when the socket is ready for
       reading. If <em class="parameter"><code>forWrite</code></em> is nonzero,
       the function will terminate when the
       socket is ready for writing.
      </p><p>
       The timeout is specified by <em class="parameter"><code>end_time</code></em>, which
       is the time to stop waiting expressed as a number of microseconds since
       the Unix epoch (that is, <code class="type">time_t</code> times 1 million).
       Timeout is infinite if <em class="parameter"><code>end_time</code></em>
       is <code class="literal">-1</code>.  Timeout is immediate (no blocking) if
       <em class="parameter"><code>end_time</code></em> is <code class="literal">0</code> (or indeed, any
       time before now).  Timeout values can be calculated conveniently by
       adding the desired number of microseconds to the result of
       <a class="xref" href="libpq-misc.html#LIBPQ-PQGETCURRENTTIMEUSEC"><code class="function">PQgetCurrentTimeUSec</code></a>.
       Note that the underlying system calls may have less than microsecond
       precision, so that the actual delay may be imprecise.
      </p><p>
       The function returns a value greater than <code class="literal">0</code> if the
       specified condition is met, <code class="literal">0</code> if a timeout occurred,
       or <code class="literal">-1</code> if an error occurred. The error can be
       retrieved by checking the <code class="literal">errno(3)</code> value. In the
       event both <em class="parameter"><code>forRead</code></em>
       and <em class="parameter"><code>forWrite</code></em> are zero, the function immediately
       returns a timeout indication.
      </p><p>
       <code class="function">PQsocketPoll</code> is implemented using either
       <code class="function">poll(2)</code> or <code class="function">select(2)</code>,
       depending on platform.  See <code class="literal">POLLIN</code>
       and <code class="literal">POLLOUT</code> from <code class="function">poll(2)</code>,
       or <em class="parameter"><code>readfds</code></em> and
       <em class="parameter"><code>writefds</code></em> from <code class="function">select(2)</code>,
       for more information.
      </p></dd><dt id="LIBPQ-PQCONNDEFAULTS"><span class="term"><code class="function">PQconndefaults</code><a id="id-1.7.3.8.2.11.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNDEFAULTS" class="id_link">#</a></dt><dd><p>
       Returns the default connection options.
</p><pre class="synopsis">
PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* The keyword of the option */
    char   *envvar;    /* Fallback environment variable name */
    char   *compiled;  /* Fallback compiled in default value */
    char   *val;       /* Option's current value, or NULL */
    char   *label;     /* Label for field in connect dialog */
    char   *dispchar;  /* Indicates how to display this field
                          in a connect dialog. Values are:
                          ""        Display entered value as is
                          "*"       Password field - hide value
                          "D"       Debug option - don't show by default */
    int     dispsize;  /* Field size in characters for dialog */
} PQconninfoOption;
</pre><p>
      </p><p>
       Returns a connection options array.  This can be used to determine
       all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and their
       current default values.  The return value points to an array of
       <code class="structname">PQconninfoOption</code> structures, which ends
       with an entry having a null <code class="structfield">keyword</code> pointer.  The
       null pointer is returned if memory could not be allocated. Note that
       the current default values (<code class="structfield">val</code> fields)
       will depend on environment variables and other context.  A
       missing or invalid service file will be silently ignored.  Callers
       must treat the connection options data as read-only.
      </p><p>
       After processing the options array, free it by passing it to
       <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>.  If this is not done, a small amount of memory
       is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a>.
      </p></dd><dt id="LIBPQ-PQCONNINFO"><span class="term"><code class="function">PQconninfo</code><a id="id-1.7.3.8.2.11.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNINFO" class="id_link">#</a></dt><dd><p>
       Returns the connection options used by a live connection.
</p><pre class="synopsis">
PQconninfoOption *PQconninfo(PGconn *conn);
</pre><p>
      </p><p>
       Returns a connection options array.  This can be used to determine
       all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and the
       values that were used to connect to the server. The return
       value points to an array of <code class="structname">PQconninfoOption</code>
       structures, which ends with an entry having a null <code class="structfield">keyword</code>
       pointer. All notes above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a> also
       apply to the result of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFO"><code class="function">PQconninfo</code></a>.
      </p></dd><dt id="LIBPQ-PQCONNINFOPARSE"><span class="term"><code class="function">PQconninfoParse</code><a id="id-1.7.3.8.2.11.9.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNINFOPARSE" class="id_link">#</a></dt><dd><p>
       Returns parsed connection options from the provided connection string.

</p><pre class="synopsis">
PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
</pre><p>
      </p><p>
       Parses a connection string and returns the resulting options as an
       array; or returns <code class="symbol">NULL</code> if there is a problem with the connection
       string.  This function can be used to extract
       the <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options in the provided
       connection string.  The return value points to an array of
       <code class="structname">PQconninfoOption</code> structures, which ends
       with an entry having a null <code class="structfield">keyword</code> pointer.
      </p><p>
       All legal options will be present in the result array, but the
       <code class="literal">PQconninfoOption</code> for any option not present
       in the connection string will have <code class="literal">val</code> set to
       <code class="literal">NULL</code>; default values are not inserted.
      </p><p>
       If <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>, then <code class="literal">*errmsg</code> is set
       to <code class="symbol">NULL</code> on success, else to a <code class="function">malloc</code>'d error string explaining
       the problem.  (It is also possible for <code class="literal">*errmsg</code> to be
       set to <code class="symbol">NULL</code> and the function to return <code class="symbol">NULL</code>;
       this indicates an out-of-memory condition.)
      </p><p>
       After processing the options array, free it by passing it to
       <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>.  If this is not done, some memory
       is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFOPARSE"><code class="function">PQconninfoParse</code></a>.
       Conversely, if an error occurs and <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>,
       be sure to free the error string using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a>.
      </p></dd><dt id="LIBPQ-PQFINISH"><span class="term"><code class="function">PQfinish</code><a id="id-1.7.3.8.2.11.10.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFINISH" class="id_link">#</a></dt><dd><p>
       Closes  the  connection to the server.  Also frees
       memory used by the <code class="structname">PGconn</code> object.
</p><pre class="synopsis">
void PQfinish(PGconn *conn);
</pre><p>
      </p><p>
       Note that even if the server connection attempt fails (as
       indicated by <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>), the application should call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>
       to free the memory used by the <code class="structname">PGconn</code> object.
       The <code class="structname">PGconn</code> pointer must not be used again after
       <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> has been called.
      </p></dd><dt id="LIBPQ-PQRESET"><span class="term"><code class="function">PQreset</code><a id="id-1.7.3.8.2.11.11.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESET" class="id_link">#</a></dt><dd><p>
       Resets the communication channel to the server.
</p><pre class="synopsis">
void PQreset(PGconn *conn);
</pre><p>
      </p><p>
       This function will close the connection
       to the server and attempt to establish a new
       connection, using all the same
       parameters previously used.  This might be useful for
       error recovery if a working connection is lost.
      </p></dd><dt id="LIBPQ-PQRESETSTART"><span class="term"><code class="function">PQresetStart</code><a id="id-1.7.3.8.2.11.12.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQresetPoll</code><a id="id-1.7.3.8.2.11.12.2.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESETSTART" class="id_link">#</a></dt><dd><p>
       Reset the communication channel to the server, in a nonblocking manner.

</p><pre class="synopsis">
int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);
</pre><p>
      </p><p>
       These functions will close the connection to the server and attempt to
       establish a new connection, using all the same
       parameters previously used. This can be useful for error recovery if a
       working connection is lost. They differ from <a class="xref" href="libpq-connect.html#LIBPQ-PQRESET"><code class="function">PQreset</code></a> (above) in that they
       act in a nonblocking manner. These functions suffer from the same
       restrictions as <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, <code class="function">PQconnectStart</code>
       and <code class="function">PQconnectPoll</code>.
      </p><p>
       To initiate a connection reset, call
       <a class="xref" href="libpq-connect.html#LIBPQ-PQRESETSTART"><code class="function">PQresetStart</code></a>. If it returns 0, the reset has
       failed. If it returns 1, poll the reset using
       <code class="function">PQresetPoll</code> in exactly the same way as you
       would create the connection using <code class="function">PQconnectPoll</code>.
      </p></dd><dt id="LIBPQ-PQPINGPARAMS"><span class="term"><code class="function">PQpingParams</code><a id="id-1.7.3.8.2.11.13.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPINGPARAMS" class="id_link">#</a></dt><dd><p>
       <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a> reports the status of the
       server.  It accepts connection parameters identical to those of
       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, described above.  It is not
       necessary to supply correct user name, password, or database name
       values to obtain the server status; however, if incorrect values
       are provided, the server will log a failed connection attempt.

</p><pre class="synopsis">
PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);
</pre><p>

       The function returns one of the following values:

       </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPINGPARAMS-PQPING_OK"><span class="term"><code class="literal">PQPING_OK</code></span> <a href="#LIBPQ-PQPINGPARAMS-PQPING_OK" class="id_link">#</a></dt><dd><p>
           The server is running and appears to be accepting connections.
          </p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_REJECT"><span class="term"><code class="literal">PQPING_REJECT</code></span> <a href="#LIBPQ-PQPINGPARAMS-PQPING_REJECT" class="id_link">#</a></dt><dd><p>
           The server is running but is in a state that disallows connections
           (startup, shutdown, or crash recovery).
          </p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_NO_RESPONSE"><span class="term"><code class="literal">PQPING_NO_RESPONSE</code></span> <a href="#LIBPQ-PQPINGPARAMS-PQPING_NO_RESPONSE" class="id_link">#</a></dt><dd><p>
           The server could not be contacted.  This might indicate that the
           server is not running, or that there is something wrong with the
           given connection parameters (for example, wrong port number), or
           that there is a network connectivity problem (for example, a
           firewall blocking the connection request).
          </p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_NO_ATTEMPT"><span class="term"><code class="literal">PQPING_NO_ATTEMPT</code></span> <a href="#LIBPQ-PQPINGPARAMS-PQPING_NO_ATTEMPT" class="id_link">#</a></dt><dd><p>
           No attempt was made to contact the server, because the supplied
           parameters were obviously incorrect or there was some client-side
           problem (for example, out of memory).
          </p></dd></dl></div><p>

      </p></dd><dt id="LIBPQ-PQPING"><span class="term"><code class="function">PQping</code><a id="id-1.7.3.8.2.11.14.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPING" class="id_link">#</a></dt><dd><p>
       <a class="xref" href="libpq-connect.html#LIBPQ-PQPING"><code class="function">PQping</code></a> reports the status of the
       server.  It accepts connection parameters identical to those of
       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, described above.  It is not
       necessary to supply correct user name, password, or database name
       values to obtain the server status; however, if incorrect values
       are provided, the server will log a failed connection attempt.

</p><pre class="synopsis">
PGPing PQping(const char *conninfo);
</pre><p>
      </p><p>
       The return values are the same as for <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a>.
      </p></dd><dt id="LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQsetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.15.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL" class="id_link">#</a></dt><dd><p>
       <code class="function">PQsetSSLKeyPassHook_OpenSSL</code> lets an application override
       <span class="application">libpq</span>'s <a class="link" href="libpq-ssl.html#LIBPQ-SSL-CLIENTCERT" title="32.19.2. Client Certificates">default
       handling of encrypted client certificate key files</a> using
       <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLPASSWORD">sslpassword</a> or interactive prompting.

</p><pre class="synopsis">
void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
</pre><p>

       The application passes a pointer to a callback function with signature:
</p><pre class="programlisting">
int callback_fn(char *buf, int size, PGconn *conn);
</pre><p>
       which <span class="application">libpq</span> will then call
       <span class="emphasis"><em>instead of</em></span> its default
       <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> handler. The
       callback should determine the password for the key and copy it to
       result-buffer <em class="parameter"><code>buf</code></em> of size
       <em class="parameter"><code>size</code></em>. The string in <em class="parameter"><code>buf</code></em>
       must be null-terminated. The callback must return the length of the
       password stored in <em class="parameter"><code>buf</code></em> excluding the null
       terminator. On failure, the callback should set
       <code class="literal">buf[0] = '\0'</code> and return 0. See
       <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> in
       <span class="application">libpq</span>'s source code for an example.
      </p><p>
       If the user specified an explicit key location,
       its path will be in <code class="literal">conn-&gt;sslkey</code> when the callback
       is invoked. This will be empty if the default key path is being used.
       For keys that are engine specifiers, it is up to engine implementations
       whether they use the <span class="productname">OpenSSL</span> password
       callback or define their own handling.
      </p><p>
       The app callback may choose to delegate unhandled cases to
       <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code>,
       or call it first and try something else if it returns 0, or completely override it.
      </p><p>
       The callback <span class="emphasis"><em>must not</em></span> escape normal flow control with exceptions,
       <code class="function">longjmp(...)</code>, etc. It must return normally.
      </p></dd><dt id="LIBPQ-PQGETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQgetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.16.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETSSLKEYPASSHOOK-OPENSSL" class="id_link">#</a></dt><dd><p>
       <code class="function">PQgetSSLKeyPassHook_OpenSSL</code> returns the current
       client certificate key password hook, or <code class="literal">NULL</code>
       if none has been set.

</p><pre class="synopsis">
PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
</pre><p>
      </p></dd></dl></div><p>
  </p><div class="sect2" id="LIBPQ-CONNSTRING"><div class="titlepage"><div><div><h3 class="title">32.1.1. Connection Strings <a href="#LIBPQ-CONNSTRING" class="id_link">#</a></h3></div></div></div><a id="id-1.7.3.8.3.2" class="indexterm"></a><a id="id-1.7.3.8.3.3" class="indexterm"></a><p>
    Several <span class="application">libpq</span> functions parse a user-specified string to obtain
    connection parameters.  There are two accepted formats for these strings:
    plain keyword/value strings
    and URIs.  URIs generally follow
    <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc3986" target="_top">RFC
    3986</a>, except that multi-host connection strings are allowed
    as further described below.
   </p><div class="sect3" id="LIBPQ-CONNSTRING-KEYWORD-VALUE"><div class="titlepage"><div><div><h4 class="title">32.1.1.1. Keyword/Value Connection Strings <a href="#LIBPQ-CONNSTRING-KEYWORD-VALUE" class="id_link">#</a></h4></div></div></div><p>
    In the keyword/value format, each parameter setting is in the form
    <em class="replaceable"><code>keyword</code></em> <code class="literal">=</code>
    <em class="replaceable"><code>value</code></em>, with space(s) between settings.
    Spaces around a setting's equal sign are
    optional. To write an empty value, or a value containing spaces, surround it
    with single quotes, for example <code class="literal">keyword = 'a value'</code>.
    Single quotes and backslashes within
    a value must be escaped with a backslash, i.e., <code class="literal">\'</code> and
    <code class="literal">\\</code>.
   </p><p>
    Example:
</p><pre class="programlisting">
host=localhost port=5432 dbname=mydb connect_timeout=10
</pre><p>
   </p><p>
    The recognized parameter key words are listed in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="32.1.2. Parameter Key Words">Section 32.1.2</a>.
   </p></div><div class="sect3" id="LIBPQ-CONNSTRING-URIS"><div class="titlepage"><div><div><h4 class="title">32.1.1.2. Connection URIs <a href="#LIBPQ-CONNSTRING-URIS" class="id_link">#</a></h4></div></div></div><p>
   The general form for a connection <acronym class="acronym">URI</acronym> is:
</p><pre class="synopsis">
postgresql://[<span class="optional"><em class="replaceable"><code>userspec</code></em>@</span>][<span class="optional"><em class="replaceable"><code>hostspec</code></em></span>][<span class="optional">/<em class="replaceable"><code>dbname</code></em></span>][<span class="optional">?<em class="replaceable"><code>paramspec</code></em></span>]

<span class="phrase">where <em class="replaceable"><code>userspec</code></em> is:</span>

<em class="replaceable"><code>user</code></em>[<span class="optional">:<em class="replaceable"><code>password</code></em></span>]

<span class="phrase">and <em class="replaceable"><code>hostspec</code></em> is:</span>

[<span class="optional"><em class="replaceable"><code>host</code></em></span>][<span class="optional">:<em class="replaceable"><code>port</code></em></span>][<span class="optional">,...</span>]

<span class="phrase">and <em class="replaceable"><code>paramspec</code></em> is:</span>

<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>[<span class="optional">&amp;...</span>]
</pre><p>
   </p><p>
    The <acronym class="acronym">URI</acronym> scheme designator can be either
    <code class="literal">postgresql://</code> or <code class="literal">postgres://</code>.  Each
    of the remaining <acronym class="acronym">URI</acronym> parts is optional.  The
    following examples illustrate valid <acronym class="acronym">URI</acronym> syntax:
</p><pre class="programlisting">
postgresql://
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/mydb
postgresql://user@localhost
postgresql://user:secret@localhost
postgresql://other@localhost/otherdb?connect_timeout=10&amp;application_name=myapp
postgresql://host1:123,host2:456/somedb?target_session_attrs=any&amp;application_name=myapp
</pre><p>
    Values that would normally appear in the hierarchical part of
    the <acronym class="acronym">URI</acronym> can alternatively be given as named
    parameters.  For example:
</p><pre class="programlisting">
postgresql:///mydb?host=localhost&amp;port=5433
</pre><p>
    All named parameters must match key words listed in
    <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="32.1.2. Parameter Key Words">Section 32.1.2</a>, except that for compatibility
    with JDBC connection <acronym class="acronym">URI</acronym>s, instances
    of <code class="literal">ssl=true</code> are translated into
    <code class="literal">sslmode=require</code>.
   </p><p>
    The connection <acronym class="acronym">URI</acronym> needs to be encoded with <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1" target="_top">percent-encoding</a>
    if it includes symbols with special meaning in any of its parts.  Here is
    an example where the equal sign (<code class="literal">=</code>) is replaced with
    <code class="literal">%3D</code> and the space character with
    <code class="literal">%20</code>:
</p><pre class="programlisting">
postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
</pre><p>
   </p><p>
    The host part may be either a host name or an IP address.  To specify an
    IPv6 address, enclose it in square brackets:
</p><pre class="synopsis">
postgresql://[2001:db8::1234]/database
</pre><p>
   </p><p>
    The host part is interpreted as described for the parameter <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-HOST">host</a>.  In particular, a Unix-domain socket
    connection is chosen if the host part is either empty or looks like an
    absolute path name,
    otherwise a TCP/IP connection is initiated.  Note, however, that the
    slash is a reserved character in the hierarchical part of the URI.  So, to
    specify a non-standard Unix-domain socket directory, either omit the host
    part of the URI and specify the host as a named parameter, or
    percent-encode the path in the host part of the URI:
</p><pre class="programlisting">
postgresql:///dbname?host=/var/lib/postgresql
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
</pre><p>
   </p><p>
    It is possible to specify multiple host components, each with an optional
    port component, in a single URI.  A URI of the form
    <code class="literal">postgresql://host1:port1,host2:port2,host3:port3/</code>
    is equivalent to a connection string of the form
    <code class="literal">host=host1,host2,host3 port=port1,port2,port3</code>.
    As further described below, each
    host will be tried in turn until a connection is successfully established.
   </p></div><div class="sect3" id="LIBPQ-MULTIPLE-HOSTS"><div class="titlepage"><div><div><h4 class="title">32.1.1.3. Specifying Multiple Hosts <a href="#LIBPQ-MULTIPLE-HOSTS" class="id_link">#</a></h4></div></div></div><p>
       It is possible to specify multiple hosts to connect to, so that they are
       tried in the given order. In the Keyword/Value format, the <code class="literal">host</code>,
       <code class="literal">hostaddr</code>, and <code class="literal">port</code> options accept comma-separated
       lists of values. The same number of elements must be given in each
       option that is specified, such
       that e.g., the first <code class="literal">hostaddr</code> corresponds to the first host name,
       the second <code class="literal">hostaddr</code> corresponds to the second host name, and so
       forth. As an exception, if only one <code class="literal">port</code> is specified, it
       applies to all the hosts.
     </p><p>
       In the connection URI format, you can list multiple <code class="literal">host:port</code> pairs
       separated by commas in the <code class="literal">host</code> component of the URI.
     </p><p>
       In either format, a single host name can translate to multiple network
       addresses. A common example of this is a host that has both an IPv4 and
       an IPv6 address.
     </p><p>
       When multiple hosts are specified, or when a single host name is
       translated to multiple addresses,  all the hosts and addresses will be
       tried in order, until one succeeds. If none of the hosts can be reached,
       the connection fails. If a connection is established successfully, but
       authentication fails, the remaining hosts in the list are not tried.
     </p><p>
       If a password file is used, you can have different passwords for
       different hosts. All the other connection options are the same for every
       host in the list; it is not possible to e.g., specify different
       usernames for different hosts.
     </p></div></div><div class="sect2" id="LIBPQ-PARAMKEYWORDS"><div class="titlepage"><div><div><h3 class="title">32.1.2. Parameter Key Words <a href="#LIBPQ-PARAMKEYWORDS" class="id_link">#</a></h3></div></div></div><p>
    The currently recognized parameter key words are:

    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CONNECT-HOST"><span class="term"><code class="literal">host</code></span> <a href="#LIBPQ-CONNECT-HOST" class="id_link">#</a></dt><dd><p>
        Name of host to connect to.<a id="id-1.7.3.8.4.2.1.1.2.1.1" class="indexterm"></a> If a host name looks like an absolute path
        name, it specifies Unix-domain communication rather than TCP/IP
        communication; the value is the name of the directory in which the
        socket file is stored.  (On Unix, an absolute path name begins with a
        slash.  On Windows, paths starting with drive letters are also
        recognized.)  If the host name starts with <code class="literal">@</code>, it is
        taken as a Unix-domain socket in the abstract namespace (currently
        supported on Linux and Windows).
        The default behavior when <code class="literal">host</code> is not
        specified, or is empty, is to connect to a Unix-domain
        socket<a id="id-1.7.3.8.4.2.1.1.2.1.4" class="indexterm"></a> in
        <code class="filename">/tmp</code> (or whatever socket directory was specified
        when <span class="productname">PostgreSQL</span> was built).  On Windows,
        the default is to connect to <code class="literal">localhost</code>.
       </p><p>
        A comma-separated list of host names is also accepted, in which case
        each host name in the list is tried in order; an empty item in the
        list selects the default behavior as explained above. See
        <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="32.1.1.3. Specifying Multiple Hosts">Section 32.1.1.3</a> for details.
       </p></dd><dt id="LIBPQ-CONNECT-HOSTADDR"><span class="term"><code class="literal">hostaddr</code></span> <a href="#LIBPQ-CONNECT-HOSTADDR" class="id_link">#</a></dt><dd><p>
        Numeric IP address of host to connect to.  This should be in the
        standard IPv4 address format, e.g., <code class="literal">172.28.40.9</code>.  If
        your machine supports IPv6, you can also use those addresses.
        TCP/IP communication is
        always used when a nonempty string is specified for this parameter.
        If this parameter is not specified, the value of <code class="literal">host</code>
        will be looked up to find the corresponding IP address — or, if
        <code class="literal">host</code> specifies an IP address, that value will be
        used directly.
       </p><p>
        Using <code class="literal">hostaddr</code> allows the
        application to avoid a host name look-up, which might be important
        in applications with time constraints. However, a host name is
        required for GSSAPI or SSPI authentication
        methods, as well as for <code class="literal">verify-full</code> SSL
        certificate verification.  The following rules are used:
        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
           If <code class="literal">host</code> is specified
           without <code class="literal">hostaddr</code>, a host name lookup occurs.
           (When using <code class="function">PQconnectPoll</code>, the lookup occurs
           when <code class="function">PQconnectPoll</code> first considers this host
           name, and it may cause <code class="function">PQconnectPoll</code> to block
           for a significant amount of time.)
          </p></li><li class="listitem"><p>
           If <code class="literal">hostaddr</code> is specified without <code class="literal">host</code>,
           the value for <code class="literal">hostaddr</code> gives the server network address.
           The connection attempt will fail if the authentication
           method requires a host name.
          </p></li><li class="listitem"><p>
           If both <code class="literal">host</code> and <code class="literal">hostaddr</code> are specified,
           the value for <code class="literal">hostaddr</code> gives the server network address.
           The value for <code class="literal">host</code> is ignored unless the
           authentication method requires it, in which case it will be
           used as the host name.
          </p></li></ul></div><p>
        Note that authentication is likely to fail if <code class="literal">host</code>
        is not the name of the server at network address <code class="literal">hostaddr</code>.
        Also, when both <code class="literal">host</code> and <code class="literal">hostaddr</code>
        are specified, <code class="literal">host</code>
        is used to identify the connection in a password file (see
        <a class="xref" href="libpq-pgpass.html" title="32.16. The Password File">Section 32.16</a>).
       </p><p>
        A comma-separated list of <code class="literal">hostaddr</code> values is also
        accepted, in which case each host in the list is tried in order.
        An empty item in the list causes the corresponding host name to be
        used, or the default host name if that is empty as well. See
        <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="32.1.1.3. Specifying Multiple Hosts">Section 32.1.1.3</a> for details.
       </p><p>
        Without either a host name or host address,
        <span class="application">libpq</span> will connect using a local
        Unix-domain socket; or on Windows, it will attempt to connect to
        <code class="literal">localhost</code>.
       </p></dd><dt id="LIBPQ-CONNECT-PORT"><span class="term"><code class="literal">port</code></span> <a href="#LIBPQ-CONNECT-PORT" class="id_link">#</a></dt><dd><p>
        Port number to connect to at the server host, or socket file
        name extension for Unix-domain
        connections.<a id="id-1.7.3.8.4.2.1.3.2.1.1" class="indexterm"></a>
        If multiple hosts were given in the <code class="literal">host</code> or
        <code class="literal">hostaddr</code> parameters, this parameter may specify a
        comma-separated list of ports of the same length as the host list, or
        it may specify a single port number to be used for all hosts.
        An empty string, or an empty item in a comma-separated list,
        specifies the default port number established
        when <span class="productname">PostgreSQL</span> was built.
       </p></dd><dt id="LIBPQ-CONNECT-DBNAME"><span class="term"><code class="literal">dbname</code></span> <a href="#LIBPQ-CONNECT-DBNAME" class="id_link">#</a></dt><dd><p>
       The database name.  Defaults to be the same as the user name.
       In certain contexts, the value is checked for extended
       formats; see <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">Section 32.1.1</a> for more details on
       those.
      </p></dd><dt id="LIBPQ-CONNECT-USER"><span class="term"><code class="literal">user</code></span> <a href="#LIBPQ-CONNECT-USER" class="id_link">#</a></dt><dd><p>
       <span class="productname">PostgreSQL</span> user name to connect as.
       Defaults to be the same as the operating system name of the user
       running the application.
      </p></dd><dt id="LIBPQ-CONNECT-PASSWORD"><span class="term"><code class="literal">password</code></span> <a href="#LIBPQ-CONNECT-PASSWORD" class="id_link">#</a></dt><dd><p>
       Password to be used if the server demands password authentication.
      </p></dd><dt id="LIBPQ-CONNECT-PASSFILE"><span class="term"><code class="literal">passfile</code></span> <a href="#LIBPQ-CONNECT-PASSFILE" class="id_link">#</a></dt><dd><p>
       Specifies the name of the file used to store passwords
       (see <a class="xref" href="libpq-pgpass.html" title="32.16. The Password File">Section 32.16</a>).
       Defaults to <code class="filename">~/.pgpass</code>, or
       <code class="filename">%APPDATA%\postgresql\pgpass.conf</code> on Microsoft Windows.
       (No error is reported if this file does not exist.)
      </p></dd><dt id="LIBPQ-CONNECT-REQUIRE-AUTH"><span class="term"><code class="literal">require_auth</code></span> <a href="#LIBPQ-CONNECT-REQUIRE-AUTH" class="id_link">#</a></dt><dd><p>
        Specifies the authentication method that the client requires from the
        server. If the server does not use the required method to authenticate
        the client, or if the authentication handshake is not fully completed by
        the server, the connection will fail. A comma-separated list of methods
        may also be provided, of which the server must use exactly one in order
        for the connection to succeed. By default, any authentication method is
        accepted, and the server is free to skip authentication altogether.
      </p><p>
        Methods may be negated with the addition of a <code class="literal">!</code>
        prefix, in which case the server must <span class="emphasis"><em>not</em></span> attempt
        the listed method; any other method is accepted, and the server is free
        not to authenticate the client at all. If a comma-separated list is
        provided, the server may not attempt <span class="emphasis"><em>any</em></span> of the
        listed negated methods. Negated and non-negated forms may not be
        combined in the same setting.
      </p><p>
        As a final special case, the <code class="literal">none</code> method requires the
        server not to use an authentication challenge. (It may also be negated,
        to require some form of authentication.)
      </p><p>
        The following methods may be specified:

        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">password</code></span></dt><dd><p>
            The server must request plaintext password authentication.
           </p></dd><dt><span class="term"><code class="literal">md5</code></span></dt><dd><p>
            The server must request MD5 hashed password authentication.
           </p><div class="warning"><h3 class="title">Warning</h3><p>
             Support for MD5-encrypted passwords is deprecated and will be
             removed in a future release of
             <span class="productname">PostgreSQL</span>.  Refer to
             <a class="xref" href="auth-password.html" title="20.5. Password Authentication">Section 20.5</a> for details about migrating to
             another password type.
            </p></div></dd><dt><span class="term"><code class="literal">gss</code></span></dt><dd><p>
            The server must either request a Kerberos handshake via
            <acronym class="acronym">GSSAPI</acronym> or establish a
            <acronym class="acronym">GSS</acronym>-encrypted channel (see also
            <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-GSSENCMODE">gssencmode</a>).
           </p></dd><dt><span class="term"><code class="literal">sspi</code></span></dt><dd><p>
            The server must request Windows <acronym class="acronym">SSPI</acronym>
            authentication.
           </p></dd><dt><span class="term"><code class="literal">scram-sha-256</code></span></dt><dd><p>
            The server must successfully complete a SCRAM-SHA-256 authentication
            exchange with the client.
           </p></dd><dt><span class="term"><code class="literal">oauth</code></span></dt><dd><p>
            The server must request an OAuth bearer token from the client.
           </p></dd><dt><span class="term"><code class="literal">none</code></span></dt><dd><p>
            The server must not prompt the client for an authentication
            exchange. (This does not prohibit client certificate authentication
            via TLS, nor GSS authentication via its encrypted transport.)
           </p></dd></dl></div><p>
      </p></dd><dt id="LIBPQ-CONNECT-CHANNEL-BINDING"><span class="term"><code class="literal">channel_binding</code></span> <a href="#LIBPQ-CONNECT-CHANNEL-BINDING" class="id_link">#</a></dt><dd><p>
        This option controls the client's use of channel binding. A setting
        of <code class="literal">require</code> means that the connection must employ
        channel binding, <code class="literal">prefer</code> means that the client will
        choose channel binding if available, and <code class="literal">disable</code>
        prevents the use of channel binding. The default
        is <code class="literal">prefer</code> if
        <span class="productname">PostgreSQL</span> is compiled with SSL support;
        otherwise the default is <code class="literal">disable</code>.
      </p><p>
        Channel binding is a method for the server to authenticate itself to
        the client. It is only supported over SSL connections
        with <span class="productname">PostgreSQL</span> 11 or later servers using
        the <code class="literal">SCRAM</code> authentication method.
      </p></dd><dt id="LIBPQ-CONNECT-CONNECT-TIMEOUT"><span class="term"><code class="literal">connect_timeout</code></span> <a href="#LIBPQ-CONNECT-CONNECT-TIMEOUT" class="id_link">#</a></dt><dd><p>
       Maximum time to wait while connecting, in seconds (write as a decimal integer,
       e.g., <code class="literal">10</code>).  Zero, negative, or not specified means
       wait indefinitely.
       This timeout applies separately to each host name or IP address.
       For example, if you specify two hosts and <code class="literal">connect_timeout</code>
       is 5, each host will time out if no connection is made within 5
       seconds, so the total time spent waiting for a connection might be
       up to 10 seconds.
      </p></dd><dt id="LIBPQ-CONNECT-CLIENT-ENCODING"><span class="term"><code class="literal">client_encoding</code></span> <a href="#LIBPQ-CONNECT-CLIENT-ENCODING" class="id_link">#</a></dt><dd><p>
       This sets the <code class="varname">client_encoding</code>
       configuration parameter for this connection.  In addition to
       the values accepted by the corresponding server option, you
       can use <code class="literal">auto</code> to determine the right
       encoding from the current locale in the client
       (<code class="envar">LC_CTYPE</code> environment variable on Unix
       systems).
      </p></dd><dt id="LIBPQ-CONNECT-OPTIONS"><span class="term"><code class="literal">options</code></span> <a href="#LIBPQ-CONNECT-OPTIONS" class="id_link">#</a></dt><dd><p>
        Specifies command-line options to send to the server at connection
        start.  For example, setting this to <code class="literal">-c geqo=off</code>
        or <code class="literal">--geqo=off</code> sets the session's value of the
        <code class="varname">geqo</code> parameter to <code class="literal">off</code>.
        Spaces within this string are considered to
        separate command-line arguments, unless escaped with a backslash
        (<code class="literal">\</code>); write <code class="literal">\\</code> to represent a literal
        backslash.  For a detailed discussion of the available
        options, consult <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a>.
       </p></dd><dt id="LIBPQ-CONNECT-APPLICATION-NAME"><span class="term"><code class="literal">application_name</code></span> <a href="#LIBPQ-CONNECT-APPLICATION-NAME" class="id_link">#</a></dt><dd><p>
        Specifies a value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a>
        configuration parameter.
       </p></dd><dt id="LIBPQ-CONNECT-FALLBACK-APPLICATION-NAME"><span class="term"><code class="literal">fallback_application_name</code></span> <a href="#LIBPQ-CONNECT-FALLBACK-APPLICATION-NAME" class="id_link">#</a></dt><dd><p>
        Specifies a fallback value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a> configuration parameter.
        This value will be used if no value has been given for
        <code class="literal">application_name</code> via a connection parameter or the
        <code class="envar">PGAPPNAME</code> environment variable.  Specifying
        a fallback name is useful in generic utility programs that
        wish to set a default application name but allow it to be
        overridden by the user.
       </p></dd><dt id="LIBPQ-KEEPALIVES"><span class="term"><code class="literal">keepalives</code></span> <a href="#LIBPQ-KEEPALIVES" class="id_link">#</a></dt><dd><p>
        Controls whether client-side TCP keepalives are used. The default
        value is 1, meaning on, but you can change this to 0, meaning off,
        if keepalives are not wanted.  This parameter is ignored for
        connections made via a Unix-domain socket.
       </p></dd><dt id="LIBPQ-KEEPALIVES-IDLE"><span class="term"><code class="literal">keepalives_idle</code></span> <a href="#LIBPQ-KEEPALIVES-IDLE" class="id_link">#</a></dt><dd><p>
        Controls the number of seconds of inactivity after which TCP should
        send a keepalive message to the server.  A value of zero uses the
        system default. This parameter is ignored for connections made via a
        Unix-domain socket, or if keepalives are disabled.
        It is only supported on systems where <code class="symbol">TCP_KEEPIDLE</code> or
        an equivalent socket option is available, and on Windows; on other
        systems, it has no effect.
       </p></dd><dt id="LIBPQ-KEEPALIVES-INTERVAL"><span class="term"><code class="literal">keepalives_interval</code></span> <a href="#LIBPQ-KEEPALIVES-INTERVAL" class="id_link">#</a></dt><dd><p>
        Controls the number of seconds after which a TCP keepalive message
        that is not acknowledged by the server should be retransmitted.  A
        value of zero uses the system default. This parameter is ignored for
        connections made via a Unix-domain socket, or if keepalives are disabled.
        It is only supported on systems where <code class="symbol">TCP_KEEPINTVL</code> or
        an equivalent socket option is available, and on Windows; on other
        systems, it has no effect.
       </p></dd><dt id="LIBPQ-KEEPALIVES-COUNT"><span class="term"><code class="literal">keepalives_count</code></span> <a href="#LIBPQ-KEEPALIVES-COUNT" class="id_link">#</a></dt><dd><p>
        Controls the number of TCP keepalives that can be lost before the
        client's connection to the server is considered dead.  A value of
        zero uses the system default. This parameter is ignored for
        connections made via a Unix-domain socket, or if keepalives are disabled.
        It is only supported on systems where <code class="symbol">TCP_KEEPCNT</code> or
        an equivalent socket option is available; on other systems, it has no
        effect.
       </p></dd><dt id="LIBPQ-TCP-USER-TIMEOUT"><span class="term"><code class="literal">tcp_user_timeout</code></span> <a href="#LIBPQ-TCP-USER-TIMEOUT" class="id_link">#</a></dt><dd><p>
        Controls the number of milliseconds that transmitted data may
        remain unacknowledged before a connection is forcibly closed.
        A value of zero uses the system default. This parameter is
        ignored for connections made via a Unix-domain socket.
        It is only supported on systems where <code class="symbol">TCP_USER_TIMEOUT</code>
        is available; on other systems, it has no effect.
       </p></dd><dt id="LIBPQ-CONNECT-REPLICATION"><span class="term"><code class="literal">replication</code></span> <a href="#LIBPQ-CONNECT-REPLICATION" class="id_link">#</a></dt><dd><p>
       This option determines whether the connection should use the
       replication protocol instead of the normal protocol.  This is what
       PostgreSQL replication connections as well as tools such as
       <span class="application">pg_basebackup</span> use internally, but it can
       also be used by third-party applications.  For a description of the
       replication protocol, consult <a class="xref" href="protocol-replication.html" title="54.4. Streaming Replication Protocol">Section 54.4</a>.
      </p><p>
       The following values, which are case-insensitive, are supported:
       </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
          <code class="literal">true</code>, <code class="literal">on</code>,
          <code class="literal">yes</code>, <code class="literal">1</code>
         </span></dt><dd><p>
           The connection goes into physical replication mode.
          </p></dd><dt><span class="term"><code class="literal">database</code></span></dt><dd><p>
           The connection goes into logical replication mode, connecting to
           the database specified in the <code class="literal">dbname</code> parameter.
          </p></dd><dt><span class="term">
          <code class="literal">false</code>, <code class="literal">off</code>,
          <code class="literal">no</code>, <code class="literal">0</code>
         </span></dt><dd><p>
           The connection is a regular one, which is the default behavior.
          </p></dd></dl></div><p>
      </p><p>
       In physical or logical replication mode, only the simple query protocol
       can be used.
      </p></dd><dt id="LIBPQ-CONNECT-GSSENCMODE"><span class="term"><code class="literal">gssencmode</code></span> <a href="#LIBPQ-CONNECT-GSSENCMODE" class="id_link">#</a></dt><dd><p>
        This option determines whether or with what priority a secure
        <acronym class="acronym">GSS</acronym> TCP/IP connection will be negotiated with the
        server. There are three modes:

        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
            only try a non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection
           </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>
            if there are <acronym class="acronym">GSSAPI</acronym> credentials present (i.e.,
            in a credentials cache), first try
            a <acronym class="acronym">GSSAPI</acronym>-encrypted connection; if that fails or
            there are no credentials, try a
            non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection.  This is the
            default when <span class="productname">PostgreSQL</span> has been
            compiled with <acronym class="acronym">GSSAPI</acronym> support.
           </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
            only try a <acronym class="acronym">GSSAPI</acronym>-encrypted connection
           </p></dd></dl></div><p>
       </p><p>
        <code class="literal">gssencmode</code> is ignored for Unix domain socket
        communication.  If <span class="productname">PostgreSQL</span> is compiled
        without GSSAPI support, using the <code class="literal">require</code> option
        will cause an error, while <code class="literal">prefer</code> will be accepted
        but <span class="application">libpq</span> will not actually attempt
        a <acronym class="acronym">GSSAPI</acronym>-encrypted
        connection.<a id="id-1.7.3.8.4.2.1.21.2.2.7" class="indexterm"></a>
       </p></dd><dt id="LIBPQ-CONNECT-SSLMODE"><span class="term"><code class="literal">sslmode</code></span> <a href="#LIBPQ-CONNECT-SSLMODE" class="id_link">#</a></dt><dd><p>
        This option determines whether or with what priority a secure
        <acronym class="acronym">SSL</acronym> TCP/IP connection will be negotiated with the
        server. There are six modes:

        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
            only try a non-<acronym class="acronym">SSL</acronym> connection
           </p></dd><dt><span class="term"><code class="literal">allow</code></span></dt><dd><p>
            first try a non-<acronym class="acronym">SSL</acronym> connection; if that
            fails, try an <acronym class="acronym">SSL</acronym> connection
           </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>
            first try an <acronym class="acronym">SSL</acronym> connection; if that fails,
            try a non-<acronym class="acronym">SSL</acronym> connection
           </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
            only try an <acronym class="acronym">SSL</acronym> connection. If a root CA
            file is present, verify the certificate in the same way as
            if <code class="literal">verify-ca</code> was specified
           </p></dd><dt><span class="term"><code class="literal">verify-ca</code></span></dt><dd><p>
            only try an <acronym class="acronym">SSL</acronym> connection, and verify that
            the server certificate is issued by a trusted
            certificate authority (<acronym class="acronym">CA</acronym>)
           </p></dd><dt><span class="term"><code class="literal">verify-full</code></span></dt><dd><p>
            only try an <acronym class="acronym">SSL</acronym> connection, verify that the
            server certificate is issued by a
            trusted <acronym class="acronym">CA</acronym> and that the requested server host name
            matches that in the certificate
           </p></dd></dl></div><p>

        See <a class="xref" href="libpq-ssl.html" title="32.19. SSL Support">Section 32.19</a> for a detailed description of how
        these options work.
       </p><p>
        <code class="literal">sslmode</code> is ignored for Unix domain socket
        communication.
        If <span class="productname">PostgreSQL</span> is compiled without SSL support,
        using options <code class="literal">require</code>, <code class="literal">verify-ca</code>, or
        <code class="literal">verify-full</code> will cause an error, while
        options <code class="literal">allow</code> and <code class="literal">prefer</code> will be
        accepted but <span class="application">libpq</span> will not actually attempt
        an <acronym class="acronym">SSL</acronym>
        connection.<a id="id-1.7.3.8.4.2.1.22.2.2.10" class="indexterm"></a>
       </p><p>
        Note that if <acronym class="acronym">GSSAPI</acronym> encryption is possible,
        that will be used in preference to <acronym class="acronym">SSL</acronym>
        encryption, regardless of the value of <code class="literal">sslmode</code>.
        To force use of <acronym class="acronym">SSL</acronym> encryption in an
        environment that has working <acronym class="acronym">GSSAPI</acronym>
        infrastructure (such as a Kerberos server), also set
        <code class="literal">gssencmode</code> to <code class="literal">disable</code>.
       </p></dd><dt id="LIBPQ-CONNECT-REQUIRESSL"><span class="term"><code class="literal">requiressl</code></span> <a href="#LIBPQ-CONNECT-REQUIRESSL" class="id_link">#</a></dt><dd><p>
        This option is deprecated in favor of the <code class="literal">sslmode</code>
        setting.
       </p><p>
        If set to 1, an <acronym class="acronym">SSL</acronym> connection to the server
        is required (this is equivalent to <code class="literal">sslmode</code>
        <code class="literal">require</code>).  <span class="application">libpq</span> will then refuse
        to connect if the server does not accept an
        <acronym class="acronym">SSL</acronym> connection.  If set to 0 (default),
        <span class="application">libpq</span> will negotiate the connection type with
        the server (equivalent to <code class="literal">sslmode</code>
        <code class="literal">prefer</code>).  This option is only available if
        <span class="productname">PostgreSQL</span> is compiled with SSL support.
       </p></dd><dt id="LIBPQ-CONNECT-SSLNEGOTIATION"><span class="term"><code class="literal">sslnegotiation</code></span> <a href="#LIBPQ-CONNECT-SSLNEGOTIATION" class="id_link">#</a></dt><dd><p>
        This option controls how SSL encryption is negotiated with the server,
        if SSL is used. In the default <code class="literal">postgres</code> mode, the
        client first asks the server if SSL is supported. In
        <code class="literal">direct</code> mode, the client starts the standard SSL
        handshake directly after establishing the TCP/IP connection. Traditional
        <span class="productname">PostgreSQL</span> protocol negotiation is the most
        flexible with different server configurations. If the server is known
        to support direct <acronym class="acronym">SSL</acronym> connections then the latter
        requires one fewer round trip reducing connection latency and also
        allows the use of protocol agnostic SSL network tools. The direct SSL
        option was introduced in <span class="productname">PostgreSQL</span> version
        17.
       </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">postgres</code></span></dt><dd><p>
             perform <span class="productname">PostgreSQL</span> protocol
             negotiation. This is the default if the option is not provided.
           </p></dd><dt><span class="term"><code class="literal">direct</code></span></dt><dd><p>
            start SSL handshake directly after establishing the TCP/IP
            connection.  This is only allowed with
            <code class="literal">sslmode=require</code> or higher, because the weaker
            settings could lead to unintended fallback to plaintext
            authentication when the server does not support direct SSL
            handshake.
           </p></dd></dl></div></dd><dt id="LIBPQ-CONNECT-SSLCOMPRESSION"><span class="term"><code class="literal">sslcompression</code></span> <a href="#LIBPQ-CONNECT-SSLCOMPRESSION" class="id_link">#</a></dt><dd><p>
        If set to 1, data sent over SSL connections will be compressed.  If
        set to 0, compression will be disabled.  The default is 0.  This
        parameter is ignored if a connection without SSL is made.
       </p><p>
        SSL compression is nowadays considered insecure and its use is no
        longer recommended.  <span class="productname">OpenSSL</span> 1.1.0 disabled
        compression by default, and many operating system distributions
        disabled it in prior versions as well, so setting this parameter to on
        will not have any effect if the server does not accept compression.
        <span class="productname">PostgreSQL</span> 14 disabled compression
        completely in the backend.
       </p><p>
        If security is not a primary concern, compression can improve
        throughput if the network is the bottleneck.  Disabling compression
        can improve response time and throughput if CPU performance is the
        limiting factor.
       </p></dd><dt id="LIBPQ-CONNECT-SSLCERT"><span class="term"><code class="literal">sslcert</code></span> <a href="#LIBPQ-CONNECT-SSLCERT" class="id_link">#</a></dt><dd><p>
        This parameter specifies the file name of the client SSL
        certificate, replacing the default
        <code class="filename">~/.postgresql/postgresql.crt</code>.
        This parameter is ignored if an SSL connection is not made.
       </p></dd><dt id="LIBPQ-CONNECT-SSLKEY"><span class="term"><code class="literal">sslkey</code></span> <a href="#LIBPQ-CONNECT-SSLKEY" class="id_link">#</a></dt><dd><p>
        This parameter specifies the location for the secret key used for
        the client certificate. It can either specify a file name that will
        be used instead of the default
        <code class="filename">~/.postgresql/postgresql.key</code>, or it can specify a key
        obtained from an external <span class="quote">“<span class="quote">engine</span>”</span> (engines are
        <span class="productname">OpenSSL</span> loadable modules).  An external engine
        specification should consist of a colon-separated engine name and
        an engine-specific key identifier.  This parameter is ignored if an
        SSL connection is not made.
       </p></dd><dt id="LIBPQ-CONNECT-SSLKEYLOGFILE"><span class="term"><code class="literal">sslkeylogfile</code></span> <a href="#LIBPQ-CONNECT-SSLKEYLOGFILE" class="id_link">#</a></dt><dd><p>
        This parameter specifies the location where <span class="application">libpq</span>
        will log keys used in this SSL context.  This is useful for debugging
        <span class="productname">PostgreSQL</span> protocol interactions or client
        connections using network inspection tools like
        <span class="productname">Wireshark</span>.  This parameter is ignored if an
        SSL connection is not made, or if <span class="productname">LibreSSL</span>
        is used (<span class="productname">LibreSSL</span> does not support key
        logging).  Keys are logged using the <span class="productname">NSS</span>
        format.
        </p><div class="warning"><h3 class="title">Warning</h3><p>
          Key logging will expose potentially sensitive information in the
          keylog file.  Keylog files should be handled with the same care as
          <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLKEY">sslkey</a> files.
         </p></div><p>
       </p></dd><dt id="LIBPQ-CONNECT-SSLPASSWORD"><span class="term"><code class="literal">sslpassword</code></span> <a href="#LIBPQ-CONNECT-SSLPASSWORD" class="id_link">#</a></dt><dd><p>
        This parameter specifies the password for the secret key specified in
        <code class="literal">sslkey</code>, allowing client certificate private keys
        to be stored in encrypted form on disk even when interactive passphrase
        input is not practical.
       </p><p>
        Specifying this parameter with any non-empty value suppresses the
        <code class="literal">Enter PEM pass phrase:</code>
        prompt that <span class="productname">OpenSSL</span> will emit by default
        when an encrypted client certificate key is provided to
        <span class="application">libpq</span>.
       </p><p>
        If the key is not encrypted this parameter is ignored. The parameter
        has no effect on keys specified by <span class="productname">OpenSSL</span>
        engines unless the engine uses the <span class="productname">OpenSSL</span>
        password callback mechanism for prompts.
       </p><p>
        There is no environment variable equivalent to this option, and no
        facility for looking it up in <code class="filename">.pgpass</code>. It can be
        used in a service file connection definition. Users with
        more sophisticated uses should consider using <span class="productname">OpenSSL</span> engines and
        tools like PKCS#11 or USB crypto offload devices.
       </p></dd><dt id="LIBPQ-CONNECT-SSLCERTMODE"><span class="term"><code class="literal">sslcertmode</code></span> <a href="#LIBPQ-CONNECT-SSLCERTMODE" class="id_link">#</a></dt><dd><p>
        This option determines whether a client certificate may be sent to the
        server, and whether the server is required to request one. There are
        three modes:

        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
            A client certificate is never sent, even if one is available
            (default location or provided via
            <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCERT">sslcert</a>).
           </p></dd><dt><span class="term"><code class="literal">allow</code> (default)</span></dt><dd><p>
            A certificate may be sent, if the server requests one and the
            client has one to send.
           </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
            The server <span class="emphasis"><em>must</em></span> request a certificate. The
            connection will fail if the client does not send a certificate and
            the server successfully authenticates the client anyway.
           </p></dd></dl></div><p>
       </p><div class="note"><h3 class="title">Note</h3><p>
         <code class="literal">sslcertmode=require</code> doesn't add any additional
         security, since there is no guarantee that the server is validating
         the certificate correctly; PostgreSQL servers generally request TLS
         certificates from clients whether they validate them or not. The
         option may be useful when troubleshooting more complicated TLS
         setups.
        </p></div></dd><dt id="LIBPQ-CONNECT-SSLROOTCERT"><span class="term"><code class="literal">sslrootcert</code></span> <a href="#LIBPQ-CONNECT-SSLROOTCERT" class="id_link">#</a></dt><dd><p>
        This parameter specifies the name of a file containing SSL
        certificate authority (<acronym class="acronym">CA</acronym>) certificate(s).
        If the file exists, the server's certificate will be verified
        to be signed by one of these authorities.  The default is
        <code class="filename">~/.postgresql/root.crt</code>.
       </p><p>
        The special value <code class="literal">system</code> may be specified instead, in
        which case the trusted CA roots from the SSL implementation will be loaded. The exact
        locations of these root certificates differ by SSL implementation and
        platform. For <span class="productname">OpenSSL</span> in particular, the
        locations may be further modified by the <code class="envar">SSL_CERT_DIR</code>
        and <code class="envar">SSL_CERT_FILE</code> environment variables.
       </p><div class="note"><h3 class="title">Note</h3><p>
         When using <code class="literal">sslrootcert=system</code>, the default
         <code class="literal">sslmode</code> is changed to <code class="literal">verify-full</code>,
         and any weaker setting will result in an error. In most cases it is
         trivial for anyone to obtain a certificate trusted by the system for a
         hostname they control, rendering <code class="literal">verify-ca</code> and all
         weaker modes useless.
        </p><p>
         The magic <code class="literal">system</code> value will take precedence over a
         local certificate file with the same name. If for some reason you find
         yourself in this situation, use an alternative path like
         <code class="literal">sslrootcert=./system</code> instead.
        </p></div></dd><dt id="LIBPQ-CONNECT-SSLCRL"><span class="term"><code class="literal">sslcrl</code></span> <a href="#LIBPQ-CONNECT-SSLCRL" class="id_link">#</a></dt><dd><p>
        This parameter specifies the file name of the SSL server certificate
        revocation list (CRL).  Certificates listed in this file, if it
        exists, will be rejected while attempting to authenticate the
        server's certificate.  If neither
        <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRL">sslcrl</a> nor
        <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRLDIR">sslcrldir</a> is set, this setting is
        taken as
        <code class="filename">~/.postgresql/root.crl</code>.
       </p></dd><dt id="LIBPQ-CONNECT-SSLCRLDIR"><span class="term"><code class="literal">sslcrldir</code></span> <a href="#LIBPQ-CONNECT-SSLCRLDIR" class="id_link">#</a></dt><dd><p>
        This parameter specifies the directory name of the SSL server certificate
        revocation list (CRL).  Certificates listed in the files in this
        directory, if it exists, will be rejected while attempting to
        authenticate the server's certificate.
       </p><p>
        The directory needs to be prepared with the
        <span class="productname">OpenSSL</span> command
        <code class="literal">openssl rehash</code> or <code class="literal">c_rehash</code>.  See
        its documentation for details.
       </p><p>
        Both <code class="literal">sslcrl</code> and <code class="literal">sslcrldir</code> can be
        specified together.
       </p></dd><dt id="LIBPQ-CONNECT-SSLSNI"><span class="term"><code class="literal">sslsni</code><a id="id-1.7.3.8.4.2.1.34.1.2" class="indexterm"></a></span> <a href="#LIBPQ-CONNECT-SSLSNI" class="id_link">#</a></dt><dd><p>
        If set to 1 (default), libpq sets the TLS extension <span class="quote">“<span class="quote">Server Name
        Indication</span>”</span> (<acronym class="acronym">SNI</acronym>) on SSL-enabled connections.
        By setting this parameter to 0, this is turned off.
       </p><p>
        The Server Name Indication can be used by SSL-aware proxies to route
        connections without having to decrypt the SSL stream.  (Note that
        unless the proxy is aware of the PostgreSQL protocol handshake this
        would require setting <code class="literal">sslnegotiation</code>
        to <code class="literal">direct</code>.)
        However, <acronym class="acronym">SNI</acronym> makes the destination host name appear
        in cleartext in the network traffic, so it might be undesirable in
        some cases.
       </p></dd><dt id="LIBPQ-CONNECT-REQUIREPEER"><span class="term"><code class="literal">requirepeer</code></span> <a href="#LIBPQ-CONNECT-REQUIREPEER" class="id_link">#</a></dt><dd><p>
        This parameter specifies the operating-system user name of the
        server, for example <code class="literal">requirepeer=postgres</code>.
        When making a Unix-domain socket connection, if this
        parameter is set, the client checks at the beginning of the
        connection that the server process is running under the specified
        user name; if it is not, the connection is aborted with an error.
        This parameter can be used to provide server authentication similar
        to that available with SSL certificates on TCP/IP connections.
        (Note that if the Unix-domain socket is in
        <code class="filename">/tmp</code> or another publicly writable location,
        any user could start a server listening there.  Use this parameter
        to ensure that you are connected to a server run by a trusted user.)
        This option is only supported on platforms for which the
        <code class="literal">peer</code> authentication method is implemented; see
        <a class="xref" href="auth-peer.html" title="20.9. Peer Authentication">Section 20.9</a>.
       </p></dd><dt id="LIBPQ-CONNECT-SSL-MIN-PROTOCOL-VERSION"><span class="term"><code class="literal">ssl_min_protocol_version</code></span> <a href="#LIBPQ-CONNECT-SSL-MIN-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p>
        This parameter specifies the minimum SSL/TLS protocol version to allow
        for the connection. Valid values are <code class="literal">TLSv1</code>,
        <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and
        <code class="literal">TLSv1.3</code>. The supported protocols depend on the
        version of <span class="productname">OpenSSL</span> used, older versions
        not supporting the most modern protocol versions. If not specified,
        the default is <code class="literal">TLSv1.2</code>, which satisfies industry
        best practices as of this writing.
       </p></dd><dt id="LIBPQ-CONNECT-SSL-MAX-PROTOCOL-VERSION"><span class="term"><code class="literal">ssl_max_protocol_version</code></span> <a href="#LIBPQ-CONNECT-SSL-MAX-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p>
        This parameter specifies the maximum SSL/TLS protocol version to allow
        for the connection. Valid values are <code class="literal">TLSv1</code>,
        <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and
        <code class="literal">TLSv1.3</code>. The supported protocols depend on the
        version of <span class="productname">OpenSSL</span> used, older versions
        not supporting the most modern protocol versions. If not set, this
        parameter is ignored and the connection will use the maximum bound
        defined by the backend, if set. Setting the maximum protocol version
        is mainly useful for testing or if some component has issues working
        with a newer protocol.
       </p></dd><dt id="LIBPQ-CONNECT-MIN-PROTOCOL-VERSION"><span class="term"><code class="literal">min_protocol_version</code></span> <a href="#LIBPQ-CONNECT-MIN-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p>
        Specifies the minimum protocol version to allow for the connection.
        The default is to allow any version of the
        <span class="productname">PostgreSQL</span> protocol supported by libpq,
        which currently means <code class="literal">3.0</code>. If the server
        does not support at least this protocol version the connection will be
        closed.
       </p><p>
        The current supported values are
        <code class="literal">3.0</code>, <code class="literal">3.2</code>,
        and <code class="literal">latest</code>. The <code class="literal">latest</code> value is
        equivalent to the latest protocol version supported by the libpq
        version being used, which is currently <code class="literal">3.2</code>.
       </p></dd><dt id="LIBPQ-CONNECT-MAX-PROTOCOL-VERSION"><span class="term"><code class="literal">max_protocol_version</code></span> <a href="#LIBPQ-CONNECT-MAX-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p>
        Specifies the protocol version to request from the server.
        The default is to use version <code class="literal">3.0</code> of the
        <span class="productname">PostgreSQL</span> protocol, unless the connection
        string specifies a feature that relies on a higher protocol version,
        in which case the latest version supported by libpq is used. If the
        server does not support the protocol version requested by the client,
        the connection is automatically downgraded to a lower minor protocol
        version that the server supports. After the connection attempt has
        completed you can use <a class="xref" href="libpq-status.html#LIBPQ-PQFULLPROTOCOLVERSION"><code class="function">PQfullProtocolVersion</code></a> to
        find out which exact protocol version was negotiated.
       </p><p>
        The current supported values are
        <code class="literal">3.0</code>, <code class="literal">3.2</code>,
        and <code class="literal">latest</code>. The <code class="literal">latest</code> value is
        equivalent to the latest protocol version supported by the libpq
        version being used, which is currently <code class="literal">3.2</code>.
       </p></dd><dt id="LIBPQ-CONNECT-KRBSRVNAME"><span class="term"><code class="literal">krbsrvname</code></span> <a href="#LIBPQ-CONNECT-KRBSRVNAME" class="id_link">#</a></dt><dd><p>
        Kerberos service name to use when authenticating with GSSAPI.
        This must match the service name specified in the server
        configuration for Kerberos authentication to succeed. (See also
        <a class="xref" href="gssapi-auth.html" title="20.6. GSSAPI Authentication">Section 20.6</a>.)
        The default value is normally <code class="literal">postgres</code>,
        but that can be changed when
        building <span class="productname">PostgreSQL</span> via
        the <code class="option">--with-krb-srvnam</code> option
        of <span class="application">configure</span>.
        In most environments, this parameter never needs to be changed.
        Some Kerberos implementations might require a different service name,
        such as Microsoft Active Directory which requires the service name
        to be in upper case (<code class="literal">POSTGRES</code>).
       </p></dd><dt id="LIBPQ-CONNECT-GSSLIB"><span class="term"><code class="literal">gsslib</code></span> <a href="#LIBPQ-CONNECT-GSSLIB" class="id_link">#</a></dt><dd><p>
        GSS library to use for GSSAPI authentication.
        Currently this is disregarded except on Windows builds that include
        both GSSAPI and SSPI support.  In that case, set
        this to <code class="literal">gssapi</code> to cause libpq to use the GSSAPI
        library for authentication instead of the default SSPI.
       </p></dd><dt id="LIBPQ-CONNECT-GSSDELEGATION"><span class="term"><code class="literal">gssdelegation</code></span> <a href="#LIBPQ-CONNECT-GSSDELEGATION" class="id_link">#</a></dt><dd><p>
        Forward (delegate) GSS credentials to the server.  The default is
        <code class="literal">0</code> which means credentials will not be forwarded
        to the server.  Set this to <code class="literal">1</code> to have credentials
        forwarded when possible.
       </p></dd><dt id="LIBPQ-CONNECT-SCRAM-CLIENT-KEY"><span class="term"><code class="literal">scram_client_key</code></span> <a href="#LIBPQ-CONNECT-SCRAM-CLIENT-KEY" class="id_link">#</a></dt><dd><p>
        The base64-encoded SCRAM client key.  This can be used by foreign-data
        wrappers or similar middleware to enable pass-through SCRAM
        authentication. See <a class="xref" href="postgres-fdw.html#POSTGRES-FDW-OPTIONS-CONNECTION-MANAGEMENT" title="F.38.1.10. Connection Management Options">Section F.38.1.10</a> for one such
        implementation.  It is not meant to be specified directly by users or
        client applications.
       </p></dd><dt id="LIBPQ-CONNECT-SCRAM-SERVER-KEY"><span class="term"><code class="literal">scram_server_key</code></span> <a href="#LIBPQ-CONNECT-SCRAM-SERVER-KEY" class="id_link">#</a></dt><dd><p>
        The base64-encoded SCRAM server key.  This can be used by foreign-data
        wrappers or similar middleware to enable pass-through SCRAM
        authentication. See <a class="xref" href="postgres-fdw.html#POSTGRES-FDW-OPTIONS-CONNECTION-MANAGEMENT" title="F.38.1.10. Connection Management Options">Section F.38.1.10</a> for one such
        implementation.  It is not meant to be specified directly by users or
        client applications.
       </p></dd><dt id="LIBPQ-CONNECT-SERVICE"><span class="term"><code class="literal">service</code></span> <a href="#LIBPQ-CONNECT-SERVICE" class="id_link">#</a></dt><dd><p>
        Service name to use for additional parameters.  It specifies a service
        name in <code class="filename">pg_service.conf</code> that holds additional connection parameters.
        This allows applications to specify only a service name so connection parameters
        can be centrally maintained. See <a class="xref" href="libpq-pgservice.html" title="32.17. The Connection Service File">Section 32.17</a>.
       </p></dd><dt id="LIBPQ-CONNECT-TARGET-SESSION-ATTRS"><span class="term"><code class="literal">target_session_attrs</code></span> <a href="#LIBPQ-CONNECT-TARGET-SESSION-ATTRS" class="id_link">#</a></dt><dd><p>
        This option determines whether the session must have certain
        properties to be acceptable.  It's typically used in combination
        with multiple host names to select the first acceptable alternative
        among several hosts.  There are six modes:

        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">any</code> (default)</span></dt><dd><p>
            any successful connection is acceptable
           </p></dd><dt><span class="term"><code class="literal">read-write</code></span></dt><dd><p>
            session must accept read-write transactions by default (that
            is, the server must not be in hot standby mode and
            the <code class="varname">default_transaction_read_only</code> parameter
            must be <code class="literal">off</code>)
           </p></dd><dt><span class="term"><code class="literal">read-only</code></span></dt><dd><p>
            session must not accept read-write transactions by default (the
            converse)
           </p></dd><dt><span class="term"><code class="literal">primary</code></span></dt><dd><p>
            server must not be in hot standby mode
           </p></dd><dt><span class="term"><code class="literal">standby</code></span></dt><dd><p>
            server must be in hot standby mode
           </p></dd><dt><span class="term"><code class="literal">prefer-standby</code></span></dt><dd><p>
            first try to find a standby server, but if none of the listed
            hosts is a standby server, try again in <code class="literal">any</code>
            mode
           </p></dd></dl></div><p>
       </p></dd><dt id="LIBPQ-CONNECT-LOAD-BALANCE-HOSTS"><span class="term"><code class="literal">load_balance_hosts</code></span> <a href="#LIBPQ-CONNECT-LOAD-BALANCE-HOSTS" class="id_link">#</a></dt><dd><p>
        Controls the order in which the client tries to connect to the available
        hosts and addresses. Once a connection attempt is successful no other
        hosts and addresses will be tried. This parameter is typically used in
        combination with multiple host names or a DNS record that returns
        multiple IPs. This parameter can be used in combination with
        <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-TARGET-SESSION-ATTRS">target_session_attrs</a>
        to, for example, load balance over standby servers only. Once successfully
        connected, subsequent queries on the returned connection will all be
        sent to the same server. There are currently two modes:
        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code> (default)</span></dt><dd><p>
            No load balancing across hosts is performed.  Hosts are tried in
            the order in which they are provided and addresses are tried in
            the order they are received from DNS or a hosts file.
           </p></dd><dt><span class="term"><code class="literal">random</code></span></dt><dd><p>
            Hosts and addresses are tried in random order. This value is mostly
            useful when opening multiple connections at the same time, possibly
            from different machines. This way connections can be load balanced
            across multiple <span class="productname">PostgreSQL</span> servers.
           </p><p>
            While random load balancing, due to its random nature, will almost
            never result in a completely uniform distribution, it statistically
            gets quite close. One important aspect here is that this algorithm
            uses two levels of random choices: First the hosts
            will be resolved in random order. Then secondly, before resolving
            the next host, all resolved addresses for the current host will be
            tried in random order. This behaviour can skew the amount of
            connections each node gets greatly in certain cases, for instance
            when some hosts resolve to more addresses than others. But such a
            skew can also be used on purpose, e.g. to increase the number of
            connections a larger server gets by providing its hostname multiple
            times in the host string.
           </p><p>
            When using this value it's recommended to also configure a reasonable
            value for <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-CONNECT-TIMEOUT">connect_timeout</a>. Because then,
            if one of the nodes that are used for load balancing is not responding,
            a new node will be tried.
           </p></dd></dl></div><p>
       </p></dd><dt id="LIBPQ-CONNECT-OAUTH-ISSUER"><span class="term"><code class="literal">oauth_issuer</code></span> <a href="#LIBPQ-CONNECT-OAUTH-ISSUER" class="id_link">#</a></dt><dd><p>
        The HTTPS URL of a trusted issuer to contact if the server requests an
        OAuth token for the connection. This parameter is required for all OAuth
        connections; it should exactly match the <code class="literal">issuer</code>
        setting in <a class="link" href="auth-oauth.html" title="20.15. OAuth Authorization/Authentication">the server's HBA configuration</a>.
       </p><p>
        As part of the standard authentication handshake, <span class="application">libpq</span>
        will ask the server for a <span class="emphasis"><em>discovery document:</em></span> a URL
        providing a set of OAuth configuration parameters. The server must
        provide a URL that is directly constructed from the components of the
        <code class="literal">oauth_issuer</code>, and this value must exactly match the
        issuer identifier that is declared in the discovery document itself, or
        the connection will fail. This is required to prevent a class of
        <a class="ulink" href="https://mailarchive.ietf.org/arch/msg/oauth/JIVxFBGsJBVtm7ljwJhPUm3Fr-w/" target="_top">
        "mix-up attacks"</a> on OAuth clients.
       </p><p>
        You may also explicitly set <code class="literal">oauth_issuer</code> to the
        <code class="literal">/.well-known/</code> URI used for OAuth discovery. In this
        case, if the server asks for a different URL, the connection will fail,
        but a <a class="link" href="libpq-oauth.html#LIBPQ-OAUTH-AUTHDATA-HOOKS" title="32.20.1. Authdata Hooks">custom OAuth flow</a>
        may be able to speed up the standard handshake by using previously
        cached tokens. (In this case, it is recommended that
        <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-OAUTH-SCOPE">oauth_scope</a> be set as well, since the
        client will not have a chance to ask the server for a correct scope
        setting, and the default scopes for a token may not be sufficient to
        connect.) <span class="application">libpq</span> currently supports the
        following well-known endpoints:
        </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">/.well-known/openid-configuration</code></p></li><li class="listitem"><p><code class="literal">/.well-known/oauth-authorization-server</code></p></li></ul></div><p>
       </p><div class="warning"><h3 class="title">Warning</h3><p>
         Issuers are highly privileged during the OAuth connection handshake. As
         a rule of thumb, if you would not trust the operator of a URL to handle
         access to your servers, or to impersonate you directly, that URL should
         not be trusted as an <code class="literal">oauth_issuer</code>.
        </p></div></dd><dt id="LIBPQ-CONNECT-OAUTH-CLIENT-ID"><span class="term"><code class="literal">oauth_client_id</code></span> <a href="#LIBPQ-CONNECT-OAUTH-CLIENT-ID" class="id_link">#</a></dt><dd><p>
        An OAuth 2.0 client identifier, as issued by the authorization server.
        If the <span class="productname">PostgreSQL</span> server
        <a class="link" href="auth-oauth.html" title="20.15. OAuth Authorization/Authentication">requests an OAuth token</a> for the
        connection (and if no <a class="link" href="libpq-oauth.html#LIBPQ-OAUTH-AUTHDATA-HOOKS" title="32.20.1. Authdata Hooks">custom
        OAuth hook</a> is installed to provide one), then this parameter must
        be set; otherwise, the connection will fail.
       </p></dd><dt id="LIBPQ-CONNECT-OAUTH-CLIENT-SECRET"><span class="term"><code class="literal">oauth_client_secret</code></span> <a href="#LIBPQ-CONNECT-OAUTH-CLIENT-SECRET" class="id_link">#</a></dt><dd><p>
        The client password, if any, to use when contacting the OAuth
        authorization server. Whether this parameter is required or not is
        determined by the OAuth provider; "public" clients generally do not use
        a secret, whereas "confidential" clients generally do.
       </p></dd><dt id="LIBPQ-CONNECT-OAUTH-SCOPE"><span class="term"><code class="literal">oauth_scope</code></span> <a href="#LIBPQ-CONNECT-OAUTH-SCOPE" class="id_link">#</a></dt><dd><p>
        The scope of the access request sent to the authorization server,
        specified as a (possibly empty) space-separated list of OAuth scope
        identifiers. This parameter is optional and intended for advanced usage.
       </p><p>
        Usually the client will obtain appropriate scope settings from the
        <span class="productname">PostgreSQL</span> server. If this parameter is used,
        the server's requested scope list will be ignored. This can prevent a
        less-trusted server from requesting inappropriate access scopes from the
        end user. However, if the client's scope setting does not contain the
        server's required scopes, the server is likely to reject the issued
        token, and the connection will fail.
       </p><p>
        The meaning of an empty scope list is provider-dependent. An OAuth
        authorization server may choose to issue a token with "default scope",
        whatever that happens to be, or it may reject the token request
        entirely.
       </p></dd></dl></div><p>
   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 32. libpq — C Library">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-status.html" title="32.2. Connection Status Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 32. <span class="application">libpq</span> — C Library </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.2. Connection Status Functions</td></tr></table></div></body></html>