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>32.1. Database Connection Control Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq.html" title="Chapter 32. libpq — C Library" /><link rel="next" href="libpq-status.html" title="32.2. Connection Status Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.1. Database Connection Control Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 32. libpq — C Library">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-status.html" title="32.2. Connection Status Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-CONNECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.1. Database Connection Control Functions <a href="#LIBPQ-CONNECT" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-CONNSTRING">32.1.1. Connection Strings</a></span></dt><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">32.1.2. Parameter Key Words</a></span></dt></dl></div><p>
3 The following functions deal with making a connection to a
4 <span class="productname">PostgreSQL</span> backend server. An
5 application program can have several backend connections open at
6 one time. (One reason to do that is to access more than one
7 database.) Each connection is represented by a
8 <code class="structname">PGconn</code><a id="id-1.7.3.8.2.3" class="indexterm"></a> object, which
9 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>, or
11 <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a>. Note that these functions will always
12 return a non-null object pointer, unless perhaps there is too
13 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 check
15 the return value for a successful connection before queries are sent
16 via the connection object.
18 </p><div class="warning"><h3 class="title">Warning</h3><p>
19 If untrusted users have access to a database that has not adopted a
20 <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.10.6. Usage Patterns">secure schema usage pattern</a>,
21 begin each session by removing publicly-writable schemas from
22 <code class="varname">search_path</code>. One can set parameter key
23 word <code class="literal">options</code> to
24 value <code class="literal">-csearch_path=</code>. Alternately, one can
25 issue <code class="literal">PQexec(<em class="replaceable"><code>conn</code></em>, "SELECT
26 pg_catalog.set_config('search_path', '', false)")</code> after
27 connecting. This consideration is not specific
28 to <span class="application">libpq</span>; it applies to every interface for
29 executing arbitrary SQL commands.
32 </p><div class="warning"><h3 class="title">Warning</h3><p>
33 On Unix, forking a process with open libpq connections can lead to
34 unpredictable results because the parent and child processes share
35 the same sockets and operating system resources. For this reason,
36 such usage is not recommended, though doing an <code class="function">exec</code> from
37 the child process to load a new executable is safe.
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.
43 </p><pre class="synopsis">
44 PGconn *PQconnectdbParams(const char * const *keywords,
45 const char * const *values,
49 This function opens a new database connection using the parameters taken
50 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 one
52 being a key word. The second, <code class="literal">values</code>, gives the value
53 for each key word. Unlike <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> below, the parameter
54 set can be extended without changing the function signature, so use of
55 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 application
59 The currently recognized parameter key words are listed in
60 <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="32.1.2. Parameter Key Words">Section 32.1.2</a>.
62 The passed arrays can be empty to use all default parameters, or can
63 contain one or more parameter settings. They must be matched in length.
64 Processing will stop at the first <code class="symbol">NULL</code> entry
65 in the <code class="literal">keywords</code> array.
66 Also, if the <code class="literal">values</code> entry associated with a
67 non-<code class="symbol">NULL</code> <code class="literal">keywords</code> entry is
68 <code class="symbol">NULL</code> or an empty string, that entry is ignored and
69 processing continues with the next pair of array entries.
71 When <code class="literal">expand_dbname</code> is non-zero, the value for
72 the first <em class="parameter"><code>dbname</code></em> key word is checked to see
73 if it is a <em class="firstterm">connection string</em>. If so, it
74 is <span class="quote">“<span class="quote">expanded</span>”</span> into the individual connection
75 parameters extracted from the string. The value is considered to
76 be a connection string, rather than just a database name, if it
77 contains an equal sign (<code class="literal">=</code>) or it begins with a
78 URI scheme designator. (More details on connection string formats
79 appear in <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">Section 32.1.1</a>.) Only the first
80 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 processed
82 as a plain database name.
84 In general the parameter arrays are processed from start to end.
85 If any key word is repeated, the last value (that is
86 not <code class="symbol">NULL</code> or empty) is used. This rule applies in
87 particular when a key word found in a connection string conflicts
88 with one appearing in the <code class="literal">keywords</code> array. Thus,
89 the programmer may determine whether array entries can override or
90 be overridden by values taken from a connection string. Array
91 entries appearing before an expanded <em class="parameter"><code>dbname</code></em>
92 entry can be overridden by fields of the connection string, and in
93 turn those fields are overridden by array entries appearing
94 after <em class="parameter"><code>dbname</code></em> (but, again, only if those
95 entries supply non-empty values).
97 After processing all the array entries and any expanded connection
98 string, any connection parameters that remain unset are filled with
99 default values. If an unset parameter's corresponding environment
100 variable (see <a class="xref" href="libpq-envars.html" title="32.15. Environment Variables">Section 32.15</a>) is set, its value is
101 used. If the environment variable is not set either, then the
102 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.
106 </p><pre class="synopsis">
107 PGconn *PQconnectdb(const char *conninfo);
110 This function opens a new database connection using the parameters taken
111 from the string <code class="literal">conninfo</code>.
113 The passed string can be empty to use all default parameters, or it can
114 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="32.1.1. Connection Strings">Section 32.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">
120 PGconn *PQsetdbLogin(const char *pghost,
122 const char *pgoptions,
129 This is the predecessor of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> with a fixed
130 set of parameters. It has the same functionality except that the
131 missing parameters will always take on default values. Write <code class="symbol">NULL</code> or an
132 empty string for any one of the fixed parameters that is to be defaulted.
134 If the <em class="parameter"><code>dbName</code></em> contains
135 an <code class="symbol">=</code> sign or has a valid connection <acronym class="acronym">URI</acronym> prefix, it
136 is taken as a <em class="parameter"><code>conninfo</code></em> string in exactly the same way as
137 if it had been passed to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and the remaining
138 parameters are then applied as specified for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>.
140 <code class="literal">pgtty</code> is no longer used and any value passed will
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">
145 PGconn *PQsetdb(char *pghost,
152 This is a macro that calls <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> with null pointers
153 for the <em class="parameter"><code>login</code></em> and <em class="parameter"><code>pwd</code></em> parameters. It is provided
154 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" id="LIBPQ-PQCONNECTPOLL"><code class="function">PQconnectPoll</code><a id="id-1.7.3.8.2.11.5.3.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTSTARTPARAMS" class="id_link">#</a></dt><dd><p>
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.
159 </p><pre class="synopsis">
160 PGconn *PQconnectStartParams(const char * const *keywords,
161 const char * const *values,
164 PGconn *PQconnectStart(const char *conninfo);
166 PostgresPollingStatusType PQconnectPoll(PGconn *conn);
169 These three functions are used to open a connection to a database server such
170 that your application's thread of execution is not blocked on remote I/O
171 whilst doing so. The point of this approach is that the waits for I/O to
172 complete can occur in the application's main loop, rather than down inside
173 <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a> or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and so the
174 application can manage this operation in parallel with other activities.
176 With <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, the database connection is made
177 using the parameters taken from the <code class="literal">keywords</code> and
178 <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>.
181 With <code class="function">PQconnectStart</code>, the database connection is made
182 using the parameters taken from the string <code class="literal">conninfo</code> as
183 described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
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 of
187 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 appropriately
190 to prevent DNS queries from being made. See the documentation of
191 this parameter in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="32.1.2. Parameter Key Words">Section 32.1.2</a> for details.
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 object
194 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 state
197 before calling <code class="function">PQconnectPoll</code>, as described below.
198 </p></li></ul></div><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 a
204 new <code class="structname">PGconn</code> structure. Otherwise, a
205 valid <code class="structname">PGconn</code> pointer is returned (though not
206 yet representing a valid connection to the database). Next
207 call <code class="literal">PQstatus(conn)</code>. If the result
208 is <code class="symbol">CONNECTION_BAD</code>, the connection attempt has already
209 failed, typically because of invalid connection parameters.
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 stage
213 is to poll <span class="application">libpq</span> so that it can proceed with
214 the connection sequence.
215 Use <code class="function">PQsocket(conn)</code> to obtain the descriptor of the
216 socket underlying the database connection.
217 (Caution: do not assume that the socket remains the same
218 across <code class="function">PQconnectPoll</code> calls.)
219 Loop thus: If <code class="function">PQconnectPoll(conn)</code> last returned
220 <code class="symbol">PGRES_POLLING_READING</code>, wait until the socket is ready to
221 read (as indicated by <code class="function">select()</code>, <code class="function">poll()</code>, or
222 similar system function). Note that <code class="function">PQsocketPoll</code>
223 can help reduce boilerplate by abstracting the setup of
224 <code class="function">select(2)</code> or <code class="function">poll(2)</code> if it is
225 available on your system.
226 Then call <code class="function">PQconnectPoll(conn)</code> again.
227 Conversely, if <code class="function">PQconnectPoll(conn)</code> last returned
228 <code class="symbol">PGRES_POLLING_WRITING</code>, wait until the socket is ready
229 to write, then call <code class="function">PQconnectPoll(conn)</code> again.
230 On the first iteration, i.e., if you have yet to call
231 <code class="function">PQconnectPoll</code>, behave as if it last returned
232 <code class="symbol">PGRES_POLLING_WRITING</code>. Continue this loop until
233 <code class="function">PQconnectPoll(conn)</code> returns
234 <code class="symbol">PGRES_POLLING_FAILED</code>, indicating the connection procedure
235 has failed, or <code class="symbol">PGRES_POLLING_OK</code>, indicating the connection
236 has been successfully made.
238 At any time during connection, the status of the connection can be
239 checked by calling <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>. If this call returns <code class="symbol">CONNECTION_BAD</code>, then the
240 connection procedure has failed; if the call returns <code class="symbol">CONNECTION_OK</code>, then the
241 connection is ready. Both of these states are equally detectable
242 from the return value of <code class="function">PQconnectPoll</code>, described above. Other states might also occur
243 during (and only during) an asynchronous connection procedure. These
244 indicate the current stage of the connection procedure and might be useful
245 to provide feedback to the user for example. These statuses are:
247 </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>
248 Waiting for connection to be made.
249 </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>
250 Connection OK; waiting to send.
251 </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>
252 Waiting for a response from the server.
253 </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>
254 Received authentication; waiting for backend start-up to finish.
255 </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>
256 Negotiating SSL encryption.
257 </p></dd><dt id="LIBPQ-CONNECTION-GSS-STARTUP"><span class="term"><code class="symbol">CONNECTION_GSS_STARTUP</code></span> <a href="#LIBPQ-CONNECTION-GSS-STARTUP" class="id_link">#</a></dt><dd><p>
258 Negotiating GSS encryption.
259 </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>
260 Checking if connection is able to handle write transactions.
261 </p></dd><dt id="LIBPQ-CONNECTION-CHECK-STANDBY"><span class="term"><code class="symbol">CONNECTION_CHECK_STANDBY</code></span> <a href="#LIBPQ-CONNECTION-CHECK-STANDBY" class="id_link">#</a></dt><dd><p>
262 Checking if connection is to a server in standby mode.
263 </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>
264 Consuming any remaining response messages on connection.
265 </p></dd></dl></div><p>
267 Note that, although these constants will remain (in order to maintain
268 compatibility), an application should never rely upon these occurring in a
269 particular order, or at all, or on the status always being one of these
270 documented values. An application might do something like this:
271 </p><pre class="programlisting">
272 switch(PQstatus(conn))
274 case CONNECTION_STARTED:
275 feedback = "Connecting...";
278 case CONNECTION_MADE:
279 feedback = "Connected to server...";
285 feedback = "Connecting...";
289 The <code class="literal">connect_timeout</code> connection parameter is ignored
290 when using <code class="function">PQconnectPoll</code>; it is the application's
291 responsibility to decide whether an excessive amount of time has elapsed.
292 Otherwise, <code class="function">PQconnectStart</code> followed by a
293 <code class="function">PQconnectPoll</code> loop is equivalent to
294 <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>.
296 Note that when <code class="function">PQconnectStart</code>
297 or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> returns a non-null
298 pointer, you must call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> when you are
299 finished with it, in order to dispose of the structure and any
300 associated memory blocks. This must be done even if the connection
301 attempt fails or is abandoned.
302 </p></dd><dt id="LIBPQ-PQSOCKETPOLL"><span class="term"><code class="function">PQsocketPoll</code><a id="id-1.7.3.8.2.11.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSOCKETPOLL" class="id_link">#</a></dt><dd><p>
303 <a id="id-1.7.3.8.2.11.6.2.1.1" class="indexterm"></a>
304 Poll a connection's underlying socket descriptor retrieved with
305 <a class="xref" href="libpq-status.html#LIBPQ-PQSOCKET"><code class="function">PQsocket</code></a>.
306 The primary use of this function is iterating through the connection
307 sequence described in the documentation of
308 <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>.
309 </p><pre class="synopsis">
310 typedef int64_t pg_usec_time_t;
312 int PQsocketPoll(int sock, int forRead, int forWrite,
313 pg_usec_time_t end_time);
316 This function performs polling of a file descriptor, optionally with
318 If <em class="parameter"><code>forRead</code></em> is nonzero, the
319 function will terminate when the socket is ready for
320 reading. If <em class="parameter"><code>forWrite</code></em> is nonzero,
321 the function will terminate when the
322 socket is ready for writing.
324 The timeout is specified by <em class="parameter"><code>end_time</code></em>, which
325 is the time to stop waiting expressed as a number of microseconds since
326 the Unix epoch (that is, <code class="type">time_t</code> times 1 million).
327 Timeout is infinite if <em class="parameter"><code>end_time</code></em>
328 is <code class="literal">-1</code>. Timeout is immediate (no blocking) if
329 <em class="parameter"><code>end_time</code></em> is <code class="literal">0</code> (or indeed, any
330 time before now). Timeout values can be calculated conveniently by
331 adding the desired number of microseconds to the result of
332 <a class="xref" href="libpq-misc.html#LIBPQ-PQGETCURRENTTIMEUSEC"><code class="function">PQgetCurrentTimeUSec</code></a>.
333 Note that the underlying system calls may have less than microsecond
334 precision, so that the actual delay may be imprecise.
336 The function returns a value greater than <code class="literal">0</code> if the
337 specified condition is met, <code class="literal">0</code> if a timeout occurred,
338 or <code class="literal">-1</code> if an error occurred. The error can be
339 retrieved by checking the <code class="literal">errno(3)</code> value. In the
340 event both <em class="parameter"><code>forRead</code></em>
341 and <em class="parameter"><code>forWrite</code></em> are zero, the function immediately
342 returns a timeout indication.
344 <code class="function">PQsocketPoll</code> is implemented using either
345 <code class="function">poll(2)</code> or <code class="function">select(2)</code>,
346 depending on platform. See <code class="literal">POLLIN</code>
347 and <code class="literal">POLLOUT</code> from <code class="function">poll(2)</code>,
348 or <em class="parameter"><code>readfds</code></em> and
349 <em class="parameter"><code>writefds</code></em> from <code class="function">select(2)</code>,
350 for more information.
351 </p></dd><dt id="LIBPQ-PQCONNDEFAULTS"><span class="term"><code class="function">PQconndefaults</code><a id="id-1.7.3.8.2.11.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNDEFAULTS" class="id_link">#</a></dt><dd><p>
352 Returns the default connection options.
353 </p><pre class="synopsis">
354 PQconninfoOption *PQconndefaults(void);
358 char *keyword; /* The keyword of the option */
359 char *envvar; /* Fallback environment variable name */
360 char *compiled; /* Fallback compiled in default value */
361 char *val; /* Option's current value, or NULL */
362 char *label; /* Label for field in connect dialog */
363 char *dispchar; /* Indicates how to display this field
364 in a connect dialog. Values are:
365 "" Display entered value as is
366 "*" Password field - hide value
367 "D" Debug option - don't show by default */
368 int dispsize; /* Field size in characters for dialog */
372 Returns a connection options array. This can be used to determine
373 all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and their
374 current default values. The return value points to an array of
375 <code class="structname">PQconninfoOption</code> structures, which ends
376 with an entry having a null <code class="structfield">keyword</code> pointer. The
377 null pointer is returned if memory could not be allocated. Note that
378 the current default values (<code class="structfield">val</code> fields)
379 will depend on environment variables and other context. A
380 missing or invalid service file will be silently ignored. Callers
381 must treat the connection options data as read-only.
383 After processing the options array, free it by passing it to
384 <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>. If this is not done, a small amount of memory
385 is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a>.
386 </p></dd><dt id="LIBPQ-PQCONNINFO"><span class="term"><code class="function">PQconninfo</code><a id="id-1.7.3.8.2.11.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNINFO" class="id_link">#</a></dt><dd><p>
387 Returns the connection options used by a live connection.
388 </p><pre class="synopsis">
389 PQconninfoOption *PQconninfo(PGconn *conn);
392 Returns a connection options array. This can be used to determine
393 all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and the
394 values that were used to connect to the server. The return
395 value points to an array of <code class="structname">PQconninfoOption</code>
396 structures, which ends with an entry having a null <code class="structfield">keyword</code>
397 pointer. All notes above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a> also
398 apply to the result of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFO"><code class="function">PQconninfo</code></a>.
399 </p></dd><dt id="LIBPQ-PQCONNINFOPARSE"><span class="term"><code class="function">PQconninfoParse</code><a id="id-1.7.3.8.2.11.9.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNINFOPARSE" class="id_link">#</a></dt><dd><p>
400 Returns parsed connection options from the provided connection string.
402 </p><pre class="synopsis">
403 PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
406 Parses a connection string and returns the resulting options as an
407 array; or returns <code class="symbol">NULL</code> if there is a problem with the connection
408 string. This function can be used to extract
409 the <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options in the provided
410 connection string. The return value points to an array of
411 <code class="structname">PQconninfoOption</code> structures, which ends
412 with an entry having a null <code class="structfield">keyword</code> pointer.
414 All legal options will be present in the result array, but the
415 <code class="literal">PQconninfoOption</code> for any option not present
416 in the connection string will have <code class="literal">val</code> set to
417 <code class="literal">NULL</code>; default values are not inserted.
419 If <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>, then <code class="literal">*errmsg</code> is set
420 to <code class="symbol">NULL</code> on success, else to a <code class="function">malloc</code>'d error string explaining
421 the problem. (It is also possible for <code class="literal">*errmsg</code> to be
422 set to <code class="symbol">NULL</code> and the function to return <code class="symbol">NULL</code>;
423 this indicates an out-of-memory condition.)
425 After processing the options array, free it by passing it to
426 <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>. If this is not done, some memory
427 is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFOPARSE"><code class="function">PQconninfoParse</code></a>.
428 Conversely, if an error occurs and <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>,
429 be sure to free the error string using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a>.
430 </p></dd><dt id="LIBPQ-PQFINISH"><span class="term"><code class="function">PQfinish</code><a id="id-1.7.3.8.2.11.10.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFINISH" class="id_link">#</a></dt><dd><p>
431 Closes the connection to the server. Also frees
432 memory used by the <code class="structname">PGconn</code> object.
433 </p><pre class="synopsis">
434 void PQfinish(PGconn *conn);
437 Note that even if the server connection attempt fails (as
438 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>
439 to free the memory used by the <code class="structname">PGconn</code> object.
440 The <code class="structname">PGconn</code> pointer must not be used again after
441 <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> has been called.
442 </p></dd><dt id="LIBPQ-PQRESET"><span class="term"><code class="function">PQreset</code><a id="id-1.7.3.8.2.11.11.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESET" class="id_link">#</a></dt><dd><p>
443 Resets the communication channel to the server.
444 </p><pre class="synopsis">
445 void PQreset(PGconn *conn);
448 This function will close the connection
449 to the server and attempt to establish a new
450 connection, using all the same
451 parameters previously used. This might be useful for
452 error recovery if a working connection is lost.
453 </p></dd><dt id="LIBPQ-PQRESETSTART"><span class="term"><code class="function">PQresetStart</code><a id="id-1.7.3.8.2.11.12.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQresetPoll</code><a id="id-1.7.3.8.2.11.12.2.2" class="indexterm"></a></span> <a href="#LIBPQ-PQRESETSTART" class="id_link">#</a></dt><dd><p>
454 Reset the communication channel to the server, in a nonblocking manner.
456 </p><pre class="synopsis">
457 int PQresetStart(PGconn *conn);
459 PostgresPollingStatusType PQresetPoll(PGconn *conn);
462 These functions will close the connection to the server and attempt to
463 establish a new connection, using all the same
464 parameters previously used. This can be useful for error recovery if a
465 working connection is lost. They differ from <a class="xref" href="libpq-connect.html#LIBPQ-PQRESET"><code class="function">PQreset</code></a> (above) in that they
466 act in a nonblocking manner. These functions suffer from the same
467 restrictions as <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, <code class="function">PQconnectStart</code>
468 and <code class="function">PQconnectPoll</code>.
470 To initiate a connection reset, call
471 <a class="xref" href="libpq-connect.html#LIBPQ-PQRESETSTART"><code class="function">PQresetStart</code></a>. If it returns 0, the reset has
472 failed. If it returns 1, poll the reset using
473 <code class="function">PQresetPoll</code> in exactly the same way as you
474 would create the connection using <code class="function">PQconnectPoll</code>.
475 </p></dd><dt id="LIBPQ-PQPINGPARAMS"><span class="term"><code class="function">PQpingParams</code><a id="id-1.7.3.8.2.11.13.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPINGPARAMS" class="id_link">#</a></dt><dd><p>
476 <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a> reports the status of the
477 server. It accepts connection parameters identical to those of
478 <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, described above. It is not
479 necessary to supply correct user name, password, or database name
480 values to obtain the server status; however, if incorrect values
481 are provided, the server will log a failed connection attempt.
483 </p><pre class="synopsis">
484 PGPing PQpingParams(const char * const *keywords,
485 const char * const *values,
489 The function returns one of the following values:
491 </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>
492 The server is running and appears to be accepting connections.
493 </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>
494 The server is running but is in a state that disallows connections
495 (startup, shutdown, or crash recovery).
496 </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>
497 The server could not be contacted. This might indicate that the
498 server is not running, or that there is something wrong with the
499 given connection parameters (for example, wrong port number), or
500 that there is a network connectivity problem (for example, a
501 firewall blocking the connection request).
502 </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>
503 No attempt was made to contact the server, because the supplied
504 parameters were obviously incorrect or there was some client-side
505 problem (for example, out of memory).
506 </p></dd></dl></div><p>
508 </p></dd><dt id="LIBPQ-PQPING"><span class="term"><code class="function">PQping</code><a id="id-1.7.3.8.2.11.14.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPING" class="id_link">#</a></dt><dd><p>
509 <a class="xref" href="libpq-connect.html#LIBPQ-PQPING"><code class="function">PQping</code></a> reports the status of the
510 server. It accepts connection parameters identical to those of
511 <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, described above. It is not
512 necessary to supply correct user name, password, or database name
513 values to obtain the server status; however, if incorrect values
514 are provided, the server will log a failed connection attempt.
516 </p><pre class="synopsis">
517 PGPing PQping(const char *conninfo);
520 The return values are the same as for <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a>.
521 </p></dd><dt id="LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQsetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.15.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL" class="id_link">#</a></dt><dd><p>
522 <code class="function">PQsetSSLKeyPassHook_OpenSSL</code> lets an application override
523 <span class="application">libpq</span>'s <a class="link" href="libpq-ssl.html#LIBPQ-SSL-CLIENTCERT" title="32.19.2. Client Certificates">default
524 handling of encrypted client certificate key files</a> using
525 <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLPASSWORD">sslpassword</a> or interactive prompting.
527 </p><pre class="synopsis">
528 void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
531 The application passes a pointer to a callback function with signature:
532 </p><pre class="programlisting">
533 int callback_fn(char *buf, int size, PGconn *conn);
535 which <span class="application">libpq</span> will then call
536 <span class="emphasis"><em>instead of</em></span> its default
537 <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> handler. The
538 callback should determine the password for the key and copy it to
539 result-buffer <em class="parameter"><code>buf</code></em> of size
540 <em class="parameter"><code>size</code></em>. The string in <em class="parameter"><code>buf</code></em>
541 must be null-terminated. The callback must return the length of the
542 password stored in <em class="parameter"><code>buf</code></em> excluding the null
543 terminator. On failure, the callback should set
544 <code class="literal">buf[0] = '\0'</code> and return 0. See
545 <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> in
546 <span class="application">libpq</span>'s source code for an example.
548 If the user specified an explicit key location,
549 its path will be in <code class="literal">conn->sslkey</code> when the callback
550 is invoked. This will be empty if the default key path is being used.
551 For keys that are engine specifiers, it is up to engine implementations
552 whether they use the <span class="productname">OpenSSL</span> password
553 callback or define their own handling.
555 The app callback may choose to delegate unhandled cases to
556 <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code>,
557 or call it first and try something else if it returns 0, or completely override it.
559 The callback <span class="emphasis"><em>must not</em></span> escape normal flow control with exceptions,
560 <code class="function">longjmp(...)</code>, etc. It must return normally.
561 </p></dd><dt id="LIBPQ-PQGETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQgetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.16.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETSSLKEYPASSHOOK-OPENSSL" class="id_link">#</a></dt><dd><p>
562 <code class="function">PQgetSSLKeyPassHook_OpenSSL</code> returns the current
563 client certificate key password hook, or <code class="literal">NULL</code>
564 if none has been set.
566 </p><pre class="synopsis">
567 PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
569 </p></dd></dl></div><p>
570 </p><div class="sect2" id="LIBPQ-CONNSTRING"><div class="titlepage"><div><div><h3 class="title">32.1.1. Connection Strings <a href="#LIBPQ-CONNSTRING" class="id_link">#</a></h3></div></div></div><a id="id-1.7.3.8.3.2" class="indexterm"></a><a id="id-1.7.3.8.3.3" class="indexterm"></a><p>
571 Several <span class="application">libpq</span> functions parse a user-specified string to obtain
572 connection parameters. There are two accepted formats for these strings:
573 plain keyword/value strings
574 and URIs. URIs generally follow
575 <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc3986" target="_top">RFC
576 3986</a>, except that multi-host connection strings are allowed
577 as further described below.
578 </p><div class="sect3" id="LIBPQ-CONNSTRING-KEYWORD-VALUE"><div class="titlepage"><div><div><h4 class="title">32.1.1.1. Keyword/Value Connection Strings <a href="#LIBPQ-CONNSTRING-KEYWORD-VALUE" class="id_link">#</a></h4></div></div></div><p>
579 In the keyword/value format, each parameter setting is in the form
580 <em class="replaceable"><code>keyword</code></em> <code class="literal">=</code>
581 <em class="replaceable"><code>value</code></em>, with space(s) between settings.
582 Spaces around a setting's equal sign are
583 optional. To write an empty value, or a value containing spaces, surround it
584 with single quotes, for example <code class="literal">keyword = 'a value'</code>.
585 Single quotes and backslashes within
586 a value must be escaped with a backslash, i.e., <code class="literal">\'</code> and
587 <code class="literal">\\</code>.
590 </p><pre class="programlisting">
591 host=localhost port=5432 dbname=mydb connect_timeout=10
594 The recognized parameter key words are listed in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="32.1.2. Parameter Key Words">Section 32.1.2</a>.
595 </p></div><div class="sect3" id="LIBPQ-CONNSTRING-URIS"><div class="titlepage"><div><div><h4 class="title">32.1.1.2. Connection URIs <a href="#LIBPQ-CONNSTRING-URIS" class="id_link">#</a></h4></div></div></div><p>
596 The general form for a connection <acronym class="acronym">URI</acronym> is:
597 </p><pre class="synopsis">
598 postgresql://[<span class="optional"><em class="replaceable"><code>userspec</code></em>@</span>][<span class="optional"><em class="replaceable"><code>hostspec</code></em></span>][<span class="optional">/<em class="replaceable"><code>dbname</code></em></span>][<span class="optional">?<em class="replaceable"><code>paramspec</code></em></span>]
600 <span class="phrase">where <em class="replaceable"><code>userspec</code></em> is:</span>
602 <em class="replaceable"><code>user</code></em>[<span class="optional">:<em class="replaceable"><code>password</code></em></span>]
604 <span class="phrase">and <em class="replaceable"><code>hostspec</code></em> is:</span>
606 [<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>]
608 <span class="phrase">and <em class="replaceable"><code>paramspec</code></em> is:</span>
610 <em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>[<span class="optional">&...</span>]
613 The <acronym class="acronym">URI</acronym> scheme designator can be either
614 <code class="literal">postgresql://</code> or <code class="literal">postgres://</code>. Each
615 of the remaining <acronym class="acronym">URI</acronym> parts is optional. The
616 following examples illustrate valid <acronym class="acronym">URI</acronym> syntax:
617 </p><pre class="programlisting">
619 postgresql://localhost
620 postgresql://localhost:5433
621 postgresql://localhost/mydb
622 postgresql://user@localhost
623 postgresql://user:secret@localhost
624 postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
625 postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
627 Values that would normally appear in the hierarchical part of
628 the <acronym class="acronym">URI</acronym> can alternatively be given as named
629 parameters. For example:
630 </p><pre class="programlisting">
631 postgresql:///mydb?host=localhost&port=5433
633 All named parameters must match key words listed in
634 <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="32.1.2. Parameter Key Words">Section 32.1.2</a>, except that for compatibility
635 with JDBC connection <acronym class="acronym">URI</acronym>s, instances
636 of <code class="literal">ssl=true</code> are translated into
637 <code class="literal">sslmode=require</code>.
639 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>
640 if it includes symbols with special meaning in any of its parts. Here is
641 an example where the equal sign (<code class="literal">=</code>) is replaced with
642 <code class="literal">%3D</code> and the space character with
643 <code class="literal">%20</code>:
644 </p><pre class="programlisting">
645 postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
648 The host part may be either a host name or an IP address. To specify an
649 IPv6 address, enclose it in square brackets:
650 </p><pre class="synopsis">
651 postgresql://[2001:db8::1234]/database
654 The host part is interpreted as described for the parameter <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-HOST">host</a>. In particular, a Unix-domain socket
655 connection is chosen if the host part is either empty or looks like an
657 otherwise a TCP/IP connection is initiated. Note, however, that the
658 slash is a reserved character in the hierarchical part of the URI. So, to
659 specify a non-standard Unix-domain socket directory, either omit the host
660 part of the URI and specify the host as a named parameter, or
661 percent-encode the path in the host part of the URI:
662 </p><pre class="programlisting">
663 postgresql:///dbname?host=/var/lib/postgresql
664 postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
667 It is possible to specify multiple host components, each with an optional
668 port component, in a single URI. A URI of the form
669 <code class="literal">postgresql://host1:port1,host2:port2,host3:port3/</code>
670 is equivalent to a connection string of the form
671 <code class="literal">host=host1,host2,host3 port=port1,port2,port3</code>.
672 As further described below, each
673 host will be tried in turn until a connection is successfully established.
674 </p></div><div class="sect3" id="LIBPQ-MULTIPLE-HOSTS"><div class="titlepage"><div><div><h4 class="title">32.1.1.3. Specifying Multiple Hosts <a href="#LIBPQ-MULTIPLE-HOSTS" class="id_link">#</a></h4></div></div></div><p>
675 It is possible to specify multiple hosts to connect to, so that they are
676 tried in the given order. In the Keyword/Value format, the <code class="literal">host</code>,
677 <code class="literal">hostaddr</code>, and <code class="literal">port</code> options accept comma-separated
678 lists of values. The same number of elements must be given in each
679 option that is specified, such
680 that e.g., the first <code class="literal">hostaddr</code> corresponds to the first host name,
681 the second <code class="literal">hostaddr</code> corresponds to the second host name, and so
682 forth. As an exception, if only one <code class="literal">port</code> is specified, it
683 applies to all the hosts.
685 In the connection URI format, you can list multiple <code class="literal">host:port</code> pairs
686 separated by commas in the <code class="literal">host</code> component of the URI.
688 In either format, a single host name can translate to multiple network
689 addresses. A common example of this is a host that has both an IPv4 and
692 When multiple hosts are specified, or when a single host name is
693 translated to multiple addresses, all the hosts and addresses will be
694 tried in order, until one succeeds. If none of the hosts can be reached,
695 the connection fails. If a connection is established successfully, but
696 authentication fails, the remaining hosts in the list are not tried.
698 If a password file is used, you can have different passwords for
699 different hosts. All the other connection options are the same for every
700 host in the list; it is not possible to e.g., specify different
701 usernames for different hosts.
702 </p></div></div><div class="sect2" id="LIBPQ-PARAMKEYWORDS"><div class="titlepage"><div><div><h3 class="title">32.1.2. Parameter Key Words <a href="#LIBPQ-PARAMKEYWORDS" class="id_link">#</a></h3></div></div></div><p>
703 The currently recognized parameter key words are:
705 </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>
706 Name of host to connect to.<a id="id-1.7.3.8.4.2.1.1.2.1.1" class="indexterm"></a> If a host name looks like an absolute path
707 name, it specifies Unix-domain communication rather than TCP/IP
708 communication; the value is the name of the directory in which the
709 socket file is stored. (On Unix, an absolute path name begins with a
710 slash. On Windows, paths starting with drive letters are also
711 recognized.) If the host name starts with <code class="literal">@</code>, it is
712 taken as a Unix-domain socket in the abstract namespace (currently
713 supported on Linux and Windows).
714 The default behavior when <code class="literal">host</code> is not
715 specified, or is empty, is to connect to a Unix-domain
716 socket<a id="id-1.7.3.8.4.2.1.1.2.1.4" class="indexterm"></a> in
717 <code class="filename">/tmp</code> (or whatever socket directory was specified
718 when <span class="productname">PostgreSQL</span> was built). On Windows,
719 the default is to connect to <code class="literal">localhost</code>.
721 A comma-separated list of host names is also accepted, in which case
722 each host name in the list is tried in order; an empty item in the
723 list selects the default behavior as explained above. See
724 <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="32.1.1.3. Specifying Multiple Hosts">Section 32.1.1.3</a> for details.
725 </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>
726 Numeric IP address of host to connect to. This should be in the
727 standard IPv4 address format, e.g., <code class="literal">172.28.40.9</code>. If
728 your machine supports IPv6, you can also use those addresses.
729 TCP/IP communication is
730 always used when a nonempty string is specified for this parameter.
731 If this parameter is not specified, the value of <code class="literal">host</code>
732 will be looked up to find the corresponding IP address — or, if
733 <code class="literal">host</code> specifies an IP address, that value will be
736 Using <code class="literal">hostaddr</code> allows the
737 application to avoid a host name look-up, which might be important
738 in applications with time constraints. However, a host name is
739 required for GSSAPI or SSPI authentication
740 methods, as well as for <code class="literal">verify-full</code> SSL
741 certificate verification. The following rules are used:
742 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
743 If <code class="literal">host</code> is specified
744 without <code class="literal">hostaddr</code>, a host name lookup occurs.
745 (When using <code class="function">PQconnectPoll</code>, the lookup occurs
746 when <code class="function">PQconnectPoll</code> first considers this host
747 name, and it may cause <code class="function">PQconnectPoll</code> to block
748 for a significant amount of time.)
749 </p></li><li class="listitem"><p>
750 If <code class="literal">hostaddr</code> is specified without <code class="literal">host</code>,
751 the value for <code class="literal">hostaddr</code> gives the server network address.
752 The connection attempt will fail if the authentication
753 method requires a host name.
754 </p></li><li class="listitem"><p>
755 If both <code class="literal">host</code> and <code class="literal">hostaddr</code> are specified,
756 the value for <code class="literal">hostaddr</code> gives the server network address.
757 The value for <code class="literal">host</code> is ignored unless the
758 authentication method requires it, in which case it will be
759 used as the host name.
760 </p></li></ul></div><p>
761 Note that authentication is likely to fail if <code class="literal">host</code>
762 is not the name of the server at network address <code class="literal">hostaddr</code>.
763 Also, when both <code class="literal">host</code> and <code class="literal">hostaddr</code>
764 are specified, <code class="literal">host</code>
765 is used to identify the connection in a password file (see
766 <a class="xref" href="libpq-pgpass.html" title="32.16. The Password File">Section 32.16</a>).
768 A comma-separated list of <code class="literal">hostaddr</code> values is also
769 accepted, in which case each host in the list is tried in order.
770 An empty item in the list causes the corresponding host name to be
771 used, or the default host name if that is empty as well. See
772 <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="32.1.1.3. Specifying Multiple Hosts">Section 32.1.1.3</a> for details.
774 Without either a host name or host address,
775 <span class="application">libpq</span> will connect using a local
776 Unix-domain socket; or on Windows, it will attempt to connect to
777 <code class="literal">localhost</code>.
778 </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>
779 Port number to connect to at the server host, or socket file
780 name extension for Unix-domain
781 connections.<a id="id-1.7.3.8.4.2.1.3.2.1.1" class="indexterm"></a>
782 If multiple hosts were given in the <code class="literal">host</code> or
783 <code class="literal">hostaddr</code> parameters, this parameter may specify a
784 comma-separated list of ports of the same length as the host list, or
785 it may specify a single port number to be used for all hosts.
786 An empty string, or an empty item in a comma-separated list,
787 specifies the default port number established
788 when <span class="productname">PostgreSQL</span> was built.
789 </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>
790 The database name. Defaults to be the same as the user name.
791 In certain contexts, the value is checked for extended
792 formats; see <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">Section 32.1.1</a> for more details on
794 </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>
795 <span class="productname">PostgreSQL</span> user name to connect as.
796 Defaults to be the same as the operating system name of the user
797 running the application.
798 </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>
799 Password to be used if the server demands password authentication.
800 </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>
801 Specifies the name of the file used to store passwords
802 (see <a class="xref" href="libpq-pgpass.html" title="32.16. The Password File">Section 32.16</a>).
803 Defaults to <code class="filename">~/.pgpass</code>, or
804 <code class="filename">%APPDATA%\postgresql\pgpass.conf</code> on Microsoft Windows.
805 (No error is reported if this file does not exist.)
806 </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>
807 Specifies the authentication method that the client requires from the
808 server. If the server does not use the required method to authenticate
809 the client, or if the authentication handshake is not fully completed by
810 the server, the connection will fail. A comma-separated list of methods
811 may also be provided, of which the server must use exactly one in order
812 for the connection to succeed. By default, any authentication method is
813 accepted, and the server is free to skip authentication altogether.
815 Methods may be negated with the addition of a <code class="literal">!</code>
816 prefix, in which case the server must <span class="emphasis"><em>not</em></span> attempt
817 the listed method; any other method is accepted, and the server is free
818 not to authenticate the client at all. If a comma-separated list is
819 provided, the server may not attempt <span class="emphasis"><em>any</em></span> of the
820 listed negated methods. Negated and non-negated forms may not be
821 combined in the same setting.
823 As a final special case, the <code class="literal">none</code> method requires the
824 server not to use an authentication challenge. (It may also be negated,
825 to require some form of authentication.)
827 The following methods may be specified:
829 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">password</code></span></dt><dd><p>
830 The server must request plaintext password authentication.
831 </p></dd><dt><span class="term"><code class="literal">md5</code></span></dt><dd><p>
832 The server must request MD5 hashed password authentication.
833 </p><div class="warning"><h3 class="title">Warning</h3><p>
834 Support for MD5-encrypted passwords is deprecated and will be
835 removed in a future release of
836 <span class="productname">PostgreSQL</span>. Refer to
837 <a class="xref" href="auth-password.html" title="20.5. Password Authentication">Section 20.5</a> for details about migrating to
838 another password type.
839 </p></div></dd><dt><span class="term"><code class="literal">gss</code></span></dt><dd><p>
840 The server must either request a Kerberos handshake via
841 <acronym class="acronym">GSSAPI</acronym> or establish a
842 <acronym class="acronym">GSS</acronym>-encrypted channel (see also
843 <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-GSSENCMODE">gssencmode</a>).
844 </p></dd><dt><span class="term"><code class="literal">sspi</code></span></dt><dd><p>
845 The server must request Windows <acronym class="acronym">SSPI</acronym>
847 </p></dd><dt><span class="term"><code class="literal">scram-sha-256</code></span></dt><dd><p>
848 The server must successfully complete a SCRAM-SHA-256 authentication
849 exchange with the client.
850 </p></dd><dt><span class="term"><code class="literal">oauth</code></span></dt><dd><p>
851 The server must request an OAuth bearer token from the client.
852 </p></dd><dt><span class="term"><code class="literal">none</code></span></dt><dd><p>
853 The server must not prompt the client for an authentication
854 exchange. (This does not prohibit client certificate authentication
855 via TLS, nor GSS authentication via its encrypted transport.)
856 </p></dd></dl></div><p>
857 </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>
858 This option controls the client's use of channel binding. A setting
859 of <code class="literal">require</code> means that the connection must employ
860 channel binding, <code class="literal">prefer</code> means that the client will
861 choose channel binding if available, and <code class="literal">disable</code>
862 prevents the use of channel binding. The default
863 is <code class="literal">prefer</code> if
864 <span class="productname">PostgreSQL</span> is compiled with SSL support;
865 otherwise the default is <code class="literal">disable</code>.
867 Channel binding is a method for the server to authenticate itself to
868 the client. It is only supported over SSL connections
869 with <span class="productname">PostgreSQL</span> 11 or later servers using
870 the <code class="literal">SCRAM</code> authentication method.
871 </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>
872 Maximum time to wait while connecting, in seconds (write as a decimal integer,
873 e.g., <code class="literal">10</code>). Zero, negative, or not specified means
875 This timeout applies separately to each host name or IP address.
876 For example, if you specify two hosts and <code class="literal">connect_timeout</code>
877 is 5, each host will time out if no connection is made within 5
878 seconds, so the total time spent waiting for a connection might be
880 </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>
881 This sets the <code class="varname">client_encoding</code>
882 configuration parameter for this connection. In addition to
883 the values accepted by the corresponding server option, you
884 can use <code class="literal">auto</code> to determine the right
885 encoding from the current locale in the client
886 (<code class="envar">LC_CTYPE</code> environment variable on Unix
888 </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>
889 Specifies command-line options to send to the server at connection
890 start. For example, setting this to <code class="literal">-c geqo=off</code>
891 or <code class="literal">--geqo=off</code> sets the session's value of the
892 <code class="varname">geqo</code> parameter to <code class="literal">off</code>.
893 Spaces within this string are considered to
894 separate command-line arguments, unless escaped with a backslash
895 (<code class="literal">\</code>); write <code class="literal">\\</code> to represent a literal
896 backslash. For a detailed discussion of the available
897 options, consult <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a>.
898 </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>
899 Specifies a value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a>
900 configuration parameter.
901 </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>
902 Specifies a fallback value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a> configuration parameter.
903 This value will be used if no value has been given for
904 <code class="literal">application_name</code> via a connection parameter or the
905 <code class="envar">PGAPPNAME</code> environment variable. Specifying
906 a fallback name is useful in generic utility programs that
907 wish to set a default application name but allow it to be
908 overridden by the user.
909 </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>
910 Controls whether client-side TCP keepalives are used. The default
911 value is 1, meaning on, but you can change this to 0, meaning off,
912 if keepalives are not wanted. This parameter is ignored for
913 connections made via a Unix-domain socket.
914 </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>
915 Controls the number of seconds of inactivity after which TCP should
916 send a keepalive message to the server. A value of zero uses the
917 system default. This parameter is ignored for connections made via a
918 Unix-domain socket, or if keepalives are disabled.
919 It is only supported on systems where <code class="symbol">TCP_KEEPIDLE</code> or
920 an equivalent socket option is available, and on Windows; on other
921 systems, it has no effect.
922 </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>
923 Controls the number of seconds after which a TCP keepalive message
924 that is not acknowledged by the server should be retransmitted. A
925 value of zero uses the system default. This parameter is ignored for
926 connections made via a Unix-domain socket, or if keepalives are disabled.
927 It is only supported on systems where <code class="symbol">TCP_KEEPINTVL</code> or
928 an equivalent socket option is available, and on Windows; on other
929 systems, it has no effect.
930 </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>
931 Controls the number of TCP keepalives that can be lost before the
932 client's connection to the server is considered dead. A value of
933 zero uses the system default. This parameter is ignored for
934 connections made via a Unix-domain socket, or if keepalives are disabled.
935 It is only supported on systems where <code class="symbol">TCP_KEEPCNT</code> or
936 an equivalent socket option is available; on other systems, it has no
938 </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>
939 Controls the number of milliseconds that transmitted data may
940 remain unacknowledged before a connection is forcibly closed.
941 A value of zero uses the system default. This parameter is
942 ignored for connections made via a Unix-domain socket.
943 It is only supported on systems where <code class="symbol">TCP_USER_TIMEOUT</code>
944 is available; on other systems, it has no effect.
945 </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>
946 This option determines whether the connection should use the
947 replication protocol instead of the normal protocol. This is what
948 PostgreSQL replication connections as well as tools such as
949 <span class="application">pg_basebackup</span> use internally, but it can
950 also be used by third-party applications. For a description of the
951 replication protocol, consult <a class="xref" href="protocol-replication.html" title="54.4. Streaming Replication Protocol">Section 54.4</a>.
953 The following values, which are case-insensitive, are supported:
954 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
955 <code class="literal">true</code>, <code class="literal">on</code>,
956 <code class="literal">yes</code>, <code class="literal">1</code>
958 The connection goes into physical replication mode.
959 </p></dd><dt><span class="term"><code class="literal">database</code></span></dt><dd><p>
960 The connection goes into logical replication mode, connecting to
961 the database specified in the <code class="literal">dbname</code> parameter.
962 </p></dd><dt><span class="term">
963 <code class="literal">false</code>, <code class="literal">off</code>,
964 <code class="literal">no</code>, <code class="literal">0</code>
966 The connection is a regular one, which is the default behavior.
967 </p></dd></dl></div><p>
969 In physical or logical replication mode, only the simple query protocol
971 </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>
972 This option determines whether or with what priority a secure
973 <acronym class="acronym">GSS</acronym> TCP/IP connection will be negotiated with the
974 server. There are three modes:
976 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
977 only try a non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection
978 </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>
979 if there are <acronym class="acronym">GSSAPI</acronym> credentials present (i.e.,
980 in a credentials cache), first try
981 a <acronym class="acronym">GSSAPI</acronym>-encrypted connection; if that fails or
982 there are no credentials, try a
983 non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection. This is the
984 default when <span class="productname">PostgreSQL</span> has been
985 compiled with <acronym class="acronym">GSSAPI</acronym> support.
986 </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
987 only try a <acronym class="acronym">GSSAPI</acronym>-encrypted connection
988 </p></dd></dl></div><p>
990 <code class="literal">gssencmode</code> is ignored for Unix domain socket
991 communication. If <span class="productname">PostgreSQL</span> is compiled
992 without GSSAPI support, using the <code class="literal">require</code> option
993 will cause an error, while <code class="literal">prefer</code> will be accepted
994 but <span class="application">libpq</span> will not actually attempt
995 a <acronym class="acronym">GSSAPI</acronym>-encrypted
996 connection.<a id="id-1.7.3.8.4.2.1.21.2.2.7" class="indexterm"></a>
997 </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>
998 This option determines whether or with what priority a secure
999 <acronym class="acronym">SSL</acronym> TCP/IP connection will be negotiated with the
1000 server. There are six modes:
1002 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
1003 only try a non-<acronym class="acronym">SSL</acronym> connection
1004 </p></dd><dt><span class="term"><code class="literal">allow</code></span></dt><dd><p>
1005 first try a non-<acronym class="acronym">SSL</acronym> connection; if that
1006 fails, try an <acronym class="acronym">SSL</acronym> connection
1007 </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p>
1008 first try an <acronym class="acronym">SSL</acronym> connection; if that fails,
1009 try a non-<acronym class="acronym">SSL</acronym> connection
1010 </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
1011 only try an <acronym class="acronym">SSL</acronym> connection. If a root CA
1012 file is present, verify the certificate in the same way as
1013 if <code class="literal">verify-ca</code> was specified
1014 </p></dd><dt><span class="term"><code class="literal">verify-ca</code></span></dt><dd><p>
1015 only try an <acronym class="acronym">SSL</acronym> connection, and verify that
1016 the server certificate is issued by a trusted
1017 certificate authority (<acronym class="acronym">CA</acronym>)
1018 </p></dd><dt><span class="term"><code class="literal">verify-full</code></span></dt><dd><p>
1019 only try an <acronym class="acronym">SSL</acronym> connection, verify that the
1020 server certificate is issued by a
1021 trusted <acronym class="acronym">CA</acronym> and that the requested server host name
1022 matches that in the certificate
1023 </p></dd></dl></div><p>
1025 See <a class="xref" href="libpq-ssl.html" title="32.19. SSL Support">Section 32.19</a> for a detailed description of how
1028 <code class="literal">sslmode</code> is ignored for Unix domain socket
1030 If <span class="productname">PostgreSQL</span> is compiled without SSL support,
1031 using options <code class="literal">require</code>, <code class="literal">verify-ca</code>, or
1032 <code class="literal">verify-full</code> will cause an error, while
1033 options <code class="literal">allow</code> and <code class="literal">prefer</code> will be
1034 accepted but <span class="application">libpq</span> will not actually attempt
1035 an <acronym class="acronym">SSL</acronym>
1036 connection.<a id="id-1.7.3.8.4.2.1.22.2.2.10" class="indexterm"></a>
1038 Note that if <acronym class="acronym">GSSAPI</acronym> encryption is possible,
1039 that will be used in preference to <acronym class="acronym">SSL</acronym>
1040 encryption, regardless of the value of <code class="literal">sslmode</code>.
1041 To force use of <acronym class="acronym">SSL</acronym> encryption in an
1042 environment that has working <acronym class="acronym">GSSAPI</acronym>
1043 infrastructure (such as a Kerberos server), also set
1044 <code class="literal">gssencmode</code> to <code class="literal">disable</code>.
1045 </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>
1046 This option is deprecated in favor of the <code class="literal">sslmode</code>
1049 If set to 1, an <acronym class="acronym">SSL</acronym> connection to the server
1050 is required (this is equivalent to <code class="literal">sslmode</code>
1051 <code class="literal">require</code>). <span class="application">libpq</span> will then refuse
1052 to connect if the server does not accept an
1053 <acronym class="acronym">SSL</acronym> connection. If set to 0 (default),
1054 <span class="application">libpq</span> will negotiate the connection type with
1055 the server (equivalent to <code class="literal">sslmode</code>
1056 <code class="literal">prefer</code>). This option is only available if
1057 <span class="productname">PostgreSQL</span> is compiled with SSL support.
1058 </p></dd><dt id="LIBPQ-CONNECT-SSLNEGOTIATION"><span class="term"><code class="literal">sslnegotiation</code></span> <a href="#LIBPQ-CONNECT-SSLNEGOTIATION" class="id_link">#</a></dt><dd><p>
1059 This option controls how SSL encryption is negotiated with the server,
1060 if SSL is used. In the default <code class="literal">postgres</code> mode, the
1061 client first asks the server if SSL is supported. In
1062 <code class="literal">direct</code> mode, the client starts the standard SSL
1063 handshake directly after establishing the TCP/IP connection. Traditional
1064 <span class="productname">PostgreSQL</span> protocol negotiation is the most
1065 flexible with different server configurations. If the server is known
1066 to support direct <acronym class="acronym">SSL</acronym> connections then the latter
1067 requires one fewer round trip reducing connection latency and also
1068 allows the use of protocol agnostic SSL network tools. The direct SSL
1069 option was introduced in <span class="productname">PostgreSQL</span> version
1071 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">postgres</code></span></dt><dd><p>
1072 perform <span class="productname">PostgreSQL</span> protocol
1073 negotiation. This is the default if the option is not provided.
1074 </p></dd><dt><span class="term"><code class="literal">direct</code></span></dt><dd><p>
1075 start SSL handshake directly after establishing the TCP/IP
1076 connection. This is only allowed with
1077 <code class="literal">sslmode=require</code> or higher, because the weaker
1078 settings could lead to unintended fallback to plaintext
1079 authentication when the server does not support direct SSL
1081 </p></dd></dl></div></dd><dt id="LIBPQ-CONNECT-SSLCOMPRESSION"><span class="term"><code class="literal">sslcompression</code></span> <a href="#LIBPQ-CONNECT-SSLCOMPRESSION" class="id_link">#</a></dt><dd><p>
1082 If set to 1, data sent over SSL connections will be compressed. If
1083 set to 0, compression will be disabled. The default is 0. This
1084 parameter is ignored if a connection without SSL is made.
1086 SSL compression is nowadays considered insecure and its use is no
1087 longer recommended. <span class="productname">OpenSSL</span> 1.1.0 disabled
1088 compression by default, and many operating system distributions
1089 disabled it in prior versions as well, so setting this parameter to on
1090 will not have any effect if the server does not accept compression.
1091 <span class="productname">PostgreSQL</span> 14 disabled compression
1092 completely in the backend.
1094 If security is not a primary concern, compression can improve
1095 throughput if the network is the bottleneck. Disabling compression
1096 can improve response time and throughput if CPU performance is the
1098 </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>
1099 This parameter specifies the file name of the client SSL
1100 certificate, replacing the default
1101 <code class="filename">~/.postgresql/postgresql.crt</code>.
1102 This parameter is ignored if an SSL connection is not made.
1103 </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>
1104 This parameter specifies the location for the secret key used for
1105 the client certificate. It can either specify a file name that will
1106 be used instead of the default
1107 <code class="filename">~/.postgresql/postgresql.key</code>, or it can specify a key
1108 obtained from an external <span class="quote">“<span class="quote">engine</span>”</span> (engines are
1109 <span class="productname">OpenSSL</span> loadable modules). An external engine
1110 specification should consist of a colon-separated engine name and
1111 an engine-specific key identifier. This parameter is ignored if an
1112 SSL connection is not made.
1113 </p></dd><dt id="LIBPQ-CONNECT-SSLKEYLOGFILE"><span class="term"><code class="literal">sslkeylogfile</code></span> <a href="#LIBPQ-CONNECT-SSLKEYLOGFILE" class="id_link">#</a></dt><dd><p>
1114 This parameter specifies the location where <span class="application">libpq</span>
1115 will log keys used in this SSL context. This is useful for debugging
1116 <span class="productname">PostgreSQL</span> protocol interactions or client
1117 connections using network inspection tools like
1118 <span class="productname">Wireshark</span>. This parameter is ignored if an
1119 SSL connection is not made, or if <span class="productname">LibreSSL</span>
1120 is used (<span class="productname">LibreSSL</span> does not support key
1121 logging). Keys are logged using the <span class="productname">NSS</span>
1123 </p><div class="warning"><h3 class="title">Warning</h3><p>
1124 Key logging will expose potentially sensitive information in the
1125 keylog file. Keylog files should be handled with the same care as
1126 <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLKEY">sslkey</a> files.
1128 </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>
1129 This parameter specifies the password for the secret key specified in
1130 <code class="literal">sslkey</code>, allowing client certificate private keys
1131 to be stored in encrypted form on disk even when interactive passphrase
1132 input is not practical.
1134 Specifying this parameter with any non-empty value suppresses the
1135 <code class="literal">Enter PEM pass phrase:</code>
1136 prompt that <span class="productname">OpenSSL</span> will emit by default
1137 when an encrypted client certificate key is provided to
1138 <span class="application">libpq</span>.
1140 If the key is not encrypted this parameter is ignored. The parameter
1141 has no effect on keys specified by <span class="productname">OpenSSL</span>
1142 engines unless the engine uses the <span class="productname">OpenSSL</span>
1143 password callback mechanism for prompts.
1145 There is no environment variable equivalent to this option, and no
1146 facility for looking it up in <code class="filename">.pgpass</code>. It can be
1147 used in a service file connection definition. Users with
1148 more sophisticated uses should consider using <span class="productname">OpenSSL</span> engines and
1149 tools like PKCS#11 or USB crypto offload devices.
1150 </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>
1151 This option determines whether a client certificate may be sent to the
1152 server, and whether the server is required to request one. There are
1155 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p>
1156 A client certificate is never sent, even if one is available
1157 (default location or provided via
1158 <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCERT">sslcert</a>).
1159 </p></dd><dt><span class="term"><code class="literal">allow</code> (default)</span></dt><dd><p>
1160 A certificate may be sent, if the server requests one and the
1161 client has one to send.
1162 </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p>
1163 The server <span class="emphasis"><em>must</em></span> request a certificate. The
1164 connection will fail if the client does not send a certificate and
1165 the server successfully authenticates the client anyway.
1166 </p></dd></dl></div><p>
1167 </p><div class="note"><h3 class="title">Note</h3><p>
1168 <code class="literal">sslcertmode=require</code> doesn't add any additional
1169 security, since there is no guarantee that the server is validating
1170 the certificate correctly; PostgreSQL servers generally request TLS
1171 certificates from clients whether they validate them or not. The
1172 option may be useful when troubleshooting more complicated TLS
1174 </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>
1175 This parameter specifies the name of a file containing SSL
1176 certificate authority (<acronym class="acronym">CA</acronym>) certificate(s).
1177 If the file exists, the server's certificate will be verified
1178 to be signed by one of these authorities. The default is
1179 <code class="filename">~/.postgresql/root.crt</code>.
1181 The special value <code class="literal">system</code> may be specified instead, in
1182 which case the trusted CA roots from the SSL implementation will be loaded. The exact
1183 locations of these root certificates differ by SSL implementation and
1184 platform. For <span class="productname">OpenSSL</span> in particular, the
1185 locations may be further modified by the <code class="envar">SSL_CERT_DIR</code>
1186 and <code class="envar">SSL_CERT_FILE</code> environment variables.
1187 </p><div class="note"><h3 class="title">Note</h3><p>
1188 When using <code class="literal">sslrootcert=system</code>, the default
1189 <code class="literal">sslmode</code> is changed to <code class="literal">verify-full</code>,
1190 and any weaker setting will result in an error. In most cases it is
1191 trivial for anyone to obtain a certificate trusted by the system for a
1192 hostname they control, rendering <code class="literal">verify-ca</code> and all
1193 weaker modes useless.
1195 The magic <code class="literal">system</code> value will take precedence over a
1196 local certificate file with the same name. If for some reason you find
1197 yourself in this situation, use an alternative path like
1198 <code class="literal">sslrootcert=./system</code> instead.
1199 </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>
1200 This parameter specifies the file name of the SSL server certificate
1201 revocation list (CRL). Certificates listed in this file, if it
1202 exists, will be rejected while attempting to authenticate the
1203 server's certificate. If neither
1204 <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRL">sslcrl</a> nor
1205 <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRLDIR">sslcrldir</a> is set, this setting is
1207 <code class="filename">~/.postgresql/root.crl</code>.
1208 </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>
1209 This parameter specifies the directory name of the SSL server certificate
1210 revocation list (CRL). Certificates listed in the files in this
1211 directory, if it exists, will be rejected while attempting to
1212 authenticate the server's certificate.
1214 The directory needs to be prepared with the
1215 <span class="productname">OpenSSL</span> command
1216 <code class="literal">openssl rehash</code> or <code class="literal">c_rehash</code>. See
1217 its documentation for details.
1219 Both <code class="literal">sslcrl</code> and <code class="literal">sslcrldir</code> can be
1221 </p></dd><dt id="LIBPQ-CONNECT-SSLSNI"><span class="term"><code class="literal">sslsni</code><a id="id-1.7.3.8.4.2.1.34.1.2" class="indexterm"></a></span> <a href="#LIBPQ-CONNECT-SSLSNI" class="id_link">#</a></dt><dd><p>
1222 If set to 1 (default), libpq sets the TLS extension <span class="quote">“<span class="quote">Server Name
1223 Indication</span>”</span> (<acronym class="acronym">SNI</acronym>) on SSL-enabled connections.
1224 By setting this parameter to 0, this is turned off.
1226 The Server Name Indication can be used by SSL-aware proxies to route
1227 connections without having to decrypt the SSL stream. (Note that
1228 unless the proxy is aware of the PostgreSQL protocol handshake this
1229 would require setting <code class="literal">sslnegotiation</code>
1230 to <code class="literal">direct</code>.)
1231 However, <acronym class="acronym">SNI</acronym> makes the destination host name appear
1232 in cleartext in the network traffic, so it might be undesirable in
1234 </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>
1235 This parameter specifies the operating-system user name of the
1236 server, for example <code class="literal">requirepeer=postgres</code>.
1237 When making a Unix-domain socket connection, if this
1238 parameter is set, the client checks at the beginning of the
1239 connection that the server process is running under the specified
1240 user name; if it is not, the connection is aborted with an error.
1241 This parameter can be used to provide server authentication similar
1242 to that available with SSL certificates on TCP/IP connections.
1243 (Note that if the Unix-domain socket is in
1244 <code class="filename">/tmp</code> or another publicly writable location,
1245 any user could start a server listening there. Use this parameter
1246 to ensure that you are connected to a server run by a trusted user.)
1247 This option is only supported on platforms for which the
1248 <code class="literal">peer</code> authentication method is implemented; see
1249 <a class="xref" href="auth-peer.html" title="20.9. Peer Authentication">Section 20.9</a>.
1250 </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>
1251 This parameter specifies the minimum SSL/TLS protocol version to allow
1252 for the connection. Valid values are <code class="literal">TLSv1</code>,
1253 <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and
1254 <code class="literal">TLSv1.3</code>. The supported protocols depend on the
1255 version of <span class="productname">OpenSSL</span> used, older versions
1256 not supporting the most modern protocol versions. If not specified,
1257 the default is <code class="literal">TLSv1.2</code>, which satisfies industry
1258 best practices as of this writing.
1259 </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>
1260 This parameter specifies the maximum SSL/TLS protocol version to allow
1261 for the connection. Valid values are <code class="literal">TLSv1</code>,
1262 <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and
1263 <code class="literal">TLSv1.3</code>. The supported protocols depend on the
1264 version of <span class="productname">OpenSSL</span> used, older versions
1265 not supporting the most modern protocol versions. If not set, this
1266 parameter is ignored and the connection will use the maximum bound
1267 defined by the backend, if set. Setting the maximum protocol version
1268 is mainly useful for testing or if some component has issues working
1269 with a newer protocol.
1270 </p></dd><dt id="LIBPQ-CONNECT-MIN-PROTOCOL-VERSION"><span class="term"><code class="literal">min_protocol_version</code></span> <a href="#LIBPQ-CONNECT-MIN-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p>
1271 Specifies the minimum protocol version to allow for the connection.
1272 The default is to allow any version of the
1273 <span class="productname">PostgreSQL</span> protocol supported by libpq,
1274 which currently means <code class="literal">3.0</code>. If the server
1275 does not support at least this protocol version the connection will be
1278 The current supported values are
1279 <code class="literal">3.0</code>, <code class="literal">3.2</code>,
1280 and <code class="literal">latest</code>. The <code class="literal">latest</code> value is
1281 equivalent to the latest protocol version supported by the libpq
1282 version being used, which is currently <code class="literal">3.2</code>.
1283 </p></dd><dt id="LIBPQ-CONNECT-MAX-PROTOCOL-VERSION"><span class="term"><code class="literal">max_protocol_version</code></span> <a href="#LIBPQ-CONNECT-MAX-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p>
1284 Specifies the protocol version to request from the server.
1285 The default is to use version <code class="literal">3.0</code> of the
1286 <span class="productname">PostgreSQL</span> protocol, unless the connection
1287 string specifies a feature that relies on a higher protocol version,
1288 in which case the latest version supported by libpq is used. If the
1289 server does not support the protocol version requested by the client,
1290 the connection is automatically downgraded to a lower minor protocol
1291 version that the server supports. After the connection attempt has
1292 completed you can use <a class="xref" href="libpq-status.html#LIBPQ-PQPROTOCOLVERSION"><code class="function">PQprotocolVersion</code></a> to
1293 find out which exact protocol version was negotiated.
1295 The current supported values are
1296 <code class="literal">3.0</code>, <code class="literal">3.2</code>,
1297 and <code class="literal">latest</code>. The <code class="literal">latest</code> value is
1298 equivalent to the latest protocol version supported by the libpq
1299 version being used, which is currently <code class="literal">3.2</code>.
1300 </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>
1301 Kerberos service name to use when authenticating with GSSAPI.
1302 This must match the service name specified in the server
1303 configuration for Kerberos authentication to succeed. (See also
1304 <a class="xref" href="gssapi-auth.html" title="20.6. GSSAPI Authentication">Section 20.6</a>.)
1305 The default value is normally <code class="literal">postgres</code>,
1306 but that can be changed when
1307 building <span class="productname">PostgreSQL</span> via
1308 the <code class="option">--with-krb-srvnam</code> option
1309 of <span class="application">configure</span>.
1310 In most environments, this parameter never needs to be changed.
1311 Some Kerberos implementations might require a different service name,
1312 such as Microsoft Active Directory which requires the service name
1313 to be in upper case (<code class="literal">POSTGRES</code>).
1314 </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>
1315 GSS library to use for GSSAPI authentication.
1316 Currently this is disregarded except on Windows builds that include
1317 both GSSAPI and SSPI support. In that case, set
1318 this to <code class="literal">gssapi</code> to cause libpq to use the GSSAPI
1319 library for authentication instead of the default SSPI.
1320 </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>
1321 Forward (delegate) GSS credentials to the server. The default is
1322 <code class="literal">0</code> which means credentials will not be forwarded
1323 to the server. Set this to <code class="literal">1</code> to have credentials
1324 forwarded when possible.
1325 </p></dd><dt id="LIBPQ-CONNECT-SCRAM-CLIENT-KEY"><span class="term"><code class="literal">scram_client_key</code></span> <a href="#LIBPQ-CONNECT-SCRAM-CLIENT-KEY" class="id_link">#</a></dt><dd><p>
1326 The base64-encoded SCRAM client key. This can be used by foreign-data
1327 wrappers or similar middleware to enable pass-through SCRAM
1328 authentication. See <a class="xref" href="postgres-fdw.html#POSTGRES-FDW-OPTIONS-CONNECTION-MANAGEMENT" title="F.38.1.10. Connection Management Options">Section F.38.1.10</a> for one such
1329 implementation. It is not meant to be specified directly by users or
1330 client applications.
1331 </p></dd><dt id="LIBPQ-CONNECT-SCRAM-SERVER-KEY"><span class="term"><code class="literal">scram_server_key</code></span> <a href="#LIBPQ-CONNECT-SCRAM-SERVER-KEY" class="id_link">#</a></dt><dd><p>
1332 The base64-encoded SCRAM server key. This can be used by foreign-data
1333 wrappers or similar middleware to enable pass-through SCRAM
1334 authentication. See <a class="xref" href="postgres-fdw.html#POSTGRES-FDW-OPTIONS-CONNECTION-MANAGEMENT" title="F.38.1.10. Connection Management Options">Section F.38.1.10</a> for one such
1335 implementation. It is not meant to be specified directly by users or
1336 client applications.
1337 </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>
1338 Service name to use for additional parameters. It specifies a service
1339 name in <code class="filename">pg_service.conf</code> that holds additional connection parameters.
1340 This allows applications to specify only a service name so connection parameters
1341 can be centrally maintained. See <a class="xref" href="libpq-pgservice.html" title="32.17. The Connection Service File">Section 32.17</a>.
1342 </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>
1343 This option determines whether the session must have certain
1344 properties to be acceptable. It's typically used in combination
1345 with multiple host names to select the first acceptable alternative
1346 among several hosts. There are six modes:
1348 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">any</code> (default)</span></dt><dd><p>
1349 any successful connection is acceptable
1350 </p></dd><dt><span class="term"><code class="literal">read-write</code></span></dt><dd><p>
1351 session must accept read-write transactions by default (that
1352 is, the server must not be in hot standby mode and
1353 the <code class="varname">default_transaction_read_only</code> parameter
1354 must be <code class="literal">off</code>)
1355 </p></dd><dt><span class="term"><code class="literal">read-only</code></span></dt><dd><p>
1356 session must not accept read-write transactions by default (the
1358 </p></dd><dt><span class="term"><code class="literal">primary</code></span></dt><dd><p>
1359 server must not be in hot standby mode
1360 </p></dd><dt><span class="term"><code class="literal">standby</code></span></dt><dd><p>
1361 server must be in hot standby mode
1362 </p></dd><dt><span class="term"><code class="literal">prefer-standby</code></span></dt><dd><p>
1363 first try to find a standby server, but if none of the listed
1364 hosts is a standby server, try again in <code class="literal">any</code>
1366 </p></dd></dl></div><p>
1367 </p></dd><dt id="LIBPQ-CONNECT-LOAD-BALANCE-HOSTS"><span class="term"><code class="literal">load_balance_hosts</code></span> <a href="#LIBPQ-CONNECT-LOAD-BALANCE-HOSTS" class="id_link">#</a></dt><dd><p>
1368 Controls the order in which the client tries to connect to the available
1369 hosts and addresses. Once a connection attempt is successful no other
1370 hosts and addresses will be tried. This parameter is typically used in
1371 combination with multiple host names or a DNS record that returns
1372 multiple IPs. This parameter can be used in combination with
1373 <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-TARGET-SESSION-ATTRS">target_session_attrs</a>
1374 to, for example, load balance over standby servers only. Once successfully
1375 connected, subsequent queries on the returned connection will all be
1376 sent to the same server. There are currently two modes:
1377 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code> (default)</span></dt><dd><p>
1378 No load balancing across hosts is performed. Hosts are tried in
1379 the order in which they are provided and addresses are tried in
1380 the order they are received from DNS or a hosts file.
1381 </p></dd><dt><span class="term"><code class="literal">random</code></span></dt><dd><p>
1382 Hosts and addresses are tried in random order. This value is mostly
1383 useful when opening multiple connections at the same time, possibly
1384 from different machines. This way connections can be load balanced
1385 across multiple <span class="productname">PostgreSQL</span> servers.
1387 While random load balancing, due to its random nature, will almost
1388 never result in a completely uniform distribution, it statistically
1389 gets quite close. One important aspect here is that this algorithm
1390 uses two levels of random choices: First the hosts
1391 will be resolved in random order. Then secondly, before resolving
1392 the next host, all resolved addresses for the current host will be
1393 tried in random order. This behaviour can skew the amount of
1394 connections each node gets greatly in certain cases, for instance
1395 when some hosts resolve to more addresses than others. But such a
1396 skew can also be used on purpose, e.g. to increase the number of
1397 connections a larger server gets by providing its hostname multiple
1398 times in the host string.
1400 When using this value it's recommended to also configure a reasonable
1401 value for <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-CONNECT-TIMEOUT">connect_timeout</a>. Because then,
1402 if one of the nodes that are used for load balancing is not responding,
1403 a new node will be tried.
1404 </p></dd></dl></div><p>
1405 </p></dd><dt id="LIBPQ-CONNECT-OAUTH-ISSUER"><span class="term"><code class="literal">oauth_issuer</code></span> <a href="#LIBPQ-CONNECT-OAUTH-ISSUER" class="id_link">#</a></dt><dd><p>
1406 The HTTPS URL of a trusted issuer to contact if the server requests an
1407 OAuth token for the connection. This parameter is required for all OAuth
1408 connections; it should exactly match the <code class="literal">issuer</code>
1409 setting in <a class="link" href="auth-oauth.html" title="20.15. OAuth Authorization/Authentication">the server's HBA configuration</a>.
1411 As part of the standard authentication handshake, <span class="application">libpq</span>
1412 will ask the server for a <span class="emphasis"><em>discovery document:</em></span> a URL
1413 providing a set of OAuth configuration parameters. The server must
1414 provide a URL that is directly constructed from the components of the
1415 <code class="literal">oauth_issuer</code>, and this value must exactly match the
1416 issuer identifier that is declared in the discovery document itself, or
1417 the connection will fail. This is required to prevent a class of
1418 <a class="ulink" href="https://mailarchive.ietf.org/arch/msg/oauth/JIVxFBGsJBVtm7ljwJhPUm3Fr-w/" target="_top">
1419 "mix-up attacks"</a> on OAuth clients.
1421 You may also explicitly set <code class="literal">oauth_issuer</code> to the
1422 <code class="literal">/.well-known/</code> URI used for OAuth discovery. In this
1423 case, if the server asks for a different URL, the connection will fail,
1424 but a <a class="link" href="libpq-oauth.html#LIBPQ-OAUTH-AUTHDATA-HOOKS" title="32.20.1. Authdata Hooks">custom OAuth flow</a>
1425 may be able to speed up the standard handshake by using previously
1426 cached tokens. (In this case, it is recommended that
1427 <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-OAUTH-SCOPE">oauth_scope</a> be set as well, since the
1428 client will not have a chance to ask the server for a correct scope
1429 setting, and the default scopes for a token may not be sufficient to
1430 connect.) <span class="application">libpq</span> currently supports the
1431 following well-known endpoints:
1432 </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">/.well-known/openid-configuration</code></p></li><li class="listitem"><p><code class="literal">/.well-known/oauth-authorization-server</code></p></li></ul></div><p>
1433 </p><div class="warning"><h3 class="title">Warning</h3><p>
1434 Issuers are highly privileged during the OAuth connection handshake. As
1435 a rule of thumb, if you would not trust the operator of a URL to handle
1436 access to your servers, or to impersonate you directly, that URL should
1437 not be trusted as an <code class="literal">oauth_issuer</code>.
1438 </p></div></dd><dt id="LIBPQ-CONNECT-OAUTH-CLIENT-ID"><span class="term"><code class="literal">oauth_client_id</code></span> <a href="#LIBPQ-CONNECT-OAUTH-CLIENT-ID" class="id_link">#</a></dt><dd><p>
1439 An OAuth 2.0 client identifier, as issued by the authorization server.
1440 If the <span class="productname">PostgreSQL</span> server
1441 <a class="link" href="auth-oauth.html" title="20.15. OAuth Authorization/Authentication">requests an OAuth token</a> for the
1442 connection (and if no <a class="link" href="libpq-oauth.html#LIBPQ-OAUTH-AUTHDATA-HOOKS" title="32.20.1. Authdata Hooks">custom
1443 OAuth hook</a> is installed to provide one), then this parameter must
1444 be set; otherwise, the connection will fail.
1445 </p></dd><dt id="LIBPQ-CONNECT-OAUTH-CLIENT-SECRET"><span class="term"><code class="literal">oauth_client_secret</code></span> <a href="#LIBPQ-CONNECT-OAUTH-CLIENT-SECRET" class="id_link">#</a></dt><dd><p>
1446 The client password, if any, to use when contacting the OAuth
1447 authorization server. Whether this parameter is required or not is
1448 determined by the OAuth provider; "public" clients generally do not use
1449 a secret, whereas "confidential" clients generally do.
1450 </p></dd><dt id="LIBPQ-CONNECT-OAUTH-SCOPE"><span class="term"><code class="literal">oauth_scope</code></span> <a href="#LIBPQ-CONNECT-OAUTH-SCOPE" class="id_link">#</a></dt><dd><p>
1451 The scope of the access request sent to the authorization server,
1452 specified as a (possibly empty) space-separated list of OAuth scope
1453 identifiers. This parameter is optional and intended for advanced usage.
1455 Usually the client will obtain appropriate scope settings from the
1456 <span class="productname">PostgreSQL</span> server. If this parameter is used,
1457 the server's requested scope list will be ignored. This can prevent a
1458 less-trusted server from requesting inappropriate access scopes from the
1459 end user. However, if the client's scope setting does not contain the
1460 server's required scopes, the server is likely to reject the issued
1461 token, and the connection will fail.
1463 The meaning of an empty scope list is provider-dependent. An OAuth
1464 authorization server may choose to issue a token with "default scope",
1465 whatever that happens to be, or it may reject the token request
1467 </p></dd></dl></div><p>
1468 </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 32. libpq — C Library">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-status.html" title="32.2. Connection Status Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 32. <span class="application">libpq</span> — C Library </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.2. Connection Status Functions</td></tr></table></div></body></html>
begriffs.com / projects / ai-pg / blob