Makes a new connection to the database server.
PGconn *PQconnectdb(const char *conninfo)
This routine opens a new database connection using the parameters taken
from the string conninfo. Unlike PQsetdbLogin below,
the parameter set can be extended without changing the function signature,
so use either of this routine or the nonblocking analogues PQconnectStart
and PQconnectPoll 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.
Each parameter setting is in the form keyword = value.
(To write an empty value or a value containing
spaces, surround it with single quotes, e.g.,
keyword = 'a value'.
Single quotes and backslashes within the value must be escaped with a
backslash, e.g., \' or \\.)
Spaces around the equal sign are optional. The currently recognized
parameter keywords are:
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
IP address of host to connect to. This should be in standard
numbers-and-dots form, as used by the BSD functions inet_aton et al. If
a nonzero-length string is specified, TCP/IP communication is used.
Using 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
hostaddr, a host name lookup is forced. If hostaddr is specified without
host, the value for hostaddr gives the remote address; if Kerberos is
used, this causes a reverse name query. If both host and hostaddr are
specified, the value for 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 libpq is passed a host name that is not the name of the
machine at hostaddr.
Without either a host name or host address, libpq will connect using a
local Unix domain socket.
Port number to connect to at the server host,
or socket file name extension for Unix-domain connections.
The database name.
User name to connect as.
Password to be used if the server demands password authentication.
Time space in seconds given to connect routine. Zero or not set means infinite.
Trace/debug options to be sent to the server.
A file or tty for optional debug output from the backend.
Set to 1 to require SSL connection to the backend. Libpq
will then refuse to connect if the server does not support
SSL. Set to 0 (default) to negotiate with server.
If any parameter is unspecified, then the corresponding
environment variable (see Section 1.10)
is checked. If the environment variable is not set either,
then hardwired defaults are used.
The return value is a pointer to an abstract struct
representing the connection to the backend.
Makes a new connection to the database server.
PGconn *PQsetdbLogin(const char *pghost,
const char *pgport,
const char *pgoptions,
const char *pgtty,
const char *dbName,
const char *login,
const char *pwd)
This is the predecessor of PQconnectdb with a fixed number
of parameters but the same functionality.
PQsetdb Makes a new connection to the database server.
PGconn *PQsetdb(char *pghost,
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.
Make a connection to the database server in a nonblocking manner.
PGconn *PQconnectStart(const char *conninfo)
PostgresPollingStatusType PQconnectPoll(PGconn *conn)
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.
The database connection is made using the parameters taken from the string
conninfo, passed to PQconnectStart. This string is in
the same format as described above for PQconnectdb.
Neither PQconnectStart nor PQconnectPoll will block, as long as a number of
restrictions are met:
The hostaddr and host parameters are used appropriately to ensure that
name and reverse name queries are not made. See the documentation of
these parameters under PQconnectdb above for details.
If you call PQtrace, ensure that the stream object into which you trace
will not block.
You ensure for yourself that the socket is in the appropriate state
before calling PQconnectPoll, as described below.
To begin, call conn=PQconnectStart("connection_info_string").
If conn is NULL, then libpq has been unable to allocate a new PGconn
structure. Otherwise, a valid PGconn pointer is returned (though not yet
representing a valid connection to the database). On return from
PQconnectStart, call status=PQstatus(conn). If status equals
CONNECTION_BAD, PQconnectStart has failed.
If PQconnectStart succeeds, the next stage is to poll libpq so that it may
proceed with the connection sequence. Loop thus: Consider a connection
"inactive" by default. If PQconnectPoll last returned PGRES_POLLING_ACTIVE,
consider it "active" instead. If PQconnectPoll(conn) last returned
PGRES_POLLING_READING, perform a select() for reading on PQsocket(conn). If
it last returned PGRES_POLLING_WRITING, perform a select() for writing on
PQsocket(conn). If you have yet to call PQconnectPoll, i.e. after the call
to PQconnectStart, behave as if it last returned PGRES_POLLING_WRITING. If
the select() shows that the socket is ready, consider it "active". If it has
been decided that this connection is "active", call PQconnectPoll(conn)
again. If this call returns PGRES_POLLING_FAILED, the connection procedure
has failed. If this call returns PGRES_POLLING_OK, the connection has been
Note that the use of select() to ensure that the socket is ready is merely
a (likely) example; those with other facilities available, such as a
poll() call, may of course use that instead.
At any time during connection, the status of the connection may be
checked, by calling PQstatus. If this is CONNECTION_BAD, then the
connection procedure has failed; if this is CONNECTION_OK, then the
connection is ready. Either of these states should be equally detectable
from the return value of 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:
Waiting for connection to be made.
Connection OK; waiting to send.
Waiting for a response from the server.
Received authentication; waiting for connection start-up to continue.
Negotiating environment (part of the connection start-up).
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:
feedback = "Connecting...";
feedback = "Connected to server...";
feedback = "Connecting...";
Note that if PQconnectStart returns a non-NULL pointer, you must call
PQfinish when you are finished with it, in order to dispose of
the structure and any associated memory blocks. This must be done even if a
call to PQconnectStart or PQconnectPoll failed.
PQconnectPoll will currently block if
libpq is compiled with USE_SSL
defined. This restriction may be removed in the future.
These functions leave the socket in a nonblocking state as if
PQsetnonblocking had been called.
PQconndefaults Returns the default connection options.
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 */
Returns a connection options array. This may
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.
After processing the options array, free it by passing it to
PQconninfoFree. If this is not done, a small amount of memory
is leaked for each call to PQconndefaults.
In PostgreSQL versions before 7.0, PQconndefaults returned a pointer
to a static array, rather than a dynamically allocated array. That
was not thread-safe, so the behavior has been changed.
Close the connection to the backend. Also frees
memory used by the PGconn object.
void PQfinish(PGconn *conn)
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.
Reset the communication port with the backend.
void PQreset(PGconn *conn)
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.
Reset the communication port with the backend, in a nonblocking manner.
int PQresetStart(PGconn *conn);
PostgresPollingStatusType PQresetPoll(PGconn *conn);
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 PQreset (above) in that they
act in a nonblocking manner. These functions suffer from the same
restrictions as PQconnectStart and PQconnectPoll.
Call PQresetStart. If it returns 0, the reset has failed. If it returns 1,
poll the reset using PQresetPoll in exactly the same way as you would
create the connection using PQconnectPoll.
Returns the database name of the connection.
char *PQdb(const PGconn *conn)
PQdb and the next several functions return the values established
at connection. These values are fixed for the life of the PGconn
Returns the user name of the connection.
char *PQuser(const PGconn *conn)
Returns the password of the connection.
char *PQpass(const PGconn *conn)
Returns the server host name of the connection.
char *PQhost(const PGconn *conn)
Returns the port of the connection.
char *PQport(const PGconn *conn)
Returns the debug tty of the connection.
char *PQtty(const PGconn *conn)
Returns the backend options used in the connection.
char *PQoptions(const PGconn *conn)
Returns the status of the connection.
ConnStatusType PQstatus(const PGconn *conn)
The status can be one of a number of values.
However, only two of these are
seen outside of an asynchronous connection procedure -
CONNECTION_BAD. A good
connection to the database has the status CONNECTION_OK.
A failed connection
attempt is signaled by status
Ordinarily, an OK status will remain so until
PQfinish, but a
communications failure might result in the status changing to
In that case the application
could try to recover by calling PQreset.
See the entry for PQconnectStart and PQconnectPoll with regards
to other status codes
that might be seen.
Returns the error message most recently generated by
an operation on the connection.
char *PQerrorMessage(const PGconn* conn);
Nearly all libpq functions will set
PQerrorMessage if they fail.
Note that by libpq convention, a non-empty
include a trailing newline.
Returns the process ID of the backend server
handling this connection.
int PQbackendPID(const PGconn *conn);
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!
Returns the SSL structure used in the connection, or NULL
if SSL is not in use.
SSL *PQgetssl(const PGconn *conn);
This structure can be used to verify encryption levels, check
server certificate and more. Refer to the SSL documentation
for information about this structure.
You must define USE_SSL in order to get the
prototype for this function. Doing this will also
automatically include ssl.h from OpenSSL.