mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-06 01:19:20 +02:00
5237 lines
179 KiB
Plaintext
5237 lines
179 KiB
Plaintext
<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.238 2007/07/18 12:00:47 mha Exp $ -->
|
|
|
|
<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</>.
|
|
<application>libpq</> is a set of library functions that allow
|
|
client programs to pass queries to the <productname>PostgreSQL</>
|
|
backend server and to receive the results of these queries.
|
|
</para>
|
|
|
|
<para>
|
|
<application>libpq</> is also the underlying engine for several
|
|
other <productname>PostgreSQL</> application interfaces, including
|
|
those written for C++, Perl, Python, Tcl and <application>ECPG</>.
|
|
So some aspects of <application>libpq</>'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</>.
|
|
</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</></>
|
|
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</><indexterm><primary>PGconn</></> object, which
|
|
is obtained from the function <function>PQconnectdb</> or
|
|
<function>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</> object.
|
|
The <function>PQstatus</> function should be called to check
|
|
whether a connection was successfully made before queries are sent
|
|
via the connection object.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQconnectdb</function><indexterm><primary>PQconnectdb</></></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>. Unlike <function>PQsetdbLogin</> below,
|
|
the parameter set can be extended without changing the function signature,
|
|
so use of this function (or its nonblocking analogues <function>PQconnectStart</>
|
|
and <function>PQconnectPoll</function>) is preferred for new application programming.
|
|
</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.
|
|
Each parameter setting is in the form <literal>keyword = value</literal>.
|
|
Spaces around the equal sign are optional.
|
|
To write an empty value or a value containing
|
|
spaces, surround it with single quotes, e.g.,
|
|
<literal>keyword = 'a value'</literal>.
|
|
Single quotes and backslashes within the value must be escaped with a
|
|
backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
The currently recognized parameter key words are:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>host</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Name of host to connect to.<indexterm><primary>host name</></>
|
|
If this begins with a slash, 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. The
|
|
default behavior when <literal>host</literal> is not specified
|
|
is to connect to a Unix-domain
|
|
socket<indexterm><primary>Unix domain socket</></> in
|
|
<filename>/tmp</filename> (or whatever socket directory was specified
|
|
when <productname>PostgreSQL</> was built). On machines without
|
|
Unix-domain sockets, the default is to connect to <literal>localhost</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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</>. 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.
|
|
</para>
|
|
<para>
|
|
Using <literal>hostaddr</> instead of <literal>host</> allows the
|
|
application to avoid a host name look-up, which might be important in
|
|
applications with time constraints. However, Kerberos and GSSAPI authentication
|
|
requires the host name. The following therefore applies: If
|
|
<literal>host</> is specified without <literal>hostaddr</>, a host name
|
|
lookup occurs. If <literal>hostaddr</> is specified without
|
|
<literal>host</>, the value for <literal>hostaddr</> gives the remote
|
|
address. When Kerberos is used, a reverse name query occurs to obtain
|
|
the host name for Kerberos. If both
|
|
<literal>host</> and <literal>hostaddr</> are specified, the value for
|
|
<literal>hostaddr</> gives the remote address; the value for
|
|
<literal>host</> is ignored, unless Kerberos is used, in which case that
|
|
value is used for Kerberos authentication. (Note that authentication is
|
|
likely to fail if <application>libpq</application> is passed a host name
|
|
that is not the name of the machine at <literal>hostaddr</>.) Also,
|
|
<literal>host</> rather than <literal>hostaddr</> is used to identify
|
|
the connection in <filename>~/.pgpass</> (see
|
|
<xref linkend="libpq-pgpass">).
|
|
</para>
|
|
<para>
|
|
Without either a host name or host address,
|
|
<application>libpq</application> will connect using a
|
|
local Unix-domain socket; or on machines without Unix-domain
|
|
sockets, it will attempt to connect to <literal>localhost</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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</></>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>dbname</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The database name. Defaults to be the same as the user name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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>
|
|
<term><literal>password</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Password to be used if the server demands password authentication.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>connect_timeout</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Maximum wait for connection, in seconds (write as a decimal integer
|
|
string). Zero or not specified means wait indefinitely. It is not
|
|
recommended to use a timeout of less than 2 seconds.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>options</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Command-line options to be sent to the server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>tty</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Ignored (formerly, this specified where to send server debug output).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>sslmode</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This option determines whether or with what priority an
|
|
<acronym>SSL</> connection will be negotiated with the
|
|
server. There are four modes: <literal>disable</> will attempt
|
|
only an unencrypted <acronym>SSL</> connection;
|
|
<literal>allow</> will negotiate, trying first a
|
|
non-<acronym>SSL</> connection, then if that fails, trying an
|
|
<acronym>SSL</> connection; <literal>prefer</> (the default)
|
|
will negotiate, trying first an <acronym>SSL</> connection,
|
|
then if that fails, trying a regular non-<acronym>SSL</>
|
|
connection; <literal>require</> will try only an
|
|
<acronym>SSL</> connection.
|
|
</para>
|
|
|
|
<para>
|
|
If <productname>PostgreSQL</> is compiled without SSL support,
|
|
using option <literal>require</> will cause an error, while
|
|
options <literal>allow</> and <literal>prefer</> will be
|
|
accepted but <application>libpq</> will not in fact attempt
|
|
an <acronym>SSL</>
|
|
connection.<indexterm><primary>SSL</><secondary
|
|
sortas="libpq">with libpq</></indexterm>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>requiressl</literal></term>
|
|
<listitem>
|
|
<para>
|
|
This option is deprecated in favor of the <literal>sslmode</>
|
|
setting.
|
|
</para>
|
|
|
|
<para>
|
|
If set to 1, an <acronym>SSL</acronym> connection to the server
|
|
is required (this is equivalent to <literal>sslmode</>
|
|
<literal>require</>). <application>libpq</> will then refuse
|
|
to connect if the server does not accept an
|
|
<acronym>SSL</acronym> connection. If set to 0 (default),
|
|
<application>libpq</> will negotiate the connection type with
|
|
the server (equivalent to <literal>sslmode</>
|
|
<literal>prefer</>). This option is only available if
|
|
<productname>PostgreSQL</> is compiled with SSL support.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>krbsrvname</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Kerberos service name to use when authenticating with Kerberos 5
|
|
or GSSAPI.
|
|
This must match the service name specified in the server
|
|
configuration for Kerberos authentication to succeed. (See also
|
|
<xref linkend="kerberos-auth"> and <xref linkend="gssapi-auth">.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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>
|
|
</variablelist>
|
|
|
|
If any parameter is unspecified, then the corresponding
|
|
environment variable (see <xref linkend="libpq-envars">)
|
|
is checked. If the environment variable is not set either,
|
|
then the indicated built-in defaults are used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsetdbLogin</function><indexterm><primary>PQsetdbLogin</></></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 <function>PQconnectdb</function> 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, it
|
|
is taken as a <parameter>conninfo</parameter> string in exactly the same way as
|
|
if it had been passed to <function>PQconnectdb</function>, and the remaining
|
|
parameters are then applied as above.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsetdb</function><indexterm><primary>PQsetdb</></></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 <function>PQsetdbLogin</function> with null pointers
|
|
for the <parameter>login</> and <parameter>pwd</> parameters. It is provided
|
|
for backward compatibility with very old programs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</></></term>
|
|
<term><function>PQconnectPoll</function><indexterm><primary>PQconnectPoll</></></term>
|
|
<listitem>
|
|
<para>
|
|
<indexterm><primary>nonblocking connection</primary></indexterm>
|
|
Make a connection to the database server in a nonblocking manner.
|
|
<synopsis>
|
|
PGconn *PQconnectStart(const char *conninfo);
|
|
</synopsis>
|
|
<synopsis>
|
|
PostgresPollingStatusType PQconnectPoll(PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
<para>
|
|
These two 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
|
|
<function>PQconnectdb</>, and so the application can manage this
|
|
operation in parallel with other activities.
|
|
</para>
|
|
<para>
|
|
The database connection is made using the parameters taken from the string
|
|
<literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
|
|
the same format as described above for <function>PQconnectdb</function>.
|
|
</para>
|
|
<para>
|
|
Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
|
|
restrictions are met:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
|
|
name and reverse name queries are not made. See the documentation of
|
|
these parameters under <function>PQconnectdb</function> above for details.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
If you call <function>PQtrace</function>, ensure that the stream object
|
|
into which you trace will not block.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
You 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 <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
|
|
If <varname>conn</varname> is null, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
|
|
structure. Otherwise, a valid <structname>PGconn</> pointer is returned (though not yet
|
|
representing a valid connection to the database). On return from
|
|
<function>PQconnectStart</function>, call <literal>status = PQstatus(conn)</literal>. If <varname>status</varname> equals
|
|
<symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
|
|
</para>
|
|
<para>
|
|
If <function>PQconnectStart</> succeeds, the next stage is to poll
|
|
<application>libpq</> 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.
|
|
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>poll()</>, 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.
|
|
If you have yet to call
|
|
<function>PQconnectPoll</function>, i.e., just after the call to
|
|
<function>PQconnectStart</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 <function>PQstatus</>. If this gives <symbol>CONNECTION_BAD</>, then the
|
|
connection procedure has failed; if it gives <function>CONNECTION_OK</>, then the
|
|
connection is ready. Both of these states are equally detectable
|
|
from the return value of <function>PQconnectPoll</>, 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>
|
|
<term><symbol>CONNECTION_STARTED</symbol></term>
|
|
<listitem>
|
|
<para>
|
|
Waiting for connection to be made.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>CONNECTION_MADE</symbol></term>
|
|
<listitem>
|
|
<para>
|
|
Connection OK; waiting to send.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
|
|
<listitem>
|
|
<para>
|
|
Waiting for a response from the server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>CONNECTION_AUTH_OK</symbol></term>
|
|
<listitem>
|
|
<para>
|
|
Received authentication; waiting for backend start-up to finish.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
|
|
<listitem>
|
|
<para>
|
|
Negotiating SSL encryption.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>CONNECTION_SETENV</symbol></term>
|
|
<listitem>
|
|
<para>
|
|
Negotiating environment-driven parameter settings.
|
|
</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
|
|
<function>PQconnectdb</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Note that if <function>PQconnectStart</function> returns a non-null pointer, you must call
|
|
<function>PQfinish</function> 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>
|
|
<term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></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; /* Character to display for 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 <function>PQconnectdb</function> 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</> 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. Callers
|
|
must treat the connection options data as read-only.
|
|
</para>
|
|
|
|
<para>
|
|
After processing the options array, free it by passing it to
|
|
<function>PQconninfoFree</function>. If this is not done, a small amount of memory
|
|
is leaked for each call to <function>PQconndefaults</function>.
|
|
</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfinish</function><indexterm><primary>PQfinish</></></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 <function>PQstatus</function>), the application should call <function>PQfinish</function>
|
|
to free the memory used by the <structname>PGconn</structname> object.
|
|
The <structname>PGconn</> pointer must not be used again after
|
|
<function>PQfinish</function> has been called.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQreset</function><indexterm><primary>PQreset</></></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 reestablish a new
|
|
connection to the same server, using all the same
|
|
parameters previously used. This might be useful for
|
|
error recovery if a working connection is lost.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQresetStart</function><indexterm><primary>PQresetStart</></></term>
|
|
<term><function>PQresetPoll</function><indexterm><primary>PQresetPoll</></></term>
|
|
<listitem>
|
|
<para>
|
|
Reset the communication channel to the server, in a nonblocking manner.
|
|
<synopsis>
|
|
int PQresetStart(PGconn *conn);
|
|
</synopsis>
|
|
<synopsis>
|
|
PostgresPollingStatusType PQresetPoll(PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
These functions will close the connection to the server and attempt to
|
|
reestablish a new connection to the same server, using all the same
|
|
parameters previously used. This can be useful for error recovery if a
|
|
working connection is lost. They differ from <function>PQreset</function> (above) in that they
|
|
act in a nonblocking manner. These functions suffer from the same
|
|
restrictions as <function>PQconnectStart</> and <function>PQconnectPoll</>.
|
|
</para>
|
|
<para>
|
|
To initiate a connection reset, call <function>PQresetStart</function>. 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>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</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</></>
|
|
<indexterm><primary>libpq-int.h</></>
|
|
<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</> 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 <structname>PGconn</> object.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQdb</function><indexterm><primary>PQdb</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the database name of the connection.
|
|
<synopsis>
|
|
char *PQdb(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQuser</function><indexterm><primary>PQuser</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the user name of the connection.
|
|
<synopsis>
|
|
char *PQuser(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQpass</function><indexterm><primary>PQpass</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the password of the connection.
|
|
<synopsis>
|
|
char *PQpass(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQhost</function><indexterm><primary>PQhost</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the server host name of the connection.
|
|
<synopsis>
|
|
char *PQhost(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQport</function><indexterm><primary>PQport</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the port of the connection.
|
|
<synopsis>
|
|
char *PQport(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQtty</function><indexterm><primary>PQtty</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the debug <acronym>TTY</acronym> of the connection.
|
|
(This is obsolete, since the server no longer pays attention
|
|
to the <acronym>TTY</acronym> setting, but the function remains
|
|
for backwards compatibility.)
|
|
<synopsis>
|
|
char *PQtty(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQoptions</function><indexterm><primary>PQoptions</></></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</> object.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQstatus</function><indexterm><primary>PQstatus</></></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
|
|
<function>PQfinish</function>, 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 <function>PQreset</function>.
|
|
</para>
|
|
|
|
<para>
|
|
See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
|
|
to other status codes
|
|
that might be seen.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQtransactionStatus</function><indexterm><primary>PQtransactionStatus</></></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>
|
|
<caution>
|
|
<para>
|
|
<function>PQtransactionStatus</> will give incorrect results when using
|
|
a <productname>PostgreSQL</> 7.3 server that has the parameter <literal>autocommit</>
|
|
set to off. The server-side autocommit feature has been
|
|
deprecated and does not exist in later server versions.
|
|
</para>
|
|
</caution>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQparameterStatus</function><indexterm><primary>PQparameterStatus</></></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.
|
|
<function>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
|
|
<literal>server_version</>,
|
|
<literal>server_encoding</>,
|
|
<literal>client_encoding</>,
|
|
<literal>is_superuser</>,
|
|
<literal>session_authorization</>,
|
|
<literal>DateStyle</>,
|
|
<literal>TimeZone</>,
|
|
<literal>integer_datetimes</>, and
|
|
<literal>standard_conforming_strings</>.
|
|
(<literal>server_encoding</>, <literal>TimeZone</>, and
|
|
<literal>integer_datetimes</> were not reported by releases before 8.0;
|
|
<literal>standard_conforming_strings</> was not reported by releases
|
|
before 8.1.)
|
|
Note that
|
|
<literal>server_version</>,
|
|
<literal>server_encoding</> and
|
|
<literal>integer_datetimes</>
|
|
cannot change after startup.
|
|
</para>
|
|
|
|
<para>
|
|
Pre-3.0-protocol servers do not report parameter settings, but
|
|
<application>libpq</> includes logic to obtain values for
|
|
<literal>server_version</> and <literal>client_encoding</> anyway.
|
|
Applications are encouraged to use <function>PQparameterStatus</>
|
|
rather than <foreignphrase>ad hoc</> code to determine these values.
|
|
(Beware however
|
|
that on a pre-3.0 connection, changing <literal>client_encoding</> via
|
|
<command>SET</> after connection startup will not be reflected by
|
|
<function>PQparameterStatus</>.) For <literal>server_version</>,
|
|
see also <function>PQserverVersion</>, which returns the information
|
|
in a numeric form that is much easier to compare against.
|
|
</para>
|
|
|
|
<para>
|
|
If no value for <literal>standard_conforming_strings</> is reported,
|
|
applications can assume it is <literal>off</>, 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'...'</>) is accepted.
|
|
</para>
|
|
|
|
<para>
|
|
Although the returned pointer is declared <literal>const</>, it in fact
|
|
points to mutable storage associated with the <literal>PGconn</> structure.
|
|
It is unwise to assume the pointer will remain valid across queries.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQprotocolVersion</function><indexterm><primary>PQprotocolVersion</></></term>
|
|
<listitem>
|
|
<para>
|
|
Interrogates the frontend/backend protocol being used.
|
|
<synopsis>
|
|
int PQprotocolVersion(const PGconn *conn);
|
|
</synopsis>
|
|
Applications might wish to use this to determine whether certain features
|
|
are supported.
|
|
Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol),
|
|
or zero (connection bad). This will not change after connection
|
|
startup is complete, but it could theoretically change during a connection
|
|
reset. The 3.0 protocol will normally be used when communicating with
|
|
<productname>PostgreSQL</> 7.4 or later servers; pre-7.4 servers support
|
|
only protocol 2.0. (Protocol 1.0 is obsolete and not supported by <application>libpq</application>.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQserverVersion</function><indexterm><primary>PQserverVersion</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns an integer representing the backend version.
|
|
<synopsis>
|
|
int PQserverVersion(const PGconn *conn);
|
|
</synopsis>
|
|
Applications might use this to determine the version of the database server they
|
|
are connected to. The number is formed by converting the major, minor, and
|
|
revision numbers into two-decimal-digit numbers and appending them
|
|
together. For example, version 8.1.5 will be returned as 80105, and version
|
|
8.2 will be returned as 80200 (leading zeroes are not shown). Zero is
|
|
returned if the connection is bad.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQerrorMessage</function><indexterm><primary>PQerrorMessage</></></term>
|
|
<listitem>
|
|
<para>
|
|
<indexterm><primary>error message</></>
|
|
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</> functions will set a message for
|
|
<function>PQerrorMessage</function> if they fail.
|
|
Note that by <application>libpq</application> convention, a nonempty
|
|
<function>PQerrorMessage</function> result will
|
|
include a trailing newline. The caller should not free the result
|
|
directly. It will be freed when the associated <structname>PGconn</>
|
|
handle is passed to <function>PQfinish</function>. The result string
|
|
should not be expected to remain the same across operations on the
|
|
<literal>PGconn</> structure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsocket</function><indexterm><primary>PQsocket</></></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>
|
|
<term><function>PQbackendPID</function><indexterm><primary>PQbackendPID</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the process <acronym>ID</acronym>
|
|
(PID)<indexterm><primary>PID</><secondary>determining PID of
|
|
server process</><tertiary>in libpq</></> of the backend server
|
|
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>
|
|
<term><function>PQconnectionUsedPassword</function><indexterm><primary>PQconnectionUsedPassword</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns true (1) if the connection authentication method
|
|
required a password to be supplied. Returns false (0) if not.
|
|
<synopsis>
|
|
int PQconnectionUsedPassword(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
This function can be applied after either successful or failed
|
|
connection attempts. In the case of failure, it can for example
|
|
be used to decide whether to prompt the user for a password.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQgetssl</function><indexterm><primary>PQgetssl</></></term>
|
|
<listitem>
|
|
<para>
|
|
<indexterm><primary>SSL</><secondary sortas="libpq">in libpq</secondary></indexterm>
|
|
Returns the SSL structure used in the connection, or null
|
|
if SSL is not in use.
|
|
<synopsis>
|
|
SSL *PQgetssl(const PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
This structure can be used to verify encryption levels, check
|
|
server certificates, and more. Refer to the <productname>OpenSSL</> documentation
|
|
for information about this structure.
|
|
</para>
|
|
<para>
|
|
You must define <symbol>USE_SSL</symbol> in order to get the
|
|
correct prototype for this function. Doing this will also
|
|
automatically include <filename>ssl.h</filename> from <productname>OpenSSL</productname>.
|
|
</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>
|
|
<term><function>PQexec</function><indexterm><primary>PQexec</></></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.
|
|
If a null pointer is returned, it
|
|
should be treated like a <symbol>PGRES_FATAL_ERROR</symbol> result.
|
|
Use <function>PQerrorMessage</function> to get more information
|
|
about such errors.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
It is allowed to include multiple SQL commands (separated by semicolons) in
|
|
the command string. Multiple queries sent in a single <function>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. 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>
|
|
<term><function>PQexecParams</function><indexterm><primary>PQexecParams</></></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>
|
|
<function>PQexecParams</> is like <function>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. <function>PQexecParams</> is supported only in protocol 3.0 and later
|
|
connections; it will fail when using protocol 2.0.
|
|
</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>$2</>,
|
|
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>paramValues[]</>,
|
|
<parameter>paramLengths[]</>, and <parameter>paramFormats[]</>. (The
|
|
array pointers can be <symbol>NULL</symbol> when <parameter>nParams</>
|
|
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</> 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>
|
|
</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 <function>PQexecParams</> over <function>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 <function>PQexec</>, <function>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</> to be treated as <type>bigint</>, whereas
|
|
by default it would be assigned the same type as <literal>x</>. 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>
|
|
<term><function>PQprepare</function><indexterm><primary>PQprepare</></></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>
|
|
<function>PQprepare</> creates a prepared statement for later execution with
|
|
<function>PQexecPrepared</>.
|
|
This feature allows commands
|
|
that will be used repeatedly to be parsed and planned just once, rather
|
|
than each time they are executed.
|
|
<function>PQprepare</> is supported only in protocol 3.0 and later
|
|
connections; it will fail when using protocol 2.0.
|
|
</para>
|
|
|
|
<para>
|
|
The function creates a prepared statement named <parameter>stmtName</>
|
|
from the <parameter>query</> string, which must contain a single SQL command.
|
|
<parameter>stmtName</> can be <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>$2</>, etc.
|
|
<parameter>nParams</> is the number of parameters for which types are
|
|
pre-specified in the array <parameter>paramTypes[]</>. (The array pointer
|
|
can be <symbol>NULL</symbol> when <parameter>nParams</> is zero.)
|
|
<parameter>paramTypes[]</> specifies, by OID, the data types to be assigned to
|
|
the parameter symbols. If <parameter>paramTypes</> 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</>; data types will be inferred for these symbols as
|
|
well. (See <function>PQdescribePrepared</function> for a means to find out
|
|
what data types were inferred.)
|
|
</para>
|
|
|
|
<para>
|
|
As with <function>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 <function>PQerrorMessage</function> to get more information
|
|
about such errors.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
Prepared statements for use with <function>PQexecPrepared</> can also
|
|
be created by executing SQL <xref linkend="sql-prepare"
|
|
endterm="sql-prepare-title"> statements. (But <function>PQprepare</>
|
|
is more flexible since it does not require parameter types to be
|
|
pre-specified.) Also, although there is no <application>libpq</>
|
|
function for deleting a prepared statement, the SQL <xref
|
|
linkend="sql-deallocate" endterm="sql-deallocate-title"> statement can
|
|
be used for that purpose.
|
|
</para>
|
|
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQexecPrepared</function><indexterm><primary>PQexecPrepared</></></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>
|
|
<function>PQexecPrepared</> is like <function>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.
|
|
<function>PQexecPrepared</> is supported only in protocol 3.0 and later
|
|
connections; it will fail when using protocol 2.0.
|
|
</para>
|
|
|
|
<para>
|
|
The parameters are identical to <function>PQexecParams</>, except that the
|
|
name of a prepared statement is given instead of a query string, and the
|
|
<parameter>paramTypes[]</> 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>
|
|
<term><function>PQdescribePrepared</function><indexterm><primary>PQdescribePrepared</></></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>
|
|
<function>PQdescribePrepared</> allows an application to obtain information
|
|
about a previously prepared statement.
|
|
<function>PQdescribePrepared</> is supported only in protocol 3.0 and later
|
|
connections; it will fail when using protocol 2.0.
|
|
</para>
|
|
|
|
<para>
|
|
<parameter>stmtName</> can be <literal>""</> or NULL to reference the unnamed
|
|
statement, otherwise it must be the name of an existing prepared statement.
|
|
On success, a <structname>PGresult</> with status
|
|
<literal>PGRES_COMMAND_OK</literal> is returned. The functions
|
|
<function>PQnparams</function> and <function>PQparamtype</function>
|
|
can be applied to this <structname>PGresult</> to obtain information
|
|
about the parameters of the prepared statement, and the functions
|
|
<function>PQnfields</function>, <function>PQfname</function>,
|
|
<function>PQftype</function>, etc provide information about the result
|
|
columns (if any) of the statement.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQdescribePortal</function><indexterm><primary>PQdescribePortal</></></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>
|
|
<function>PQdescribePortal</> allows an application to obtain information
|
|
about a previously created portal. (<application>libpq</> 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</> SQL command.)
|
|
<function>PQdescribePortal</> is supported only in protocol 3.0 and later
|
|
connections; it will fail when using protocol 2.0.
|
|
</para>
|
|
|
|
<para>
|
|
<parameter>portalName</> can be <literal>""</> or NULL to reference the unnamed
|
|
portal, otherwise it must be the name of an existing portal.
|
|
On success, a <structname>PGresult</> with status
|
|
<literal>PGRES_COMMAND_OK</literal> is returned. The functions
|
|
<function>PQnfields</function>, <function>PQfname</function>,
|
|
<function>PQftype</function>, etc can be applied to the
|
|
<structname>PGresult</> 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</></>
|
|
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>
|
|
<term><function>PQresultStatus</function><indexterm><primary>PQresultStatus</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the result status of the command.
|
|
<synopsis>
|
|
ExecStatusType PQresultStatus(const PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQresultStatus</function> can return one of the following values:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>PGRES_EMPTY_QUERY</literal></term>
|
|
<listitem>
|
|
<para>The string sent to the server was empty.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGRES_COMMAND_OK</literal></term>
|
|
<listitem>
|
|
<para>Successful completion of a command returning no data.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGRES_TUPLES_OK</literal></term>
|
|
<listitem>
|
|
<para>Successful completion of a command returning data (such as
|
|
a <command>SELECT</> or <command>SHOW</>).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGRES_COPY_OUT</literal></term>
|
|
<listitem>
|
|
<para>Copy Out (from server) data transfer started.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGRES_COPY_IN</literal></term>
|
|
<listitem>
|
|
<para>Copy In (to server) data transfer started.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGRES_BAD_RESPONSE</literal></term>
|
|
<listitem>
|
|
<para>The server's response was not understood.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGRES_NONFATAL_ERROR</literal></term>
|
|
<listitem>
|
|
<para>A nonfatal error (a notice or warning) occurred.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PGRES_FATAL_ERROR</literal></term>
|
|
<listitem>
|
|
<para>A fatal error occurred.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
If the result status is <literal>PGRES_TUPLES_OK</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>, <command>UPDATE</command>,
|
|
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 <function>PQexec</function> 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>
|
|
<term><function>PQresStatus</function><indexterm><primary>PQresStatus</></></term>
|
|
<listitem>
|
|
<para>
|
|
Converts the enumerated type returned by <function>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>
|
|
<term><function>PQresultErrorMessage</function><indexterm><primary>PQresultErrorMessage</></></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</> handle is passed to
|
|
<function>PQclear</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Immediately following a <function>PQexec</function> or <function>PQgetResult</function>
|
|
call, <function>PQerrorMessage</function> (on the connection) will return the same
|
|
string as <function>PQresultErrorMessage</function> (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 <function>PQresultErrorMessage</function> when you want to
|
|
know the status associated with a particular <structname>PGresult</structname>; use <function>PQerrorMessage</function>
|
|
when you want to know the status from the latest operation on the connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQresultErrorField</function><indexterm><primary>PQresultErrorField</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns an individual field of an error report.
|
|
<synopsis>
|
|
char *PQresultErrorField(const PGresult *res, int fieldcode);
|
|
</synopsis>
|
|
<parameter>fieldcode</> 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</> handle is passed to
|
|
<function>PQclear</function>.
|
|
</para>
|
|
|
|
<para>
|
|
The following field codes are available:
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><symbol>PG_DIAG_SEVERITY</></term>
|
|
<listitem>
|
|
<para>
|
|
The severity; the field contents are <literal>ERROR</>,
|
|
<literal>FATAL</>, or <literal>PANIC</> (in an error message), or
|
|
<literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>,
|
|
<literal>INFO</>, or <literal>LOG</> (in a notice message), or a
|
|
localized translation of one of these. Always present.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<indexterm>
|
|
<primary>error codes</primary>
|
|
<secondary>libpq</secondary>
|
|
</indexterm>
|
|
<term><symbol>PG_DIAG_SQLSTATE</>
|
|
</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>
|
|
<term><symbol>PG_DIAG_MESSAGE_PRIMARY</></term>
|
|
<listitem>
|
|
<para>
|
|
The primary human-readable error message (typically one line). Always
|
|
present.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>PG_DIAG_MESSAGE_DETAIL</></term>
|
|
<listitem>
|
|
<para>
|
|
Detail: an optional secondary error message carrying more detail about
|
|
the problem. Might run to multiple lines.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>PG_DIAG_MESSAGE_HINT</></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>
|
|
<term><symbol>PG_DIAG_STATEMENT_POSITION</></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>
|
|
<term><symbol>PG_DIAG_INTERNAL_POSITION</></term>
|
|
<listitem>
|
|
<para>
|
|
This is defined the same as the <symbol>PG_DIAG_STATEMENT_POSITION</>
|
|
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</> field will always appear when this field
|
|
appears.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>PG_DIAG_INTERNAL_QUERY</></term>
|
|
<listitem>
|
|
<para>
|
|
The text of a failed internally-generated command.
|
|
This could be, for example, a SQL query issued by a PL/pgSQL function.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>PG_DIAG_CONTEXT</></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>
|
|
<term><symbol>PG_DIAG_SOURCE_FILE</></term>
|
|
<listitem>
|
|
<para>
|
|
The file name of the source-code location where the error was
|
|
reported.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>PG_DIAG_SOURCE_LINE</></term>
|
|
<listitem>
|
|
<para>
|
|
The line number of the source-code location where the error was
|
|
reported.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>PG_DIAG_SOURCE_FUNCTION</></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the source-code function reporting the error.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<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.
|
|
Errors returned by a pre-3.0-protocol server will include severity and
|
|
primary message, and sometimes a detail message, but 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>
|
|
<term><function>PQclear</function><indexterm><primary>PQclear</></></term>
|
|
<listitem>
|
|
<para>
|
|
Frees the storage associated with a <structname>PGresult</structname>.
|
|
Every command result should be freed via <function>PQclear</function> when
|
|
it is no longer needed.
|
|
<synopsis>
|
|
void PQclear(PGresult *res);
|
|
</synopsis>
|
|
</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 <function>PQclear</function>. Failure to do this will
|
|
result in memory leaks in your application.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQmakeEmptyPGresult</function><indexterm><primary>PQmakeEmptyPGresult</></></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</>'s internal function to allocate and
|
|
initialize an empty <structname>PGresult</structname> object. This
|
|
function returns NULL 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</>
|
|
indicates an error, the current error message of the specified
|
|
connection is copied into the <structname>PGresult</structname>. Note
|
|
that <function>PQclear</function> should eventually be called on the
|
|
object, just as with a <structname>PGresult</structname> returned by
|
|
<application>libpq</application> itself.
|
|
</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>). 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>
|
|
<term><function>PQntuples</function><indexterm><primary>PQntuples</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the number of rows (tuples)
|
|
in the query result.
|
|
<synopsis>
|
|
int PQntuples(const PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQnfields</function><indexterm><primary>PQnfields</></></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>
|
|
<term><function>PQfname</function><indexterm><primary>PQfname</></></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</>
|
|
handle is passed to <function>PQclear</function>.
|
|
<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>
|
|
<term><function>PQfnumber</function><indexterm><primary>PQfnumber</></></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>
|
|
<term><function>PQftable</function><indexterm><primary>PQftable</></></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</> is returned if the column number is out of range,
|
|
or if the specified column is not a simple reference to a table column,
|
|
or when using pre-3.0 protocol.
|
|
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>
|
|
<term><function>PQftablecol</function><indexterm><primary>PQftablecol</></></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,
|
|
or when using pre-3.0 protocol.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfformat</function><indexterm><primary>PQfformat</></></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>
|
|
<term><function>PQftype</function><indexterm><primary>PQftype</></></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>src/include/catalog/pg_type.h</filename>
|
|
in the source tree.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfmod</function><indexterm><primary>PQfmod</></></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</>. Most data types do not use modifiers,
|
|
in which case the value is always -1.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfsize</function><indexterm><primary>PQfsize</></></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>
|
|
<function>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>
|
|
<term><function>PQbinaryTuples</function><indexterm><primary>PQbinaryTuples</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns 1 if the <structname>PGresult</> 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</>), because it is possible for a single
|
|
<structname>PGresult</>
|
|
to contain text data in some columns and binary data in others.
|
|
<function>PQfformat</> is preferred. <function>PQbinaryTuples</>
|
|
returns 1 only if all columns of the result are binary (format 1).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQgetvalue</function><indexterm><primary>PQgetvalue</></></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</> handle is passed to
|
|
<function>PQclear</function>.
|
|
<synopsis>
|
|
char *PQgetvalue(const PGresult *res,
|
|
int row_number,
|
|
int column_number);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
For data in text format, the value returned by <function>PQgetvalue</function>
|
|
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</> and
|
|
<function>typreceive</> 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
|
|
<function>PQgetisnull</> to distinguish null values from empty-string values.
|
|
</para>
|
|
|
|
<para>
|
|
The pointer
|
|
returned by <function>PQgetvalue</function> 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>
|
|
<term><function>PQgetisnull</function><indexterm><primary>PQgetisnull</></></term>
|
|
<indexterm><primary>null value</><secondary sortas="libpq">in libpq</></indexterm><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 <function>PQgetvalue</function>
|
|
will return an empty string, not a null pointer, for a null field.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQgetlength</function><indexterm><primary>PQgetlength</></></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 <function>PQgetvalue</function>. For text
|
|
data format this is the same as <function>strlen()</>. For binary format
|
|
this is essential information. Note that one should <emphasis>not</> rely
|
|
on <function>PQfsize</function> to obtain the actual data length.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQnparams</function><indexterm><primary>PQnparams</></></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
|
|
<function>PQdescribePrepared</>. For other types of queries it will
|
|
return zero.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQparamtype</function><indexterm><primary>PQparamtype</></></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
|
|
<function>PQdescribePrepared</>. For other types of queries it will
|
|
return zero.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQprint</function><indexterm><primary>PQprint</></></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 Result Information for Other Commands</title>
|
|
|
|
<para>
|
|
These functions are used to extract information from
|
|
<structname>PGresult</structname> objects that are not <command>SELECT</>
|
|
results.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQcmdStatus</function><indexterm><primary>PQcmdStatus</></></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</> handle is passed to
|
|
<function>PQclear</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQcmdTuples</function><indexterm><primary>PQcmdTuples</></></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</> statement that generated the
|
|
<structname>PGresult</>. This function can only be used
|
|
following the execution of an <command>INSERT</>,
|
|
<command>UPDATE</>, <command>DELETE</>, <command>MOVE</>,
|
|
<command>FETCH</>, or <command>COPY</> statement,
|
|
or an <command>EXECUTE</> of a
|
|
prepared query that contains an <command>INSERT</>,
|
|
<command>UPDATE</>, or <command>DELETE</> statement. If the
|
|
command that generated the <structname>PGresult</> was
|
|
anything else, <function>PQcmdTuples</> returns an empty
|
|
string. The caller should not free the return value
|
|
directly. It will be freed when the associated
|
|
<structname>PGresult</> handle is passed to
|
|
<function>PQclear</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQoidValue</function><indexterm><primary>PQoidValue</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the OID<indexterm><primary>OID</><secondary>in
|
|
libpq</></> of the inserted row, if the <acronym>SQL</>
|
|
command was an <command>INSERT</> that inserted exactly one
|
|
row into a table that has OIDs, or a <command>EXECUTE</> of
|
|
a prepared query containing a suitable <command>INSERT</>
|
|
statement. Otherwise, this function returns
|
|
<literal>InvalidOid</literal>. This function will also
|
|
return <literal>InvalidOid</literal> if the table affected
|
|
by the <command>INSERT</> statement does not contain OIDs.
|
|
<synopsis>
|
|
Oid PQoidValue(const PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQoidStatus</function><indexterm><primary>PQoidStatus</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns a string with the OID of the inserted row, if the
|
|
<acronym>SQL</acronym> command was an
|
|
<command>INSERT</command> that inserted exactly one row, or
|
|
a <command>EXECUTE</command> of a prepared statement
|
|
consisting of a suitable <command>INSERT</command>. (The string will be
|
|
<literal>0</> if the <command>INSERT</command> did not
|
|
insert exactly one row, or if the target table does not have
|
|
OIDs.) If the command was not an <command>INSERT</command>,
|
|
returns an empty string.
|
|
<synopsis>
|
|
char *PQoidStatus(const PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
This function is deprecated in favor of <function>PQoidValue</function>.
|
|
It is not thread-safe.
|
|
</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>PQescapeStringConn</></>
|
|
<indexterm zone="libpq-exec-escape-string"><primary>PQescapeString</></>
|
|
<indexterm zone="libpq-exec-escape-string">
|
|
<primary>escaping strings</>
|
|
<secondary>in libpq</secondary>
|
|
</>
|
|
|
|
<para>
|
|
<function>PQescapeStringConn</function> 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.
|
|
<function>PQescapeStringConn</> performs this operation.
|
|
</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</> attacks wherein unwanted
|
|
SQL commands are fed to your database.
|
|
</para>
|
|
</tip>
|
|
|
|
<para>
|
|
Note that it is not necessary nor correct to do escaping when a data
|
|
value is passed as a separate parameter in <function>PQexecParams</> or
|
|
its sibling routines.
|
|
|
|
<synopsis>
|
|
size_t PQescapeStringConn (PGconn *conn,
|
|
char *to, const char *from, size_t length,
|
|
int *error);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQescapeStringConn</> writes an escaped
|
|
version of the <parameter>from</> string to the <parameter>to</>
|
|
buffer, escaping special characters so that they cannot cause any
|
|
harm, and adding a terminating zero byte. The single quotes that
|
|
must surround <productname>PostgreSQL</> string literals are not
|
|
included in the result string; they should be provided in the SQL
|
|
command that the result is inserted into.
|
|
The parameter <parameter>from</> points to the first character of the string
|
|
that is to be escaped, and the <parameter>length</> parameter gives the
|
|
number of bytes in this string. A terminating zero byte is not
|
|
required, and should not be counted in <parameter>length</>. (If
|
|
a terminating zero byte is found before <parameter>length</> bytes are
|
|
processed, <function>PQescapeStringConn</> stops at the zero; the behavior
|
|
is thus rather like <function>strncpy</>.)
|
|
<parameter>to</> shall point to a
|
|
buffer that is able to hold at least one more byte than twice
|
|
the value of <parameter>length</>, otherwise the behavior is
|
|
undefined.
|
|
Behavior is likewise undefined if the <parameter>to</> and <parameter>from</>
|
|
strings overlap.
|
|
</para>
|
|
<para>
|
|
If the <parameter>error</> parameter is not NULL, then <literal>*error</>
|
|
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</> object, whether or not <parameter>error</>
|
|
is NULL.
|
|
</para>
|
|
<para>
|
|
<function>PQescapeStringConn</> returns the number of bytes written
|
|
to <parameter>to</>, not including the terminating zero byte.
|
|
</para>
|
|
|
|
<para>
|
|
<synopsis>
|
|
size_t PQescapeString (char *to, const char *from, size_t length);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQescapeString</> is an older, deprecated version of
|
|
<function>PQescapeStringConn</>; the difference is that it does not
|
|
take <parameter>conn</> or <parameter>error</> 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</>.
|
|
Also, it has no way to report error conditions.
|
|
</para>
|
|
<para>
|
|
<function>PQescapeString</> can be used safely in single-threaded client
|
|
programs that work with only one <productname>PostgreSQL</> connection at
|
|
a time (in this case it can find out what it needs to know <quote>behind the
|
|
scenes</>). In other contexts it is a security hazard and should be avoided
|
|
in favor of <function>PQescapeStringConn</>.
|
|
</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="libpq-exec-escape-bytea">
|
|
<title>Escaping Binary Strings for Inclusion in SQL Commands</title>
|
|
|
|
<indexterm zone="libpq-exec-escape-bytea">
|
|
<primary>bytea</>
|
|
<secondary sortas="libpq">in libpq</>
|
|
</indexterm>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQescapeByteaConn</function><indexterm><primary>PQescapeByteaConn</></></term>
|
|
<listitem>
|
|
<para>
|
|
Escapes binary data for use within an SQL command with the type
|
|
<type>bytea</type>. As with <function>PQescapeStringConn</function>,
|
|
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 <emphasis>must</emphasis> be escaped (but all
|
|
byte values <emphasis>can</emphasis> be escaped) when used as part
|
|
of a <type>bytea</type> literal in an <acronym>SQL</acronym>
|
|
statement. In general, to escape a byte, it is converted into the
|
|
three digit octal number equal to the octet value, and preceded by
|
|
usually two backslashes. The single quote (<literal>'</>) and backslash
|
|
(<literal>\</>) characters have special alternative escape
|
|
sequences. See <xref linkend="datatype-binary"> for more
|
|
information. <function>PQescapeByteaConn</function> performs this
|
|
operation, escaping only the minimally required bytes.
|
|
</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>
|
|
<function>PQescapeByteaConn</> returns an escaped version of the
|
|
<parameter>from</parameter> parameter binary string in memory
|
|
allocated with <function>malloc()</>. This memory must be freed using
|
|
<function>PQfreemem()</> 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</> object. Currently, the only
|
|
possible error is insufficient memory for the result string.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQescapeBytea</function><indexterm><primary>PQescapeBytea</></></term>
|
|
<listitem>
|
|
<para>
|
|
<function>PQescapeBytea</> is an older, deprecated version of
|
|
<function>PQescapeByteaConn</>.
|
|
<synopsis>
|
|
unsigned char *PQescapeBytea(const unsigned char *from,
|
|
size_t from_length,
|
|
size_t *to_length);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
The only difference from <function>PQescapeByteaConn</> is that
|
|
<function>PQescapeBytea</> does not
|
|
take a <structname>PGconn</> parameter. Because of this, it cannot adjust
|
|
its behavior depending on the connection properties (in particular,
|
|
whether standard-conforming strings are enabled)
|
|
and therefore <emphasis>it might give the wrong results</>. Also, it
|
|
has no way to return an error message on failure.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQescapeBytea</> can be used safely in single-threaded client
|
|
programs that work with only one <productname>PostgreSQL</> connection at
|
|
a time (in this case it can find out what it needs to know <quote>behind the
|
|
scenes</>). In other contexts it is a security hazard and should be
|
|
avoided in favor of <function>PQescapeByteaConn</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQunescapeBytea</function><indexterm><primary>PQunescapeBytea</></></term>
|
|
<listitem>
|
|
<para>
|
|
Converts a string representation of binary data into binary
|
|
data — the reverse of <function>PQescapeBytea</function>.
|
|
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 <function>PQgetvalue</function> when applied
|
|
to a <type>bytea</type> column. <function>PQunescapeBytea</function>
|
|
converts this string representation into its binary representation.
|
|
It returns a pointer to a buffer allocated with
|
|
<function>malloc()</function>, or null on error, and puts the size of
|
|
the buffer in <parameter>to_length</parameter>. The result must be
|
|
freed using <function>PQfreemem</> when it is no longer needed.
|
|
</para>
|
|
|
|
<para>
|
|
This conversion is not exactly the inverse of
|
|
<function>PQescapeBytea</function>, because the string is not expected
|
|
to be <quote>escaped</> when received from <function>PQgetvalue</function>.
|
|
In particular this means there is no need for string quoting considerations,
|
|
and so no need for a <structname>PGconn</> parameter.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfreemem</function><indexterm><primary>PQfreemem</></></term>
|
|
<listitem>
|
|
<para>
|
|
Frees memory allocated by <application>libpq</>.
|
|
<synopsis>
|
|
void PQfreemem(void *ptr);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
Frees memory allocated by <application>libpq</>, particularly
|
|
<function>PQescapeByteaConn</function>,
|
|
<function>PQescapeBytea</function>,
|
|
<function>PQunescapeBytea</function>,
|
|
and <function>PQnotifies</function>.
|
|
It is particularly important that this function, rather than
|
|
<function>free()</>, 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()</>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-async">
|
|
<title>Asynchronous Command Processing</title>
|
|
|
|
<indexterm zone="libpq-async"><primary>nonblocking connection</></>
|
|
|
|
<para>
|
|
The <function>PQexec</function> function is adequate for submitting commands in
|
|
normal, synchronous
|
|
applications. It has a couple of deficiencies, however, that can be of importance to some users:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQexec</function> 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>
|
|
<function>PQexec</function> 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 <function>PQexec</function>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Applications that do not like these limitations can instead use the
|
|
underlying functions that <function>PQexec</function> is built from:
|
|
<function>PQsendQuery</function> and <function>PQgetResult</function>.
|
|
There are also
|
|
<function>PQsendQueryParams</function>,
|
|
<function>PQsendPrepare</function>,
|
|
<function>PQsendQueryPrepared</function>,
|
|
<function>PQsendDescribePrepared</function>, and
|
|
<function>PQsendDescribePortal</function>,
|
|
which can be used with <function>PQgetResult</function> to duplicate the
|
|
functionality of
|
|
<function>PQexecParams</function>,
|
|
<function>PQprepare</function>,
|
|
<function>PQexecPrepared</function>,
|
|
<function>PQdescribePrepared</function>, and
|
|
<function>PQdescribePortal</function>
|
|
respectively.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQsendQuery</function><indexterm><primary>PQsendQuery</></></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
|
|
<function>PQerrorMessage</> to get more information about the failure).
|
|
<synopsis>
|
|
int PQsendQuery(PGconn *conn, const char *command);
|
|
</synopsis>
|
|
|
|
After successfully calling <function>PQsendQuery</function>, call
|
|
<function>PQgetResult</function> one or more
|
|
times to obtain the results. <function>PQsendQuery</function> cannot be called
|
|
again (on the same connection) until <function>PQgetResult</function> has returned a null pointer,
|
|
indicating that the command is done.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsendQueryParams</function><indexterm><primary>PQsendQueryParams</></></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 <function>PQsendQuery</function> except that
|
|
query parameters can be specified separately from the query string.
|
|
The function's parameters are handled identically to
|
|
<function>PQexecParams</function>. Like
|
|
<function>PQexecParams</function>, it will not work on 2.0-protocol
|
|
connections, and it allows only one command in the query string.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsendPrepare</><indexterm><primary>PQsendPrepare</></></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 <function>PQprepare</>: it
|
|
returns 1 if it was able to dispatch the request, and 0 if not.
|
|
After a successful call, call <function>PQgetResult</function>
|
|
to determine whether the server successfully created the prepared
|
|
statement.
|
|
The function's parameters are handled identically to
|
|
<function>PQprepare</function>. Like
|
|
<function>PQprepare</function>, it will not work on 2.0-protocol
|
|
connections.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsendQueryPrepared</function><indexterm><primary>PQsendQueryPrepared</></></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 <function>PQsendQueryParams</function>, 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
|
|
<function>PQexecPrepared</function>. Like
|
|
<function>PQexecPrepared</function>, it will not work on 2.0-protocol
|
|
connections.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsendDescribePrepared</><indexterm><primary>PQsendDescribePrepared</></></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 <function>PQdescribePrepared</>: it
|
|
returns 1 if it was able to dispatch the request, and 0 if not.
|
|
After a successful call, call <function>PQgetResult</function>
|
|
to obtain the results.
|
|
The function's parameters are handled identically to
|
|
<function>PQdescribePrepared</function>. Like
|
|
<function>PQdescribePrepared</function>, it will not work on 2.0-protocol
|
|
connections.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQsendDescribePortal</><indexterm><primary>PQsendDescribePortal</></></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 <function>PQdescribePortal</>: it
|
|
returns 1 if it was able to dispatch the request, and 0 if not.
|
|
After a successful call, call <function>PQgetResult</function>
|
|
to obtain the results.
|
|
The function's parameters are handled identically to
|
|
<function>PQdescribePortal</function>. Like
|
|
<function>PQdescribePortal</function>, it will not work on 2.0-protocol
|
|
connections.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQgetResult</function><indexterm><primary>PQgetResult</></></term>
|
|
<listitem>
|
|
<para>
|
|
Waits for the next result from a prior
|
|
<function>PQsendQuery</function>,
|
|
<function>PQsendQueryParams</function>,
|
|
<function>PQsendPrepare</function>, or
|
|
<function>PQsendQueryPrepared</function> 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>
|
|
<function>PQgetResult</function> must be called repeatedly until it returns a null pointer,
|
|
indicating that the command is done. (If called when no command is
|
|
active, <function>PQgetResult</function> will just return a null pointer at once.)
|
|
Each non-null result from <function>PQgetResult</function> should be processed using
|
|
the same <structname>PGresult</> accessor functions previously described.
|
|
Don't forget to free each result object with <function>PQclear</function> when done with it.
|
|
Note that <function>PQgetResult</function> will block only if a command is active and the
|
|
necessary response data has not yet been read by <function>PQconsumeInput</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Using <function>PQsendQuery</function> and <function>PQgetResult</function>
|
|
solves one of <function>PQexec</function>'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.) However, calling <function>PQgetResult</function> 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>
|
|
<term><function>PQconsumeInput</function><indexterm><primary>PQconsumeInput</></></term>
|
|
<listitem>
|
|
<para>
|
|
If input is available from the server, consume it.
|
|
<synopsis>
|
|
int PQconsumeInput(PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQconsumeInput</function> normally returns 1 indicating <quote>no error</quote>,
|
|
but returns 0 if there was some kind of trouble (in which case
|
|
<function>PQerrorMessage</function> can be consulted). Note that the result
|
|
does not say
|
|
whether any input data was actually collected. After calling
|
|
<function>PQconsumeInput</function>, the application can check
|
|
<function>PQisBusy</function> and/or <function>PQnotifies</function> to see if
|
|
their state has changed.
|
|
</para>
|
|
<para>
|
|
<function>PQconsumeInput</function> 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 <function>PQconsumeInput</function> to clear the
|
|
<function>select()</function> condition immediately, and then examine the results at leisure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQisBusy</function><indexterm><primary>PQisBusy</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns 1 if a command is busy, that is, <function>PQgetResult</function> would block
|
|
waiting for input. A 0 return indicates that <function>PQgetResult</function> can
|
|
be called with assurance of not blocking.
|
|
<synopsis>
|
|
int PQisBusy(PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQisBusy</function> will not itself attempt to read data from the server;
|
|
therefore <function>PQconsumeInput</function> 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()</> 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 <function>PQsocket</function>.
|
|
When the main loop detects input ready, it should call
|
|
<function>PQconsumeInput</function> to read the input. It can then call
|
|
<function>PQisBusy</function>, followed by <function>PQgetResult</function>
|
|
if <function>PQisBusy</function> returns false (0). It can also call
|
|
<function>PQnotifies</function> to detect <command>NOTIFY</> messages (see <xref linkend="libpq-notify">).
|
|
</para>
|
|
|
|
<para>
|
|
A client that uses
|
|
<function>PQsendQuery</function>/<function>PQgetResult</function> 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 <function>PQcancel</function>, the application must continue with the
|
|
normal result-reading sequence using <function>PQgetResult</function>.
|
|
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>
|
|
<term><function>PQsetnonblocking</function><indexterm><primary>PQsetnonblocking</></></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
|
|
<function>PQsendQuery</function>,
|
|
<function>PQputline</function>, <function>PQputnbytes</function>,
|
|
and <function>PQendcopy</function>
|
|
will not block but instead return an error if they need to be called
|
|
again.
|
|
</para>
|
|
<para>
|
|
Note that <function>PQexec</function> does not honor nonblocking mode;
|
|
if it is called, it will act in blocking fashion anyway.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQisnonblocking</function><indexterm><primary>PQisnonblocking</></></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>
|
|
<term><function>PQflush</function><indexterm><primary>PQflush</></></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
|
|
<function>PQflush</function>. If it returns 1, wait for the socket to be
|
|
write-ready and call it again; repeat until it returns 0. Once
|
|
<function>PQflush</function> returns 0, wait for the socket to be read-ready
|
|
and then read the response as described above.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-cancel">
|
|
<title>Cancelling Queries in Progress</title>
|
|
|
|
<indexterm zone="libpq-cancel"><primary>canceling</><secondary>SQL command</></>
|
|
|
|
<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>
|
|
<term><function>PQgetCancel</function><indexterm><primary>PQgetCancel</></></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>
|
|
<function>PQgetCancel</function> creates a
|
|
<structname>PGcancel</><indexterm><primary>PGcancel</></> object given
|
|
a <structname>PGconn</> connection object. It will return NULL if the
|
|
given <parameter>conn</> is NULL or an invalid connection. The
|
|
<structname>PGcancel</> object is an opaque structure that is not meant
|
|
to be accessed directly by the application; it can only be passed to
|
|
<function>PQcancel</function> or <function>PQfreeCancel</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfreeCancel</function><indexterm><primary>PQfreeCancel</></></term>
|
|
<listitem>
|
|
<para>
|
|
Frees a data structure created by <function>PQgetCancel</function>.
|
|
<synopsis>
|
|
void PQfreeCancel(PGcancel *cancel);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQfreeCancel</function> frees a data object previously created
|
|
by <function>PQgetCancel</function>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQcancel</function><indexterm><primary>PQcancel</></></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</> is filled with an error
|
|
message explaining why not. <parameter>errbuf</> must be a char array of size
|
|
<parameter>errbufsize</> (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>
|
|
<function>PQcancel</function> can safely be invoked from a signal handler,
|
|
if the <parameter>errbuf</> is a local variable in the signal handler. The
|
|
<structname>PGcancel</> object is read-only as far as
|
|
<function>PQcancel</function> is concerned, so it can also be invoked from a
|
|
thread that is separate from the one manipulating the <structname>PGconn</>
|
|
object.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQrequestCancel</function><indexterm><primary>PQrequestCancel</></></term>
|
|
<listitem>
|
|
<para>
|
|
Requests that the server abandon
|
|
processing of the current command.
|
|
<synopsis>
|
|
int PQrequestCancel(PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQrequestCancel</function> is a deprecated variant of
|
|
<function>PQcancel</function>. It operates directly on the
|
|
<structname>PGconn</> object, and in case of failure stores the
|
|
error message in the <structname>PGconn</> object (whence it can be
|
|
retrieved by <function>PQerrorMessage</function>). Although the
|
|
functionality is the same, this approach creates hazards for multiple-thread
|
|
programs and signal handlers, since it is possible that overwriting the
|
|
<structname>PGconn</>'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</></>
|
|
|
|
<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>PQfn</function><indexterm><primary>PQfn</></>
|
|
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</> argument is the OID of the function to be
|
|
executed. <parameter>args</> and <parameter>nargs</> define the
|
|
parameters to be passed to the function; they must match the declared
|
|
function argument list. When the <parameter>isint</> field of a
|
|
parameter
|
|
structure is true,
|
|
the <parameter>u.integer</> value is sent to the server as an integer
|
|
of the indicated length (this must be 1, 2, or 4 bytes); proper
|
|
byte-swapping occurs. When <parameter>isint</> is false, the
|
|
indicated number of bytes at <parameter>*u.ptr</> 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.
|
|
<parameter>result_buf</parameter> is the buffer in which
|
|
to place the return value. The caller must have allocated
|
|
sufficient space to store the return value. (There is no check!)
|
|
The actual result length will be returned in the integer pointed
|
|
to by <parameter>result_len</parameter>.
|
|
If a 1, 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</> to byte-swap the value if necessary, so that
|
|
it is
|
|
delivered as a proper <type>int</type> value for the client machine. When
|
|
<parameter>result_is_int</> is 0, the binary-format byte string sent by
|
|
the server is returned unmodified.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQfn</function> always returns a valid <structname>PGresult</structname> pointer. The result status
|
|
should be checked before the result is used. The
|
|
caller is responsible for freeing the <structname>PGresult</structname> with
|
|
<function>PQclear</function> when it is no longer needed.
|
|
</para>
|
|
|
|
<para>
|
|
Note that it is not possible to handle null arguments, null results, nor
|
|
set-valued results when using this interface.
|
|
</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 condition with the <command>LISTEN</command> command (and can stop listening
|
|
with the <command>UNLISTEN</command> command). All sessions listening on a
|
|
particular condition will be notified asynchronously when a <command>NOTIFY</command> command with that
|
|
condition name is executed by any session. No additional information is
|
|
passed from the notifier to the listener. Thus, typically, any actual data
|
|
that needs to be communicated is transferred through a database table.
|
|
Commonly, the condition name is the same as the associated table, but it is
|
|
not necessary for there to be any associated table.
|
|
</para>
|
|
|
|
<para>
|
|
<application>libpq</application> applications submit
|
|
<command>LISTEN</command> and <command>UNLISTEN</command> commands as
|
|
ordinary SQL commands. The arrival of <command>NOTIFY</command>
|
|
messages can subsequently be detected by calling
|
|
<function>PQnotifies</function>.<indexterm><primary>PQnotifies</></>
|
|
</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</>, it is considered handled and will be
|
|
removed from the list of notifications.
|
|
<synopsis>
|
|
PGnotify *PQnotifies(PGconn *conn);
|
|
|
|
typedef struct pgNotify {
|
|
char *relname; /* notification condition name */
|
|
int be_pid; /* process ID of notifying server process */
|
|
char *extra; /* notification parameter */
|
|
} PGnotify;
|
|
</synopsis>
|
|
After processing a <structname>PGnotify</structname> object returned by
|
|
<function>PQnotifies</function>, be sure to free it with
|
|
<function>PQfreemem</function>. It is sufficient to free the
|
|
<structname>PGnotify</structname> pointer; the
|
|
<structfield>relname</structfield> and <structfield>extra</structfield> fields
|
|
do not represent separate allocations.
|
|
(At present, the <structfield>extra</structfield> field is unused and will
|
|
always point to an empty string.)
|
|
</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 prior releases of <application>libpq</application>, the only way
|
|
to ensure timely receipt of <command>NOTIFY</> messages was to constantly submit commands,
|
|
even empty ones, and then check <function>PQnotifies</function> after each
|
|
<function>PQexec</function>. While this still works, it is
|
|
deprecated as a waste of processing power.
|
|
</para>
|
|
|
|
<para>
|
|
A better way to check for <command>NOTIFY</>
|
|
messages when you have no useful commands to execute is to call
|
|
<function>PQconsumeInput</function>, 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 <function>PQsocket</function> to obtain the file descriptor
|
|
number to use with <function>select()</function>.)
|
|
Note that this will work OK whether you submit commands with
|
|
<function>PQsendQuery</function>/<function>PQgetResult</function> or simply
|
|
use <function>PQexec</function>. You should, however, remember to
|
|
check <function>PQnotifies</function> after each
|
|
<function>PQgetResult</function> or <function>PQexec</function>, 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 <function>PQexec</function> or one
|
|
of the equivalent functions. The response to this (if there is no error
|
|
in the command) will be a <structname>PGresult</> 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</> 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
|
|
<function>PQexec</function>. (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
|
|
<function>PQexec</function> in a string that could contain additional
|
|
commands, the application must continue fetching results via
|
|
<function>PQgetResult</> after completing the <command>COPY</command>
|
|
sequence. Only when <function>PQgetResult</> returns <symbol>NULL</symbol> is it certain
|
|
that the <function>PQexec</function> 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 <function>PQexec</function> or
|
|
<function>PQgetResult</function>.
|
|
</para>
|
|
|
|
<para>
|
|
A <structname>PGresult</> 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>
|
|
<term><function>PQnfields</function><indexterm><primary>PQnfields</><secondary>with COPY</></></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the number of columns (fields) to be copied.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQbinaryTuples</function><indexterm><primary>PQbinaryTuples</><secondary>with COPY</></></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" endterm="sql-copy-title">
|
|
for more information.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQfformat</function><indexterm><primary>PQfformat</><secondary>with COPY</></></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</>,
|
|
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>
|
|
|
|
<note>
|
|
<para>
|
|
These additional data values are only available when using protocol 3.0.
|
|
When using protocol 2.0, all these functions will return 0.
|
|
</para>
|
|
</note>
|
|
|
|
<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</>.
|
|
They will fail if called when the connection is not in <literal>COPY_IN</>
|
|
state.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQputCopyData</function><indexterm><primary>PQputCopyData</></></term>
|
|
<listitem>
|
|
<para>
|
|
Sends data to the server during <literal>COPY_IN</> 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</>, of length
|
|
<parameter>nbytes</>, to the server. The result is 1 if the data was sent,
|
|
zero if it was not sent because the attempt would block (this case is only
|
|
possible if the connection is in nonblocking mode), or -1 if an error occurred.
|
|
(Use <function>PQerrorMessage</function> 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; see
|
|
<xref linkend="sql-copy" endterm="sql-copy-title"> for details.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQputCopyEnd</function><indexterm><primary>PQputCopyEnd</></></term>
|
|
<listitem>
|
|
<para>
|
|
Sends end-of-data indication to the server during <literal>COPY_IN</> state.
|
|
<synopsis>
|
|
int PQputCopyEnd(PGconn *conn,
|
|
const char *errormsg);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
Ends the <literal>COPY_IN</> operation successfully if <parameter>errormsg</>
|
|
is <symbol>NULL</symbol>. If <parameter>errormsg</> is not <symbol>NULL</symbol> then the <command>COPY</>
|
|
is forced to fail, with the string pointed to by <parameter>errormsg</>
|
|
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</> for its own reasons. Also note that the
|
|
option to force failure does not work when using pre-3.0-protocol connections.)
|
|
</para>
|
|
|
|
<para>
|
|
The result is 1 if the termination data was sent,
|
|
zero if it was not sent because the attempt would block (this case is only
|
|
possible if the connection is in nonblocking mode), or -1 if an error occurred.
|
|
(Use <function>PQerrorMessage</function> to retrieve details if the return
|
|
value is -1. If the value is zero, wait for write-ready and try again.)
|
|
</para>
|
|
|
|
<para>
|
|
After successfully calling <function>PQputCopyEnd</>, call
|
|
<function>PQgetResult</> to obtain the final result status of the
|
|
<command>COPY</> 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</>.
|
|
They will fail if called when the connection is not in <literal>COPY_OUT</>
|
|
state.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQgetCopyData</function><indexterm><primary>PQgetCopyData</></></term>
|
|
<listitem>
|
|
<para>
|
|
Receives data from the server during <literal>COPY_OUT</> 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 must be non-<symbol>NULL</symbol>. <parameter>*buffer</>
|
|
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 must be freed using
|
|
<function>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</> is true). A
|
|
result of -1 indicates that the <command>COPY</command> is done.
|
|
A result of -2 indicates that an error occurred (consult
|
|
<function>PQerrorMessage</> for the reason).
|
|
</para>
|
|
|
|
<para>
|
|
When <parameter>async</> is true (not zero), <function>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 <function>PQconsumeInput</> before calling
|
|
<function>PQgetCopyData</> again.) When <parameter>async</> is
|
|
false (zero), <function>PQgetCopyData</> will block until data is available
|
|
or the operation completes.
|
|
</para>
|
|
|
|
<para>
|
|
After <function>PQgetCopyData</> returns -1, call
|
|
<function>PQgetResult</> to obtain the final result status of the
|
|
<command>COPY</> 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</>.
|
|
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>
|
|
<term><function>PQgetline</function><indexterm><primary>PQgetline</></></term>
|
|
<listitem>
|
|
<para>
|
|
Reads a newline-terminated line of characters
|
|
(transmitted by the server) into a buffer
|
|
string of size <parameter>length</>.
|
|
<synopsis>
|
|
int PQgetline(PGconn *conn,
|
|
char *buffer,
|
|
int length);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
This function copies up to <parameter>length</>-1 characters
|
|
into the buffer and converts
|
|
the terminating newline into a zero byte.
|
|
<function>PQgetline</function> 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</>-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>
|
|
<term><function>PQgetlineAsync</function><indexterm><primary>PQgetlineAsync</></></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 <function>PQgetline</function>, 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 <function>PQconsumeInput</function> and
|
|
<function>PQgetlineAsync</function> until the
|
|
end-of-data signal is detected.
|
|
</para>
|
|
<para>
|
|
Unlike <function>PQgetline</function>, this function takes
|
|
responsibility for detecting end-of-data.
|
|
</para>
|
|
<para>
|
|
On each call, <function>PQgetlineAsync</function> will return data if a
|
|
complete data row is available in <application>libpq</>'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
|
|
<function>PQendcopy</function>, 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</>, actual parsing of the <command>COPY</> 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>
|
|
<term><function>PQputline</function><indexterm><primary>PQputline</></></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
|
|
<function>PQputline</function> has the same format as that returned by
|
|
<function>PQgetlineAsync</function>, except that applications are not
|
|
obliged to send exactly one data row per <function>PQputline</function>
|
|
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</> 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 <function>PQendcopy</function> after
|
|
having sent the actual data.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQputnbytes</function><indexterm><primary>PQputnbytes</></></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 <function>PQputline</function>, 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>
|
|
<term><function>PQendcopy</function><indexterm><primary>PQendcopy</></></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 <function>PQputline</function> or when the
|
|
last string has been received from the server
|
|
using <function>PGgetline</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 <function>PQerrorMessage</function> to retrieve
|
|
details if the return value is nonzero.)
|
|
</para>
|
|
|
|
<para>
|
|
When using <function>PQgetResult</function>, the application should respond to
|
|
a <literal>PGRES_COPY_OUT</literal> result by executing <function>PQgetline</function>
|
|
repeatedly, followed by <function>PQendcopy</function> after the terminator line is seen.
|
|
It should then return to the <function>PQgetResult</function> loop until
|
|
<function>PQgetResult</function> returns a null pointer. Similarly a <literal>PGRES_COPY_IN</literal>
|
|
result is processed by a series of <function>PQputline</function> calls followed by
|
|
<function>PQendcopy</function>, then return to the <function>PQgetResult</function> 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 <function>PQexec</function> and assume that the transaction is done after
|
|
<function>PQendcopy</function>.
|
|
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</>'s behavior.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQsetErrorVerbosity</function><indexterm><primary>PQsetErrorVerbosity</></></term>
|
|
<listitem>
|
|
<para>
|
|
Determines the verbosity of messages returned by
|
|
<function>PQerrorMessage</> and <function>PQresultErrorMessage</>.
|
|
<synopsis>
|
|
typedef enum {
|
|
PQERRORS_TERSE,
|
|
PQERRORS_DEFAULT,
|
|
PQERRORS_VERBOSE
|
|
} PGVerbosity;
|
|
|
|
PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
|
|
</synopsis>
|
|
<function>PQsetErrorVerbosity</> sets the verbosity mode, returning
|
|
the connection's previous setting. In <firstterm>TERSE</> mode,
|
|
returned messages include severity, primary text, and position only;
|
|
this will normally fit on a single line. The default mode produces
|
|
messages that include the above plus any detail, hint, or context
|
|
fields (these might span multiple lines). The <firstterm>VERBOSE</>
|
|
mode includes all available fields. Changing the verbosity does not
|
|
affect the messages available from already-existing
|
|
<structname>PGresult</> objects, only subsequently-created ones.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><function>PQtrace</function><indexterm><primary>PQtrace</></></term>
|
|
<listitem>
|
|
<para>
|
|
Enables tracing of the client/server communication to a debugging file stream.
|
|
<synopsis>
|
|
void PQtrace(PGconn *conn, FILE *stream);
|
|
</synopsis>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
On Windows, if the <application>libpq</> library and an application are
|
|
compiled with different flags, this function call will crash the
|
|
application because the internal representation of the <literal>FILE</>
|
|
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>
|
|
<term><function>PQuntrace</function><indexterm><primary>PQuntrace</></></term>
|
|
<listitem>
|
|
<para>
|
|
Disables tracing started by <function>PQtrace</function>.
|
|
<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>
|
|
<term><function>PQencryptPassword</function><indexterm><primary>PQencryptPassword</></></term>
|
|
<listitem>
|
|
<para>
|
|
Prepares the encrypted form of a <productname>PostgreSQL</> password.
|
|
<synopsis>
|
|
char * PQencryptPassword(const char *passwd, const char *user);
|
|
</synopsis>
|
|
This function is intended to be used by client
|
|
applications that wish to send commands like
|
|
<literal>ALTER USER joe PASSWORD 'pwd'</>.
|
|
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. The arguments are the cleartext password, and the SQL
|
|
name of the user it is for. The return value is a string allocated by
|
|
<function>malloc</function>, or <symbol>NULL</symbol> if out of memory.
|
|
The caller can assume the string doesn't contain any special
|
|
characters that would require escaping. Use <function>PQfreemem</> to free
|
|
the result when done with it.
|
|
</para>
|
|
</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>PQsetNoticeReceiver</function>
|
|
<indexterm><primary>notice receiver</></><indexterm><primary>PQsetNoticeReceiver</></>
|
|
sets or examines the current notice receiver for a connection object.
|
|
Similarly, <function>PQsetNoticeProcessor</function>
|
|
<indexterm><primary>notice processor</></><indexterm><primary>PQsetNoticeProcessor</></>
|
|
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
|
|
<function>PQresultErrorField</>, or the complete preformatted message using
|
|
<function>PQresultErrorMessage</>.)
|
|
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
|
|
<function>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</> object or
|
|
<structname>PGresult</> objects made from it exist. At creation of a
|
|
<structname>PGresult</>, the <structname>PGconn</>'s current notice handling
|
|
pointers are copied into the <structname>PGresult</> for possible use by
|
|
functions like <function>PQgetvalue</function>.
|
|
</para>
|
|
|
|
</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
|
|
<function>PQconnectdb</>, <function>PQsetdbLogin</> and
|
|
<function>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> sets the database server name.
|
|
If this begins with a slash, it specifies Unix-domain communication
|
|
rather than TCP/IP communication; the value is then the name of the
|
|
directory in which the socket file is stored (in a default installation
|
|
setup this would be <filename>/tmp</filename>).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGHOSTADDR</envar></primary>
|
|
</indexterm>
|
|
<envar>PGHOSTADDR</envar> specifies the numeric IP address of the database
|
|
server. This can be set instead of or in addition to <envar>PGHOST</envar>
|
|
to avoid DNS lookup overhead. See the documentation of
|
|
these parameters, under <function>PQconnectdb</function> above, for details
|
|
on their interaction.
|
|
</para>
|
|
<para>
|
|
When neither <envar>PGHOST</envar> nor <envar>PGHOSTADDR</envar> is set,
|
|
the default behavior is to connect using a local Unix-domain socket; or on
|
|
machines without Unix-domain sockets, <application>libpq</application> will
|
|
attempt to connect to <literal>localhost</>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGPORT</envar></primary>
|
|
</indexterm>
|
|
<envar>PGPORT</envar> sets the TCP port number or Unix-domain
|
|
socket file extension for communicating with the
|
|
<productname>PostgreSQL</productname> server.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGDATABASE</envar></primary>
|
|
</indexterm>
|
|
<envar>PGDATABASE</envar> sets the
|
|
<productname>PostgreSQL</productname> database name.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGUSER</envar></primary>
|
|
</indexterm>
|
|
<envar>PGUSER</envar>
|
|
sets the user name used to connect to the database.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGPASSWORD</envar></primary>
|
|
</indexterm>
|
|
<envar>PGPASSWORD</envar>
|
|
sets the password used if the server demands password
|
|
authentication. Use of this environment variable is not
|
|
recommended for security reasons (some operating systems
|
|
allow non-root users to see process environment variables via
|
|
<application>ps</>); instead consider using the
|
|
<filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGPASSFILE</envar></primary>
|
|
</indexterm>
|
|
<envar>PGPASSFILE</envar>
|
|
specifies the name of the password file to use for lookups.
|
|
If not set, it defaults to <filename>~/.pgpass</>
|
|
(see <xref linkend="libpq-pgpass">).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGSERVICE</envar></primary>
|
|
</indexterm>
|
|
<envar>PGSERVICE</envar>
|
|
sets the service name to be looked up in <filename>pg_service.conf</filename>.
|
|
This offers a shorthand way of setting all the parameters.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGREALM</envar></primary>
|
|
</indexterm>
|
|
<envar>PGREALM</envar> sets the Kerberos realm to use with
|
|
<productname>PostgreSQL</productname>, if it is different from the local realm.
|
|
If <envar>PGREALM</envar> is set, <application>libpq</application>
|
|
applications will attempt authentication with servers for this realm and use
|
|
separate ticket files to avoid conflicts with local
|
|
ticket files. This environment variable is only
|
|
used if Kerberos authentication is selected by the server.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGOPTIONS</envar></primary>
|
|
</indexterm>
|
|
<envar>PGOPTIONS</envar> sets additional run-time options for
|
|
the <productname>PostgreSQL</productname> server.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGSSLMODE</envar></primary>
|
|
</indexterm>
|
|
<envar>PGSSLMODE</envar> determines whether and with what priority an
|
|
<acronym>SSL</> connection will be negotiated with the server. There are
|
|
four modes: <literal>disable</> will attempt only an unencrypted
|
|
<acronym>SSL</> connection; <literal>allow</> will negotiate,
|
|
trying first a non-<acronym>SSL</> connection, then if that fails,
|
|
trying an <acronym>SSL</> connection; <literal>prefer</>
|
|
(the default) will negotiate, trying first an <acronym>SSL</>
|
|
connection, then if that fails, trying a regular non-<acronym>SSL</>
|
|
connection; <literal>require</> will try only an <acronym>SSL</>
|
|
connection. If <productname>PostgreSQL</> is compiled without SSL support,
|
|
using option <literal>require</> will cause an error, while options
|
|
<literal>allow</> and <literal>prefer</> will be accepted but
|
|
<application>libpq</> will not in fact attempt an <acronym>SSL</>
|
|
connection.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGREQUIRESSL</envar></primary>
|
|
</indexterm>
|
|
<envar>PGREQUIRESSL</envar> sets whether or not the connection must be
|
|
made over <acronym>SSL</acronym>. If set to
|
|
<quote>1</quote>, <application>libpq</>
|
|
will refuse to connect if the server does not accept
|
|
an <acronym>SSL</acronym> connection (equivalent to <literal>sslmode</>
|
|
<literal>prefer</>).
|
|
This option is deprecated in favor of the <literal>sslmode</>
|
|
setting, and is only available if
|
|
<productname>PostgreSQL</> is compiled with SSL support.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGSSLKEY</envar></primary>
|
|
</indexterm>
|
|
<envar>PGSSLKEY</envar>
|
|
specifies the hardware token that stores the secret key for the client
|
|
certificate. The value of this variable should consist
|
|
of a colon-separated engine name (engines are <productname>OpenSSL</>
|
|
loadable modules) and an engine-specific key identifier. If this is not
|
|
set, the secret key must be kept in a file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGKRBSRVNAME</envar></primary>
|
|
</indexterm>
|
|
<envar>PGKRBSRVNAME</envar> sets the Kerberos service name to use when
|
|
authenticating with Kerberos 5 or GSSAPI.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGCONNECT_TIMEOUT</envar></primary>
|
|
</indexterm>
|
|
<envar>PGCONNECT_TIMEOUT</envar> sets the maximum number of seconds
|
|
that <application>libpq</application> will wait when attempting to
|
|
connect to the <productname>PostgreSQL</productname> server. If unset
|
|
or set to zero, <application>libpq</application> will wait indefinitely.
|
|
It is not recommended to set the timeout to less than 2 seconds.
|
|
</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-alteruser" endterm="sql-alteruser-title"> and
|
|
<xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">
|
|
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>PGCLIENTENCODING</envar></primary>
|
|
</indexterm>
|
|
<envar>PGCLIENTENCODING</envar>
|
|
sets the default client character set encoding.
|
|
(Equivalent to <literal>SET client_encoding 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" endterm="sql-set-title">
|
|
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</> file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGLOCALEDIR</envar></primary>
|
|
</indexterm>
|
|
<envar>PGLOCALEDIR</envar>
|
|
sets the directory containing the <literal>locale</> files for message
|
|
internationalization.
|
|
</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 or the
|
|
file referenced by <envar>PGPASSFILE</envar> 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</> (where
|
|
<filename>%APPDATA%</> refers to the Application Data subdirectory in
|
|
the user's profile).
|
|
</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>
|
|
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>.
|
|
A host name of <literal>localhost</> matches both TCP (hostname
|
|
<literal>localhost</>) and Unix domain socket (<literal>pghost</> empty or the
|
|
default socket directory) connections coming from the local machine.
|
|
</para>
|
|
|
|
<para>
|
|
On Unix systems, the permissions on <filename>.pgpass</filename> must disallow
|
|
any access to world or group; achieve this by the command
|
|
<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>
|
|
|
|
<para>
|
|
The connection service file allows libpq connection parameters to be
|
|
associated with a single service name. That service name can then be
|
|
specified by a libpq connection, and the associated settings will be
|
|
used. This allows connection parameters to be modified without requiring
|
|
a recompile of the libpq application. The service name can also be
|
|
specified using the <envar>PGSERVICE</envar> environment variable.
|
|
</para>
|
|
<para>
|
|
To use this feature, copy
|
|
<filename>share/pg_service.conf.sample</filename> to
|
|
<filename>etc/pg_service.conf</filename> and edit the file to add
|
|
service names and parameters. This file can be used for client-only
|
|
installs too. The file's location can also be specified by the
|
|
<envar>PGSYSCONFDIR</envar> environment variable.
|
|
</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 RFC 1959 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
|
|
<synopsis>
|
|
version:1
|
|
dn:cn=mydatabase,dc=mycompany,dc=com
|
|
changetype:add
|
|
objectclass:top
|
|
objectclass:groupOfUniqueNames
|
|
cn:mydatabase
|
|
uniqueMember:host=dbserver.mycompany.com
|
|
uniqueMember:port=5439
|
|
uniqueMember:dbname=mydb
|
|
uniqueMember:user=mydb_user
|
|
uniqueMember:sslmode=require
|
|
</synopsis>
|
|
might be queried with the following LDAP URL:
|
|
<synopsis>
|
|
ldap://ldap.mycompany.com/dc=mycompany,dc=com?uniqueMember?one?(cn=mydatabase)
|
|
</synopsis>
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="libpq-ssl">
|
|
<title>SSL Support</title>
|
|
|
|
<indexterm zone="libpq-ssl">
|
|
<primary>SSL</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</> has native support for using
|
|
<acronym>SSL</> connections to encrypt client/server communications
|
|
for increased security. See <xref linkend="ssl-tcp"> for details
|
|
about the server-side <acronym>SSL</> 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</>.
|
|
This default can be overridden by setting environment variable
|
|
<envar>OPENSSL_CONF</envar> to the name of the desired configuration
|
|
file.
|
|
</para>
|
|
|
|
<para>
|
|
If the server demands a client certificate,
|
|
<application>libpq</application>
|
|
will send the certificate stored in file
|
|
<filename>~/.postgresql/postgresql.crt</> within the user's home directory.
|
|
A matching private key file <filename>~/.postgresql/postgresql.key</>
|
|
must also be present, unless the secret key for the certificate is stored
|
|
in a hardware token, as specified by <envar>PGSSLKEY</envar>.
|
|
(On Microsoft Windows these files are named
|
|
<filename>%APPDATA%\postgresql\postgresql.crt</filename> and
|
|
<filename>%APPDATA%\postgresql\postgresql.key</filename>.)
|
|
The private key file must not be world-readable.
|
|
</para>
|
|
|
|
<para>
|
|
If the environment variable <envar>PGSSLKEY</envar> is set, its value
|
|
should consist of a colon-separated engine name and key identifier. In
|
|
this case, <application>libpq</application> will load the specified
|
|
engine, i.e. the <productname>OpenSSL</> module which supports special
|
|
hardware, and reference the key with the specified identifier.
|
|
Identifiers are engine-specific. Typically, cryptography hardware tokens
|
|
do not reveal secret keys to the application. Instead, applications
|
|
delegate all cryptography operations which require the secret key to
|
|
the hardware token.
|
|
</para>
|
|
|
|
<para>
|
|
If the file <filename>~/.postgresql/root.crt</> is present in the user's
|
|
home directory,
|
|
<application>libpq</application> will use the certificate list stored
|
|
therein to verify the server's certificate.
|
|
(On Microsoft Windows the file is named
|
|
<filename>%APPDATA%\postgresql\root.crt</filename>.)
|
|
The SSL connection will
|
|
fail if the server does not present a certificate; therefore, to
|
|
use this feature the server must have a <filename>server.crt</> file.
|
|
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>
|
|
If you are using <acronym>SSL</> inside your application (in addition to
|
|
inside <application>libpq</application>), you can use <function>PQinitSSL(int)</>
|
|
to tell <application>libpq</application> that the <acronym>SSL</> library
|
|
has already been initialized by your application.
|
|
</para>
|
|
|
|
|
|
</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 if the
|
|
<filename>configure</filename> command-line option
|
|
<literal>--enable-thread-safety</> was used when the
|
|
<productname>PostgreSQL</productname> distribution was built. In
|
|
addition, you might need to use additional 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</>
|
|
and <literal>PTHREAD_LIBS</>. This function allows the querying of
|
|
<application>libpq</application>'s thread-safe status:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><function>PQisthreadsafe</function><indexterm><primary>PQisthreadsafe</></></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</> 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</> objects are read-only after creation, and so can be
|
|
passed around freely between threads.
|
|
</para>
|
|
|
|
<para>
|
|
The deprecated functions
|
|
<function>PQrequestCancel</function> and
|
|
<function>PQoidStatus</function>
|
|
are not thread-safe and should not be used in multithread programs.
|
|
<function>PQrequestCancel</function> can be replaced by
|
|
<function>PQcancel</function>.
|
|
<function>PQoidStatus</function> can be replaced by
|
|
<function>PQoidValue</function>.
|
|
</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</> in the
|
|
<application>libpq</application> source code for a way to do cooperative
|
|
locking between <application>libpq</application> and your application.
|
|
</para>
|
|
|
|
<para>
|
|
If you experience problems with threaded applications, run
|
|
the program in <filename>src/tools/thread</> to see if your
|
|
platform has thread-unsafe functions. This program is run
|
|
by <filename>configure</filename>, but for binary distributions
|
|
your library might not match the library used to build the binaries.
|
|
</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</> 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</><secondary
|
|
sortas="libpq">with libpq</></> 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>
|
|
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>
|
|
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>
|
|
/*
|
|
* 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, "Connection to database failed: %s",
|
|
PQerrorMessage(conn));
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/*
|
|
* 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);
|
|
}
|
|
|
|
/*
|
|
* Should PQclear PGresult whenever it is no longer needed to avoid memory
|
|
* leaks
|
|
*/
|
|
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>
|
|
/*
|
|
* 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 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);
|
|
*
|
|
* and do this four times:
|
|
*
|
|
* INSERT INTO TBL1 VALUES (10);
|
|
*/
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <string.h>
|
|
#include <errno.h>
|
|
#include <sys/time.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, "Connection to database failed: %s",
|
|
PQerrorMessage(conn));
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/*
|
|
* 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);
|
|
}
|
|
|
|
/*
|
|
* should PQclear PGresult whenever it is no longer needed to avoid memory
|
|
* leaks
|
|
*/
|
|
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++;
|
|
}
|
|
}
|
|
|
|
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</>
|
|
|
|
<programlisting>
|
|
/*
|
|
* 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 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
|
|
*/
|
|
#include <stdio.h>
|
|
#include <stdlib.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, "Connection to database failed: %s",
|
|
PQerrorMessage(conn));
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/*
|
|
* 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>
|