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 @@ ...@@ -2,15 +2,22 @@
<Title><FileName>libpq</FileName></Title> <Title><FileName>libpq</FileName></Title>
<Para> <Para>
<FileName>libpq</FileName> is the application programming interface to <ProductName>Postgres</ProductName>.
<FileName>libpq</FileName> is a set of library routines which allows <FileName>libpq</FileName> is the C application programmer's interface to
client programs to pass queries to the <ProductName>Postgres</ProductName> backend <ProductName>Postgres</ProductName>. <FileName>libpq</FileName> is a set
server and to receive the results of these queries. of library routines that allow client programs to pass queries to the
This version of the documentation describes the <Acronym>C</Acronym> <ProductName>Postgres</ProductName> backend server and to receive the
interface library. Three short programs are included results of these queries. <FileName>libpq</FileName> is also the
at the end of this section to show how to write programs that use <FileName>libpq</FileName>. underlying engine for several other <ProductName>Postgres</ProductName>
There are several examples of <FileName>libpq</FileName> applications in the application interfaces, including <FileName>libpq++</FileName> (C++),
following directories: <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> <ProgramListing>
../src/test/regress ../src/test/regress
...@@ -19,170 +26,135 @@ ...@@ -19,170 +26,135 @@
</ProgramListing> </ProgramListing>
<Para> <Para>
Frontend programs which use <FileName>libpq</FileName> must include the 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> header file <FileName>libpq-fe.h</FileName> and must link with the
library. <FileName>libpq</FileName> library.
</Para> </Para>
<Sect1> <Sect1>
<Title>Control and Initialization</Title> <Title>Database Connection Functions</Title>
<Para> <Para>
The following environment variables can be used to set The following routines deal with making a connection to
up default environment values to avoid hard-coding a <ProductName>Postgres</ProductName> backend server. The application
database names into an application program: 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> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGHOST</Acronym> sets the default server name. <Function>PQsetdbLogin</Function>
If it is set to a non-zero-length string, it causes TCP/IP Makes a new connection to a backend.
communication to be used, rather than the default local Unix domain sockets. <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> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <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> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGPORT</Acronym> sets the default port or local Unix domain socket <Function>PQconnectdb</Function>
file extension for communicating with the <ProductName>Postgres</ProductName> Makes a new connection to a backend.
backend. <ProgramListing>
</Para> PGconn *PQconnectdb(const char *conninfo)
</ListItem> </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> <ListItem>
<Para> <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> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <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> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGREALM</Acronym> sets the Kerberos realm to use with <ProductName>Postgres</ProductName>, <Acronym>dbname</Acronym> -- database name.
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.
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList>
</Para>
<Para>
The following environment variables can be used to specify user-level default
behavior for every Postgres session:
<ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGDATESTYLE</Acronym> <Acronym>user</Acronym> -- user name for authentication.
sets the default style of date/time representation.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGTZ</Acronym> <Acronym>password</Acronym> --
sets the default time zone. password used if the backend demands password authentication.
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList>
</Para>
<Para>
The following environment variables can be used to specify default internal
behavior for every Postgres session:
<ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGGEQO</Acronym> <Acronym>authtype</Acronym> -- authorization type. (No longer used,
sets the default mode for the genetic optimizer. since the backend now chooses how to authenticate users. libpq still
accepts and ignores this keyword for backward compatibility.)
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGRPLANS</Acronym> <Acronym>options</Acronym> -- trace/debug options to send to backend.
sets the default mode to allow or disable right-sided plans in the optimizer.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Acronym>PGCOSTHEAP</Acronym> <Acronym>tty</Acronym> -- file or tty for optional debug output.
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> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</Para> Like PQsetdbLogin, PQconnectdb uses environment variables or built-in
default values for unspecified options.
<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.
</Para> </Para>
</ListItem> </ListItem>
...@@ -196,7 +168,7 @@ PQconninfoOption *PQconndefaults(void) ...@@ -196,7 +168,7 @@ PQconninfoOption *PQconndefaults(void)
struct PQconninfoOption struct PQconninfoOption
{ {
char *keyword; /* The keyword of the option */ 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 *compiled; /* Fallback compiled in default value */
char *val; /* Options value */ char *val; /* Options value */
char *label; /* Label for field in connect dialog */ char *label; /* Label for field in connect dialog */
...@@ -211,10 +183,59 @@ struct PQconninfoOption ...@@ -211,10 +183,59 @@ struct PQconninfoOption
</ProgramListing> </ProgramListing>
Returns the address of the connection options structure. This may 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> </Para>
</ListItem> </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> <ListItem>
<Para> <Para>
<Function>PQdb</Function> <Function>PQdb</Function>
...@@ -222,25 +243,38 @@ struct PQconninfoOption ...@@ -222,25 +243,38 @@ struct PQconninfoOption
<ProgramListing> <ProgramListing>
char *PQdb(PGconn *conn) char *PQdb(PGconn *conn)
</ProgramListing> </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> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQhost</Function> <Function>PQuser</Function>
Returns the host name of the connection. Returns the user name of the connection.
<ProgramListing> <ProgramListing>
char *PQhost(PGconn *conn) char *PQuser(PGconn *conn)
</ProgramListing> </ProgramListing>
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQoptions</Function> <Function>PQpass</Function>
Returns the pgoptions used in the connection. Returns the password of the connection.
<ProgramListing> <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> </ProgramListing>
</Para> </Para>
</ListItem> </ListItem>
...@@ -248,7 +282,7 @@ char *PQoptions(PGconn *conn) ...@@ -248,7 +282,7 @@ char *PQoptions(PGconn *conn)
<ListItem> <ListItem>
<Para> <Para>
<Function>PQport</Function> <Function>PQport</Function>
Returns the pgport of the connection. Returns the port of the connection.
<ProgramListing> <ProgramListing>
char *PQport(PGconn *conn) char *PQport(PGconn *conn)
</ProgramListing> </ProgramListing>
...@@ -258,7 +292,7 @@ char *PQport(PGconn *conn) ...@@ -258,7 +292,7 @@ char *PQport(PGconn *conn)
<ListItem> <ListItem>
<Para> <Para>
<Function>PQtty</Function> <Function>PQtty</Function>
Returns the pgtty of the connection. Returns the debug tty of the connection.
<ProgramListing> <ProgramListing>
char *PQtty(PGconn *conn) char *PQtty(PGconn *conn)
</ProgramListing> </ProgramListing>
...@@ -267,50 +301,59 @@ char *PQtty(PGconn *conn) ...@@ -267,50 +301,59 @@ char *PQtty(PGconn *conn)
<ListItem> <ListItem>
<Para> <Para>
<Function>PQstatus</Function> <Function>PQoptions</Function>
Returns the status of the connection. Returns the backend options used in the connection.
The status can be CONNECTION_OK or CONNECTION_BAD.
<ProgramListing> <ProgramListing>
ConnStatusType *PQstatus(PGconn *conn) char *PQoptions(PGconn *conn)
</ProgramListing> </ProgramListing>
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQerrorMessage</Function> <Function>PQstatus</Function>
Returns the error message associated with the connection Returns the status of the connection.
The status can be CONNECTION_OK or CONNECTION_BAD.
<ProgramListing> <ProgramListing>
char *PQerrorMessage(PGconn* conn); ConnStatusType *PQstatus(PGconn *conn)
</ProgramListing> </ProgramListing>
</Para> </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>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQfinish</Function> <Function>PQerrorMessage</Function>
Close the connection to the backend. Also frees Returns the error message most recently generated by
memory used by the PGconn structure. The PGconn an operation on the connection.
pointer should not be used after PQfinish has been
called.
<ProgramListing> <ProgramListing>
void PQfinish(PGconn *conn) char *PQerrorMessage(PGconn* conn);
</ProgramListing> </ProgramListing>
</Para> </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>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQreset</Function> <Function>PQbackendPID</Function>
Reset the communication port with the backend. Returns the process ID of the backend server handling this
This function will close the IPC socket connection connection.
to the backend and attempt to reestablish a new
connection to the same postmaster.
<ProgramListing> <ProgramListing>
void PQreset(PGconn *conn) int PQbackendPID(PGconn *conn);
</ProgramListing> </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> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</Para> </Para>
</Sect1> </Sect1>
...@@ -319,29 +362,45 @@ void PQreset(PGconn *conn) ...@@ -319,29 +362,45 @@ void PQreset(PGconn *conn)
<Title>Query Execution Functions</Title> <Title>Query Execution Functions</Title>
<Para> <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> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQexec</Function> <Function>PQexec</Function>
Submit a query to <ProductName>Postgres</ProductName>. Returns a PGresult Submit a query to <ProductName>Postgres</ProductName>
pointer or possibly a NULL pointer. If a NULL is returned, it and wait for the result.
should be treated like a PGRES_FATAL_ERROR result: use
PQerrorMessage to get more information about the error.
<ProgramListing> <ProgramListing>
PGresult *PQexec(PGconn *conn, PGresult *PQexec(PGconn *conn,
const char *query); const char *query);
</ProgramListing> </ProgramListing>
The <Function>PGresult</Function> structure encapsulates the query Returns a PGresult pointer or possibly a NULL pointer.
result returned by the backend. <Function>libpq</Function> programmers A non-NULL pointer will generally be returned except in
should be careful to maintain the PGresult out-of-memory conditions or serious errors such as inability
abstraction. Use the accessor functions described to send the query to the backend.
below to retrieve the results of the query. Avoid If a NULL is returned, it
directly referencing the fields of the PGresult should be treated like a PGRES_FATAL_ERROR result. Use
structure as they are subject to change in the PQerrorMessage to get more information about the error.
future.
</Para> </Para>
</ListItem> </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> <ListItem>
<Para> <Para>
<Function>PQresultStatus</Function> <Function>PQresultStatus</Function>
...@@ -350,21 +409,42 @@ PGresult *PQexec(PGconn *conn, ...@@ -350,21 +409,42 @@ PGresult *PQexec(PGconn *conn,
PGRES_EMPTY_QUERY, PGRES_EMPTY_QUERY,
PGRES_COMMAND_OK, /* the query was a command returning no data */ PGRES_COMMAND_OK, /* the query was a command returning no data */
PGRES_TUPLES_OK, /* the query successfully returned tuples */ PGRES_TUPLES_OK, /* the query successfully returned tuples */
PGRES_COPY_OUT, PGRES_COPY_OUT, /* Copy Out (from server) data transfer started */
PGRES_COPY_IN, PGRES_COPY_IN, /* Copy In (to server) data transfer started */
PGRES_BAD_RESPONSE, /* an unexpected response was received */ PGRES_BAD_RESPONSE, /* an unexpected response was received */
PGRES_NONFATAL_ERROR, PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR PGRES_FATAL_ERROR
</ProgramListing> </ProgramListing>
If the result status is PGRES_TUPLES_OK, then the If the result status is PGRES_TUPLES_OK, then the
following routines can be used to retrieve the routines described below can be used to retrieve the
tuples returned by the query. 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> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQntuples</Function> returns the number of tuples (instances) <Function>PQntuples</Function>
Returns the number of tuples (instances)
in the query result. in the query result.
<ProgramListing> <ProgramListing>
int PQntuples(PGresult *res); int PQntuples(PGresult *res);
...@@ -376,13 +456,26 @@ int PQntuples(PGresult *res); ...@@ -376,13 +456,26 @@ int PQntuples(PGresult *res);
<Para> <Para>
<Function>PQnfields</Function> <Function>PQnfields</Function>
Returns the number of fields Returns the number of fields
(attributes) in the query result. (attributes) in each tuple of the query result.
<ProgramListing> <ProgramListing>
int PQnfields(PGresult *res); int PQnfields(PGresult *res);
</ProgramListing> </ProgramListing>
</Para> </Para>
</ListItem> </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> <ListItem>
<Para> <Para>
<Function>PQfname</Function> <Function>PQfname</Function>
...@@ -405,6 +498,7 @@ int PQfnumber(PGresult *res, ...@@ -405,6 +498,7 @@ int PQfnumber(PGresult *res,
char* field_name); char* field_name);
</ProgramListing> </ProgramListing>
</Para> </Para>
-1 is returned if the given name does not match any field.
</ListItem> </ListItem>
<ListItem> <ListItem>
...@@ -424,13 +518,13 @@ Oid PQftype(PGresult *res, ...@@ -424,13 +518,13 @@ Oid PQftype(PGresult *res,
<ListItem> <ListItem>
<Para> <Para>
<Function>PQfsize</Function> <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 associated with the given field index. If the size
returned is -1, the field is a variable length returned is -1, the field is a variable length
field. Field indices start at 0. field. Field indices start at 0.
<ProgramListing> <ProgramListing>
short PQfsize(PGresult *res, int PQfsize(PGresult *res,
int field_index); int field_index);
</ProgramListing> </ProgramListing>
</Para> </Para>
</ListItem> </ListItem>
...@@ -451,24 +545,27 @@ int PQfmod(PGresult *res, ...@@ -451,24 +545,27 @@ int PQfmod(PGresult *res,
<ListItem> <ListItem>
<Para> <Para>
<Function>PQgetvalue</Function> <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 For most queries, the value returned by PQgetvalue
is a null-terminated ASCII string representation is a null-terminated ASCII string representation
of the attribute value. If the query was a result of the attribute value. If the query extracted data from
of a <Acronym>BINARY</Acronym> cursor, then the value returned by a <Acronym>BINARY</Acronym> cursor, then the value returned by
PQgetvalue is the binary representation of the PQgetvalue is the binary representation of the
type in the internal format of the backend server. type in the internal format of the backend server.
It is the programmer's responsibility to cast and 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 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 copy the value into other storage if it is to
be used past the lifetime of the PGresult structure itself. be used past the lifetime of the PGresult structure itself.
<ProgramListing>
char* PQgetvalue(PGresult *res,
int tup_num,
int field_num);
</ProgramListing>
</Para> </Para>
</ListItem> </ListItem>
...@@ -476,37 +573,45 @@ char* PQgetvalue(PGresult *res, ...@@ -476,37 +573,45 @@ char* PQgetvalue(PGresult *res,
<Para> <Para>
<Function>PQgetisnull</Function> <Function>PQgetisnull</Function>
Tests a field for a NULL entry. Tests a field for a NULL entry.
Tuple and field indices start at 0.
<ProgramListing> <ProgramListing>
int PQgetisnull(PGresult *res, int PQgetisnull(PGresult *res,
int tup_num, int tup_num,
int field_num); int field_num);
</ProgramListing> </ProgramListing>
This function returns 1 if the field contains a NULL, 0 if 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> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQgetlength</Function> <Function>PQgetlength</Function>
Returns the length of a field Returns the length of a field
(attribute) in bytes. If the field is a struct (attribute) in bytes.
varlena, the length returned here does not include Tuple and field indices start at 0.
the size field of the varlena, i.e., it is 4 bytes
less.
<ProgramListing> <ProgramListing>
int PQgetlength(PGresult *res, int PQgetlength(PGresult *res,
int tup_num, int tup_num,
int field_num); int field_num);
</ProgramListing> </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> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQcmdStatus</Function> <Function>PQcmdStatus</Function>
Returns the command status associated with the Returns the command status string from the SQL command that
last query command. generated the PGresult.
<ProgramListing> <ProgramListing>
char *PQcmdStatus(PGresult *res); char *PQcmdStatus(PGresult *res);
</ProgramListing> </ProgramListing>
...@@ -516,12 +621,13 @@ char *PQcmdStatus(PGresult *res); ...@@ -516,12 +621,13 @@ char *PQcmdStatus(PGresult *res);
<ListItem> <ListItem>
<Para> <Para>
<Function>PQcmdTuples</Function> <Function>PQcmdTuples</Function>
Returns the number of rows affected by the last command. Returns the number of rows affected by the SQL command.
<ProgramListing> <ProgramListing>
const char *PQcmdTuples(PGresult *res); const char *PQcmdTuples(PGresult *res);
</ProgramListing> </ProgramListing>
If the last command was INSERT, UPDATE or DELETE, this returns If the SQL command that generated the
a string containing the number of rows affected. If the last 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. command was anything else, it returns the empty string.
</Para> </Para>
</ListItem> </ListItem>
...@@ -530,7 +636,7 @@ const char *PQcmdTuples(PGresult *res); ...@@ -530,7 +636,7 @@ const char *PQcmdTuples(PGresult *res);
<Para> <Para>
<Function>PQoidStatus</Function> <Function>PQoidStatus</Function>
Returns a string with the object id of the tuple 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. Otherwise, returns an empty string.
<ProgramListing> <ProgramListing>
char* PQoidStatus(PGresult *res); char* PQoidStatus(PGresult *res);
...@@ -562,8 +668,9 @@ struct _PQprintOpt ...@@ -562,8 +668,9 @@ struct _PQprintOpt
char **fieldName; /* null terminated array of replacement field names */ char **fieldName; /* null terminated array of replacement field names */
}; };
</ProgramListing> </ProgramListing>
This funtion is intended to replace PQprintTuples(), which is This function is intended to replace PQprintTuples(), which is
now obsolete. now obsolete. The <FileName>psql</FileName> program uses
PQprint() to display query results.
</Para> </Para>
</ListItem> </ListItem>
...@@ -588,13 +695,12 @@ void PQprintTuples(PGresult* res, ...@@ -588,13 +695,12 @@ void PQprintTuples(PGresult* res,
Prints out all the tuples and, optionally, the Prints out all the tuples and, optionally, the
attribute names to the specified output stream. attribute names to the specified output stream.
<ProgramListing> <ProgramListing>
void PQdisplayTuples( void PQdisplayTuples(PGresult* res,
PGresult* res,
FILE* fout, /* output stream */ FILE* fout, /* output stream */
int fillAlign, /* space fill to align columns */ int fillAlign, /* space fill to align columns */
const char *fieldSep, /* field separator */ const char *fieldSep, /* field separator */
int printHeader, /* display headers? */ int printHeader, /* display headers? */
int quiet); /* suppress print of row count at end */ int quiet); /* suppress print of row count at end */
</ProgramListing> </ProgramListing>
PQdisplayTuples() was intended to supersede PQprintTuples(), and PQdisplayTuples() was intended to supersede PQprintTuples(), and
is in turn superseded by PQprint(). is in turn superseded by PQprint().
...@@ -604,14 +710,36 @@ void PQdisplayTuples( ...@@ -604,14 +710,36 @@ void PQdisplayTuples(
<Para> <Para>
<Function>PQclear</Function> <Function>PQclear</Function>
Frees the storage associated with the PGresult. Frees the storage associated with the PGresult.
Every query result should be properly freed when Every query result should be freed via PQclear when
it is no longer used. Failure to do this will it is no longer needed.
result in memory leaks in the frontend application.
<ProgramListing> <ProgramListing>
void PQclear(PQresult *res); void PQclear(PQresult *res);
</ProgramListing> </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> </Para>
</ListItem> </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> </ItemizedList>
</Para> </Para>
</Sect1> </Sect1>
...@@ -715,11 +843,14 @@ functions: ...@@ -715,11 +843,14 @@ functions:
<Function>PQconsumeInput</Function> <Function>PQconsumeInput</Function>
If input is available from the backend, consume it. If input is available from the backend, consume it.
<ProgramListing> <ProgramListing>
void PQconsumeInput(PGconn *conn); int PQconsumeInput(PGconn *conn);
</ProgramListing> </ProgramListing>
No direct return value is available from PQconsumeInput, but PQconsumeInput normally returns 1 indicating "no error", but returns
after calling it, the application may check PQisBusy and/or 0 if there was some kind of trouble (in which case PQerrorMessage
PQnotifies to see if their state has changed. 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 PQconsumeInput may be called even if the application is not
prepared to deal with a result or notification just yet. prepared to deal with a result or notification just yet.
It will read available data and save it in a buffer, thereby It will read available data and save it in a buffer, thereby
...@@ -841,8 +972,11 @@ PGresult* PQfn(PGconn* conn, ...@@ -841,8 +972,11 @@ PGresult* PQfn(PGconn* conn,
PQArgBlock *args, PQArgBlock *args,
int nargs); int nargs);
</ProgramListing> </ProgramListing>
The fnid argument is the object identifier of the function to be executed. result_buf is the buffer in which The fnid argument is the object identifier of the function to be
to load the return value. The caller must have allocated sufficient space to store the return value. The 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 result length will be returned in the storage pointed
to by result_len. If the result is to be an integer to by result_len. If the result is to be an integer
value, than result_is_int should be set to 1; otherwise value, than result_is_int should be set to 1; otherwise
...@@ -874,7 +1008,8 @@ typedef struct { ...@@ -874,7 +1008,8 @@ typedef struct {
<Para> <Para>
<ProductName>Postgres</ProductName> supports asynchronous notification via the <ProductName>Postgres</ProductName> supports asynchronous notification via the
LISTEN and NOTIFY commands. A backend registers its interest in a particular 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 particular condition will be notified asynchronously when a NOTIFY of that
condition name is executed by any backend. No additional information is condition name is executed by any backend. No additional information is
passed from the notifier to the listener. Thus, typically, any actual data 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 ...@@ -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. not necessary for there to be any associated relation.
<Para> <Para>
<FileName>libpq</FileName> applications submit LISTEN commands as ordinary <FileName>libpq</FileName> applications submit LISTEN and UNLISTEN
SQL queries. Subsequently, arrival of NOTIFY messages can be detected by commands as ordinary SQL queries. Subsequently, arrival of NOTIFY
calling PQnotifies(). messages can be detected by calling PQnotifies().
<Para> <Para>
<ItemizedList> <ItemizedList>
...@@ -894,22 +1029,23 @@ calling PQnotifies(). ...@@ -894,22 +1029,23 @@ calling PQnotifies().
<Function>PQnotifies</Function> <Function>PQnotifies</Function>
Returns the next notification from a list of unhandled Returns the next notification from a list of unhandled
notification messages received from the backend. Returns NULL if notification messages received from the backend. Returns NULL if
there are no pending notifications. PQnotifies behaves like the there are no pending notifications. Once a notification is
popping of a stack. Once a notification is returned from returned from PQnotifies, it is considered handled and will be
PQnotifies, it is considered handled and will be removed from the removed from the list of notifications.
list of notifications.
<ProgramListing> <ProgramListing>
PGnotify* PQnotifies(PGconn *conn); PGnotify* PQnotifies(PGconn *conn);
</ProgramListing> </ProgramListing>
After processing a PGnotify object returned by PQnotifies, After processing a PGnotify object returned by PQnotifies,
be sure to free it with free() to avoid a memory leak. 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> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</Para> </Para>
<Para>
The second sample program gives an example of the use
of asynchronous notification.
<Para> <Para>
PQnotifies() does not actually read backend data; it just returns messages PQnotifies() does not actually read backend data; it just returns messages
previously absorbed by another <FileName>libpq</FileName> function. In prior previously absorbed by another <FileName>libpq</FileName> function. In prior
...@@ -932,10 +1068,10 @@ processing of the query. ...@@ -932,10 +1068,10 @@ processing of the query.
<Title>Functions Associated with the COPY Command</Title> <Title>Functions Associated with the COPY Command</Title>
<Para> <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>. 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 Therefore, functions are necessary to access this network
advantage of this capability. connection directly so applications may take advantage of this capability.
</Para> </Para>
<Para> <Para>
...@@ -950,7 +1086,13 @@ processing of the query. ...@@ -950,7 +1086,13 @@ processing of the query.
<Function>PQgetline</Function> <Function>PQgetline</Function>
Reads a newline-terminated line of characters Reads a newline-terminated line of characters
(transmitted by the backend server) into a buffer (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 It is like gets(3), however, in that it converts
the terminating newline into a null character. the terminating newline into a null character.
PQgetline returns EOF at EOF, 0 if the entire line PQgetline returns EOF at EOF, 0 if the entire line
...@@ -958,35 +1100,85 @@ processing of the query. ...@@ -958,35 +1100,85 @@ processing of the query.
terminating newline has not yet been read. terminating newline has not yet been read.
Notice that the application must check to see if a Notice that the application must check to see if a
new line consists of the two characters "\.", new line consists of the two characters "\.",
which indicates that the backend server has finished sending the results of the copy command. which indicates that the backend server has finished sending
Therefore, if the application ever expects to the results of the copy command.
receive lines that are more than length-1 characters long, the application must be sure to check If the application might
the return value of PQgetline very carefully. receive lines that are more than length-1 characters long,
The code in 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> <FileName>
../src/bin/psql/psql.c ../src/bin/psql/psql.c
</FileName> </FileName>
contains routines that correctly handle the copy contains routines that correctly handle the copy protocol.
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> <ProgramListing>
int PQgetline(PGconn *conn, int PQgetlineAsync(PGconn *conn,
char *string, char *buffer,
int length) int bufsize)
</ProgramListing> </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> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
<Function>PQputline</Function> <Function>PQputline</Function>
Sends a null-terminated string to the backend Sends a null-terminated string to the backend server.
server. Returns 0 if OK, EOF if unable to send the string.
The application must explicitly send the two
characters "\." on a final line to indicate to the backend that it
has finished sending its data.
<ProgramListing> <ProgramListing>
void PQputline(PGconn *conn, int PQputline(PGconn *conn,
char *string); char *string);
</ProgramListing> </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> </Para>
</ListItem> </ListItem>
...@@ -1120,10 +1312,8 @@ any creation of a new PGconn object. ...@@ -1120,10 +1312,8 @@ any creation of a new PGconn object.
<Title>User Authentication Functions</Title> <Title>User Authentication Functions</Title>
<Para> <Para>
If the user has generated the appropriate authentication credentials The frontend/backend authentication process is handled
(e.g., obtaining <Acronym>Kerberos</Acronym> tickets), by <Function>PQconnectdb</Function> without any further intervention.
the frontend/backend authentication process is handled
by <Function>PQexec</Function> without any further intervention.
The authentication method is now The authentication method is now
determined entirely by the DBA (see pga_hba.conf(5)). The following determined entirely by the DBA (see pga_hba.conf(5)). The following
routines no longer have any effect and should not be used. routines no longer have any effect and should not be used.
...@@ -1166,6 +1356,131 @@ void fe_setauthsvc(char *name, ...@@ -1166,6 +1356,131 @@ void fe_setauthsvc(char *name,
</Sect1> </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> <Sect1>
<Title>Caveats</Title> <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