mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-30 18:51:20 +02:00
78ee60ed84
This doesn't have any external effect at the moment, but it will allow adding useful link-discoverability features later. Brar Piening, reviewed by Karl Pinc. Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
9584 lines
363 KiB
Plaintext
9584 lines
363 KiB
Plaintext
<!-- 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-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-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>
|
|
</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-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>
|
|
</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>
|
|
</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, 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 but instead return
|
|
an error if they need to be called again.
|
|
</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>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>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>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>
|
|
</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.
|
|
</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>
|