diff options
Diffstat (limited to 'doc/src/sgml/html/libpq-connect.html')
| -rw-r--r-- | doc/src/sgml/html/libpq-connect.html | 1134 |
1 files changed, 1134 insertions, 0 deletions
diff --git a/doc/src/sgml/html/libpq-connect.html b/doc/src/sgml/html/libpq-connect.html new file mode 100644 index 0000000..28df8d2 --- /dev/null +++ b/doc/src/sgml/html/libpq-connect.html @@ -0,0 +1,1134 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.1. Database Connection Control Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq.html" title="Chapter 34. libpq — C Library" /><link rel="next" href="libpq-status.html" title="34.2. Connection Status Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.1. Database Connection Control Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 34. libpq — C Library">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-status.html" title="34.2. Connection Status Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-CONNECT"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.1. Database Connection Control Functions</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-CONNSTRING">34.1.1. Connection Strings</a></span></dt><dt><span class="sect2"><a href="libpq-connect.html#LIBPQ-PARAMKEYWORDS">34.1.2. Parameter Key Words</a></span></dt></dl></div><p> + The following functions deal with making a connection to a + <span class="productname">PostgreSQL</span> backend server. An + application program can have several backend connections open at + one time. (One reason to do that is to access more than one + database.) Each connection is represented by a + <code class="structname">PGconn</code><a id="id-1.7.3.8.2.3" class="indexterm"></a> object, which + is obtained from the function <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, + <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, or + <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a>. Note that these functions will always + return a non-null object pointer, unless perhaps there is too + little memory even to allocate the <code class="structname">PGconn</code> object. + The <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a> function should be called to check + the return value for a successful connection before queries are sent + via the connection object. + + </p><div class="warning"><h3 class="title">Warning</h3><p> + If untrusted users have access to a database that has not adopted a + <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage pattern</a>, + begin each session by removing publicly-writable schemas from + <code class="varname">search_path</code>. One can set parameter key + word <code class="literal">options</code> to + value <code class="literal">-csearch_path=</code>. Alternately, one can + issue <code class="literal">PQexec(<em class="replaceable"><code>conn</code></em>, "SELECT + pg_catalog.set_config('search_path', '', false)")</code> after + connecting. This consideration is not specific + to <span class="application">libpq</span>; it applies to every interface for + executing arbitrary SQL commands. + </p></div><p> + + </p><div class="warning"><h3 class="title">Warning</h3><p> + On Unix, forking a process with open libpq connections can lead to + unpredictable results because the parent and child processes share + the same sockets and operating system resources. For this reason, + such usage is not recommended, though doing an <code class="function">exec</code> from + the child process to load a new executable is safe. + </p></div><p> + + </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCONNECTDBPARAMS"><span class="term"><code class="function">PQconnectdbParams</code><a id="id-1.7.3.8.2.11.1.1.2" class="indexterm"></a></span></dt><dd><p> + Makes a new connection to the database server. + +</p><pre class="synopsis"> +PGconn *PQconnectdbParams(const char * const *keywords, + const char * const *values, + int expand_dbname); +</pre><p> + </p><p> + This function opens a new database connection using the parameters taken + from two <code class="symbol">NULL</code>-terminated arrays. The first, + <code class="literal">keywords</code>, is defined as an array of strings, each one + being a key word. The second, <code class="literal">values</code>, gives the value + for each key word. Unlike <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> below, the parameter + set can be extended without changing the function signature, so use of + this function (or its nonblocking analogs <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> + and <code class="function">PQconnectPoll</code>) is preferred for new application + programming. + </p><p> + The currently recognized parameter key words are listed in + <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>. + </p><p> + The passed arrays can be empty to use all default parameters, or can + contain one or more parameter settings. They must be matched in length. + Processing will stop at the first <code class="symbol">NULL</code> entry + in the <code class="literal">keywords</code> array. + Also, if the <code class="literal">values</code> entry associated with a + non-<code class="symbol">NULL</code> <code class="literal">keywords</code> entry is + <code class="symbol">NULL</code> or an empty string, that entry is ignored and + processing continues with the next pair of array entries. + </p><p> + When <code class="literal">expand_dbname</code> is non-zero, the value for + the first <em class="parameter"><code>dbname</code></em> key word is checked to see + if it is a <em class="firstterm">connection string</em>. If so, it + is <span class="quote">“<span class="quote">expanded</span>”</span> into the individual connection + parameters extracted from the string. The value is considered to + be a connection string, rather than just a database name, if it + contains an equal sign (<code class="literal">=</code>) or it begins with a + URI scheme designator. (More details on connection string formats + appear in <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>.) Only the first + occurrence of <em class="parameter"><code>dbname</code></em> is treated in this way; + any subsequent <em class="parameter"><code>dbname</code></em> parameter is processed + as a plain database name. + </p><p> + In general the parameter arrays are processed from start to end. + If any key word is repeated, the last value (that is + not <code class="symbol">NULL</code> or empty) is used. This rule applies in + particular when a key word found in a connection string conflicts + with one appearing in the <code class="literal">keywords</code> array. Thus, + the programmer may determine whether array entries can override or + be overridden by values taken from a connection string. Array + entries appearing before an expanded <em class="parameter"><code>dbname</code></em> + entry can be overridden by fields of the connection string, and in + turn those fields are overridden by array entries appearing + after <em class="parameter"><code>dbname</code></em> (but, again, only if those + entries supply non-empty values). + </p><p> + After processing all the array entries and any expanded connection + string, any connection parameters that remain unset are filled with + default values. If an unset parameter's corresponding environment + variable (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>) is set, its value is + used. If the environment variable is not set either, then the + parameter's built-in default value is used. + </p></dd><dt id="LIBPQ-PQCONNECTDB"><span class="term"><code class="function">PQconnectdb</code><a id="id-1.7.3.8.2.11.2.1.2" class="indexterm"></a></span></dt><dd><p> + Makes a new connection to the database server. + +</p><pre class="synopsis"> +PGconn *PQconnectdb(const char *conninfo); +</pre><p> + </p><p> + This function opens a new database connection using the parameters taken + from the string <code class="literal">conninfo</code>. + </p><p> + The passed string can be empty to use all default parameters, or it can + contain one or more parameter settings separated by whitespace, + or it can contain a <acronym class="acronym">URI</acronym>. + See <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for details. + </p></dd><dt id="LIBPQ-PQSETDBLOGIN"><span class="term"><code class="function">PQsetdbLogin</code><a id="id-1.7.3.8.2.11.3.1.2" class="indexterm"></a></span></dt><dd><p> + Makes a new connection to the database server. +</p><pre class="synopsis"> +PGconn *PQsetdbLogin(const char *pghost, + const char *pgport, + const char *pgoptions, + const char *pgtty, + const char *dbName, + const char *login, + const char *pwd); +</pre><p> + </p><p> + This is the predecessor of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> with a fixed + set of parameters. It has the same functionality except that the + missing parameters will always take on default values. Write <code class="symbol">NULL</code> or an + empty string for any one of the fixed parameters that is to be defaulted. + </p><p> + If the <em class="parameter"><code>dbName</code></em> contains + an <code class="symbol">=</code> sign or has a valid connection <acronym class="acronym">URI</acronym> prefix, it + is taken as a <em class="parameter"><code>conninfo</code></em> string in exactly the same way as + if it had been passed to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and the remaining + parameters are then applied as specified for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>. + </p><p> + <code class="literal">pgtty</code> is no longer used and any value passed will + be ignored. + </p></dd><dt id="LIBPQ-PQSETDB"><span class="term"><code class="function">PQsetdb</code><a id="id-1.7.3.8.2.11.4.1.2" class="indexterm"></a></span></dt><dd><p> + Makes a new connection to the database server. +</p><pre class="synopsis"> +PGconn *PQsetdb(char *pghost, + char *pgport, + char *pgoptions, + char *pgtty, + char *dbName); +</pre><p> + </p><p> + This is a macro that calls <a class="xref" href="libpq-connect.html#LIBPQ-PQSETDBLOGIN"><code class="function">PQsetdbLogin</code></a> with null pointers + for the <em class="parameter"><code>login</code></em> and <em class="parameter"><code>pwd</code></em> parameters. It is provided + for backward compatibility with very old programs. + </p></dd><dt id="LIBPQ-PQCONNECTSTARTPARAMS"><span class="term"><code class="function">PQconnectStartParams</code><a id="id-1.7.3.8.2.11.5.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQconnectStart</code><a id="id-1.7.3.8.2.11.5.2.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQconnectPoll</code><a id="id-1.7.3.8.2.11.5.3.2" class="indexterm"></a></span></dt><dd><p> + <a id="id-1.7.3.8.2.11.5.4.1.1" class="indexterm"></a> + Make a connection to the database server in a nonblocking manner. + +</p><pre class="synopsis"> +PGconn *PQconnectStartParams(const char * const *keywords, + const char * const *values, + int expand_dbname); + +PGconn *PQconnectStart(const char *conninfo); + +PostgresPollingStatusType PQconnectPoll(PGconn *conn); +</pre><p> + </p><p> + These three functions are used to open a connection to a database server such + that your application's thread of execution is not blocked on remote I/O + whilst doing so. The point of this approach is that the waits for I/O to + complete can occur in the application's main loop, rather than down inside + <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a> or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, and so the + application can manage this operation in parallel with other activities. + </p><p> + With <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, the database connection is made + using the parameters taken from the <code class="literal">keywords</code> and + <code class="literal">values</code> arrays, and controlled by <code class="literal">expand_dbname</code>, + as described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>. + </p><p> + With <code class="function">PQconnectStart</code>, the database connection is made + using the parameters taken from the string <code class="literal">conninfo</code> as + described above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>. + </p><p> + Neither <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> nor <code class="function">PQconnectStart</code> + nor <code class="function">PQconnectPoll</code> will block, so long as a number of + restrictions are met: + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + The <code class="literal">hostaddr</code> parameter must be used appropriately + to prevent DNS queries from being made. See the documentation of + this parameter in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a> for details. + </p></li><li class="listitem"><p> + If you call <a class="xref" href="libpq-control.html#LIBPQ-PQTRACE"><code class="function">PQtrace</code></a>, ensure that the stream object + into which you trace will not block. + </p></li><li class="listitem"><p> + You must ensure that the socket is in the appropriate state + before calling <code class="function">PQconnectPoll</code>, as described below. + </p></li></ul></div><p> + </p><p> + To begin a nonblocking connection request, + call <code class="function">PQconnectStart</code> + or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>. If the result is null, + then <span class="application">libpq</span> has been unable to allocate a + new <code class="structname">PGconn</code> structure. Otherwise, a + valid <code class="structname">PGconn</code> pointer is returned (though not + yet representing a valid connection to the database). Next + call <code class="literal">PQstatus(conn)</code>. If the result + is <code class="symbol">CONNECTION_BAD</code>, the connection attempt has already + failed, typically because of invalid connection parameters. + </p><p> + If <code class="function">PQconnectStart</code> + or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> succeeds, the next stage + is to poll <span class="application">libpq</span> so that it can proceed with + the connection sequence. + Use <code class="function">PQsocket(conn)</code> to obtain the descriptor of the + socket underlying the database connection. + (Caution: do not assume that the socket remains the same + across <code class="function">PQconnectPoll</code> calls.) + Loop thus: If <code class="function">PQconnectPoll(conn)</code> last returned + <code class="symbol">PGRES_POLLING_READING</code>, wait until the socket is ready to + read (as indicated by <code class="function">select()</code>, <code class="function">poll()</code>, or + similar system function). + Then call <code class="function">PQconnectPoll(conn)</code> again. + Conversely, if <code class="function">PQconnectPoll(conn)</code> last returned + <code class="symbol">PGRES_POLLING_WRITING</code>, wait until the socket is ready + to write, then call <code class="function">PQconnectPoll(conn)</code> again. + On the first iteration, i.e., if you have yet to call + <code class="function">PQconnectPoll</code>, behave as if it last returned + <code class="symbol">PGRES_POLLING_WRITING</code>. Continue this loop until + <code class="function">PQconnectPoll(conn)</code> returns + <code class="symbol">PGRES_POLLING_FAILED</code>, indicating the connection procedure + has failed, or <code class="symbol">PGRES_POLLING_OK</code>, indicating the connection + has been successfully made. + </p><p> + At any time during connection, the status of the connection can be + checked by calling <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>. If this call returns <code class="symbol">CONNECTION_BAD</code>, then the + connection procedure has failed; if the call returns <code class="function">CONNECTION_OK</code>, then the + connection is ready. Both of these states are equally detectable + from the return value of <code class="function">PQconnectPoll</code>, described above. Other states might also occur + during (and only during) an asynchronous connection procedure. These + indicate the current stage of the connection procedure and might be useful + to provide feedback to the user for example. These statuses are: + + </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CONNECTION-STARTED"><span class="term"><code class="symbol">CONNECTION_STARTED</code></span></dt><dd><p> + Waiting for connection to be made. + </p></dd><dt id="LIBPQ-CONNECTION-MADE"><span class="term"><code class="symbol">CONNECTION_MADE</code></span></dt><dd><p> + Connection OK; waiting to send. + </p></dd><dt id="LIBPQ-CONNECTION-AWAITING-RESPONSE"><span class="term"><code class="symbol">CONNECTION_AWAITING_RESPONSE</code></span></dt><dd><p> + Waiting for a response from the server. + </p></dd><dt id="LIBPQ-CONNECTION-AUTH-OK"><span class="term"><code class="symbol">CONNECTION_AUTH_OK</code></span></dt><dd><p> + Received authentication; waiting for backend start-up to finish. + </p></dd><dt id="LIBPQ-CONNECTION-SSL-STARTUP"><span class="term"><code class="symbol">CONNECTION_SSL_STARTUP</code></span></dt><dd><p> + Negotiating SSL encryption. + </p></dd><dt id="LIBPQ-CONNECTION-SETENV"><span class="term"><code class="symbol">CONNECTION_SETENV</code></span></dt><dd><p> + Negotiating environment-driven parameter settings. + </p></dd><dt id="LIBPQ-CONNECTION-CHECK-WRITABLE"><span class="term"><code class="symbol">CONNECTION_CHECK_WRITABLE</code></span></dt><dd><p> + Checking if connection is able to handle write transactions. + </p></dd><dt id="LIBPQ-CONNECTION-CONSUME"><span class="term"><code class="symbol">CONNECTION_CONSUME</code></span></dt><dd><p> + Consuming any remaining response messages on connection. + </p></dd></dl></div><p> + + Note that, although these constants will remain (in order to maintain + compatibility), an application should never rely upon these occurring in a + particular order, or at all, or on the status always being one of these + documented values. An application might do something like this: +</p><pre class="programlisting"> +switch(PQstatus(conn)) +{ + case CONNECTION_STARTED: + feedback = "Connecting..."; + break; + + case CONNECTION_MADE: + feedback = "Connected to server..."; + break; +. +. +. + default: + feedback = "Connecting..."; +} +</pre><p> + </p><p> + The <code class="literal">connect_timeout</code> connection parameter is ignored + when using <code class="function">PQconnectPoll</code>; it is the application's + responsibility to decide whether an excessive amount of time has elapsed. + Otherwise, <code class="function">PQconnectStart</code> followed by a + <code class="function">PQconnectPoll</code> loop is equivalent to + <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>. + </p><p> + Note that when <code class="function">PQconnectStart</code> + or <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a> returns a non-null + pointer, you must call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> when you are + finished with it, in order to dispose of the structure and any + associated memory blocks. This must be done even if the connection + attempt fails or is abandoned. + </p></dd><dt id="LIBPQ-PQCONNDEFAULTS"><span class="term"><code class="function">PQconndefaults</code><a id="id-1.7.3.8.2.11.6.1.2" class="indexterm"></a></span></dt><dd><p> + Returns the default connection options. +</p><pre class="synopsis"> +PQconninfoOption *PQconndefaults(void); + +typedef struct +{ + char *keyword; /* The keyword of the option */ + char *envvar; /* Fallback environment variable name */ + char *compiled; /* Fallback compiled in default value */ + char *val; /* Option's current value, or NULL */ + char *label; /* Label for field in connect dialog */ + char *dispchar; /* Indicates how to display this field + in a connect dialog. Values are: + "" Display entered value as is + "*" Password field - hide value + "D" Debug option - don't show by default */ + int dispsize; /* Field size in characters for dialog */ +} PQconninfoOption; +</pre><p> + </p><p> + Returns a connection options array. This can be used to determine + all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and their + current default values. The return value points to an array of + <code class="structname">PQconninfoOption</code> structures, which ends + with an entry having a null <code class="structfield">keyword</code> pointer. The + null pointer is returned if memory could not be allocated. Note that + the current default values (<code class="structfield">val</code> fields) + will depend on environment variables and other context. A + missing or invalid service file will be silently ignored. Callers + must treat the connection options data as read-only. + </p><p> + After processing the options array, free it by passing it to + <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>. If this is not done, a small amount of memory + is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a>. + </p></dd><dt id="LIBPQ-PQCONNINFO"><span class="term"><code class="function">PQconninfo</code><a id="id-1.7.3.8.2.11.7.1.2" class="indexterm"></a></span></dt><dd><p> + Returns the connection options used by a live connection. +</p><pre class="synopsis"> +PQconninfoOption *PQconninfo(PGconn *conn); +</pre><p> + </p><p> + Returns a connection options array. This can be used to determine + all possible <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options and the + values that were used to connect to the server. The return + value points to an array of <code class="structname">PQconninfoOption</code> + structures, which ends with an entry having a null <code class="structfield">keyword</code> + pointer. All notes above for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNDEFAULTS"><code class="function">PQconndefaults</code></a> also + apply to the result of <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFO"><code class="function">PQconninfo</code></a>. + </p></dd><dt id="LIBPQ-PQCONNINFOPARSE"><span class="term"><code class="function">PQconninfoParse</code><a id="id-1.7.3.8.2.11.8.1.2" class="indexterm"></a></span></dt><dd><p> + Returns parsed connection options from the provided connection string. + +</p><pre class="synopsis"> +PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); +</pre><p> + </p><p> + Parses a connection string and returns the resulting options as an + array; or returns <code class="symbol">NULL</code> if there is a problem with the connection + string. This function can be used to extract + the <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a> options in the provided + connection string. The return value points to an array of + <code class="structname">PQconninfoOption</code> structures, which ends + with an entry having a null <code class="structfield">keyword</code> pointer. + </p><p> + All legal options will be present in the result array, but the + <code class="literal">PQconninfoOption</code> for any option not present + in the connection string will have <code class="literal">val</code> set to + <code class="literal">NULL</code>; default values are not inserted. + </p><p> + If <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>, then <code class="literal">*errmsg</code> is set + to <code class="symbol">NULL</code> on success, else to a <code class="function">malloc</code>'d error string explaining + the problem. (It is also possible for <code class="literal">*errmsg</code> to be + set to <code class="symbol">NULL</code> and the function to return <code class="symbol">NULL</code>; + this indicates an out-of-memory condition.) + </p><p> + After processing the options array, free it by passing it to + <a class="xref" href="libpq-misc.html#LIBPQ-PQCONNINFOFREE"><code class="function">PQconninfoFree</code></a>. If this is not done, some memory + is leaked for each call to <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNINFOPARSE"><code class="function">PQconninfoParse</code></a>. + Conversely, if an error occurs and <code class="literal">errmsg</code> is not <code class="symbol">NULL</code>, + be sure to free the error string using <a class="xref" href="libpq-misc.html#LIBPQ-PQFREEMEM"><code class="function">PQfreemem</code></a>. + </p></dd><dt id="LIBPQ-PQFINISH"><span class="term"><code class="function">PQfinish</code><a id="id-1.7.3.8.2.11.9.1.2" class="indexterm"></a></span></dt><dd><p> + Closes the connection to the server. Also frees + memory used by the <code class="structname">PGconn</code> object. +</p><pre class="synopsis"> +void PQfinish(PGconn *conn); +</pre><p> + </p><p> + Note that even if the server connection attempt fails (as + indicated by <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>), the application should call <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> + to free the memory used by the <code class="structname">PGconn</code> object. + The <code class="structname">PGconn</code> pointer must not be used again after + <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a> has been called. + </p></dd><dt id="LIBPQ-PQRESET"><span class="term"><code class="function">PQreset</code><a id="id-1.7.3.8.2.11.10.1.2" class="indexterm"></a></span></dt><dd><p> + Resets the communication channel to the server. +</p><pre class="synopsis"> +void PQreset(PGconn *conn); +</pre><p> + </p><p> + This function will close the connection + to the server and attempt to establish a new + connection, using all the same + parameters previously used. This might be useful for + error recovery if a working connection is lost. + </p></dd><dt id="LIBPQ-PQRESETSTART"><span class="term"><code class="function">PQresetStart</code><a id="id-1.7.3.8.2.11.11.1.2" class="indexterm"></a><br /></span><span class="term"><code class="function">PQresetPoll</code><a id="id-1.7.3.8.2.11.11.2.2" class="indexterm"></a></span></dt><dd><p> + Reset the communication channel to the server, in a nonblocking manner. + +</p><pre class="synopsis"> +int PQresetStart(PGconn *conn); + +PostgresPollingStatusType PQresetPoll(PGconn *conn); +</pre><p> + </p><p> + These functions will close the connection to the server and attempt to + establish a new connection, using all the same + parameters previously used. This can be useful for error recovery if a + working connection is lost. They differ from <a class="xref" href="libpq-connect.html#LIBPQ-PQRESET"><code class="function">PQreset</code></a> (above) in that they + act in a nonblocking manner. These functions suffer from the same + restrictions as <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, <code class="function">PQconnectStart</code> + and <code class="function">PQconnectPoll</code>. + </p><p> + To initiate a connection reset, call + <a class="xref" href="libpq-connect.html#LIBPQ-PQRESETSTART"><code class="function">PQresetStart</code></a>. If it returns 0, the reset has + failed. If it returns 1, poll the reset using + <code class="function">PQresetPoll</code> in exactly the same way as you + would create the connection using <code class="function">PQconnectPoll</code>. + </p></dd><dt id="LIBPQ-PQPINGPARAMS"><span class="term"><code class="function">PQpingParams</code><a id="id-1.7.3.8.2.11.12.1.2" class="indexterm"></a></span></dt><dd><p> + <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a> reports the status of the + server. It accepts connection parameters identical to those of + <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS"><code class="function">PQconnectdbParams</code></a>, described above. It is not + necessary to supply correct user name, password, or database name + values to obtain the server status; however, if incorrect values + are provided, the server will log a failed connection attempt. + +</p><pre class="synopsis"> +PGPing PQpingParams(const char * const *keywords, + const char * const *values, + int expand_dbname); +</pre><p> + + The function returns one of the following values: + + </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQPINGPARAMS-PQPING_OK"><span class="term"><code class="literal">PQPING_OK</code></span></dt><dd><p> + The server is running and appears to be accepting connections. + </p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_REJECT"><span class="term"><code class="literal">PQPING_REJECT</code></span></dt><dd><p> + The server is running but is in a state that disallows connections + (startup, shutdown, or crash recovery). + </p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_NO_RESPONSE"><span class="term"><code class="literal">PQPING_NO_RESPONSE</code></span></dt><dd><p> + The server could not be contacted. This might indicate that the + server is not running, or that there is something wrong with the + given connection parameters (for example, wrong port number), or + that there is a network connectivity problem (for example, a + firewall blocking the connection request). + </p></dd><dt id="LIBPQ-PQPINGPARAMS-PQPING_NO_ATTEMPT"><span class="term"><code class="literal">PQPING_NO_ATTEMPT</code></span></dt><dd><p> + No attempt was made to contact the server, because the supplied + parameters were obviously incorrect or there was some client-side + problem (for example, out of memory). + </p></dd></dl></div><p> + + </p></dd><dt id="LIBPQ-PQPING"><span class="term"><code class="function">PQping</code><a id="id-1.7.3.8.2.11.13.1.2" class="indexterm"></a></span></dt><dd><p> + <a class="xref" href="libpq-connect.html#LIBPQ-PQPING"><code class="function">PQping</code></a> reports the status of the + server. It accepts connection parameters identical to those of + <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTDB"><code class="function">PQconnectdb</code></a>, described above. It is not + necessary to supply correct user name, password, or database name + values to obtain the server status; however, if incorrect values + are provided, the server will log a failed connection attempt. + +</p><pre class="synopsis"> +PGPing PQping(const char *conninfo); +</pre><p> + </p><p> + The return values are the same as for <a class="xref" href="libpq-connect.html#LIBPQ-PQPINGPARAMS"><code class="function">PQpingParams</code></a>. + </p></dd><dt id="LIBPQ-PQSETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQsetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.14.1.2" class="indexterm"></a></span></dt><dd><p> + <code class="function">PQsetSSLKeyPassHook_OpenSSL</code> lets an application override + <span class="application">libpq</span>'s <a class="link" href="libpq-ssl.html#LIBPQ-SSL-CLIENTCERT" title="34.19.2. Client Certificates">default + handling of encrypted client certificate key files</a> using + <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLPASSWORD">sslpassword</a> or interactive prompting. + +</p><pre class="synopsis"> +void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); +</pre><p> + + The application passes a pointer to a callback function with signature: +</p><pre class="programlisting"> +int callback_fn(char *buf, int size, PGconn *conn); +</pre><p> + which <span class="application">libpq</span> will then call + <span class="emphasis"><em>instead of</em></span> its default + <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> handler. The + callback should determine the password for the key and copy it to + result-buffer <em class="parameter"><code>buf</code></em> of size + <em class="parameter"><code>size</code></em>. The string in <em class="parameter"><code>buf</code></em> + must be null-terminated. The callback must return the length of the + password stored in <em class="parameter"><code>buf</code></em> excluding the null + terminator. On failure, the callback should set + <code class="literal">buf[0] = '\0'</code> and return 0. See + <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code> in + <span class="application">libpq</span>'s source code for an example. + </p><p> + If the user specified an explicit key location, + its path will be in <code class="literal">conn->sslkey</code> when the callback + is invoked. This will be empty if the default key path is being used. + For keys that are engine specifiers, it is up to engine implementations + whether they use the <span class="productname">OpenSSL</span> password + callback or define their own handling. + </p><p> + The app callback may choose to delegate unhandled cases to + <code class="function">PQdefaultSSLKeyPassHook_OpenSSL</code>, + or call it first and try something else if it returns 0, or completely override it. + </p><p> + The callback <span class="emphasis"><em>must not</em></span> escape normal flow control with exceptions, + <code class="function">longjmp(...)</code>, etc. It must return normally. + </p></dd><dt id="LIBPQ-PQGETSSLKEYPASSHOOK-OPENSSL"><span class="term"><code class="function">PQgetSSLKeyPassHook_OpenSSL</code><a id="id-1.7.3.8.2.11.15.1.2" class="indexterm"></a></span></dt><dd><p> + <code class="function">PQgetSSLKeyPassHook_OpenSSL</code> returns the current + client certificate key password hook, or <code class="literal">NULL</code> + if none has been set. + +</p><pre class="synopsis"> +PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); +</pre><p> + </p></dd></dl></div><p> + </p><div class="sect2" id="LIBPQ-CONNSTRING"><div class="titlepage"><div><div><h3 class="title">34.1.1. Connection Strings</h3></div></div></div><a id="id-1.7.3.8.3.2" class="indexterm"></a><a id="id-1.7.3.8.3.3" class="indexterm"></a><p> + Several <span class="application">libpq</span> functions parse a user-specified string to obtain + connection parameters. There are two accepted formats for these strings: + plain keyword/value strings + and URIs. URIs generally follow + <a class="ulink" href="https://tools.ietf.org/html/rfc3986" target="_top">RFC + 3986</a>, except that multi-host connection strings are allowed + as further described below. + </p><div class="sect3" id="id-1.7.3.8.3.5"><div class="titlepage"><div><div><h4 class="title">34.1.1.1. Keyword/Value Connection Strings</h4></div></div></div><p> + In the keyword/value format, each parameter setting is in the form + <em class="replaceable"><code>keyword</code></em> <code class="literal">=</code> + <em class="replaceable"><code>value</code></em>, with space(s) between settings. + Spaces around a setting's equal sign are + optional. To write an empty value, or a value containing spaces, surround it + with single quotes, for example <code class="literal">keyword = 'a value'</code>. + Single quotes and backslashes within + a value must be escaped with a backslash, i.e., <code class="literal">\'</code> and + <code class="literal">\\</code>. + </p><p> + Example: +</p><pre class="programlisting"> +host=localhost port=5432 dbname=mydb connect_timeout=10 +</pre><p> + </p><p> + The recognized parameter key words are listed in <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>. + </p></div><div class="sect3" id="id-1.7.3.8.3.6"><div class="titlepage"><div><div><h4 class="title">34.1.1.2. Connection URIs</h4></div></div></div><p> + The general form for a connection <acronym class="acronym">URI</acronym> is: +</p><pre class="synopsis"> +postgresql://[<span class="optional"><em class="replaceable"><code>userspec</code></em>@</span>][<span class="optional"><em class="replaceable"><code>hostspec</code></em></span>][<span class="optional">/<em class="replaceable"><code>dbname</code></em></span>][<span class="optional">?<em class="replaceable"><code>paramspec</code></em></span>] + +<span class="phrase">where <em class="replaceable"><code>userspec</code></em> is:</span> + +<em class="replaceable"><code>user</code></em>[<span class="optional">:<em class="replaceable"><code>password</code></em></span>] + +<span class="phrase">and <em class="replaceable"><code>hostspec</code></em> is:</span> + +[<span class="optional"><em class="replaceable"><code>host</code></em></span>][<span class="optional">:<em class="replaceable"><code>port</code></em></span>][<span class="optional">,...</span>] + +<span class="phrase">and <em class="replaceable"><code>paramspec</code></em> is:</span> + +<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>[<span class="optional">&...</span>] +</pre><p> + </p><p> + The <acronym class="acronym">URI</acronym> scheme designator can be either + <code class="literal">postgresql://</code> or <code class="literal">postgres://</code>. Each + of the remaining <acronym class="acronym">URI</acronym> parts is optional. The + following examples illustrate valid <acronym class="acronym">URI</acronym> syntax: +</p><pre class="programlisting"> +postgresql:// +postgresql://localhost +postgresql://localhost:5433 +postgresql://localhost/mydb +postgresql://user@localhost +postgresql://user:secret@localhost +postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp +postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp +</pre><p> + Values that would normally appear in the hierarchical part of + the <acronym class="acronym">URI</acronym> can alternatively be given as named + parameters. For example: +</p><pre class="programlisting"> +postgresql:///mydb?host=localhost&port=5433 +</pre><p> + All named parameters must match key words listed in + <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a>, except that for compatibility + with JDBC connection <acronym class="acronym">URI</acronym>s, instances + of <code class="literal">ssl=true</code> are translated into + <code class="literal">sslmode=require</code>. + </p><p> + The connection <acronym class="acronym">URI</acronym> needs to be encoded with <a class="ulink" href="https://tools.ietf.org/html/rfc3986#section-2.1" target="_top">percent-encoding</a> + if it includes symbols with special meaning in any of its parts. Here is + an example where the equal sign (<code class="literal">=</code>) is replaced with + <code class="literal">%3D</code> and the space character with + <code class="literal">%20</code>: +</p><pre class="programlisting"> +postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff +</pre><p> + </p><p> + The host part may be either a host name or an IP address. To specify an + IPv6 address, enclose it in square brackets: +</p><pre class="synopsis"> +postgresql://[2001:db8::1234]/database +</pre><p> + </p><p> + The host part is interpreted as described for the parameter <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-HOST">host</a>. In particular, a Unix-domain socket + connection is chosen if the host part is either empty or looks like an + absolute path name, + otherwise a TCP/IP connection is initiated. Note, however, that the + slash is a reserved character in the hierarchical part of the URI. So, to + specify a non-standard Unix-domain socket directory, either omit the host + part of the URI and specify the host as a named parameter, or + percent-encode the path in the host part of the URI: +</p><pre class="programlisting"> +postgresql:///dbname?host=/var/lib/postgresql +postgresql://%2Fvar%2Flib%2Fpostgresql/dbname +</pre><p> + </p><p> + It is possible to specify multiple host components, each with an optional + port component, in a single URI. A URI of the form + <code class="literal">postgresql://host1:port1,host2:port2,host3:port3/</code> + is equivalent to a connection string of the form + <code class="literal">host=host1,host2,host3 port=port1,port2,port3</code>. + As further described below, each + host will be tried in turn until a connection is successfully established. + </p></div><div class="sect3" id="LIBPQ-MULTIPLE-HOSTS"><div class="titlepage"><div><div><h4 class="title">34.1.1.3. Specifying Multiple Hosts</h4></div></div></div><p> + It is possible to specify multiple hosts to connect to, so that they are + tried in the given order. In the Keyword/Value format, the <code class="literal">host</code>, + <code class="literal">hostaddr</code>, and <code class="literal">port</code> options accept comma-separated + lists of values. The same number of elements must be given in each + option that is specified, such + that e.g., the first <code class="literal">hostaddr</code> corresponds to the first host name, + the second <code class="literal">hostaddr</code> corresponds to the second host name, and so + forth. As an exception, if only one <code class="literal">port</code> is specified, it + applies to all the hosts. + </p><p> + In the connection URI format, you can list multiple <code class="literal">host:port</code> pairs + separated by commas in the <code class="literal">host</code> component of the URI. + </p><p> + In either format, a single host name can translate to multiple network + addresses. A common example of this is a host that has both an IPv4 and + an IPv6 address. + </p><p> + When multiple hosts are specified, or when a single host name is + translated to multiple addresses, all the hosts and addresses will be + tried in order, until one succeeds. If none of the hosts can be reached, + the connection fails. If a connection is established successfully, but + authentication fails, the remaining hosts in the list are not tried. + </p><p> + If a password file is used, you can have different passwords for + different hosts. All the other connection options are the same for every + host in the list; it is not possible to e.g., specify different + usernames for different hosts. + </p></div></div><div class="sect2" id="LIBPQ-PARAMKEYWORDS"><div class="titlepage"><div><div><h3 class="title">34.1.2. Parameter Key Words</h3></div></div></div><p> + The currently recognized parameter key words are: + + </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-CONNECT-HOST"><span class="term"><code class="literal">host</code></span></dt><dd><p> + Name of host to connect to.<a id="id-1.7.3.8.4.2.1.1.2.1.1" class="indexterm"></a> If a host name looks like an absolute path + name, it specifies Unix-domain communication rather than TCP/IP + communication; the value is the name of the directory in which the + socket file is stored. (On Unix, an absolute path name begins with a + slash. On Windows, paths starting with drive letters are also + recognized.) If the host name starts with <code class="literal">@</code>, it is + taken as a Unix-domain socket in the abstract namespace (currently + supported on Linux and Windows). + The default behavior when <code class="literal">host</code> is not + specified, or is empty, is to connect to a Unix-domain + socket<a id="id-1.7.3.8.4.2.1.1.2.1.4" class="indexterm"></a> in + <code class="filename">/tmp</code> (or whatever socket directory was specified + when <span class="productname">PostgreSQL</span> was built). On Windows and + on machines without Unix-domain sockets, the default is to connect to + <code class="literal">localhost</code>. + </p><p> + A comma-separated list of host names is also accepted, in which case + each host name in the list is tried in order; an empty item in the + list selects the default behavior as explained above. See + <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details. + </p></dd><dt id="LIBPQ-CONNECT-HOSTADDR"><span class="term"><code class="literal">hostaddr</code></span></dt><dd><p> + Numeric IP address of host to connect to. This should be in the + standard IPv4 address format, e.g., <code class="literal">172.28.40.9</code>. If + your machine supports IPv6, you can also use those addresses. + TCP/IP communication is + always used when a nonempty string is specified for this parameter. + If this parameter is not specified, the value of <code class="literal">host</code> + will be looked up to find the corresponding IP address — or, if + <code class="literal">host</code> specifies an IP address, that value will be + used directly. + </p><p> + Using <code class="literal">hostaddr</code> allows the + application to avoid a host name look-up, which might be important + in applications with time constraints. However, a host name is + required for GSSAPI or SSPI authentication + methods, as well as for <code class="literal">verify-full</code> SSL + certificate verification. The following rules are used: + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + If <code class="literal">host</code> is specified + without <code class="literal">hostaddr</code>, a host name lookup occurs. + (When using <code class="function">PQconnectPoll</code>, the lookup occurs + when <code class="function">PQconnectPoll</code> first considers this host + name, and it may cause <code class="function">PQconnectPoll</code> to block + for a significant amount of time.) + </p></li><li class="listitem"><p> + If <code class="literal">hostaddr</code> is specified without <code class="literal">host</code>, + the value for <code class="literal">hostaddr</code> gives the server network address. + The connection attempt will fail if the authentication + method requires a host name. + </p></li><li class="listitem"><p> + If both <code class="literal">host</code> and <code class="literal">hostaddr</code> are specified, + the value for <code class="literal">hostaddr</code> gives the server network address. + The value for <code class="literal">host</code> is ignored unless the + authentication method requires it, in which case it will be + used as the host name. + </p></li></ul></div><p> + Note that authentication is likely to fail if <code class="literal">host</code> + is not the name of the server at network address <code class="literal">hostaddr</code>. + Also, when both <code class="literal">host</code> and <code class="literal">hostaddr</code> + are specified, <code class="literal">host</code> + is used to identify the connection in a password file (see + <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>). + </p><p> + A comma-separated list of <code class="literal">hostaddr</code> values is also + accepted, in which case each host in the list is tried in order. + An empty item in the list causes the corresponding host name to be + used, or the default host name if that is empty as well. See + <a class="xref" href="libpq-connect.html#LIBPQ-MULTIPLE-HOSTS" title="34.1.1.3. Specifying Multiple Hosts">Section 34.1.1.3</a> for details. + </p><p> + Without either a host name or host address, + <span class="application">libpq</span> will connect using a local + Unix-domain socket; or on Windows and on machines without Unix-domain + sockets, it will attempt to connect to <code class="literal">localhost</code>. + </p></dd><dt id="LIBPQ-CONNECT-PORT"><span class="term"><code class="literal">port</code></span></dt><dd><p> + Port number to connect to at the server host, or socket file + name extension for Unix-domain + connections.<a id="id-1.7.3.8.4.2.1.3.2.1.1" class="indexterm"></a> + If multiple hosts were given in the <code class="literal">host</code> or + <code class="literal">hostaddr</code> parameters, this parameter may specify a + comma-separated list of ports of the same length as the host list, or + it may specify a single port number to be used for all hosts. + An empty string, or an empty item in a comma-separated list, + specifies the default port number established + when <span class="productname">PostgreSQL</span> was built. + </p></dd><dt id="LIBPQ-CONNECT-DBNAME"><span class="term"><code class="literal">dbname</code></span></dt><dd><p> + The database name. Defaults to be the same as the user name. + In certain contexts, the value is checked for extended + formats; see <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a> for more details on + those. + </p></dd><dt id="LIBPQ-CONNECT-USER"><span class="term"><code class="literal">user</code></span></dt><dd><p> + <span class="productname">PostgreSQL</span> user name to connect as. + Defaults to be the same as the operating system name of the user + running the application. + </p></dd><dt id="LIBPQ-CONNECT-PASSWORD"><span class="term"><code class="literal">password</code></span></dt><dd><p> + Password to be used if the server demands password authentication. + </p></dd><dt id="LIBPQ-CONNECT-PASSFILE"><span class="term"><code class="literal">passfile</code></span></dt><dd><p> + Specifies the name of the file used to store passwords + (see <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a>). + Defaults to <code class="filename">~/.pgpass</code>, or + <code class="filename">%APPDATA%\postgresql\pgpass.conf</code> on Microsoft Windows. + (No error is reported if this file does not exist.) + </p></dd><dt id="LIBPQ-CONNECT-CHANNEL-BINDING"><span class="term"><code class="literal">channel_binding</code></span></dt><dd><p> + This option controls the client's use of channel binding. A setting + of <code class="literal">require</code> means that the connection must employ + channel binding, <code class="literal">prefer</code> means that the client will + choose channel binding if available, and <code class="literal">disable</code> + prevents the use of channel binding. The default + is <code class="literal">prefer</code> if + <span class="productname">PostgreSQL</span> is compiled with SSL support; + otherwise the default is <code class="literal">disable</code>. + </p><p> + Channel binding is a method for the server to authenticate itself to + the client. It is only supported over SSL connections + with <span class="productname">PostgreSQL</span> 11 or later servers using + the <code class="literal">SCRAM</code> authentication method. + </p></dd><dt id="LIBPQ-CONNECT-CONNECT-TIMEOUT"><span class="term"><code class="literal">connect_timeout</code></span></dt><dd><p> + Maximum time to wait while connecting, in seconds (write as a decimal integer, + e.g., <code class="literal">10</code>). Zero, negative, or not specified means + wait indefinitely. The minimum allowed timeout is 2 seconds, therefore + a value of <code class="literal">1</code> is interpreted as <code class="literal">2</code>. + This timeout applies separately to each host name or IP address. + For example, if you specify two hosts and <code class="literal">connect_timeout</code> + is 5, each host will time out if no connection is made within 5 + seconds, so the total time spent waiting for a connection might be + up to 10 seconds. + </p></dd><dt id="LIBPQ-CONNECT-CLIENT-ENCODING"><span class="term"><code class="literal">client_encoding</code></span></dt><dd><p> + This sets the <code class="varname">client_encoding</code> + configuration parameter for this connection. In addition to + the values accepted by the corresponding server option, you + can use <code class="literal">auto</code> to determine the right + encoding from the current locale in the client + (<code class="envar">LC_CTYPE</code> environment variable on Unix + systems). + </p></dd><dt id="LIBPQ-CONNECT-OPTIONS"><span class="term"><code class="literal">options</code></span></dt><dd><p> + Specifies command-line options to send to the server at connection + start. For example, setting this to <code class="literal">-c geqo=off</code> sets the + session's value of the <code class="varname">geqo</code> parameter to + <code class="literal">off</code>. Spaces within this string are considered to + separate command-line arguments, unless escaped with a backslash + (<code class="literal">\</code>); write <code class="literal">\\</code> to represent a literal + backslash. For a detailed discussion of the available + options, consult <a class="xref" href="runtime-config.html" title="Chapter 20. Server Configuration">Chapter 20</a>. + </p></dd><dt id="LIBPQ-CONNECT-APPLICATION-NAME"><span class="term"><code class="literal">application_name</code></span></dt><dd><p> + Specifies a value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a> + configuration parameter. + </p></dd><dt id="LIBPQ-CONNECT-FALLBACK-APPLICATION-NAME"><span class="term"><code class="literal">fallback_application_name</code></span></dt><dd><p> + Specifies a fallback value for the <a class="xref" href="runtime-config-logging.html#GUC-APPLICATION-NAME">application_name</a> configuration parameter. + This value will be used if no value has been given for + <code class="literal">application_name</code> via a connection parameter or the + <code class="envar">PGAPPNAME</code> environment variable. Specifying + a fallback name is useful in generic utility programs that + wish to set a default application name but allow it to be + overridden by the user. + </p></dd><dt id="LIBPQ-KEEPALIVES"><span class="term"><code class="literal">keepalives</code></span></dt><dd><p> + Controls whether client-side TCP keepalives are used. The default + value is 1, meaning on, but you can change this to 0, meaning off, + if keepalives are not wanted. This parameter is ignored for + connections made via a Unix-domain socket. + </p></dd><dt id="LIBPQ-KEEPALIVES-IDLE"><span class="term"><code class="literal">keepalives_idle</code></span></dt><dd><p> + Controls the number of seconds of inactivity after which TCP should + send a keepalive message to the server. A value of zero uses the + system default. This parameter is ignored for connections made via a + Unix-domain socket, or if keepalives are disabled. + It is only supported on systems where <code class="symbol">TCP_KEEPIDLE</code> or + an equivalent socket option is available, and on Windows; on other + systems, it has no effect. + </p></dd><dt id="LIBPQ-KEEPALIVES-INTERVAL"><span class="term"><code class="literal">keepalives_interval</code></span></dt><dd><p> + Controls the number of seconds after which a TCP keepalive message + that is not acknowledged by the server should be retransmitted. A + value of zero uses the system default. This parameter is ignored for + connections made via a Unix-domain socket, or if keepalives are disabled. + It is only supported on systems where <code class="symbol">TCP_KEEPINTVL</code> or + an equivalent socket option is available, and on Windows; on other + systems, it has no effect. + </p></dd><dt id="LIBPQ-KEEPALIVES-COUNT"><span class="term"><code class="literal">keepalives_count</code></span></dt><dd><p> + Controls the number of TCP keepalives that can be lost before the + client's connection to the server is considered dead. A value of + zero uses the system default. This parameter is ignored for + connections made via a Unix-domain socket, or if keepalives are disabled. + It is only supported on systems where <code class="symbol">TCP_KEEPCNT</code> or + an equivalent socket option is available; on other systems, it has no + effect. + </p></dd><dt id="LIBPQ-TCP-USER-TIMEOUT"><span class="term"><code class="literal">tcp_user_timeout</code></span></dt><dd><p> + Controls the number of milliseconds that transmitted data may + remain unacknowledged before a connection is forcibly closed. + A value of zero uses the system default. This parameter is + ignored for connections made via a Unix-domain socket. + It is only supported on systems where <code class="symbol">TCP_USER_TIMEOUT</code> + is available; on other systems, it has no effect. + </p></dd><dt id="LIBPQ-CONNECT-REPLICATION"><span class="term"><code class="literal">replication</code></span></dt><dd><p> + This option determines whether the connection should use the + replication protocol instead of the normal protocol. This is what + PostgreSQL replication connections as well as tools such as + <span class="application">pg_basebackup</span> use internally, but it can + also be used by third-party applications. For a description of the + replication protocol, consult <a class="xref" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Section 55.4</a>. + </p><p> + The following values, which are case-insensitive, are supported: + </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> + <code class="literal">true</code>, <code class="literal">on</code>, + <code class="literal">yes</code>, <code class="literal">1</code> + </span></dt><dd><p> + The connection goes into physical replication mode. + </p></dd><dt><span class="term"><code class="literal">database</code></span></dt><dd><p> + The connection goes into logical replication mode, connecting to + the database specified in the <code class="literal">dbname</code> parameter. + </p></dd><dt><span class="term"> + <code class="literal">false</code>, <code class="literal">off</code>, + <code class="literal">no</code>, <code class="literal">0</code> + </span></dt><dd><p> + The connection is a regular one, which is the default behavior. + </p></dd></dl></div><p> + </p><p> + In physical or logical replication mode, only the simple query protocol + can be used. + </p></dd><dt id="LIBPQ-CONNECT-GSSENCMODE"><span class="term"><code class="literal">gssencmode</code></span></dt><dd><p> + This option determines whether or with what priority a secure + <acronym class="acronym">GSS</acronym> TCP/IP connection will be negotiated with the + server. There are three modes: + + </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p> + only try a non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection + </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p> + if there are <acronym class="acronym">GSSAPI</acronym> credentials present (i.e., + in a credentials cache), first try + a <acronym class="acronym">GSSAPI</acronym>-encrypted connection; if that fails or + there are no credentials, try a + non-<acronym class="acronym">GSSAPI</acronym>-encrypted connection. This is the + default when <span class="productname">PostgreSQL</span> has been + compiled with <acronym class="acronym">GSSAPI</acronym> support. + </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p> + only try a <acronym class="acronym">GSSAPI</acronym>-encrypted connection + </p></dd></dl></div><p> + </p><p> + <code class="literal">gssencmode</code> is ignored for Unix domain socket + communication. If <span class="productname">PostgreSQL</span> is compiled + without GSSAPI support, using the <code class="literal">require</code> option + will cause an error, while <code class="literal">prefer</code> will be accepted + but <span class="application">libpq</span> will not actually attempt + a <acronym class="acronym">GSSAPI</acronym>-encrypted + connection.<a id="id-1.7.3.8.4.2.1.20.2.2.7" class="indexterm"></a> + </p></dd><dt id="LIBPQ-CONNECT-SSLMODE"><span class="term"><code class="literal">sslmode</code></span></dt><dd><p> + This option determines whether or with what priority a secure + <acronym class="acronym">SSL</acronym> TCP/IP connection will be negotiated with the + server. There are six modes: + + </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">disable</code></span></dt><dd><p> + only try a non-<acronym class="acronym">SSL</acronym> connection + </p></dd><dt><span class="term"><code class="literal">allow</code></span></dt><dd><p> + first try a non-<acronym class="acronym">SSL</acronym> connection; if that + fails, try an <acronym class="acronym">SSL</acronym> connection + </p></dd><dt><span class="term"><code class="literal">prefer</code> (default)</span></dt><dd><p> + first try an <acronym class="acronym">SSL</acronym> connection; if that fails, + try a non-<acronym class="acronym">SSL</acronym> connection + </p></dd><dt><span class="term"><code class="literal">require</code></span></dt><dd><p> + only try an <acronym class="acronym">SSL</acronym> connection. If a root CA + file is present, verify the certificate in the same way as + if <code class="literal">verify-ca</code> was specified + </p></dd><dt><span class="term"><code class="literal">verify-ca</code></span></dt><dd><p> + only try an <acronym class="acronym">SSL</acronym> connection, and verify that + the server certificate is issued by a trusted + certificate authority (<acronym class="acronym">CA</acronym>) + </p></dd><dt><span class="term"><code class="literal">verify-full</code></span></dt><dd><p> + only try an <acronym class="acronym">SSL</acronym> connection, verify that the + server certificate is issued by a + trusted <acronym class="acronym">CA</acronym> and that the requested server host name + matches that in the certificate + </p></dd></dl></div><p> + + See <a class="xref" href="libpq-ssl.html" title="34.19. SSL Support">Section 34.19</a> for a detailed description of how + these options work. + </p><p> + <code class="literal">sslmode</code> is ignored for Unix domain socket + communication. + If <span class="productname">PostgreSQL</span> is compiled without SSL support, + using options <code class="literal">require</code>, <code class="literal">verify-ca</code>, or + <code class="literal">verify-full</code> will cause an error, while + options <code class="literal">allow</code> and <code class="literal">prefer</code> will be + accepted but <span class="application">libpq</span> will not actually attempt + an <acronym class="acronym">SSL</acronym> + connection.<a id="id-1.7.3.8.4.2.1.21.2.2.10" class="indexterm"></a> + </p><p> + Note that if <acronym class="acronym">GSSAPI</acronym> encryption is possible, + that will be used in preference to <acronym class="acronym">SSL</acronym> + encryption, regardless of the value of <code class="literal">sslmode</code>. + To force use of <acronym class="acronym">SSL</acronym> encryption in an + environment that has working <acronym class="acronym">GSSAPI</acronym> + infrastructure (such as a Kerberos server), also + set <code class="literal">gssencmode</code> to <code class="literal">disable</code>. + </p></dd><dt id="LIBPQ-CONNECT-REQUIRESSL"><span class="term"><code class="literal">requiressl</code></span></dt><dd><p> + This option is deprecated in favor of the <code class="literal">sslmode</code> + setting. + </p><p> + If set to 1, an <acronym class="acronym">SSL</acronym> connection to the server + is required (this is equivalent to <code class="literal">sslmode</code> + <code class="literal">require</code>). <span class="application">libpq</span> will then refuse + to connect if the server does not accept an + <acronym class="acronym">SSL</acronym> connection. If set to 0 (default), + <span class="application">libpq</span> will negotiate the connection type with + the server (equivalent to <code class="literal">sslmode</code> + <code class="literal">prefer</code>). This option is only available if + <span class="productname">PostgreSQL</span> is compiled with SSL support. + </p></dd><dt id="LIBPQ-CONNECT-SSLCOMPRESSION"><span class="term"><code class="literal">sslcompression</code></span></dt><dd><p> + If set to 1, data sent over SSL connections will be compressed. If + set to 0, compression will be disabled. The default is 0. This + parameter is ignored if a connection without SSL is made. + </p><p> + SSL compression is nowadays considered insecure and its use is no + longer recommended. <span class="productname">OpenSSL</span> 1.1.0 disables + compression by default, and many operating system distributions + disable it in prior versions as well, so setting this parameter to on + will not have any effect if the server does not accept compression. + <span class="productname">PostgreSQL</span> 14 disables compression + completely in the backend. + </p><p> + If security is not a primary concern, compression can improve + throughput if the network is the bottleneck. Disabling compression + can improve response time and throughput if CPU performance is the + limiting factor. + </p></dd><dt id="LIBPQ-CONNECT-SSLCERT"><span class="term"><code class="literal">sslcert</code></span></dt><dd><p> + This parameter specifies the file name of the client SSL + certificate, replacing the default + <code class="filename">~/.postgresql/postgresql.crt</code>. + This parameter is ignored if an SSL connection is not made. + </p></dd><dt id="LIBPQ-CONNECT-SSLKEY"><span class="term"><code class="literal">sslkey</code></span></dt><dd><p> + This parameter specifies the location for the secret key used for + the client certificate. It can either specify a file name that will + be used instead of the default + <code class="filename">~/.postgresql/postgresql.key</code>, or it can specify a key + obtained from an external <span class="quote">“<span class="quote">engine</span>”</span> (engines are + <span class="productname">OpenSSL</span> loadable modules). An external engine + specification should consist of a colon-separated engine name and + an engine-specific key identifier. This parameter is ignored if an + SSL connection is not made. + </p></dd><dt id="LIBPQ-CONNECT-SSLPASSWORD"><span class="term"><code class="literal">sslpassword</code></span></dt><dd><p> + This parameter specifies the password for the secret key specified in + <code class="literal">sslkey</code>, allowing client certificate private keys + to be stored in encrypted form on disk even when interactive passphrase + input is not practical. + </p><p> + Specifying this parameter with any non-empty value suppresses the + <code class="literal">Enter PEM pass phrase:</code> + prompt that <span class="productname">OpenSSL</span> will emit by default + when an encrypted client certificate key is provided to + <code class="literal">libpq</code>. + </p><p> + If the key is not encrypted this parameter is ignored. The parameter + has no effect on keys specified by <span class="productname">OpenSSL</span> + engines unless the engine uses the <span class="productname">OpenSSL</span> + password callback mechanism for prompts. + </p><p> + There is no environment variable equivalent to this option, and no + facility for looking it up in <code class="filename">.pgpass</code>. It can be + used in a service file connection definition. Users with + more sophisticated uses should consider using <span class="productname">OpenSSL</span> engines and + tools like PKCS#11 or USB crypto offload devices. + </p></dd><dt id="LIBPQ-CONNECT-SSLROOTCERT"><span class="term"><code class="literal">sslrootcert</code></span></dt><dd><p> + This parameter specifies the name of a file containing SSL + certificate authority (<acronym class="acronym">CA</acronym>) certificate(s). + If the file exists, the server's certificate will be verified + to be signed by one of these authorities. The default is + <code class="filename">~/.postgresql/root.crt</code>. + </p></dd><dt id="LIBPQ-CONNECT-SSLCRL"><span class="term"><code class="literal">sslcrl</code></span></dt><dd><p> + This parameter specifies the file name of the SSL server certificate + revocation list (CRL). Certificates listed in this file, if it + exists, will be rejected while attempting to authenticate the + server's certificate. If neither + <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRL">sslcrl</a> nor + <a class="xref" href="libpq-connect.html#LIBPQ-CONNECT-SSLCRLDIR">sslcrldir</a> is set, this setting is + taken as + <code class="filename">~/.postgresql/root.crl</code>. + </p></dd><dt id="LIBPQ-CONNECT-SSLCRLDIR"><span class="term"><code class="literal">sslcrldir</code></span></dt><dd><p> + This parameter specifies the directory name of the SSL server certificate + revocation list (CRL). Certificates listed in the files in this + directory, if it exists, will be rejected while attempting to + authenticate the server's certificate. + </p><p> + The directory needs to be prepared with the + <span class="productname">OpenSSL</span> command + <code class="literal">openssl rehash</code> or <code class="literal">c_rehash</code>. See + its documentation for details. + </p><p> + Both <code class="literal">sslcrl</code> and <code class="literal">sslcrldir</code> can be + specified together. + </p></dd><dt id="LIBPQ-CONNECT-SSLSNI"><span class="term"><code class="literal">sslsni</code><a id="id-1.7.3.8.4.2.1.30.1.2" class="indexterm"></a></span></dt><dd><p> + If set to 1 (default), libpq sets the TLS extension <span class="quote">“<span class="quote">Server Name + Indication</span>”</span> (<acronym class="acronym">SNI</acronym>) on SSL-enabled connections. + By setting this parameter to 0, this is turned off. + </p><p> + The Server Name Indication can be used by SSL-aware proxies to route + connections without having to decrypt the SSL stream. (Note that this + requires a proxy that is aware of the PostgreSQL protocol handshake, + not just any SSL proxy.) However, <acronym class="acronym">SNI</acronym> makes the + destination host name appear in cleartext in the network traffic, so + it might be undesirable in some cases. + </p></dd><dt id="LIBPQ-CONNECT-REQUIREPEER"><span class="term"><code class="literal">requirepeer</code></span></dt><dd><p> + This parameter specifies the operating-system user name of the + server, for example <code class="literal">requirepeer=postgres</code>. + When making a Unix-domain socket connection, if this + parameter is set, the client checks at the beginning of the + connection that the server process is running under the specified + user name; if it is not, the connection is aborted with an error. + This parameter can be used to provide server authentication similar + to that available with SSL certificates on TCP/IP connections. + (Note that if the Unix-domain socket is in + <code class="filename">/tmp</code> or another publicly writable location, + any user could start a server listening there. Use this parameter + to ensure that you are connected to a server run by a trusted user.) + This option is only supported on platforms for which the + <code class="literal">peer</code> authentication method is implemented; see + <a class="xref" href="auth-peer.html" title="21.9. Peer Authentication">Section 21.9</a>. + </p></dd><dt id="LIBPQ-CONNECT-SSL-MIN-PROTOCOL-VERSION"><span class="term"><code class="literal">ssl_min_protocol_version</code></span></dt><dd><p> + This parameter specifies the minimum SSL/TLS protocol version to allow + for the connection. Valid values are <code class="literal">TLSv1</code>, + <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and + <code class="literal">TLSv1.3</code>. The supported protocols depend on the + version of <span class="productname">OpenSSL</span> used, older versions + not supporting the most modern protocol versions. If not specified, + the default is <code class="literal">TLSv1.2</code>, which satisfies industry + best practices as of this writing. + </p></dd><dt id="LIBPQ-CONNECT-SSL-MAX-PROTOCOL-VERSION"><span class="term"><code class="literal">ssl_max_protocol_version</code></span></dt><dd><p> + This parameter specifies the maximum SSL/TLS protocol version to allow + for the connection. Valid values are <code class="literal">TLSv1</code>, + <code class="literal">TLSv1.1</code>, <code class="literal">TLSv1.2</code> and + <code class="literal">TLSv1.3</code>. The supported protocols depend on the + version of <span class="productname">OpenSSL</span> used, older versions + not supporting the most modern protocol versions. If not set, this + parameter is ignored and the connection will use the maximum bound + defined by the backend, if set. Setting the maximum protocol version + is mainly useful for testing or if some component has issues working + with a newer protocol. + </p></dd><dt id="LIBPQ-CONNECT-KRBSRVNAME"><span class="term"><code class="literal">krbsrvname</code></span></dt><dd><p> + Kerberos service name to use when authenticating with GSSAPI. + This must match the service name specified in the server + configuration for Kerberos authentication to succeed. (See also + <a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a>.) + The default value is normally <code class="literal">postgres</code>, + but that can be changed when + building <span class="productname">PostgreSQL</span> via + the <code class="option">--with-krb-srvnam</code> option + of <span class="application">configure</span>. + In most environments, this parameter never needs to be changed. + Some Kerberos implementations might require a different service name, + such as Microsoft Active Directory which requires the service name + to be in upper case (<code class="literal">POSTGRES</code>). + </p></dd><dt id="LIBPQ-CONNECT-GSSLIB"><span class="term"><code class="literal">gsslib</code></span></dt><dd><p> + GSS library to use for GSSAPI authentication. + Currently this is disregarded except on Windows builds that include + both GSSAPI and SSPI support. In that case, set + this to <code class="literal">gssapi</code> to cause libpq to use the GSSAPI + library for authentication instead of the default SSPI. + </p></dd><dt id="LIBPQ-CONNECT-SERVICE"><span class="term"><code class="literal">service</code></span></dt><dd><p> + Service name to use for additional parameters. It specifies a service + name in <code class="filename">pg_service.conf</code> that holds additional connection parameters. + This allows applications to specify only a service name so connection parameters + can be centrally maintained. See <a class="xref" href="libpq-pgservice.html" title="34.17. The Connection Service File">Section 34.17</a>. + </p></dd><dt id="LIBPQ-CONNECT-TARGET-SESSION-ATTRS"><span class="term"><code class="literal">target_session_attrs</code></span></dt><dd><p> + This option determines whether the session must have certain + properties to be acceptable. It's typically used in combination + with multiple host names to select the first acceptable alternative + among several hosts. There are six modes: + + </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">any</code> (default)</span></dt><dd><p> + any successful connection is acceptable + </p></dd><dt><span class="term"><code class="literal">read-write</code></span></dt><dd><p> + session must accept read-write transactions by default (that + is, the server must not be in hot standby mode and + the <code class="varname">default_transaction_read_only</code> parameter + must be <code class="literal">off</code>) + </p></dd><dt><span class="term"><code class="literal">read-only</code></span></dt><dd><p> + session must not accept read-write transactions by default (the + converse) + </p></dd><dt><span class="term"><code class="literal">primary</code></span></dt><dd><p> + server must not be in hot standby mode + </p></dd><dt><span class="term"><code class="literal">standby</code></span></dt><dd><p> + server must be in hot standby mode + </p></dd><dt><span class="term"><code class="literal">prefer-standby</code></span></dt><dd><p> + first try to find a standby server, but if none of the listed + hosts is a standby server, try again in <code class="literal">any</code> + mode + </p></dd></dl></div><p> + </p></dd></dl></div><p> + </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq.html" title="Chapter 34. libpq — C Library">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-status.html" title="34.2. Connection Status Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 34. <span class="application">libpq</span> — C Library </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.2. Connection Status Functions</td></tr></table></div></body></html>
\ No newline at end of file |