codekingpro/portable-devtools
114k
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->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">&...</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&application_name=myapp571postgresql://host1:123,host2:456/somedb?target_session_attrs=any&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&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