Skip to content

P
Postgres FD Implementation
Commit 16c6545d authored by Tom Lane's avatar Tom Lane
Browse files
Options

Many updates...

parent 445ce695
Hide whitespace changes
Inline Side-by-side
Showing with 561 additions and 246 deletions
doc/src/sgml/libpq.sgml
View file @ 16c6545d
......@@ -2,15 +2,22 @@
<Title><FileName>libpq</FileName></Title>
<Para>
<FileName>libpq</FileName> is the application programming interface to <ProductName>Postgres</ProductName>.
<FileName>libpq</FileName> is a set of library routines which allows
client programs to pass queries to the <ProductName>Postgres</ProductName> backend
server and to receive the results of these queries.
This version of the documentation describes the <Acronym>C</Acronym>
interface library. 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 examples of <FileName>libpq</FileName> applications in the
following directories:
<FileName>libpq</FileName> is the C application programmer's interface to
<ProductName>Postgres</ProductName>. <FileName>libpq</FileName> is a set
of library routines that allow client programs to pass queries to the
<ProductName>Postgres</ProductName> backend server and to receive the
results of these queries. <FileName>libpq</FileName> is also the
underlying engine for several other <ProductName>Postgres</ProductName>
application interfaces, including <FileName>libpq++</FileName> (C++),
<FileName>libpgtcl</FileName> (Tcl), <FileName>perl5</FileName>, and
<FileName>ecpg</FileName>. So some aspects of libpq's behavior will be
important to you if you use one of those packages.
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:
<ProgramListing>
../src/test/regress
......@@ -19,170 +26,135 @@
</ProgramListing>
<Para>
Frontend programs which use <FileName>libpq</FileName> must include the
header file <FileName>libpq-fe.h</FileName> and must link with the <FileName>libpq</FileName>
library.
Frontend programs which 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>
<Title>Control and Initialization</Title>
<Title>Database Connection Functions</Title>
<Para>
The following environment variables can be used to set
up default environment values to avoid hard-coding
database names into an application program:
The following routines deal with making a connection to
a <ProductName>Postgres</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 PGconn object which is obtained
from PQconnectdb() or PQsetdbLogin(). NOTE that these functions
will always return a non-null object pointer, unless perhaps
there is too little memory even to allocate the PGconn object.
The PQstatus function should be called
to check whether a connection was successfully made
before queries are sent via the connection object.
<ItemizedList>
<ListItem>
<Para>
<Acronym>PGHOST</Acronym> sets the default server name.
If it is set to a non-zero-length string, it causes TCP/IP
communication to be used, rather than the default local Unix domain sockets.
<Function>PQsetdbLogin</Function>
Makes a new connection to a backend.
<ProgramListing>
PGconn *PQsetdbLogin(const char *pghost,
const char *pgport,
const char *pgoptions,
const char *pgtty,
const char *dbName,
const char *login,
const char *pwd)
</ProgramListing>
If any argument is NULL, then the corresponding
environment variable (see "Environment Variables" section)
is checked. If the environment variable
is also not set, then hardwired defaults are used.
The return value is a pointer to an abstract struct
representing the connection to the backend.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGOPTIONS</Acronym> sets additional runtime options for the <ProductName>Postgres</ProductName> backend.
<Function>PQsetdb</Function>
Makes a new connection to a backend.
<ProgramListing>
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName)
</ProgramListing>
This is a macro that calls PQsetdbLogin() with null pointers
for the login and pwd parameters. It is provided primarily
for backward compatibility with old programs.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGPORT</Acronym> sets the default port or local Unix domain socket
file extension for communicating with the <ProductName>Postgres</ProductName>
backend.
</Para>
</ListItem>
<Function>PQconnectdb</Function>
Makes a new connection to a backend.
<ProgramListing>
PGconn *PQconnectdb(const char *conninfo)
</ProgramListing>
This routine opens a new database connection using parameters
taken from a string. Unlike PQsetdbLogin(), the parameter set
can be extended without changing the function signature, so use
of this routine is encouraged for new 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. Each parameter setting is in the form
keyword = value. (To write a null value or a value containing
spaces, surround it with single quotes, eg, keyword = 'a value'.
Single quotes within the value must be written as \'. Spaces
around the equal sign are optional.) The currently recognized
parameter keywords are:
<ItemizedList>
<ListItem>
<Para>
<Acronym>PGTTY</Acronym> sets the file or tty on which debugging messages from the backend server are displayed.
<Acronym>host</Acronym> -- host to connect to.
If a non-zero-length string is specified, TCP/IP communication is used.
Without a host name, libpq will connect using a local Unix domain socket.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGDATABASE</Acronym> sets the default <ProductName>Postgres</ProductName> database name.
<Acronym>port</Acronym> -- port number to connect to at the server host,
or socket filename extension for Unix-domain connections.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGREALM</Acronym> sets the Kerberos realm to use with <ProductName>Postgres</ProductName>,
if it is different from the local realm. If
<Acronym>PGREALM</Acronym> is set, <ProductName>Postgres</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 enabled.
<Acronym>dbname</Acronym> -- database name.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
The following environment variables can be used to specify user-level default
behavior for every Postgres session:
<ItemizedList>
<ListItem>
<Para>
<Acronym>PGDATESTYLE</Acronym>
sets the default style of date/time representation.
<Acronym>user</Acronym> -- user name for authentication.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGTZ</Acronym>
sets the default time zone.
<Acronym>password</Acronym> --
password used if the backend demands password authentication.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
The following environment variables can be used to specify default internal
behavior for every Postgres session:
<ItemizedList>
<ListItem>
<Para>
<Acronym>PGGEQO</Acronym>
sets the default mode for the genetic optimizer.
<Acronym>authtype</Acronym> -- authorization type. (No longer used,
since the backend now chooses how to authenticate users. libpq still
accepts and ignores this keyword for backward compatibility.)
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGRPLANS</Acronym>
sets the default mode to allow or disable right-sided plans in the optimizer.
<Acronym>options</Acronym> -- trace/debug options to send to backend.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGCOSTHEAP</Acronym>
sets the default cost for heap searches for the optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGCOSTINDEX</Acronym>
sets the default cost for indexed searches for the optimizer.
<Acronym>tty</Acronym> -- file or tty for optional debug output.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
Refer to the <command>SET</command> <acronym>SQL</acronym> command
for information on the arguments for these environment variables.
</Sect1>
<Sect1>
<Title>Database Connection Functions</Title>
<Para>
The following routines deal with making a connection to
a backend from a <Acronym>C</Acronym> program.
<ItemizedList>
<ListItem>
<Para>
<Function>PQsetdbLogin</Function>
Makes a new connection to a backend.
<ProgramListing>
PGconn *PQsetdbLogin(const char *pghost,
const char *pgport,
const char *pgoptions,
const char *pgtty,
const char *dbName,
const char *login,
const char *pwd);
</ProgramListing>
If any argument is NULL, then the corresponding
environment variable is checked. If the environment variable is also not set, then hardwired
defaults are used.
PQsetdbLogin always returns a valid PGconn pointer.
The PQstatus (see below) command should be called
to ensure that a connection was properly made
before queries are sent via the connection. <FileName>libpq</FileName>
programmers should be careful to maintain the
PGconn abstraction. Use the accessor functions
below to get at the contents of PGconn. Avoid
directly referencing the fields of the PGconn
structure as they are subject to change in the
future.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQsetdb</Function>
Makes a new connection to a backend.
<ProgramListing>
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName);
</ProgramListing>
This is a macro that calls PQsetdbLogin() with null pointers
for the login and pwd parameters.
Like PQsetdbLogin, PQconnectdb uses environment variables or built-in
default values for unspecified options.
</Para>
</ListItem>
......@@ -196,7 +168,7 @@ PQconninfoOption *PQconndefaults(void)
struct PQconninfoOption
{
char *keyword; /* The keyword of the option */
char *environ; /* Fallback environment variable name */
char *envvar; /* Fallback environment variable name */
char *compiled; /* Fallback compiled in default value */
char *val; /* Options value */
char *label; /* Label for field in connect dialog */
......@@ -211,10 +183,59 @@ struct PQconninfoOption
</ProgramListing>
Returns the address of the connection options structure. This may
be used to determine all possible options and their current values.
be used to determine all possible PQconnectdb options and their
current default values. The return value points to an array of
PQconninfoOption structs, which ends with an entry having a NULL
keyword pointer. Note that the default values ("val" fields)
will depend on environment variables and other context.
Callers must treat the connection options data as read-only.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQfinish</Function>
Close the connection to the backend. Also frees
memory used by the PGconn object.
<ProgramListing>
void PQfinish(PGconn *conn)
</ProgramListing>
Note that even if the backend connection attempt fails (as
indicated by PQstatus), the application should call PQfinish
to free the memory used by the PGconn object.
The PGconn pointer should not be used after PQfinish has been called.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQreset</Function>
Reset the communication port with the backend.
<ProgramListing>
void PQreset(PGconn *conn)
</ProgramListing>
This function will close the connection
to the backend and attempt to reestablish a new
connection to the same postmaster, using all the same
parameters previously used. This may be useful for
error recovery if a working connection is lost.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
<FileName>libpq</FileName> application programmers should be careful to
maintain the PGconn abstraction. Use the accessor functions below to get
at the contents of PGconn. Avoid directly referencing the fields of the
PGconn structure because they are subject to change in the future.
(Beginning in <ProductName>Postgres</ProductName> release 6.4, the
definition of struct PGconn is not even provided in libpq-fe.h. If you
have old code that accesses PGconn fields directly, you can keep using it
by including libpq-int.h too, but you are encouraged to fix the code
soon.)
<ItemizedList>
<ListItem>
<Para>
<Function>PQdb</Function>
......@@ -222,25 +243,38 @@ struct PQconninfoOption
<ProgramListing>
char *PQdb(PGconn *conn)
</ProgramListing>
PQdb and the next several functions return the values established
at connection. These values are fixed for the life of the PGconn
object.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQhost</Function>
Returns the host name of the connection.
<Function>PQuser</Function>
Returns the user name of the connection.
<ProgramListing>
char *PQhost(PGconn *conn)
char *PQuser(PGconn *conn)
</ProgramListing>
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQoptions</Function>
Returns the pgoptions used in the connection.
<Function>PQpass</Function>
Returns the password of the connection.
<ProgramListing>
char *PQoptions(PGconn *conn)
char *PQpass(PGconn *conn)
</ProgramListing>
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQhost</Function>
Returns the server host name of the connection.
<ProgramListing>
char *PQhost(PGconn *conn)
</ProgramListing>
</Para>
</ListItem>
......@@ -248,7 +282,7 @@ char *PQoptions(PGconn *conn)
<ListItem>
<Para>
<Function>PQport</Function>
Returns the pgport of the connection.
Returns the port of the connection.
<ProgramListing>
char *PQport(PGconn *conn)
</ProgramListing>
......@@ -258,7 +292,7 @@ char *PQport(PGconn *conn)
<ListItem>
<Para>
<Function>PQtty</Function>
Returns the pgtty of the connection.
Returns the debug tty of the connection.
<ProgramListing>
char *PQtty(PGconn *conn)
</ProgramListing>
......@@ -267,50 +301,59 @@ char *PQtty(PGconn *conn)
<ListItem>
<Para>
<Function>PQstatus</Function>
Returns the status of the connection.
The status can be CONNECTION_OK or CONNECTION_BAD.
<Function>PQoptions</Function>
Returns the backend options used in the connection.
<ProgramListing>
ConnStatusType *PQstatus(PGconn *conn)
char *PQoptions(PGconn *conn)
</ProgramListing>
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQerrorMessage</Function>
Returns the error message associated with the connection
<Function>PQstatus</Function>
Returns the status of the connection.
The status can be CONNECTION_OK or CONNECTION_BAD.
<ProgramListing>
char *PQerrorMessage(PGconn* conn);
ConnStatusType *PQstatus(PGconn *conn)
</ProgramListing>
</Para>
A failed connection attempt is signaled by status CONNECTION_BAD.
Ordinarily, an OK status will remain so until PQfinish, but a
communications failure might result in the status changing to
CONNECTION_BAD prematurely. In that case the application could
try to recover by calling PQreset.
</ListItem>
<ListItem>
<Para>
<Function>PQfinish</Function>
Close the connection to the backend. Also frees
memory used by the PGconn structure. The PGconn
pointer should not be used after PQfinish has been
called.
<Function>PQerrorMessage</Function>
Returns the error message most recently generated by
an operation on the connection.
<ProgramListing>
void PQfinish(PGconn *conn)
char *PQerrorMessage(PGconn* conn);
</ProgramListing>
</Para>
Nearly all libpq functions will set PQerrorMessage if they fail.
Note that by libpq convention, a non-empty PQerrorMessage will
include a trailing newline.
</ListItem>
<ListItem>
<Para>
<Function>PQreset</Function>
Reset the communication port with the backend.
This function will close the IPC socket connection
to the backend and attempt to reestablish a new
connection to the same postmaster.
<Function>PQbackendPID</Function>
Returns the process ID of the backend server handling this
connection.
<ProgramListing>
void PQreset(PGconn *conn)
int PQbackendPID(PGconn *conn);
</ProgramListing>
The backend PID is useful for debugging purposes and for comparison
to NOTIFY messages (which include the PID of the notifying backend).
Note that the PID belongs to a process executing on the database
server host, not the local host!
</Para>
</ListItem>
</ItemizedList>
</Para>
</Sect1>
......@@ -319,29 +362,45 @@ void PQreset(PGconn *conn)
<Title>Query 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.
<ItemizedList>
<ListItem>
<Para>
<Function>PQexec</Function>
Submit a query to <ProductName>Postgres</ProductName>. Returns a PGresult
pointer or possibly a NULL pointer. If a NULL is returned, it
should be treated like a PGRES_FATAL_ERROR result: use
PQerrorMessage to get more information about the error.
Submit a query to <ProductName>Postgres</ProductName>
and wait for the result.
<ProgramListing>
PGresult *PQexec(PGconn *conn,
const char *query);
</ProgramListing>
The <Function>PGresult</Function> structure encapsulates the query
result returned by the backend. <Function>libpq</Function> programmers
should be careful to maintain the PGresult
abstraction. Use the accessor functions described
below to retrieve the results of the query. Avoid
directly referencing the fields of the PGresult
structure as they are subject to change in the
future.
Returns a PGresult 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 query to the backend.
If a NULL is returned, it
should be treated like a PGRES_FATAL_ERROR result. Use
PQerrorMessage to get more information about the error.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
The <Function>PGresult</Function> structure encapsulates the query result
returned by the backend.
<FileName>libpq</FileName> application programmers should be careful to
maintain the PGresult abstraction. Use the accessor functions below to get
at the contents of PGresult. Avoid directly referencing the fields of the
PGresult structure because they are subject to change in the future.
(Beginning in <ProductName>Postgres</ProductName> release 6.4, the
definition of struct PGresult is not even provided in libpq-fe.h. If you
have old code that accesses PGresult fields directly, you can keep using it
by including libpq-int.h too, but you are encouraged to fix the code
soon.)
<ItemizedList>
<ListItem>
<Para>
<Function>PQresultStatus</Function>
......@@ -350,21 +409,42 @@ PGresult *PQexec(PGconn *conn,
PGRES_EMPTY_QUERY,
PGRES_COMMAND_OK, /* the query was a command returning no data */
PGRES_TUPLES_OK, /* the query successfully returned tuples */
PGRES_COPY_OUT,
PGRES_COPY_IN,
PGRES_COPY_OUT, /* Copy Out (from server) data transfer started */
PGRES_COPY_IN, /* Copy In (to server) data transfer started */
PGRES_BAD_RESPONSE, /* an unexpected response was received */
PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR
</ProgramListing>
If the result status is PGRES_TUPLES_OK, then the
following routines can be used to retrieve the
tuples returned by the query.
routines described below can be used to retrieve the
tuples returned by the query. Note that a SELECT that
happens to retrieve zero tuples still shows PGRES_TUPLES_OK;
PGRES_COMMAND_OK is for commands that can never return tuples.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQresultErrorMessage</Function>
returns the error message associated with the query, or an empty string
if there was no error.
<ProgramListing>
const char *PQresultErrorMessage(PGresult *res);
</ProgramListing>
Immediately following a PQexec or PQgetResult call, PQerrorMessage
(on the connection) will return the same string as PQresultErrorMessage
(on the result). However, a PGresult will retain its error message
until destroyed, whereas the connection's error message will change when
subsequent operations are done. Use PQresultErrorMessage when you want to
know the status associated with a particular PGresult; use PQerrorMessage
when you want to know the status from the latest operation on the connection.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQntuples</Function> returns the number of tuples (instances)
<Function>PQntuples</Function>
Returns the number of tuples (instances)
in the query result.
<ProgramListing>
int PQntuples(PGresult *res);
......@@ -376,13 +456,26 @@ int PQntuples(PGresult *res);
<Para>
<Function>PQnfields</Function>
Returns the number of fields
(attributes) in the query result.
(attributes) in each tuple of the query result.
<ProgramListing>
int PQnfields(PGresult *res);
</ProgramListing>
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQbinaryTuples</Function>
Returns 1 if the PGresult contains binary tuple data,
0 if it contains ASCII data.
<ProgramListing>
int PQbinaryTuples(PGresult *res);
</ProgramListing>
Currently, binary tuple data can only be returned by a query that
extracts data from a <Acronym>BINARY</Acronym> cursor.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQfname</Function>
......@@ -405,6 +498,7 @@ int PQfnumber(PGresult *res,
char* field_name);
</ProgramListing>
</Para>
-1 is returned if the given name does not match any field.
</ListItem>
<ListItem>
......@@ -424,13 +518,13 @@ Oid PQftype(PGresult *res,
<ListItem>
<Para>
<Function>PQfsize</Function>
Returns the size in bytes of the field
Returns the size in bytes of the field
associated with the given field index. If the size
returned is -1, the field is a variable length
field. Field indices start at 0.
<ProgramListing>
short PQfsize(PGresult *res,
int field_index);
int PQfsize(PGresult *res,
int field_index);
</ProgramListing>
</Para>
</ListItem>
......@@ -451,24 +545,27 @@ int PQfmod(PGresult *res,
<ListItem>
<Para>
<Function>PQgetvalue</Function>
Returns the field (attribute) value.
Returns a single field (attribute) value of one tuple
of a PGresult.
Tuple and field indices start at 0.
<ProgramListing>
char* PQgetvalue(PGresult *res,
int tup_num,
int field_num);
</ProgramListing>
For most queries, the value returned by PQgetvalue
is a null-terminated ASCII string representation
of the attribute value. If the query was a result
of a <Acronym>BINARY</Acronym> cursor, then the value returned by
of the attribute value. If the query extracted data from
a <Acronym>BINARY</Acronym> cursor, then the value returned by
PQgetvalue is the binary representation of the
type in the internal format of the backend server.
It is the programmer's responsibility to cast and
convert the data to the correct C type. The value
convert the data to the correct C type. The pointer
returned by PQgetvalue points to storage that is
part of the PGresult structure. One must explicitly
part of the PGresult 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 PGresult structure itself.
<ProgramListing>
char* PQgetvalue(PGresult *res,
int tup_num,
int field_num);
</ProgramListing>
</Para>
</ListItem>
......@@ -476,37 +573,45 @@ char* PQgetvalue(PGresult *res,
<Para>
<Function>PQgetisnull</Function>
Tests a field for a NULL entry.
Tuple and field indices start at 0.
<ProgramListing>
int PQgetisnull(PGresult *res,
int tup_num,
int field_num);
</ProgramListing>
This function returns 1 if the field contains a NULL, 0 if
it contains a known value.
it contains a non-null value. (Note that PQgetvalue
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) in bytes. If the field is a struct
varlena, the length returned here does not include
the size field of the varlena, i.e., it is 4 bytes
less.
Returns the length of a field
(attribute) in bytes.
Tuple and field indices start at 0.
<ProgramListing>
int PQgetlength(PGresult *res,
int tup_num,
int field_num);
</ProgramListing>
This is the actual data length for the particular data value,
whereas PQfsize shows the allocated space for all entries in
this column.
If the field is a struct
varlena, the length returned here does not include
the size field of the varlena, i.e., it is 4 bytes
less.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQcmdStatus</Function>
Returns the command status associated with the
last query command.
Returns the command status string from the SQL command that
generated the PGresult.
<ProgramListing>
char *PQcmdStatus(PGresult *res);
</ProgramListing>
......@@ -516,12 +621,13 @@ char *PQcmdStatus(PGresult *res);
<ListItem>
<Para>
<Function>PQcmdTuples</Function>
Returns the number of rows affected by the last command.
Returns the number of rows affected by the SQL command.
<ProgramListing>
const char *PQcmdTuples(PGresult *res);
</ProgramListing>
If the last command was INSERT, UPDATE or DELETE, this returns
a string containing the number of rows affected. If the last
If the SQL command that generated the
PGresult 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>
......@@ -530,7 +636,7 @@ const char *PQcmdTuples(PGresult *res);
<Para>
<Function>PQoidStatus</Function>
Returns a string with the object id of the tuple
inserted if the last query is an INSERT command.
inserted, if the SQL command was an INSERT.
Otherwise, returns an empty string.
<ProgramListing>
char* PQoidStatus(PGresult *res);
......@@ -562,8 +668,9 @@ struct _PQprintOpt
char **fieldName; /* null terminated array of replacement field names */
};
</ProgramListing>
This funtion is intended to replace PQprintTuples(), which is
now obsolete.
This function is intended to replace PQprintTuples(), which is
now obsolete. The <FileName>psql</FileName> program uses
PQprint() to display query results.
</Para>
</ListItem>
......@@ -588,13 +695,12 @@ void PQprintTuples(PGresult* res,
Prints out all the tuples and, optionally, the
attribute names to the specified output stream.
<ProgramListing>
void PQdisplayTuples(
PGresult* res,
void PQdisplayTuples(PGresult* res,
FILE* fout, /* output stream */
int fillAlign, /* space fill to align columns */
const char *fieldSep, /* field separator */
int printHeader, /* display headers? */
int quiet); /* suppress print of row count at end */
int printHeader, /* display headers? */
int quiet); /* suppress print of row count at end */
</ProgramListing>
PQdisplayTuples() was intended to supersede PQprintTuples(), and
is in turn superseded by PQprint().
......@@ -604,14 +710,36 @@ void PQdisplayTuples(
<Para>
<Function>PQclear</Function>
Frees the storage associated with the PGresult.
Every query result should be properly freed when
it is no longer used. Failure to do this will
result in memory leaks in the frontend application.
Every query result should be freed via PQclear when
it is no longer needed.
<ProgramListing>
void PQclear(PQresult *res);
</ProgramListing>
You can keep a PGresult 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 PQclear. Failure to do this will
result in memory leaks in the frontend application.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQmakeEmptyPGresult</Function>
Constructs an empty PGresult object with the given status.
<ProgramListing>
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
</ProgramListing>
This is libpq's internal routine to allocate and initialize an empty
PGresult object. It is exported because some applications find it
useful to generate result objects (particularly objects with error
status) themselves. If conn is not NULL and status indicates an error,
the connection's current errorMessage is copied into the PGresult.
Note that PQclear should eventually be called on the object, just
as with a PGresult returned by libpq itself.
</Para>
</ListItem>
</ItemizedList>
</Para>
</Sect1>
......@@ -715,11 +843,14 @@ functions:
<Function>PQconsumeInput</Function>
If input is available from the backend, consume it.
<ProgramListing>
void PQconsumeInput(PGconn *conn);
int PQconsumeInput(PGconn *conn);
</ProgramListing>
No direct return value is available from PQconsumeInput, but
after calling it, the application may check PQisBusy and/or
PQnotifies to see if their state has changed.
PQconsumeInput normally returns 1 indicating "no error", but returns
0 if there was some kind of trouble (in which case PQerrorMessage
is set). Note that the result does not say whether any input data
was actually collected. After calling PQconsumeInput,
the application may check PQisBusy and/or PQnotifies to see if their state
has changed.
PQconsumeInput may be called even if the application is not
prepared to deal with a result or notification just yet.
It will read available data and save it in a buffer, thereby
......@@ -841,8 +972,11 @@ PGresult* PQfn(PGconn* conn,
PQArgBlock *args,
int nargs);
</ProgramListing>
The fnid argument is the object identifier of the function to be executed. result_buf is the buffer in which
to load the return value. The caller must have allocated sufficient space to store the return value. The
The fnid argument is the object identifier of the function to be
executed.
result_buf is the buffer in which
to place the return value. The caller must have allocated
sufficient space to store the return value. The
result length will be returned in the storage pointed
to by result_len. If the result is to be an integer
value, than result_is_int should be set to 1; otherwise
......@@ -874,7 +1008,8 @@ typedef struct {
<Para>
<ProductName>Postgres</ProductName> supports asynchronous notification via the
LISTEN and NOTIFY commands. A backend registers its interest in a particular
notification condition with the LISTEN command. All backends listening on a
notification condition with the LISTEN command (and can stop listening
with the UNLISTEN command). All backends listening on a
particular condition will be notified asynchronously when a NOTIFY 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
......@@ -883,9 +1018,9 @@ Commonly the condition name is the same as the associated relation, but it is
not necessary for there to be any associated relation.
<Para>
<FileName>libpq</FileName> applications submit LISTEN commands as ordinary
SQL queries. Subsequently, arrival of NOTIFY messages can be detected by
calling PQnotifies().
<FileName>libpq</FileName> applications submit LISTEN and UNLISTEN
commands as ordinary SQL queries. Subsequently, arrival of NOTIFY
messages can be detected by calling PQnotifies().
<Para>
<ItemizedList>
......@@ -894,22 +1029,23 @@ calling PQnotifies().
<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. PQnotifies behaves like the
popping of a stack. Once a notification is returned from
PQnotifies, it is considered handled and will be removed from the
list of notifications.
there are no pending notifications. Once a notification is
returned from PQnotifies, it is considered handled and will be
removed from the list of notifications.
<ProgramListing>
PGnotify* PQnotifies(PGconn *conn);
</ProgramListing>
After processing a PGnotify object returned by PQnotifies,
be sure to free it with free() to avoid a memory leak.
The second sample program gives an example of the use
of asynchronous notification.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
The second sample program gives an example of the use
of asynchronous notification.
<Para>
PQnotifies() does not actually read backend data; it just returns messages
previously absorbed by another <FileName>libpq</FileName> function. In prior
......@@ -932,10 +1068,10 @@ processing of the query.
<Title>Functions Associated with the COPY Command</Title>
<Para>
The copy command in <ProductName>Postgres</ProductName> has options to read from
The COPY command in <ProductName>Postgres</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 full
advantage of this capability.
Therefore, functions are necessary to access this network
connection directly so applications may take advantage of this capability.
</Para>
<Para>
......@@ -950,7 +1086,13 @@ processing of the query.
<Function>PQgetline</Function>
Reads a newline-terminated line of characters
(transmitted by the backend server) into a buffer
string of size length. Like fgets(3), this routine copies up to length-1 characters into string.
string of size length.
<ProgramListing>
int PQgetline(PGconn *conn,
char *string,
int length)
</ProgramListing>
Like fgets(3), this routine copies up to length-1 characters into string.
It is like gets(3), however, in that it converts
the terminating newline into a null character.
PQgetline returns EOF at EOF, 0 if the entire line
......@@ -958,35 +1100,85 @@ processing of the query.
terminating newline has not yet been read.
Notice that the application must check to see if a
new line consists of the two characters "\.",
which indicates that the backend server has finished sending the results of the copy command.
Therefore, if the application ever expects to
receive lines that are more than length-1 characters long, the application must be sure to check
the return value of PQgetline very carefully.
The code in
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 "\." 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/psql.c
</FileName>
contains routines that correctly handle the copy
protocol.
contains 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.
<ProgramListing>
int PQgetline(PGconn *conn,
char *string,
int length)
int PQgetlineAsync(PGconn *conn,
char *buffer,
int bufsize)
</ProgramListing>
This routine is similar to PQgetline, 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 PGRES_COPY_OUT response, the
application should call PQconsumeInput and PQgetlineAsync until the
end-of-data signal is detected. Unlike PQgetline, this routine takes
responsibility for detecting end-of-data.
On each call, PQgetlineAsync will return data if a complete newline-
terminated data line is available in 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.
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
PQendcopy, 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 '\n' or not.
The returned string is not null-terminated. (If you want to add a
terminating null, be sure to pass a bufsize one smaller than the room
actually available.)
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQputline</Function>
Sends a null-terminated string to the backend
server.
The application must explicitly send the two
characters "\." on a final line to indicate to the backend that it
has finished sending its data.
Sends a null-terminated string to the backend server.
Returns 0 if OK, EOF if unable to send the string.
<ProgramListing>
void PQputline(PGconn *conn,
char *string);
int PQputline(PGconn *conn,
char *string);
</ProgramListing>
Note the application must explicitly send the two
characters "\." 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, EOF if unable to send the string.
<ProgramListing>
int PQputnbytes(PGconn *conn,
const char *buffer,
int nbytes);
</ProgramListing>
This is exactly like PQputline, except that the data buffer need
not be null-terminated since the number of bytes to send is
specified directly.
</Para>
</ListItem>
......@@ -1120,10 +1312,8 @@ any creation of a new PGconn object.
<Title>User Authentication Functions</Title>
<Para>
If the user has generated the appropriate authentication credentials
(e.g., obtaining <Acronym>Kerberos</Acronym> tickets),
the frontend/backend authentication process is handled
by <Function>PQexec</Function> without any further intervention.
The frontend/backend authentication process is handled
by <Function>PQconnectdb</Function> without any further intervention.
The authentication method is now
determined entirely by the DBA (see pga_hba.conf(5)). The following
routines no longer have any effect and should not be used.
......@@ -1166,6 +1356,131 @@ void fe_setauthsvc(char *name,
</Sect1>
<Sect1>
<Title>Environment Variables</Title>
<Para>
The following environment variables can be used to select default
connection parameter values, which will be used by PQconnectdb or
PQsetdbLogin 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>
<Acronym>PGHOST</Acronym> sets the default server name.
If a non-zero-length string is specified, TCP/IP communication is used.
Without a host name, libpq will connect using a local Unix domain socket.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGPORT</Acronym> sets the default port or local Unix domain socket
file extension for communicating with the <ProductName>Postgres</ProductName>
backend.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGDATABASE</Acronym> sets the default <ProductName>Postgres</ProductName> database name.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGUSER</Acronym>
sets the username used to connect to the database and for authentication.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGPASSWORD</Acronym>
sets the password used if the backend demands password authentication.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGREALM</Acronym> sets the Kerberos realm to use with <ProductName>Postgres</ProductName>,
if it is different from the local realm. If
<Acronym>PGREALM</Acronym> is set, <ProductName>Postgres</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>
<Acronym>PGOPTIONS</Acronym> sets additional runtime options for the <ProductName>Postgres</ProductName> backend.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGTTY</Acronym> 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 Postgres session:
<ItemizedList>
<ListItem>
<Para>
<Acronym>PGDATESTYLE</Acronym>
sets the default style of date/time representation.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGTZ</Acronym>
sets the default time zone.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
The following environment variables can be used to specify default internal
behavior for every Postgres session:
<ItemizedList>
<ListItem>
<Para>
<Acronym>PGGEQO</Acronym>
sets the default mode for the genetic optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGRPLANS</Acronym>
sets the default mode to allow or disable right-sided plans in the optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGCOSTHEAP</Acronym>
sets the default cost for heap searches for the optimizer.
</Para>
</ListItem>
<ListItem>
<Para>
<Acronym>PGCOSTINDEX</Acronym>
sets the default cost for indexed searches for the 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>
<Title>Caveats</Title>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment