diff options
Diffstat (limited to 'doc/src/sgml/libpq.sgml')
| -rw-r--r-- | doc/src/sgml/libpq.sgml | 9893 |
1 files changed, 9893 insertions, 0 deletions
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml new file mode 100644 index 0000000..f180186 --- /dev/null +++ b/doc/src/sgml/libpq.sgml @@ -0,0 +1,9893 @@ +<!-- doc/src/sgml/libpq.sgml --> + +<chapter id="libpq"> + <title><application>libpq</application> — C Library</title> + + <indexterm zone="libpq"> + <primary>libpq</primary> + </indexterm> + + <indexterm zone="libpq"> + <primary>C</primary> + </indexterm> + + <para> + <application>libpq</application> is the <acronym>C</acronym> + application programmer's interface to <productname>PostgreSQL</productname>. + <application>libpq</application> is a set of library functions that allow + client programs to pass queries to the <productname>PostgreSQL</productname> + backend server and to receive the results of these queries. + </para> + + <para> + <application>libpq</application> is also the underlying engine for several + other <productname>PostgreSQL</productname> application interfaces, including + those written for C++, Perl, Python, Tcl and <application>ECPG</application>. + So some aspects of <application>libpq</application>'s behavior will be + important to you if you use one of those packages. In particular, + <xref linkend="libpq-envars"/>, + <xref linkend="libpq-pgpass"/> and + <xref linkend="libpq-ssl"/> + describe behavior that is visible to the user of any application + that uses <application>libpq</application>. + </para> + + <para> + Some short programs are included at the end of this chapter (<xref linkend="libpq-example"/>) to show how + to write programs that use <application>libpq</application>. There are also several + complete examples of <application>libpq</application> applications in the + directory <filename>src/test/examples</filename> in the source code distribution. + </para> + + <para> + Client programs that use <application>libpq</application> must + include the header file + <filename>libpq-fe.h</filename><indexterm><primary>libpq-fe.h</primary></indexterm> + and must link with the <application>libpq</application> library. + </para> + + <sect1 id="libpq-connect"> + <title>Database Connection Control Functions</title> + + <para> + The following functions deal with making a connection to a + <productname>PostgreSQL</productname> 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 + <structname>PGconn</structname><indexterm><primary>PGconn</primary></indexterm> object, which + is obtained from the function <xref linkend="libpq-PQconnectdb"/>, + <xref linkend="libpq-PQconnectdbParams"/>, or + <xref linkend="libpq-PQsetdbLogin"/>. Note that these functions will always + return a non-null object pointer, unless perhaps there is too + little memory even to allocate the <structname>PGconn</structname> object. + The <xref linkend="libpq-PQstatus"/> function should be called to check + the return value for a successful connection before queries are sent + via the connection object. + + <warning> + <para> + If untrusted users have access to a database that has not adopted a + <link linkend="ddl-schemas-patterns">secure schema usage pattern</link>, + begin each session by removing publicly-writable schemas from + <varname>search_path</varname>. One can set parameter key + word <literal>options</literal> to + value <literal>-csearch_path=</literal>. Alternately, one can + issue <literal>PQexec(<replaceable>conn</replaceable>, "SELECT + pg_catalog.set_config('search_path', '', false)")</literal> after + connecting. This consideration is not specific + to <application>libpq</application>; it applies to every interface for + executing arbitrary SQL commands. + </para> + </warning> + + <warning> + <para> + 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 <function>exec</function> from + the child process to load a new executable is safe. + </para> + </warning> + + <variablelist> + <varlistentry id="libpq-PQconnectdbParams"> + <term><function>PQconnectdbParams</function><indexterm><primary>PQconnectdbParams</primary></indexterm></term> + <listitem> + <para> + Makes a new connection to the database server. + +<synopsis> +PGconn *PQconnectdbParams(const char * const *keywords, + const char * const *values, + int expand_dbname); +</synopsis> + </para> + + <para> + This function opens a new database connection using the parameters taken + from two <symbol>NULL</symbol>-terminated arrays. The first, + <literal>keywords</literal>, is defined as an array of strings, each one + being a key word. The second, <literal>values</literal>, gives the value + for each key word. Unlike <xref linkend="libpq-PQsetdbLogin"/> below, the parameter + set can be extended without changing the function signature, so use of + this function (or its nonblocking analogs <xref linkend="libpq-PQconnectStartParams"/> + and <function>PQconnectPoll</function>) is preferred for new application + programming. + </para> + + <para> + The currently recognized parameter key words are listed in + <xref linkend="libpq-paramkeywords"/>. + </para> + + <para> + 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 <symbol>NULL</symbol> entry + in the <literal>keywords</literal> array. + Also, if the <literal>values</literal> entry associated with a + non-<symbol>NULL</symbol> <literal>keywords</literal> entry is + <symbol>NULL</symbol> or an empty string, that entry is ignored and + processing continues with the next pair of array entries. + </para> + + <para> + When <literal>expand_dbname</literal> is non-zero, the value for + the first <parameter>dbname</parameter> key word is checked to see + if it is a <firstterm>connection string</firstterm>. If so, it + is <quote>expanded</quote> 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 (<literal>=</literal>) or it begins with a + URI scheme designator. (More details on connection string formats + appear in <xref linkend="libpq-connstring"/>.) Only the first + occurrence of <parameter>dbname</parameter> is treated in this way; + any subsequent <parameter>dbname</parameter> parameter is processed + as a plain database name. + </para> + + <para> + In general the parameter arrays are processed from start to end. + If any key word is repeated, the last value (that is + not <symbol>NULL</symbol> or empty) is used. This rule applies in + particular when a key word found in a connection string conflicts + with one appearing in the <literal>keywords</literal> 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 <parameter>dbname</parameter> + entry can be overridden by fields of the connection string, and in + turn those fields are overridden by array entries appearing + after <parameter>dbname</parameter> (but, again, only if those + entries supply non-empty values). + </para> + + <para> + 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 <xref linkend="libpq-envars"/>) is set, its value is + used. If the environment variable is not set either, then the + parameter's built-in default value is used. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQconnectdb"> + <term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</primary></indexterm></term> + <listitem> + <para> + Makes a new connection to the database server. + +<synopsis> +PGconn *PQconnectdb(const char *conninfo); +</synopsis> + </para> + + <para> + This function opens a new database connection using the parameters taken + from the string <literal>conninfo</literal>. + </para> + + <para> + 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>URI</acronym>. + See <xref linkend="libpq-connstring"/> for details. + </para> + + + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsetdbLogin"> + <term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</primary></indexterm></term> + <listitem> + <para> + Makes a new connection to the database server. +<synopsis> +PGconn *PQsetdbLogin(const char *pghost, + const char *pgport, + const char *pgoptions, + const char *pgtty, + const char *dbName, + const char *login, + const char *pwd); +</synopsis> + </para> + + <para> + This is the predecessor of <xref linkend="libpq-PQconnectdb"/> with a fixed + set of parameters. It has the same functionality except that the + missing parameters will always take on default values. Write <symbol>NULL</symbol> or an + empty string for any one of the fixed parameters that is to be defaulted. + </para> + + <para> + If the <parameter>dbName</parameter> contains + an <symbol>=</symbol> sign or has a valid connection <acronym>URI</acronym> prefix, it + is taken as a <parameter>conninfo</parameter> string in exactly the same way as + if it had been passed to <xref linkend="libpq-PQconnectdb"/>, and the remaining + parameters are then applied as specified for <xref linkend="libpq-PQconnectdbParams"/>. + </para> + + <para> + <literal>pgtty</literal> is no longer used and any value passed will + be ignored. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsetdb"> + <term><function>PQsetdb</function><indexterm><primary>PQsetdb</primary></indexterm></term> + <listitem> + <para> + Makes a new connection to the database server. +<synopsis> +PGconn *PQsetdb(char *pghost, + char *pgport, + char *pgoptions, + char *pgtty, + char *dbName); +</synopsis> + </para> + + <para> + This is a macro that calls <xref linkend="libpq-PQsetdbLogin"/> with null pointers + for the <parameter>login</parameter> and <parameter>pwd</parameter> parameters. It is provided + for backward compatibility with very old programs. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQconnectStartParams"> + <term><function>PQconnectStartParams</function><indexterm><primary>PQconnectStartParams</primary></indexterm></term> + <term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</primary></indexterm></term> + <term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</primary></indexterm></term> + <listitem> + <para> + <indexterm><primary>nonblocking connection</primary></indexterm> + Make a connection to the database server in a nonblocking manner. + +<synopsis> +PGconn *PQconnectStartParams(const char * const *keywords, + const char * const *values, + int expand_dbname); + +PGconn *PQconnectStart(const char *conninfo); + +PostgresPollingStatusType PQconnectPoll(PGconn *conn); +</synopsis> + </para> + + <para> + 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 + <xref linkend="libpq-PQconnectdbParams"/> or <xref linkend="libpq-PQconnectdb"/>, and so the + application can manage this operation in parallel with other activities. + </para> + + <para> + With <xref linkend="libpq-PQconnectStartParams"/>, the database connection is made + using the parameters taken from the <literal>keywords</literal> and + <literal>values</literal> arrays, and controlled by <literal>expand_dbname</literal>, + as described above for <xref linkend="libpq-PQconnectdbParams"/>. + </para> + + <para> + With <function>PQconnectStart</function>, the database connection is made + using the parameters taken from the string <literal>conninfo</literal> as + described above for <xref linkend="libpq-PQconnectdb"/>. + </para> + + <para> + Neither <xref linkend="libpq-PQconnectStartParams"/> nor <function>PQconnectStart</function> + nor <function>PQconnectPoll</function> will block, so long as a number of + restrictions are met: + <itemizedlist> + <listitem> + <para> + The <literal>hostaddr</literal> parameter must be used appropriately + to prevent DNS queries from being made. See the documentation of + this parameter in <xref linkend="libpq-paramkeywords"/> for details. + </para> + </listitem> + + <listitem> + <para> + If you call <xref linkend="libpq-PQtrace"/>, ensure that the stream object + into which you trace will not block. + </para> + </listitem> + + <listitem> + <para> + You must ensure that the socket is in the appropriate state + before calling <function>PQconnectPoll</function>, as described below. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + To begin a nonblocking connection request, + call <function>PQconnectStart</function> + or <xref linkend="libpq-PQconnectStartParams"/>. If the result is null, + then <application>libpq</application> has been unable to allocate a + new <structname>PGconn</structname> structure. Otherwise, a + valid <structname>PGconn</structname> pointer is returned (though not + yet representing a valid connection to the database). Next + call <literal>PQstatus(conn)</literal>. If the result + is <symbol>CONNECTION_BAD</symbol>, the connection attempt has already + failed, typically because of invalid connection parameters. + </para> + + <para> + If <function>PQconnectStart</function> + or <xref linkend="libpq-PQconnectStartParams"/> succeeds, the next stage + is to poll <application>libpq</application> so that it can proceed with + the connection sequence. + Use <function>PQsocket(conn)</function> to obtain the descriptor of the + socket underlying the database connection. + (Caution: do not assume that the socket remains the same + across <function>PQconnectPoll</function> calls.) + Loop thus: If <function>PQconnectPoll(conn)</function> last returned + <symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to + read (as indicated by <function>select()</function>, <function>poll()</function>, or + similar system function). + Then call <function>PQconnectPoll(conn)</function> again. + Conversely, if <function>PQconnectPoll(conn)</function> last returned + <symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready + to write, then call <function>PQconnectPoll(conn)</function> again. + On the first iteration, i.e., if you have yet to call + <function>PQconnectPoll</function>, behave as if it last returned + <symbol>PGRES_POLLING_WRITING</symbol>. Continue this loop until + <function>PQconnectPoll(conn)</function> returns + <symbol>PGRES_POLLING_FAILED</symbol>, indicating the connection procedure + has failed, or <symbol>PGRES_POLLING_OK</symbol>, indicating the connection + has been successfully made. + </para> + + <para> + At any time during connection, the status of the connection can be + checked by calling <xref linkend="libpq-PQstatus"/>. If this call returns <symbol>CONNECTION_BAD</symbol>, then the + connection procedure has failed; if the call returns <function>CONNECTION_OK</function>, then the + connection is ready. Both of these states are equally detectable + from the return value of <function>PQconnectPoll</function>, 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: + + <variablelist> + <varlistentry id="libpq-connection-started"> + <term><symbol>CONNECTION_STARTED</symbol></term> + <listitem> + <para> + Waiting for connection to be made. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connection-made"> + <term><symbol>CONNECTION_MADE</symbol></term> + <listitem> + <para> + Connection OK; waiting to send. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connection-awaiting-response"> + <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term> + <listitem> + <para> + Waiting for a response from the server. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connection-auth-ok"> + <term><symbol>CONNECTION_AUTH_OK</symbol></term> + <listitem> + <para> + Received authentication; waiting for backend start-up to finish. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connection-ssl-startup"> + <term><symbol>CONNECTION_SSL_STARTUP</symbol></term> + <listitem> + <para> + Negotiating SSL encryption. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connection-setenv"> + <term><symbol>CONNECTION_SETENV</symbol></term> + <listitem> + <para> + Negotiating environment-driven parameter settings. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connection-check-writable"> + <term><symbol>CONNECTION_CHECK_WRITABLE</symbol></term> + <listitem> + <para> + Checking if connection is able to handle write transactions. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connection-consume"> + <term><symbol>CONNECTION_CONSUME</symbol></term> + <listitem> + <para> + Consuming any remaining response messages on connection. + </para> + </listitem> + </varlistentry> + </variablelist> + + 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: +<programlisting> +switch(PQstatus(conn)) +{ + case CONNECTION_STARTED: + feedback = "Connecting..."; + break; + + case CONNECTION_MADE: + feedback = "Connected to server..."; + break; +. +. +. + default: + feedback = "Connecting..."; +} +</programlisting> + </para> + + <para> + The <literal>connect_timeout</literal> connection parameter is ignored + when using <function>PQconnectPoll</function>; it is the application's + responsibility to decide whether an excessive amount of time has elapsed. + Otherwise, <function>PQconnectStart</function> followed by a + <function>PQconnectPoll</function> loop is equivalent to + <xref linkend="libpq-PQconnectdb"/>. + </para> + + <para> + Note that when <function>PQconnectStart</function> + or <xref linkend="libpq-PQconnectStartParams"/> returns a non-null + pointer, you must call <xref linkend="libpq-PQfinish"/> 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. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQconndefaults"> + <term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</primary></indexterm></term> + <listitem> + <para> + Returns the default connection options. +<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; +</synopsis> + </para> + + <para> + Returns a connection options array. This can be used to determine + all possible <xref linkend="libpq-PQconnectdb"/> options and their + current default values. The return value points to an array of + <structname>PQconninfoOption</structname> structures, which ends + with an entry having a null <structfield>keyword</structfield> pointer. The + null pointer is returned if memory could not be allocated. Note that + the current default values (<structfield>val</structfield> 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. + </para> + + <para> + After processing the options array, free it by passing it to + <xref linkend="libpq-PQconninfoFree"/>. If this is not done, a small amount of memory + is leaked for each call to <xref linkend="libpq-PQconndefaults"/>. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQconninfo"> + <term><function>PQconninfo</function><indexterm><primary>PQconninfo</primary></indexterm></term> + <listitem> + <para> + Returns the connection options used by a live connection. +<synopsis> +PQconninfoOption *PQconninfo(PGconn *conn); +</synopsis> + </para> + + <para> + Returns a connection options array. This can be used to determine + all possible <xref linkend="libpq-PQconnectdb"/> options and the + values that were used to connect to the server. The return + value points to an array of <structname>PQconninfoOption</structname> + structures, which ends with an entry having a null <structfield>keyword</structfield> + pointer. All notes above for <xref linkend="libpq-PQconndefaults"/> also + apply to the result of <xref linkend="libpq-PQconninfo"/>. + </para> + + </listitem> + </varlistentry> + + + <varlistentry id="libpq-PQconninfoParse"> + <term><function>PQconninfoParse</function><indexterm><primary>PQconninfoParse</primary></indexterm></term> + <listitem> + <para> + Returns parsed connection options from the provided connection string. + +<synopsis> +PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); +</synopsis> + </para> + + <para> + Parses a connection string and returns the resulting options as an + array; or returns <symbol>NULL</symbol> if there is a problem with the connection + string. This function can be used to extract + the <xref linkend="libpq-PQconnectdb"/> options in the provided + connection string. The return value points to an array of + <structname>PQconninfoOption</structname> structures, which ends + with an entry having a null <structfield>keyword</structfield> pointer. + </para> + + <para> + All legal options will be present in the result array, but the + <literal>PQconninfoOption</literal> for any option not present + in the connection string will have <literal>val</literal> set to + <literal>NULL</literal>; default values are not inserted. + </para> + + <para> + If <literal>errmsg</literal> is not <symbol>NULL</symbol>, then <literal>*errmsg</literal> is set + to <symbol>NULL</symbol> on success, else to a <function>malloc</function>'d error string explaining + the problem. (It is also possible for <literal>*errmsg</literal> to be + set to <symbol>NULL</symbol> and the function to return <symbol>NULL</symbol>; + this indicates an out-of-memory condition.) + </para> + + <para> + After processing the options array, free it by passing it to + <xref linkend="libpq-PQconninfoFree"/>. If this is not done, some memory + is leaked for each call to <xref linkend="libpq-PQconninfoParse"/>. + Conversely, if an error occurs and <literal>errmsg</literal> is not <symbol>NULL</symbol>, + be sure to free the error string using <xref linkend="libpq-PQfreemem"/>. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQfinish"> + <term><function>PQfinish</function><indexterm><primary>PQfinish</primary></indexterm></term> + <listitem> + <para> + Closes the connection to the server. Also frees + memory used by the <structname>PGconn</structname> object. +<synopsis> +void PQfinish(PGconn *conn); +</synopsis> + </para> + + <para> + Note that even if the server connection attempt fails (as + indicated by <xref linkend="libpq-PQstatus"/>), the application should call <xref linkend="libpq-PQfinish"/> + to free the memory used by the <structname>PGconn</structname> object. + The <structname>PGconn</structname> pointer must not be used again after + <xref linkend="libpq-PQfinish"/> has been called. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQreset"> + <term><function>PQreset</function><indexterm><primary>PQreset</primary></indexterm></term> + <listitem> + <para> + Resets the communication channel to the server. +<synopsis> +void PQreset(PGconn *conn); +</synopsis> + </para> + + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQresetStart"> + <term><function>PQresetStart</function><indexterm><primary>PQresetStart</primary></indexterm></term> + <term><function>PQresetPoll</function><indexterm><primary>PQresetPoll</primary></indexterm></term> + <listitem> + <para> + Reset the communication channel to the server, in a nonblocking manner. + +<synopsis> +int PQresetStart(PGconn *conn); + +PostgresPollingStatusType PQresetPoll(PGconn *conn); +</synopsis> + </para> + + <para> + 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 <xref linkend="libpq-PQreset"/> (above) in that they + act in a nonblocking manner. These functions suffer from the same + restrictions as <xref linkend="libpq-PQconnectStartParams"/>, <function>PQconnectStart</function> + and <function>PQconnectPoll</function>. + </para> + + <para> + To initiate a connection reset, call + <xref linkend="libpq-PQresetStart"/>. If it returns 0, the reset has + failed. If it returns 1, poll the reset using + <function>PQresetPoll</function> in exactly the same way as you + would create the connection using <function>PQconnectPoll</function>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQpingParams"> + <term><function>PQpingParams</function><indexterm><primary>PQpingParams</primary></indexterm></term> + <listitem> + <para> + <xref linkend="libpq-PQpingParams"/> reports the status of the + server. It accepts connection parameters identical to those of + <xref linkend="libpq-PQconnectdbParams"/>, 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. + +<synopsis> +PGPing PQpingParams(const char * const *keywords, + const char * const *values, + int expand_dbname); +</synopsis> + + The function returns one of the following values: + + <variablelist> + <varlistentry id="libpq-PQpingParams-PQPING_OK"> + <term><literal>PQPING_OK</literal></term> + <listitem> + <para> + The server is running and appears to be accepting connections. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQpingParams-PQPING_REJECT"> + <term><literal>PQPING_REJECT</literal></term> + <listitem> + <para> + The server is running but is in a state that disallows connections + (startup, shutdown, or crash recovery). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQpingParams-PQPING_NO_RESPONSE"> + <term><literal>PQPING_NO_RESPONSE</literal></term> + <listitem> + <para> + 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). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQpingParams-PQPING_NO_ATTEMPT"> + <term><literal>PQPING_NO_ATTEMPT</literal></term> + <listitem> + <para> + 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). + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQping"> + <term><function>PQping</function><indexterm><primary>PQping</primary></indexterm></term> + <listitem> + <para> + <xref linkend="libpq-PQping"/> reports the status of the + server. It accepts connection parameters identical to those of + <xref linkend="libpq-PQconnectdb"/>, 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. + +<synopsis> +PGPing PQping(const char *conninfo); +</synopsis> + </para> + + <para> + The return values are the same as for <xref linkend="libpq-PQpingParams"/>. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-pqsetsslkeypasshook-openssl"> + <term><function>PQsetSSLKeyPassHook_OpenSSL</function><indexterm><primary>PQsetSSLKeyPassHook_OpenSSL</primary></indexterm></term> + <listitem> + <para> + <function>PQsetSSLKeyPassHook_OpenSSL</function> lets an application override + <application>libpq</application>'s <link linkend="libpq-ssl-clientcert">default + handling of encrypted client certificate key files</link> using + <xref linkend="libpq-connect-sslpassword"/> or interactive prompting. + +<synopsis> +void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook); +</synopsis> + + The application passes a pointer to a callback function with signature: +<programlisting> +int callback_fn(char *buf, int size, PGconn *conn); +</programlisting> + which <application>libpq</application> will then call + <emphasis>instead of</emphasis> its default + <function>PQdefaultSSLKeyPassHook_OpenSSL</function> handler. The + callback should determine the password for the key and copy it to + result-buffer <parameter>buf</parameter> of size + <parameter>size</parameter>. The string in <parameter>buf</parameter> + must be null-terminated. The callback must return the length of the + password stored in <parameter>buf</parameter> excluding the null + terminator. On failure, the callback should set + <literal>buf[0] = '\0'</literal> and return 0. See + <function>PQdefaultSSLKeyPassHook_OpenSSL</function> in + <application>libpq</application>'s source code for an example. + </para> + + <para> + If the user specified an explicit key location, + its path will be in <literal>conn->sslkey</literal> 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 <productname>OpenSSL</productname> password + callback or define their own handling. + </para> + + <para> + The app callback may choose to delegate unhandled cases to + <function>PQdefaultSSLKeyPassHook_OpenSSL</function>, + or call it first and try something else if it returns 0, or completely override it. + </para> + + <para> + The callback <emphasis>must not</emphasis> escape normal flow control with exceptions, + <function>longjmp(...)</function>, etc. It must return normally. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-pqgetsslkeypasshook-openssl"> + <term><function>PQgetSSLKeyPassHook_OpenSSL</function><indexterm><primary>PQgetSSLKeyPassHook_OpenSSL</primary></indexterm></term> + <listitem> + <para> + <function>PQgetSSLKeyPassHook_OpenSSL</function> returns the current + client certificate key password hook, or <literal>NULL</literal> + if none has been set. + +<synopsis> +PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void); +</synopsis> + </para> + + </listitem> + </varlistentry> + + </variablelist> + </para> + + <sect2 id="libpq-connstring"> + <title>Connection Strings</title> + + <indexterm zone="libpq-connstring"> + <primary><literal>conninfo</literal></primary> + </indexterm> + + <indexterm zone="libpq-connstring"> + <primary><literal>URI</literal></primary> + </indexterm> + + <para> + Several <application>libpq</application> 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 + <ulink url="https://tools.ietf.org/html/rfc3986">RFC + 3986</ulink>, except that multi-host connection strings are allowed + as further described below. + </para> + + <sect3 id="libpq-connstring-keyword-value"> + <title>Keyword/Value Connection Strings</title> + + <para> + In the keyword/value format, each parameter setting is in the form + <replaceable>keyword</replaceable> <literal>=</literal> + <replaceable>value</replaceable>, 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 <literal>keyword = 'a value'</literal>. + Single quotes and backslashes within + a value must be escaped with a backslash, i.e., <literal>\'</literal> and + <literal>\\</literal>. + </para> + + <para> + Example: +<programlisting> +host=localhost port=5432 dbname=mydb connect_timeout=10 +</programlisting> + </para> + + <para> + The recognized parameter key words are listed in <xref + linkend="libpq-paramkeywords"/>. + </para> + </sect3> + + <sect3 id="libpq-connstring-uris"> + <title>Connection URIs</title> + + <para> + The general form for a connection <acronym>URI</acronym> is: +<synopsis> +postgresql://<optional><replaceable>userspec</replaceable>@</optional><optional><replaceable>hostspec</replaceable></optional><optional>/<replaceable>dbname</replaceable></optional><optional>?<replaceable>paramspec</replaceable></optional> + +<phrase>where <replaceable>userspec</replaceable> is:</phrase> + +<replaceable>user</replaceable><optional>:<replaceable>password</replaceable></optional> + +<phrase>and <replaceable>hostspec</replaceable> is:</phrase> + +<optional><replaceable>host</replaceable></optional><optional>:<replaceable>port</replaceable></optional><optional>,...</optional> + +<phrase>and <replaceable>paramspec</replaceable> is:</phrase> + +<replaceable>name</replaceable>=<replaceable>value</replaceable><optional>&...</optional> +</synopsis> + </para> + + <para> + The <acronym>URI</acronym> scheme designator can be either + <literal>postgresql://</literal> or <literal>postgres://</literal>. Each + of the remaining <acronym>URI</acronym> parts is optional. The + following examples illustrate valid <acronym>URI</acronym> syntax: +<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 +</programlisting> + Values that would normally appear in the hierarchical part of + the <acronym>URI</acronym> can alternatively be given as named + parameters. For example: +<programlisting> +postgresql:///mydb?host=localhost&port=5433 +</programlisting> + All named parameters must match key words listed in + <xref linkend="libpq-paramkeywords"/>, except that for compatibility + with JDBC connection <acronym>URI</acronym>s, instances + of <literal>ssl=true</literal> are translated into + <literal>sslmode=require</literal>. + </para> + + <para> + The connection <acronym>URI</acronym> needs to be encoded with <ulink + url="https://tools.ietf.org/html/rfc3986#section-2.1">percent-encoding</ulink> + if it includes symbols with special meaning in any of its parts. Here is + an example where the equal sign (<literal>=</literal>) is replaced with + <literal>%3D</literal> and the space character with + <literal>%20</literal>: +<programlisting> +postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff +</programlisting> + </para> + + <para> + The host part may be either a host name or an IP address. To specify an + IPv6 address, enclose it in square brackets: +<synopsis> +postgresql://[2001:db8::1234]/database +</synopsis> + </para> + + <para> + The host part is interpreted as described for the parameter <xref + linkend="libpq-connect-host"/>. 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: +<programlisting> +postgresql:///dbname?host=/var/lib/postgresql +postgresql://%2Fvar%2Flib%2Fpostgresql/dbname +</programlisting> + </para> + + <para> + It is possible to specify multiple host components, each with an optional + port component, in a single URI. A URI of the form + <literal>postgresql://host1:port1,host2:port2,host3:port3/</literal> + is equivalent to a connection string of the form + <literal>host=host1,host2,host3 port=port1,port2,port3</literal>. + As further described below, each + host will be tried in turn until a connection is successfully established. + </para> + </sect3> + + <sect3 id="libpq-multiple-hosts"> + <title>Specifying Multiple Hosts</title> + + <para> + 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 <literal>host</literal>, + <literal>hostaddr</literal>, and <literal>port</literal> 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 <literal>hostaddr</literal> corresponds to the first host name, + the second <literal>hostaddr</literal> corresponds to the second host name, and so + forth. As an exception, if only one <literal>port</literal> is specified, it + applies to all the hosts. + </para> + + <para> + In the connection URI format, you can list multiple <literal>host:port</literal> pairs + separated by commas in the <literal>host</literal> component of the URI. + </para> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <para> + 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. + </para> + </sect3> + </sect2> + + <sect2 id="libpq-paramkeywords"> + <title>Parameter Key Words</title> + + <para> + The currently recognized parameter key words are: + + <variablelist> + <varlistentry id="libpq-connect-host" xreflabel="host"> + <term><literal>host</literal></term> + <listitem> + <para> + Name of host to connect to.<indexterm><primary>host + name</primary></indexterm> 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 <literal>@</literal>, it is + taken as a Unix-domain socket in the abstract namespace (currently + supported on Linux and Windows). + The default behavior when <literal>host</literal> is not + specified, or is empty, is to connect to a Unix-domain + socket<indexterm><primary>Unix domain socket</primary></indexterm> in + <filename>/tmp</filename> (or whatever socket directory was specified + when <productname>PostgreSQL</productname> was built). On Windows, + the default is to connect to <literal>localhost</literal>. + </para> + <para> + 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 + <xref linkend="libpq-multiple-hosts"/> for details. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-hostaddr" xreflabel="hostaddr"> + <term><literal>hostaddr</literal></term> + <listitem> + <para> + Numeric IP address of host to connect to. This should be in the + standard IPv4 address format, e.g., <literal>172.28.40.9</literal>. 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 <literal>host</literal> + will be looked up to find the corresponding IP address — or, if + <literal>host</literal> specifies an IP address, that value will be + used directly. + </para> + + <para> + Using <literal>hostaddr</literal> 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 <literal>verify-full</literal> SSL + certificate verification. The following rules are used: + <itemizedlist> + <listitem> + <para> + If <literal>host</literal> is specified + without <literal>hostaddr</literal>, a host name lookup occurs. + (When using <function>PQconnectPoll</function>, the lookup occurs + when <function>PQconnectPoll</function> first considers this host + name, and it may cause <function>PQconnectPoll</function> to block + for a significant amount of time.) + </para> + </listitem> + <listitem> + <para> + If <literal>hostaddr</literal> is specified without <literal>host</literal>, + the value for <literal>hostaddr</literal> gives the server network address. + The connection attempt will fail if the authentication + method requires a host name. + </para> + </listitem> + <listitem> + <para> + If both <literal>host</literal> and <literal>hostaddr</literal> are specified, + the value for <literal>hostaddr</literal> gives the server network address. + The value for <literal>host</literal> is ignored unless the + authentication method requires it, in which case it will be + used as the host name. + </para> + </listitem> + </itemizedlist> + Note that authentication is likely to fail if <literal>host</literal> + is not the name of the server at network address <literal>hostaddr</literal>. + Also, when both <literal>host</literal> and <literal>hostaddr</literal> + are specified, <literal>host</literal> + is used to identify the connection in a password file (see + <xref linkend="libpq-pgpass"/>). + </para> + + <para> + A comma-separated list of <literal>hostaddr</literal> 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 + <xref linkend="libpq-multiple-hosts"/> for details. + </para> + <para> + Without either a host name or host address, + <application>libpq</application> will connect using a local + Unix-domain socket; or on Windows, it will attempt to connect to + <literal>localhost</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-port" xreflabel="port"> + <term><literal>port</literal></term> + <listitem> + <para> + Port number to connect to at the server host, or socket file + name extension for Unix-domain + connections.<indexterm><primary>port</primary></indexterm> + If multiple hosts were given in the <literal>host</literal> or + <literal>hostaddr</literal> 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 <productname>PostgreSQL</productname> was built. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-dbname" xreflabel="dbname"> + <term><literal>dbname</literal></term> + <listitem> + <para> + The database name. Defaults to be the same as the user name. + In certain contexts, the value is checked for extended + formats; see <xref linkend="libpq-connstring"/> for more details on + those. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-user" xreflabel="user"> + <term><literal>user</literal></term> + <listitem> + <para> + <productname>PostgreSQL</productname> user name to connect as. + Defaults to be the same as the operating system name of the user + running the application. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-password" xreflabel="password"> + <term><literal>password</literal></term> + <listitem> + <para> + Password to be used if the server demands password authentication. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-passfile" xreflabel="passfile"> + <term><literal>passfile</literal></term> + <listitem> + <para> + Specifies the name of the file used to store passwords + (see <xref linkend="libpq-pgpass"/>). + Defaults to <filename>~/.pgpass</filename>, or + <filename>%APPDATA%\postgresql\pgpass.conf</filename> on Microsoft Windows. + (No error is reported if this file does not exist.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-require-auth" xreflabel="require_auth"> + <term><literal>require_auth</literal></term> + <listitem> + <para> + Specifies the authentication method that the client requires from the + server. If the server does not use the required method to authenticate + the client, or if the authentication handshake is not fully completed by + the server, the connection will fail. A comma-separated list of methods + may also be provided, of which the server must use exactly one in order + for the connection to succeed. By default, any authentication method is + accepted, and the server is free to skip authentication altogether. + </para> + <para> + Methods may be negated with the addition of a <literal>!</literal> + prefix, in which case the server must <emphasis>not</emphasis> attempt + the listed method; any other method is accepted, and the server is free + not to authenticate the client at all. If a comma-separated list is + provided, the server may not attempt <emphasis>any</emphasis> of the + listed negated methods. Negated and non-negated forms may not be + combined in the same setting. + </para> + <para> + As a final special case, the <literal>none</literal> method requires the + server not to use an authentication challenge. (It may also be negated, + to require some form of authentication.) + </para> + <para> + The following methods may be specified: + + <variablelist> + <varlistentry> + <term><literal>password</literal></term> + <listitem> + <para> + The server must request plaintext password authentication. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>md5</literal></term> + <listitem> + <para> + The server must request MD5 hashed password authentication. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>gss</literal></term> + <listitem> + <para> + The server must either request a Kerberos handshake via + <acronym>GSSAPI</acronym> or establish a + <acronym>GSS</acronym>-encrypted channel (see also + <xref linkend="libpq-connect-gssencmode" />). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>sspi</literal></term> + <listitem> + <para> + The server must request Windows <acronym>SSPI</acronym> + authentication. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>scram-sha-256</literal></term> + <listitem> + <para> + The server must successfully complete a SCRAM-SHA-256 authentication + exchange with the client. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>none</literal></term> + <listitem> + <para> + The server must not prompt the client for an authentication + exchange. (This does not prohibit client certificate authentication + via TLS, nor GSS authentication via its encrypted transport.) + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-channel-binding" xreflabel="channel_binding"> + <term><literal>channel_binding</literal></term> + <listitem> + <para> + This option controls the client's use of channel binding. A setting + of <literal>require</literal> means that the connection must employ + channel binding, <literal>prefer</literal> means that the client will + choose channel binding if available, and <literal>disable</literal> + prevents the use of channel binding. The default + is <literal>prefer</literal> if + <productname>PostgreSQL</productname> is compiled with SSL support; + otherwise the default is <literal>disable</literal>. + </para> + <para> + Channel binding is a method for the server to authenticate itself to + the client. It is only supported over SSL connections + with <productname>PostgreSQL</productname> 11 or later servers using + the <literal>SCRAM</literal> authentication method. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-connect-timeout" xreflabel="connect_timeout"> + <term><literal>connect_timeout</literal></term> + <listitem> + <para> + Maximum time to wait while connecting, in seconds (write as a decimal integer, + e.g., <literal>10</literal>). Zero, negative, or not specified means + wait indefinitely. The minimum allowed timeout is 2 seconds, therefore + a value of <literal>1</literal> is interpreted as <literal>2</literal>. + This timeout applies separately to each host name or IP address. + For example, if you specify two hosts and <literal>connect_timeout</literal> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-client-encoding" xreflabel="client_encoding"> + <term><literal>client_encoding</literal></term> + <listitem> + <para> + This sets the <varname>client_encoding</varname> + configuration parameter for this connection. In addition to + the values accepted by the corresponding server option, you + can use <literal>auto</literal> to determine the right + encoding from the current locale in the client + (<envar>LC_CTYPE</envar> environment variable on Unix + systems). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-options" xreflabel="options"> + <term><literal>options</literal></term> + <listitem> + <para> + Specifies command-line options to send to the server at connection + start. For example, setting this to <literal>-c geqo=off</literal> sets the + session's value of the <varname>geqo</varname> parameter to + <literal>off</literal>. Spaces within this string are considered to + separate command-line arguments, unless escaped with a backslash + (<literal>\</literal>); write <literal>\\</literal> to represent a literal + backslash. For a detailed discussion of the available + options, consult <xref linkend="runtime-config"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-application-name" xreflabel="application_name"> + <term><literal>application_name</literal></term> + <listitem> + <para> + Specifies a value for the <xref linkend="guc-application-name"/> + configuration parameter. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-fallback-application-name" xreflabel="fallback_application_name"> + <term><literal>fallback_application_name</literal></term> + <listitem> + <para> + Specifies a fallback value for the <xref + linkend="guc-application-name"/> configuration parameter. + This value will be used if no value has been given for + <literal>application_name</literal> via a connection parameter or the + <envar>PGAPPNAME</envar> 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. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-keepalives" xreflabel="keepalives"> + <term><literal>keepalives</literal></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-keepalives-idle" xreflabel="keepalives_idle"> + <term><literal>keepalives_idle</literal></term> + <listitem> + <para> + 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 <symbol>TCP_KEEPIDLE</symbol> or + an equivalent socket option is available, and on Windows; on other + systems, it has no effect. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-keepalives-interval" xreflabel="keepalives_interval"> + <term><literal>keepalives_interval</literal></term> + <listitem> + <para> + 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 <symbol>TCP_KEEPINTVL</symbol> or + an equivalent socket option is available, and on Windows; on other + systems, it has no effect. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-keepalives-count" xreflabel="keepalives_count"> + <term><literal>keepalives_count</literal></term> + <listitem> + <para> + 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 <symbol>TCP_KEEPCNT</symbol> or + an equivalent socket option is available; on other systems, it has no + effect. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-tcp-user-timeout" xreflabel="tcp_user_timeout"> + <term><literal>tcp_user_timeout</literal></term> + <listitem> + <para> + 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 <symbol>TCP_USER_TIMEOUT</symbol> + is available; on other systems, it has no effect. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-replication" xreflabel="replication"> + <term><literal>replication</literal></term> + <listitem> + <para> + 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 + <application>pg_basebackup</application> use internally, but it can + also be used by third-party applications. For a description of the + replication protocol, consult <xref linkend="protocol-replication"/>. + </para> + + <para> + The following values, which are case-insensitive, are supported: + <variablelist> + <varlistentry> + <term> + <literal>true</literal>, <literal>on</literal>, + <literal>yes</literal>, <literal>1</literal> + </term> + <listitem> + <para> + The connection goes into physical replication mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>database</literal></term> + <listitem> + <para> + The connection goes into logical replication mode, connecting to + the database specified in the <literal>dbname</literal> parameter. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>false</literal>, <literal>off</literal>, + <literal>no</literal>, <literal>0</literal> + </term> + <listitem> + <para> + The connection is a regular one, which is the default behavior. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + In physical or logical replication mode, only the simple query protocol + can be used. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-gssencmode" xreflabel="gssencmode"> + <term><literal>gssencmode</literal></term> + <listitem> + <para> + This option determines whether or with what priority a secure + <acronym>GSS</acronym> TCP/IP connection will be negotiated with the + server. There are three modes: + + <variablelist> + <varlistentry> + <term><literal>disable</literal></term> + <listitem> + <para> + only try a non-<acronym>GSSAPI</acronym>-encrypted connection + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>prefer</literal> (default)</term> + <listitem> + <para> + if there are <acronym>GSSAPI</acronym> credentials present (i.e., + in a credentials cache), first try + a <acronym>GSSAPI</acronym>-encrypted connection; if that fails or + there are no credentials, try a + non-<acronym>GSSAPI</acronym>-encrypted connection. This is the + default when <productname>PostgreSQL</productname> has been + compiled with <acronym>GSSAPI</acronym> support. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>require</literal></term> + <listitem> + <para> + only try a <acronym>GSSAPI</acronym>-encrypted connection + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + <literal>gssencmode</literal> is ignored for Unix domain socket + communication. If <productname>PostgreSQL</productname> is compiled + without GSSAPI support, using the <literal>require</literal> option + will cause an error, while <literal>prefer</literal> will be accepted + but <application>libpq</application> will not actually attempt + a <acronym>GSSAPI</acronym>-encrypted + connection.<indexterm><primary>GSSAPI</primary><secondary sortas="libpq">with + libpq</secondary></indexterm> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslmode" xreflabel="sslmode"> + <term><literal>sslmode</literal></term> + <listitem> + <para> + This option determines whether or with what priority a secure + <acronym>SSL</acronym> TCP/IP connection will be negotiated with the + server. There are six modes: + + <variablelist> + <varlistentry> + <term><literal>disable</literal></term> + <listitem> + <para> + only try a non-<acronym>SSL</acronym> connection + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>allow</literal></term> + <listitem> + <para> + first try a non-<acronym>SSL</acronym> connection; if that + fails, try an <acronym>SSL</acronym> connection + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>prefer</literal> (default)</term> + <listitem> + <para> + first try an <acronym>SSL</acronym> connection; if that fails, + try a non-<acronym>SSL</acronym> connection + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>require</literal></term> + <listitem> + <para> + only try an <acronym>SSL</acronym> connection. If a root CA + file is present, verify the certificate in the same way as + if <literal>verify-ca</literal> was specified + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>verify-ca</literal></term> + <listitem> + <para> + only try an <acronym>SSL</acronym> connection, and verify that + the server certificate is issued by a trusted + certificate authority (<acronym>CA</acronym>) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>verify-full</literal></term> + <listitem> + <para> + only try an <acronym>SSL</acronym> connection, verify that the + server certificate is issued by a + trusted <acronym>CA</acronym> and that the requested server host name + matches that in the certificate + </para> + </listitem> + </varlistentry> + </variablelist> + + See <xref linkend="libpq-ssl"/> for a detailed description of how + these options work. + </para> + + <para> + <literal>sslmode</literal> is ignored for Unix domain socket + communication. + If <productname>PostgreSQL</productname> is compiled without SSL support, + using options <literal>require</literal>, <literal>verify-ca</literal>, or + <literal>verify-full</literal> will cause an error, while + options <literal>allow</literal> and <literal>prefer</literal> will be + accepted but <application>libpq</application> will not actually attempt + an <acronym>SSL</acronym> + connection.<indexterm><primary>SSL</primary><secondary + sortas="libpq">with libpq</secondary></indexterm> + </para> + + <para> + Note that if <acronym>GSSAPI</acronym> encryption is possible, + that will be used in preference to <acronym>SSL</acronym> + encryption, regardless of the value of <literal>sslmode</literal>. + To force use of <acronym>SSL</acronym> encryption in an + environment that has working <acronym>GSSAPI</acronym> + infrastructure (such as a Kerberos server), also + set <literal>gssencmode</literal> to <literal>disable</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-requiressl" xreflabel="requiressl"> + <term><literal>requiressl</literal></term> + <listitem> + <para> + This option is deprecated in favor of the <literal>sslmode</literal> + setting. + </para> + + <para> + If set to 1, an <acronym>SSL</acronym> connection to the server + is required (this is equivalent to <literal>sslmode</literal> + <literal>require</literal>). <application>libpq</application> will then refuse + to connect if the server does not accept an + <acronym>SSL</acronym> connection. If set to 0 (default), + <application>libpq</application> will negotiate the connection type with + the server (equivalent to <literal>sslmode</literal> + <literal>prefer</literal>). This option is only available if + <productname>PostgreSQL</productname> is compiled with SSL support. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslcompression" xreflabel="sslcompression"> + <term><literal>sslcompression</literal></term> + <listitem> + <para> + 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. + </para> + + <para> + SSL compression is nowadays considered insecure and its use is no + longer recommended. <productname>OpenSSL</productname> 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. + <productname>PostgreSQL</productname> 14 disables compression + completely in the backend. + </para> + + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslcert" xreflabel="sslcert"> + <term><literal>sslcert</literal></term> + <listitem> + <para> + This parameter specifies the file name of the client SSL + certificate, replacing the default + <filename>~/.postgresql/postgresql.crt</filename>. + This parameter is ignored if an SSL connection is not made. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslkey" xreflabel="sslkey"> + <term><literal>sslkey</literal></term> + <listitem> + <para> + 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 + <filename>~/.postgresql/postgresql.key</filename>, or it can specify a key + obtained from an external <quote>engine</quote> (engines are + <productname>OpenSSL</productname> 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. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslpassword" xreflabel="sslpassword"> + <term><literal>sslpassword</literal></term> + <listitem> + <para> + This parameter specifies the password for the secret key specified in + <literal>sslkey</literal>, allowing client certificate private keys + to be stored in encrypted form on disk even when interactive passphrase + input is not practical. + </para> + <para> + Specifying this parameter with any non-empty value suppresses the + <literal>Enter PEM pass phrase:</literal> + prompt that <productname>OpenSSL</productname> will emit by default + when an encrypted client certificate key is provided to + <literal>libpq</literal>. + </para> + <para> + If the key is not encrypted this parameter is ignored. The parameter + has no effect on keys specified by <productname>OpenSSL</productname> + engines unless the engine uses the <productname>OpenSSL</productname> + password callback mechanism for prompts. + </para> + <para> + There is no environment variable equivalent to this option, and no + facility for looking it up in <filename>.pgpass</filename>. It can be + used in a service file connection definition. Users with + more sophisticated uses should consider using <productname>OpenSSL</productname> engines and + tools like PKCS#11 or USB crypto offload devices. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslcertmode" xreflabel="sslcertmode"> + <term><literal>sslcertmode</literal></term> + <listitem> + <para> + This option determines whether a client certificate may be sent to the + server, and whether the server is required to request one. There are + three modes: + + <variablelist> + <varlistentry> + <term><literal>disable</literal></term> + <listitem> + <para> + A client certificate is never sent, even if one is available + (default location or provided via + <xref linkend="libpq-connect-sslcert" />). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>allow</literal> (default)</term> + <listitem> + <para> + A certificate may be sent, if the server requests one and the + client has one to send. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>require</literal></term> + <listitem> + <para> + The server <emphasis>must</emphasis> request a certificate. The + connection will fail if the client does not send a certificate and + the server successfully authenticates the client anyway. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <note> + <para> + <literal>sslcertmode=require</literal> doesn't add any additional + security, since there is no guarantee that the server is validating + the certificate correctly; PostgreSQL servers generally request TLS + certificates from clients whether they validate them or not. The + option may be useful when troubleshooting more complicated TLS + setups. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslrootcert" xreflabel="sslrootcert"> + <term><literal>sslrootcert</literal></term> + <listitem> + <para> + This parameter specifies the name of a file containing SSL + certificate authority (<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 + <filename>~/.postgresql/root.crt</filename>. + </para> + <para> + The special value <literal>system</literal> may be specified instead, in + which case the system's trusted CA roots will be loaded. The exact + locations of these root certificates differ by SSL implementation and + platform. For <productname>OpenSSL</productname> in particular, the + locations may be further modified by the <envar>SSL_CERT_DIR</envar> + and <envar>SSL_CERT_FILE</envar> environment variables. + </para> + <note> + <para> + When using <literal>sslrootcert=system</literal>, the default + <literal>sslmode</literal> is changed to <literal>verify-full</literal>, + and any weaker setting will result in an error. In most cases it is + trivial for anyone to obtain a certificate trusted by the system for a + hostname they control, rendering <literal>verify-ca</literal> and all + weaker modes useless. + </para> + <para> + The magic <literal>system</literal> value will take precedence over a + local certificate file with the same name. If for some reason you find + yourself in this situation, use an alternative path like + <literal>sslrootcert=./system</literal> instead. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslcrl" xreflabel="sslcrl"> + <term><literal>sslcrl</literal></term> + <listitem> + <para> + 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 + <xref linkend="libpq-connect-sslcrl"/> nor + <xref linkend="libpq-connect-sslcrldir"/> is set, this setting is + taken as + <filename>~/.postgresql/root.crl</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslcrldir" xreflabel="sslcrldir"> + <term><literal>sslcrldir</literal></term> + <listitem> + <para> + 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. + </para> + + <para> + The directory needs to be prepared with the + <productname>OpenSSL</productname> command + <literal>openssl rehash</literal> or <literal>c_rehash</literal>. See + its documentation for details. + </para> + + <para> + Both <literal>sslcrl</literal> and <literal>sslcrldir</literal> can be + specified together. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-sslsni" xreflabel="sslsni"> + <term><literal>sslsni</literal><indexterm><primary>Server Name Indication</primary></indexterm></term> + <listitem> + <para> + If set to 1 (default), libpq sets the TLS extension <quote>Server Name + Indication</quote> (<acronym>SNI</acronym>) on SSL-enabled connections. + By setting this parameter to 0, this is turned off. + </para> + + <para> + 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>SNI</acronym> makes the + destination host name appear in cleartext in the network traffic, so + it might be undesirable in some cases. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-requirepeer" xreflabel="requirepeer"> + <term><literal>requirepeer</literal></term> + <listitem> + <para> + This parameter specifies the operating-system user name of the + server, for example <literal>requirepeer=postgres</literal>. + 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 + <filename>/tmp</filename> 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 + <literal>peer</literal> authentication method is implemented; see + <xref linkend="auth-peer"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-ssl-min-protocol-version" xreflabel="ssl_min_protocol_version"> + <term><literal>ssl_min_protocol_version</literal></term> + <listitem> + <para> + This parameter specifies the minimum SSL/TLS protocol version to allow + for the connection. Valid values are <literal>TLSv1</literal>, + <literal>TLSv1.1</literal>, <literal>TLSv1.2</literal> and + <literal>TLSv1.3</literal>. The supported protocols depend on the + version of <productname>OpenSSL</productname> used, older versions + not supporting the most modern protocol versions. If not specified, + the default is <literal>TLSv1.2</literal>, which satisfies industry + best practices as of this writing. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-ssl-max-protocol-version" xreflabel="ssl_max_protocol_version"> + <term><literal>ssl_max_protocol_version</literal></term> + <listitem> + <para> + This parameter specifies the maximum SSL/TLS protocol version to allow + for the connection. Valid values are <literal>TLSv1</literal>, + <literal>TLSv1.1</literal>, <literal>TLSv1.2</literal> and + <literal>TLSv1.3</literal>. The supported protocols depend on the + version of <productname>OpenSSL</productname> 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. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-krbsrvname" xreflabel="krbsrvname"> + <term><literal>krbsrvname</literal></term> + <listitem> + <para> + 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 + <xref linkend="gssapi-auth"/>.) + The default value is normally <literal>postgres</literal>, + but that can be changed when + building <productname>PostgreSQL</productname> via + the <option>--with-krb-srvnam</option> option + of <application>configure</application>. + 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 (<literal>POSTGRES</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-gsslib" xreflabel="gsslib"> + <term><literal>gsslib</literal></term> + <listitem> + <para> + 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 <literal>gssapi</literal> to cause libpq to use the GSSAPI + library for authentication instead of the default SSPI. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-gssdelegation" xreflabel="gssdelegation"> + <term><literal>gssdelegation</literal></term> + <listitem> + <para> + Forward (delegate) GSS credentials to the server. The default is + <literal>0</literal> which means credentials will not be forwarded + to the server. Set this to <literal>1</literal> to have credentials + forwarded when possible. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-service" xreflabel="service"> + <term><literal>service</literal></term> + <listitem> + <para> + Service name to use for additional parameters. It specifies a service + name in <filename>pg_service.conf</filename> that holds additional connection parameters. + This allows applications to specify only a service name so connection parameters + can be centrally maintained. See <xref linkend="libpq-pgservice"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-target-session-attrs" xreflabel="target_session_attrs"> + <term><literal>target_session_attrs</literal></term> + <listitem> + <para> + 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: + + <variablelist> + <varlistentry> + <term><literal>any</literal> (default)</term> + <listitem> + <para> + any successful connection is acceptable + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>read-write</literal></term> + <listitem> + <para> + session must accept read-write transactions by default (that + is, the server must not be in hot standby mode and + the <varname>default_transaction_read_only</varname> parameter + must be <literal>off</literal>) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>read-only</literal></term> + <listitem> + <para> + session must not accept read-write transactions by default (the + converse) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>primary</literal></term> + <listitem> + <para> + server must not be in hot standby mode + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>standby</literal></term> + <listitem> + <para> + server must be in hot standby mode + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>prefer-standby</literal></term> + <listitem> + <para> + first try to find a standby server, but if none of the listed + hosts is a standby server, try again in <literal>any</literal> + mode + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connect-load-balance-hosts" xreflabel="load_balance_hosts"> + <term><literal>load_balance_hosts</literal></term> + <listitem> + <para> + Controls the order in which the client tries to connect to the available + hosts and addresses. Once a connection attempt is successful no other + hosts and addresses will be tried. This parameter is typically used in + combination with multiple host names or a DNS record that returns + multiple IPs. This parameter can be used in combination with + <xref linkend="libpq-connect-target-session-attrs"/> + to, for example, load balance over standby servers only. Once successfully + connected, subsequent queries on the returned connection will all be + sent to the same server. There are currently two modes: + <variablelist> + <varlistentry> + <term><literal>disable</literal> (default)</term> + <listitem> + <para> + No load balancing across hosts is performed. Hosts are tried in + the order in which they are provided and addresses are tried in + the order they are received from DNS or a hosts file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>random</literal></term> + <listitem> + <para> + Hosts and addresses are tried in random order. This value is mostly + useful when opening multiple connections at the same time, possibly + from different machines. This way connections can be load balanced + across multiple <productname>PostgreSQL</productname> servers. + </para> + <para> + While random load balancing, due to its random nature, will almost + never result in a completely uniform distribution, it statistically + gets quite close. One important aspect here is that this algorithm + uses two levels of random choices: First the hosts + will be resolved in random order. Then secondly, before resolving + the next host, all resolved addresses for the current host will be + tried in random order. This behaviour can skew the amount of + connections each node gets greatly in certain cases, for instance + when some hosts resolve to more addresses than others. But such a + skew can also be used on purpose, e.g. to increase the number of + connections a larger server gets by providing its hostname multiple + times in the host string. + </para> + <para> + When using this value it's recommended to also configure a reasonable + value for <xref linkend="libpq-connect-connect-timeout"/>. Because then, + if one of the nodes that are used for load balancing is not responding, + a new node will be tried. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect2> + </sect1> + + <sect1 id="libpq-status"> + <title>Connection Status Functions</title> + + <para> + These functions can be used to interrogate the status + of an existing database connection object. + </para> + + <tip> + <para> + <indexterm><primary>libpq-fe.h</primary></indexterm> + <indexterm><primary>libpq-int.h</primary></indexterm> + <application>libpq</application> application programmers should be careful to + maintain the <structname>PGconn</structname> abstraction. Use the accessor + functions described below to get at the contents of <structname>PGconn</structname>. + Reference to internal <structname>PGconn</structname> fields using + <filename>libpq-int.h</filename> is not recommended because they are subject to change + in the future. + </para> + </tip> + + <para> + The following functions return parameter values established at connection. + These values are fixed for the life of the connection. If a multi-host + connection string is used, the values of <xref linkend="libpq-PQhost"/>, + <xref linkend="libpq-PQport"/>, and <xref linkend="libpq-PQpass"/> can change if a new connection + is established using the same <structname>PGconn</structname> object. Other values + are fixed for the lifetime of the <structname>PGconn</structname> object. + + <variablelist> + <varlistentry id="libpq-PQdb"> + <term><function>PQdb</function><indexterm><primary>PQdb</primary></indexterm></term> + + <listitem> + <para> + Returns the database name of the connection. +<synopsis> +char *PQdb(const PGconn *conn); +</synopsis> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQuser"> + <term><function>PQuser</function><indexterm><primary>PQuser</primary></indexterm></term> + + <listitem> + <para> + Returns the user name of the connection. +<synopsis> +char *PQuser(const PGconn *conn); +</synopsis> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQpass"> + <term><function>PQpass</function><indexterm><primary>PQpass</primary></indexterm></term> + + <listitem> + <para> + Returns the password of the connection. +<synopsis> +char *PQpass(const PGconn *conn); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQpass"/> will return either the password specified + in the connection parameters, or if there was none and the password + was obtained from the <link linkend="libpq-pgpass">password + file</link>, it will return that. In the latter case, + if multiple hosts were specified in the connection parameters, it is + not possible to rely on the result of <xref linkend="libpq-PQpass"/> until + the connection is established. The status of the connection can be + checked using the function <xref linkend="libpq-PQstatus"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQhost"> + <term><function>PQhost</function><indexterm><primary>PQhost</primary></indexterm></term> + + <listitem> + <para> + Returns the server host name of the active connection. + This can be a host name, an IP address, or a directory path if the + connection is via Unix socket. (The path case can be distinguished + because it will always be an absolute path, beginning + with <literal>/</literal>.) +<synopsis> +char *PQhost(const PGconn *conn); +</synopsis> + </para> + + <para> + If the connection parameters specified both <literal>host</literal> and + <literal>hostaddr</literal>, then <xref linkend="libpq-PQhost"/> will + return the <literal>host</literal> information. If only + <literal>hostaddr</literal> was specified, then that is returned. + If multiple hosts were specified in the connection parameters, + <xref linkend="libpq-PQhost"/> returns the host actually connected to. + </para> + + <para> + <xref linkend="libpq-PQhost"/> returns <symbol>NULL</symbol> if the + <parameter>conn</parameter> argument is <symbol>NULL</symbol>. + Otherwise, if there is an error producing the host information (perhaps + if the connection has not been fully established or there was an + error), it returns an empty string. + </para> + + <para> + If multiple hosts were specified in the connection parameters, it is + not possible to rely on the result of <xref linkend="libpq-PQhost"/> until + the connection is established. The status of the connection can be + checked using the function <xref linkend="libpq-PQstatus"/>. + </para> + </listitem> + </varlistentry> + + + <varlistentry id="libpq-PQhostaddr"> + <term><function>PQhostaddr</function><indexterm><primary>PQhostaddr</primary></indexterm></term> + + <listitem> + <para> + Returns the server IP address of the active connection. + This can be the address that a host name resolved to, + or an IP address provided through the <literal>hostaddr</literal> + parameter. +<synopsis> +char *PQhostaddr(const PGconn *conn); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQhostaddr"/> returns <symbol>NULL</symbol> if the + <parameter>conn</parameter> argument is <symbol>NULL</symbol>. + Otherwise, if there is an error producing the host information + (perhaps if the connection has not been fully established or + there was an error), it returns an empty string. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQport"> + <term><function>PQport</function><indexterm><primary>PQport</primary></indexterm></term> + + <listitem> + <para> + Returns the port of the active connection. + +<synopsis> +char *PQport(const PGconn *conn); +</synopsis> + </para> + + <para> + If multiple ports were specified in the connection parameters, + <xref linkend="libpq-PQport"/> returns the port actually connected to. + </para> + + <para> + <xref linkend="libpq-PQport"/> returns <symbol>NULL</symbol> if the + <parameter>conn</parameter> argument is <symbol>NULL</symbol>. + Otherwise, if there is an error producing the port information (perhaps + if the connection has not been fully established or there was an + error), it returns an empty string. + </para> + + <para> + If multiple ports were specified in the connection parameters, it is + not possible to rely on the result of <xref linkend="libpq-PQport"/> until + the connection is established. The status of the connection can be + checked using the function <xref linkend="libpq-PQstatus"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQtty"> + <term><function>PQtty</function><indexterm><primary>PQtty</primary></indexterm></term> + + <listitem> + <para> + This function no longer does anything, but it remains for backwards + compatibility. The function always return an empty string, or + <symbol>NULL</symbol> if the <parameter>conn</parameter> argument is + <symbol>NULL</symbol>. + +<synopsis> +char *PQtty(const PGconn *conn); +</synopsis> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQoptions"> + <term><function>PQoptions</function><indexterm><primary>PQoptions</primary></indexterm></term> + + <listitem> + <para> + Returns the command-line options passed in the connection request. +<synopsis> +char *PQoptions(const PGconn *conn); +</synopsis> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + The following functions return status data that can change as operations + are executed on the <structname>PGconn</structname> object. + + <variablelist> + <varlistentry id="libpq-PQstatus"> + <term><function>PQstatus</function><indexterm><primary>PQstatus</primary></indexterm></term> + + <listitem> + <para> + Returns the status of the connection. +<synopsis> +ConnStatusType PQstatus(const PGconn *conn); +</synopsis> + </para> + + <para> + The status can be one of a number of values. However, only two of + these are seen outside of an asynchronous connection procedure: + <literal>CONNECTION_OK</literal> and + <literal>CONNECTION_BAD</literal>. A good connection to the database + has the status <literal>CONNECTION_OK</literal>. A failed + connection attempt is signaled by status + <literal>CONNECTION_BAD</literal>. Ordinarily, an OK status will + remain so until <xref linkend="libpq-PQfinish"/>, but a communications + failure might result in the status changing to + <literal>CONNECTION_BAD</literal> prematurely. In that case the + application could try to recover by calling + <xref linkend="libpq-PQreset"/>. + </para> + + <para> + See the entry for <xref linkend="libpq-PQconnectStartParams"/>, <function>PQconnectStart</function> + and <function>PQconnectPoll</function> with regards to other status codes that + might be returned. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQtransactionStatus"> + <term><function>PQtransactionStatus</function><indexterm><primary>PQtransactionStatus</primary></indexterm></term> + + <listitem> + <para> + Returns the current in-transaction status of the server. + +<synopsis> +PGTransactionStatusType PQtransactionStatus(const PGconn *conn); +</synopsis> + + The status can be <literal>PQTRANS_IDLE</literal> (currently idle), + <literal>PQTRANS_ACTIVE</literal> (a command is in progress), + <literal>PQTRANS_INTRANS</literal> (idle, in a valid transaction block), + or <literal>PQTRANS_INERROR</literal> (idle, in a failed transaction block). + <literal>PQTRANS_UNKNOWN</literal> is reported if the connection is bad. + <literal>PQTRANS_ACTIVE</literal> is reported only when a query + has been sent to the server and not yet completed. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQparameterStatus"> + <term><function>PQparameterStatus</function><indexterm><primary>PQparameterStatus</primary></indexterm></term> + + <listitem> + <para> + Looks up a current parameter setting of the server. + +<synopsis> +const char *PQparameterStatus(const PGconn *conn, const char *paramName); +</synopsis> + + Certain parameter values are reported by the server automatically at + connection startup or whenever their values change. + <xref linkend="libpq-PQparameterStatus"/> can be used to interrogate these settings. + It returns the current value of a parameter if known, or <symbol>NULL</symbol> + if the parameter is not known. + </para> + + <para> + Parameters reported as of the current release include + <varname>server_version</varname>, + <varname>server_encoding</varname>, + <varname>client_encoding</varname>, + <varname>application_name</varname>, + <varname>default_transaction_read_only</varname>, + <varname>in_hot_standby</varname>, + <varname>is_superuser</varname>, + <varname>session_authorization</varname>, + <varname>DateStyle</varname>, + <varname>IntervalStyle</varname>, + <varname>TimeZone</varname>, + <varname>integer_datetimes</varname>, and + <varname>standard_conforming_strings</varname>. + (<varname>server_encoding</varname>, <varname>TimeZone</varname>, and + <varname>integer_datetimes</varname> were not reported by releases before 8.0; + <varname>standard_conforming_strings</varname> was not reported by releases + before 8.1; + <varname>IntervalStyle</varname> was not reported by releases before 8.4; + <varname>application_name</varname> was not reported by releases before + 9.0; + <varname>default_transaction_read_only</varname> and + <varname>in_hot_standby</varname> were not reported by releases before + 14.) + Note that + <varname>server_version</varname>, + <varname>server_encoding</varname> and + <varname>integer_datetimes</varname> + cannot change after startup. + </para> + + <para> + If no value for <varname>standard_conforming_strings</varname> is reported, + applications can assume it is <literal>off</literal>, that is, backslashes + are treated as escapes in string literals. Also, the presence of + this parameter can be taken as an indication that the escape string + syntax (<literal>E'...'</literal>) is accepted. + </para> + + <para> + Although the returned pointer is declared <literal>const</literal>, it in fact + points to mutable storage associated with the <literal>PGconn</literal> structure. + It is unwise to assume the pointer will remain valid across queries. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQprotocolVersion"> + <term><function>PQprotocolVersion</function><indexterm><primary>PQprotocolVersion</primary></indexterm></term> + + <listitem> + <para> + Interrogates the frontend/backend protocol being used. +<synopsis> +int PQprotocolVersion(const PGconn *conn); +</synopsis> + Applications might wish to use this function to determine whether certain + features are supported. Currently, the possible values are 3 + (3.0 protocol), or zero (connection bad). The protocol version will + not change after connection startup is complete, but it could + theoretically change during a connection reset. The 3.0 protocol is + supported by <productname>PostgreSQL</productname> server versions 7.4 + and above. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQserverVersion"> + <term><function>PQserverVersion</function><indexterm><primary>PQserverVersion</primary></indexterm></term> + + <listitem> + <para> + Returns an integer representing the server version. +<synopsis> +int PQserverVersion(const PGconn *conn); +</synopsis> + </para> + + <para> + Applications might use this function to determine the version of the + database server they are connected to. The result is formed by + multiplying the server's major version number by 10000 and adding + the minor version number. For example, version 10.1 will be + returned as 100001, and version 11.0 will be returned as 110000. + Zero is returned if the connection is bad. + </para> + + <para> + Prior to major version 10, <productname>PostgreSQL</productname> used + three-part version numbers in which the first two parts together + represented the major version. For those + versions, <xref linkend="libpq-PQserverVersion"/> uses two digits for each + part; for example version 9.1.5 will be returned as 90105, and + version 9.2.0 will be returned as 90200. + </para> + + <para> + Therefore, for purposes of determining feature compatibility, + applications should divide the result of <xref linkend="libpq-PQserverVersion"/> + by 100 not 10000 to determine a logical major version number. + In all release series, only the last two digits differ between + minor releases (bug-fix releases). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQerrorMessage"> + <term><function>PQerrorMessage</function><indexterm><primary>PQerrorMessage</primary></indexterm></term> + + <listitem> + <para> + <indexterm><primary>error message</primary></indexterm> Returns the error message + most recently generated by an operation on the connection. + +<synopsis> +char *PQerrorMessage(const PGconn *conn); +</synopsis> + + </para> + + <para> + Nearly all <application>libpq</application> functions will set a message for + <xref linkend="libpq-PQerrorMessage"/> if they fail. Note that by + <application>libpq</application> convention, a nonempty + <xref linkend="libpq-PQerrorMessage"/> result can consist of multiple lines, + and will include a trailing newline. The caller should not free + the result directly. It will be freed when the associated + <structname>PGconn</structname> handle is passed to + <xref linkend="libpq-PQfinish"/>. The result string should not be + expected to remain the same across operations on the + <literal>PGconn</literal> structure. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsocket"> + <term><function>PQsocket</function><indexterm><primary>PQsocket</primary></indexterm></term> + <listitem> + <para> + Obtains the file descriptor number of the connection socket to + the server. A valid descriptor will be greater than or equal + to 0; a result of -1 indicates that no server connection is + currently open. (This will not change during normal operation, + but could change during connection setup or reset.) + +<synopsis> +int PQsocket(const PGconn *conn); +</synopsis> + + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQbackendPID"> + <term><function>PQbackendPID</function><indexterm><primary>PQbackendPID</primary></indexterm></term> + <listitem> + <para> + Returns the process <acronym>ID</acronym> (PID)<indexterm> + <primary>PID</primary> + <secondary>determining PID of server process</secondary> + <tertiary>in libpq</tertiary> + </indexterm> + of the backend process handling this connection. + +<synopsis> +int PQbackendPID(const PGconn *conn); +</synopsis> + </para> + + <para> + The backend <acronym>PID</acronym> is useful for debugging + purposes and for comparison to <command>NOTIFY</command> + messages (which include the <acronym>PID</acronym> of the + notifying backend process). Note that the + <acronym>PID</acronym> belongs to a process executing on the + database server host, not the local host! + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQconnectionNeedsPassword"> + <term><function>PQconnectionNeedsPassword</function><indexterm><primary>PQconnectionNeedsPassword</primary></indexterm></term> + <listitem> + <para> + Returns true (1) if the connection authentication method + required a password, but none was available. + Returns false (0) if not. + +<synopsis> +int PQconnectionNeedsPassword(const PGconn *conn); +</synopsis> + </para> + + <para> + This function can be applied after a failed connection attempt + to decide whether to prompt the user for a password. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQconnectionUsedPassword"> + <term><function>PQconnectionUsedPassword</function><indexterm><primary>PQconnectionUsedPassword</primary></indexterm></term> + <listitem> + <para> + Returns true (1) if the connection authentication method + used a password. Returns false (0) if not. + +<synopsis> +int PQconnectionUsedPassword(const PGconn *conn); +</synopsis> + </para> + + <para> + This function can be applied after either a failed or successful + connection attempt to detect whether the server demanded a password. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQconnectionUsedGSSAPI"> + <term><function>PQconnectionUsedGSSAPI</function><indexterm><primary>PQconnectionUsedGSSAPI</primary></indexterm></term> + <listitem> + <para> + Returns true (1) if the connection authentication method + used GSSAPI. Returns false (0) if not. + +<synopsis> +int PQconnectionUsedGSSAPI(const PGconn *conn); +</synopsis> + </para> + + <para> + This function can be applied to detect whether the connection was + authenticated with GSSAPI. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + The following functions return information related to SSL. This information + usually doesn't change after a connection is established. + + <variablelist> + <varlistentry id="libpq-PQsslInUse"> + <term><function>PQsslInUse</function><indexterm><primary>PQsslInUse</primary></indexterm></term> + <listitem> + <para> + Returns true (1) if the connection uses SSL, false (0) if not. + +<synopsis> +int PQsslInUse(const PGconn *conn); +</synopsis> + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsslAttribute"> + <term><function>PQsslAttribute</function><indexterm><primary>PQsslAttribute</primary></indexterm></term> + <listitem> + <para> + Returns SSL-related information about the connection. + +<synopsis> +const char *PQsslAttribute(const PGconn *conn, const char *attribute_name); +</synopsis> + </para> + + <para> + The list of available attributes varies depending on the SSL library + being used and the type of connection. Returns NULL if the connection + does not use SSL or the specified attribute name is not defined for the + library in use. + </para> + + <para> + The following attributes are commonly available: + <variablelist> + <varlistentry> + <term><literal>library</literal></term> + <listitem> + <para> + Name of the SSL implementation in use. (Currently, only + <literal>"OpenSSL"</literal> is implemented) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>protocol</literal></term> + <listitem> + <para> + SSL/TLS version in use. Common values + are <literal>"TLSv1"</literal>, <literal>"TLSv1.1"</literal> + and <literal>"TLSv1.2"</literal>, but an implementation may + return other strings if some other protocol is used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>key_bits</literal></term> + <listitem> + <para> + Number of key bits used by the encryption algorithm. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>cipher</literal></term> + <listitem> + <para> + A short name of the ciphersuite used, e.g., + <literal>"DHE-RSA-DES-CBC3-SHA"</literal>. The names are specific + to each SSL implementation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>compression</literal></term> + <listitem> + <para> + Returns "on" if SSL compression is in use, else it returns "off". + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + As a special case, the <literal>library</literal> attribute may be + queried without a connection by passing NULL as + the <literal>conn</literal> argument. The result will be the default + SSL library name, or NULL if <application>libpq</application> was + compiled without any SSL support. (Prior + to <productname>PostgreSQL</productname> version 15, passing NULL as + the <literal>conn</literal> argument always resulted in NULL. + Client programs needing to differentiate between the newer and older + implementations of this case may check the + <literal>LIBPQ_HAS_SSL_LIBRARY_DETECTION</literal> feature macro.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsslAttributeNames"> + <term><function>PQsslAttributeNames</function><indexterm><primary>PQsslAttributeNames</primary></indexterm></term> + <listitem> + <para> + Returns an array of SSL attribute names that can be used + in <function>PQsslAttribute()</function>. + The array is terminated by a NULL pointer. +<synopsis> +const char * const * PQsslAttributeNames(const PGconn *conn); +</synopsis> + </para> + + <para> + If <literal>conn</literal> is NULL, the attributes available for the + default SSL library are returned, or an empty list + if <application>libpq</application> was compiled without any SSL + support. If <literal>conn</literal> is not NULL, the attributes + available for the SSL library in use for the connection are returned, + or an empty list if the connection is not encrypted. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsslStruct"> + <term><function>PQsslStruct</function><indexterm><primary>PQsslStruct</primary></indexterm></term> + <listitem> + <para> + Returns a pointer to an SSL-implementation-specific object describing + the connection. Returns NULL if the connection is not encrypted + or the requested type of object is not available from the connection's + SSL implementation. +<synopsis> +void *PQsslStruct(const PGconn *conn, const char *struct_name); +</synopsis> + </para> + <para> + The struct(s) available depend on the SSL implementation in use. + For <productname>OpenSSL</productname>, there is one struct, + available under the name <literal>OpenSSL</literal>, + and it returns a pointer to + <productname>OpenSSL</productname>'s <literal>SSL</literal> struct. + To use this function, code along the following lines could be used: +<programlisting><![CDATA[ +#include <libpq-fe.h> +#include <openssl/ssl.h> + +... + + SSL *ssl; + + dbconn = PQconnectdb(...); + ... + + ssl = PQsslStruct(dbconn, "OpenSSL"); + if (ssl) + { + /* use OpenSSL functions to access ssl */ + } +]]></programlisting> + </para> + <para> + This structure can be used to verify encryption levels, check server + certificates, and more. Refer to the <productname>OpenSSL</productname> + documentation for information about this structure. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQgetssl"> + <term><function>PQgetssl</function><indexterm><primary>PQgetssl</primary></indexterm></term> + <listitem> + <para> + <indexterm><primary>SSL</primary><secondary sortas="libpq">in libpq</secondary></indexterm> + Returns the SSL structure used in the connection, or NULL + if SSL is not in use. + +<synopsis> +void *PQgetssl(const PGconn *conn); +</synopsis> + </para> + + <para> + This function is equivalent to <literal>PQsslStruct(conn, "OpenSSL")</literal>. It should + not be used in new applications, because the returned struct is + specific to <productname>OpenSSL</productname> and will not be + available if another <acronym>SSL</acronym> implementation is used. + To check if a connection uses SSL, call + <xref linkend="libpq-PQsslInUse"/> instead, and for more details about the + connection, use <xref linkend="libpq-PQsslAttribute"/>. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + </sect1> + + <sect1 id="libpq-exec"> + <title>Command Execution Functions</title> + + <para> + Once a connection to a database server has been successfully + established, the functions described here are used to perform + SQL queries and commands. + </para> + + <sect2 id="libpq-exec-main"> + <title>Main Functions</title> + + <para> + <variablelist> + <varlistentry id="libpq-PQexec"> + <term><function>PQexec</function><indexterm><primary>PQexec</primary></indexterm></term> + + <listitem> + <para> + Submits a command to the server and waits for the result. + +<synopsis> +PGresult *PQexec(PGconn *conn, const char *command); +</synopsis> + </para> + + <para> + Returns a <structname>PGresult</structname> pointer or possibly a null + pointer. A non-null pointer will generally be returned except in + out-of-memory conditions or serious errors such as inability to send + the command to the server. The <xref linkend="libpq-PQresultStatus"/> function + should be called to check the return value for any errors (including + the value of a null pointer, in which case it will return + <symbol>PGRES_FATAL_ERROR</symbol>). Use + <xref linkend="libpq-PQerrorMessage"/> to get more information about such + errors. + </para> + </listitem> + </varlistentry> + </variablelist> + + The command string can include multiple SQL commands + (separated by semicolons). Multiple queries sent in a single + <xref linkend="libpq-PQexec"/> call are processed in a single transaction, unless + there are explicit <command>BEGIN</command>/<command>COMMIT</command> + commands included in the query string to divide it into multiple + transactions. (See <xref linkend="protocol-flow-multi-statement"/> + for more details about how the server handles multi-query strings.) + Note however that the returned + <structname>PGresult</structname> structure describes only the result + of the last command executed from the string. Should one of the + commands fail, processing of the string stops with it and the returned + <structname>PGresult</structname> describes the error condition. + </para> + + <para> + <variablelist> + <varlistentry id="libpq-PQexecParams"> + <term><function>PQexecParams</function><indexterm><primary>PQexecParams</primary></indexterm></term> + + <listitem> + <para> + Submits a command to the server and waits for the result, + with the ability to pass parameters separately from the SQL + command text. + +<synopsis> +PGresult *PQexecParams(PGconn *conn, + const char *command, + int nParams, + const Oid *paramTypes, + const char * const *paramValues, + const int *paramLengths, + const int *paramFormats, + int resultFormat); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQexecParams"/> is like <xref linkend="libpq-PQexec"/>, but offers additional + functionality: parameter values can be specified separately from the command + string proper, and query results can be requested in either text or binary + format. + </para> + + <para> + The function arguments are: + + <variablelist> + <varlistentry> + <term><parameter>conn</parameter></term> + + <listitem> + <para> + The connection object to send the command through. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>command</parameter></term> + <listitem> + <para> + The SQL command string to be executed. If parameters are used, + they are referred to in the command string as <literal>$1</literal>, + <literal>$2</literal>, etc. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>nParams</parameter></term> + <listitem> + <para> + The number of parameters supplied; it is the length of the arrays + <parameter>paramTypes[]</parameter>, <parameter>paramValues[]</parameter>, + <parameter>paramLengths[]</parameter>, and <parameter>paramFormats[]</parameter>. (The + array pointers can be <symbol>NULL</symbol> when <parameter>nParams</parameter> + is zero.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>paramTypes[]</parameter></term> + <listitem> + <para> + Specifies, by OID, the data types to be assigned to the + parameter symbols. If <parameter>paramTypes</parameter> is + <symbol>NULL</symbol>, or any particular element in the array + is zero, the server infers a data type for the parameter symbol + in the same way it would do for an untyped literal string. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>paramValues[]</parameter></term> + <listitem> + <para> + Specifies the actual values of the parameters. A null pointer + in this array means the corresponding parameter is null; + otherwise the pointer points to a zero-terminated text string + (for text format) or binary data in the format expected by the + server (for binary format). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>paramLengths[]</parameter></term> + <listitem> + <para> + Specifies the actual data lengths of binary-format parameters. + It is ignored for null parameters and text-format parameters. + The array pointer can be null when there are no binary parameters. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>paramFormats[]</parameter></term> + <listitem> + <para> + Specifies whether parameters are text (put a zero in the + array entry for the corresponding parameter) or binary (put + a one in the array entry for the corresponding parameter). + If the array pointer is null then all parameters are presumed + to be text strings. + </para> + <para> + Values passed in binary format require knowledge of + the internal representation expected by the backend. + For example, integers must be passed in network byte + order. Passing <type>numeric</type> values requires + knowledge of the server storage format, as implemented + in + <filename>src/backend/utils/adt/numeric.c::numeric_send()</filename> and + <filename>src/backend/utils/adt/numeric.c::numeric_recv()</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>resultFormat</parameter></term> + <listitem> + <para> + Specify zero to obtain results in text format, or one to obtain + results in binary format. (There is not currently a provision + to obtain different result columns in different formats, + although that is possible in the underlying protocol.) + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + The primary advantage of <xref linkend="libpq-PQexecParams"/> over + <xref linkend="libpq-PQexec"/> is that parameter values can be separated from the + command string, thus avoiding the need for tedious and error-prone + quoting and escaping. + </para> + + <para> + Unlike <xref linkend="libpq-PQexec"/>, <xref linkend="libpq-PQexecParams"/> allows at most + one SQL command in the given string. (There can be semicolons in it, + but not more than one nonempty command.) This is a limitation of the + underlying protocol, but has some usefulness as an extra defense against + SQL-injection attacks. + </para> + + <tip> + <para> + Specifying parameter types via OIDs is tedious, particularly if you prefer + not to hard-wire particular OID values into your program. However, you can + avoid doing so even in cases where the server by itself cannot determine the + type of the parameter, or chooses a different type than you want. In the + SQL command text, attach an explicit cast to the parameter symbol to show what + data type you will send. For example: +<programlisting> +SELECT * FROM mytable WHERE x = $1::bigint; +</programlisting> + This forces parameter <literal>$1</literal> to be treated as <type>bigint</type>, whereas + by default it would be assigned the same type as <literal>x</literal>. Forcing the + parameter type decision, either this way or by specifying a numeric type OID, + is strongly recommended when sending parameter values in binary format, because + binary format has less redundancy than text format and so there is less chance + that the server will detect a type mismatch mistake for you. + </para> + </tip> + + <para> + <variablelist> + <varlistentry id="libpq-PQprepare"> + <term><function>PQprepare</function><indexterm><primary>PQprepare</primary></indexterm></term> + + <listitem> + <para> + Submits a request to create a prepared statement with the + given parameters, and waits for completion. +<synopsis> +PGresult *PQprepare(PGconn *conn, + const char *stmtName, + const char *query, + int nParams, + const Oid *paramTypes); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQprepare"/> creates a prepared statement for later + execution with <xref linkend="libpq-PQexecPrepared"/>. This feature allows + commands to be executed repeatedly without being parsed and + planned each time; see <xref linkend="sql-prepare"/> for details. + </para> + + <para> + The function creates a prepared statement named + <parameter>stmtName</parameter> from the <parameter>query</parameter> string, which + must contain a single SQL command. <parameter>stmtName</parameter> can be + <literal>""</literal> to create an unnamed statement, in which case any + pre-existing unnamed statement is automatically replaced; otherwise + it is an error if the statement name is already defined in the + current session. If any parameters are used, they are referred + to in the query as <literal>$1</literal>, <literal>$2</literal>, etc. + <parameter>nParams</parameter> is the number of parameters for which types + are pre-specified in the array <parameter>paramTypes[]</parameter>. (The + array pointer can be <symbol>NULL</symbol> when + <parameter>nParams</parameter> is zero.) <parameter>paramTypes[]</parameter> + specifies, by OID, the data types to be assigned to the parameter + symbols. If <parameter>paramTypes</parameter> is <symbol>NULL</symbol>, + or any particular element in the array is zero, the server assigns + a data type to the parameter symbol in the same way it would do + for an untyped literal string. Also, the query can use parameter + symbols with numbers higher than <parameter>nParams</parameter>; data types + will be inferred for these symbols as well. (See + <xref linkend="libpq-PQdescribePrepared"/> for a means to find out + what data types were inferred.) + </para> + + <para> + As with <xref linkend="libpq-PQexec"/>, the result is normally a + <structname>PGresult</structname> object whose contents indicate + server-side success or failure. A null result indicates + out-of-memory or inability to send the command at all. Use + <xref linkend="libpq-PQerrorMessage"/> to get more information about + such errors. + </para> + </listitem> + </varlistentry> + </variablelist> + + Prepared statements for use with <xref linkend="libpq-PQexecPrepared"/> can also + be created by executing SQL <xref linkend="sql-prepare"/> + statements. Also, although there is no <application>libpq</application> + function for deleting a prepared statement, the SQL <xref + linkend="sql-deallocate"/> statement + can be used for that purpose. + </para> + + <para> + <variablelist> + <varlistentry id="libpq-PQexecPrepared"> + <term><function>PQexecPrepared</function><indexterm><primary>PQexecPrepared</primary></indexterm></term> + + <listitem> + <para> + Sends a request to execute a prepared statement with given + parameters, and waits for the result. +<synopsis> +PGresult *PQexecPrepared(PGconn *conn, + const char *stmtName, + int nParams, + const char * const *paramValues, + const int *paramLengths, + const int *paramFormats, + int resultFormat); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQexecPrepared"/> is like <xref linkend="libpq-PQexecParams"/>, + but the command to be executed is specified by naming a + previously-prepared statement, instead of giving a query string. + This feature allows commands that will be used repeatedly to be + parsed and planned just once, rather than each time they are + executed. The statement must have been prepared previously in + the current session. + </para> + + <para> + The parameters are identical to <xref linkend="libpq-PQexecParams"/>, except that the + name of a prepared statement is given instead of a query string, and the + <parameter>paramTypes[]</parameter> parameter is not present (it is not needed since + the prepared statement's parameter types were determined when it was created). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQdescribePrepared"> + <term><function>PQdescribePrepared</function><indexterm><primary>PQdescribePrepared</primary></indexterm></term> + + <listitem> + <para> + Submits a request to obtain information about the specified + prepared statement, and waits for completion. +<synopsis> +PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQdescribePrepared"/> allows an application to obtain + information about a previously prepared statement. + </para> + + <para> + <parameter>stmtName</parameter> can be <literal>""</literal> or <symbol>NULL</symbol> to reference + the unnamed statement, otherwise it must be the name of an existing + prepared statement. On success, a <structname>PGresult</structname> with + status <literal>PGRES_COMMAND_OK</literal> is returned. The + functions <xref linkend="libpq-PQnparams"/> and + <xref linkend="libpq-PQparamtype"/> can be applied to this + <structname>PGresult</structname> to obtain information about the parameters + of the prepared statement, and the functions + <xref linkend="libpq-PQnfields"/>, <xref linkend="libpq-PQfname"/>, + <xref linkend="libpq-PQftype"/>, etc. provide information about the + result columns (if any) of the statement. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQdescribePortal"> + <term><function>PQdescribePortal</function><indexterm><primary>PQdescribePortal</primary></indexterm></term> + + <listitem> + <para> + Submits a request to obtain information about the specified + portal, and waits for completion. +<synopsis> +PGresult *PQdescribePortal(PGconn *conn, const char *portalName); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQdescribePortal"/> allows an application to obtain + information about a previously created portal. + (<application>libpq</application> does not provide any direct access to + portals, but you can use this function to inspect the properties + of a cursor created with a <command>DECLARE CURSOR</command> SQL command.) + </para> + + <para> + <parameter>portalName</parameter> can be <literal>""</literal> or <symbol>NULL</symbol> to reference + the unnamed portal, otherwise it must be the name of an existing + portal. On success, a <structname>PGresult</structname> with status + <literal>PGRES_COMMAND_OK</literal> is returned. The functions + <xref linkend="libpq-PQnfields"/>, <xref linkend="libpq-PQfname"/>, + <xref linkend="libpq-PQftype"/>, etc. can be applied to the + <structname>PGresult</structname> to obtain information about the result + columns (if any) of the portal. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + The <structname>PGresult</structname><indexterm><primary>PGresult</primary></indexterm> + structure encapsulates the result returned by the server. + <application>libpq</application> application programmers should be + careful to maintain the <structname>PGresult</structname> abstraction. + Use the accessor functions below to get at the contents of + <structname>PGresult</structname>. Avoid directly referencing the + fields of the <structname>PGresult</structname> structure because they + are subject to change in the future. + + <variablelist> + <varlistentry id="libpq-PQresultStatus"> + <term><function>PQresultStatus</function><indexterm><primary>PQresultStatus</primary></indexterm></term> + + <listitem> + <para> + Returns the result status of the command. +<synopsis> +ExecStatusType PQresultStatus(const PGresult *res); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQresultStatus"/> can return one of the following values: + + <variablelist> + <varlistentry id="libpq-pgres-empty-query"> + <term><literal>PGRES_EMPTY_QUERY</literal></term> + <listitem> + <para> + The string sent to the server was empty. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-command-ok"> + <term><literal>PGRES_COMMAND_OK</literal></term> + <listitem> + <para> + Successful completion of a command returning no data. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-tuples-ok"> + <term><literal>PGRES_TUPLES_OK</literal></term> + <listitem> + <para> + Successful completion of a command returning data (such as + a <command>SELECT</command> or <command>SHOW</command>). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-copy-out"> + <term><literal>PGRES_COPY_OUT</literal></term> + <listitem> + <para> + Copy Out (from server) data transfer started. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-copy-in"> + <term><literal>PGRES_COPY_IN</literal></term> + <listitem> + <para> + Copy In (to server) data transfer started. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-bad-response"> + <term><literal>PGRES_BAD_RESPONSE</literal></term> + <listitem> + <para> + The server's response was not understood. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-nonfatal-error"> + <term><literal>PGRES_NONFATAL_ERROR</literal></term> + <listitem> + <para> + A nonfatal error (a notice or warning) occurred. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-fatal-error"> + <term><literal>PGRES_FATAL_ERROR</literal></term> + <listitem> + <para> + A fatal error occurred. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-copy-both"> + <term><literal>PGRES_COPY_BOTH</literal></term> + <listitem> + <para> + Copy In/Out (to and from server) data transfer started. This + feature is currently used only for streaming replication, + so this status should not occur in ordinary applications. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-single-tuple"> + <term><literal>PGRES_SINGLE_TUPLE</literal></term> + <listitem> + <para> + The <structname>PGresult</structname> contains a single result tuple + from the current command. This status occurs only when + single-row mode has been selected for the query + (see <xref linkend="libpq-single-row-mode"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-pipeline-sync"> + <term><literal>PGRES_PIPELINE_SYNC</literal></term> + <listitem> + <para> + The <structname>PGresult</structname> represents a + synchronization point in pipeline mode, requested by + <xref linkend="libpq-PQpipelineSync"/>. + This status occurs only when pipeline mode has been selected. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgres-pipeline-aborted"> + <term><literal>PGRES_PIPELINE_ABORTED</literal></term> + <listitem> + <para> + The <structname>PGresult</structname> represents a pipeline that has + received an error from the server. <function>PQgetResult</function> + must be called repeatedly, and each time it will return this status code + until the end of the current pipeline, at which point it will return + <literal>PGRES_PIPELINE_SYNC</literal> and normal processing can + resume. + </para> + </listitem> + </varlistentry> + + </variablelist> + + If the result status is <literal>PGRES_TUPLES_OK</literal> or + <literal>PGRES_SINGLE_TUPLE</literal>, then + the functions described below can be used to retrieve the rows + returned by the query. Note that a <command>SELECT</command> + command that happens to retrieve zero rows still shows + <literal>PGRES_TUPLES_OK</literal>. + <literal>PGRES_COMMAND_OK</literal> is for commands that can never + return rows (<command>INSERT</command> or <command>UPDATE</command> + without a <literal>RETURNING</literal> clause, + etc.). A response of <literal>PGRES_EMPTY_QUERY</literal> might + indicate a bug in the client software. + </para> + + <para> + A result of status <symbol>PGRES_NONFATAL_ERROR</symbol> will + never be returned directly by <xref linkend="libpq-PQexec"/> or other + query execution functions; results of this kind are instead passed + to the notice processor (see <xref + linkend="libpq-notice-processing"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQresStatus"> + <term><function>PQresStatus</function><indexterm><primary>PQresStatus</primary></indexterm></term> + + <listitem> + <para> + Converts the enumerated type returned by + <xref linkend="libpq-PQresultStatus"/> into a string constant describing the + status code. The caller should not free the result. + +<synopsis> +char *PQresStatus(ExecStatusType status); +</synopsis> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQresultErrorMessage"> + <term><function>PQresultErrorMessage</function><indexterm><primary>PQresultErrorMessage</primary></indexterm></term> + + <listitem> + <para> + Returns the error message associated with the command, or an empty string + if there was no error. +<synopsis> +char *PQresultErrorMessage(const PGresult *res); +</synopsis> + If there was an error, the returned string will include a trailing + newline. The caller should not free the result directly. It will + be freed when the associated <structname>PGresult</structname> handle is + passed to <xref linkend="libpq-PQclear"/>. + </para> + + <para> + Immediately following a <xref linkend="libpq-PQexec"/> or + <xref linkend="libpq-PQgetResult"/> call, + <xref linkend="libpq-PQerrorMessage"/> (on the connection) will return + the same string as <xref linkend="libpq-PQresultErrorMessage"/> (on + the result). However, a <structname>PGresult</structname> will + retain its error message until destroyed, whereas the connection's + error message will change when subsequent operations are done. + Use <xref linkend="libpq-PQresultErrorMessage"/> when you want to + know the status associated with a particular + <structname>PGresult</structname>; use + <xref linkend="libpq-PQerrorMessage"/> when you want to know the + status from the latest operation on the connection. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQresultVerboseErrorMessage"> + <term><function>PQresultVerboseErrorMessage</function><indexterm><primary>PQresultVerboseErrorMessage</primary></indexterm></term> + + <listitem> + <para> + Returns a reformatted version of the error message associated with + a <structname>PGresult</structname> object. +<synopsis> +char *PQresultVerboseErrorMessage(const PGresult *res, + PGVerbosity verbosity, + PGContextVisibility show_context); +</synopsis> + In some situations a client might wish to obtain a more detailed + version of a previously-reported error. + <xref linkend="libpq-PQresultVerboseErrorMessage"/> addresses this need + by computing the message that would have been produced + by <xref linkend="libpq-PQresultErrorMessage"/> if the specified + verbosity settings had been in effect for the connection when the + given <structname>PGresult</structname> was generated. If + the <structname>PGresult</structname> is not an error result, + <quote>PGresult is not an error result</quote> is reported instead. + The returned string includes a trailing newline. + </para> + + <para> + Unlike most other functions for extracting data from + a <structname>PGresult</structname>, the result of this function is a freshly + allocated string. The caller must free it + using <function>PQfreemem()</function> when the string is no longer needed. + </para> + + <para> + A NULL return is possible if there is insufficient memory. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQresultErrorField"> + <term><function>PQresultErrorField</function><indexterm><primary>PQresultErrorField</primary></indexterm></term> + <listitem> + <para> + Returns an individual field of an error report. +<synopsis> +char *PQresultErrorField(const PGresult *res, int fieldcode); +</synopsis> + <parameter>fieldcode</parameter> is an error field identifier; see the symbols + listed below. <symbol>NULL</symbol> is returned if the + <structname>PGresult</structname> is not an error or warning result, + or does not include the specified field. Field values will normally + not include a trailing newline. The caller should not free the + result directly. It will be freed when the + associated <structname>PGresult</structname> handle is passed to + <xref linkend="libpq-PQclear"/>. + </para> + + <para> + The following field codes are available: + <variablelist> + <varlistentry id="libpq-pg-diag-severity"> + <term><symbol>PG_DIAG_SEVERITY</symbol></term> + <listitem> + <para> + The severity; the field contents are <literal>ERROR</literal>, + <literal>FATAL</literal>, or <literal>PANIC</literal> (in an error message), + or <literal>WARNING</literal>, <literal>NOTICE</literal>, <literal>DEBUG</literal>, + <literal>INFO</literal>, or <literal>LOG</literal> (in a notice message), or + a localized translation of one of these. Always present. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PG-diag-severity-nonlocalized"> + <term><symbol>PG_DIAG_SEVERITY_NONLOCALIZED</symbol></term> + <listitem> + <para> + The severity; the field contents are <literal>ERROR</literal>, + <literal>FATAL</literal>, or <literal>PANIC</literal> (in an error message), + or <literal>WARNING</literal>, <literal>NOTICE</literal>, <literal>DEBUG</literal>, + <literal>INFO</literal>, or <literal>LOG</literal> (in a notice message). + This is identical to the <symbol>PG_DIAG_SEVERITY</symbol> field except + that the contents are never localized. This is present only in + reports generated by <productname>PostgreSQL</productname> versions 9.6 + and later. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-sqlstate"> + <term><symbol>PG_DIAG_SQLSTATE</symbol><indexterm + ><primary>error codes</primary><secondary>libpq</secondary></indexterm></term> + <listitem> + <para> + The SQLSTATE code for the error. The SQLSTATE code identifies + the type of error that has occurred; it can be used by + front-end applications to perform specific operations (such + as error handling) in response to a particular database error. + For a list of the possible SQLSTATE codes, see <xref + linkend="errcodes-appendix"/>. This field is not localizable, + and is always present. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-message-primary"> + <term><symbol>PG_DIAG_MESSAGE_PRIMARY</symbol></term> + <listitem> + <para> + The primary human-readable error message (typically one line). + Always present. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-message-detail"> + <term><symbol>PG_DIAG_MESSAGE_DETAIL</symbol></term> + <listitem> + <para> + Detail: an optional secondary error message carrying more + detail about the problem. Might run to multiple lines. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-message-hint"> + <term><symbol>PG_DIAG_MESSAGE_HINT</symbol></term> + <listitem> + <para> + Hint: an optional suggestion what to do about the problem. + This is intended to differ from detail in that it offers advice + (potentially inappropriate) rather than hard facts. Might + run to multiple lines. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-statement-position"> + <term><symbol>PG_DIAG_STATEMENT_POSITION</symbol></term> + <listitem> + <para> + A string containing a decimal integer indicating an error cursor + position as an index into the original statement string. The + first character has index 1, and positions are measured in + characters not bytes. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-internal-position"> + <term><symbol>PG_DIAG_INTERNAL_POSITION</symbol></term> + <listitem> + <para> + This is defined the same as the + <symbol>PG_DIAG_STATEMENT_POSITION</symbol> field, but it is used + when the cursor position refers to an internally generated + command rather than the one submitted by the client. The + <symbol>PG_DIAG_INTERNAL_QUERY</symbol> field will always appear when + this field appears. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-internal-query"> + <term><symbol>PG_DIAG_INTERNAL_QUERY</symbol></term> + <listitem> + <para> + The text of a failed internally-generated command. This could + be, for example, an SQL query issued by a PL/pgSQL function. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-context"> + <term><symbol>PG_DIAG_CONTEXT</symbol></term> + <listitem> + <para> + An indication of the context in which the error occurred. + Presently this includes a call stack traceback of active + procedural language functions and internally-generated queries. + The trace is one entry per line, most recent first. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-schema-name"> + <term><symbol>PG_DIAG_SCHEMA_NAME</symbol></term> + <listitem> + <para> + If the error was associated with a specific database object, + the name of the schema containing that object, if any. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-table-name"> + <term><symbol>PG_DIAG_TABLE_NAME</symbol></term> + <listitem> + <para> + If the error was associated with a specific table, the name of the + table. (Refer to the schema name field for the name of the + table's schema.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-column-name"> + <term><symbol>PG_DIAG_COLUMN_NAME</symbol></term> + <listitem> + <para> + If the error was associated with a specific table column, the name + of the column. (Refer to the schema and table name fields to + identify the table.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-datatype-name"> + <term><symbol>PG_DIAG_DATATYPE_NAME</symbol></term> + <listitem> + <para> + If the error was associated with a specific data type, the name of + the data type. (Refer to the schema name field for the name of + the data type's schema.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-constraint-name"> + <term><symbol>PG_DIAG_CONSTRAINT_NAME</symbol></term> + <listitem> + <para> + If the error was associated with a specific constraint, the name + of the constraint. Refer to fields listed above for the + associated table or domain. (For this purpose, indexes are + treated as constraints, even if they weren't created with + constraint syntax.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-source-file"> + <term><symbol>PG_DIAG_SOURCE_FILE</symbol></term> + <listitem> + <para> + The file name of the source-code location where the error was + reported. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-source-line"> + <term><symbol>PG_DIAG_SOURCE_LINE</symbol></term> + <listitem> + <para> + The line number of the source-code location where the error + was reported. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pg-diag-source-function"> + <term><symbol>PG_DIAG_SOURCE_FUNCTION</symbol></term> + <listitem> + <para> + The name of the source-code function reporting the error. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <note> + <para> + The fields for schema name, table name, column name, data type name, + and constraint name are supplied only for a limited number of error + types; see <xref linkend="errcodes-appendix"/>. Do not assume that + the presence of any of these fields guarantees the presence of + another field. Core error sources observe the interrelationships + noted above, but user-defined functions may use these fields in other + ways. In the same vein, do not assume that these fields denote + contemporary objects in the current database. + </para> + </note> + + <para> + The client is responsible for formatting displayed information to meet + its needs; in particular it should break long lines as needed. + Newline characters appearing in the error message fields should be + treated as paragraph breaks, not line breaks. + </para> + + <para> + Errors generated internally by <application>libpq</application> will + have severity and primary message, but typically no other fields. + </para> + + <para> + Note that error fields are only available from + <structname>PGresult</structname> objects, not + <structname>PGconn</structname> objects; there is no + <function>PQerrorField</function> function. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQclear"> + <term><function>PQclear</function><indexterm><primary>PQclear</primary></indexterm></term> + <listitem> + <para> + Frees the storage associated with a + <structname>PGresult</structname>. Every command result should be + freed via <xref linkend="libpq-PQclear"/> when it is no longer + needed. + +<synopsis> +void PQclear(PGresult *res); +</synopsis> + + If the argument is a <symbol>NULL</symbol> pointer, no operation is + performed. + </para> + + <para> + You can keep a <structname>PGresult</structname> object around for + as long as you need it; it does not go away when you issue a new + command, nor even if you close the connection. To get rid of it, + you must call <xref linkend="libpq-PQclear"/>. Failure to do this + will result in memory leaks in your application. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect2> + + <sect2 id="libpq-exec-select-info"> + <title>Retrieving Query Result Information</title> + + <para> + These functions are used to extract information from a + <structname>PGresult</structname> object that represents a successful + query result (that is, one that has status + <literal>PGRES_TUPLES_OK</literal> or <literal>PGRES_SINGLE_TUPLE</literal>). + They can also be used to extract + information from a successful Describe operation: a Describe's result + has all the same column information that actual execution of the query + would provide, but it has zero rows. For objects with other status values, + these functions will act as though the result has zero rows and zero columns. + </para> + + <variablelist> + <varlistentry id="libpq-PQntuples"> + <term><function>PQntuples</function><indexterm><primary>PQntuples</primary></indexterm></term> + + <listitem> + <para> + Returns the number of rows (tuples) in the query result. + (Note that <structname>PGresult</structname> objects are limited to no more + than <literal>INT_MAX</literal> rows, so an <type>int</type> result is + sufficient.) + +<synopsis> +int PQntuples(const PGresult *res); +</synopsis> + + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQnfields"> + <term><function>PQnfields</function><indexterm><primary>PQnfields</primary></indexterm></term> + + <listitem> + <para> + Returns the number of columns (fields) in each row of the query + result. + +<synopsis> +int PQnfields(const PGresult *res); +</synopsis> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQfname"> + <term><function>PQfname</function><indexterm><primary>PQfname</primary></indexterm></term> + + <listitem> + <para> + Returns the column name associated with the given column number. + Column numbers start at 0. The caller should not free the result + directly. It will be freed when the associated + <structname>PGresult</structname> handle is passed to + <xref linkend="libpq-PQclear"/>. +<synopsis> +char *PQfname(const PGresult *res, + int column_number); +</synopsis> + </para> + + <para> + <symbol>NULL</symbol> is returned if the column number is out of range. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQfnumber"> + <term><function>PQfnumber</function><indexterm><primary>PQfnumber</primary></indexterm></term> + + <listitem> + <para> + Returns the column number associated with the given column name. +<synopsis> +int PQfnumber(const PGresult *res, + const char *column_name); +</synopsis> + </para> + + <para> + -1 is returned if the given name does not match any column. + </para> + + <para> + The given name is treated like an identifier in an SQL command, + that is, it is downcased unless double-quoted. For example, given + a query result generated from the SQL command: +<programlisting> +SELECT 1 AS FOO, 2 AS "BAR"; +</programlisting> + we would have the results: +<programlisting> +PQfname(res, 0) <lineannotation>foo</lineannotation> +PQfname(res, 1) <lineannotation>BAR</lineannotation> +PQfnumber(res, "FOO") <lineannotation>0</lineannotation> +PQfnumber(res, "foo") <lineannotation>0</lineannotation> +PQfnumber(res, "BAR") <lineannotation>-1</lineannotation> +PQfnumber(res, "\"BAR\"") <lineannotation>1</lineannotation> +</programlisting> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQftable"> + <term><function>PQftable</function><indexterm><primary>PQftable</primary></indexterm></term> + + <listitem> + <para> + Returns the OID of the table from which the given column was + fetched. Column numbers start at 0. +<synopsis> +Oid PQftable(const PGresult *res, + int column_number); +</synopsis> + </para> + + <para> + <literal>InvalidOid</literal> is returned if the column number is out of range, + or if the specified column is not a simple reference to a table column. + You can query the system table <literal>pg_class</literal> to determine + exactly which table is referenced. + </para> + + <para> + The type <type>Oid</type> and the constant + <literal>InvalidOid</literal> will be defined when you include + the <application>libpq</application> header file. They will both + be some integer type. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQftablecol"> + <term><function>PQftablecol</function><indexterm><primary>PQftablecol</primary></indexterm></term> + + <listitem> + <para> + Returns the column number (within its table) of the column making + up the specified query result column. Query-result column numbers + start at 0, but table columns have nonzero numbers. +<synopsis> +int PQftablecol(const PGresult *res, + int column_number); +</synopsis> + </para> + + <para> + Zero is returned if the column number is out of range, or if the + specified column is not a simple reference to a table column. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQfformat"> + <term><function>PQfformat</function><indexterm><primary>PQfformat</primary></indexterm></term> + + <listitem> + <para> + Returns the format code indicating the format of the given + column. Column numbers start at 0. +<synopsis> +int PQfformat(const PGresult *res, + int column_number); +</synopsis> + </para> + + <para> + Format code zero indicates textual data representation, while format + code one indicates binary representation. (Other codes are reserved + for future definition.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQftype"> + <term><function>PQftype</function><indexterm><primary>PQftype</primary></indexterm></term> + + <listitem> + <para> + Returns the data type associated with the given column number. + The integer returned is the internal OID number of the type. + Column numbers start at 0. +<synopsis> +Oid PQftype(const PGresult *res, + int column_number); +</synopsis> + </para> + + <para> + You can query the system table <literal>pg_type</literal> to + obtain the names and properties of the various data types. The + <acronym>OID</acronym>s of the built-in data types are defined + in the file <filename>catalog/pg_type_d.h</filename> + in the <productname>PostgreSQL</productname> + installation's <filename>include</filename> directory. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQfmod"> + <term><function>PQfmod</function><indexterm><primary>PQfmod</primary></indexterm></term> + + <listitem> + <para> + Returns the type modifier of the column associated with the + given column number. Column numbers start at 0. +<synopsis> +int PQfmod(const PGresult *res, + int column_number); +</synopsis> + </para> + + <para> + The interpretation of modifier values is type-specific; they + typically indicate precision or size limits. The value -1 is + used to indicate <quote>no information available</quote>. Most data + types do not use modifiers, in which case the value is always + -1. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQfsize"> + <term><function>PQfsize</function><indexterm><primary>PQfsize</primary></indexterm></term> + + <listitem> + <para> + Returns the size in bytes of the column associated with the + given column number. Column numbers start at 0. +<synopsis> +int PQfsize(const PGresult *res, + int column_number); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQfsize"/> returns the space allocated for this column + in a database row, in other words the size of the server's + internal representation of the data type. (Accordingly, it is + not really very useful to clients.) A negative value indicates + the data type is variable-length. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQbinaryTuples"> + <term><function>PQbinaryTuples</function><indexterm><primary>PQbinaryTuples</primary></indexterm></term> + + <listitem> + <para> + Returns 1 if the <structname>PGresult</structname> contains binary data + and 0 if it contains text data. +<synopsis> +int PQbinaryTuples(const PGresult *res); +</synopsis> + </para> + + <para> + This function is deprecated (except for its use in connection with + <command>COPY</command>), because it is possible for a single + <structname>PGresult</structname> to contain text data in some columns and + binary data in others. <xref linkend="libpq-PQfformat"/> is preferred. + <xref linkend="libpq-PQbinaryTuples"/> returns 1 only if all columns of the + result are binary (format 1). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQgetvalue"> + <term><function>PQgetvalue</function><indexterm><primary>PQgetvalue</primary></indexterm></term> + + <listitem> + <para> + Returns a single field value of one row of a + <structname>PGresult</structname>. Row and column numbers start + at 0. The caller should not free the result directly. It will + be freed when the associated <structname>PGresult</structname> handle is + passed to <xref linkend="libpq-PQclear"/>. +<synopsis> +char *PQgetvalue(const PGresult *res, + int row_number, + int column_number); +</synopsis> + </para> + + <para> + For data in text format, the value returned by + <xref linkend="libpq-PQgetvalue"/> is a null-terminated character + string representation of the field value. For data in binary + format, the value is in the binary representation determined by + the data type's <function>typsend</function> and <function>typreceive</function> + functions. (The value is actually followed by a zero byte in + this case too, but that is not ordinarily useful, since the + value is likely to contain embedded nulls.) + </para> + + <para> + An empty string is returned if the field value is null. See + <xref linkend="libpq-PQgetisnull"/> to distinguish null values from + empty-string values. + </para> + + <para> + The pointer returned by <xref linkend="libpq-PQgetvalue"/> points + to storage that is part of the <structname>PGresult</structname> + structure. One should not modify the data it points to, and one + must explicitly copy the data into other storage if it is to be + used past the lifetime of the <structname>PGresult</structname> + structure itself. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQgetisnull"> + <term><function>PQgetisnull</function><indexterm + ><primary>PQgetisnull</primary></indexterm><indexterm + ><primary>null value</primary><secondary sortas="libpq">in libpq</secondary></indexterm></term> + + <listitem> + <para> + Tests a field for a null value. Row and column numbers start + at 0. +<synopsis> +int PQgetisnull(const PGresult *res, + int row_number, + int column_number); +</synopsis> + </para> + + <para> + This function returns 1 if the field is null and 0 if it + contains a non-null value. (Note that + <xref linkend="libpq-PQgetvalue"/> will return an empty string, + not a null pointer, for a null field.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQgetlength"> + <term><function>PQgetlength</function><indexterm><primary>PQgetlength</primary></indexterm></term> + + <listitem> + <para> + Returns the actual length of a field value in bytes. Row and + column numbers start at 0. +<synopsis> +int PQgetlength(const PGresult *res, + int row_number, + int column_number); +</synopsis> + </para> + + <para> + This is the actual data length for the particular data value, + that is, the size of the object pointed to by + <xref linkend="libpq-PQgetvalue"/>. For text data format this is + the same as <function>strlen()</function>. For binary format this is + essential information. Note that one should <emphasis>not</emphasis> + rely on <xref linkend="libpq-PQfsize"/> to obtain the actual data + length. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQnparams"> + <term><function>PQnparams</function><indexterm><primary>PQnparams</primary></indexterm></term> + + <listitem> + <para> + Returns the number of parameters of a prepared statement. +<synopsis> +int PQnparams(const PGresult *res); +</synopsis> + </para> + + <para> + This function is only useful when inspecting the result of + <xref linkend="libpq-PQdescribePrepared"/>. For other types of results it + will return zero. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQparamtype"> + <term><function>PQparamtype</function><indexterm><primary>PQparamtype</primary></indexterm></term> + + <listitem> + <para> + Returns the data type of the indicated statement parameter. + Parameter numbers start at 0. +<synopsis> +Oid PQparamtype(const PGresult *res, int param_number); +</synopsis> + </para> + + <para> + This function is only useful when inspecting the result of + <xref linkend="libpq-PQdescribePrepared"/>. For other types of results it + will return zero. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQprint"> + <term><function>PQprint</function><indexterm><primary>PQprint</primary></indexterm></term> + + <listitem> + <para> + Prints out all the rows and, optionally, the column names to + the specified output stream. +<synopsis> +void PQprint(FILE *fout, /* output stream */ + const PGresult *res, + const PQprintOpt *po); +typedef struct +{ + pqbool header; /* print output field headings and row count */ + pqbool align; /* fill align the fields */ + pqbool standard; /* old brain dead format */ + pqbool html3; /* output HTML tables */ + pqbool expanded; /* expand tables */ + pqbool pager; /* use pager for output if needed */ + char *fieldSep; /* field separator */ + char *tableOpt; /* attributes for HTML table element */ + char *caption; /* HTML table caption */ + char **fieldName; /* null-terminated array of replacement field names */ +} PQprintOpt; +</synopsis> + </para> + + <para> + This function was formerly used by <application>psql</application> + to print query results, but this is no longer the case. Note + that it assumes all the data is in text format. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="libpq-exec-nonselect"> + <title>Retrieving Other Result Information</title> + + <para> + These functions are used to extract other information from + <structname>PGresult</structname> objects. + </para> + + <variablelist> + <varlistentry id="libpq-PQcmdStatus"> + <term><function>PQcmdStatus</function><indexterm><primary>PQcmdStatus</primary></indexterm></term> + + <listitem> + <para> + Returns the command status tag from the SQL command that generated + the <structname>PGresult</structname>. +<synopsis> +char *PQcmdStatus(PGresult *res); +</synopsis> + </para> + + <para> + Commonly this is just the name of the command, but it might include + additional data such as the number of rows processed. The caller + should not free the result directly. It will be freed when the + associated <structname>PGresult</structname> handle is passed to + <xref linkend="libpq-PQclear"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQcmdTuples"> + <term><function>PQcmdTuples</function><indexterm><primary>PQcmdTuples</primary></indexterm></term> + + <listitem> + <para> + Returns the number of rows affected by the SQL command. +<synopsis> +char *PQcmdTuples(PGresult *res); +</synopsis> + </para> + + <para> + This function returns a string containing the number of rows + affected by the <acronym>SQL</acronym> statement that generated the + <structname>PGresult</structname>. This function can only be used following + the execution of a <command>SELECT</command>, <command>CREATE TABLE AS</command>, + <command>INSERT</command>, <command>UPDATE</command>, <command>DELETE</command>, + <command>MERGE</command>, <command>MOVE</command>, <command>FETCH</command>, + or <command>COPY</command> statement, or an <command>EXECUTE</command> of a + prepared query that contains an <command>INSERT</command>, + <command>UPDATE</command>, <command>DELETE</command>, + or <command>MERGE</command> statement. + If the command that generated the <structname>PGresult</structname> was anything + else, <xref linkend="libpq-PQcmdTuples"/> returns an empty string. The caller + should not free the return value directly. It will be freed when + the associated <structname>PGresult</structname> handle is passed to + <xref linkend="libpq-PQclear"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQoidValue"> + <term><function>PQoidValue</function><indexterm><primary>PQoidValue</primary></indexterm></term> + + <listitem> + <para> + Returns the OID<indexterm><primary>OID</primary><secondary>in libpq</secondary></indexterm> + of the inserted row, if the <acronym>SQL</acronym> command was an + <command>INSERT</command> that inserted exactly one row into a table that + has OIDs, or a <command>EXECUTE</command> of a prepared query containing + a suitable <command>INSERT</command> statement. Otherwise, this function + returns <literal>InvalidOid</literal>. This function will also + return <literal>InvalidOid</literal> if the table affected by the + <command>INSERT</command> statement does not contain OIDs. +<synopsis> +Oid PQoidValue(const PGresult *res); +</synopsis> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQoidStatus"> + <term><function>PQoidStatus</function><indexterm><primary>PQoidStatus</primary></indexterm></term> + + <listitem> + <para> + This function is deprecated in favor of + <xref linkend="libpq-PQoidValue"/> and is not thread-safe. + It returns a string with the OID of the inserted row, while + <xref linkend="libpq-PQoidValue"/> returns the OID value. +<synopsis> +char *PQoidStatus(const PGresult *res); +</synopsis> + </para> + + </listitem> + </varlistentry> + </variablelist> + + </sect2> + + <sect2 id="libpq-exec-escape-string"> + <title>Escaping Strings for Inclusion in SQL Commands</title> + + <indexterm zone="libpq-exec-escape-string"> + <primary>escaping strings</primary> + <secondary>in libpq</secondary> + </indexterm> + + <variablelist> + <varlistentry id="libpq-PQescapeLiteral"> + <term><function>PQescapeLiteral</function><indexterm><primary>PQescapeLiteral</primary></indexterm></term> + + <listitem> + <para> +<synopsis> +char *PQescapeLiteral(PGconn *conn, const char *str, size_t length); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQescapeLiteral"/> escapes a string for + use within an SQL command. This is useful when inserting data + values as literal constants in SQL commands. Certain characters + (such as quotes and backslashes) must be escaped to prevent them + from being interpreted specially by the SQL parser. + <xref linkend="libpq-PQescapeLiteral"/> performs this operation. + </para> + + <para> + <xref linkend="libpq-PQescapeLiteral"/> returns an escaped version of the + <parameter>str</parameter> parameter in memory allocated with + <function>malloc()</function>. This memory should be freed using + <function>PQfreemem()</function> when the result is no longer needed. + A terminating zero byte is not required, and should not be + counted in <parameter>length</parameter>. (If a terminating zero byte is found + before <parameter>length</parameter> bytes are processed, + <xref linkend="libpq-PQescapeLiteral"/> stops at the zero; the behavior is + thus rather like <function>strncpy</function>.) The + return string has all special characters replaced so that they can + be properly processed by the <productname>PostgreSQL</productname> + string literal parser. A terminating zero byte is also added. The + single quotes that must surround <productname>PostgreSQL</productname> + string literals are included in the result string. + </para> + + <para> + On error, <xref linkend="libpq-PQescapeLiteral"/> returns <symbol>NULL</symbol> and a suitable + message is stored in the <parameter>conn</parameter> object. + </para> + + <tip> + <para> + It is especially important to do proper escaping when handling + strings that were received from an untrustworthy source. + Otherwise there is a security risk: you are vulnerable to + <quote>SQL injection</quote> attacks wherein unwanted SQL commands are + fed to your database. + </para> + </tip> + + <para> + Note that it is neither necessary nor correct to do escaping when a data + value is passed as a separate parameter in <xref linkend="libpq-PQexecParams"/> or + its sibling routines. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQescapeIdentifier"> + <term><function>PQescapeIdentifier</function><indexterm><primary>PQescapeIdentifier</primary></indexterm></term> + + <listitem> + <para> +<synopsis> +char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQescapeIdentifier"/> escapes a string for + use as an SQL identifier, such as a table, column, or function name. + This is useful when a user-supplied identifier might contain + special characters that would otherwise not be interpreted as part + of the identifier by the SQL parser, or when the identifier might + contain upper case characters whose case should be preserved. + </para> + + <para> + <xref linkend="libpq-PQescapeIdentifier"/> returns a version of the + <parameter>str</parameter> parameter escaped as an SQL identifier + in memory allocated with <function>malloc()</function>. This memory must be + freed using <function>PQfreemem()</function> when the result is no longer + needed. A terminating zero byte is not required, and should not be + counted in <parameter>length</parameter>. (If a terminating zero byte is found + before <parameter>length</parameter> bytes are processed, + <xref linkend="libpq-PQescapeIdentifier"/> stops at the zero; the behavior is + thus rather like <function>strncpy</function>.) The + return string has all special characters replaced so that it + will be properly processed as an SQL identifier. A terminating zero byte + is also added. The return string will also be surrounded by double + quotes. + </para> + + <para> + On error, <xref linkend="libpq-PQescapeIdentifier"/> returns <symbol>NULL</symbol> and a suitable + message is stored in the <parameter>conn</parameter> object. + </para> + + <tip> + <para> + As with string literals, to prevent SQL injection attacks, + SQL identifiers must be escaped when they are received from an + untrustworthy source. + </para> + </tip> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQescapeStringConn"> + <term><function>PQescapeStringConn</function><indexterm><primary>PQescapeStringConn</primary></indexterm></term> + + <listitem> + <para> +<synopsis> +size_t PQescapeStringConn(PGconn *conn, + char *to, const char *from, size_t length, + int *error); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQescapeStringConn"/> escapes string literals, much like + <xref linkend="libpq-PQescapeLiteral"/>. Unlike <xref linkend="libpq-PQescapeLiteral"/>, + the caller is responsible for providing an appropriately sized buffer. + Furthermore, <xref linkend="libpq-PQescapeStringConn"/> does not generate the + single quotes that must surround <productname>PostgreSQL</productname> string + literals; they should be provided in the SQL command that the + result is inserted into. The parameter <parameter>from</parameter> points to + the first character of the string that is to be escaped, and the + <parameter>length</parameter> parameter gives the number of bytes in this + string. A terminating zero byte is not required, and should not be + counted in <parameter>length</parameter>. (If a terminating zero byte is found + before <parameter>length</parameter> bytes are processed, + <xref linkend="libpq-PQescapeStringConn"/> stops at the zero; the behavior is + thus rather like <function>strncpy</function>.) <parameter>to</parameter> shall point + to a buffer that is able to hold at least one more byte than twice + the value of <parameter>length</parameter>, otherwise the behavior is undefined. + Behavior is likewise undefined if the <parameter>to</parameter> and + <parameter>from</parameter> strings overlap. + </para> + + <para> + If the <parameter>error</parameter> parameter is not <symbol>NULL</symbol>, then + <literal>*error</literal> is set to zero on success, nonzero on error. + Presently the only possible error conditions involve invalid multibyte + encoding in the source string. The output string is still generated + on error, but it can be expected that the server will reject it as + malformed. On error, a suitable message is stored in the + <parameter>conn</parameter> object, whether or not <parameter>error</parameter> is <symbol>NULL</symbol>. + </para> + + <para> + <xref linkend="libpq-PQescapeStringConn"/> returns the number of bytes written + to <parameter>to</parameter>, not including the terminating zero byte. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQescapeString"> + <term><function>PQescapeString</function><indexterm><primary>PQescapeString</primary></indexterm></term> + + <listitem> + <para> + <xref linkend="libpq-PQescapeString"/> is an older, deprecated version of + <xref linkend="libpq-PQescapeStringConn"/>. +<synopsis> +size_t PQescapeString (char *to, const char *from, size_t length); +</synopsis> + </para> + + <para> + The only difference from <xref linkend="libpq-PQescapeStringConn"/> is that + <xref linkend="libpq-PQescapeString"/> does not take <structname>PGconn</structname> + or <parameter>error</parameter> parameters. + Because of this, it cannot adjust its behavior depending on the + connection properties (such as character encoding) and therefore + <emphasis>it might give the wrong results</emphasis>. Also, it has no way + to report error conditions. + </para> + + <para> + <xref linkend="libpq-PQescapeString"/> can be used safely in + client programs that work with only one <productname>PostgreSQL</productname> + connection at a time (in this case it can find out what it needs to + know <quote>behind the scenes</quote>). In other contexts it is a security + hazard and should be avoided in favor of + <xref linkend="libpq-PQescapeStringConn"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQescapeByteaConn"> + <term><function>PQescapeByteaConn</function><indexterm><primary>PQescapeByteaConn</primary></indexterm></term> + + <listitem> + <para> + Escapes binary data for use within an SQL command with the type + <type>bytea</type>. As with <xref linkend="libpq-PQescapeStringConn"/>, + this is only used when inserting data directly into an SQL command string. +<synopsis> +unsigned char *PQescapeByteaConn(PGconn *conn, + const unsigned char *from, + size_t from_length, + size_t *to_length); +</synopsis> + </para> + + <para> + Certain byte values must be escaped when used as part of a + <type>bytea</type> literal in an <acronym>SQL</acronym> statement. + <xref linkend="libpq-PQescapeByteaConn"/> escapes bytes using + either hex encoding or backslash escaping. See <xref + linkend="datatype-binary"/> for more information. + </para> + + <para> + The <parameter>from</parameter> parameter points to the first + byte of the string that is to be escaped, and the + <parameter>from_length</parameter> parameter gives the number of + bytes in this binary string. (A terminating zero byte is + neither necessary nor counted.) The <parameter>to_length</parameter> + parameter points to a variable that will hold the resultant + escaped string length. This result string length includes the terminating + zero byte of the result. + </para> + + <para> + <xref linkend="libpq-PQescapeByteaConn"/> returns an escaped version of the + <parameter>from</parameter> parameter binary string in memory + allocated with <function>malloc()</function>. This memory should be freed using + <function>PQfreemem()</function> when the result is no longer needed. The + return string has all special characters replaced so that they can + be properly processed by the <productname>PostgreSQL</productname> + string literal parser, and the <type>bytea</type> input function. A + terminating zero byte is also added. The single quotes that must + surround <productname>PostgreSQL</productname> string literals are + not part of the result string. + </para> + + <para> + On error, a null pointer is returned, and a suitable error message + is stored in the <parameter>conn</parameter> object. Currently, the only + possible error is insufficient memory for the result string. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQescapeBytea"> + <term><function>PQescapeBytea</function><indexterm><primary>PQescapeBytea</primary></indexterm></term> + + <listitem> + <para> + <xref linkend="libpq-PQescapeBytea"/> is an older, deprecated version of + <xref linkend="libpq-PQescapeByteaConn"/>. +<synopsis> +unsigned char *PQescapeBytea(const unsigned char *from, + size_t from_length, + size_t *to_length); +</synopsis> + </para> + + <para> + The only difference from <xref linkend="libpq-PQescapeByteaConn"/> is that + <xref linkend="libpq-PQescapeBytea"/> does not take a <structname>PGconn</structname> + parameter. Because of this, <xref linkend="libpq-PQescapeBytea"/> can + only be used safely in client programs that use a single + <productname>PostgreSQL</productname> connection at a time (in this case + it can find out what it needs to know <quote>behind the + scenes</quote>). It <emphasis>might give the wrong results</emphasis> if + used in programs that use multiple database connections (use + <xref linkend="libpq-PQescapeByteaConn"/> in such cases). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQunescapeBytea"> + <term><function>PQunescapeBytea</function><indexterm><primary>PQunescapeBytea</primary></indexterm></term> + + <listitem> + <para> + Converts a string representation of binary data into binary data + — the reverse of <xref linkend="libpq-PQescapeBytea"/>. This + is needed when retrieving <type>bytea</type> data in text format, + but not when retrieving it in binary format. + +<synopsis> +unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length); +</synopsis> + </para> + + <para> + The <parameter>from</parameter> parameter points to a string + such as might be returned by <xref linkend="libpq-PQgetvalue"/> when applied + to a <type>bytea</type> column. <xref linkend="libpq-PQunescapeBytea"/> + converts this string representation into its binary representation. + It returns a pointer to a buffer allocated with + <function>malloc()</function>, or <symbol>NULL</symbol> on error, and puts the size of + the buffer in <parameter>to_length</parameter>. The result must be + freed using <xref linkend="libpq-PQfreemem"/> when it is no longer needed. + </para> + + <para> + This conversion is not exactly the inverse of + <xref linkend="libpq-PQescapeBytea"/>, because the string is not expected + to be <quote>escaped</quote> when received from <xref linkend="libpq-PQgetvalue"/>. + In particular this means there is no need for string quoting considerations, + and so no need for a <structname>PGconn</structname> parameter. + </para> + </listitem> + </varlistentry> + </variablelist> + + </sect2> + + </sect1> + + <sect1 id="libpq-async"> + <title>Asynchronous Command Processing</title> + + <indexterm zone="libpq-async"> + <primary>nonblocking connection</primary> + </indexterm> + + <para> + The <xref linkend="libpq-PQexec"/> function is adequate for submitting + commands in normal, synchronous applications. It has a few + deficiencies, however, that can be of importance to some users: + + <itemizedlist> + <listitem> + <para> + <xref linkend="libpq-PQexec"/> waits for the command to be completed. + The application might have other work to do (such as maintaining a + user interface), in which case it won't want to block waiting for + the response. + </para> + </listitem> + + <listitem> + <para> + Since the execution of the client application is suspended while it + waits for the result, it is hard for the application to decide that + it would like to try to cancel the ongoing command. (It can be done + from a signal handler, but not otherwise.) + </para> + </listitem> + + <listitem> + <para> + <xref linkend="libpq-PQexec"/> can return only one + <structname>PGresult</structname> structure. If the submitted command + string contains multiple <acronym>SQL</acronym> commands, all but + the last <structname>PGresult</structname> are discarded by + <xref linkend="libpq-PQexec"/>. + </para> + </listitem> + + <listitem> + <para> + <xref linkend="libpq-PQexec"/> always collects the command's entire result, + buffering it in a single <structname>PGresult</structname>. While + this simplifies error-handling logic for the application, it can be + impractical for results containing many rows. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + Applications that do not like these limitations can instead use the + underlying functions that <xref linkend="libpq-PQexec"/> is built from: + <xref linkend="libpq-PQsendQuery"/> and <xref linkend="libpq-PQgetResult"/>. + There are also + <xref linkend="libpq-PQsendQueryParams"/>, + <xref linkend="libpq-PQsendPrepare"/>, + <xref linkend="libpq-PQsendQueryPrepared"/>, + <xref linkend="libpq-PQsendDescribePrepared"/>, and + <xref linkend="libpq-PQsendDescribePortal"/>, + which can be used with <xref linkend="libpq-PQgetResult"/> to duplicate + the functionality of + <xref linkend="libpq-PQexecParams"/>, + <xref linkend="libpq-PQprepare"/>, + <xref linkend="libpq-PQexecPrepared"/>, + <xref linkend="libpq-PQdescribePrepared"/>, and + <xref linkend="libpq-PQdescribePortal"/> + respectively. + + <variablelist> + <varlistentry id="libpq-PQsendQuery"> + <term><function>PQsendQuery</function><indexterm><primary>PQsendQuery</primary></indexterm></term> + + <listitem> + <para> + Submits a command to the server without waiting for the result(s). + 1 is returned if the command was successfully dispatched and 0 if + not (in which case, use <xref linkend="libpq-PQerrorMessage"/> to get more + information about the failure). +<synopsis> +int PQsendQuery(PGconn *conn, const char *command); +</synopsis> + + After successfully calling <xref linkend="libpq-PQsendQuery"/>, call + <xref linkend="libpq-PQgetResult"/> one or more times to obtain the + results. <xref linkend="libpq-PQsendQuery"/> cannot be called again + (on the same connection) until <xref linkend="libpq-PQgetResult"/> + has returned a null pointer, indicating that the command is done. + </para> + + <para> + In pipeline mode, this function is disallowed. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsendQueryParams"> + <term><function>PQsendQueryParams</function><indexterm><primary>PQsendQueryParams</primary></indexterm></term> + + <listitem> + <para> + Submits a command and separate parameters to the server without + waiting for the result(s). +<synopsis> +int PQsendQueryParams(PGconn *conn, + const char *command, + int nParams, + const Oid *paramTypes, + const char * const *paramValues, + const int *paramLengths, + const int *paramFormats, + int resultFormat); +</synopsis> + + This is equivalent to <xref linkend="libpq-PQsendQuery"/> except that + query parameters can be specified separately from the query string. + The function's parameters are handled identically to + <xref linkend="libpq-PQexecParams"/>. Like + <xref linkend="libpq-PQexecParams"/>, it allows only one command in the + query string. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsendPrepare"> + <term><function>PQsendPrepare</function><indexterm><primary>PQsendPrepare</primary></indexterm></term> + + <listitem> + <para> + Sends a request to create a prepared statement with the given + parameters, without waiting for completion. +<synopsis> +int PQsendPrepare(PGconn *conn, + const char *stmtName, + const char *query, + int nParams, + const Oid *paramTypes); +</synopsis> + + This is an asynchronous version of <xref linkend="libpq-PQprepare"/>: it + returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call <xref linkend="libpq-PQgetResult"/> to + determine whether the server successfully created the prepared + statement. The function's parameters are handled identically to + <xref linkend="libpq-PQprepare"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsendQueryPrepared"> + <term><function>PQsendQueryPrepared</function><indexterm><primary>PQsendQueryPrepared</primary></indexterm></term> + + <listitem> + <para> + Sends a request to execute a prepared statement with given + parameters, without waiting for the result(s). +<synopsis> +int PQsendQueryPrepared(PGconn *conn, + const char *stmtName, + int nParams, + const char * const *paramValues, + const int *paramLengths, + const int *paramFormats, + int resultFormat); +</synopsis> + + This is similar to <xref linkend="libpq-PQsendQueryParams"/>, but + the command to be executed is specified by naming a + previously-prepared statement, instead of giving a query string. + The function's parameters are handled identically to + <xref linkend="libpq-PQexecPrepared"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsendDescribePrepared"> + <term><function>PQsendDescribePrepared</function><indexterm><primary>PQsendDescribePrepared</primary></indexterm></term> + + <listitem> + <para> + Submits a request to obtain information about the specified + prepared statement, without waiting for completion. +<synopsis> +int PQsendDescribePrepared(PGconn *conn, const char *stmtName); +</synopsis> + + This is an asynchronous version of <xref linkend="libpq-PQdescribePrepared"/>: + it returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call <xref linkend="libpq-PQgetResult"/> to + obtain the results. The function's parameters are handled + identically to <xref linkend="libpq-PQdescribePrepared"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsendDescribePortal"> + <term><function>PQsendDescribePortal</function><indexterm><primary>PQsendDescribePortal</primary></indexterm></term> + + <listitem> + <para> + Submits a request to obtain information about the specified + portal, without waiting for completion. +<synopsis> +int PQsendDescribePortal(PGconn *conn, const char *portalName); +</synopsis> + + This is an asynchronous version of <xref linkend="libpq-PQdescribePortal"/>: + it returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call <xref linkend="libpq-PQgetResult"/> to + obtain the results. The function's parameters are handled + identically to <xref linkend="libpq-PQdescribePortal"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQgetResult"> + <term><function>PQgetResult</function><indexterm><primary>PQgetResult</primary></indexterm></term> + + <listitem> + <para> + Waits for the next result from a prior + <xref linkend="libpq-PQsendQuery"/>, + <xref linkend="libpq-PQsendQueryParams"/>, + <xref linkend="libpq-PQsendPrepare"/>, + <xref linkend="libpq-PQsendQueryPrepared"/>, + <xref linkend="libpq-PQsendDescribePrepared"/>, + <xref linkend="libpq-PQsendDescribePortal"/>, or + <xref linkend="libpq-PQpipelineSync"/> + call, and returns it. + A null pointer is returned when the command is complete and there + will be no more results. +<synopsis> +PGresult *PQgetResult(PGconn *conn); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQgetResult"/> must be called repeatedly until + it returns a null pointer, indicating that the command is done. + (If called when no command is active, + <xref linkend="libpq-PQgetResult"/> will just return a null pointer + at once.) Each non-null result from + <xref linkend="libpq-PQgetResult"/> should be processed using the + same <structname>PGresult</structname> accessor functions previously + described. Don't forget to free each result object with + <xref linkend="libpq-PQclear"/> when done with it. Note that + <xref linkend="libpq-PQgetResult"/> will block only if a command is + active and the necessary response data has not yet been read by + <xref linkend="libpq-PQconsumeInput"/>. + </para> + + <para> + In pipeline mode, <function>PQgetResult</function> will return normally + unless an error occurs; for any subsequent query sent after the one + that caused the error until (and excluding) the next synchronization point, + a special result of type <literal>PGRES_PIPELINE_ABORTED</literal> will + be returned, and a null pointer will be returned after it. + When the pipeline synchronization point is reached, a result of type + <literal>PGRES_PIPELINE_SYNC</literal> will be returned. + The result of the next query after the synchronization point follows + immediately (that is, no null pointer is returned after + the synchronization point.) + </para> + + <note> + <para> + Even when <xref linkend="libpq-PQresultStatus"/> indicates a fatal + error, <xref linkend="libpq-PQgetResult"/> should be called until it + returns a null pointer, to allow <application>libpq</application> to + process the error information completely. + </para> + </note> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + Using <xref linkend="libpq-PQsendQuery"/> and + <xref linkend="libpq-PQgetResult"/> solves one of + <xref linkend="libpq-PQexec"/>'s problems: If a command string contains + multiple <acronym>SQL</acronym> commands, the results of those commands + can be obtained individually. (This allows a simple form of overlapped + processing, by the way: the client can be handling the results of one + command while the server is still working on later queries in the same + command string.) + </para> + + <para> + Another frequently-desired feature that can be obtained with + <xref linkend="libpq-PQsendQuery"/> and <xref linkend="libpq-PQgetResult"/> + is retrieving large query results a row at a time. This is discussed + in <xref linkend="libpq-single-row-mode"/>. + </para> + + <para> + By itself, calling <xref linkend="libpq-PQgetResult"/> + will still cause the client to block until the server completes the + next <acronym>SQL</acronym> command. This can be avoided by proper + use of two more functions: + + <variablelist> + <varlistentry id="libpq-PQconsumeInput"> + <term><function>PQconsumeInput</function><indexterm><primary>PQconsumeInput</primary></indexterm> + </term> + + <listitem> + <para> + If input is available from the server, consume it. +<synopsis> +int PQconsumeInput(PGconn *conn); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQconsumeInput"/> normally returns 1 indicating + <quote>no error</quote>, but returns 0 if there was some kind of + trouble (in which case <xref linkend="libpq-PQerrorMessage"/> can be + consulted). Note that the result does not say whether any input + data was actually collected. After calling + <xref linkend="libpq-PQconsumeInput"/>, the application can check + <xref linkend="libpq-PQisBusy"/> and/or + <function>PQnotifies</function> to see if their state has changed. + </para> + + <para> + <xref linkend="libpq-PQconsumeInput"/> can be called even if the + application is not prepared to deal with a result or notification + just yet. The function will read available data and save it in + a buffer, thereby causing a <function>select()</function> + read-ready indication to go away. The application can thus use + <xref linkend="libpq-PQconsumeInput"/> to clear the + <function>select()</function> condition immediately, and then + examine the results at leisure. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQisBusy"> + <term><function>PQisBusy</function><indexterm><primary>PQisBusy</primary></indexterm></term> + + <listitem> + <para> + Returns 1 if a command is busy, that is, + <xref linkend="libpq-PQgetResult"/> would block waiting for input. + A 0 return indicates that <xref linkend="libpq-PQgetResult"/> can be + called with assurance of not blocking. +<synopsis> +int PQisBusy(PGconn *conn); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQisBusy"/> will not itself attempt to read data + from the server; therefore <xref linkend="libpq-PQconsumeInput"/> + must be invoked first, or the busy state will never end. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + A typical application using these functions will have a main loop that + uses <function>select()</function> or <function>poll()</function> to wait for + all the conditions that it must respond to. One of the conditions + will be input available from the server, which in terms of + <function>select()</function> means readable data on the file + descriptor identified by <xref linkend="libpq-PQsocket"/>. When the main + loop detects input ready, it should call + <xref linkend="libpq-PQconsumeInput"/> to read the input. It can then + call <xref linkend="libpq-PQisBusy"/>, followed by + <xref linkend="libpq-PQgetResult"/> if <xref linkend="libpq-PQisBusy"/> + returns false (0). It can also call <function>PQnotifies</function> + to detect <command>NOTIFY</command> messages (see <xref + linkend="libpq-notify"/>). + </para> + + <para> + A client that uses + <xref linkend="libpq-PQsendQuery"/>/<xref linkend="libpq-PQgetResult"/> + can also attempt to cancel a command that is still being processed + by the server; see <xref linkend="libpq-cancel"/>. But regardless of + the return value of <xref linkend="libpq-PQcancel"/>, the application + must continue with the normal result-reading sequence using + <xref linkend="libpq-PQgetResult"/>. A successful cancellation will + simply cause the command to terminate sooner than it would have + otherwise. + </para> + + <para> + By using the functions described above, it is possible to avoid + blocking while waiting for input from the database server. However, + it is still possible that the application will block waiting to send + output to the server. This is relatively uncommon but can happen if + very long SQL commands or data values are sent. (It is much more + probable if the application sends data via <command>COPY IN</command>, + however.) To prevent this possibility and achieve completely + nonblocking database operation, the following additional functions + can be used. + + <variablelist> + <varlistentry id="libpq-PQsetnonblocking"> + <term><function>PQsetnonblocking</function><indexterm><primary>PQsetnonblocking</primary></indexterm></term> + + <listitem> + <para> + Sets the nonblocking status of the connection. +<synopsis> +int PQsetnonblocking(PGconn *conn, int arg); +</synopsis> + </para> + + <para> + Sets the state of the connection to nonblocking if + <parameter>arg</parameter> is 1, or blocking if + <parameter>arg</parameter> is 0. Returns 0 if OK, -1 if error. + </para> + + <para> + In the nonblocking state, successful calls to + <xref linkend="libpq-PQsendQuery"/>, <xref linkend="libpq-PQputline"/>, + <xref linkend="libpq-PQputnbytes"/>, <xref linkend="libpq-PQputCopyData"/>, + and <xref linkend="libpq-PQendcopy"/> will not block; their changes + are stored in the local output buffer until they are flushed. + Unsuccessful calls will return an error and must be retried. + </para> + + <para> + Note that <xref linkend="libpq-PQexec"/> does not honor nonblocking + mode; if it is called, it will act in blocking fashion anyway. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQisnonblocking"> + <term><function>PQisnonblocking</function><indexterm><primary>PQisnonblocking</primary></indexterm></term> + + <listitem> + <para> + Returns the blocking status of the database connection. +<synopsis> +int PQisnonblocking(const PGconn *conn); +</synopsis> + </para> + + <para> + Returns 1 if the connection is set to nonblocking mode and 0 if + blocking. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQflush"> + <term><function>PQflush</function><indexterm><primary>PQflush</primary></indexterm></term> + + <listitem> + <para> + Attempts to flush any queued output data to the server. Returns + 0 if successful (or if the send queue is empty), -1 if it failed + for some reason, or 1 if it was unable to send all the data in + the send queue yet (this case can only occur if the connection + is nonblocking). +<synopsis> +int PQflush(PGconn *conn); +</synopsis> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + After sending any command or data on a nonblocking connection, call + <xref linkend="libpq-PQflush"/>. If it returns 1, wait for the socket + to become read- or write-ready. If it becomes write-ready, call + <xref linkend="libpq-PQflush"/> again. If it becomes read-ready, call + <xref linkend="libpq-PQconsumeInput"/>, then call + <xref linkend="libpq-PQflush"/> again. Repeat until + <xref linkend="libpq-PQflush"/> returns 0. (It is necessary to check for + read-ready and drain the input with <xref linkend="libpq-PQconsumeInput"/>, + because the server can block trying to send us data, e.g., NOTICE + messages, and won't read our data until we read its.) Once + <xref linkend="libpq-PQflush"/> returns 0, wait for the socket to be + read-ready and then read the response as described above. + </para> + + </sect1> + + <sect1 id="libpq-pipeline-mode"> + <title>Pipeline Mode</title> + + <indexterm zone="libpq-pipeline-mode"> + <primary>libpq</primary> + <secondary>pipeline mode</secondary> + </indexterm> + + <indexterm zone="libpq-pipeline-mode"> + <primary>pipelining</primary> + <secondary>in libpq</secondary> + </indexterm> + + <indexterm zone="libpq-pipeline-mode"> + <primary>batch mode</primary> + <secondary>in libpq</secondary> + </indexterm> + + <para> + <application>libpq</application> pipeline mode allows applications to + send a query without having to read the result of the previously + sent query. Taking advantage of the pipeline mode, a client will wait + less for the server, since multiple queries/results can be + sent/received in a single network transaction. + </para> + + <para> + While pipeline mode provides a significant performance boost, writing + clients using the pipeline mode is more complex because it involves + managing a queue of pending queries and finding which result + corresponds to which query in the queue. + </para> + + <para> + Pipeline mode also generally consumes more memory on both the client and server, + though careful and aggressive management of the send/receive queue can mitigate + this. This applies whether or not the connection is in blocking or non-blocking + mode. + </para> + + <para> + While <application>libpq</application>'s pipeline API was introduced in + <productname>PostgreSQL</productname> 14, it is a client-side feature + which doesn't require special server support and works on any server + that supports the v3 extended query protocol. For more information see + <xref linkend="protocol-flow-pipelining"/>. + </para> + + <sect2 id="libpq-pipeline-using"> + <title>Using Pipeline Mode</title> + + <para> + To issue pipelines, the application must switch the connection + into pipeline mode, + which is done with <xref linkend="libpq-PQenterPipelineMode"/>. + <xref linkend="libpq-PQpipelineStatus"/> can be used + to test whether pipeline mode is active. + In pipeline mode, only <link linkend="libpq-async">asynchronous operations</link> + that utilize the extended query protocol + are permitted, command strings containing multiple SQL commands are + disallowed, and so is <literal>COPY</literal>. + Using synchronous command execution functions + such as <function>PQfn</function>, + <function>PQexec</function>, + <function>PQexecParams</function>, + <function>PQprepare</function>, + <function>PQexecPrepared</function>, + <function>PQdescribePrepared</function>, + <function>PQdescribePortal</function>, + is an error condition. + <function>PQsendQuery</function> is + also disallowed, because it uses the simple query protocol. + Once all dispatched commands have had their results processed, and + the end pipeline result has been consumed, the application may return + to non-pipelined mode with <xref linkend="libpq-PQexitPipelineMode"/>. + </para> + + <note> + <para> + It is best to use pipeline mode with <application>libpq</application> in + <link linkend="libpq-PQsetnonblocking">non-blocking mode</link>. If used + in blocking mode it is possible for a client/server deadlock to occur. + <footnote> + <para> + The client will block trying to send queries to the server, but the + server will block trying to send results to the client from queries + it has already processed. This only occurs when the client sends + enough queries to fill both its output buffer and the server's receive + buffer before it switches to processing input from the server, + but it's hard to predict exactly when that will happen. + </para> + </footnote> + </para> + </note> + + <sect3 id="libpq-pipeline-sending"> + <title>Issuing Queries</title> + + <para> + After entering pipeline mode, the application dispatches requests using + <xref linkend="libpq-PQsendQueryParams"/> + or its prepared-query sibling + <xref linkend="libpq-PQsendQueryPrepared"/>. + These requests are queued on the client-side until flushed to the server; + this occurs when <xref linkend="libpq-PQpipelineSync"/> is used to + establish a synchronization point in the pipeline, + or when <xref linkend="libpq-PQflush"/> is called. + The functions <xref linkend="libpq-PQsendPrepare"/>, + <xref linkend="libpq-PQsendDescribePrepared"/>, and + <xref linkend="libpq-PQsendDescribePortal"/> also work in pipeline mode. + Result processing is described below. + </para> + + <para> + The server executes statements, and returns results, in the order the + client sends them. The server will begin executing the commands in the + pipeline immediately, not waiting for the end of the pipeline. + Note that results are buffered on the server side; the server flushes + that buffer when a synchronization point is established with + <function>PQpipelineSync</function>, or when + <function>PQsendFlushRequest</function> is called. + If any statement encounters an error, the server aborts the current + transaction and does not execute any subsequent command in the queue + until the next synchronization point; + a <literal>PGRES_PIPELINE_ABORTED</literal> result is produced for + each such command. + (This remains true even if the commands in the pipeline would rollback + the transaction.) + Query processing resumes after the synchronization point. + </para> + + <para> + It's fine for one operation to depend on the results of a + prior one; for example, one query may define a table that the next + query in the same pipeline uses. Similarly, an application may + create a named prepared statement and execute it with later + statements in the same pipeline. + </para> + </sect3> + + <sect3 id="libpq-pipeline-results"> + <title>Processing Results</title> + + <para> + To process the result of one query in a pipeline, the application calls + <function>PQgetResult</function> repeatedly and handles each result + until <function>PQgetResult</function> returns null. + The result from the next query in the pipeline may then be retrieved using + <function>PQgetResult</function> again and the cycle repeated. + The application handles individual statement results as normal. + When the results of all the queries in the pipeline have been + returned, <function>PQgetResult</function> returns a result + containing the status value <literal>PGRES_PIPELINE_SYNC</literal> + </para> + + <para> + The client may choose to defer result processing until the complete + pipeline has been sent, or interleave that with sending further + queries in the pipeline; see <xref linkend="libpq-pipeline-interleave"/>. + </para> + + <para> + To enter single-row mode, call <function>PQsetSingleRowMode</function> + before retrieving results with <function>PQgetResult</function>. + This mode selection is effective only for the query currently + being processed. For more information on the use of + <function>PQsetSingleRowMode</function>, + refer to <xref linkend="libpq-single-row-mode"/>. + </para> + + <para> + <function>PQgetResult</function> behaves the same as for normal + asynchronous processing except that it may contain the new + <type>PGresult</type> types <literal>PGRES_PIPELINE_SYNC</literal> + and <literal>PGRES_PIPELINE_ABORTED</literal>. + <literal>PGRES_PIPELINE_SYNC</literal> is reported exactly once for each + <function>PQpipelineSync</function> at the corresponding point + in the pipeline. + <literal>PGRES_PIPELINE_ABORTED</literal> is emitted in place of a normal + query result for the first error and all subsequent results + until the next <literal>PGRES_PIPELINE_SYNC</literal>; + see <xref linkend="libpq-pipeline-errors"/>. + </para> + + <para> + <function>PQisBusy</function>, <function>PQconsumeInput</function>, etc + operate as normal when processing pipeline results. In particular, + a call to <function>PQisBusy</function> in the middle of a pipeline + returns 0 if the results for all the queries issued so far have been + consumed. + </para> + + <para> + <application>libpq</application> does not provide any information to the + application about the query currently being processed (except that + <function>PQgetResult</function> returns null to indicate that we start + returning the results of next query). The application must keep track + of the order in which it sent queries, to associate them with their + corresponding results. + Applications will typically use a state machine or a FIFO queue for this. + </para> + + </sect3> + + <sect3 id="libpq-pipeline-errors"> + <title>Error Handling</title> + + <para> + From the client's perspective, after <function>PQresultStatus</function> + returns <literal>PGRES_FATAL_ERROR</literal>, + the pipeline is flagged as aborted. + <function>PQresultStatus</function> will report a + <literal>PGRES_PIPELINE_ABORTED</literal> result for each remaining queued + operation in an aborted pipeline. The result for + <function>PQpipelineSync</function> is reported as + <literal>PGRES_PIPELINE_SYNC</literal> to signal the end of the aborted pipeline + and resumption of normal result processing. + </para> + + <para> + The client <emphasis>must</emphasis> process results with + <function>PQgetResult</function> during error recovery. + </para> + + <para> + If the pipeline used an implicit transaction, then operations that have + already executed are rolled back and operations that were queued to follow + the failed operation are skipped entirely. The same behavior holds if the + pipeline starts and commits a single explicit transaction (i.e. the first + statement is <literal>BEGIN</literal> and the last is + <literal>COMMIT</literal>) except that the session remains in an aborted + transaction state at the end of the pipeline. If a pipeline contains + <emphasis>multiple explicit transactions</emphasis>, all transactions that + committed prior to the error remain committed, the currently in-progress + transaction is aborted, and all subsequent operations are skipped completely, + including subsequent transactions. If a pipeline synchronization point + occurs with an explicit transaction block in aborted state, the next pipeline + will become aborted immediately unless the next command puts the transaction + in normal mode with <command>ROLLBACK</command>. + </para> + + <note> + <para> + The client must not assume that work is committed when it + <emphasis>sends</emphasis> a <literal>COMMIT</literal> — only when the + corresponding result is received to confirm the commit is complete. + Because errors arrive asynchronously, the application needs to be able to + restart from the last <emphasis>received</emphasis> committed change and + resend work done after that point if something goes wrong. + </para> + </note> + </sect3> + + <sect3 id="libpq-pipeline-interleave"> + <title>Interleaving Result Processing and Query Dispatch</title> + + <para> + To avoid deadlocks on large pipelines the client should be structured + around a non-blocking event loop using operating system facilities + such as <function>select</function>, <function>poll</function>, + <function>WaitForMultipleObjectEx</function>, etc. + </para> + + <para> + The client application should generally maintain a queue of work + remaining to be dispatched and a queue of work that has been dispatched + but not yet had its results processed. When the socket is writable + it should dispatch more work. When the socket is readable it should + read results and process them, matching them up to the next entry in + its corresponding results queue. Based on available memory, results from the + socket should be read frequently: there's no need to wait until the + pipeline end to read the results. Pipelines should be scoped to logical + units of work, usually (but not necessarily) one transaction per pipeline. + There's no need to exit pipeline mode and re-enter it between pipelines, + or to wait for one pipeline to finish before sending the next. + </para> + + <para> + An example using <function>select()</function> and a simple state + machine to track sent and received work is in + <filename>src/test/modules/libpq_pipeline/libpq_pipeline.c</filename> + in the PostgreSQL source distribution. + </para> + </sect3> + </sect2> + + <sect2 id="libpq-pipeline-functions"> + <title>Functions Associated with Pipeline Mode</title> + + <variablelist> + + <varlistentry id="libpq-PQpipelineStatus"> + <term><function>PQpipelineStatus</function><indexterm><primary>PQpipelineStatus</primary></indexterm></term> + + <listitem> + <para> + Returns the current pipeline mode status of the + <application>libpq</application> connection. +<synopsis> +PGpipelineStatus PQpipelineStatus(const PGconn *conn); +</synopsis> + </para> + + <para> + <function>PQpipelineStatus</function> can return one of the following values: + + <variablelist> + <varlistentry> + <term> + <literal>PQ_PIPELINE_ON</literal> + </term> + <listitem> + <para> + The <application>libpq</application> connection is in + pipeline mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PQ_PIPELINE_OFF</literal> + </term> + <listitem> + <para> + The <application>libpq</application> connection is + <emphasis>not</emphasis> in pipeline mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>PQ_PIPELINE_ABORTED</literal> + </term> + <listitem> + <para> + The <application>libpq</application> connection is in pipeline + mode and an error occurred while processing the current pipeline. + The aborted flag is cleared when <function>PQgetResult</function> + returns a result of type <literal>PGRES_PIPELINE_SYNC</literal>. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQenterPipelineMode"> + <term><function>PQenterPipelineMode</function><indexterm><primary>PQenterPipelineMode</primary></indexterm></term> + + <listitem> + <para> + Causes a connection to enter pipeline mode if it is currently idle or + already in pipeline mode. + +<synopsis> +int PQenterPipelineMode(PGconn *conn); +</synopsis> + + </para> + <para> + Returns 1 for success. + Returns 0 and has no effect if the connection is not currently + idle, i.e., it has a result ready, or it is waiting for more + input from the server, etc. + This function does not actually send anything to the server, + it just changes the <application>libpq</application> connection + state. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQexitPipelineMode"> + <term><function>PQexitPipelineMode</function><indexterm><primary>PQexitPipelineMode</primary></indexterm></term> + + <listitem> + <para> + Causes a connection to exit pipeline mode if it is currently in pipeline mode + with an empty queue and no pending results. +<synopsis> +int PQexitPipelineMode(PGconn *conn); +</synopsis> + </para> + <para> + Returns 1 for success. Returns 1 and takes no action if not in + pipeline mode. If the current statement isn't finished processing, + or <function>PQgetResult</function> has not been called to collect + results from all previously sent query, returns 0 (in which case, + use <xref linkend="libpq-PQerrorMessage"/> to get more information + about the failure). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQpipelineSync"> + <term><function>PQpipelineSync</function><indexterm><primary>PQpipelineSync</primary></indexterm></term> + + <listitem> + <para> + Marks a synchronization point in a pipeline by sending a + <link linkend="protocol-flow-ext-query">sync message</link> + and flushing the send buffer. This serves as + the delimiter of an implicit transaction and an error recovery + point; see <xref linkend="libpq-pipeline-errors"/>. + +<synopsis> +int PQpipelineSync(PGconn *conn); +</synopsis> + </para> + <para> + Returns 1 for success. Returns 0 if the connection is not in + pipeline mode or sending a + <link linkend="protocol-flow-ext-query">sync message</link> + failed. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsendFlushRequest"> + <term><function>PQsendFlushRequest</function><indexterm><primary>PQsendFlushRequest</primary></indexterm></term> + + <listitem> + <para> + Sends a request for the server to flush its output buffer. +<synopsis> +int PQsendFlushRequest(PGconn *conn); +</synopsis> + </para> + + <para> + Returns 1 for success. Returns 0 on any failure. + </para> + <para> + The server flushes its output buffer automatically as a result of + <function>PQpipelineSync</function> being called, or + on any request when not in pipeline mode; this function is useful + to cause the server to flush its output buffer in pipeline mode + without establishing a synchronization point. + Note that the request is not itself flushed to the server automatically; + use <function>PQflush</function> if necessary. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="libpq-pipeline-tips"> + <title>When to Use Pipeline Mode</title> + + <para> + Much like asynchronous query mode, there is no meaningful performance + overhead when using pipeline mode. It increases client application complexity, + and extra caution is required to prevent client/server deadlocks, but + pipeline mode can offer considerable performance improvements, in exchange for + increased memory usage from leaving state around longer. + </para> + + <para> + Pipeline mode is most useful when the server is distant, i.e., network latency + (<quote>ping time</quote>) is high, and also when many small operations + are being performed in rapid succession. There is usually less benefit + in using pipelined commands when each query takes many multiples of the client/server + round-trip time to execute. A 100-statement operation run on a server + 300 ms round-trip-time away would take 30 seconds in network latency alone + without pipelining; with pipelining it may spend as little as 0.3 s waiting for + results from the server. + </para> + + <para> + Use pipelined commands when your application does lots of small + <literal>INSERT</literal>, <literal>UPDATE</literal> and + <literal>DELETE</literal> operations that can't easily be transformed + into operations on sets, or into a <literal>COPY</literal> operation. + </para> + + <para> + Pipeline mode is not useful when information from one operation is required by + the client to produce the next operation. In such cases, the client + would have to introduce a synchronization point and wait for a full client/server + round-trip to get the results it needs. However, it's often possible to + adjust the client design to exchange the required information server-side. + Read-modify-write cycles are especially good candidates; for example: +<programlisting> +BEGIN; +SELECT x FROM mytable WHERE id = 42 FOR UPDATE; +-- result: x=2 +-- client adds 1 to x: +UPDATE mytable SET x = 3 WHERE id = 42; +COMMIT; +</programlisting> + could be much more efficiently done with: +<programlisting> +UPDATE mytable SET x = x + 1 WHERE id = 42; +</programlisting> + </para> + + <para> + Pipelining is less useful, and more complex, when a single pipeline contains + multiple transactions (see <xref linkend="libpq-pipeline-errors"/>). + </para> + </sect2> + </sect1> + + <sect1 id="libpq-single-row-mode"> + <title>Retrieving Query Results Row-by-Row</title> + + <indexterm zone="libpq-single-row-mode"> + <primary>libpq</primary> + <secondary>single-row mode</secondary> + </indexterm> + + <para> + Ordinarily, <application>libpq</application> collects an SQL command's + entire result and returns it to the application as a single + <structname>PGresult</structname>. This can be unworkable for commands + that return a large number of rows. For such cases, applications can use + <xref linkend="libpq-PQsendQuery"/> and <xref linkend="libpq-PQgetResult"/> in + <firstterm>single-row mode</firstterm>. In this mode, the result row(s) are + returned to the application one at a time, as they are received from the + server. + </para> + + <para> + To enter single-row mode, call <xref linkend="libpq-PQsetSingleRowMode"/> + immediately after a successful call of <xref linkend="libpq-PQsendQuery"/> + (or a sibling function). This mode selection is effective only for the + currently executing query. Then call <xref linkend="libpq-PQgetResult"/> + repeatedly, until it returns null, as documented in <xref + linkend="libpq-async"/>. If the query returns any rows, they are returned + as individual <structname>PGresult</structname> objects, which look like + normal query results except for having status code + <literal>PGRES_SINGLE_TUPLE</literal> instead of + <literal>PGRES_TUPLES_OK</literal>. After the last row, or immediately if + the query returns zero rows, a zero-row object with status + <literal>PGRES_TUPLES_OK</literal> is returned; this is the signal that no + more rows will arrive. (But note that it is still necessary to continue + calling <xref linkend="libpq-PQgetResult"/> until it returns null.) All of + these <structname>PGresult</structname> objects will contain the same row + description data (column names, types, etc.) that an ordinary + <structname>PGresult</structname> object for the query would have. + Each object should be freed with <xref linkend="libpq-PQclear"/> as usual. + </para> + + <para> + When using pipeline mode, single-row mode needs to be activated for each + query in the pipeline before retrieving results for that query + with <function>PQgetResult</function>. + See <xref linkend="libpq-pipeline-mode"/> for more information. + </para> + + <para> + <variablelist> + <varlistentry id="libpq-PQsetSingleRowMode"> + <term><function>PQsetSingleRowMode</function><indexterm><primary>PQsetSingleRowMode</primary></indexterm></term> + + <listitem> + <para> + Select single-row mode for the currently-executing query. + +<synopsis> +int PQsetSingleRowMode(PGconn *conn); +</synopsis> + </para> + + <para> + This function can only be called immediately after + <xref linkend="libpq-PQsendQuery"/> or one of its sibling functions, + before any other operation on the connection such as + <xref linkend="libpq-PQconsumeInput"/> or + <xref linkend="libpq-PQgetResult"/>. If called at the correct time, + the function activates single-row mode for the current query and + returns 1. Otherwise the mode stays unchanged and the function + returns 0. In any case, the mode reverts to normal after + completion of the current query. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <caution> + <para> + While processing a query, the server may return some rows and then + encounter an error, causing the query to be aborted. Ordinarily, + <application>libpq</application> discards any such rows and reports only the + error. But in single-row mode, those rows will have already been + returned to the application. Hence, the application will see some + <literal>PGRES_SINGLE_TUPLE</literal> <structname>PGresult</structname> + objects followed by a <literal>PGRES_FATAL_ERROR</literal> object. For + proper transactional behavior, the application must be designed to + discard or undo whatever has been done with the previously-processed + rows, if the query ultimately fails. + </para> + </caution> + + </sect1> + + <sect1 id="libpq-cancel"> + <title>Canceling Queries in Progress</title> + + <indexterm zone="libpq-cancel"> + <primary>canceling</primary> + <secondary>SQL command</secondary> + </indexterm> + + <para> + A client application can request cancellation of a command that is + still being processed by the server, using the functions described in + this section. + + <variablelist> + <varlistentry id="libpq-PQgetCancel"> + <term><function>PQgetCancel</function><indexterm><primary>PQgetCancel</primary></indexterm></term> + + <listitem> + <para> + Creates a data structure containing the information needed to cancel + a command issued through a particular database connection. +<synopsis> +PGcancel *PQgetCancel(PGconn *conn); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQgetCancel"/> creates a + <structname>PGcancel</structname><indexterm><primary>PGcancel</primary></indexterm> object + given a <structname>PGconn</structname> connection object. It will return + <symbol>NULL</symbol> if the given <parameter>conn</parameter> is <symbol>NULL</symbol> or an invalid + connection. The <structname>PGcancel</structname> object is an opaque + structure that is not meant to be accessed directly by the + application; it can only be passed to <xref linkend="libpq-PQcancel"/> + or <xref linkend="libpq-PQfreeCancel"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQfreeCancel"> + <term><function>PQfreeCancel</function><indexterm><primary>PQfreeCancel</primary></indexterm></term> + + <listitem> + <para> + Frees a data structure created by <xref linkend="libpq-PQgetCancel"/>. +<synopsis> +void PQfreeCancel(PGcancel *cancel); +</synopsis> + </para> + + <para> + <xref linkend="libpq-PQfreeCancel"/> frees a data object previously created + by <xref linkend="libpq-PQgetCancel"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQcancel"> + <term><function>PQcancel</function><indexterm><primary>PQcancel</primary></indexterm></term> + + <listitem> + <para> + Requests that the server abandon processing of the current command. +<synopsis> +int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); +</synopsis> + </para> + + <para> + The return value is 1 if the cancel request was successfully + dispatched and 0 if not. If not, <parameter>errbuf</parameter> is filled + with an explanatory error message. <parameter>errbuf</parameter> + must be a char array of size <parameter>errbufsize</parameter> (the + recommended size is 256 bytes). + </para> + + <para> + Successful dispatch is no guarantee that the request will have + any effect, however. If the cancellation is effective, the current + command will terminate early and return an error result. If the + cancellation fails (say, because the server was already done + processing the command), then there will be no visible result at + all. + </para> + + <para> + <xref linkend="libpq-PQcancel"/> can safely be invoked from a signal + handler, if the <parameter>errbuf</parameter> is a local variable in the + signal handler. The <structname>PGcancel</structname> object is read-only + as far as <xref linkend="libpq-PQcancel"/> is concerned, so it can + also be invoked from a thread that is separate from the one + manipulating the <structname>PGconn</structname> object. + </para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry id="libpq-PQrequestCancel"> + <term><function>PQrequestCancel</function><indexterm><primary>PQrequestCancel</primary></indexterm></term> + + <listitem> + <para> + <xref linkend="libpq-PQrequestCancel"/> is a deprecated variant of + <xref linkend="libpq-PQcancel"/>. +<synopsis> +int PQrequestCancel(PGconn *conn); +</synopsis> + </para> + + <para> + Requests that the server abandon processing of the current + command. It operates directly on the + <structname>PGconn</structname> object, and in case of failure stores the + error message in the <structname>PGconn</structname> object (whence it can + be retrieved by <xref linkend="libpq-PQerrorMessage"/>). Although + the functionality is the same, this approach is not safe within + multiple-thread programs or signal handlers, since it is possible + that overwriting the <structname>PGconn</structname>'s error message will + mess up the operation currently in progress on the connection. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + </sect1> + + <sect1 id="libpq-fastpath"> + <title>The Fast-Path Interface</title> + + <indexterm zone="libpq-fastpath"> + <primary>fast path</primary> + </indexterm> + + <para> + <productname>PostgreSQL</productname> provides a fast-path interface + to send simple function calls to the server. + </para> + + <tip> + <para> + This interface is somewhat obsolete, as one can achieve similar + performance and greater functionality by setting up a prepared + statement to define the function call. Then, executing the statement + with binary transmission of parameters and results substitutes for a + fast-path function call. + </para> + </tip> + + <para> + The function <function id="libpq-PQfn">PQfn</function><indexterm><primary>PQfn</primary></indexterm> + requests execution of a server function via the fast-path interface: +<synopsis> +PGresult *PQfn(PGconn *conn, + int fnid, + int *result_buf, + int *result_len, + int result_is_int, + const PQArgBlock *args, + int nargs); + +typedef struct +{ + int len; + int isint; + union + { + int *ptr; + int integer; + } u; +} PQArgBlock; +</synopsis> + </para> + + <para> + The <parameter>fnid</parameter> argument is the OID of the function to be + executed. <parameter>args</parameter> and <parameter>nargs</parameter> define the + parameters to be passed to the function; they must match the declared + function argument list. When the <parameter>isint</parameter> field of a + parameter structure is true, the <parameter>u.integer</parameter> value is sent + to the server as an integer of the indicated length (this must be + 2 or 4 bytes); proper byte-swapping occurs. When <parameter>isint</parameter> + is false, the indicated number of bytes at <parameter>*u.ptr</parameter> are + sent with no processing; the data must be in the format expected by + the server for binary transmission of the function's argument data + type. (The declaration of <parameter>u.ptr</parameter> as being of + type <type>int *</type> is historical; it would be better to consider + it <type>void *</type>.) + <parameter>result_buf</parameter> points to the buffer in which to place + the function's return value. The caller must have allocated sufficient + space to store the return value. (There is no check!) The actual result + length in bytes will be returned in the integer pointed to by + <parameter>result_len</parameter>. If a 2- or 4-byte integer result + is expected, set <parameter>result_is_int</parameter> to 1, otherwise + set it to 0. Setting <parameter>result_is_int</parameter> to 1 causes + <application>libpq</application> to byte-swap the value if necessary, so that it + is delivered as a proper <type>int</type> value for the client machine; + note that a 4-byte integer is delivered into <parameter>*result_buf</parameter> + for either allowed result size. + When <parameter>result_is_int</parameter> is 0, the binary-format byte string + sent by the server is returned unmodified. (In this case it's better + to consider <parameter>result_buf</parameter> as being of + type <type>void *</type>.) + </para> + + <para> + <function>PQfn</function> always returns a valid + <structname>PGresult</structname> pointer, with + status <literal>PGRES_COMMAND_OK</literal> for success + or <literal>PGRES_FATAL_ERROR</literal> if some problem was encountered. + The result status should be + checked before the result is used. The caller is responsible for + freeing the <structname>PGresult</structname> with + <xref linkend="libpq-PQclear"/> when it is no longer needed. + </para> + + <para> + To pass a NULL argument to the function, set + the <parameter>len</parameter> field of that parameter structure + to <literal>-1</literal>; the <parameter>isint</parameter> + and <parameter>u</parameter> fields are then irrelevant. + </para> + + <para> + If the function returns NULL, <parameter>*result_len</parameter> is set + to <literal>-1</literal>, and <parameter>*result_buf</parameter> is not + modified. + </para> + + <para> + Note that it is not possible to handle set-valued results when using + this interface. Also, the function must be a plain function, not an + aggregate, window function, or procedure. + </para> + + </sect1> + + <sect1 id="libpq-notify"> + <title>Asynchronous Notification</title> + + <indexterm zone="libpq-notify"> + <primary>NOTIFY</primary> + <secondary>in libpq</secondary> + </indexterm> + + <para> + <productname>PostgreSQL</productname> offers asynchronous notification + via the <command>LISTEN</command> and <command>NOTIFY</command> + commands. A client session registers its interest in a particular + notification channel with the <command>LISTEN</command> command (and + can stop listening with the <command>UNLISTEN</command> command). All + sessions listening on a particular channel will be notified + asynchronously when a <command>NOTIFY</command> command with that + channel name is executed by any session. A <quote>payload</quote> string can + be passed to communicate additional data to the listeners. + </para> + + <para> + <application>libpq</application> applications submit + <command>LISTEN</command>, <command>UNLISTEN</command>, + and <command>NOTIFY</command> commands as + ordinary SQL commands. The arrival of <command>NOTIFY</command> + messages can subsequently be detected by calling + <function id="libpq-PQnotifies">PQnotifies</function>.<indexterm><primary>PQnotifies</primary></indexterm> + </para> + + <para> + The function <function>PQnotifies</function> returns the next notification + from a list of unhandled notification messages received from the server. + It returns a null pointer if there are no pending notifications. Once a + notification is returned from <function>PQnotifies</function>, it is considered + handled and will be removed from the list of notifications. + +<synopsis> +PGnotify *PQnotifies(PGconn *conn); + +typedef struct pgNotify +{ + char *relname; /* notification channel name */ + int be_pid; /* process ID of notifying server process */ + char *extra; /* notification payload string */ +} PGnotify; +</synopsis> + + After processing a <structname>PGnotify</structname> object returned + by <function>PQnotifies</function>, be sure to free it with + <xref linkend="libpq-PQfreemem"/>. It is sufficient to free the + <structname>PGnotify</structname> pointer; the + <structfield>relname</structfield> and <structfield>extra</structfield> + fields do not represent separate allocations. (The names of these fields + are historical; in particular, channel names need not have anything to + do with relation names.) + </para> + + <para> + <xref linkend="libpq-example-2"/> gives a sample program that illustrates + the use of asynchronous notification. + </para> + + <para> + <function>PQnotifies</function> does not actually read data from the + server; it just returns messages previously absorbed by another + <application>libpq</application> function. In ancient releases of + <application>libpq</application>, the only way to ensure timely receipt + of <command>NOTIFY</command> messages was to constantly submit commands, even + empty ones, and then check <function>PQnotifies</function> after each + <xref linkend="libpq-PQexec"/>. While this still works, it is deprecated + as a waste of processing power. + </para> + + <para> + A better way to check for <command>NOTIFY</command> messages when you have no + useful commands to execute is to call + <xref linkend="libpq-PQconsumeInput"/>, then check + <function>PQnotifies</function>. You can use + <function>select()</function> to wait for data to arrive from the + server, thereby using no <acronym>CPU</acronym> power unless there is + something to do. (See <xref linkend="libpq-PQsocket"/> to obtain the file + descriptor number to use with <function>select()</function>.) Note that + this will work OK whether you submit commands with + <xref linkend="libpq-PQsendQuery"/>/<xref linkend="libpq-PQgetResult"/> or + simply use <xref linkend="libpq-PQexec"/>. You should, however, remember + to check <function>PQnotifies</function> after each + <xref linkend="libpq-PQgetResult"/> or <xref linkend="libpq-PQexec"/>, to + see if any notifications came in during the processing of the command. + </para> + + </sect1> + + <sect1 id="libpq-copy"> + <title>Functions Associated with the <command>COPY</command> Command</title> + + <indexterm zone="libpq-copy"> + <primary>COPY</primary> + <secondary>with libpq</secondary> + </indexterm> + + <para> + The <command>COPY</command> command in + <productname>PostgreSQL</productname> has options to read from or write + to the network connection used by <application>libpq</application>. + The functions described in this section allow applications to take + advantage of this capability by supplying or consuming copied data. + </para> + + <para> + The overall process is that the application first issues the SQL + <command>COPY</command> command via <xref linkend="libpq-PQexec"/> or one + of the equivalent functions. The response to this (if there is no + error in the command) will be a <structname>PGresult</structname> object bearing + a status code of <literal>PGRES_COPY_OUT</literal> or + <literal>PGRES_COPY_IN</literal> (depending on the specified copy + direction). The application should then use the functions of this + section to receive or transmit data rows. When the data transfer is + complete, another <structname>PGresult</structname> object is returned to indicate + success or failure of the transfer. Its status will be + <literal>PGRES_COMMAND_OK</literal> for success or + <literal>PGRES_FATAL_ERROR</literal> if some problem was encountered. + At this point further SQL commands can be issued via + <xref linkend="libpq-PQexec"/>. (It is not possible to execute other SQL + commands using the same connection while the <command>COPY</command> + operation is in progress.) + </para> + + <para> + If a <command>COPY</command> command is issued via + <xref linkend="libpq-PQexec"/> in a string that could contain additional + commands, the application must continue fetching results via + <xref linkend="libpq-PQgetResult"/> after completing the <command>COPY</command> + sequence. Only when <xref linkend="libpq-PQgetResult"/> returns + <symbol>NULL</symbol> is it certain that the <xref linkend="libpq-PQexec"/> + command string is done and it is safe to issue more commands. + </para> + + <para> + The functions of this section should be executed only after obtaining + a result status of <literal>PGRES_COPY_OUT</literal> or + <literal>PGRES_COPY_IN</literal> from <xref linkend="libpq-PQexec"/> or + <xref linkend="libpq-PQgetResult"/>. + </para> + + <para> + A <structname>PGresult</structname> object bearing one of these status values + carries some additional data about the <command>COPY</command> operation + that is starting. This additional data is available using functions + that are also used in connection with query results: + + <variablelist> + <varlistentry id="libpq-PQnfields-1"> + <term><function>PQnfields</function><indexterm + ><primary>PQnfields</primary><secondary>with COPY</secondary></indexterm></term> + + <listitem> + <para> + Returns the number of columns (fields) to be copied. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQbinaryTuples-1"> + <term><function>PQbinaryTuples</function><indexterm + ><primary>PQbinaryTuples</primary><secondary>with COPY</secondary></indexterm></term> + + <listitem> + <para> + 0 indicates the overall copy format is textual (rows separated by + newlines, columns separated by separator characters, etc.). 1 + indicates the overall copy format is binary. See <xref + linkend="sql-copy"/> for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQfformat-1"> + <term><function>PQfformat</function><indexterm + ><primary>PQfformat</primary><secondary>with COPY</secondary></indexterm></term> + + <listitem> + <para> + Returns the format code (0 for text, 1 for binary) associated with + each column of the copy operation. The per-column format codes + will always be zero when the overall copy format is textual, but + the binary format can support both text and binary columns. + (However, as of the current implementation of <command>COPY</command>, + only binary columns appear in a binary copy; so the per-column + formats always match the overall format at present.) + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <sect2 id="libpq-copy-send"> + <title>Functions for Sending <command>COPY</command> Data</title> + + <para> + These functions are used to send data during <literal>COPY FROM + STDIN</literal>. They will fail if called when the connection is not in + <literal>COPY_IN</literal> state. + </para> + + <variablelist> + <varlistentry id="libpq-PQputCopyData"> + <term><function>PQputCopyData</function><indexterm><primary>PQputCopyData</primary></indexterm></term> + + <listitem> + <para> + Sends data to the server during <literal>COPY_IN</literal> state. +<synopsis> +int PQputCopyData(PGconn *conn, + const char *buffer, + int nbytes); +</synopsis> + </para> + + <para> + Transmits the <command>COPY</command> data in the specified + <parameter>buffer</parameter>, of length <parameter>nbytes</parameter>, to the server. + The result is 1 if the data was queued, zero if it was not queued + because of full buffers (this will only happen in nonblocking mode), + or -1 if an error occurred. + (Use <xref linkend="libpq-PQerrorMessage"/> to retrieve details if + the return value is -1. If the value is zero, wait for write-ready + and try again.) + </para> + + <para> + The application can divide the <command>COPY</command> data stream + into buffer loads of any convenient size. Buffer-load boundaries + have no semantic significance when sending. The contents of the + data stream must match the data format expected by the + <command>COPY</command> command; see <xref linkend="sql-copy"/> for details. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQputCopyEnd"> + <term><function>PQputCopyEnd</function><indexterm><primary>PQputCopyEnd</primary></indexterm></term> + + <listitem> + <para> + Sends end-of-data indication to the server during <literal>COPY_IN</literal> state. +<synopsis> +int PQputCopyEnd(PGconn *conn, + const char *errormsg); +</synopsis> + </para> + + <para> + Ends the <literal>COPY_IN</literal> operation successfully if + <parameter>errormsg</parameter> is <symbol>NULL</symbol>. If + <parameter>errormsg</parameter> is not <symbol>NULL</symbol> then the + <command>COPY</command> is forced to fail, with the string pointed to by + <parameter>errormsg</parameter> used as the error message. (One should not + assume that this exact error message will come back from the server, + however, as the server might have already failed the + <command>COPY</command> for its own reasons.) + </para> + + <para> + The result is 1 if the termination message was sent; or in + nonblocking mode, this may only indicate that the termination + message was successfully queued. (In nonblocking mode, to be + certain that the data has been sent, you should next wait for + write-ready and call <xref linkend="libpq-PQflush"/>, repeating until it + returns zero.) Zero indicates that the function could not queue + the termination message because of full buffers; this will only + happen in nonblocking mode. (In this case, wait for + write-ready and try the <xref linkend="libpq-PQputCopyEnd"/> call + again.) If a hard error occurs, -1 is returned; you can use + <xref linkend="libpq-PQerrorMessage"/> to retrieve details. + </para> + + <para> + After successfully calling <xref linkend="libpq-PQputCopyEnd"/>, call + <xref linkend="libpq-PQgetResult"/> to obtain the final result status of the + <command>COPY</command> command. One can wait for this result to be + available in the usual way. Then return to normal operation. + </para> + </listitem> + </varlistentry> + </variablelist> + + </sect2> + + <sect2 id="libpq-copy-receive"> + <title>Functions for Receiving <command>COPY</command> Data</title> + + <para> + These functions are used to receive data during <literal>COPY TO + STDOUT</literal>. They will fail if called when the connection is not in + <literal>COPY_OUT</literal> state. + </para> + + <variablelist> + <varlistentry id="libpq-PQgetCopyData"> + <term><function>PQgetCopyData</function><indexterm><primary>PQgetCopyData</primary></indexterm></term> + + <listitem> + <para> + Receives data from the server during <literal>COPY_OUT</literal> state. +<synopsis> +int PQgetCopyData(PGconn *conn, + char **buffer, + int async); +</synopsis> + </para> + + <para> + Attempts to obtain another row of data from the server during a + <command>COPY</command>. Data is always returned one data row at + a time; if only a partial row is available, it is not returned. + Successful return of a data row involves allocating a chunk of + memory to hold the data. The <parameter>buffer</parameter> parameter must + be non-<symbol>NULL</symbol>. <parameter>*buffer</parameter> is set to + point to the allocated memory, or to <symbol>NULL</symbol> in cases + where no buffer is returned. A non-<symbol>NULL</symbol> result + buffer should be freed using <xref linkend="libpq-PQfreemem"/> when no longer + needed. + </para> + + <para> + When a row is successfully returned, the return value is the number + of data bytes in the row (this will always be greater than zero). + The returned string is always null-terminated, though this is + probably only useful for textual <command>COPY</command>. A result + of zero indicates that the <command>COPY</command> is still in + progress, but no row is yet available (this is only possible when + <parameter>async</parameter> is true). A result of -1 indicates that the + <command>COPY</command> is done. A result of -2 indicates that an + error occurred (consult <xref linkend="libpq-PQerrorMessage"/> for the reason). + </para> + + <para> + When <parameter>async</parameter> is true (not zero), + <xref linkend="libpq-PQgetCopyData"/> will not block waiting for input; it + will return zero if the <command>COPY</command> is still in progress + but no complete row is available. (In this case wait for read-ready + and then call <xref linkend="libpq-PQconsumeInput"/> before calling + <xref linkend="libpq-PQgetCopyData"/> again.) When <parameter>async</parameter> is + false (zero), <xref linkend="libpq-PQgetCopyData"/> will block until data is + available or the operation completes. + </para> + + <para> + After <xref linkend="libpq-PQgetCopyData"/> returns -1, call + <xref linkend="libpq-PQgetResult"/> to obtain the final result status of the + <command>COPY</command> command. One can wait for this result to be + available in the usual way. Then return to normal operation. + </para> + </listitem> + </varlistentry> + </variablelist> + + </sect2> + + <sect2 id="libpq-copy-deprecated"> + <title>Obsolete Functions for <command>COPY</command></title> + + <para> + These functions represent older methods of handling <command>COPY</command>. + Although they still work, they are deprecated due to poor error handling, + inconvenient methods of detecting end-of-data, and lack of support for binary + or nonblocking transfers. + </para> + + <variablelist> + <varlistentry id="libpq-PQgetline"> + <term><function>PQgetline</function><indexterm><primary>PQgetline</primary></indexterm></term> + + <listitem> + <para> + Reads a newline-terminated line of characters (transmitted + by the server) into a buffer string of size <parameter>length</parameter>. +<synopsis> +int PQgetline(PGconn *conn, + char *buffer, + int length); +</synopsis> + </para> + + <para> + This function copies up to <parameter>length</parameter>-1 characters into + the buffer and converts the terminating newline into a zero byte. + <xref linkend="libpq-PQgetline"/> returns <symbol>EOF</symbol> at the + end of input, 0 if the entire line has been read, and 1 if the + buffer is full but the terminating newline has not yet been read. + </para> + <para> + Note that the application must check to see if a new line consists + of the two characters <literal>\.</literal>, which indicates + that the server has finished sending the results of the + <command>COPY</command> command. If the application might receive + lines that are more than <parameter>length</parameter>-1 characters long, + care is needed to be sure it recognizes the <literal>\.</literal> + line correctly (and does not, for example, mistake the end of a + long data line for a terminator line). + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQgetlineAsync"> + <term><function>PQgetlineAsync</function><indexterm><primary>PQgetlineAsync</primary></indexterm></term> + + <listitem> + <para> + Reads a row of <command>COPY</command> data (transmitted by the + server) into a buffer without blocking. +<synopsis> +int PQgetlineAsync(PGconn *conn, + char *buffer, + int bufsize); +</synopsis> + </para> + + <para> + This function is similar to <xref linkend="libpq-PQgetline"/>, but it can be used + by applications + that must read <command>COPY</command> data asynchronously, that is, without blocking. + Having issued the <command>COPY</command> command and gotten a <literal>PGRES_COPY_OUT</literal> + response, the + application should call <xref linkend="libpq-PQconsumeInput"/> and + <xref linkend="libpq-PQgetlineAsync"/> until the + end-of-data signal is detected. + </para> + <para> + Unlike <xref linkend="libpq-PQgetline"/>, this function takes + responsibility for detecting end-of-data. + </para> + + <para> + On each call, <xref linkend="libpq-PQgetlineAsync"/> will return data if a + complete data row is available in <application>libpq</application>'s input buffer. + Otherwise, no data is returned until the rest of the row arrives. + The function returns -1 if the end-of-copy-data marker has been recognized, + or 0 if no data is available, or a positive number giving the number of + bytes of data returned. If -1 is returned, the caller must next call + <xref linkend="libpq-PQendcopy"/>, and then return to normal processing. + </para> + + <para> + The data returned will not extend beyond a data-row boundary. If possible + a whole row will be returned at one time. But if the buffer offered by + the caller is too small to hold a row sent by the server, then a partial + data row will be returned. With textual data this can be detected by testing + whether the last returned byte is <literal>\n</literal> or not. (In a binary + <command>COPY</command>, actual parsing of the <command>COPY</command> data format will be needed to make the + equivalent determination.) + The returned string is not null-terminated. (If you want to add a + terminating null, be sure to pass a <parameter>bufsize</parameter> one smaller + than the room actually available.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQputline"> + <term><function>PQputline</function><indexterm><primary>PQputline</primary></indexterm></term> + + <listitem> + <para> + Sends a null-terminated string to the server. Returns 0 if + OK and <symbol>EOF</symbol> if unable to send the string. +<synopsis> +int PQputline(PGconn *conn, + const char *string); +</synopsis> + </para> + + <para> + The <command>COPY</command> data stream sent by a series of calls + to <xref linkend="libpq-PQputline"/> has the same format as that + returned by <xref linkend="libpq-PQgetlineAsync"/>, except that + applications are not obliged to send exactly one data row per + <xref linkend="libpq-PQputline"/> call; it is okay to send a partial + line or multiple lines per call. + </para> + + <note> + <para> + Before <productname>PostgreSQL</productname> protocol 3.0, it was necessary + for the application to explicitly send the two characters + <literal>\.</literal> as a final line to indicate to the server that it had + finished sending <command>COPY</command> data. While this still works, it is deprecated and the + special meaning of <literal>\.</literal> can be expected to be removed in a + future release. It is sufficient to call <xref linkend="libpq-PQendcopy"/> after + having sent the actual data. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQputnbytes"> + <term><function>PQputnbytes</function><indexterm><primary>PQputnbytes</primary></indexterm></term> + + <listitem> + <para> + Sends a non-null-terminated string to the server. Returns + 0 if OK and <symbol>EOF</symbol> if unable to send the string. +<synopsis> +int PQputnbytes(PGconn *conn, + const char *buffer, + int nbytes); +</synopsis> + </para> + + <para> + This is exactly like <xref linkend="libpq-PQputline"/>, except that the data + buffer need not be null-terminated since the number of bytes to send is + specified directly. Use this procedure when sending binary data. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQendcopy"> + <term><function>PQendcopy</function><indexterm><primary>PQendcopy</primary></indexterm></term> + + <listitem> + <para> + Synchronizes with the server. +<synopsis> +int PQendcopy(PGconn *conn); +</synopsis> + This function waits until the server has finished the copying. + It should either be issued when the last string has been sent + to the server using <xref linkend="libpq-PQputline"/> or when the + last string has been received from the server using + <function>PQgetline</function>. It must be issued or the server + will get <quote>out of sync</quote> with the client. Upon return + from this function, the server is ready to receive the next SQL + command. The return value is 0 on successful completion, + nonzero otherwise. (Use <xref linkend="libpq-PQerrorMessage"/> to + retrieve details if the return value is nonzero.) + </para> + + <para> + When using <xref linkend="libpq-PQgetResult"/>, the application should + respond to a <literal>PGRES_COPY_OUT</literal> result by executing + <xref linkend="libpq-PQgetline"/> repeatedly, followed by + <xref linkend="libpq-PQendcopy"/> after the terminator line is seen. + It should then return to the <xref linkend="libpq-PQgetResult"/> loop + until <xref linkend="libpq-PQgetResult"/> returns a null pointer. + Similarly a <literal>PGRES_COPY_IN</literal> result is processed + by a series of <xref linkend="libpq-PQputline"/> calls followed by + <xref linkend="libpq-PQendcopy"/>, then return to the + <xref linkend="libpq-PQgetResult"/> loop. This arrangement will + ensure that a <command>COPY</command> command embedded in a series + of <acronym>SQL</acronym> commands will be executed correctly. + </para> + + <para> + Older applications are likely to submit a <command>COPY</command> + via <xref linkend="libpq-PQexec"/> and assume that the transaction + is done after <xref linkend="libpq-PQendcopy"/>. This will work + correctly only if the <command>COPY</command> is the only + <acronym>SQL</acronym> command in the command string. + </para> + </listitem> + </varlistentry> + </variablelist> + + </sect2> + + </sect1> + + <sect1 id="libpq-control"> + <title>Control Functions</title> + + <para> + These functions control miscellaneous details of <application>libpq</application>'s + behavior. + </para> + + <variablelist> + <varlistentry id="libpq-PQclientEncoding"> + <term><function>PQclientEncoding</function><indexterm><primary>PQclientEncoding</primary></indexterm></term> + + <listitem> + <para> + Returns the client encoding. +<synopsis> +int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>); +</synopsis> + + Note that it returns the encoding ID, not a symbolic string + such as <literal>EUC_JP</literal>. If unsuccessful, it returns -1. + To convert an encoding ID to an encoding name, you + can use: + +<synopsis> +char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>); +</synopsis> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsetClientEncoding"> + <term><function>PQsetClientEncoding</function><indexterm><primary>PQsetClientEncoding</primary></indexterm></term> + + <listitem> + <para> + Sets the client encoding. +<synopsis> +int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>); +</synopsis> + + <replaceable>conn</replaceable> is a connection to the server, + and <replaceable>encoding</replaceable> is the encoding you want to + use. If the function successfully sets the encoding, it returns 0, + otherwise -1. The current encoding for this connection can be + determined by using <xref linkend="libpq-PQclientEncoding"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsetErrorVerbosity"> + <term><function>PQsetErrorVerbosity</function><indexterm><primary>PQsetErrorVerbosity</primary></indexterm></term> + + <listitem> + <para> + Determines the verbosity of messages returned by + <xref linkend="libpq-PQerrorMessage"/> and <xref linkend="libpq-PQresultErrorMessage"/>. +<synopsis> +typedef enum +{ + PQERRORS_TERSE, + PQERRORS_DEFAULT, + PQERRORS_VERBOSE, + PQERRORS_SQLSTATE +} PGVerbosity; + +PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity); +</synopsis> + + <xref linkend="libpq-PQsetErrorVerbosity"/> sets the verbosity mode, + returning the connection's previous setting. + In <firstterm>TERSE</firstterm> mode, returned messages include + severity, primary text, and position only; this will normally fit on a + single line. The <firstterm>DEFAULT</firstterm> mode produces messages + that include the above plus any detail, hint, or context fields (these + might span multiple lines). The <firstterm>VERBOSE</firstterm> mode + includes all available fields. The <firstterm>SQLSTATE</firstterm> + mode includes only the error severity and the <symbol>SQLSTATE</symbol> + error code, if one is available (if not, the output is like + <firstterm>TERSE</firstterm> mode). + </para> + + <para> + Changing the verbosity setting does not affect the messages available + from already-existing <structname>PGresult</structname> objects, only + subsequently-created ones. + (But see <xref linkend="libpq-PQresultVerboseErrorMessage"/> if you + want to print a previous error with a different verbosity.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsetErrorContextVisibility"> + <term><function>PQsetErrorContextVisibility</function><indexterm><primary>PQsetErrorContextVisibility</primary></indexterm></term> + + <listitem> + <para> + Determines the handling of <literal>CONTEXT</literal> fields in messages + returned by <xref linkend="libpq-PQerrorMessage"/> + and <xref linkend="libpq-PQresultErrorMessage"/>. +<synopsis> +typedef enum +{ + PQSHOW_CONTEXT_NEVER, + PQSHOW_CONTEXT_ERRORS, + PQSHOW_CONTEXT_ALWAYS +} PGContextVisibility; + +PGContextVisibility PQsetErrorContextVisibility(PGconn *conn, PGContextVisibility show_context); +</synopsis> + + <xref linkend="libpq-PQsetErrorContextVisibility"/> sets the context display mode, + returning the connection's previous setting. This mode controls + whether the <literal>CONTEXT</literal> field is included in messages. + The <firstterm>NEVER</firstterm> mode + never includes <literal>CONTEXT</literal>, while <firstterm>ALWAYS</firstterm> always + includes it if available. In <firstterm>ERRORS</firstterm> mode (the + default), <literal>CONTEXT</literal> fields are included only in error + messages, not in notices and warnings. + (However, if the verbosity setting is <firstterm>TERSE</firstterm> + or <firstterm>SQLSTATE</firstterm>, <literal>CONTEXT</literal> fields + are omitted regardless of the context display mode.) + </para> + + <para> + Changing this mode does not + affect the messages available from + already-existing <structname>PGresult</structname> objects, only + subsequently-created ones. + (But see <xref linkend="libpq-PQresultVerboseErrorMessage"/> if you + want to print a previous error with a different display mode.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQtrace"> + <term><function>PQtrace</function><indexterm><primary>PQtrace</primary></indexterm></term> + + <listitem> + <para> + Enables tracing of the client/server communication to a debugging file + stream. +<synopsis> +void PQtrace(PGconn *conn, FILE *stream); +</synopsis> + </para> + + <para> + Each line consists of: an optional timestamp, a direction indicator + (<literal>F</literal> for messages from client to server + or <literal>B</literal> for messages from server to client), + message length, message type, and message contents. + Non-message contents fields (timestamp, direction, length and message type) + are separated by a tab. Message contents are separated by a space. + Protocol strings are enclosed in double quotes, while strings used as data + values are enclosed in single quotes. Non-printable chars are printed as + hexadecimal escapes. + Further message-type-specific detail can be found in + <xref linkend="protocol-message-formats"/>. + </para> + + <note> + <para> + On Windows, if the <application>libpq</application> library and an application are + compiled with different flags, this function call will crash the + application because the internal representation of the <literal>FILE</literal> + pointers differ. Specifically, multithreaded/single-threaded, + release/debug, and static/dynamic flags should be the same for the + library and all applications using that library. + </para> + </note> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsetTraceFlags"> + <term><function>PQsetTraceFlags</function><indexterm><primary>PQsetTraceFlags</primary></indexterm></term> + + <listitem> + <para> + Controls the tracing behavior of client/server communication. +<synopsis> +void PQsetTraceFlags(PGconn *conn, int flags); +</synopsis> + </para> + + <para> + <literal>flags</literal> contains flag bits describing the operating mode + of tracing. + If <literal>flags</literal> contains <literal>PQTRACE_SUPPRESS_TIMESTAMPS</literal>, + then the timestamp is not included when printing each message. + If <literal>flags</literal> contains <literal>PQTRACE_REGRESS_MODE</literal>, + then some fields are redacted when printing each message, such as object + OIDs, to make the output more convenient to use in testing frameworks. + This function must be called after calling <function>PQtrace</function>. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQuntrace"> + <term><function>PQuntrace</function><indexterm><primary>PQuntrace</primary></indexterm></term> + + <listitem> + <para> + Disables tracing started by <xref linkend="libpq-PQtrace"/>. +<synopsis> +void PQuntrace(PGconn *conn); +</synopsis> + </para> + </listitem> + </varlistentry> + </variablelist> + + </sect1> + + <sect1 id="libpq-misc"> + <title>Miscellaneous Functions</title> + + <para> + As always, there are some functions that just don't fit anywhere. + </para> + + <variablelist> + <varlistentry id="libpq-PQfreemem"> + <term><function>PQfreemem</function><indexterm><primary>PQfreemem</primary></indexterm></term> + + <listitem> + <para> + Frees memory allocated by <application>libpq</application>. +<synopsis> +void PQfreemem(void *ptr); +</synopsis> + </para> + + <para> + Frees memory allocated by <application>libpq</application>, particularly + <xref linkend="libpq-PQescapeByteaConn"/>, + <xref linkend="libpq-PQescapeBytea"/>, + <xref linkend="libpq-PQunescapeBytea"/>, + and <function>PQnotifies</function>. + It is particularly important that this function, rather than + <function>free()</function>, be used on Microsoft Windows. This is because + allocating memory in a DLL and releasing it in the application works + only if multithreaded/single-threaded, release/debug, and static/dynamic + flags are the same for the DLL and the application. On non-Microsoft + Windows platforms, this function is the same as the standard library + function <function>free()</function>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQconninfoFree"> + <term><function>PQconninfoFree</function><indexterm><primary>PQconninfoFree</primary></indexterm></term> + + <listitem> + <para> + Frees the data structures allocated by + <xref linkend="libpq-PQconndefaults"/> or <xref linkend="libpq-PQconninfoParse"/>. +<synopsis> +void PQconninfoFree(PQconninfoOption *connOptions); +</synopsis> + If the argument is a <symbol>NULL</symbol> pointer, no operation is + performed. + </para> + + <para> + A simple <xref linkend="libpq-PQfreemem"/> will not do for this, since + the array contains references to subsidiary strings. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQencryptPasswordConn"> + <term><function>PQencryptPasswordConn</function><indexterm><primary>PQencryptPasswordConn</primary></indexterm></term> + + <listitem> + <para> + Prepares the encrypted form of a <productname>PostgreSQL</productname> password. +<synopsis> +char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm); +</synopsis> + This function is intended to be used by client applications that + wish to send commands like <literal>ALTER USER joe PASSWORD + 'pwd'</literal>. It is good practice not to send the original cleartext + password in such a command, because it might be exposed in command + logs, activity displays, and so on. Instead, use this function to + convert the password to encrypted form before it is sent. + </para> + + <para> + The <parameter>passwd</parameter> and <parameter>user</parameter> arguments + are the cleartext password, and the SQL name of the user it is for. + <parameter>algorithm</parameter> specifies the encryption algorithm + to use to encrypt the password. Currently supported algorithms are + <literal>md5</literal> and <literal>scram-sha-256</literal> (<literal>on</literal> and + <literal>off</literal> are also accepted as aliases for <literal>md5</literal>, for + compatibility with older server versions). Note that support for + <literal>scram-sha-256</literal> was introduced in <productname>PostgreSQL</productname> + version 10, and will not work correctly with older server versions. If + <parameter>algorithm</parameter> is <symbol>NULL</symbol>, this function will query + the server for the current value of the + <xref linkend="guc-password-encryption"/> setting. That can block, and + will fail if the current transaction is aborted, or if the connection + is busy executing another query. If you wish to use the default + algorithm for the server but want to avoid blocking, query + <varname>password_encryption</varname> yourself before calling + <xref linkend="libpq-PQencryptPasswordConn"/>, and pass that value as the + <parameter>algorithm</parameter>. + </para> + + <para> + The return value is a string allocated by <function>malloc</function>. + The caller can assume the string doesn't contain any special characters + that would require escaping. Use <xref linkend="libpq-PQfreemem"/> to free the + result when done with it. On error, returns <symbol>NULL</symbol>, and + a suitable message is stored in the connection object. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQencryptPassword"> + <term><function>PQencryptPassword</function><indexterm><primary>PQencryptPassword</primary></indexterm></term> + + <listitem> + <para> + Prepares the md5-encrypted form of a <productname>PostgreSQL</productname> password. +<synopsis> +char *PQencryptPassword(const char *passwd, const char *user); +</synopsis> + <xref linkend="libpq-PQencryptPassword"/> is an older, deprecated version of + <xref linkend="libpq-PQencryptPasswordConn"/>. The difference is that + <xref linkend="libpq-PQencryptPassword"/> does not + require a connection object, and <literal>md5</literal> is always used as the + encryption algorithm. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQmakeEmptyPGresult"> + <term><function>PQmakeEmptyPGresult</function><indexterm><primary>PQmakeEmptyPGresult</primary></indexterm></term> + + <listitem> + <para> + Constructs an empty <structname>PGresult</structname> object with the given status. +<synopsis> +PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); +</synopsis> + </para> + + <para> + This is <application>libpq</application>'s internal function to allocate and + initialize an empty <structname>PGresult</structname> object. This + function returns <symbol>NULL</symbol> if memory could not be allocated. It is + exported because some applications find it useful to generate result + objects (particularly objects with error status) themselves. If + <parameter>conn</parameter> is not null and <parameter>status</parameter> + indicates an error, the current error message of the specified + connection is copied into the <structname>PGresult</structname>. + Also, if <parameter>conn</parameter> is not null, any event procedures + registered in the connection are copied into the + <structname>PGresult</structname>. (They do not get + <literal>PGEVT_RESULTCREATE</literal> calls, but see + <xref linkend="libpq-PQfireResultCreateEvents"/>.) + Note that <xref linkend="libpq-PQclear"/> should eventually be called + on the object, just as with a <structname>PGresult</structname> + returned by <application>libpq</application> itself. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQfireResultCreateEvents"> + <term><function>PQfireResultCreateEvents</function><indexterm><primary>PQfireResultCreateEvents</primary></indexterm></term> + <listitem> + <para> + Fires a <literal>PGEVT_RESULTCREATE</literal> event (see <xref + linkend="libpq-events"/>) for each event procedure registered in the + <structname>PGresult</structname> object. Returns non-zero for success, + zero if any event procedure fails. + +<synopsis> +int PQfireResultCreateEvents(PGconn *conn, PGresult *res); +</synopsis> + </para> + + <para> + The <literal>conn</literal> argument is passed through to event procedures + but not used directly. It can be <symbol>NULL</symbol> if the event + procedures won't use it. + </para> + + <para> + Event procedures that have already received a + <literal>PGEVT_RESULTCREATE</literal> or <literal>PGEVT_RESULTCOPY</literal> event + for this object are not fired again. + </para> + + <para> + The main reason that this function is separate from + <xref linkend="libpq-PQmakeEmptyPGresult"/> is that it is often appropriate + to create a <structname>PGresult</structname> and fill it with data + before invoking the event procedures. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQcopyResult"> + <term><function>PQcopyResult</function><indexterm><primary>PQcopyResult</primary></indexterm></term> + + <listitem> + <para> + Makes a copy of a <structname>PGresult</structname> object. The copy is + not linked to the source result in any way and + <xref linkend="libpq-PQclear"/> must be called when the copy is no longer + needed. If the function fails, <symbol>NULL</symbol> is returned. + +<synopsis> +PGresult *PQcopyResult(const PGresult *src, int flags); +</synopsis> + </para> + + <para> + This is not intended to make an exact copy. The returned result is + always put into <literal>PGRES_TUPLES_OK</literal> status, and does not + copy any error message in the source. (It does copy the command status + string, however.) The <parameter>flags</parameter> argument determines + what else is copied. It is a bitwise OR of several flags. + <literal>PG_COPYRES_ATTRS</literal> specifies copying the source + result's attributes (column definitions). + <literal>PG_COPYRES_TUPLES</literal> specifies copying the source + result's tuples. (This implies copying the attributes, too.) + <literal>PG_COPYRES_NOTICEHOOKS</literal> specifies + copying the source result's notify hooks. + <literal>PG_COPYRES_EVENTS</literal> specifies copying the source + result's events. (But any instance data associated with the source + is not copied.) + The event procedures receive <literal>PGEVT_RESULTCOPY</literal> events. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsetResultAttrs"> + <term><function>PQsetResultAttrs</function><indexterm><primary>PQsetResultAttrs</primary></indexterm></term> + + <listitem> + <para> + Sets the attributes of a <structname>PGresult</structname> object. +<synopsis> +int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs); +</synopsis> + </para> + + <para> + The provided <parameter>attDescs</parameter> are copied into the result. + If the <parameter>attDescs</parameter> pointer is <symbol>NULL</symbol> or + <parameter>numAttributes</parameter> is less than one, the request is + ignored and the function succeeds. If <parameter>res</parameter> + already contains attributes, the function will fail. If the function + fails, the return value is zero. If the function succeeds, the return + value is non-zero. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsetvalue"> + <term><function>PQsetvalue</function><indexterm><primary>PQsetvalue</primary></indexterm></term> + + <listitem> + <para> + Sets a tuple field value of a <structname>PGresult</structname> object. +<synopsis> +int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len); +</synopsis> + </para> + + <para> + The function will automatically grow the result's internal tuples array + as needed. However, the <parameter>tup_num</parameter> argument must be + less than or equal to <xref linkend="libpq-PQntuples"/>, meaning this + function can only grow the tuples array one tuple at a time. But any + field of any existing tuple can be modified in any order. If a value at + <parameter>field_num</parameter> already exists, it will be overwritten. + If <parameter>len</parameter> is -1 or + <parameter>value</parameter> is <symbol>NULL</symbol>, the field value + will be set to an SQL null value. The + <parameter>value</parameter> is copied into the result's private storage, + thus is no longer needed after the function + returns. If the function fails, the return value is zero. If the + function succeeds, the return value is non-zero. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQresultAlloc"> + <term><function>PQresultAlloc</function><indexterm><primary>PQresultAlloc</primary></indexterm></term> + + <listitem> + <para> + Allocate subsidiary storage for a <structname>PGresult</structname> object. +<synopsis> +void *PQresultAlloc(PGresult *res, size_t nBytes); +</synopsis> + </para> + + <para> + Any memory allocated with this function will be freed when + <parameter>res</parameter> is cleared. If the function fails, + the return value is <symbol>NULL</symbol>. The result is + guaranteed to be adequately aligned for any type of data, + just as for <function>malloc</function>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQresultMemorySize"> + <term><function>PQresultMemorySize</function><indexterm><primary>PQresultMemorySize</primary></indexterm></term> + + <listitem> + <para> + Retrieves the number of bytes allocated for + a <structname>PGresult</structname> object. +<synopsis> +size_t PQresultMemorySize(const PGresult *res); +</synopsis> + </para> + + <para> + This value is the sum of all <function>malloc</function> requests + associated with the <structname>PGresult</structname> object, that is, + all the space that will be freed by <xref linkend="libpq-PQclear"/>. + This information can be useful for managing memory consumption. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQlibVersion"> + <term><function>PQlibVersion</function><indexterm + ><primary>PQlibVersion</primary><seealso>PQserverVersion</seealso></indexterm></term> + + <listitem> + <para> + Return the version of <productname>libpq</productname> that is being used. +<synopsis> +int PQlibVersion(void); +</synopsis> + </para> + + <para> + The result of this function can be used to determine, at + run time, whether specific functionality is available in the currently + loaded version of libpq. The function can be used, for example, + to determine which connection options are available in + <xref linkend="libpq-PQconnectdb"/>. + </para> + + <para> + The result is formed by multiplying the library's major version + number by 10000 and adding the minor version number. For example, + version 10.1 will be returned as 100001, and version 11.0 will be + returned as 110000. + </para> + + <para> + Prior to major version 10, <productname>PostgreSQL</productname> used + three-part version numbers in which the first two parts together + represented the major version. For those + versions, <xref linkend="libpq-PQlibVersion"/> uses two digits for each + part; for example version 9.1.5 will be returned as 90105, and + version 9.2.0 will be returned as 90200. + </para> + + <para> + Therefore, for purposes of determining feature compatibility, + applications should divide the result of <xref linkend="libpq-PQlibVersion"/> + by 100 not 10000 to determine a logical major version number. + In all release series, only the last two digits differ between + minor releases (bug-fix releases). + </para> + + <note> + <para> + This function appeared in <productname>PostgreSQL</productname> version 9.1, so + it cannot be used to detect required functionality in earlier + versions, since calling it will create a link dependency + on version 9.1 or later. + </para> + </note> + </listitem> + </varlistentry> + + </variablelist> + + </sect1> + + <sect1 id="libpq-notice-processing"> + <title>Notice Processing</title> + + <indexterm zone="libpq-notice-processing"> + <primary>notice processing</primary> + <secondary>in libpq</secondary> + </indexterm> + + <para> + Notice and warning messages generated by the server are not returned + by the query execution functions, since they do not imply failure of + the query. Instead they are passed to a notice handling function, and + execution continues normally after the handler returns. The default + notice handling function prints the message on + <filename>stderr</filename>, but the application can override this + behavior by supplying its own handling function. + </para> + + <para> + For historical reasons, there are two levels of notice handling, called + the notice receiver and notice processor. The default behavior is for + the notice receiver to format the notice and pass a string to the notice + processor for printing. However, an application that chooses to provide + its own notice receiver will typically ignore the notice processor + layer and just do all the work in the notice receiver. + </para> + + <para> + The function <function id="libpq-PQsetNoticeReceiver">PQsetNoticeReceiver</function> + <indexterm><primary>notice receiver</primary></indexterm> + <indexterm><primary>PQsetNoticeReceiver</primary></indexterm> sets or + examines the current notice receiver for a connection object. + Similarly, <function id="libpq-PQsetNoticeProcessor">PQsetNoticeProcessor</function> + <indexterm><primary>notice processor</primary></indexterm> + <indexterm><primary>PQsetNoticeProcessor</primary></indexterm> sets or + examines the current notice processor. + +<synopsis> +typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res); + +PQnoticeReceiver +PQsetNoticeReceiver(PGconn *conn, + PQnoticeReceiver proc, + void *arg); + +typedef void (*PQnoticeProcessor) (void *arg, const char *message); + +PQnoticeProcessor +PQsetNoticeProcessor(PGconn *conn, + PQnoticeProcessor proc, + void *arg); +</synopsis> + + Each of these functions returns the previous notice receiver or + processor function pointer, and sets the new value. If you supply a + null function pointer, no action is taken, but the current pointer is + returned. + </para> + + <para> + When a notice or warning message is received from the server, or + generated internally by <application>libpq</application>, the notice + receiver function is called. It is passed the message in the form of + a <symbol>PGRES_NONFATAL_ERROR</symbol> + <structname>PGresult</structname>. (This allows the receiver to extract + individual fields using <xref linkend="libpq-PQresultErrorField"/>, or obtain a + complete preformatted message using <xref linkend="libpq-PQresultErrorMessage"/> + or <xref linkend="libpq-PQresultVerboseErrorMessage"/>.) The same + void pointer passed to <function>PQsetNoticeReceiver</function> is also + passed. (This pointer can be used to access application-specific state + if needed.) + </para> + + <para> + The default notice receiver simply extracts the message (using + <xref linkend="libpq-PQresultErrorMessage"/>) and passes it to the notice + processor. + </para> + + <para> + The notice processor is responsible for handling a notice or warning + message given in text form. It is passed the string text of the message + (including a trailing newline), plus a void pointer that is the same + one passed to <function>PQsetNoticeProcessor</function>. (This pointer + can be used to access application-specific state if needed.) + </para> + + <para> + The default notice processor is simply: +<programlisting> +static void +defaultNoticeProcessor(void *arg, const char *message) +{ + fprintf(stderr, "%s", message); +} +</programlisting> + </para> + + <para> + Once you have set a notice receiver or processor, you should expect + that that function could be called as long as either the + <structname>PGconn</structname> object or <structname>PGresult</structname> objects made + from it exist. At creation of a <structname>PGresult</structname>, the + <structname>PGconn</structname>'s current notice handling pointers are copied + into the <structname>PGresult</structname> for possible use by functions like + <xref linkend="libpq-PQgetvalue"/>. + </para> + + </sect1> + + <sect1 id="libpq-events"> + <title>Event System</title> + + <para> + <application>libpq</application>'s event system is designed to notify + registered event handlers about interesting + <application>libpq</application> events, such as the creation or + destruction of <structname>PGconn</structname> and + <structname>PGresult</structname> objects. A principal use case is that + this allows applications to associate their own data with a + <structname>PGconn</structname> or <structname>PGresult</structname> + and ensure that that data is freed at an appropriate time. + </para> + + <para> + Each registered event handler is associated with two pieces of data, + known to <application>libpq</application> only as opaque <literal>void *</literal> + pointers. There is a <firstterm>pass-through</firstterm> pointer that is provided + by the application when the event handler is registered with a + <structname>PGconn</structname>. The pass-through pointer never changes for the + life of the <structname>PGconn</structname> and all <structname>PGresult</structname>s + generated from it; so if used, it must point to long-lived data. + In addition there is an <firstterm>instance data</firstterm> pointer, which starts + out <symbol>NULL</symbol> in every <structname>PGconn</structname> and <structname>PGresult</structname>. + This pointer can be manipulated using the + <xref linkend="libpq-PQinstanceData"/>, + <xref linkend="libpq-PQsetInstanceData"/>, + <xref linkend="libpq-PQresultInstanceData"/> and + <xref linkend="libpq-PQresultSetInstanceData"/> functions. Note that + unlike the pass-through pointer, instance data of a <structname>PGconn</structname> + is not automatically inherited by <structname>PGresult</structname>s created from + it. <application>libpq</application> does not know what pass-through + and instance data pointers point to (if anything) and will never attempt + to free them — that is the responsibility of the event handler. + </para> + + <sect2 id="libpq-events-types"> + <title>Event Types</title> + + <para> + The enum <literal>PGEventId</literal> names the types of events handled by + the event system. All its values have names beginning with + <literal>PGEVT</literal>. For each event type, there is a corresponding + event info structure that carries the parameters passed to the event + handlers. The event types are: + </para> + + <variablelist> + <varlistentry id="libpq-pgevt-register"> + <term><literal>PGEVT_REGISTER</literal></term> + <listitem> + <para> + The register event occurs when <xref linkend="libpq-PQregisterEventProc"/> + is called. It is the ideal time to initialize any + <literal>instanceData</literal> an event procedure may need. Only one + register event will be fired per event handler per connection. If the + event procedure fails (returns zero), the registration is cancelled. + +<synopsis> +typedef struct +{ + PGconn *conn; +} PGEventRegister; +</synopsis> + + When a <literal>PGEVT_REGISTER</literal> event is received, the + <parameter>evtInfo</parameter> pointer should be cast to a + <structname>PGEventRegister *</structname>. This structure contains a + <structname>PGconn</structname> that should be in the + <literal>CONNECTION_OK</literal> status; guaranteed if one calls + <xref linkend="libpq-PQregisterEventProc"/> right after obtaining a good + <structname>PGconn</structname>. When returning a failure code, all + cleanup must be performed as no <literal>PGEVT_CONNDESTROY</literal> + event will be sent. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgevt-connreset"> + <term><literal>PGEVT_CONNRESET</literal></term> + <listitem> + <para> + The connection reset event is fired on completion of + <xref linkend="libpq-PQreset"/> or <function>PQresetPoll</function>. In + both cases, the event is only fired if the reset was successful. + The return value of the event procedure is ignored + in <productname>PostgreSQL</productname> v15 and later. + With earlier versions, however, it's important to return success + (nonzero) or the connection will be aborted. + +<synopsis> +typedef struct +{ + PGconn *conn; +} PGEventConnReset; +</synopsis> + + When a <literal>PGEVT_CONNRESET</literal> event is received, the + <parameter>evtInfo</parameter> pointer should be cast to a + <structname>PGEventConnReset *</structname>. Although the contained + <structname>PGconn</structname> was just reset, all event data remains + unchanged. This event should be used to reset/reload/requery any + associated <literal>instanceData</literal>. Note that even if the + event procedure fails to process <literal>PGEVT_CONNRESET</literal>, it will + still receive a <literal>PGEVT_CONNDESTROY</literal> event when the connection + is closed. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgevt-conndestroy"> + <term><literal>PGEVT_CONNDESTROY</literal></term> + <listitem> + <para> + The connection destroy event is fired in response to + <xref linkend="libpq-PQfinish"/>. It is the event procedure's + responsibility to properly clean up its event data as libpq has no + ability to manage this memory. Failure to clean up will lead + to memory leaks. + +<synopsis> +typedef struct +{ + PGconn *conn; +} PGEventConnDestroy; +</synopsis> + + When a <literal>PGEVT_CONNDESTROY</literal> event is received, the + <parameter>evtInfo</parameter> pointer should be cast to a + <structname>PGEventConnDestroy *</structname>. This event is fired + prior to <xref linkend="libpq-PQfinish"/> performing any other cleanup. + The return value of the event procedure is ignored since there is no + way of indicating a failure from <xref linkend="libpq-PQfinish"/>. Also, + an event procedure failure should not abort the process of cleaning up + unwanted memory. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgevt-resultcreate"> + <term><literal>PGEVT_RESULTCREATE</literal></term> + <listitem> + <para> + The result creation event is fired in response to any query execution + function that generates a result, including + <xref linkend="libpq-PQgetResult"/>. This event will only be fired after + the result has been created successfully. + +<synopsis> +typedef struct +{ + PGconn *conn; + PGresult *result; +} PGEventResultCreate; +</synopsis> + + When a <literal>PGEVT_RESULTCREATE</literal> event is received, the + <parameter>evtInfo</parameter> pointer should be cast to a + <structname>PGEventResultCreate *</structname>. The + <parameter>conn</parameter> is the connection used to generate the + result. This is the ideal place to initialize any + <literal>instanceData</literal> that needs to be associated with the + result. If an event procedure fails (returns zero), that event + procedure will be ignored for the remaining lifetime of the result; + that is, it will not receive <literal>PGEVT_RESULTCOPY</literal> + or <literal>PGEVT_RESULTDESTROY</literal> events for this result or + results copied from it. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgevt-resultcopy"> + <term><literal>PGEVT_RESULTCOPY</literal></term> + <listitem> + <para> + The result copy event is fired in response to + <xref linkend="libpq-PQcopyResult"/>. This event will only be fired after + the copy is complete. Only event procedures that have + successfully handled the <literal>PGEVT_RESULTCREATE</literal> + or <literal>PGEVT_RESULTCOPY</literal> event for the source result + will receive <literal>PGEVT_RESULTCOPY</literal> events. + +<synopsis> +typedef struct +{ + const PGresult *src; + PGresult *dest; +} PGEventResultCopy; +</synopsis> + + When a <literal>PGEVT_RESULTCOPY</literal> event is received, the + <parameter>evtInfo</parameter> pointer should be cast to a + <structname>PGEventResultCopy *</structname>. The + <parameter>src</parameter> result is what was copied while the + <parameter>dest</parameter> result is the copy destination. This event + can be used to provide a deep copy of <literal>instanceData</literal>, + since <literal>PQcopyResult</literal> cannot do that. If an event + procedure fails (returns zero), that event procedure will be + ignored for the remaining lifetime of the new result; that is, it + will not receive <literal>PGEVT_RESULTCOPY</literal> + or <literal>PGEVT_RESULTDESTROY</literal> events for that result or + results copied from it. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-pgevt-resultdestroy"> + <term><literal>PGEVT_RESULTDESTROY</literal></term> + <listitem> + <para> + The result destroy event is fired in response to a + <xref linkend="libpq-PQclear"/>. It is the event procedure's + responsibility to properly clean up its event data as libpq has no + ability to manage this memory. Failure to clean up will lead + to memory leaks. + +<synopsis> +typedef struct +{ + PGresult *result; +} PGEventResultDestroy; +</synopsis> + + When a <literal>PGEVT_RESULTDESTROY</literal> event is received, the + <parameter>evtInfo</parameter> pointer should be cast to a + <structname>PGEventResultDestroy *</structname>. This event is fired + prior to <xref linkend="libpq-PQclear"/> performing any other cleanup. + The return value of the event procedure is ignored since there is no + way of indicating a failure from <xref linkend="libpq-PQclear"/>. Also, + an event procedure failure should not abort the process of cleaning up + unwanted memory. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="libpq-events-proc"> + <title>Event Callback Procedure</title> + + <variablelist> + <varlistentry id="libpq-PGEventProc"> + <term><literal>PGEventProc</literal><indexterm><primary>PGEventProc</primary></indexterm></term> + + <listitem> + <para> + <literal>PGEventProc</literal> is a typedef for a pointer to an + event procedure, that is, the user callback function that receives + events from libpq. The signature of an event procedure must be + +<synopsis> +int eventproc(PGEventId evtId, void *evtInfo, void *passThrough) +</synopsis> + + The <parameter>evtId</parameter> parameter indicates which + <literal>PGEVT</literal> event occurred. The + <parameter>evtInfo</parameter> pointer must be cast to the appropriate + structure type to obtain further information about the event. + The <parameter>passThrough</parameter> parameter is the pointer + provided to <xref linkend="libpq-PQregisterEventProc"/> when the event + procedure was registered. The function should return a non-zero value + if it succeeds and zero if it fails. + </para> + + <para> + A particular event procedure can be registered only once in any + <structname>PGconn</structname>. This is because the address of the procedure + is used as a lookup key to identify the associated instance data. + </para> + + <caution> + <para> + On Windows, functions can have two different addresses: one visible + from outside a DLL and another visible from inside the DLL. One + should be careful that only one of these addresses is used with + <application>libpq</application>'s event-procedure functions, else confusion will + result. The simplest rule for writing code that will work is to + ensure that event procedures are declared <literal>static</literal>. If the + procedure's address must be available outside its own source file, + expose a separate function to return the address. + </para> + </caution> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="libpq-events-funcs"> + <title>Event Support Functions</title> + + <variablelist> + <varlistentry id="libpq-PQregisterEventProc"> + <term><function>PQregisterEventProc</function><indexterm><primary>PQregisterEventProc</primary></indexterm></term> + + <listitem> + <para> + Registers an event callback procedure with libpq. + +<synopsis> +int PQregisterEventProc(PGconn *conn, PGEventProc proc, + const char *name, void *passThrough); +</synopsis> + </para> + + <para> + An event procedure must be registered once on each + <structname>PGconn</structname> you want to receive events about. There is no + limit, other than memory, on the number of event procedures that + can be registered with a connection. The function returns a non-zero + value if it succeeds and zero if it fails. + </para> + + <para> + The <parameter>proc</parameter> argument will be called when a libpq + event is fired. Its memory address is also used to lookup + <literal>instanceData</literal>. The <parameter>name</parameter> + argument is used to refer to the event procedure in error messages. + This value cannot be <symbol>NULL</symbol> or a zero-length string. The name string is + copied into the <structname>PGconn</structname>, so what is passed need not be + long-lived. The <parameter>passThrough</parameter> pointer is passed + to the <parameter>proc</parameter> whenever an event occurs. This + argument can be <symbol>NULL</symbol>. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQsetInstanceData"> + <term><function>PQsetInstanceData</function><indexterm><primary>PQsetInstanceData</primary></indexterm></term> + <listitem> + <para> + Sets the connection <parameter>conn</parameter>'s <literal>instanceData</literal> + for procedure <parameter>proc</parameter> to <parameter>data</parameter>. This + returns non-zero for success and zero for failure. (Failure is + only possible if <parameter>proc</parameter> has not been properly + registered in <parameter>conn</parameter>.) + +<synopsis> +int PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data); +</synopsis> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQinstanceData"> + <term><function>PQinstanceData</function><indexterm><primary>PQinstanceData</primary></indexterm></term> + <listitem> + <para> + Returns the + connection <parameter>conn</parameter>'s <literal>instanceData</literal> + associated with procedure <parameter>proc</parameter>, + or <symbol>NULL</symbol> if there is none. + +<synopsis> +void *PQinstanceData(const PGconn *conn, PGEventProc proc); +</synopsis> + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQresultSetInstanceData"> + <term><function>PQresultSetInstanceData</function><indexterm><primary>PQresultSetInstanceData</primary></indexterm></term> + <listitem> + <para> + Sets the result's <literal>instanceData</literal> + for <parameter>proc</parameter> to <parameter>data</parameter>. This returns + non-zero for success and zero for failure. (Failure is only + possible if <parameter>proc</parameter> has not been properly registered + in the result.) + +<synopsis> +int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data); +</synopsis> + </para> + + <para> + Beware that any storage represented by <parameter>data</parameter> + will not be accounted for by <xref linkend="libpq-PQresultMemorySize"/>, + unless it is allocated using <xref linkend="libpq-PQresultAlloc"/>. + (Doing so is recommendable because it eliminates the need to free + such storage explicitly when the result is destroyed.) + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQresultInstanceData"> + <term><function>PQresultInstanceData</function><indexterm><primary>PQresultInstanceData</primary></indexterm></term> + <listitem> + <para> + Returns the result's <literal>instanceData</literal> associated with <parameter>proc</parameter>, or <symbol>NULL</symbol> + if there is none. + +<synopsis> +void *PQresultInstanceData(const PGresult *res, PGEventProc proc); +</synopsis> + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="libpq-events-example"> + <title>Event Example</title> + + <para> + Here is a skeleton example of managing private data associated with + libpq connections and results. + </para> + +<programlisting> +<![CDATA[ +/* required header for libpq events (note: includes libpq-fe.h) */ +#include <libpq-events.h> + +/* The instanceData */ +typedef struct +{ + int n; + char *str; +} mydata; + +/* PGEventProc */ +static int myEventProc(PGEventId evtId, void *evtInfo, void *passThrough); + +int +main(void) +{ + mydata *data; + PGresult *res; + PGconn *conn = + PQconnectdb("dbname=postgres options=-csearch_path="); + + if (PQstatus(conn) != CONNECTION_OK) + { + /* PQerrorMessage's result includes a trailing newline */ + fprintf(stderr, "%s", PQerrorMessage(conn)); + PQfinish(conn); + return 1; + } + + /* called once on any connection that should receive events. + * Sends a PGEVT_REGISTER to myEventProc. + */ + if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL)) + { + fprintf(stderr, "Cannot register PGEventProc\n"); + PQfinish(conn); + return 1; + } + + /* conn instanceData is available */ + data = PQinstanceData(conn, myEventProc); + + /* Sends a PGEVT_RESULTCREATE to myEventProc */ + res = PQexec(conn, "SELECT 1 + 1"); + + /* result instanceData is available */ + data = PQresultInstanceData(res, myEventProc); + + /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */ + res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS); + + /* result instanceData is available if PG_COPYRES_EVENTS was + * used during the PQcopyResult call. + */ + data = PQresultInstanceData(res_copy, myEventProc); + + /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */ + PQclear(res); + PQclear(res_copy); + + /* Sends a PGEVT_CONNDESTROY to myEventProc */ + PQfinish(conn); + + return 0; +} + +static int +myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) +{ + switch (evtId) + { + case PGEVT_REGISTER: + { + PGEventRegister *e = (PGEventRegister *)evtInfo; + mydata *data = get_mydata(e->conn); + + /* associate app specific data with connection */ + PQsetInstanceData(e->conn, myEventProc, data); + break; + } + + case PGEVT_CONNRESET: + { + PGEventConnReset *e = (PGEventConnReset *)evtInfo; + mydata *data = PQinstanceData(e->conn, myEventProc); + + if (data) + memset(data, 0, sizeof(mydata)); + break; + } + + case PGEVT_CONNDESTROY: + { + PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo; + mydata *data = PQinstanceData(e->conn, myEventProc); + + /* free instance data because the conn is being destroyed */ + if (data) + free_mydata(data); + break; + } + + case PGEVT_RESULTCREATE: + { + PGEventResultCreate *e = (PGEventResultCreate *)evtInfo; + mydata *conn_data = PQinstanceData(e->conn, myEventProc); + mydata *res_data = dup_mydata(conn_data); + + /* associate app specific data with result (copy it from conn) */ + PQresultSetInstanceData(e->result, myEventProc, res_data); + break; + } + + case PGEVT_RESULTCOPY: + { + PGEventResultCopy *e = (PGEventResultCopy *)evtInfo; + mydata *src_data = PQresultInstanceData(e->src, myEventProc); + mydata *dest_data = dup_mydata(src_data); + + /* associate app specific data with result (copy it from a result) */ + PQresultSetInstanceData(e->dest, myEventProc, dest_data); + break; + } + + case PGEVT_RESULTDESTROY: + { + PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo; + mydata *data = PQresultInstanceData(e->result, myEventProc); + + /* free instance data because the result is being destroyed */ + if (data) + free_mydata(data); + break; + } + + /* unknown event ID, just return true. */ + default: + break; + } + + return true; /* event processing succeeded */ +} +]]> +</programlisting> + </sect2> + </sect1> + + <sect1 id="libpq-envars"> + <title>Environment Variables</title> + + <indexterm zone="libpq-envars"> + <primary>environment variable</primary> + </indexterm> + + <para> + The following environment variables can be used to select default + connection parameter values, which will be used by + <xref linkend="libpq-PQconnectdb"/>, <xref linkend="libpq-PQsetdbLogin"/> and + <xref linkend="libpq-PQsetdb"/> if no value is directly specified by the calling + code. These are useful to avoid hard-coding database connection + information into simple client applications, for example. + + <itemizedlist> + <listitem> + <para> + <indexterm> + <primary><envar>PGHOST</envar></primary> + </indexterm> + <envar>PGHOST</envar> behaves the same as the <xref + linkend="libpq-connect-host"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGHOSTADDR</envar></primary> + </indexterm> + <envar>PGHOSTADDR</envar> behaves the same as the <xref + linkend="libpq-connect-hostaddr"/> connection parameter. + This can be set instead of or in addition to <envar>PGHOST</envar> + to avoid DNS lookup overhead. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGPORT</envar></primary> + </indexterm> + <envar>PGPORT</envar> behaves the same as the <xref + linkend="libpq-connect-port"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGDATABASE</envar></primary> + </indexterm> + <envar>PGDATABASE</envar> behaves the same as the <xref + linkend="libpq-connect-dbname"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGUSER</envar></primary> + </indexterm> + <envar>PGUSER</envar> behaves the same as the <xref + linkend="libpq-connect-user"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGPASSWORD</envar></primary> + </indexterm> + <envar>PGPASSWORD</envar> behaves the same as the <xref + linkend="libpq-connect-password"/> connection parameter. + Use of this environment variable + is not recommended for security reasons, as some operating systems + allow non-root users to see process environment variables via + <application>ps</application>; instead consider using a password file + (see <xref linkend="libpq-pgpass"/>). + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGPASSFILE</envar></primary> + </indexterm> + <envar>PGPASSFILE</envar> behaves the same as the <xref + linkend="libpq-connect-passfile"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGREQUIREAUTH</envar></primary> + </indexterm> + <envar>PGREQUIREAUTH</envar> behaves the same as the <xref + linkend="libpq-connect-require-auth"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGCHANNELBINDING</envar></primary> + </indexterm> + <envar>PGCHANNELBINDING</envar> behaves the same as the <xref + linkend="libpq-connect-channel-binding"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSERVICE</envar></primary> + </indexterm> + <envar>PGSERVICE</envar> behaves the same as the <xref + linkend="libpq-connect-service"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSERVICEFILE</envar></primary> + </indexterm> + <envar>PGSERVICEFILE</envar> specifies the name of the per-user + connection service file + (see <xref linkend="libpq-pgservice"/>). + Defaults to <filename>~/.pg_service.conf</filename>, or + <filename>%APPDATA%\postgresql\.pg_service.conf</filename> on + Microsoft Windows. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGOPTIONS</envar></primary> + </indexterm> + <envar>PGOPTIONS</envar> behaves the same as the <xref + linkend="libpq-connect-options"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGAPPNAME</envar></primary> + </indexterm> + <envar>PGAPPNAME</envar> behaves the same as the <xref + linkend="libpq-connect-application-name"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLMODE</envar></primary> + </indexterm> + <envar>PGSSLMODE</envar> behaves the same as the <xref + linkend="libpq-connect-sslmode"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGREQUIRESSL</envar></primary> + </indexterm> + <envar>PGREQUIRESSL</envar> behaves the same as the <xref + linkend="libpq-connect-requiressl"/> connection parameter. + This environment variable is deprecated in favor of the + <envar>PGSSLMODE</envar> variable; setting both variables suppresses the + effect of this one. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLCOMPRESSION</envar></primary> + </indexterm> + <envar>PGSSLCOMPRESSION</envar> behaves the same as the <xref + linkend="libpq-connect-sslcompression"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLCERT</envar></primary> + </indexterm> + <envar>PGSSLCERT</envar> behaves the same as the <xref + linkend="libpq-connect-sslcert"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLKEY</envar></primary> + </indexterm> + <envar>PGSSLKEY</envar> behaves the same as the <xref + linkend="libpq-connect-sslkey"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLCERTMODE</envar></primary> + </indexterm> + <envar>PGSSLCERTMODE</envar> behaves the same as the <xref + linkend="libpq-connect-sslcertmode"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLROOTCERT</envar></primary> + </indexterm> + <envar>PGSSLROOTCERT</envar> behaves the same as the <xref + linkend="libpq-connect-sslrootcert"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLCRL</envar></primary> + </indexterm> + <envar>PGSSLCRL</envar> behaves the same as the <xref + linkend="libpq-connect-sslcrl"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLCRLDIR</envar></primary> + </indexterm> + <envar>PGSSLCRLDIR</envar> behaves the same as the <xref + linkend="libpq-connect-sslcrldir"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLSNI</envar></primary> + </indexterm> + <envar>PGSSLSNI</envar> behaves the same as the <xref + linkend="libpq-connect-sslsni"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGREQUIREPEER</envar></primary> + </indexterm> + <envar>PGREQUIREPEER</envar> behaves the same as the <xref + linkend="libpq-connect-requirepeer"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLMINPROTOCOLVERSION</envar></primary> + </indexterm> + <envar>PGSSLMINPROTOCOLVERSION</envar> behaves the same as the <xref + linkend="libpq-connect-ssl-min-protocol-version"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGSSLMAXPROTOCOLVERSION</envar></primary> + </indexterm> + <envar>PGSSLMAXPROTOCOLVERSION</envar> behaves the same as the <xref + linkend="libpq-connect-ssl-max-protocol-version"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGGSSENCMODE</envar></primary> + </indexterm> + <envar>PGGSSENCMODE</envar> behaves the same as the <xref + linkend="libpq-connect-gssencmode"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGKRBSRVNAME</envar></primary> + </indexterm> + <envar>PGKRBSRVNAME</envar> behaves the same as the <xref + linkend="libpq-connect-krbsrvname"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGGSSLIB</envar></primary> + </indexterm> + <envar>PGGSSLIB</envar> behaves the same as the <xref + linkend="libpq-connect-gsslib"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGGSSDELEGATION</envar></primary> + </indexterm> + <envar>PGGSSDELEGATION</envar> behaves the same as the <xref + linkend="libpq-connect-gssdelegation"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGCONNECT_TIMEOUT</envar></primary> + </indexterm> + <envar>PGCONNECT_TIMEOUT</envar> behaves the same as the <xref + linkend="libpq-connect-connect-timeout"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGCLIENTENCODING</envar></primary> + </indexterm> + <envar>PGCLIENTENCODING</envar> behaves the same as the <xref + linkend="libpq-connect-client-encoding"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGTARGETSESSIONATTRS</envar></primary> + </indexterm> + <envar>PGTARGETSESSIONATTRS</envar> behaves the same as the <xref + linkend="libpq-connect-target-session-attrs"/> connection parameter. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGLOADBALANCEHOSTS</envar></primary> + </indexterm> + <envar>PGLOADBALANCEHOSTS</envar> behaves the same as the <xref + linkend="libpq-connect-load-balance-hosts"/> connection parameter. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + The following environment variables can be used to specify default + behavior for each <productname>PostgreSQL</productname> session. (See + also the <xref linkend="sql-alterrole"/> + and <xref linkend="sql-alterdatabase"/> + commands for ways to set default behavior on a per-user or per-database + basis.) + + <itemizedlist> + <listitem> + <para> + <indexterm> + <primary><envar>PGDATESTYLE</envar></primary> + </indexterm> + <envar>PGDATESTYLE</envar> sets the default style of date/time + representation. (Equivalent to <literal>SET datestyle TO + ...</literal>.) + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGTZ</envar></primary> + </indexterm> + <envar>PGTZ</envar> sets the default time zone. (Equivalent to + <literal>SET timezone TO ...</literal>.) + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGGEQO</envar></primary> + </indexterm> + <envar>PGGEQO</envar> sets the default mode for the genetic query + optimizer. (Equivalent to <literal>SET geqo TO ...</literal>.) + </para> + </listitem> + </itemizedlist> + + Refer to the <acronym>SQL</acronym> command <xref linkend="sql-set"/> + for information on correct values for these + environment variables. + </para> + + <para> + The following environment variables determine internal behavior of + <application>libpq</application>; they override compiled-in defaults. + + <itemizedlist> + <listitem> + <para> + <indexterm> + <primary><envar>PGSYSCONFDIR</envar></primary> + </indexterm> + <envar>PGSYSCONFDIR</envar> sets the directory containing the + <filename>pg_service.conf</filename> file and in a future version + possibly other system-wide configuration files. + </para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGLOCALEDIR</envar></primary> + </indexterm> + <envar>PGLOCALEDIR</envar> sets the directory containing the + <literal>locale</literal> files for message localization. + </para> + </listitem> + </itemizedlist> + </para> + + </sect1> + + + <sect1 id="libpq-pgpass"> + <title>The Password File</title> + + <indexterm zone="libpq-pgpass"> + <primary>password file</primary> + </indexterm> + <indexterm zone="libpq-pgpass"> + <primary>.pgpass</primary> + </indexterm> + + <para> + The file <filename>.pgpass</filename> in a user's home directory can + contain passwords to + be used if the connection requires a password (and no password has been + specified otherwise). On Microsoft Windows the file is named + <filename>%APPDATA%\postgresql\pgpass.conf</filename> (where + <filename>%APPDATA%</filename> refers to the Application Data subdirectory in + the user's profile). + Alternatively, the password file to use can be specified + using the connection parameter <xref linkend="libpq-connect-passfile"/> + or the environment variable <envar>PGPASSFILE</envar>. + </para> + + <para> + This file should contain lines of the following format: +<synopsis> +<replaceable>hostname</replaceable>:<replaceable>port</replaceable>:<replaceable>database</replaceable>:<replaceable>username</replaceable>:<replaceable>password</replaceable> +</synopsis> + (You can add a reminder comment to the file by copying the line above and + preceding it with <literal>#</literal>.) + Each of the first four fields can be a literal value, or + <literal>*</literal>, which matches anything. The password field from + the first line that matches the current connection parameters will be + used. (Therefore, put more-specific entries first when you are using + wildcards.) If an entry needs to contain <literal>:</literal> or + <literal>\</literal>, escape this character with <literal>\</literal>. + The host name field is matched to the <literal>host</literal> connection + parameter if that is specified, otherwise to + the <literal>hostaddr</literal> parameter if that is specified; if neither + are given then the host name <literal>localhost</literal> is searched for. + The host name <literal>localhost</literal> is also searched for when + the connection is a Unix-domain socket connection and + the <literal>host</literal> parameter + matches <application>libpq</application>'s default socket directory path. + In a standby server, a database field of <literal>replication</literal> + matches streaming replication connections made to the primary server. + The database field is of limited usefulness otherwise, because users have + the same password for all databases in the same cluster. + </para> + + <para> + On Unix systems, the permissions on a password file must + disallow any access to world or group; achieve this by a command such as + <command>chmod 0600 ~/.pgpass</command>. If the permissions are less + strict than this, the file will be ignored. On Microsoft Windows, it + is assumed that the file is stored in a directory that is secure, so + no special permissions check is made. + </para> + </sect1> + + + <sect1 id="libpq-pgservice"> + <title>The Connection Service File</title> + + <indexterm zone="libpq-pgservice"> + <primary>connection service file</primary> + </indexterm> + <indexterm zone="libpq-pgservice"> + <primary>pg_service.conf</primary> + </indexterm> + <indexterm zone="libpq-pgservice"> + <primary>.pg_service.conf</primary> + </indexterm> + + <para> + The connection service file allows libpq connection parameters to be + associated with a single service name. That service name can then be + specified in a libpq connection string, and the associated settings will be + used. This allows connection parameters to be modified without requiring + a recompile of the libpq-using application. The service name can also be + specified using the <envar>PGSERVICE</envar> environment variable. + </para> + + <para> + Service names can be defined in either a per-user service file or a + system-wide file. If the same service name exists in both the user + and the system file, the user file takes precedence. + By default, the per-user service file is named + <filename>~/.pg_service.conf</filename>. + On Microsoft Windows, it is named + <filename>%APPDATA%\postgresql\.pg_service.conf</filename> (where + <filename>%APPDATA%</filename> refers to the Application Data subdirectory + in the user's profile). A different file name can be specified by + setting the environment variable <envar>PGSERVICEFILE</envar>. + The system-wide file is named <filename>pg_service.conf</filename>. + By default it is sought in the <filename>etc</filename> directory + of the <productname>PostgreSQL</productname> installation + (use <literal>pg_config --sysconfdir</literal> to identify this + directory precisely). Another directory, but not a different file + name, can be specified by setting the environment variable + <envar>PGSYSCONFDIR</envar>. + </para> + + <para> + Either service file uses an <quote>INI file</quote> format where the section + name is the service name and the parameters are connection + parameters; see <xref linkend="libpq-paramkeywords"/> for a list. For + example: +<programlisting> +# comment +[mydb] +host=somehost +port=5433 +user=admin +</programlisting> + An example file is provided in + the <productname>PostgreSQL</productname> installation at + <filename>share/pg_service.conf.sample</filename>. + </para> + + <para> + Connection parameters obtained from a service file are combined with + parameters obtained from other sources. A service file setting + overrides the corresponding environment variable, and in turn can be + overridden by a value given directly in the connection string. + For example, using the above service file, a connection string + <literal>service=mydb port=5434</literal> will use + host <literal>somehost</literal>, port <literal>5434</literal>, + user <literal>admin</literal>, and other parameters as set by + environment variables or built-in defaults. + </para> + </sect1> + + + <sect1 id="libpq-ldap"> + <title>LDAP Lookup of Connection Parameters</title> + + <indexterm zone="libpq-ldap"> + <primary>LDAP connection parameter lookup</primary> + </indexterm> + + <para> + If <application>libpq</application> has been compiled with LDAP support (option + <literal><option>--with-ldap</option></literal> for <command>configure</command>) + it is possible to retrieve connection options like <literal>host</literal> + or <literal>dbname</literal> via LDAP from a central server. + The advantage is that if the connection parameters for a database change, + the connection information doesn't have to be updated on all client machines. + </para> + + <para> + LDAP connection parameter lookup uses the connection service file + <filename>pg_service.conf</filename> (see <xref + linkend="libpq-pgservice"/>). A line in a + <filename>pg_service.conf</filename> stanza that starts with + <literal>ldap://</literal> will be recognized as an LDAP URL and an + LDAP query will be performed. The result must be a list of + <literal>keyword = value</literal> pairs which will be used to set + connection options. The URL must conform to + <ulink url="https://tools.ietf.org/html/rfc1959">RFC 1959</ulink> + and be of the form +<synopsis> +ldap://[<replaceable>hostname</replaceable>[:<replaceable>port</replaceable>]]/<replaceable>search_base</replaceable>?<replaceable>attribute</replaceable>?<replaceable>search_scope</replaceable>?<replaceable>filter</replaceable> +</synopsis> + where <replaceable>hostname</replaceable> defaults to + <literal>localhost</literal> and <replaceable>port</replaceable> + defaults to 389. + </para> + + <para> + Processing of <filename>pg_service.conf</filename> is terminated after + a successful LDAP lookup, but is continued if the LDAP server cannot + be contacted. This is to provide a fallback with further LDAP URL + lines that point to different LDAP servers, classical <literal>keyword + = value</literal> pairs, or default connection options. If you would + rather get an error message in this case, add a syntactically incorrect + line after the LDAP URL. + </para> + + <para> + A sample LDAP entry that has been created with the LDIF file +<programlisting> +version:1 +dn:cn=mydatabase,dc=mycompany,dc=com +changetype:add +objectclass:top +objectclass:device +cn:mydatabase +description:host=dbserver.mycompany.com +description:port=5439 +description:dbname=mydb +description:user=mydb_user +description:sslmode=require +</programlisting> + might be queried with the following LDAP URL: +<programlisting> +ldap://ldap.mycompany.com/dc=mycompany,dc=com?description?one?(cn=mydatabase) +</programlisting> + </para> + + <para> + You can also mix regular service file entries with LDAP lookups. + A complete example for a stanza in <filename>pg_service.conf</filename> + would be: +<programlisting> +# only host and port are stored in LDAP, specify dbname and user explicitly +[customerdb] +dbname=customer +user=appuser +ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) +</programlisting> + </para> + + </sect1> + + + <sect1 id="libpq-ssl"> + <title>SSL Support</title> + + <indexterm zone="libpq-ssl"> + <primary>SSL</primary> + <secondary>TLS</secondary> + </indexterm> + + <para> + <productname>PostgreSQL</productname> has native support for using <acronym>SSL</acronym> + connections to encrypt client/server communications using + <acronym>TLS</acronym> protocols for increased security. + See <xref linkend="ssl-tcp"/> for details about the server-side + <acronym>SSL</acronym> functionality. + </para> + + <para> + <application>libpq</application> reads the system-wide + <productname>OpenSSL</productname> configuration file. By default, this + file is named <filename>openssl.cnf</filename> and is located in the + directory reported by <literal>openssl version -d</literal>. This default + can be overridden by setting environment variable + <envar>OPENSSL_CONF</envar> to the name of the desired configuration + file. + </para> + + <sect2 id="libq-ssl-certificates"> + <title>Client Verification of Server Certificates</title> + + <para> + By default, <productname>PostgreSQL</productname> will not perform any verification of + the server certificate. This means that it is possible to spoof the server + identity (for example by modifying a DNS record or by taking over the server + IP address) without the client knowing. In order to prevent spoofing, + the client must be able to verify the server's identity via a chain of + trust. A chain of trust is established by placing a root (self-signed) + certificate authority (<acronym>CA</acronym>) certificate on one + computer and a leaf certificate <emphasis>signed</emphasis> by the + root certificate on another computer. It is also possible to use an + <quote>intermediate</quote> certificate which is signed by the root + certificate and signs leaf certificates. + </para> + + <para> + To allow the client to verify the identity of the server, place a root + certificate on the client and a leaf certificate signed by the root + certificate on the server. To allow the server to verify the identity + of the client, place a root certificate on the server and a leaf + certificate signed by the root certificate on the client. One or more + intermediate certificates (usually stored with the leaf certificate) + can also be used to link the leaf certificate to the root certificate. + </para> + + <para> + Once a chain of trust has been established, there are two ways for + the client to validate the leaf certificate sent by the server. + If the parameter <literal>sslmode</literal> is set to <literal>verify-ca</literal>, + libpq will verify that the server is trustworthy by checking the + certificate chain up to the root certificate stored on the client. + If <literal>sslmode</literal> is set to <literal>verify-full</literal>, + libpq will <emphasis>also</emphasis> verify that the server host + name matches the name stored in the server certificate. The + SSL connection will fail if the server certificate cannot be + verified. <literal>verify-full</literal> is recommended in most + security-sensitive environments. + </para> + + <para> + In <literal>verify-full</literal> mode, the host name is matched against the + certificate's Subject Alternative Name attribute(s) (SAN), or against the + Common Name attribute if no SAN of type <literal>dNSName</literal> is + present. If the certificate's name attribute starts with an asterisk + (<literal>*</literal>), the asterisk will be treated as + a wildcard, which will match all characters <emphasis>except</emphasis> a dot + (<literal>.</literal>). This means the certificate will not match subdomains. + If the connection is made using an IP address instead of a host name, the + IP address will be matched (without doing any DNS lookups) against SANs of + type <literal>iPAddress</literal> or <literal>dNSName</literal>. If no + <literal>iPAddress</literal> SAN is present and no + matching <literal>dNSName</literal> SAN is present, the host IP address is + matched against the Common Name attribute. + </para> + + <note> + <para> + For backward compatibility with earlier versions of PostgreSQL, the host + IP address is verified in a manner different + from <ulink url="https://tools.ietf.org/html/rfc6125">RFC 6125</ulink>. + The host IP address is always matched against <literal>dNSName</literal> + SANs as well as <literal>iPAddress</literal> SANs, and can be matched + against the Common Name attribute if no relevant SANs exist. + </para> + </note> + + <para> + To allow server certificate verification, one or more root certificates + must be placed in the file <filename>~/.postgresql/root.crt</filename> + in the user's home directory. (On Microsoft Windows the file is named + <filename>%APPDATA%\postgresql\root.crt</filename>.) Intermediate + certificates should also be added to the file if they are needed to link + the certificate chain sent by the server to the root certificates + stored on the client. + </para> + + <para> + Certificate Revocation List (CRL) entries are also checked + if the file <filename>~/.postgresql/root.crl</filename> exists + (<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft + Windows). + </para> + + <para> + The location of the root certificate file and the CRL can be changed by + setting + the connection parameters <literal>sslrootcert</literal> and <literal>sslcrl</literal> + or the environment variables <envar>PGSSLROOTCERT</envar> and <envar>PGSSLCRL</envar>. + <literal>sslcrldir</literal> or the environment variable <envar>PGSSLCRLDIR</envar> + can also be used to specify a directory containing CRL files. + </para> + + <note> + <para> + For backwards compatibility with earlier versions of PostgreSQL, if a + root CA file exists, the behavior of + <literal>sslmode</literal>=<literal>require</literal> will be the same + as that of <literal>verify-ca</literal>, meaning the server certificate + is validated against the CA. Relying on this behavior is discouraged, + and applications that need certificate validation should always use + <literal>verify-ca</literal> or <literal>verify-full</literal>. + </para> + </note> + </sect2> + + <sect2 id="libpq-ssl-clientcert"> + <title>Client Certificates</title> + + <para> + If the server attempts to verify the identity of the + client by requesting the client's leaf certificate, + <application>libpq</application> will send the certificate(s) stored in + file <filename>~/.postgresql/postgresql.crt</filename> in the user's home + directory. The certificates must chain to the root certificate trusted + by the server. A matching + private key file <filename>~/.postgresql/postgresql.key</filename> must also + be present. + On Microsoft Windows these files are named + <filename>%APPDATA%\postgresql\postgresql.crt</filename> and + <filename>%APPDATA%\postgresql\postgresql.key</filename>. + The location of the certificate and key files can be overridden by the + connection parameters <literal>sslcert</literal> + and <literal>sslkey</literal>, or by the + environment variables <envar>PGSSLCERT</envar> and <envar>PGSSLKEY</envar>. + </para> + + <para> + On Unix systems, the permissions on the private key file must disallow + any access to world or group; achieve this by a command such as + <command>chmod 0600 ~/.postgresql/postgresql.key</command>. + Alternatively, the file can be owned by root and have group read access + (that is, <literal>0640</literal> permissions). That setup is intended + for installations where certificate and key files are managed by the + operating system. The user of <application>libpq</application> should + then be made a member of the group that has access to those certificate + and key files. (On Microsoft Windows, there is no file permissions + check, since the <filename>%APPDATA%\postgresql</filename> directory is + presumed secure.) + </para> + + <para> + The first certificate in <filename>postgresql.crt</filename> must be the + client's certificate because it must match the client's private key. + <quote>Intermediate</quote> certificates can be optionally appended + to the file — doing so avoids requiring storage of intermediate + certificates on the server (<xref linkend="guc-ssl-ca-file"/>). + </para> + + <para> + The certificate and key may be in PEM or ASN.1 DER format. + </para> + + <para> + The key may be + stored in cleartext or encrypted with a passphrase using any algorithm + supported by <productname>OpenSSL</productname>, like AES-128. If the key + is stored encrypted, then the passphrase may be provided in the + <xref linkend="libpq-connect-sslpassword"/> connection option. If an + encrypted key is supplied and the <literal>sslpassword</literal> option + is absent or blank, a password will be prompted for interactively by + <productname>OpenSSL</productname> with a + <literal>Enter PEM pass phrase:</literal> prompt if a TTY is available. + Applications can override the client certificate prompt and the handling + of the <literal>sslpassword</literal> parameter by supplying their own + key password callback; see + <xref linkend="libpq-pqsetsslkeypasshook-openssl"/>. + </para> + + <para> + For instructions on creating certificates, see <xref + linkend="ssl-certificate-creation"/>. + </para> + </sect2> + + <sect2 id="libpq-ssl-protection"> + <title>Protection Provided in Different Modes</title> + + <para> + The different values for the <literal>sslmode</literal> parameter provide different + levels of protection. SSL can provide + protection against three types of attacks: + + <variablelist> + <varlistentry> + <term>Eavesdropping</term> + <listitem> + <para>If a third party can examine the network traffic between the + client and the server, it can read both connection information (including + the user name and password) and the data that is passed. <acronym>SSL</acronym> + uses encryption to prevent this. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Man-in-the-middle (<acronym>MITM</acronym>)</term> + <listitem> + <para>If a third party can modify the data while passing between the + client and server, it can pretend to be the server and therefore see and + modify data <emphasis>even if it is encrypted</emphasis>. The third party can then + forward the connection information and data to the original server, + making it impossible to detect this attack. Common vectors to do this + include DNS poisoning and address hijacking, whereby the client is directed + to a different server than intended. There are also several other + attack methods that can accomplish this. <acronym>SSL</acronym> uses certificate + verification to prevent this, by authenticating the server to the client. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Impersonation</term> + <listitem> + <para>If a third party can pretend to be an authorized client, it can + simply access data it should not have access to. Typically this can + happen through insecure password management. <acronym>SSL</acronym> uses + client certificates to prevent this, by making sure that only holders + of valid certificates can access the server. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + For a connection to be known SSL-secured, SSL usage must be configured + on <emphasis>both the client and the server</emphasis> before the connection + is made. If it is only configured on the server, the client may end up + sending sensitive information (e.g., passwords) before + it knows that the server requires high security. In libpq, secure + connections can be ensured + by setting the <literal>sslmode</literal> parameter to <literal>verify-full</literal> or + <literal>verify-ca</literal>, and providing the system with a root certificate to + verify against. This is analogous to using an <literal>https</literal> + <acronym>URL</acronym> for encrypted web browsing. + </para> + + <para> + Once the server has been authenticated, the client can pass sensitive data. + This means that up until this point, the client does not need to know if + certificates will be used for authentication, making it safe to specify that + only in the server configuration. + </para> + + <para> + All <acronym>SSL</acronym> options carry overhead in the form of encryption and + key-exchange, so there is a trade-off that has to be made between performance + and security. <xref linkend="libpq-ssl-sslmode-statements"/> + illustrates the risks the different <literal>sslmode</literal> values + protect against, and what statement they make about security and overhead. + </para> + + <table id="libpq-ssl-sslmode-statements"> + <title>SSL Mode Descriptions</title> + <tgroup cols="4"> + <colspec colname="col1" colwidth="1*"/> + <colspec colname="col2" colwidth="1*"/> + <colspec colname="col3" colwidth="1*"/> + <colspec colname="col4" colwidth="2*"/> + <thead> + <row> + <entry><literal>sslmode</literal></entry> + <entry>Eavesdropping protection</entry> + <entry><acronym>MITM</acronym> protection</entry> + <entry>Statement</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>disable</literal></entry> + <entry>No</entry> + <entry>No</entry> + <entry>I don't care about security, and I don't want to pay the overhead + of encryption. + </entry> + </row> + + <row> + <entry><literal>allow</literal></entry> + <entry>Maybe</entry> + <entry>No</entry> + <entry>I don't care about security, but I will pay the overhead of + encryption if the server insists on it. + </entry> + </row> + + <row> + <entry><literal>prefer</literal></entry> + <entry>Maybe</entry> + <entry>No</entry> + <entry>I don't care about encryption, but I wish to pay the overhead of + encryption if the server supports it. + </entry> + </row> + + <row> + <entry><literal>require</literal></entry> + <entry>Yes</entry> + <entry>No</entry> + <entry>I want my data to be encrypted, and I accept the overhead. I trust + that the network will make sure I always connect to the server I want. + </entry> + </row> + + <row> + <entry><literal>verify-ca</literal></entry> + <entry>Yes</entry> + <entry>Depends on CA policy</entry> + <entry>I want my data encrypted, and I accept the overhead. I want to be + sure that I connect to a server that I trust. + </entry> + </row> + + <row> + <entry><literal>verify-full</literal></entry> + <entry>Yes</entry> + <entry>Yes</entry> + <entry>I want my data encrypted, and I accept the overhead. I want to be + sure that I connect to a server I trust, and that it's the one I + specify. + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <para> + The difference between <literal>verify-ca</literal> and <literal>verify-full</literal> + depends on the policy of the root <acronym>CA</acronym>. If a public + <acronym>CA</acronym> is used, <literal>verify-ca</literal> allows connections to a server + that <emphasis>somebody else</emphasis> may have registered with the <acronym>CA</acronym>. + In this case, <literal>verify-full</literal> should always be used. If + a local <acronym>CA</acronym> is used, or even a self-signed certificate, using + <literal>verify-ca</literal> often provides enough protection. + </para> + + <para> + The default value for <literal>sslmode</literal> is <literal>prefer</literal>. As is shown + in the table, this makes no sense from a security point of view, and it only + promises performance overhead if possible. It is only provided as the default + for backward compatibility, and is not recommended in secure deployments. + </para> + + </sect2> + + <sect2 id="libpq-ssl-fileusage"> + <title>SSL Client File Usage</title> + + <para> + <xref linkend="libpq-ssl-file-usage"/> summarizes the files that are + relevant to the SSL setup on the client. + </para> + + <table id="libpq-ssl-file-usage"> + <title>Libpq/Client SSL File Usage</title> + <tgroup cols="3"> + <thead> + <row> + <entry>File</entry> + <entry>Contents</entry> + <entry>Effect</entry> + </row> + </thead> + + <tbody> + + <row> + <entry><filename>~/.postgresql/postgresql.crt</filename></entry> + <entry>client certificate</entry> + <entry>sent to server</entry> + </row> + + <row> + <entry><filename>~/.postgresql/postgresql.key</filename></entry> + <entry>client private key</entry> + <entry>proves client certificate sent by owner; does not indicate + certificate owner is trustworthy</entry> + </row> + + <row> + <entry><filename>~/.postgresql/root.crt</filename></entry> + <entry>trusted certificate authorities</entry> + <entry>checks that server certificate is signed by a trusted certificate + authority</entry> + </row> + + <row> + <entry><filename>~/.postgresql/root.crl</filename></entry> + <entry>certificates revoked by certificate authorities</entry> + <entry>server certificate must not be on this list</entry> + </row> + + </tbody> + </tgroup> + </table> + </sect2> + + <sect2 id="libpq-ssl-initialize"> + <title>SSL Library Initialization</title> + + <para> + If your application initializes <literal>libssl</literal> and/or + <literal>libcrypto</literal> libraries and <application>libpq</application> + is built with <acronym>SSL</acronym> support, you should call + <xref linkend="libpq-PQinitOpenSSL"/> to tell <application>libpq</application> + that the <literal>libssl</literal> and/or <literal>libcrypto</literal> libraries + have been initialized by your application, so that + <application>libpq</application> will not also initialize those libraries. + However, this is unnecessary when using <productname>OpenSSL</productname> + version 1.1.0 or later, as duplicate initializations are no longer problematic. + </para> + + <para> + <variablelist> + <varlistentry id="libpq-PQinitOpenSSL"> + <term><function>PQinitOpenSSL</function><indexterm><primary>PQinitOpenSSL</primary></indexterm></term> + + <listitem> + <para> + Allows applications to select which security libraries to initialize. +<synopsis> +void PQinitOpenSSL(int do_ssl, int do_crypto); +</synopsis> + </para> + + <para> + When <parameter>do_ssl</parameter> is non-zero, <application>libpq</application> + will initialize the <productname>OpenSSL</productname> library before first + opening a database connection. When <parameter>do_crypto</parameter> is + non-zero, the <literal>libcrypto</literal> library will be initialized. By + default (if <xref linkend="libpq-PQinitOpenSSL"/> is not called), both libraries + are initialized. When SSL support is not compiled in, this function is + present but does nothing. + </para> + + <para> + If your application uses and initializes either <productname>OpenSSL</productname> + or its underlying <literal>libcrypto</literal> library, you <emphasis>must</emphasis> + call this function with zeroes for the appropriate parameter(s) + before first opening a database connection. Also be sure that you + have done that initialization before opening a database connection. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-PQinitSSL"> + <term><function>PQinitSSL</function><indexterm><primary>PQinitSSL</primary></indexterm></term><listitem> + <para> + Allows applications to select which security libraries to initialize. +<synopsis> +void PQinitSSL(int do_ssl); +</synopsis> + </para> + + <para> + This function is equivalent to + <literal>PQinitOpenSSL(do_ssl, do_ssl)</literal>. + It is sufficient for applications that initialize both or neither + of <productname>OpenSSL</productname> and <literal>libcrypto</literal>. + </para> + + <para> + <xref linkend="libpq-PQinitSSL"/> has been present since + <productname>PostgreSQL</productname> 8.0, while <xref linkend="libpq-PQinitOpenSSL"/> + was added in <productname>PostgreSQL</productname> 8.4, so <xref linkend="libpq-PQinitSSL"/> + might be preferable for applications that need to work with older + versions of <application>libpq</application>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect2> + + </sect1> + + + <sect1 id="libpq-threading"> + <title>Behavior in Threaded Programs</title> + + <indexterm zone="libpq-threading"> + <primary>threads</primary> + <secondary>with libpq</secondary> + </indexterm> + + <para> + <application>libpq</application> is reentrant and thread-safe by default. + You might need to use special compiler command-line + options when you compile your application code. Refer to your + system's documentation for information about how to build + thread-enabled applications, or look in + <filename>src/Makefile.global</filename> for <literal>PTHREAD_CFLAGS</literal> + and <literal>PTHREAD_LIBS</literal>. This function allows the querying of + <application>libpq</application>'s thread-safe status: + </para> + + <variablelist> + <varlistentry id="libpq-PQisthreadsafe"> + <term><function>PQisthreadsafe</function><indexterm><primary>PQisthreadsafe</primary></indexterm></term> + + <listitem> + <para> + Returns the thread safety status of the + <application>libpq</application> library. +<synopsis> +int PQisthreadsafe(); +</synopsis> + </para> + + <para> + Returns 1 if the <application>libpq</application> is thread-safe + and 0 if it is not. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + One thread restriction is that no two threads attempt to manipulate + the same <structname>PGconn</structname> object at the same time. In particular, + you cannot issue concurrent commands from different threads through + the same connection object. (If you need to run concurrent commands, + use multiple connections.) + </para> + + <para> + <structname>PGresult</structname> objects are normally read-only after creation, + and so can be passed around freely between threads. However, if you use + any of the <structname>PGresult</structname>-modifying functions described in + <xref linkend="libpq-misc"/> or <xref linkend="libpq-events"/>, it's up + to you to avoid concurrent operations on the same <structname>PGresult</structname>, + too. + </para> + + <para> + The deprecated functions <xref linkend="libpq-PQrequestCancel"/> and + <xref linkend="libpq-PQoidStatus"/> are not thread-safe and should not be + used in multithread programs. <xref linkend="libpq-PQrequestCancel"/> + can be replaced by <xref linkend="libpq-PQcancel"/>. + <xref linkend="libpq-PQoidStatus"/> can be replaced by + <xref linkend="libpq-PQoidValue"/>. + </para> + + <para> + If you are using Kerberos inside your application (in addition to inside + <application>libpq</application>), you will need to do locking around + Kerberos calls because Kerberos functions are not thread-safe. See + function <function>PQregisterThreadLock</function> in the + <application>libpq</application> source code for a way to do cooperative + locking between <application>libpq</application> and your application. + </para> + </sect1> + + + <sect1 id="libpq-build"> + <title>Building <application>libpq</application> Programs</title> + + <indexterm zone="libpq-build"> + <primary>compiling</primary> + <secondary>libpq applications</secondary> + </indexterm> + + <para> + To build (i.e., compile and link) a program using + <application>libpq</application> you need to do all of the following + things: + + <itemizedlist> + <listitem> + <para> + Include the <filename>libpq-fe.h</filename> header file: +<programlisting> +#include <libpq-fe.h> +</programlisting> + If you failed to do that then you will normally get error messages + from your compiler similar to: +<screen> +foo.c: In function `main': +foo.c:34: `PGconn' undeclared (first use in this function) +foo.c:35: `PGresult' undeclared (first use in this function) +foo.c:54: `CONNECTION_BAD' undeclared (first use in this function) +foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function) +foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function) +</screen> + </para> + </listitem> + + <listitem> + <para> + Point your compiler to the directory where the <productname>PostgreSQL</productname> header + files were installed, by supplying the + <literal>-I<replaceable>directory</replaceable></literal> option + to your compiler. (In some cases the compiler will look into + the directory in question by default, so you can omit this + option.) For instance, your compile command line could look + like: +<programlisting> +cc -c -I/usr/local/pgsql/include testprog.c +</programlisting> + If you are using makefiles then add the option to the + <varname>CPPFLAGS</varname> variable: +<programlisting> +CPPFLAGS += -I/usr/local/pgsql/include +</programlisting> + </para> + + <para> + If there is any chance that your program might be compiled by + other users then you should not hardcode the directory location + like that. Instead, you can run the utility + <command>pg_config</command><indexterm><primary>pg_config</primary><secondary + sortas="libpq">with libpq</secondary></indexterm> to find out where the header + files are on the local system: +<screen> +<prompt>$</prompt> pg_config --includedir +<computeroutput>/usr/local/include</computeroutput> +</screen> + </para> + + <para> + If you + have <command>pkg-config</command><indexterm><primary>pkg-config</primary><secondary sortas="libpq">with + libpq</secondary></indexterm> installed, you can run instead: +<screen> +<prompt>$</prompt> pkg-config --cflags libpq +<computeroutput>-I/usr/local/include</computeroutput> +</screen> + Note that this will already include the <option>-I</option> in front of + the path. + </para> + + <para> + Failure to specify the correct option to the compiler will + result in an error message such as: +<screen> +testlibpq.c:8:22: libpq-fe.h: No such file or directory +</screen> + </para> + </listitem> + + <listitem> + <para> + When linking the final program, specify the option + <literal>-lpq</literal> so that the <application>libpq</application> + library gets pulled in, as well as the option + <literal>-L<replaceable>directory</replaceable></literal> to point + the compiler to the directory where the + <application>libpq</application> library resides. (Again, the + compiler will search some directories by default.) For maximum + portability, put the <option>-L</option> option before the + <option>-lpq</option> option. For example: +<programlisting> +cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq +</programlisting> + </para> + + <para> + You can find out the library directory using + <command>pg_config</command> as well: +<screen> +<prompt>$</prompt> pg_config --libdir +<computeroutput>/usr/local/pgsql/lib</computeroutput> +</screen> + </para> + + <para> + Or again use <command>pkg-config</command>: +<screen> +<prompt>$</prompt> pkg-config --libs libpq +<computeroutput>-L/usr/local/pgsql/lib -lpq</computeroutput> +</screen> + Note again that this prints the full options, not only the path. + </para> + + <para> + Error messages that point to problems in this area could look like + the following: +<screen> +testlibpq.o: In function `main': +testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin' +testlibpq.o(.text+0x71): undefined reference to `PQstatus' +testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage' +</screen> + This means you forgot <option>-lpq</option>. +<screen> +/usr/bin/ld: cannot find -lpq +</screen> + This means you forgot the <option>-L</option> option or did not + specify the right directory. + </para> + </listitem> + </itemizedlist> + </para> + + </sect1> + + + <sect1 id="libpq-example"> + <title>Example Programs</title> + + <para> + These examples and others can be found in the + directory <filename>src/test/examples</filename> in the source code + distribution. + </para> + + <example id="libpq-example-1"> + <title><application>libpq</application> Example Program 1</title> + +<programlisting> +<![CDATA[ +/* + * src/test/examples/testlibpq.c + * + * + * testlibpq.c + * + * Test the C version of libpq, the PostgreSQL frontend library. + */ +#include <stdio.h> +#include <stdlib.h> +#include "libpq-fe.h" + +static void +exit_nicely(PGconn *conn) +{ + PQfinish(conn); + exit(1); +} + +int +main(int argc, char **argv) +{ + const char *conninfo; + PGconn *conn; + PGresult *res; + int nFields; + int i, + j; + + /* + * If the user supplies a parameter on the command line, use it as the + * conninfo string; otherwise default to setting dbname=postgres and using + * environment variables or defaults for all other connection parameters. + */ + if (argc > 1) + conninfo = argv[1]; + else + conninfo = "dbname = postgres"; + + /* Make a connection to the database */ + conn = PQconnectdb(conninfo); + + /* Check to see that the backend connection was successfully made */ + if (PQstatus(conn) != CONNECTION_OK) + { + fprintf(stderr, "%s", PQerrorMessage(conn)); + exit_nicely(conn); + } + + /* Set always-secure search path, so malicious users can't take control. */ + res = PQexec(conn, + "SELECT pg_catalog.set_config('search_path', '', false)"); + if (PQresultStatus(res) != PGRES_TUPLES_OK) + { + fprintf(stderr, "SET failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + + /* + * Should PQclear PGresult whenever it is no longer needed to avoid memory + * leaks + */ + PQclear(res); + + /* + * Our test case here involves using a cursor, for which we must be inside + * a transaction block. We could do the whole thing with a single + * PQexec() of "select * from pg_database", but that's too trivial to make + * a good example. + */ + + /* Start a transaction block */ + res = PQexec(conn, "BEGIN"); + if (PQresultStatus(res) != PGRES_COMMAND_OK) + { + fprintf(stderr, "BEGIN command failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + PQclear(res); + + /* + * Fetch rows from pg_database, the system catalog of databases + */ + res = PQexec(conn, "DECLARE myportal CURSOR FOR select * from pg_database"); + if (PQresultStatus(res) != PGRES_COMMAND_OK) + { + fprintf(stderr, "DECLARE CURSOR failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + PQclear(res); + + res = PQexec(conn, "FETCH ALL in myportal"); + if (PQresultStatus(res) != PGRES_TUPLES_OK) + { + fprintf(stderr, "FETCH ALL failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + + /* first, print out the attribute names */ + nFields = PQnfields(res); + for (i = 0; i < nFields; i++) + printf("%-15s", PQfname(res, i)); + printf("\n\n"); + + /* next, print out the rows */ + for (i = 0; i < PQntuples(res); i++) + { + for (j = 0; j < nFields; j++) + printf("%-15s", PQgetvalue(res, i, j)); + printf("\n"); + } + + PQclear(res); + + /* close the portal ... we don't bother to check for errors ... */ + res = PQexec(conn, "CLOSE myportal"); + PQclear(res); + + /* end the transaction */ + res = PQexec(conn, "END"); + PQclear(res); + + /* close the connection to the database and cleanup */ + PQfinish(conn); + + return 0; +} +]]> +</programlisting> + </example> + + <example id="libpq-example-2"> + <title><application>libpq</application> Example Program 2</title> + +<programlisting> +<![CDATA[ +/* + * src/test/examples/testlibpq2.c + * + * + * testlibpq2.c + * Test of the asynchronous notification interface + * + * Start this program, then from psql in another window do + * NOTIFY TBL2; + * Repeat four times to get this program to exit. + * + * Or, if you want to get fancy, try this: + * populate a database with the following commands + * (provided in src/test/examples/testlibpq2.sql): + * + * CREATE SCHEMA TESTLIBPQ2; + * SET search_path = TESTLIBPQ2; + * CREATE TABLE TBL1 (i int4); + * CREATE TABLE TBL2 (i int4); + * CREATE RULE r1 AS ON INSERT TO TBL1 DO + * (INSERT INTO TBL2 VALUES (new.i); NOTIFY TBL2); + * + * Start this program, then from psql do this four times: + * + * INSERT INTO TESTLIBPQ2.TBL1 VALUES (10); + */ + +#ifdef WIN32 +#include <windows.h> +#endif +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <errno.h> +#include <sys/select.h> +#include <sys/time.h> +#include <sys/types.h> + +#include "libpq-fe.h" + +static void +exit_nicely(PGconn *conn) +{ + PQfinish(conn); + exit(1); +} + +int +main(int argc, char **argv) +{ + const char *conninfo; + PGconn *conn; + PGresult *res; + PGnotify *notify; + int nnotifies; + + /* + * If the user supplies a parameter on the command line, use it as the + * conninfo string; otherwise default to setting dbname=postgres and using + * environment variables or defaults for all other connection parameters. + */ + if (argc > 1) + conninfo = argv[1]; + else + conninfo = "dbname = postgres"; + + /* Make a connection to the database */ + conn = PQconnectdb(conninfo); + + /* Check to see that the backend connection was successfully made */ + if (PQstatus(conn) != CONNECTION_OK) + { + fprintf(stderr, "%s", PQerrorMessage(conn)); + exit_nicely(conn); + } + + /* Set always-secure search path, so malicious users can't take control. */ + res = PQexec(conn, + "SELECT pg_catalog.set_config('search_path', '', false)"); + if (PQresultStatus(res) != PGRES_TUPLES_OK) + { + fprintf(stderr, "SET failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + + /* + * Should PQclear PGresult whenever it is no longer needed to avoid memory + * leaks + */ + PQclear(res); + + /* + * Issue LISTEN command to enable notifications from the rule's NOTIFY. + */ + res = PQexec(conn, "LISTEN TBL2"); + if (PQresultStatus(res) != PGRES_COMMAND_OK) + { + fprintf(stderr, "LISTEN command failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + PQclear(res); + + /* Quit after four notifies are received. */ + nnotifies = 0; + while (nnotifies < 4) + { + /* + * Sleep until something happens on the connection. We use select(2) + * to wait for input, but you could also use poll() or similar + * facilities. + */ + int sock; + fd_set input_mask; + + sock = PQsocket(conn); + + if (sock < 0) + break; /* shouldn't happen */ + + FD_ZERO(&input_mask); + FD_SET(sock, &input_mask); + + if (select(sock + 1, &input_mask, NULL, NULL, NULL) < 0) + { + fprintf(stderr, "select() failed: %s\n", strerror(errno)); + exit_nicely(conn); + } + + /* Now check for input */ + PQconsumeInput(conn); + while ((notify = PQnotifies(conn)) != NULL) + { + fprintf(stderr, + "ASYNC NOTIFY of '%s' received from backend PID %d\n", + notify->relname, notify->be_pid); + PQfreemem(notify); + nnotifies++; + PQconsumeInput(conn); + } + } + + fprintf(stderr, "Done.\n"); + + /* close the connection to the database and cleanup */ + PQfinish(conn); + + return 0; +} +]]> +</programlisting> + </example> + + <example id="libpq-example-3"> + <title><application>libpq</application> Example Program 3</title> + +<programlisting> +<![CDATA[ +/* + * src/test/examples/testlibpq3.c + * + * + * testlibpq3.c + * Test out-of-line parameters and binary I/O. + * + * Before running this, populate a database with the following commands + * (provided in src/test/examples/testlibpq3.sql): + * + * CREATE SCHEMA testlibpq3; + * SET search_path = testlibpq3; + * SET standard_conforming_strings = ON; + * CREATE TABLE test1 (i int4, t text, b bytea); + * INSERT INTO test1 values (1, 'joe''s place', '\000\001\002\003\004'); + * INSERT INTO test1 values (2, 'ho there', '\004\003\002\001\000'); + * + * The expected output is: + * + * tuple 0: got + * i = (4 bytes) 1 + * t = (11 bytes) 'joe's place' + * b = (5 bytes) \000\001\002\003\004 + * + * tuple 0: got + * i = (4 bytes) 2 + * t = (8 bytes) 'ho there' + * b = (5 bytes) \004\003\002\001\000 + */ + +#ifdef WIN32 +#include <windows.h> +#endif + +#include <stdio.h> +#include <stdlib.h> +#include <stdint.h> +#include <string.h> +#include <sys/types.h> +#include "libpq-fe.h" + +/* for ntohl/htonl */ +#include <netinet/in.h> +#include <arpa/inet.h> + + +static void +exit_nicely(PGconn *conn) +{ + PQfinish(conn); + exit(1); +} + +/* + * This function prints a query result that is a binary-format fetch from + * a table defined as in the comment above. We split it out because the + * main() function uses it twice. + */ +static void +show_binary_results(PGresult *res) +{ + int i, + j; + int i_fnum, + t_fnum, + b_fnum; + + /* Use PQfnumber to avoid assumptions about field order in result */ + i_fnum = PQfnumber(res, "i"); + t_fnum = PQfnumber(res, "t"); + b_fnum = PQfnumber(res, "b"); + + for (i = 0; i < PQntuples(res); i++) + { + char *iptr; + char *tptr; + char *bptr; + int blen; + int ival; + + /* Get the field values (we ignore possibility they are null!) */ + iptr = PQgetvalue(res, i, i_fnum); + tptr = PQgetvalue(res, i, t_fnum); + bptr = PQgetvalue(res, i, b_fnum); + + /* + * The binary representation of INT4 is in network byte order, which + * we'd better coerce to the local byte order. + */ + ival = ntohl(*((uint32_t *) iptr)); + + /* + * The binary representation of TEXT is, well, text, and since libpq + * was nice enough to append a zero byte to it, it'll work just fine + * as a C string. + * + * The binary representation of BYTEA is a bunch of bytes, which could + * include embedded nulls so we have to pay attention to field length. + */ + blen = PQgetlength(res, i, b_fnum); + + printf("tuple %d: got\n", i); + printf(" i = (%d bytes) %d\n", + PQgetlength(res, i, i_fnum), ival); + printf(" t = (%d bytes) '%s'\n", + PQgetlength(res, i, t_fnum), tptr); + printf(" b = (%d bytes) ", blen); + for (j = 0; j < blen; j++) + printf("\\%03o", bptr[j]); + printf("\n\n"); + } +} + +int +main(int argc, char **argv) +{ + const char *conninfo; + PGconn *conn; + PGresult *res; + const char *paramValues[1]; + int paramLengths[1]; + int paramFormats[1]; + uint32_t binaryIntVal; + + /* + * If the user supplies a parameter on the command line, use it as the + * conninfo string; otherwise default to setting dbname=postgres and using + * environment variables or defaults for all other connection parameters. + */ + if (argc > 1) + conninfo = argv[1]; + else + conninfo = "dbname = postgres"; + + /* Make a connection to the database */ + conn = PQconnectdb(conninfo); + + /* Check to see that the backend connection was successfully made */ + if (PQstatus(conn) != CONNECTION_OK) + { + fprintf(stderr, "%s", PQerrorMessage(conn)); + exit_nicely(conn); + } + + /* Set always-secure search path, so malicious users can't take control. */ + res = PQexec(conn, "SET search_path = testlibpq3"); + if (PQresultStatus(res) != PGRES_COMMAND_OK) + { + fprintf(stderr, "SET failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + PQclear(res); + + /* + * The point of this program is to illustrate use of PQexecParams() with + * out-of-line parameters, as well as binary transmission of data. + * + * This first example transmits the parameters as text, but receives the + * results in binary format. By using out-of-line parameters we can avoid + * a lot of tedious mucking about with quoting and escaping, even though + * the data is text. Notice how we don't have to do anything special with + * the quote mark in the parameter value. + */ + + /* Here is our out-of-line parameter value */ + paramValues[0] = "joe's place"; + + res = PQexecParams(conn, + "SELECT * FROM test1 WHERE t = $1", + 1, /* one param */ + NULL, /* let the backend deduce param type */ + paramValues, + NULL, /* don't need param lengths since text */ + NULL, /* default to all text params */ + 1); /* ask for binary results */ + + if (PQresultStatus(res) != PGRES_TUPLES_OK) + { + fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + + show_binary_results(res); + + PQclear(res); + + /* + * In this second example we transmit an integer parameter in binary form, + * and again retrieve the results in binary form. + * + * Although we tell PQexecParams we are letting the backend deduce + * parameter type, we really force the decision by casting the parameter + * symbol in the query text. This is a good safety measure when sending + * binary parameters. + */ + + /* Convert integer value "2" to network byte order */ + binaryIntVal = htonl((uint32_t) 2); + + /* Set up parameter arrays for PQexecParams */ + paramValues[0] = (char *) &binaryIntVal; + paramLengths[0] = sizeof(binaryIntVal); + paramFormats[0] = 1; /* binary */ + + res = PQexecParams(conn, + "SELECT * FROM test1 WHERE i = $1::int4", + 1, /* one param */ + NULL, /* let the backend deduce param type */ + paramValues, + paramLengths, + paramFormats, + 1); /* ask for binary results */ + + if (PQresultStatus(res) != PGRES_TUPLES_OK) + { + fprintf(stderr, "SELECT failed: %s", PQerrorMessage(conn)); + PQclear(res); + exit_nicely(conn); + } + + show_binary_results(res); + + PQclear(res); + + /* close the connection to the database and cleanup */ + PQfinish(conn); + + return 0; +} +]]> +</programlisting> + </example> + + </sect1> +</chapter> |