Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes14kdownloads
libpq-connect.html1262 linesDownload Raw Back to html
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.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 34. libpq — C Library" /><link rel="next" href="libpq-status.html" title="34.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">34.1. Database Connection Control Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 34. libpq — C Library">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-status.html" title="34.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">34.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">34.1.1. Connection Strings</a></span></dt><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">34.1.2. Parameter Key Words</a></span></dt></dl></div><p>3   The following functions deal with making a connection to a4   <span class="productname">PostgreSQL</span> backend server.  An5   application program can have several backend connections open at6   one time.  (One reason to do that is to access more than one7   database.)  Each connection is represented by a8   <code class="structname">PGconn</code><a id="id-1.7.3.8.2.3" class="indexterm"></a> object, which9   is obtained from the function <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>,10   <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, or11   <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a>.  Note that these functions will always12   return a non-null object pointer, unless perhaps there is too13   little memory even to allocate the <code class="structname">PGconn</code> object.14   The <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a> function should be called to check15   the return value for a successful connection before queries are sent16   via the connection object.17 18   </p><div class="warning"><h3 class="title">Warning</h3><p>19     If untrusted users have access to a database that has not adopted a20     <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage pattern</a>,21     begin each session by removing publicly-writable schemas from22     <code class="varname">search_path</code>.  One can set parameter key23     word <code class="literal">options</code> to24     value <code class="literal">-csearch_path=</code>.  Alternately, one can25     issue <code class="literal">PQexec(<em class="replaceable"><code>conn</code></em>, "SELECT26     pg_catalog.set_config('search_path', '', false)")</code> after27     connecting.  This consideration is not specific28     to <span class="application">libpq</span>; it applies to every interface for29     executing arbitrary SQL commands.30    </p></div><p>31 32   </p><div class="warning"><h3 class="title">Warning</h3><p>33     On Unix, forking a process with open libpq connections can lead to34     unpredictable results because the parent and child processes share35     the same sockets and operating system resources.  For this reason,36     such usage is not recommended, though doing an <code class="function">exec</code> from37     the child process to load a new executable is safe.38    </p></div><p>39 40   </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>41       Makes a new connection to the database server.42 43</p><pre class="synopsis">44PGconn *PQconnectdbParams(const char * const *keywords,45                          const char * const *values,46                          int expand_dbname);47</pre><p>48      </p><p>49       This function opens a new database connection using the parameters taken50       from two <code class="symbol">NULL</code>-terminated arrays. The first,51       <code class="literal">keywords</code>, is defined as an array of strings, each one52       being a key word. The second, <code class="literal">values</code>, gives the value53       for each key word. Unlike <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> below, the parameter54       set can be extended without changing the function signature, so use of55       this function (or its nonblocking analogs <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>56       and <code class="function">PQconnectPoll</code>) is preferred for new application57       programming.58      </p><p>59       The currently recognized parameter key words are listed in60       <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>.61      </p><p>62       The passed arrays can be empty to use all default parameters, or can63       contain one or more parameter settings. They must be matched in length.64       Processing will stop at the first <code class="symbol">NULL</code> entry65       in the <code class="literal">keywords</code> array.66       Also, if the <code class="literal">values</code> entry associated with a67       non-<code class="symbol">NULL</code> <code class="literal">keywords</code> entry is68       <code class="symbol">NULL</code> or an empty string, that entry is ignored and69       processing continues with the next pair of array entries.70      </p><p>71       When <code class="literal">expand_dbname</code> is non-zero, the value for72       the first <em class="parameter"><code>dbname</code></em> key word is checked to see73       if it is a <em class="firstterm">connection string</em>.  If so, it74       is <span class="quote">“<span class="quote">expanded</span>”</span> into the individual connection75       parameters extracted from the string.  The value is considered to76       be a connection string, rather than just a database name, if it77       contains an equal sign (<code class="literal">=</code>) or it begins with a78       URI scheme designator.  (More details on connection string formats79       appear in <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>.)  Only the first80       occurrence of <em class="parameter"><code>dbname</code></em> is treated in this way;81       any subsequent <em class="parameter"><code>dbname</code></em> parameter is processed82       as a plain database name.83      </p><p>84       In general the parameter arrays are processed from start to end.85       If any key word is repeated, the last value (that is86       not <code class="symbol">NULL</code> or empty) is used.  This rule applies in87       particular when a key word found in a connection string conflicts88       with one appearing in the <code class="literal">keywords</code> array.  Thus,89       the programmer may determine whether array entries can override or90       be overridden by values taken from a connection string.  Array91       entries appearing before an expanded <em class="parameter"><code>dbname</code></em>92       entry can be overridden by fields of the connection string, and in93       turn those fields are overridden by array entries appearing94       after <em class="parameter"><code>dbname</code></em> (but, again, only if those95       entries supply non-empty values).96      </p><p>97       After processing all the array entries and any expanded connection98       string, any connection parameters that remain unset are filled with99       default values.  If an unset parameter's corresponding environment100       variable (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>) is set, its value is101       used.  If the environment variable is not set either, then the102       parameter's built-in default value is used.103      </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>104       Makes a new connection to the database server.105 106</p><pre class="synopsis">107PGconn *PQconnectdb(const char *conninfo);108</pre><p>109      </p><p>110       This function opens a new database connection using the parameters taken111       from the string <code class="literal">conninfo</code>.112      </p><p>113       The passed string can be empty to use all default parameters, or it can114       contain one or more parameter settings separated by whitespace,115       or it can contain a <acronym class="acronym">URI</acronym>.116       See <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for details.117     </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>118       Makes a new connection to the database server.119</p><pre class="synopsis">120PGconn *PQsetdbLogin(const char *pghost,121                     const char *pgport,122                     const char *pgoptions,123                     const char *pgtty,124                     const char *dbName,125                     const char *login,126                     const char *pwd);127</pre><p>128       </p><p>129        This is the predecessor of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> with a fixed130        set of parameters.  It has the same functionality except that the131        missing parameters will always take on default values.  Write <code class="symbol">NULL</code> or an132        empty string for any one of the fixed parameters that is to be defaulted.133      </p><p>134        If the <em class="parameter"><code>dbName</code></em> contains135        an <code class="symbol">=</code> sign or has a valid connection <acronym class="acronym">URI</acronym> prefix, it136        is taken as a <em class="parameter"><code>conninfo</code></em> string in exactly the same way as137        if it had been passed to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and the remaining138        parameters are then applied as specified for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>.139      </p><p>140        <code class="literal">pgtty</code> is no longer used and any value passed will141        be ignored.142      </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>143   Makes a new connection to the database server.144</p><pre class="synopsis">145PGconn *PQsetdb(char *pghost,146                char *pgport,147                char *pgoptions,148                char *pgtty,149                char *dbName);150</pre><p>151     </p><p>152      This is a macro that calls <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> with null pointers153      for the <em class="parameter"><code>login</code></em> and <em class="parameter"><code>pwd</code></em> parameters.  It is provided154      for backward compatibility with very old programs.155     </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"><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>156       <a id="id-1.7.3.8.2.11.5.4.1.1" class="indexterm"></a>157       Make a connection to the database server in a nonblocking manner.158 159</p><pre class="synopsis">160PGconn *PQconnectStartParams(const char * const *keywords,161                             const char * const *values,162                             int expand_dbname);163 164PGconn *PQconnectStart(const char *conninfo);165 166PostgresPollingStatusType PQconnectPoll(PGconn *conn);167</pre><p>168      </p><p>169       These three functions are used to open a connection to a database server such170       that your application's thread of execution is not blocked on remote I/O171       whilst doing so. The point of this approach is that the waits for I/O to172       complete can occur in the application's main loop, rather than down inside173       <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 the174       application can manage this operation in parallel with other activities.175      </p><p>176       With <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, the database connection is made177       using the parameters taken from the <code class="literal">keywords</code> and178       <code class="literal">values</code> arrays, and controlled by <code class="literal">expand_dbname</code>,179       as described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>.180      </p><p>181       With <code class="function">PQconnectStart</code>, the database connection is made182       using the parameters taken from the string <code class="literal">conninfo</code> as183       described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.184      </p><p>185       Neither <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> nor <code class="function">PQconnectStart</code>186       nor <code class="function">PQconnectPoll</code> will block, so long as a number of187       restrictions are met:188       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>189          The <code class="literal">hostaddr</code> parameter must be used appropriately190          to prevent DNS queries from being made.  See the documentation of191          this parameter in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a> for details.192         </p></li><li class="listitem"><p>193          If you call <a class="xref" href="libpq-control.html#LIBPQ-PQTRACE"><code class="function">PQtrace</code></a>, ensure that the stream object194          into which you trace will not block.195         </p></li><li class="listitem"><p>196          You must ensure that the socket is in the appropriate state197          before calling <code class="function">PQconnectPoll</code>, as described below.198         </p></li></ul></div><p>199      </p><p>200       To begin a nonblocking connection request,201       call <code class="function">PQconnectStart</code>202       or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>.  If the result is null,203       then <span class="application">libpq</span> has been unable to allocate a204       new <code class="structname">PGconn</code> structure.  Otherwise, a205       valid <code class="structname">PGconn</code> pointer is returned (though not206       yet representing a valid connection to the database).  Next207       call <code class="literal">PQstatus(conn)</code>.  If the result208       is <code class="symbol">CONNECTION_BAD</code>, the connection attempt has already209       failed, typically because of invalid connection parameters.210      </p><p>211       If <code class="function">PQconnectStart</code>212       or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> succeeds, the next stage213       is to poll <span class="application">libpq</span> so that it can proceed with214       the connection sequence.215       Use <code class="function">PQsocket(conn)</code> to obtain the descriptor of the216       socket underlying the database connection.217       (Caution: do not assume that the socket remains the same218       across <code class="function">PQconnectPoll</code> calls.)219       Loop thus: If <code class="function">PQconnectPoll(conn)</code> last returned220       <code class="symbol">PGRES_POLLING_READING</code>, wait until the socket is ready to221       read (as indicated by <code class="function">select()</code>, <code class="function">poll()</code>, or222       similar system function).223       Then call <code class="function">PQconnectPoll(conn)</code> again.224       Conversely, if <code class="function">PQconnectPoll(conn)</code> last returned225       <code class="symbol">PGRES_POLLING_WRITING</code>, wait until the socket is ready226       to write, then call <code class="function">PQconnectPoll(conn)</code> again.227       On the first iteration, i.e., if you have yet to call228       <code class="function">PQconnectPoll</code>, behave as if it last returned229       <code class="symbol">PGRES_POLLING_WRITING</code>.  Continue this loop until230       <code class="function">PQconnectPoll(conn)</code> returns231       <code class="symbol">PGRES_POLLING_FAILED</code>, indicating the connection procedure232       has failed, or <code class="symbol">PGRES_POLLING_OK</code>, indicating the connection233       has been successfully made.234      </p><p>235       At any time during connection, the status of the connection can be236       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 the237       connection procedure has failed; if the call returns <code class="function">CONNECTION_OK</code>, then the238       connection is ready.  Both of these states are equally detectable239       from the return value of <code class="function">PQconnectPoll</code>, described above. Other states might also occur240       during (and only during) an asynchronous connection procedure. These241       indicate the current stage of the connection procedure and might be useful242       to provide feedback to the user for example. These statuses are:243 244       </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>245           Waiting for connection to be made.246          </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>247           Connection OK; waiting to send.248          </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>249           Waiting for a response from the server.250          </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>251           Received authentication; waiting for backend start-up to finish.252          </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>253           Negotiating SSL encryption.254          </p></dd><dt id="LIBPQ-CONNECTION-SETENV"><span class="term"><code class="symbol">CONNECTION_SETENV</code></span> <a href="#LIBPQ-CONNECTION-SETENV" class="id_link">#</a></dt><dd><p>255           Negotiating environment-driven parameter settings.256          </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>257           Checking if connection is able to handle write transactions.258          </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>259           Consuming any remaining response messages on connection.260          </p></dd></dl></div><p>261 262       Note that, although these constants will remain (in order to maintain263       compatibility), an application should never rely upon these occurring in a264       particular order, or at all, or on the status always being one of these265       documented values. An application might do something like this:266</p><pre class="programlisting">267switch(PQstatus(conn))268{269        case CONNECTION_STARTED:270            feedback = "Connecting...";271            break;272 273        case CONNECTION_MADE:274            feedback = "Connected to server...";275            break;276.277.278.279        default:280            feedback = "Connecting...";281}282</pre><p>283      </p><p>284       The <code class="literal">connect_timeout</code> connection parameter is ignored285       when using <code class="function">PQconnectPoll</code>; it is the application's286       responsibility to decide whether an excessive amount of time has elapsed.287       Otherwise, <code class="function">PQconnectStart</code> followed by a288       <code class="function">PQconnectPoll</code> loop is equivalent to289       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.290      </p><p>291       Note that when <code class="function">PQconnectStart</code>292       or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> returns a non-null293       pointer, you must call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> when you are294       finished with it, in order to dispose of the structure and any295       associated memory blocks.  This must be done even if the connection296       attempt fails or is abandoned.297      </p></dd><dt id="LIBPQ-PQCONNDEFAULTS"><span class="term"><code class="function">PQconndefaults</code><a id="id-1.7.3.8.2.11.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNDEFAULTS" class="id_link">#</a></dt><dd><p>298       Returns the default connection options.299</p><pre class="synopsis">300PQconninfoOption *PQconndefaults(void);301 302typedef struct303{304    char   *keyword;   /* The keyword of the option */305    char   *envvar;    /* Fallback environment variable name */306    char   *compiled;  /* Fallback compiled in default value */307    char   *val;       /* Option's current value, or NULL */308    char   *label;     /* Label for field in connect dialog */309    char   *dispchar;  /* Indicates how to display this field310                          in a connect dialog. Values are:311                          ""        Display entered value as is312                          "*"       Password field - hide value313                          "D"       Debug option - don't show by default */314    int     dispsize;  /* Field size in characters for dialog */315} PQconninfoOption;316</pre><p>317      </p><p>318       Returns a connection options array.  This can be used to determine319       all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and their320       current default values.  The return value points to an array of321       <code class="structname">PQconninfoOption</code> structures, which ends322       with an entry having a null <code class="structfield">keyword</code> pointer.  The323       null pointer is returned if memory could not be allocated. Note that324       the current default values (<code class="structfield">val</code> fields)325       will depend on environment variables and other context.  A326       missing or invalid service file will be silently ignored.  Callers327       must treat the connection options data as read-only.328      </p><p>329       After processing the options array, free it by passing it to330       <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>.  If this is not done, a small amount of memory331       is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a>.332      </p></dd><dt id="LIBPQ-PQCONNINFO"><span class="term"><code class="function">PQconninfo</code><a id="id-1.7.3.8.2.11.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNINFO" class="id_link">#</a></dt><dd><p>333       Returns the connection options used by a live connection.334</p><pre class="synopsis">335PQconninfoOption *PQconninfo(PGconn *conn);336</pre><p>337      </p><p>338       Returns a connection options array.  This can be used to determine339       all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and the340       values that were used to connect to the server. The return341       value points to an array of <code class="structname">PQconninfoOption</code>342       structures, which ends with an entry having a null <code class="structfield">keyword</code>343       pointer. All notes above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a> also344       apply to the result of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFO"><code class="function">PQconninfo</code></a>.345      </p></dd><dt id="LIBPQ-PQCONNINFOPARSE"><span class="term"><code class="function">PQconninfoParse</code><a id="id-1.7.3.8.2.11.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNINFOPARSE" class="id_link">#</a></dt><dd><p>346       Returns parsed connection options from the provided connection string.347 348</p><pre class="synopsis">349PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);350</pre><p>351      </p><p>352       Parses a connection string and returns the resulting options as an353       array; or returns <code class="symbol">NULL</code> if there is a problem with the connection354       string.  This function can be used to extract355       the <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options in the provided356       connection string.  The return value points to an array of357       <code class="structname">PQconninfoOption</code> structures, which ends358       with an entry having a null <code class="structfield">keyword</code> pointer.359      </p><p>360       All legal options will be present in the result array, but the361       <code class="literal">PQconninfoOption</code> for any option not present362       in the connection string will have <code class="literal">val</code> set to363       <code class="literal">NULL</code>; default values are not inserted.364      </p><p>365       If <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>, then <code class="literal">*errmsg</code> is set366       to <code class="symbol">NULL</code> on success, else to a <code class="function">malloc</code>'d error string explaining367       the problem.  (It is also possible for <code class="literal">*errmsg</code> to be368       set to <code class="symbol">NULL</code> and the function to return <code class="symbol">NULL</code>;369       this indicates an out-of-memory condition.)370      </p><p>371       After processing the options array, free it by passing it to372       <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>.  If this is not done, some memory373       is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFOPARSE"><code class="function">PQconninfoParse</code></a>.374       Conversely, if an error occurs and <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>,375       be sure to free the error string using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a>.376      </p></dd><dt id="LIBPQ-PQFINISH"><span class="term"><code class="function">PQfinish</code><a id="id-1.7.3.8.2.11.9.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFINISH" class="id_link">#</a></dt><dd><p>377       Closes  the  connection to the server.  Also frees378       memory used by the <code class="structname">PGconn</code> object.379</p><pre class="synopsis">380void PQfinish(PGconn *conn);381</pre><p>382      </p><p>383       Note that even if the server connection attempt fails (as384       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>385       to free the memory used by the <code class="structname">PGconn</code> object.386       The <code class="structname">PGconn</code> pointer must not be used again after387       <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> has been called.388      </p></dd><dt id="LIBPQ-PQRESET"><span class="term"><code class="function">PQreset</code><a id="id-1.7.3.8.2.11.10.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESET" class="id_link">#</a></dt><dd><p>389       Resets the communication channel to the server.390</p><pre class="synopsis">391void PQreset(PGconn *conn);392</pre><p>393      </p><p>394       This function will close the connection395       to the server and attempt to establish a new396       connection, using all the same397       parameters previously used.  This might be useful for398       error recovery if a working connection is lost.399      </p></dd><dt id="LIBPQ-PQRESETSTART"><span class="term"><code class="function">PQresetStart</code><a id="id-1.7.3.8.2.11.11.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQresetPoll</code><a id="id-1.7.3.8.2.11.11.2.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESETSTART" class="id_link">#</a></dt><dd><p>400       Reset the communication channel to the server, in a nonblocking manner.401 402</p><pre class="synopsis">403int PQresetStart(PGconn *conn);404 405PostgresPollingStatusType PQresetPoll(PGconn *conn);406</pre><p>407      </p><p>408       These functions will close the connection to the server and attempt to409       establish a new connection, using all the same410       parameters previously used. This can be useful for error recovery if a411       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 they412       act in a nonblocking manner. These functions suffer from the same413       restrictions as <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, <code class="function">PQconnectStart</code>414       and <code class="function">PQconnectPoll</code>.415      </p><p>416       To initiate a connection reset, call417       <a class="xref" href="libpq-connect.html#LIBPQ-PQRESETSTART"><code class="function">PQresetStart</code></a>. If it returns 0, the reset has418       failed. If it returns 1, poll the reset using419       <code class="function">PQresetPoll</code> in exactly the same way as you420       would create the connection using <code class="function">PQconnectPoll</code>.421      </p></dd><dt id="LIBPQ-PQPINGPARAMS"><span class="term"><code class="function">PQpingParams</code><a id="id-1.7.3.8.2.11.12.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPINGPARAMS" class="id_link">#</a></dt><dd><p>422       <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a> reports the status of the423       server.  It accepts connection parameters identical to those of424       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, described above.  It is not425       necessary to supply correct user name, password, or database name426       values to obtain the server status; however, if incorrect values427       are provided, the server will log a failed connection attempt.428 429</p><pre class="synopsis">430PGPing PQpingParams(const char * const *keywords,431                    const char * const *values,432                    int expand_dbname);433</pre><p>434 435       The function returns one of the following values:436 437       </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>438           The server is running and appears to be accepting connections.439          </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>440           The server is running but is in a state that disallows connections441           (startup, shutdown, or crash recovery).442          </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>443           The server could not be contacted.  This might indicate that the444           server is not running, or that there is something wrong with the445           given connection parameters (for example, wrong port number), or446           that there is a network connectivity problem (for example, a447           firewall blocking the connection request).448          </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>449           No attempt was made to contact the server, because the supplied450           parameters were obviously incorrect or there was some client-side451           problem (for example, out of memory).452          </p></dd></dl></div><p>453 454      </p></dd><dt id="LIBPQ-PQPING"><span class="term"><code class="function">PQping</code><a id="id-1.7.3.8.2.11.13.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPING" class="id_link">#</a></dt><dd><p>455       <a class="xref" href="libpq-connect.html#LIBPQ-PQPING"><code class="function">PQping</code></a> reports the status of the456       server.  It accepts connection parameters identical to those of457       <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, described above.  It is not458       necessary to supply correct user name, password, or database name459       values to obtain the server status; however, if incorrect values460       are provided, the server will log a failed connection attempt.461 462</p><pre class="synopsis">463PGPing PQping(const char *conninfo);464</pre><p>465      </p><p>466       The return values are the same as for <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a>.467      </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.14.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL" class="id_link">#</a></dt><dd><p>468       <code class="function">PQsetSSLKeyPassHook_OpenSSL</code> lets an application override469       <span class="application">libpq</span>'s <a class="link" href="libpq-ssl.html#LIBPQ-SSL-CLIENTCERT" title="34.19.2. Client Certificates">default470       handling of encrypted client certificate key files</a> using471       <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLPASSWORD">sslpassword</a> or interactive prompting.472 473</p><pre class="synopsis">474void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);475</pre><p>476 477       The application passes a pointer to a callback function with signature:478</p><pre class="programlisting">479int callback_fn(char *buf, int size, PGconn *conn);480</pre><p>481       which <span class="application">libpq</span> will then call482       <span class="emphasis"><em>instead of</em></span> its default483       <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> handler. The484       callback should determine the password for the key and copy it to485       result-buffer <em class="parameter"><code>buf</code></em> of size486       <em class="parameter"><code>size</code></em>. The string in <em class="parameter"><code>buf</code></em>487       must be null-terminated. The callback must return the length of the488       password stored in <em class="parameter"><code>buf</code></em> excluding the null489       terminator. On failure, the callback should set490       <code class="literal">buf[0] = '\0'</code> and return 0. See491       <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> in492       <span class="application">libpq</span>'s source code for an example.493      </p><p>494       If the user specified an explicit key location,495       its path will be in <code class="literal">conn-&gt;sslkey</code> when the callback496       is invoked. This will be empty if the default key path is being used.497       For keys that are engine specifiers, it is up to engine implementations498       whether they use the <span class="productname">OpenSSL</span> password499       callback or define their own handling.500      </p><p>501       The app callback may choose to delegate unhandled cases to502       <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code>,503       or call it first and try something else if it returns 0, or completely override it.504      </p><p>505       The callback <span class="emphasis"><em>must not</em></span> escape normal flow control with exceptions,506       <code class="function">longjmp(...)</code>, etc. It must return normally.507      </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.15.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETSSLKEYPASSHOOK-OPENSSL" class="id_link">#</a></dt><dd><p>508       <code class="function">PQgetSSLKeyPassHook_OpenSSL</code> returns the current509       client certificate key password hook, or <code class="literal">NULL</code>510       if none has been set.511 512</p><pre class="synopsis">513PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);514</pre><p>515      </p></dd></dl></div><p>516  </p><div class="sect2" id="LIBPQ-CONNSTRING"><div class="titlepage"><div><div><h3 class="title">34.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>517    Several <span class="application">libpq</span> functions parse a user-specified string to obtain518    connection parameters.  There are two accepted formats for these strings:519    plain keyword/value strings520    and URIs.  URIs generally follow521    <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc3986" target="_top">RFC522    3986</a>, except that multi-host connection strings are allowed523    as further described below.524   </p><div class="sect3" id="LIBPQ-CONNSTRING-KEYWORD-VALUE"><div class="titlepage"><div><div><h4 class="title">34.1.1.1. Keyword/Value Connection Strings <a href="#LIBPQ-CONNSTRING-KEYWORD-VALUE" class="id_link">#</a></h4></div></div></div><p>525    In the keyword/value format, each parameter setting is in the form526    <em class="replaceable"><code>keyword</code></em> <code class="literal">=</code>527    <em class="replaceable"><code>value</code></em>, with space(s) between settings.528    Spaces around a setting's equal sign are529    optional. To write an empty value, or a value containing spaces, surround it530    with single quotes, for example <code class="literal">keyword = 'a value'</code>.531    Single quotes and backslashes within532    a value must be escaped with a backslash, i.e., <code class="literal">\'</code> and533    <code class="literal">\\</code>.534   </p><p>535    Example:536</p><pre class="programlisting">537host=localhost port=5432 dbname=mydb connect_timeout=10538</pre><p>539   </p><p>540    The recognized parameter key words are listed in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>.541   </p></div><div class="sect3" id="LIBPQ-CONNSTRING-URIS"><div class="titlepage"><div><div><h4 class="title">34.1.1.2. Connection URIs <a href="#LIBPQ-CONNSTRING-URIS" class="id_link">#</a></h4></div></div></div><p>542   The general form for a connection <acronym class="acronym">URI</acronym> is:543</p><pre class="synopsis">544postgresql://[<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>]545 546<span class="phrase">where <em class="replaceable"><code>userspec</code></em> is:</span>547 548<em class="replaceable"><code>user</code></em>[<span class="optional">:<em class="replaceable"><code>password</code></em></span>]549 550<span class="phrase">and <em class="replaceable"><code>hostspec</code></em> is:</span>551 552[<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>]553 554<span class="phrase">and <em class="replaceable"><code>paramspec</code></em> is:</span>555 556<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>[<span class="optional">&amp;...</span>]557</pre><p>558   </p><p>559    The <acronym class="acronym">URI</acronym> scheme designator can be either560    <code class="literal">postgresql://</code> or <code class="literal">postgres://</code>.  Each561    of the remaining <acronym class="acronym">URI</acronym> parts is optional.  The562    following examples illustrate valid <acronym class="acronym">URI</acronym> syntax:563</p><pre class="programlisting">564postgresql://565postgresql://localhost566postgresql://localhost:5433567postgresql://localhost/mydb568postgresql://user@localhost569postgresql://user:secret@localhost570postgresql://other@localhost/otherdb?connect_timeout=10&amp;application_name=myapp571postgresql://host1:123,host2:456/somedb?target_session_attrs=any&amp;application_name=myapp572</pre><p>573    Values that would normally appear in the hierarchical part of574    the <acronym class="acronym">URI</acronym> can alternatively be given as named575    parameters.  For example:576</p><pre class="programlisting">577postgresql:///mydb?host=localhost&amp;port=5433578</pre><p>579    All named parameters must match key words listed in580    <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>, except that for compatibility581    with JDBC connection <acronym class="acronym">URI</acronym>s, instances582    of <code class="literal">ssl=true</code> are translated into583    <code class="literal">sslmode=require</code>.584   </p><p>585    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>586    if it includes symbols with special meaning in any of its parts.  Here is587    an example where the equal sign (<code class="literal">=</code>) is replaced with588    <code class="literal">%3D</code> and the space character with589    <code class="literal">%20</code>:590</p><pre class="programlisting">591postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff592</pre><p>593   </p><p>594    The host part may be either a host name or an IP address.  To specify an595    IPv6 address, enclose it in square brackets:596</p><pre class="synopsis">597postgresql://[2001:db8::1234]/database598</pre><p>599   </p><p>600    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 socket601    connection is chosen if the host part is either empty or looks like an602    absolute path name,603    otherwise a TCP/IP connection is initiated.  Note, however, that the604    slash is a reserved character in the hierarchical part of the URI.  So, to605    specify a non-standard Unix-domain socket directory, either omit the host606    part of the URI and specify the host as a named parameter, or607    percent-encode the path in the host part of the URI:608</p><pre class="programlisting">609postgresql:///dbname?host=/var/lib/postgresql610postgresql://%2Fvar%2Flib%2Fpostgresql/dbname611</pre><p>612   </p><p>613    It is possible to specify multiple host components, each with an optional614    port component, in a single URI.  A URI of the form615    <code class="literal">postgresql://host1:port1,host2:port2,host3:port3/</code>616    is equivalent to a connection string of the form617    <code class="literal">host=host1,host2,host3 port=port1,port2,port3</code>.618    As further described below, each619    host will be tried in turn until a connection is successfully established.620   </p></div><div class="sect3" id="LIBPQ-MULTIPLE-HOSTS"><div class="titlepage"><div><div><h4 class="title">34.1.1.3. Specifying Multiple Hosts <a href="#LIBPQ-MULTIPLE-HOSTS" class="id_link">#</a></h4></div></div></div><p>621       It is possible to specify multiple hosts to connect to, so that they are622       tried in the given order. In the Keyword/Value format, the <code class="literal">host</code>,623       <code class="literal">hostaddr</code>, and <code class="literal">port</code> options accept comma-separated624       lists of values. The same number of elements must be given in each625       option that is specified, such626       that e.g., the first <code class="literal">hostaddr</code> corresponds to the first host name,627       the second <code class="literal">hostaddr</code> corresponds to the second host name, and so628       forth. As an exception, if only one <code class="literal">port</code> is specified, it629       applies to all the hosts.630     </p><p>631       In the connection URI format, you can list multiple <code class="literal">host:port</code> pairs632       separated by commas in the <code class="literal">host</code> component of the URI.633     </p><p>634       In either format, a single host name can translate to multiple network635       addresses. A common example of this is a host that has both an IPv4 and636       an IPv6 address.637     </p><p>638       When multiple hosts are specified, or when a single host name is639       translated to multiple addresses,  all the hosts and addresses will be640       tried in order, until one succeeds. If none of the hosts can be reached,641       the connection fails. If a connection is established successfully, but642       authentication fails, the remaining hosts in the list are not tried.643     </p><p>644       If a password file is used, you can have different passwords for645       different hosts. All the other connection options are the same for every646       host in the list; it is not possible to e.g., specify different647       usernames for different hosts.648     </p></div></div><div class="sect2" id="LIBPQ-PARAMKEYWORDS"><div class="titlepage"><div><div><h3 class="title">34.1.2. Parameter Key Words <a href="#LIBPQ-PARAMKEYWORDS" class="id_link">#</a></h3></div></div></div><p>649    The currently recognized parameter key words are:650 651    </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>652        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 path653        name, it specifies Unix-domain communication rather than TCP/IP654        communication; the value is the name of the directory in which the655        socket file is stored.  (On Unix, an absolute path name begins with a656        slash.  On Windows, paths starting with drive letters are also657        recognized.)  If the host name starts with <code class="literal">@</code>, it is658        taken as a Unix-domain socket in the abstract namespace (currently659        supported on Linux and Windows).660        The default behavior when <code class="literal">host</code> is not661        specified, or is empty, is to connect to a Unix-domain662        socket<a id="id-1.7.3.8.4.2.1.1.2.1.4" class="indexterm"></a> in663        <code class="filename">/tmp</code> (or whatever socket directory was specified664        when <span class="productname">PostgreSQL</span> was built).  On Windows,665        the default is to connect to <code class="literal">localhost</code>.666       </p><p>667        A comma-separated list of host names is also accepted, in which case668        each host name in the list is tried in order; an empty item in the669        list selects the default behavior as explained above. See670        <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details.671       </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>672        Numeric IP address of host to connect to.  This should be in the673        standard IPv4 address format, e.g., <code class="literal">172.28.40.9</code>.  If674        your machine supports IPv6, you can also use those addresses.675        TCP/IP communication is676        always used when a nonempty string is specified for this parameter.677        If this parameter is not specified, the value of <code class="literal">host</code>678        will be looked up to find the corresponding IP address — or, if679        <code class="literal">host</code> specifies an IP address, that value will be680        used directly.681       </p><p>682        Using <code class="literal">hostaddr</code> allows the683        application to avoid a host name look-up, which might be important684        in applications with time constraints. However, a host name is685        required for GSSAPI or SSPI authentication686        methods, as well as for <code class="literal">verify-full</code> SSL687        certificate verification.  The following rules are used:688        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>689           If <code class="literal">host</code> is specified690           without <code class="literal">hostaddr</code>, a host name lookup occurs.691           (When using <code class="function">PQconnectPoll</code>, the lookup occurs692           when <code class="function">PQconnectPoll</code> first considers this host693           name, and it may cause <code class="function">PQconnectPoll</code> to block694           for a significant amount of time.)695          </p></li><li class="listitem"><p>696           If <code class="literal">hostaddr</code> is specified without <code class="literal">host</code>,697           the value for <code class="literal">hostaddr</code> gives the server network address.698           The connection attempt will fail if the authentication699           method requires a host name.700          </p></li><li class="listitem"><p>701           If both <code class="literal">host</code> and <code class="literal">hostaddr</code> are specified,702           the value for <code class="literal">hostaddr</code> gives the server network address.703           The value for <code class="literal">host</code> is ignored unless the704           authentication method requires it, in which case it will be705           used as the host name.706          </p></li></ul></div><p>707        Note that authentication is likely to fail if <code class="literal">host</code>708        is not the name of the server at network address <code class="literal">hostaddr</code>.709        Also, when both <code class="literal">host</code> and <code class="literal">hostaddr</code>710        are specified, <code class="literal">host</code>711        is used to identify the connection in a password file (see712        <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>).713       </p><p>714        A comma-separated list of <code class="literal">hostaddr</code> values is also715        accepted, in which case each host in the list is tried in order.716        An empty item in the list causes the corresponding host name to be717        used, or the default host name if that is empty as well. See718        <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details.719       </p><p>720        Without either a host name or host address,721        <span class="application">libpq</span> will connect using a local722        Unix-domain socket; or on Windows, it will attempt to connect to723        <code class="literal">localhost</code>.724       </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>725        Port number to connect to at the server host, or socket file726        name extension for Unix-domain727        connections.<a id="id-1.7.3.8.4.2.1.3.2.1.1" class="indexterm"></a>728        If multiple hosts were given in the <code class="literal">host</code> or729        <code class="literal">hostaddr</code> parameters, this parameter may specify a730        comma-separated list of ports of the same length as the host list, or731        it may specify a single port number to be used for all hosts.732        An empty string, or an empty item in a comma-separated list,733        specifies the default port number established734        when <span class="productname">PostgreSQL</span> was built.735       </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>736       The database name.  Defaults to be the same as the user name.737       In certain contexts, the value is checked for extended738       formats; see <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for more details on739       those.740      </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>741       <span class="productname">PostgreSQL</span> user name to connect as.742       Defaults to be the same as the operating system name of the user743       running the application.744      </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>745       Password to be used if the server demands password authentication.746      </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>747       Specifies the name of the file used to store passwords748       (see <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>).749       Defaults to <code class="filename">~/.pgpass</code>, or750       <code class="filename">%APPDATA%\postgresql\pgpass.conf</code> on Microsoft Windows.751       (No error is reported if this file does not exist.)752      </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>753        Specifies the authentication method that the client requires from the754        server. If the server does not use the required method to authenticate755        the client, or if the authentication handshake is not fully completed by756        the server, the connection will fail. A comma-separated list of methods757        may also be provided, of which the server must use exactly one in order758        for the connection to succeed. By default, any authentication method is759        accepted, and the server is free to skip authentication altogether.760      </p><p>761        Methods may be negated with the addition of a <code class="literal">!</code>762        prefix, in which case the server must <span class="emphasis"><em>not</em></span> attempt763        the listed method; any other method is accepted, and the server is free764        not to authenticate the client at all. If a comma-separated list is765        provided, the server may not attempt <span class="emphasis"><em>any</em></span> of the766        listed negated methods. Negated and non-negated forms may not be767        combined in the same setting.768      </p><p>769        As a final special case, the <code class="literal">none</code> method requires the770        server not to use an authentication challenge. (It may also be negated,771        to require some form of authentication.)772      </p><p>773        The following methods may be specified:774 775        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">password</code></span></dt><dd><p>776            The server must request plaintext password authentication.777           </p></dd><dt><span class="term"><code class="literal">md5</code></span></dt><dd><p>778            The server must request MD5 hashed password authentication.779           </p></dd><dt><span class="term"><code class="literal">gss</code></span></dt><dd><p>780            The server must either request a Kerberos handshake via781            <acronym class="acronym">GSSAPI</acronym> or establish a782            <acronym class="acronym">GSS</acronym>-encrypted channel (see also783            <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-GSSENCMODE">gssencmode</a>).784           </p></dd><dt><span class="term"><code class="literal">sspi</code></span></dt><dd><p>785            The server must request Windows <acronym class="acronym">SSPI</acronym>786            authentication.787           </p></dd><dt><span class="term"><code class="literal">scram-sha-256</code></span></dt><dd><p>788            The server must successfully complete a SCRAM-SHA-256 authentication789            exchange with the client.790           </p></dd><dt><span class="term"><code class="literal">none</code></span></dt><dd><p>791            The server must not prompt the client for an authentication792            exchange. (This does not prohibit client certificate authentication793            via TLS, nor GSS authentication via its encrypted transport.)794           </p></dd></dl></div><p>795      </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>796        This option controls the client's use of channel binding. A setting797        of <code class="literal">require</code> means that the connection must employ798        channel binding, <code class="literal">prefer</code> means that the client will799        choose channel binding if available, and <code class="literal">disable</code>800        prevents the use of channel binding. The default801        is <code class="literal">prefer</code> if802        <span class="productname">PostgreSQL</span> is compiled with SSL support;803        otherwise the default is <code class="literal">disable</code>.804      </p><p>805        Channel binding is a method for the server to authenticate itself to806        the client. It is only supported over SSL connections807        with <span class="productname">PostgreSQL</span> 11 or later servers using808        the <code class="literal">SCRAM</code> authentication method.809      </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>810       Maximum time to wait while connecting, in seconds (write as a decimal integer,811       e.g., <code class="literal">10</code>).  Zero, negative, or not specified means812       wait indefinitely.  The minimum allowed timeout is 2 seconds, therefore813       a value of <code class="literal">1</code> is interpreted as <code class="literal">2</code>.814       This timeout applies separately to each host name or IP address.815       For example, if you specify two hosts and <code class="literal">connect_timeout</code>816       is 5, each host will time out if no connection is made within 5817       seconds, so the total time spent waiting for a connection might be818       up to 10 seconds.819      </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>820       This sets the <code class="varname">client_encoding</code>821       configuration parameter for this connection.  In addition to822       the values accepted by the corresponding server option, you823       can use <code class="literal">auto</code> to determine the right824       encoding from the current locale in the client825       (<code class="envar">LC_CTYPE</code> environment variable on Unix826       systems).827      </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>828        Specifies command-line options to send to the server at connection829        start.  For example, setting this to <code class="literal">-c geqo=off</code> sets the830        session's value of the <code class="varname">geqo</code> parameter to831        <code class="literal">off</code>.  Spaces within this string are considered to832        separate command-line arguments, unless escaped with a backslash833        (<code class="literal">\</code>); write <code class="literal">\\</code> to represent a literal834        backslash.  For a detailed discussion of the available835        options, consult <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>.836       </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>837        Specifies a value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a>838        configuration parameter.839       </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>840        Specifies a fallback value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a> configuration parameter.841        This value will be used if no value has been given for842        <code class="literal">application_name</code> via a connection parameter or the843        <code class="envar">PGAPPNAME</code> environment variable.  Specifying844        a fallback name is useful in generic utility programs that845        wish to set a default application name but allow it to be846        overridden by the user.847       </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>848        Controls whether client-side TCP keepalives are used. The default849        value is 1, meaning on, but you can change this to 0, meaning off,850        if keepalives are not wanted.  This parameter is ignored for851        connections made via a Unix-domain socket.852       </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>853        Controls the number of seconds of inactivity after which TCP should854        send a keepalive message to the server.  A value of zero uses the855        system default. This parameter is ignored for connections made via a856        Unix-domain socket, or if keepalives are disabled.857        It is only supported on systems where <code class="symbol">TCP_KEEPIDLE</code> or858        an equivalent socket option is available, and on Windows; on other859        systems, it has no effect.860       </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>861        Controls the number of seconds after which a TCP keepalive message862        that is not acknowledged by the server should be retransmitted.  A863        value of zero uses the system default. This parameter is ignored for864        connections made via a Unix-domain socket, or if keepalives are disabled.865        It is only supported on systems where <code class="symbol">TCP_KEEPINTVL</code> or866        an equivalent socket option is available, and on Windows; on other867        systems, it has no effect.868       </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>869        Controls the number of TCP keepalives that can be lost before the870        client's connection to the server is considered dead.  A value of871        zero uses the system default. This parameter is ignored for872        connections made via a Unix-domain socket, or if keepalives are disabled.873        It is only supported on systems where <code class="symbol">TCP_KEEPCNT</code> or874        an equivalent socket option is available; on other systems, it has no875        effect.876       </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>877        Controls the number of milliseconds that transmitted data may878        remain unacknowledged before a connection is forcibly closed.879        A value of zero uses the system default. This parameter is880        ignored for connections made via a Unix-domain socket.881        It is only supported on systems where <code class="symbol">TCP_USER_TIMEOUT</code>882        is available; on other systems, it has no effect.883       </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>884       This option determines whether the connection should use the885       replication protocol instead of the normal protocol.  This is what886       PostgreSQL replication connections as well as tools such as887       <span class="application">pg_basebackup</span> use internally, but it can888       also be used by third-party applications.  For a description of the889       replication protocol, consult <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>.890      </p><p>891       The following values, which are case-insensitive, are supported:892       </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">893          <code class="literal">true</code>, <code class="literal">on</code>,894          <code class="literal">yes</code>, <code class="literal">1</code>895         </span></dt><dd><p>896           The connection goes into physical replication mode.897          </p></dd><dt><span class="term"><code class="literal">database</code></span></dt><dd><p>898           The connection goes into logical replication mode, connecting to899           the database specified in the <code class="literal">dbname</code> parameter.900          </p></dd><dt><span class="term">901          <code class="literal">false</code>, <code class="literal">off</code>,902          <code class="literal">no</code>, <code class="literal">0</code>903         </span></dt><dd><p>904           The connection is a regular one, which is the default behavior.905          </p></dd></dl></div><p>906      </p><p>907       In physical or logical replication mode, only the simple query protocol908       can be used.909      </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>910        This option determines whether or with what priority a secure911        <acronym class="acronym">GSS</acronym> TCP/IP connection will be negotiated with the912        server. There are three modes:913 914        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>915            only try a non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection916           </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>917            if there are <acronym class="acronym">GSSAPI</acronym> credentials present (i.e.,918            in a credentials cache), first try919            a <acronym class="acronym">GSSAPI</acronym>-encrypted connection; if that fails or920            there are no credentials, try a921            non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection.  This is the922            default when <span class="productname">PostgreSQL</span> has been923            compiled with <acronym class="acronym">GSSAPI</acronym> support.924           </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>925            only try a <acronym class="acronym">GSSAPI</acronym>-encrypted connection926           </p></dd></dl></div><p>927       </p><p>928        <code class="literal">gssencmode</code> is ignored for Unix domain socket929        communication.  If <span class="productname">PostgreSQL</span> is compiled930        without GSSAPI support, using the <code class="literal">require</code> option931        will cause an error, while <code class="literal">prefer</code> will be accepted932        but <span class="application">libpq</span> will not actually attempt933        a <acronym class="acronym">GSSAPI</acronym>-encrypted934        connection.<a id="id-1.7.3.8.4.2.1.21.2.2.7" class="indexterm"></a>935       </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>936        This option determines whether or with what priority a secure937        <acronym class="acronym">SSL</acronym> TCP/IP connection will be negotiated with the938        server. There are six modes:939 940        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>941            only try a non-<acronym class="acronym">SSL</acronym> connection942           </p></dd><dt><span class="term"><code class="literal">allow</code></span></dt><dd><p>943            first try a non-<acronym class="acronym">SSL</acronym> connection; if that944            fails, try an <acronym class="acronym">SSL</acronym> connection945           </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>946            first try an <acronym class="acronym">SSL</acronym> connection; if that fails,947            try a non-<acronym class="acronym">SSL</acronym> connection948           </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>949            only try an <acronym class="acronym">SSL</acronym> connection. If a root CA950            file is present, verify the certificate in the same way as951            if <code class="literal">verify-ca</code> was specified952           </p></dd><dt><span class="term"><code class="literal">verify-ca</code></span></dt><dd><p>953            only try an <acronym class="acronym">SSL</acronym> connection, and verify that954            the server certificate is issued by a trusted955            certificate authority (<acronym class="acronym">CA</acronym>)956           </p></dd><dt><span class="term"><code class="literal">verify-full</code></span></dt><dd><p>957            only try an <acronym class="acronym">SSL</acronym> connection, verify that the958            server certificate is issued by a959            trusted <acronym class="acronym">CA</acronym> and that the requested server host name960            matches that in the certificate961           </p></dd></dl></div><p>962 963        See <a class="xref" href="libpq-ssl.html" title="34.19. SSL Support">Section 34.19</a> for a detailed description of how964        these options work.965       </p><p>966        <code class="literal">sslmode</code> is ignored for Unix domain socket967        communication.968        If <span class="productname">PostgreSQL</span> is compiled without SSL support,969        using options <code class="literal">require</code>, <code class="literal">verify-ca</code>, or970        <code class="literal">verify-full</code> will cause an error, while971        options <code class="literal">allow</code> and <code class="literal">prefer</code> will be972        accepted but <span class="application">libpq</span> will not actually attempt973        an <acronym class="acronym">SSL</acronym>974        connection.<a id="id-1.7.3.8.4.2.1.22.2.2.10" class="indexterm"></a>975       </p><p>976        Note that if <acronym class="acronym">GSSAPI</acronym> encryption is possible,977        that will be used in preference to <acronym class="acronym">SSL</acronym>978        encryption, regardless of the value of <code class="literal">sslmode</code>.979        To force use of <acronym class="acronym">SSL</acronym> encryption in an980        environment that has working <acronym class="acronym">GSSAPI</acronym>981        infrastructure (such as a Kerberos server), also982        set <code class="literal">gssencmode</code> to <code class="literal">disable</code>.983       </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>984        This option is deprecated in favor of the <code class="literal">sslmode</code>985        setting.986       </p><p>987        If set to 1, an <acronym class="acronym">SSL</acronym> connection to the server988        is required (this is equivalent to <code class="literal">sslmode</code>989        <code class="literal">require</code>).  <span class="application">libpq</span> will then refuse990        to connect if the server does not accept an991        <acronym class="acronym">SSL</acronym> connection.  If set to 0 (default),992        <span class="application">libpq</span> will negotiate the connection type with993        the server (equivalent to <code class="literal">sslmode</code>994        <code class="literal">prefer</code>).  This option is only available if995        <span class="productname">PostgreSQL</span> is compiled with SSL support.996       </p></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>997        If set to 1, data sent over SSL connections will be compressed.  If998        set to 0, compression will be disabled.  The default is 0.  This999        parameter is ignored if a connection without SSL is made.1000       </p><p>1001        SSL compression is nowadays considered insecure and its use is no1002        longer recommended.  <span class="productname">OpenSSL</span> 1.1.0 disables1003        compression by default, and many operating system distributions1004        disable it in prior versions as well, so setting this parameter to on1005        will not have any effect if the server does not accept compression.1006        <span class="productname">PostgreSQL</span> 14 disables compression1007        completely in the backend.1008       </p><p>1009        If security is not a primary concern, compression can improve1010        throughput if the network is the bottleneck.  Disabling compression1011        can improve response time and throughput if CPU performance is the1012        limiting factor.1013       </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>1014        This parameter specifies the file name of the client SSL1015        certificate, replacing the default1016        <code class="filename">~/.postgresql/postgresql.crt</code>.1017        This parameter is ignored if an SSL connection is not made.1018       </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>1019        This parameter specifies the location for the secret key used for1020        the client certificate. It can either specify a file name that will1021        be used instead of the default1022        <code class="filename">~/.postgresql/postgresql.key</code>, or it can specify a key1023        obtained from an external <span class="quote">“<span class="quote">engine</span>”</span> (engines are1024        <span class="productname">OpenSSL</span> loadable modules).  An external engine1025        specification should consist of a colon-separated engine name and1026        an engine-specific key identifier.  This parameter is ignored if an1027        SSL connection is not made.1028       </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>1029        This parameter specifies the password for the secret key specified in1030        <code class="literal">sslkey</code>, allowing client certificate private keys1031        to be stored in encrypted form on disk even when interactive passphrase1032        input is not practical.1033       </p><p>1034        Specifying this parameter with any non-empty value suppresses the1035        <code class="literal">Enter PEM pass phrase:</code>1036        prompt that <span class="productname">OpenSSL</span> will emit by default1037        when an encrypted client certificate key is provided to1038        <code class="literal">libpq</code>.1039       </p><p>1040        If the key is not encrypted this parameter is ignored. The parameter1041        has no effect on keys specified by <span class="productname">OpenSSL</span>1042        engines unless the engine uses the <span class="productname">OpenSSL</span>1043        password callback mechanism for prompts.1044       </p><p>1045        There is no environment variable equivalent to this option, and no1046        facility for looking it up in <code class="filename">.pgpass</code>. It can be1047        used in a service file connection definition. Users with1048        more sophisticated uses should consider using <span class="productname">OpenSSL</span> engines and1049        tools like PKCS#11 or USB crypto offload devices.1050       </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>1051        This option determines whether a client certificate may be sent to the1052        server, and whether the server is required to request one. There are1053        three modes:1054 1055        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>1056            A client certificate is never sent, even if one is available1057            (default location or provided via1058            <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCERT">sslcert</a>).1059           </p></dd><dt><span class="term"><code class="literal">allow</code> (default)</span></dt><dd><p>1060            A certificate may be sent, if the server requests one and the1061            client has one to send.1062           </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>1063            The server <span class="emphasis"><em>must</em></span> request a certificate. The1064            connection will fail if the client does not send a certificate and1065            the server successfully authenticates the client anyway.1066           </p></dd></dl></div><p>1067       </p><div class="note"><h3 class="title">Note</h3><p>1068         <code class="literal">sslcertmode=require</code> doesn't add any additional1069         security, since there is no guarantee that the server is validating1070         the certificate correctly; PostgreSQL servers generally request TLS1071         certificates from clients whether they validate them or not. The1072         option may be useful when troubleshooting more complicated TLS1073         setups.1074        </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>1075        This parameter specifies the name of a file containing SSL1076        certificate authority (<acronym class="acronym">CA</acronym>) certificate(s).1077        If the file exists, the server's certificate will be verified1078        to be signed by one of these authorities.  The default is1079        <code class="filename">~/.postgresql/root.crt</code>.1080       </p><p>1081        The special value <code class="literal">system</code> may be specified instead, in1082        which case the system's trusted CA roots will be loaded. The exact1083        locations of these root certificates differ by SSL implementation and1084        platform. For <span class="productname">OpenSSL</span> in particular, the1085        locations may be further modified by the <code class="envar">SSL_CERT_DIR</code>1086        and <code class="envar">SSL_CERT_FILE</code> environment variables.1087       </p><div class="note"><h3 class="title">Note</h3><p>1088         When using <code class="literal">sslrootcert=system</code>, the default1089         <code class="literal">sslmode</code> is changed to <code class="literal">verify-full</code>,1090         and any weaker setting will result in an error. In most cases it is1091         trivial for anyone to obtain a certificate trusted by the system for a1092         hostname they control, rendering <code class="literal">verify-ca</code> and all1093         weaker modes useless.1094        </p><p>1095         The magic <code class="literal">system</code> value will take precedence over a1096         local certificate file with the same name. If for some reason you find1097         yourself in this situation, use an alternative path like1098         <code class="literal">sslrootcert=./system</code> instead.1099        </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>1100        This parameter specifies the file name of the SSL server certificate1101        revocation list (CRL).  Certificates listed in this file, if it1102        exists, will be rejected while attempting to authenticate the1103        server's certificate.  If neither1104        <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRL">sslcrl</a> nor1105        <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRLDIR">sslcrldir</a> is set, this setting is1106        taken as1107        <code class="filename">~/.postgresql/root.crl</code>.1108       </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>1109        This parameter specifies the directory name of the SSL server certificate1110        revocation list (CRL).  Certificates listed in the files in this1111        directory, if it exists, will be rejected while attempting to1112        authenticate the server's certificate.1113       </p><p>1114        The directory needs to be prepared with the1115        <span class="productname">OpenSSL</span> command1116        <code class="literal">openssl rehash</code> or <code class="literal">c_rehash</code>.  See1117        its documentation for details.1118       </p><p>1119        Both <code class="literal">sslcrl</code> and <code class="literal">sslcrldir</code> can be1120        specified together.1121       </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.32.1.2" class="indexterm"></a></span> <a href="#LIBPQ-CONNECT-SSLSNI" class="id_link">#</a></dt><dd><p>1122        If set to 1 (default), libpq sets the TLS extension <span class="quote">“<span class="quote">Server Name1123        Indication</span>”</span> (<acronym class="acronym">SNI</acronym>) on SSL-enabled connections.1124        By setting this parameter to 0, this is turned off.1125       </p><p>1126        The Server Name Indication can be used by SSL-aware proxies to route1127        connections without having to decrypt the SSL stream.  (Note that this1128        requires a proxy that is aware of the PostgreSQL protocol handshake,1129        not just any SSL proxy.)  However, <acronym class="acronym">SNI</acronym> makes the1130        destination host name appear in cleartext in the network traffic, so1131        it might be undesirable in some cases.1132       </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>1133        This parameter specifies the operating-system user name of the1134        server, for example <code class="literal">requirepeer=postgres</code>.1135        When making a Unix-domain socket connection, if this1136        parameter is set, the client checks at the beginning of the1137        connection that the server process is running under the specified1138        user name; if it is not, the connection is aborted with an error.1139        This parameter can be used to provide server authentication similar1140        to that available with SSL certificates on TCP/IP connections.1141        (Note that if the Unix-domain socket is in1142        <code class="filename">/tmp</code> or another publicly writable location,1143        any user could start a server listening there.  Use this parameter1144        to ensure that you are connected to a server run by a trusted user.)1145        This option is only supported on platforms for which the1146        <code class="literal">peer</code> authentication method is implemented; see1147        <a class="xref" href="auth-peer.html" title="21.9. Peer Authentication">Section 21.9</a>.1148       </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>1149        This parameter specifies the minimum SSL/TLS protocol version to allow1150        for the connection. Valid values are <code class="literal">TLSv1</code>,1151        <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and1152        <code class="literal">TLSv1.3</code>. The supported protocols depend on the1153        version of <span class="productname">OpenSSL</span> used, older versions1154        not supporting the most modern protocol versions. If not specified,1155        the default is <code class="literal">TLSv1.2</code>, which satisfies industry1156        best practices as of this writing.1157       </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>1158        This parameter specifies the maximum SSL/TLS protocol version to allow1159        for the connection. Valid values are <code class="literal">TLSv1</code>,1160        <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and1161        <code class="literal">TLSv1.3</code>. The supported protocols depend on the1162        version of <span class="productname">OpenSSL</span> used, older versions1163        not supporting the most modern protocol versions. If not set, this1164        parameter is ignored and the connection will use the maximum bound1165        defined by the backend, if set. Setting the maximum protocol version1166        is mainly useful for testing or if some component has issues working1167        with a newer protocol.1168       </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>1169        Kerberos service name to use when authenticating with GSSAPI.1170        This must match the service name specified in the server1171        configuration for Kerberos authentication to succeed. (See also1172        <a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a>.)1173        The default value is normally <code class="literal">postgres</code>,1174        but that can be changed when1175        building <span class="productname">PostgreSQL</span> via1176        the <code class="option">--with-krb-srvnam</code> option1177        of <span class="application">configure</span>.1178        In most environments, this parameter never needs to be changed.1179        Some Kerberos implementations might require a different service name,1180        such as Microsoft Active Directory which requires the service name1181        to be in upper case (<code class="literal">POSTGRES</code>).1182       </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>1183        GSS library to use for GSSAPI authentication.1184        Currently this is disregarded except on Windows builds that include1185        both GSSAPI and SSPI support.  In that case, set1186        this to <code class="literal">gssapi</code> to cause libpq to use the GSSAPI1187        library for authentication instead of the default SSPI.1188       </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>1189        Forward (delegate) GSS credentials to the server.  The default is1190        <code class="literal">0</code> which means credentials will not be forwarded1191        to the server.  Set this to <code class="literal">1</code> to have credentials1192        forwarded when possible.1193       </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>1194        Service name to use for additional parameters.  It specifies a service1195        name in <code class="filename">pg_service.conf</code> that holds additional connection parameters.1196        This allows applications to specify only a service name so connection parameters1197        can be centrally maintained. See <a class="xref" href="libpq-pgservice.html" title="34.17. The Connection Service File">Section 34.17</a>.1198       </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>1199        This option determines whether the session must have certain1200        properties to be acceptable.  It's typically used in combination

Showing the first 1,200 of 1262 lines. Download the file for the rest.

codekingpro/portable-devtools · Team Ai