mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-21 11:13:23 +02:00
2783 lines
94 KiB
Plaintext
2783 lines
94 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.104 2003/01/06 22:48:16 momjian Exp $
|
|
-->
|
|
|
|
<chapter id="libpq">
|
|
<title><application>libpq</application> - C Library</title>
|
|
|
|
<indexterm zone="libpq">
|
|
<primary>libpq</primary>
|
|
</indexterm>
|
|
|
|
<sect1 id="libpq-intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
<application>libpq</application> is the <acronym>C</acronym>
|
|
application programmer's interface to
|
|
<productname>PostgreSQL</productname>. <application>libpq</application> is a set
|
|
of library routines that allow client programs to pass queries to the
|
|
<productname>PostgreSQL</productname> backend server and to receive the
|
|
results of these queries. <application>libpq</application> is also the
|
|
underlying engine for several other <productname>PostgreSQL</productname>
|
|
application interfaces, including <application>libpq++</application> (C++),
|
|
<filename>libpgtcl</filename> (Tcl), <productname>Perl</productname>, and
|
|
<filename>ecpg</filename>. So some aspects of <application>libpq</>'s behavior will be
|
|
important to you if you use one of those packages.
|
|
</para>
|
|
|
|
<para>
|
|
Three short programs are included at the end of this section to show how
|
|
to write programs that use <filename>libpq</filename>. There are several
|
|
complete examples of <filename>libpq</filename> applications in the
|
|
following directories:
|
|
|
|
<simplelist>
|
|
<member><filename>src/test/examples</filename></member>
|
|
<member><filename>src/bin/psql</filename></member>
|
|
</simplelist>
|
|
</para>
|
|
|
|
<para>
|
|
Frontend programs that use <filename>libpq</filename> must include the
|
|
header file <filename>libpq-fe.h</filename> and must link with the
|
|
<filename>libpq</filename> library.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-connect">
|
|
<title>Database Connection Functions</title>
|
|
|
|
<para>
|
|
The following routines deal with making a connection to a
|
|
<productname>PostgreSQL</productname> backend server. The
|
|
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</> object which is obtained from
|
|
<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.
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQconnectdb</function>
|
|
Makes a new connection to the database server.
|
|
<synopsis>
|
|
PGconn *PQconnectdb(const char *conninfo)
|
|
</synopsis>
|
|
|
|
This routine 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 either of this routine or the nonblocking analogues <function>PQconnectStart</>
|
|
and <function>PQconnectPoll</function> is preferred for application programming. The passed string
|
|
can be empty to use all default parameters, or it can contain one or more
|
|
parameter settings separated by whitespace.
|
|
</para>
|
|
|
|
<para>
|
|
Each parameter setting is in the form <literal>keyword = value</literal>.
|
|
(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, e.g., <literal>\'</literal> or <literal>\\</literal>.)
|
|
Spaces around the equal sign are optional. The currently recognized
|
|
parameter keywords are:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>host</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Name of host to connect to.
|
|
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 is to connect to a Unix-domain socket in
|
|
<filename>/tmp</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>hostaddr</literal></term>
|
|
<listitem>
|
|
<para>
|
|
IP address of host to connect to. This should be in standard
|
|
IPv4 address format, e.g. <literal>172.28.40.9</>. If your machine
|
|
supports IPv6, you can also use those addresses. If a nonzero-length
|
|
string is specified, TCP/IP communication is used.
|
|
</para>
|
|
<para>
|
|
Using <literal>hostaddr</> instead of host allows the application to avoid a host
|
|
name look-up, which may be important in applications with time
|
|
constraints. However, Kerberos authentication requires the host
|
|
name. The following therefore applies: If host is specified without
|
|
<literal>hostaddr</>, a host name lookup is forced. If <literal>hostaddr</> is specified without
|
|
host, the value for <literal>hostaddr</> gives the remote address; if Kerberos is
|
|
used, this causes a reverse name query. If both host and <literal>hostaddr</> are
|
|
specified, the value for <literal>hostaddr</> gives the remote address; the value
|
|
for 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</>.
|
|
</para>
|
|
<para>
|
|
Without either a host name or host address, <application>libpq</application> will connect using a
|
|
local Unix domain socket.
|
|
</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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>dbname</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The database name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>user</literal></term>
|
|
<listitem>
|
|
<para>
|
|
User name to connect as.
|
|
</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>
|
|
Time space in seconds given to connect routine. Zero or not set means infinite.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>options</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Trace/debug options to be sent to the server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>tty</literal></term>
|
|
<listitem>
|
|
<para>
|
|
A file or <acronym>tty</acronym> for optional debug output from the backend.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>requiressl</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Set to 1 to require SSL connection to the backend. <application>Libpq</>
|
|
will then refuse to connect if the server does not support
|
|
SSL. Set to 0 (default) to negotiate with server.
|
|
</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 hardwired defaults are used.
|
|
The return value is a pointer to an abstract <type>struct</type>
|
|
representing the connection to the backend.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQsetdbLogin</function>
|
|
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>
|
|
|
|
This is the predecessor of <function>PQconnectdb</function> with a fixed number
|
|
of parameters but the same functionality.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQsetdb</function> Makes a new connection to the database server.
|
|
<synopsis>
|
|
PGconn *PQsetdb(char *pghost,
|
|
char *pgport,
|
|
char *pgoptions,
|
|
char *pgtty,
|
|
char *dbName)
|
|
</synopsis>
|
|
This is a macro that calls <function>PQsetdbLogin</function> with null pointers
|
|
for the <parameter>login</> and <parameter>pwd</> parameters. It is provided primarily
|
|
for backward compatibility with old programs.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQconnectStart</function>,
|
|
<function>PQconnectPoll</function>
|
|
<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>
|
|
These two routines 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.
|
|
</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, as 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 for yourself that the socket is in the appropriate state
|
|
before calling <function>PQconnectPoll</function>, as described below.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
To begin, 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 status 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 may
|
|
proceed with the connection sequence. Loop thus: Consider a connection
|
|
<quote>inactive</quote> by default. If <function>PQconnectPoll</function> last returned <symbol>PGRES_POLLING_ACTIVE</>,
|
|
consider it <quote>active</quote> instead. If <function>PQconnectPoll(conn)</function> last returned
|
|
<symbol>PGRES_POLLING_READING</symbol>, perform a <function>select()</> for reading on <function>PQsocket(conn)</function>. If
|
|
it last returned <symbol>PGRES_POLLING_WRITING</symbol>, perform a <function>select()</> for writing on
|
|
<function>PQsocket(conn)</function>. If you have yet to call <function>PQconnectPoll</function>, i.e. after the call
|
|
to <function>PQconnectStart</function>, behave as if it last returned <symbol>PGRES_POLLING_WRITING</symbol>. If
|
|
the <function>select()</> shows that the socket is ready, consider it <quote>active</quote>. If it has
|
|
been decided that this connection is <quote>active</quote>, call <function>PQconnectPoll(conn)</function>
|
|
again. If this call returns <symbol>PGRES_POLLING_FAILED</symbol>, the connection procedure
|
|
has failed. If this call returns <symbol>PGRES_POLLING_OK</symbol>, the connection has been
|
|
successfully made.
|
|
</para>
|
|
|
|
<para>
|
|
Note that the use of <function>select()</function> to ensure that the socket is ready is merely
|
|
a (likely) example; those with other facilities available, such as a
|
|
<function>poll()</function> call, may of course use that instead.
|
|
</para>
|
|
|
|
<para>
|
|
At any time during connection, the status of the connection may be
|
|
checked, by calling <function>PQstatus</>. If this is <symbol>CONNECTION_BAD</>, then the
|
|
connection procedure has failed; if this is <function>CONNECTION_OK</>, then the
|
|
connection is ready. Either of these states should be equally detectable
|
|
from the return value of <function>PQconnectPoll</>, as above. Other states may be
|
|
shown during (and only during) an asynchronous connection procedure. These
|
|
indicate the current stage of the connection procedure, and may be useful
|
|
to provide feedback to the user for example. These statuses may include:
|
|
|
|
<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 connection start-up to continue.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><symbol>CONNECTION_SETENV</symbol></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Negotiating environment (part of the connection start-up).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
Note that, although these constants will remain (in order to maintain
|
|
compatibility), an application should never rely upon these appearing in a
|
|
particular order, or at all, or on the status always being one of these
|
|
documented values. An application may 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>
|
|
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 a
|
|
call to <function>PQconnectStart</function> or <function>PQconnectPoll</function> failed.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQconnectPoll</function> will currently block if
|
|
<application>libpq</> is compiled with <symbol>USE_SSL</symbol>
|
|
defined. This restriction may be removed in the future.
|
|
</para>
|
|
|
|
<para>
|
|
These functions leave the socket in a nonblocking state as if
|
|
<function>PQsetnonblocking</function> had been called.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQconndefaults</function> Returns the default connection options.
|
|
<synopsis>
|
|
PQconninfoOption *PQconndefaults(void)
|
|
|
|
struct PQconninfoOption
|
|
{
|
|
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 */
|
|
}
|
|
</synopsis>
|
|
Returns a connection options array. This may
|
|
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> <type>struct</>s, which ends with an entry having a NULL
|
|
keyword pointer. Note that the 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>
|
|
|
|
<para>
|
|
In <productname>PostgreSQL</productname> versions before 7.0, <function>PQconndefaults</function> returned a pointer
|
|
to a static array, rather than a dynamically allocated array. That
|
|
was not thread-safe, so the behavior has been changed.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQfinish</function>
|
|
Close the connection to the backend. Also frees
|
|
memory used by the <structname>PGconn</structname> object.
|
|
<synopsis>
|
|
void PQfinish(PGconn *conn)
|
|
</synopsis>
|
|
Note that even if the backend 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 should not be used after <function>PQfinish</function> has been called.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQreset</function>
|
|
Reset the communication port with the backend.
|
|
<synopsis>
|
|
void PQreset(PGconn *conn)
|
|
</synopsis>
|
|
This function will close the connection
|
|
to the backend and attempt to reestablish a new
|
|
connection to the same server, using all the same
|
|
parameters previously used. This may be useful for
|
|
error recovery if a working connection is lost.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQresetStart</function>
|
|
<function>PQresetPoll</function>
|
|
Reset the communication port with the backend, in a nonblocking manner.
|
|
<synopsis>
|
|
int PQresetStart(PGconn *conn);
|
|
</synopsis>
|
|
<synopsis>
|
|
PostgresPollingStatusType PQresetPoll(PGconn *conn);
|
|
</synopsis>
|
|
These functions will close the connection to the backend and attempt to
|
|
reestablish a new connection to the same server, using all the same
|
|
parameters previously used. This may 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>
|
|
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>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<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 below to get
|
|
at the contents of <structname>PGconn</structname>. Avoid directly referencing the fields of the
|
|
<structname>PGconn</> structure because they are subject to change in the future.
|
|
(Beginning in <productname>PostgreSQL</productname> release 6.4, the
|
|
definition of <type>struct PGconn</> is not even provided in <filename>libpq-fe.h</filename>.
|
|
If you have old code that accesses <structname>PGconn</structname> fields directly, you can keep using it
|
|
by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code
|
|
soon.)
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQdb</function>
|
|
Returns the database name of the connection.
|
|
<synopsis>
|
|
char *PQdb(const PGconn *conn)
|
|
</synopsis>
|
|
<function>PQdb</> and the next several functions return the values established
|
|
at connection. These values are fixed for the life of the <structname>PGconn</>
|
|
object.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQuser</function>
|
|
Returns the user name of the connection.
|
|
<synopsis>
|
|
char *PQuser(const PGconn *conn)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQpass</function>
|
|
Returns the password of the connection.
|
|
<synopsis>
|
|
char *PQpass(const PGconn *conn)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQhost</function>
|
|
Returns the server host name of the connection.
|
|
<synopsis>
|
|
char *PQhost(const PGconn *conn)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQport</function>
|
|
Returns the port of the connection.
|
|
<synopsis>
|
|
char *PQport(const PGconn *conn)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQtty</function>
|
|
Returns the debug <acronym>tty</acronym> of the connection.
|
|
<synopsis>
|
|
char *PQtty(const PGconn *conn)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQoptions</function>
|
|
Returns the backend options used in the connection.
|
|
<synopsis>
|
|
char *PQoptions(const PGconn *conn)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQstatus</function>
|
|
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> or
|
|
<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>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQerrorMessage</function>
|
|
<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
|
|
<function>PQerrorMessage</function> if they fail.
|
|
Note that by <application>libpq</application> convention, a non-empty
|
|
<function>PQerrorMessage</function> will
|
|
include a trailing newline.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQbackendPID</function>
|
|
Returns the process <acronym>ID</acronym> of the backend server
|
|
handling this connection.
|
|
<synopsis>
|
|
int PQbackendPID(const PGconn *conn);
|
|
</synopsis>
|
|
The backend <acronym>PID</acronym> is useful for debugging
|
|
purposes and for comparison
|
|
to NOTIFY messages (which include the <acronym>PID</acronym> of
|
|
the notifying backend).
|
|
Note that the <acronym>PID</acronym> belongs to a process
|
|
executing on the database
|
|
server host, not the local host!
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQgetssl</function>
|
|
<indexterm><primary>SSL</></>
|
|
Returns the SSL structure used in the connection, or NULL
|
|
if SSL is not in use.
|
|
<synopsis>
|
|
SSL *PQgetssl(const PGconn *conn);
|
|
</synopsis>
|
|
This structure can be used to verify encryption levels, check
|
|
server certificate and more. Refer to the SSL documentation
|
|
for information about this structure.
|
|
</para>
|
|
<para>
|
|
You must define <literal>USE_SSL</literal> in order to get the
|
|
prototype for this function. Doing this will also
|
|
automatically include <filename>ssl.h</filename> from <productname>OpenSSL</productname>.
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</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 Routines</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQexec</function>
|
|
Submit a command to the server
|
|
and wait for the result.
|
|
<synopsis>
|
|
PGresult *PQexec(PGconn *conn,
|
|
const char *query);
|
|
</synopsis>
|
|
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 backend.
|
|
If a NULL is returned, it
|
|
should be treated like a <symbol>PGRES_FATAL_ERROR</symbol> result. Use
|
|
<function>PQerrorMessage</function> to get more information about the error.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The <function>PGresult</function> structure encapsulates the result
|
|
returned by the backend.
|
|
<filename>libpq</filename> 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.
|
|
(Beginning in <productname>PostgreSQL</productname> 6.4, the
|
|
definition of <type>struct PGresult</> is not even provided in <filename>libpq-fe.h</>. If you
|
|
have old code that accesses <structname>PGresult</structname> fields directly, you can keep using it
|
|
by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code
|
|
soon.)
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQresultStatus</function>
|
|
Returns the result status of the command.
|
|
<synopsis>
|
|
ExecStatusType PQresultStatus(const PGresult *res)
|
|
</synopsis>
|
|
<function>PQresultStatus</function> can return one of the following values:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>PGRES_EMPTY_QUERY</literal> -- The string sent to the backend was empty.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>PGRES_COMMAND_OK</literal> -- Successful completion of a command returning no data</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>PGRES_TUPLES_OK</literal> -- The query successfully executed</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>PGRES_COPY_OUT</literal> -- Copy Out (from server) data transfer started</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>PGRES_COPY_IN</literal> -- Copy In (to server) data transfer started</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>PGRES_BAD_RESPONSE</literal> -- The server's response was not understood</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>PGRES_NONFATAL_ERROR</literal></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>PGRES_FATAL_ERROR</literal></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
If the result status is <literal>PGRES_TUPLES_OK</literal>, then the
|
|
routines described below can be used to retrieve the
|
|
rows returned by the query. Note that a SELECT 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
|
|
(INSERT, UPDATE, etc.). A response of <literal>PGRES_EMPTY_QUERY</literal> often
|
|
exposes a bug in the client software.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQresStatus</function>
|
|
Converts the enumerated type returned by <function>PQresultStatus</> into
|
|
a string constant describing the status code.
|
|
<synopsis>
|
|
char *PQresStatus(ExecStatusType status);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQresultErrorMessage</function>
|
|
returns the error message associated with the query, or an empty string
|
|
if there was no error.
|
|
<synopsis>
|
|
char *PQresultErrorMessage(const PGresult *res);
|
|
</synopsis>
|
|
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>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQclear</function>
|
|
Frees the storage associated with the <structname>PGresult</structname>.
|
|
Every query result should be freed via <function>PQclear</function> when
|
|
it is no longer needed.
|
|
<synopsis>
|
|
void PQclear(PQresult *res);
|
|
</synopsis>
|
|
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 query,
|
|
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 the frontend application.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQmakeEmptyPGresult</function>
|
|
Constructs an empty <structname>PGresult</structname> object with the given status.
|
|
<synopsis>
|
|
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
|
|
</synopsis>
|
|
This is <application>libpq</>'s internal routine to allocate and initialize an empty
|
|
<structname>PGresult</structname> object. 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 status indicates an error,
|
|
the connection's current error message 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>
|
|
</itemizedlist>
|
|
</sect2>
|
|
|
|
<sect2 id="libpq-exec-escape-string">
|
|
<title>Escaping strings for inclusion in SQL queries</title>
|
|
|
|
<indexterm zone="libpq-exec-escape-string"><primary>escaping strings</></>
|
|
|
|
<para>
|
|
<function>PQescapeString</function>
|
|
Escapes a string for use within an SQL query.
|
|
<synopsis>
|
|
size_t PQescapeString (char *to, const char *from, size_t length);
|
|
</synopsis>
|
|
If you want to include strings that have been received
|
|
from a source that is not trustworthy (for example, because a random user
|
|
entered them), you cannot directly include them in SQL
|
|
queries for security reasons. Instead, you have to quote special
|
|
characters that are otherwise interpreted by the SQL parser.
|
|
</para>
|
|
<para>
|
|
<function>PQescapeString</> performs this operation. The
|
|
<parameter>from</> points to the first character of the string that
|
|
is to be escaped, and the <parameter>length</> parameter counts the
|
|
number of characters in this string (a terminating zero byte is
|
|
neither necessary nor counted). <parameter>to</> shall point to a
|
|
buffer that is able to hold at least one more character than twice
|
|
the value of <parameter>length</>, otherwise the behavior is
|
|
undefined. A call to <function>PQescapeString</> writes an escaped
|
|
version of the <parameter>from</> string to the <parameter>to</>
|
|
buffer, replacing 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 part of the result
|
|
string.
|
|
</para>
|
|
<para>
|
|
<function>PQescapeString</> returns the number of characters written
|
|
to <parameter>to</>, not including the terminating zero byte.
|
|
Behavior is undefined when the <parameter>to</> and <parameter>from</>
|
|
strings overlap.
|
|
</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="libpq-exec-escape-bytea">
|
|
<title>Escaping binary strings for inclusion in SQL queries</title>
|
|
<indexterm zone="libpq-exec-escape-bytea">
|
|
<primary>escaping binary strings</primary>
|
|
</indexterm>
|
|
<para>
|
|
<function>PQescapeBytea</function>
|
|
Escapes a binary string (<type>bytea</type> type) for use within an SQL query.
|
|
<synopsis>
|
|
unsigned char *PQescapeBytea(const unsigned char *from,
|
|
size_t from_length,
|
|
size_t *to_length);
|
|
</synopsis>
|
|
|
|
Certain <acronym>ASCII</acronym> characters <emphasis>must</emphasis>
|
|
be escaped (but all characters <emphasis>may</emphasis> be escaped)
|
|
when used as part of a <type>bytea</type>
|
|
string literal in an <acronym>SQL</acronym> statement. In general, to
|
|
escape a character, it is converted into the three digit octal number
|
|
equal to the decimal <acronym>ASCII</acronym> value, and preceded by
|
|
two backslashes. The single quote (') and backslash (\) characters have
|
|
special alternate escape sequences. See the <citetitle>User's Guide</citetitle>
|
|
for more information. <function>PQescapeBytea
|
|
</function> performs this operation, escaping only the minimally
|
|
required characters.
|
|
</para>
|
|
|
|
<para>
|
|
The <parameter>from</parameter> parameter points to the first
|
|
character of the string that is to be escaped, and the
|
|
<parameter>from_length</parameter> parameter reflects the number of
|
|
characters in this binary string (a terminating zero byte is
|
|
neither necessary nor counted). The <parameter>to_length</parameter>
|
|
parameter shall point to a buffer suitable to hold the resultant
|
|
escaped string length. The result string length includes the terminating
|
|
zero byte of the result.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQescapeBytea</> returns an escaped version of the
|
|
<parameter>from</parameter> parameter binary string, to a
|
|
caller-provided buffer. The return string has all special
|
|
characters replaced so that they can be properly processed by the
|
|
<productname>PostgreSQL</> 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</> string literals are not part of the
|
|
result string.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQunescapeBytea</function>
|
|
Converts an escaped string representation of binary data into binary
|
|
data - the reverse of <function>PQescapeBytea</function>.
|
|
<synopsis>
|
|
unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
|
|
</synopsis>
|
|
|
|
The <parameter>from</parameter> parameter points to an escaped string
|
|
such as might be returned by <function>PQgetvalue</function> of a
|
|
<type>BYTEA</type> column. <function>PQunescapeBytea</function> converts
|
|
this string representation into its binary representation, filling the supplied buffer.
|
|
It returns a pointer to the buffer which is NULL on error, and the size
|
|
of the buffer in <parameter>to_length</parameter>. The pointer may
|
|
subsequently be used as an argument to the function
|
|
<function>free(3)</function>.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="libpq-exec-select-info">
|
|
<title>Retrieving SELECT Result Information</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQntuples</function>
|
|
Returns the number of tuples (rows)
|
|
in the query result.
|
|
<synopsis>
|
|
int PQntuples(const PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQnfields</function>
|
|
Returns the number of fields
|
|
(columns) in each row of the query result.
|
|
<synopsis>
|
|
int PQnfields(const PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQfname</function>
|
|
Returns the field (column) name associated with the given field index.
|
|
Field indices start at 0.
|
|
<synopsis>
|
|
char *PQfname(const PGresult *res,
|
|
int field_index);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQfnumber</function>
|
|
Returns the field (column) index
|
|
associated with the given field name.
|
|
<synopsis>
|
|
int PQfnumber(const PGresult *res,
|
|
const char *field_name);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
-1 is returned if the given name does not match any field.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQftype</function>
|
|
Returns the field type associated with the
|
|
given field index. The integer returned is an
|
|
internal coding of the type. Field indices start
|
|
at 0.
|
|
<synopsis>
|
|
Oid PQftype(const PGresult *res,
|
|
int field_index);
|
|
</synopsis>
|
|
You can query the system table <literal>pg_type</literal> to obtain
|
|
the name and properties of the various data types. The <acronym>OID</acronym>s
|
|
of the built-in data types are defined in <filename>src/include/catalog/pg_type.h</filename>
|
|
in the source tree.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQfmod</function>
|
|
Returns the type-specific modification data of the field
|
|
associated with the given field index.
|
|
Field indices start at 0.
|
|
<synopsis>
|
|
int PQfmod(const PGresult *res,
|
|
int field_index);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQfsize</function>
|
|
Returns the size in bytes of the field
|
|
associated with the given field index.
|
|
Field indices start at 0.
|
|
<synopsis>
|
|
int PQfsize(const PGresult *res,
|
|
int field_index);
|
|
</synopsis>
|
|
<function>PQfsize</> returns the space allocated for this field in a database
|
|
tuple, in other words the size of the server's binary representation
|
|
of the data type. -1 is returned if the field is variable size.
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQbinaryTuples</function>
|
|
Returns 1 if the <structname>PGresult</> contains binary tuple data,
|
|
0 if it contains ASCII data.
|
|
<synopsis>
|
|
int PQbinaryTuples(const PGresult *res);
|
|
</synopsis>
|
|
Currently, binary tuple data can only be returned by a query that
|
|
extracts data from a binary cursor.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
|
|
<sect2 id="libpq-exec-select-values">
|
|
<title>Retrieving SELECT Result Values</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQgetvalue</function>
|
|
Returns a single field (column) value of one tuple (row)
|
|
of a <structname>PGresult</structname>.
|
|
Tuple and field indices start at 0.
|
|
<synopsis>
|
|
char* PQgetvalue(const PGresult *res,
|
|
int tup_num,
|
|
int field_num);
|
|
</synopsis>
|
|
For most queries, the value returned by <function>PQgetvalue</function>
|
|
is a null-terminated character string representation
|
|
of the attribute value. But if <function>PQbinaryTuples()</function> is 1,
|
|
the value returned by <function>PQgetvalue</function> is the binary
|
|
representation of the
|
|
type in the internal format of the backend server
|
|
(but not including the size word, if the field is variable-length).
|
|
It is then the programmer's responsibility to cast and
|
|
convert the data to the correct C type. The pointer
|
|
returned by <function>PQgetvalue</function> points to storage that is
|
|
part of the <structname>PGresult</structname> structure. One should not modify it,
|
|
and one must explicitly
|
|
copy the value into other storage if it is to
|
|
be used past the lifetime of the <structname>PGresult</structname> structure itself.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQgetisnull</function>
|
|
Tests a field for a NULL entry.
|
|
Tuple and field indices start at 0.
|
|
<synopsis>
|
|
int PQgetisnull(const PGresult *res,
|
|
int tup_num,
|
|
int field_num);
|
|
</synopsis>
|
|
This function returns 1 if the field contains a NULL, 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>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQgetlength</function>
|
|
Returns the length of a field (attribute) value in bytes.
|
|
Tuple and field indices start at 0.
|
|
<synopsis>
|
|
int PQgetlength(const PGresult *res,
|
|
int tup_num,
|
|
int field_num);
|
|
</synopsis>
|
|
This is the actual data length for the particular data value, that is the
|
|
size of the object pointed to by <function>PQgetvalue</function>. Note that for character-represented
|
|
values, this size has little to do with the binary size reported by <function>PQfsize</function>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQprint</function>
|
|
Prints out all the tuples and, optionally, the
|
|
attribute names to the specified output stream.
|
|
<synopsis>
|
|
void PQprint(FILE* fout, /* output stream */
|
|
const PGresult *res,
|
|
const PQprintOpt *po);
|
|
|
|
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; /* insert to HTML <replaceable>table ...</replaceable> */
|
|
char *caption; /* HTML <replaceable>caption</replaceable> */
|
|
char **fieldName; /* null terminated array of replacement field names */
|
|
} PQprintOpt;
|
|
</synopsis>
|
|
This function was formerly used by <application>psql</application>
|
|
to print query results, but this is no longer the case and this
|
|
function is no longer actively supported.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
|
|
<sect2 id="libpq-exec-nonselect">
|
|
<title>Retrieving Non-SELECT Result Information</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQcmdStatus</function>
|
|
Returns the command status string from the SQL command that
|
|
generated the <structname>PGresult</structname>.
|
|
<synopsis>
|
|
char * PQcmdStatus(PGresult *res);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQcmdTuples</function>
|
|
Returns the number of rows affected by the SQL command.
|
|
<synopsis>
|
|
char * PQcmdTuples(PGresult *res);
|
|
</synopsis>
|
|
If the <acronym>SQL</acronym> command that generated the
|
|
<structname>PGresult</structname> was INSERT, UPDATE or DELETE, this returns a
|
|
string containing the number of rows affected. If the
|
|
command was anything else, it returns the empty string.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQoidValue</function>
|
|
Returns the object ID of the inserted row, if the
|
|
<acronym>SQL</acronym> command was an INSERT
|
|
that inserted exactly one row into a table that has OIDs.
|
|
Otherwise, returns <literal>InvalidOid</literal>.
|
|
<synopsis>
|
|
Oid PQoidValue(const PGresult *res);
|
|
</synopsis>
|
|
The type <type>Oid</type> and the constant <literal>InvalidOid</literal>
|
|
will be defined if you include the <application>libpq</application>
|
|
header file. They will both be some integer type.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQoidStatus</function>
|
|
Returns a string with the object ID of the inserted row, if the
|
|
<acronym>SQL</acronym> command was an INSERT.
|
|
(The string will be <literal>0</> if the INSERT did not insert exactly one
|
|
row, or if the target table does not have OIDs.) If the command
|
|
was not an INSERT, returns an empty string.
|
|
<synopsis>
|
|
char * PQoidStatus(const PGresult *res);
|
|
</synopsis>
|
|
This function is deprecated in favor of <function>PQoidValue</function>
|
|
and is not thread-safe.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-async">
|
|
<title>Asynchronous Query Processing</title>
|
|
|
|
<indexterm zone="libpq-async"><primary>nonblocking connection</></>
|
|
|
|
<para>
|
|
The <function>PQexec</function> function is adequate for submitting commands in
|
|
simple synchronous
|
|
applications. It has a couple of major deficiencies however:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQexec</function> waits for the command to be completed. The application may 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 control is buried inside <function>PQexec</function>, it is hard for the frontend
|
|
to decide 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>.
|
|
</para>
|
|
<para>
|
|
Older programs that used this functionality as well as
|
|
<function>PQputline</function> and <function>PQputnbytes</function>
|
|
could block waiting to send data to the backend. To
|
|
address that issue, the function <function>PQsetnonblocking</function>
|
|
was added.
|
|
</para>
|
|
<para>
|
|
Old applications can neglect to use <function>PQsetnonblocking</function>
|
|
and get the older potentially blocking behavior. Newer programs can use
|
|
<function>PQsetnonblocking</function> to achieve a completely nonblocking
|
|
connection to the backend.
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQsetnonblocking</function> Sets the nonblocking status of the
|
|
connection.
|
|
<synopsis>
|
|
int PQsetnonblocking(PGconn *conn, int arg)
|
|
</synopsis>
|
|
Sets the state of the connection to nonblocking if <parameter>arg</parameter> is 1,
|
|
blocking if <parameter>arg</parameter> is 0. Returns 0 if OK, -1 if error.
|
|
</para>
|
|
<para>
|
|
In the nonblocking state, calls to
|
|
<function>PQputline</function>, <function>PQputnbytes</function>,
|
|
<function>PQsendQuery</function> and <function>PQendcopy</function>
|
|
will not block but instead return an error if they need to be called
|
|
again.
|
|
</para>
|
|
<para>
|
|
When a database connection has been set to nonblocking mode and
|
|
<function>PQexec</function> is called, it will temporarily set the state
|
|
of the connection to blocking until the <function>PQexec</function>
|
|
completes.
|
|
</para>
|
|
<para>
|
|
More of <application>libpq</application> is expected to be made safe for
|
|
<function>PQsetnonblocking</function> functionality in the near future.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQisnonblocking</function>
|
|
Returns the blocking status of the database connection.
|
|
<synopsis>
|
|
int PQisnonblocking(const PGconn *conn)
|
|
</synopsis>
|
|
Returns 1 if the connection is set to nonblocking mode,
|
|
0 if blocking.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQsendQuery</function>
|
|
Submit a command to the server without
|
|
waiting for the result(s). 1 is returned if the command was
|
|
successfully dispatched, 0 if not (in which case, use
|
|
<function>PQerrorMessage</> to get more information about the failure).
|
|
<synopsis>
|
|
int PQsendQuery(PGconn *conn,
|
|
const char *query);
|
|
</synopsis>
|
|
After successfully calling <function>PQsendQuery</function>, call
|
|
<function>PQgetResult</function> one or more
|
|
times to obtain the results. <function>PQsendQuery</function> may not be called
|
|
again (on the same connection) until <function>PQgetResult</function> has returned NULL,
|
|
indicating that the command is done.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQgetResult</function>
|
|
Wait for the next result from a prior <function>PQsendQuery</function>,
|
|
and return it. NULL is returned when the query is complete
|
|
and there will be no more results.
|
|
<synopsis>
|
|
PGresult *PQgetResult(PGconn *conn);
|
|
</synopsis>
|
|
<function>PQgetResult</function> must be called repeatedly until it returns NULL,
|
|
indicating that the command is done. (If called when no command is
|
|
active, <function>PQgetResult</function> will just return NULL 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 query is active and the
|
|
necessary response data has not yet been read by <function>PQconsumeInput</function>.
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</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 frontend can be handling the
|
|
results of one query while the backend is still working on later
|
|
queries in the same command string.) However, calling <function>PQgetResult</function> will
|
|
still cause the frontend to block until the backend completes the
|
|
next <acronym>SQL</acronym> command. This can be avoided by proper use of three more
|
|
functions:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQconsumeInput</function>
|
|
If input is available from the backend, consume it.
|
|
<synopsis>
|
|
int PQconsumeInput(PGconn *conn);
|
|
</synopsis>
|
|
<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> is set). Note that the result does not say
|
|
whether any input data was actually collected. After calling
|
|
<function>PQconsumeInput</function>, the application may check
|
|
<function>PQisBusy</function> and/or <function>PQnotifies</function> to see if
|
|
their state has changed.
|
|
</para>
|
|
<para>
|
|
<function>PQconsumeInput</function> may be called even if the application is not
|
|
prepared to deal with a result or notification just yet. The
|
|
routine 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>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQisBusy</function>
|
|
Returns 1 if a query 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>
|
|
<function>PQisBusy</function> will not itself attempt to read data from the backend;
|
|
therefore <function>PQconsumeInput</function> must be invoked first, or the busy
|
|
state will never end.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQflush</function> Attempt to flush any data queued to the backend,
|
|
returns 0 if successful (or if the send queue is empty) or <symbol>EOF</symbol> if it failed for
|
|
some reason.
|
|
<synopsis>
|
|
int PQflush(PGconn *conn);
|
|
</synopsis>
|
|
<function>PQflush</function> needs to be called on a nonblocking connection
|
|
before calling <function>select()</function> to determine if a response has
|
|
arrived. If 0 is returned it ensures that there is no data queued to the
|
|
backend that has not actually been sent. Only applications that have used
|
|
<function>PQsetnonblocking</function> have a need for this.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQsocket</function>
|
|
Obtain the file descriptor number for the backend connection socket.
|
|
A valid descriptor will be >= 0; a result of -1 indicates that
|
|
no backend connection is currently open.
|
|
<synopsis>
|
|
int PQsocket(const PGconn *conn);
|
|
</synopsis>
|
|
<function>PQsocket</function> should be used to obtain the backend socket descriptor
|
|
in preparation for executing <function>select()</function>. This allows an
|
|
application using a blocking connection to wait for either backend responses or
|
|
other conditions.
|
|
If the result of <function>select()</function> indicates that data can be read from
|
|
the backend socket, then <function>PQconsumeInput</function> should be called to read the
|
|
data; after which, <function>PQisBusy</function>, <function>PQgetResult</function>,
|
|
and/or <function>PQnotifies</function> can be used to process the response.
|
|
</para>
|
|
<para>
|
|
Nonblocking connections (that have used <function>PQsetnonblocking</function>)
|
|
should not use <function>select()</function> until <function>PQflush</function>
|
|
has returned 0 indicating that there is no buffered data waiting to be sent
|
|
to the backend.
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
A typical frontend using these functions will have a main loop that uses
|
|
<function>select</function> to wait for all the conditions that it must
|
|
respond to. One of the conditions will be input available from the backend,
|
|
which in <function>select</function>'s terms is 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 NOTIFY messages (see <xref linkend="libpq-notify">).
|
|
</para>
|
|
|
|
<para>
|
|
A frontend that uses <function>PQsendQuery</function>/<function>PQgetResult</function>
|
|
can also attempt to cancel a command that is still being processed by the backend.
|
|
</para>
|
|
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQrequestCancel</function>
|
|
Request that <productname>PostgreSQL</productname> abandon
|
|
processing of the current command.
|
|
<synopsis>
|
|
int PQrequestCancel(PGconn *conn);
|
|
</synopsis>
|
|
The return value is 1 if the cancel request was successfully
|
|
dispatched, 0 if not. (If not, <function>PQerrorMessage</function> tells why not.)
|
|
Successful dispatch is no guarantee that the request will have any
|
|
effect, however. Regardless of the return value of <function>PQrequestCancel</function>,
|
|
the application must continue with the normal result-reading
|
|
sequence using <function>PQgetResult</function>. If the cancellation
|
|
is effective, the current command will terminate early and return
|
|
an error result. If the cancellation fails (say, because the
|
|
backend was already done processing the command), then there will
|
|
be no visible result at all.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Note that if the current command is part of a transaction, cancellation
|
|
will abort the whole transaction.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQrequestCancel</function> can safely be invoked from a signal handler.
|
|
So, it is also possible to use it in conjunction with plain
|
|
<function>PQexec</function>, if the decision to cancel can be made in a signal
|
|
handler. For example, <application>psql</application> invokes
|
|
<function>PQrequestCancel</function> from a <systemitem>SIGINT</> signal handler, thus allowing
|
|
interactive cancellation of queries that it issues through <function>PQexec</function>.
|
|
Note that <function>PQrequestCancel</function> will have no effect if the connection
|
|
is not currently open or the backend is not currently processing a command.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-fastpath">
|
|
<title>The Fast-Path Interface</title>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> provides a fast-path interface to send
|
|
function calls to the backend. This is a trapdoor into system internals and
|
|
can be a potential security hole. Most users will not need this feature.
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQfn</function>
|
|
Request execution of a backend 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);
|
|
</synopsis>
|
|
The <parameter>fnid</> argument is the object identifier of the function to be
|
|
executed.
|
|
<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 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
|
|
tells <application>libpq</> to byte-swap the value if necessary, so that it is
|
|
delivered as a proper int value for the client machine. When
|
|
<parameter>result_is_int</> is 0, the byte string sent by the backend is returned
|
|
unmodified.)
|
|
<parameter>args</> and <parameter>nargs</> specify the arguments to be passed to the function.
|
|
<synopsis>
|
|
typedef struct {
|
|
int len;
|
|
int isint;
|
|
union {
|
|
int *ptr;
|
|
int integer;
|
|
} u;
|
|
} PQArgBlock;
|
|
</synopsis>
|
|
<function>PQfn</function> always returns a valid <structname>PGresult*</structname>. 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>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-notify">
|
|
<title>Asynchronous Notification</title>
|
|
|
|
<indexterm zone="libpq-notify"><primary>NOTIFY</primary></indexterm>
|
|
|
|
<para>
|
|
<productname>PostgreSQL</productname> supports asynchronous notification via the
|
|
<command>LISTEN</command> and <command>NOTIFY</command> commands. A backend 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 backends listening on a
|
|
particular condition will be notified asynchronously when a <command>NOTIFY</command> of that
|
|
condition name is executed by any backend. 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 relation.
|
|
Commonly the condition name is the same as the associated relation, but it is
|
|
not necessary for there to be any associated relation.
|
|
</para>
|
|
|
|
<para>
|
|
<filename>libpq</filename> applications submit <command>LISTEN</command> and <command>UNLISTEN</command>
|
|
commands as ordinary SQL command. Subsequently, arrival of <command>NOTIFY</command>
|
|
messages can be detected by calling <function>PQnotifies</function>.
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQnotifies</function>
|
|
Returns the next notification from a list of unhandled
|
|
notification messages received from the backend. Returns NULL 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; /* name of relation containing data */
|
|
int be_pid; /* process id of backend */
|
|
} PGnotify;
|
|
</synopsis>
|
|
After processing a <structname>PGnotify</structname> object returned by <function>PQnotifies</function>,
|
|
be sure to free it with <function>free()</function> to avoid a memory leak.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
In <productname>PostgreSQL</productname> 6.4 and later,
|
|
the <literal>be_pid</literal> is that of the notifying backend,
|
|
whereas in earlier versions it was always the <acronym>PID</acronym> of your own backend.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
The second sample program gives an example of the use
|
|
of asynchronous notification.
|
|
</para>
|
|
|
|
<para>
|
|
<function>PQnotifies()</function> does not actually read backend data; 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 NOTIFY messages was to constantly submit queries,
|
|
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 NOTIFY
|
|
messages when you have no useful queries to make is to call
|
|
<function>PQconsumeInput()</function>, then check
|
|
<function>PQnotifies()</function>.
|
|
You can use <function>select()</function> to wait for backend data to
|
|
arrive, 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 queries 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 query.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-copy">
|
|
<title>Functions Associated with the COPY Command</title>
|
|
|
|
<indexterm zone="libpq-copy">
|
|
<primary>COPY</primary>
|
|
<secondary>with libpq</secondary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
The COPY command in <productname>PostgreSQL</productname> has options to read from
|
|
or write to the network connection used by <filename>libpq</filename>.
|
|
Therefore, functions are necessary to access this network
|
|
connection directly so applications may take advantage of this capability.
|
|
</para>
|
|
|
|
<para>
|
|
These functions should be executed only after obtaining a <literal>PGRES_COPY_OUT</literal>
|
|
or <literal>PGRES_COPY_IN</literal> result object from <function>PQexec</function>
|
|
or <function>PQgetResult</function>.
|
|
</para>
|
|
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQgetline</function>
|
|
Reads a newline-terminated line of characters
|
|
(transmitted by the backend server) into a buffer
|
|
string of size length.
|
|
<synopsis>
|
|
int PQgetline(PGconn *conn,
|
|
char *string,
|
|
int length)
|
|
</synopsis>
|
|
Like <function>fgets</function>, this routine copies up to length-1 characters
|
|
into string. It is like <function>gets</function>, however, in that it 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>
|
|
Notice that the application must check to see if a
|
|
new line consists of the two characters <literal>\.</literal>,
|
|
which indicates that the backend server has finished sending
|
|
the results of the copy command.
|
|
If the application might
|
|
receive lines that are more than length-1 characters long,
|
|
care is needed to be sure one recognizes the <literal>\.</literal> line correctly
|
|
(and does not, for example, mistake the end of a long data line
|
|
for a terminator line).
|
|
The code in
|
|
<filename>
|
|
src/bin/psql/copy.c
|
|
</filename>
|
|
contains example routines that correctly handle the copy protocol.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQgetlineAsync</function>
|
|
Reads a newline-terminated line of characters
|
|
(transmitted by the backend server) into a buffer
|
|
without blocking.
|
|
<synopsis>
|
|
int PQgetlineAsync(PGconn *conn,
|
|
char *buffer,
|
|
int bufsize)
|
|
</synopsis>
|
|
This routine is similar to <function>PQgetline</function>, but it can be used
|
|
by applications
|
|
that must read COPY data asynchronously, that is without blocking.
|
|
Having issued the COPY 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. Unlike <function>PQgetline</function>, this routine takes
|
|
responsibility for detecting end-of-data.
|
|
On each call, <function>PQgetlineAsync</function> will return data if a complete newline-
|
|
terminated data line is available in <application>libpq</>'s input buffer, or if the
|
|
incoming data line is too long to fit in the buffer offered by the caller.
|
|
Otherwise, no data is returned until the rest of the line arrives.
|
|
</para>
|
|
<para>
|
|
The routine 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.
|
|
The data returned will not extend beyond a newline character. If possible
|
|
a whole line will be returned at one time. But if the buffer offered by
|
|
the caller is too small to hold a line sent by the backend, then a partial
|
|
data line will be returned. This can be detected by testing whether the
|
|
last returned byte is <literal>\n</literal> or not.
|
|
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>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQputline</function>
|
|
Sends a null-terminated string to the backend server.
|
|
Returns 0 if OK, <symbol>EOF</symbol> if unable to send the string.
|
|
<synopsis>
|
|
int PQputline(PGconn *conn,
|
|
const char *string);
|
|
</synopsis>
|
|
Note the application must explicitly send the two
|
|
characters <literal>\.</literal> on a final line to indicate to
|
|
the backend that it has finished sending its data.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQputnbytes</function>
|
|
Sends a non-null-terminated string to the backend server.
|
|
Returns 0 if OK, <symbol>EOF</symbol> if unable to send the string.
|
|
<synopsis>
|
|
int PQputnbytes(PGconn *conn,
|
|
const char *buffer,
|
|
int nbytes);
|
|
</synopsis>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQendcopy</function>
|
|
Synchronizes with the backend. This function waits until
|
|
the backend has finished the copy. It should
|
|
either be issued when the last string has been
|
|
sent to the backend using <function>PQputline</function> or when the
|
|
last string has been received from the backend
|
|
using <function>PGgetline</function>. It must be issued or the backend
|
|
may get <quote>out of sync</quote> with the frontend. Upon
|
|
return from this function, the backend is ready to
|
|
receive the next SQL command.
|
|
The return value is 0 on successful completion,
|
|
nonzero otherwise.
|
|
<synopsis>
|
|
int PQendcopy(PGconn *conn);
|
|
</synopsis>
|
|
</para>
|
|
|
|
<para>
|
|
As an example:
|
|
|
|
<programlisting>
|
|
PQexec(conn, "CREATE TABLE foo (a int4, b char(16), d double precision)");
|
|
PQexec(conn, "COPY foo FROM STDIN");
|
|
PQputline(conn, "3\thello world\t4.5\n");
|
|
PQputline(conn,"4\tgoodbye world\t7.11\n");
|
|
...
|
|
PQputline(conn,"\\.\n");
|
|
PQendcopy(conn);
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</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 NULL. 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 copy in or copy out command embedded in a series of <acronym>SQL</acronym> commands
|
|
will be executed correctly.
|
|
</para>
|
|
<para>
|
|
Older applications are likely to submit a copy in or copy out
|
|
via <function>PQexec</function> and assume that the transaction is done after
|
|
<function>PQendcopy</function>.
|
|
This will work correctly only if the copy in/out is the only
|
|
<acronym>SQL</acronym> command in the command string.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-trace">
|
|
<title><application>libpq</application> Tracing Functions</title>
|
|
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQtrace</function>
|
|
Enable tracing of the frontend/backend communication to a debugging file stream.
|
|
<synopsis>
|
|
void PQtrace(PGconn *conn
|
|
FILE *debug_port)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<function>PQuntrace</function>
|
|
Disable tracing started by <function>PQtrace</function>.
|
|
<synopsis>
|
|
void PQuntrace(PGconn *conn)
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-control">
|
|
<title><application>libpq</application> Control Functions</title>
|
|
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>PQsetNoticeProcessor</function>
|
|
<indexterm><primary>notice processor</></>
|
|
Control reporting of notice and warning messages generated by <application>libpq</>.
|
|
<synopsis>
|
|
typedef void (*PQnoticeProcessor) (void *arg, const char *message);
|
|
|
|
PQnoticeProcessor
|
|
PQsetNoticeProcessor(PGconn *conn,
|
|
PQnoticeProcessor proc,
|
|
void *arg);
|
|
</synopsis>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
By default, <application>libpq</application> prints notice
|
|
messages from the backend on <filename>stderr</filename>,
|
|
as well as a few error messages that it generates by itself.
|
|
This behavior can be overridden by supplying a callback function that
|
|
does something else with the messages. The callback function is passed
|
|
the text of the error message (which includes 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.)
|
|
The default notice processor is simply
|
|
<programlisting>
|
|
static void
|
|
defaultNoticeProcessor(void * arg, const char * message)
|
|
{
|
|
fprintf(stderr, "%s", message);
|
|
}
|
|
</programlisting>
|
|
To use a special notice processor, call
|
|
<function>PQsetNoticeProcessor</function> just after
|
|
creation of a new <structname>PGconn</> object.
|
|
</para>
|
|
|
|
<para>
|
|
The return value is the pointer to the previous notice processor.
|
|
If you supply a callback function pointer of NULL, no action is taken,
|
|
but the current pointer is returned.
|
|
</para>
|
|
|
|
<para>
|
|
Once you have set a notice 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 processor pointer is copied into the <structname>PGresult</> for possible use by
|
|
routines like <function>PQgetvalue</function>.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-envars">
|
|
<title>Environment Variables</title>
|
|
|
|
<indexterm zone="libpq-envars">
|
|
<primary>environment variables</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
The following environment variables can be used to select default
|
|
connection parameter values, which will be used by <function>PQconnectdb</function> or
|
|
<function>PQsetdbLogin</function> if no value is directly specified by the calling code.
|
|
These are useful to avoid hard-coding database names into simple
|
|
application programs.
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGHOST</envar></primary>
|
|
</indexterm>
|
|
<envar>PGHOST</envar> sets the default server 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 (default <filename>/tmp</filename>).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGPORT</envar></primary>
|
|
</indexterm>
|
|
<envar>PGPORT</envar> sets the default TCP port number or Unix-domain
|
|
socket file extension for communicating with the
|
|
<productname>PostgreSQL</productname> backend.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGDATABASE</envar></primary>
|
|
</indexterm>
|
|
<envar>PGDATABASE</envar> sets the default
|
|
<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 and for authentication.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<indexterm>
|
|
<primary><envar>PGPASSWORD</envar></primary>
|
|
</indexterm>
|
|
<envar>PGPASSWORD</envar>
|
|
sets the password used if the backend demands password
|
|
authentication. This functionality is deprecated for security
|
|
reasons; consider migrating to use the <link linkend='pgpassfile'>
|
|
<filename>$HOME/.pgpass</></link>
|
|
file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<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, <productname>PostgreSQL</productname>
|
|
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 backend.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGOPTIONS</envar> sets additional run-time options for
|
|
the <productname>PostgreSQL</productname> backend.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGTTY</envar> sets the file or tty on which debugging
|
|
messages from the backend server are displayed.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
The following environment variables can be used to specify user-level default
|
|
behavior for every <productname>PostgreSQL</productname> session:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGDATESTYLE</envar>
|
|
sets the default style of date/time representation.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGTZ</envar>
|
|
sets the default time zone.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGCLIENTENCODING</envar>
|
|
sets the default client encoding (if multibyte support was selected
|
|
when configuring <productname>PostgreSQL</productname>).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
The following environment variables can be used to specify default internal
|
|
behavior for every <productname>PostgreSQL</productname> session:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<envar>PGGEQO</envar>
|
|
sets the default mode for the genetic optimizer.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Refer to the <command>SET</command> <acronym>SQL</acronym> command
|
|
for information on correct values for these environment variables.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="libpq-files">
|
|
<title>Files</title>
|
|
|
|
<indexterm zone="libpq-files">
|
|
<primary>files</primary>
|
|
</indexterm>
|
|
<para>
|
|
<anchor id="pgpassfile">
|
|
<indexterm>
|
|
<primary>password</primary>
|
|
<secondary>.pgpass</secondary>
|
|
</indexterm>
|
|
The <filename>.pgpass</filename> file in a user's home directory is a
|
|
file that can contain passwords to be used if the connection requires
|
|
a password. This file should have the format:
|
|
<synopsis>
|
|
<replaceable>hostname</replaceable>:<replaceable>port</replaceable>:<replaceable>database</replaceable>:<replaceable>username</replaceable>:<replaceable>password</replaceable>
|
|
</synopsis>
|
|
Any of these may be a literal name, or <literal>*</literal>, which matches
|
|
anything. The first match will be used so put more specific entries first.
|
|
Entries with <literal>:</literal> or <literal>\</literal> should be escaped
|
|
with <literal>\</literal>.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="libpq-threading">
|
|
<title>Threading Behavior</title>
|
|
|
|
<indexterm zone="libpq-threading">
|
|
<primary>threads</primary>
|
|
<secondary>with libpq</secondary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
<filename>libpq</filename> is thread-safe as of
|
|
<productname>PostgreSQL</productname> 7.0, so long as no two threads
|
|
attempt to manipulate the same <structname>PGconn</> object at the same
|
|
time. In particular, you cannot issue concurrent queries from different
|
|
threads through the same connection object. (If you need to run
|
|
concurrent queries, start up 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>PQoidStatus</function> and
|
|
<function>fe_setauthsvc</function> are not thread-safe and should not be
|
|
used in multithread programs. <function>PQoidStatus</function> can be
|
|
replaced by <function>PQoidValue</function>. There is no good reason to
|
|
call <function>fe_setauthsvc</function> at all.
|
|
</para>
|
|
|
|
<para>
|
|
<filename>Libpq</filename> clients using the <literal>crypt</literal>
|
|
encryption method rely on the <literal>crypt()</literal> operating
|
|
system function, which is often not thread-safe. It is better to use
|
|
<literal>MD5</literal> encryption, which is thread-safe on all
|
|
platforms.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="libpq-build">
|
|
<title>Building <application>Libpq</application> Programs</title>
|
|
|
|
<para>
|
|
To build (i.e., compile and link) your <application>libpq</application> programs 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>
|
|
<indexterm><primary>pg_config</></>
|
|
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> 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 it 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> or did not specify
|
|
the right path.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
<indexterm><primary>libpq-int.h</></>
|
|
If your codes references the header file
|
|
<filename>libpq-int.h</filename> and you refuse to fix your code to
|
|
not use it, starting in <productname>PostgreSQL</> 7.2, this file will be found in
|
|
<filename><replaceable>includedir</replaceable>/postgresql/internal/libpq-int.h</filename>,
|
|
so you need to add the appropriate <option>-I</option> option to
|
|
your compiler command line.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="libpq-example">
|
|
<title>Example Programs</title>
|
|
|
|
<example id="libpq-example-1">
|
|
<title><application>libpq</application> Example Program 1</title>
|
|
|
|
<programlisting>
|
|
/*
|
|
* testlibpq.c
|
|
*
|
|
* Test the C version of libpq, the <productname>PostgreSQL</> frontend
|
|
* library.
|
|
*/
|
|
#include <stdio.h>
|
|
#include <libpq-fe.h>
|
|
|
|
void
|
|
exit_nicely(PGconn *conn)
|
|
{
|
|
PQfinish(conn);
|
|
exit(1);
|
|
}
|
|
|
|
main()
|
|
{
|
|
char *pghost,
|
|
*pgport,
|
|
*pgoptions,
|
|
*pgtty;
|
|
char *dbName;
|
|
int nFields;
|
|
int i,
|
|
j;
|
|
|
|
/* FILE *debug; */
|
|
|
|
PGconn *conn;
|
|
PGresult *res;
|
|
|
|
/*
|
|
* begin, by setting the parameters for a backend connection if the
|
|
* parameters are null, then the system will try to use reasonable
|
|
* defaults by looking up environment variables or, failing that,
|
|
* using hardwired constants
|
|
*/
|
|
pghost = NULL; /* host name of the backend server */
|
|
pgport = NULL; /* port of the backend server */
|
|
pgoptions = NULL; /* special options to start up the backend
|
|
* server */
|
|
pgtty = NULL; /* debugging tty for the backend server */
|
|
dbName = "template1";
|
|
|
|
/* make a connection to the database */
|
|
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
|
|
|
|
/*
|
|
* check to see that the backend connection was successfully made
|
|
*/
|
|
if (PQstatus(conn) == CONNECTION_BAD)
|
|
{
|
|
fprintf(stderr, "Connection to database '%s' failed.\n", dbName);
|
|
fprintf(stderr, "%s", PQerrorMessage(conn));
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/* debug = fopen("/tmp/trace.out","w"); */
|
|
/* PQtrace(conn, debug); */
|
|
|
|
/* start a transaction block */
|
|
res = PQexec(conn, "BEGIN");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "BEGIN command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/*
|
|
* should PQclear PGresult whenever it is no longer needed to avoid
|
|
* memory leaks
|
|
*/
|
|
PQclear(res);
|
|
|
|
/*
|
|
* fetch rows from the pg_database, the system catalog of
|
|
* databases
|
|
*/
|
|
res = PQexec(conn, "DECLARE mycursor CURSOR FOR SELECT * FROM pg_database");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "DECLARE CURSOR command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
PQclear(res);
|
|
res = PQexec(conn, "FETCH ALL in mycursor");
|
|
if (!res || PQresultStatus(res) != PGRES_TUPLES_OK)
|
|
{
|
|
fprintf(stderr, "FETCH ALL command didn't return tuples properly\n");
|
|
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 cursor */
|
|
res = PQexec(conn, "CLOSE mycursor");
|
|
PQclear(res);
|
|
|
|
/* commit the transaction */
|
|
res = PQexec(conn, "COMMIT");
|
|
PQclear(res);
|
|
|
|
/* close the connection to the database and cleanup */
|
|
PQfinish(conn);
|
|
|
|
/* fclose(debug); */
|
|
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;
|
|
*
|
|
* Or, if you want to get fancy, try this:
|
|
* Populate a database with the following:
|
|
*
|
|
* 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
|
|
*
|
|
* INSERT INTO TBL1 values (10);
|
|
*
|
|
*/
|
|
#include <stdio.h>
|
|
#include "libpq-fe.h"
|
|
|
|
void
|
|
exit_nicely(PGconn *conn)
|
|
{
|
|
PQfinish(conn);
|
|
exit(1);
|
|
}
|
|
|
|
main()
|
|
{
|
|
char *pghost,
|
|
*pgport,
|
|
*pgoptions,
|
|
*pgtty;
|
|
char *dbName;
|
|
int nFields;
|
|
int i,
|
|
j;
|
|
|
|
PGconn *conn;
|
|
PGresult *res;
|
|
PGnotify *notify;
|
|
|
|
/*
|
|
* begin, by setting the parameters for a backend connection if the
|
|
* parameters are null, then the system will try to use reasonable
|
|
* defaults by looking up environment variables or, failing that,
|
|
* using hardwired constants
|
|
*/
|
|
pghost = NULL; /* host name of the backend server */
|
|
pgport = NULL; /* port of the backend server */
|
|
pgoptions = NULL; /* special options to start up the backend
|
|
* server */
|
|
pgtty = NULL; /* debugging tty for the backend server */
|
|
dbName = getenv("USER"); /* change this to the name of your test
|
|
* database */
|
|
|
|
/* make a connection to the database */
|
|
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
|
|
|
|
/*
|
|
* check to see that the backend connection was successfully made
|
|
*/
|
|
if (PQstatus(conn) == CONNECTION_BAD)
|
|
{
|
|
fprintf(stderr, "Connection to database '%s' failed.\n", dbName);
|
|
fprintf(stderr, "%s", PQerrorMessage(conn));
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
res = PQexec(conn, "LISTEN TBL2");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "LISTEN command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/*
|
|
* should PQclear PGresult whenever it is no longer needed to avoid
|
|
* memory leaks
|
|
*/
|
|
PQclear(res);
|
|
|
|
while (1)
|
|
{
|
|
|
|
/*
|
|
* wait a little bit between checks; waiting with select()
|
|
* would be more efficient.
|
|
*/
|
|
sleep(1);
|
|
/* collect any asynchronous backend messages */
|
|
PQconsumeInput(conn);
|
|
/* check for asynchronous notify messages */
|
|
while ((notify = PQnotifies(conn)) != NULL)
|
|
{
|
|
fprintf(stderr,
|
|
"ASYNC NOTIFY of '%s' from backend pid '%d' received\n",
|
|
notify->relname, notify->be_pid);
|
|
free(notify);
|
|
}
|
|
}
|
|
|
|
/* 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 the C version of Libpq, the <productname>PostgreSQL</> frontend
|
|
* library. tests the binary cursor interface
|
|
*
|
|
*
|
|
*
|
|
* populate a database by doing the following:
|
|
*
|
|
* CREATE TABLE test1 (i int4, d real, p polygon);
|
|
*
|
|
* INSERT INTO test1 values (1, 3.567, polygon '(3.0, 4.0, 1.0, 2.0)');
|
|
*
|
|
* INSERT INTO test1 values (2, 89.05, polygon '(4.0, 3.0, 2.0, 1.0)');
|
|
*
|
|
* the expected output is:
|
|
*
|
|
* tuple 0: got i = (4 bytes) 1, d = (4 bytes) 3.567000, p = (4
|
|
* bytes) 2 points boundbox = (hi=3.000000/4.000000, lo =
|
|
* 1.000000,2.000000) tuple 1: got i = (4 bytes) 2, d = (4 bytes)
|
|
* 89.050003, p = (4 bytes) 2 points boundbox =
|
|
* (hi=4.000000/3.000000, lo = 2.000000,1.000000)
|
|
*
|
|
*
|
|
*/
|
|
#include <stdio.h>
|
|
#include "libpq-fe.h"
|
|
#include "utils/geo_decls.h" /* for the POLYGON type */
|
|
|
|
void
|
|
exit_nicely(PGconn *conn)
|
|
{
|
|
PQfinish(conn);
|
|
exit(1);
|
|
}
|
|
|
|
main()
|
|
{
|
|
char *pghost,
|
|
*pgport,
|
|
*pgoptions,
|
|
*pgtty;
|
|
char *dbName;
|
|
int nFields;
|
|
int i,
|
|
j;
|
|
int i_fnum,
|
|
d_fnum,
|
|
p_fnum;
|
|
PGconn *conn;
|
|
PGresult *res;
|
|
|
|
/*
|
|
* begin, by setting the parameters for a backend connection if the
|
|
* parameters are null, then the system will try to use reasonable
|
|
* defaults by looking up environment variables or, failing that,
|
|
* using hardwired constants
|
|
*/
|
|
pghost = NULL; /* host name of the backend server */
|
|
pgport = NULL; /* port of the backend server */
|
|
pgoptions = NULL; /* special options to start up the backend
|
|
* server */
|
|
pgtty = NULL; /* debugging tty for the backend server */
|
|
|
|
dbName = getenv("USER"); /* change this to the name of your test
|
|
* database */
|
|
|
|
/* make a connection to the database */
|
|
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
|
|
|
|
/*
|
|
* check to see that the backend connection was successfully made
|
|
*/
|
|
if (PQstatus(conn) == CONNECTION_BAD)
|
|
{
|
|
fprintf(stderr, "Connection to database '%s' failed.\n", dbName);
|
|
fprintf(stderr, "%s", PQerrorMessage(conn));
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/* start a transaction block */
|
|
res = PQexec(conn, "BEGIN");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "BEGIN command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
/*
|
|
* should PQclear PGresult whenever it is no longer needed to avoid
|
|
* memory leaks
|
|
*/
|
|
PQclear(res);
|
|
|
|
/*
|
|
* fetch rows from the pg_database, the system catalog of
|
|
* databases
|
|
*/
|
|
res = PQexec(conn, "DECLARE mycursor BINARY CURSOR FOR SELECT * FROM test1");
|
|
if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
|
|
{
|
|
fprintf(stderr, "DECLARE CURSOR command failed\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
PQclear(res);
|
|
|
|
res = PQexec(conn, "FETCH ALL in mycursor");
|
|
if (!res || PQresultStatus(res) != PGRES_TUPLES_OK)
|
|
{
|
|
fprintf(stderr, "FETCH ALL command didn't return tuples properly\n");
|
|
PQclear(res);
|
|
exit_nicely(conn);
|
|
}
|
|
|
|
i_fnum = PQfnumber(res, "i");
|
|
d_fnum = PQfnumber(res, "d");
|
|
p_fnum = PQfnumber(res, "p");
|
|
|
|
for (i = 0; i < 3; i++)
|
|
{
|
|
printf("type[%d] = %d, size[%d] = %d\n",
|
|
i, PQftype(res, i),
|
|
i, PQfsize(res, i));
|
|
}
|
|
for (i = 0; i < PQntuples(res); i++)
|
|
{
|
|
int *ival;
|
|
float *dval;
|
|
int plen;
|
|
POLYGON *pval;
|
|
|
|
/* we hard-wire this to the 3 fields we know about */
|
|
ival = (int *) PQgetvalue(res, i, i_fnum);
|
|
dval = (float *) PQgetvalue(res, i, d_fnum);
|
|
plen = PQgetlength(res, i, p_fnum);
|
|
|
|
/*
|
|
* plen doesn't include the length field so need to
|
|
* increment by VARHDSZ
|
|
*/
|
|
pval = (POLYGON *) malloc(plen + VARHDRSZ);
|
|
pval->size = plen;
|
|
memmove((char *) &pval->npts, PQgetvalue(res, i, p_fnum), plen);
|
|
printf("tuple %d: got\n", i);
|
|
printf(" i = (%d bytes) %d,\n",
|
|
PQgetlength(res, i, i_fnum), *ival);
|
|
printf(" d = (%d bytes) %f,\n",
|
|
PQgetlength(res, i, d_fnum), *dval);
|
|
printf(" p = (%d bytes) %d points \tboundbox = (hi=%f/%f, lo = %f,%f)\n",
|
|
PQgetlength(res, i, d_fnum),
|
|
pval->npts,
|
|
pval->boundbox.xh,
|
|
pval->boundbox.yh,
|
|
pval->boundbox.xl,
|
|
pval->boundbox.yl);
|
|
}
|
|
PQclear(res);
|
|
|
|
/* close the cursor */
|
|
res = PQexec(conn, "CLOSE mycursor");
|
|
PQclear(res);
|
|
|
|
/* commit the transaction */
|
|
res = PQexec(conn, "COMMIT");
|
|
PQclear(res);
|
|
|
|
/* close the connection to the database and cleanup */
|
|
PQfinish(conn);
|
|
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode:sgml
|
|
sgml-omittag:nil
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"./reference.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|